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:

Operator	Description
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"
    }
  }
}

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
          }
        }
      }
    ]
  }
}