Filtering

Basic Filtering

List queries in TakeShape provide powerful filtering and sorting features: 

query 

query ($terms: String $sort: TSSearchSort){
  getPostList(terms: $terms sort: [$sort]) {
    items {
      _id
      title
      bodyHtml
    }
    total
  }
}

variables 

{
  "terms": "Lewis",
  "sort": {
    "field": "_updatedAt",
    "order": "desc"
  }
}

In this query we search for posts with that match "Lewis"  in any of their text fields sorted by updated date in descending order. 

Advanced Filtering

For more advanced filtering we can use the where parameter. The where input allows you to construct complex filters on the values of your fields by using the boolean operators AND, OR, and NOT. There is an implicit AND condition applied to all adjacent keys. Using a where input will override the onlyEnabled default filter.

query 

query jobs($where: TSWhereJobInput!) {
  getJobList(where: $where) {
    items {
      title
      company {
        name
      }
    }
  }
}

variables 

{
  "where": {
    "title": {
      "match": "engineer"
    }
  }
}

Fields

Each content type will have its fields available to filter against, in addition to three special operator fields:

  1. AND takes an array of conditions that must appear in the matching results. Nested boolean operators can be used to create complex filters.
  2. OR takes an array of conditions that should appear in the matching results. Nested boolean operators can be used to create complex filters.
  3. NOT takes a single condition that must not appear in the matching results.
{
  "where": {
    "OR": [
      {
        "title": {
          "match": "engineer"
        }
      },
      {
        "NOT": {
          "hotJob": {
            "eq": true
          }
        }
      }
    ]
  }
}

Comparison Operators

Filters are applied to fields using comparison operators:

  • eq - Exact match
  • in - An array of possible exact match values
  • gt - Greater than
  • gte - Greater than or equal
  • lt - Less than
  • lte - Less than or equal
  • match - Full text search with fuzzy string matching
  • regexp - Regular expression string matching. There are some limitations - see the regular expression section below for more details.
{
  "where": {
    "title": {
      "in": ["Front-End Developer", "Engineering Manager"]
    },
    "_createdAt": {
      "gte": "now-1w"
    }
  }
}

The available operators are determined by the field type. For example, boolean fields only provide the eq operator.

Filtering by type

Filters are available for common types like String, Int, Number, and Bool. They're also available for more complex types.

Relationship filters

Relationships can be used in list queries like any other nested object. In the example below, company is a relationship field on the Job content type:

{
  "where": {
    "company": {
      "name": {
        "match": "atoms"
      }
    }
  }
}

Nested relationships are not supported. For example, if the Company content type also had a relationship field, that would not be available within the Job list query.

Keep in mind that including multiple relationship filters may degrade the performance of your query.

In some cases, content types may have fields with conflicting names because of a relationship with another content type that has an identical field name. This is mostly an issue when searching across multiple content types. A common example is when two types each have an image field, but one is a file or asset, and the other is a url. In these cases, the field name will be prefixed with the content type name, like the example below. To avoid confusion, it is best to give fields a unique name.

{
  "where": {
    "book_image": {
      "filename": {
        "match": "my-file"
      }
    },
    "post_image": {
      "regexp": ".*.png"
    }
  }
}

Date filters

TakeShape queries support date ranges and date math expressions. The expression starts with an "anchor" date, which can be either now or a date string (in yyyy-mm-dd ISO 8601 format) ending with ||. It can be followed by a math expression, supporting +- and / (rounding). The units supported are

  • y (year)
  • M (month)
  • w (week)
  • d (day)
  • h (hour)
  • m (minute)
  • s (second)
// simple range
{
  "where": {
    "_createdAt": {
      "gt": "2020-01-01",
      "lt": "2020-06-01"
    }
  }
}

// returns content created within the last week
{
  "where": {
    "_createdAt": {
      "gt": "now-1w"
    }
  }
}

Workflow filters

If Workflows are enabled, the _status field can be used to compare the status of a content item within a Workflow. Since workflow steps have a specified order, the status field can be treated as a range. In the example below, if the workflow had steps "draft", "edit", "legal", and "published", the query would return items in either the "edit" or "legal" steps.

{
  "where": {
    "_status": {
      "gt": "draft",
      "lt": "published"
    }
  }
}

Regular Expressions

TakeShape queries support all Unicode characters. However, the following characters are reserved as operators:

. ? + * | { } [ ] ( ) " \ # @ & < >  ~

To use one of these characters literally, escape it with a preceding backslash or surround it with double quotes. For example:

\@                  # renders as a literal '@'
\\                  # renders as a literal '\'
"john@smith.com"    # renders as 'john@smith.com'

Examples

Here is an example Job list query with a where clause provided as a GraphQL variable, and below are sample filters that could be applied to this query.

query jobs($where: TSWhereJobInput!) {
  getJobList(where: $where) {
    items {
      title
      company {
        name
      }
      bodyHtml
      hotJob
      _createdAt
    }
  }
}

Simple filter

The simplest filter would be to have one or more fields adjacent to one another. This will apply the implicit AND condition to return "hot" jobs whose title contains "engineer".

{
  "where": {
    "title": {
      "match": "engineer"
    },
    "hotJob": {
      "eq": true
    }
  }
}

OR filter

Now we can make this an OR condition. Note how each field is contained within its own object.

{
  "where": {
    "OR": [
      {
    	"title": {
          "match": "engineer"
        }    
      },
      {
    	"hotJob": {
          "eq": true
        }    
      }
    ]
  }
}

Nested filters

Boolean operators can be nested to create complex filters. While specifying the AND operator here isn't entirely necessary, it improves the readability of the filter, especially when there are multiple conditions.

{
  "where": {
    "OR": [
      {
        "AND": [
          {
            "title": {
              "match": "front"
            }
          },
          {
            "company": {
              "name": {
                "match": "atoms"
              }
            }
          }
        ]
      },
      {
        "NOT": {
          "hotJob": {
            "eq": true
          }
        }
      }
    ]
  }
}

Join us

Interested in joining the team as coworker or investor?

contact@takeshape.com