Skip to main content

Advanced Query Filtering

For advanced filtering use the where parameter. where allows you to construct complex filters on 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 jobs($where: TSWhereJobInput!) {
getJobList(where: $where) {
items {
title
company {
name
}
}
}
}
{
"where": {
"title": {
"match": "engineer"
}
}
}

Fields#

All shape fields are 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 can be applied using comparison operators:

OperatorDescription
eqExact match
inAn array of possible exact match values
gtGreater than
gteGreater than or equal
ltLess than
lteLess than or equal
matchFull text search with fuzzy string matching
regexpRegular 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"
}
}
}

Not all operators are available on every 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 shapes.

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 shape:

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

Nested relationships are not supported. For example, if the Company shape 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, shapes may have fields with conflicting names because of a relationship with another shape that has an identical field name. This is mostly an issue when searching across multiple shapes. 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 shape 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
}
}
}
]
}
}