Filtering

The where filtering allows specifying more complex conditions with the use of AND and OR operators, combined with operations like equal (eq), one of, and range. It's available under the where option. The where filtering is a new and more flexible solution compared to the older filter option. Whenever possible, we recommend using where filtering where is available for its advanced capabilities and flexibility. Read more in the Filter vs Where Filtering section.

info

The where filtering is available on the following types:

Attribute
Product
Promotion

General approach

Currently only AND and OR operators are available. (See the example for AND and OR operator usage).
Each provided value is treated explicitly, which means that filtering by null value for a non-nullable field will result in returning empty list. (See the examples).
You can filter by flat fields and specify operators, but you cannot mix these two approaches. (See the example).
When only flat fields are provided, the conditions are mixed with the AND operator. (See the example).
At each level, you can specify only one operator. (See the example).
In the new where approach, each field of a given type has a corresponding filter option. As a result, the search filter is now located at the top level. (See the example).
The filter input type corresponds to the property name in the API type.
The string, enum, date, and all numeric type fields have specific input types with available operations options. Currently, there is an option to filter by specific value (example) and list of values (example).
You can only specify one operation. Using eq or oneOf is acceptable, but using both will result in an error. (See the example).
You cannot provide both filter and where options at the same time. (See the example).

Examples

To use new filters you need to specify the where option. The following examples will be presented on the attributes query.

Filtering by a specific value

To filter by a specific value, use the eq operation. Only object with the exact match will be returned.

Example: Return attributes that have Flavor name.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
        name
        inputType
      }
    }
  }
}

Query variables:

{
  "where": { "type": { "eq": "Flavor" } }
}

Filtering by a list of values

To filter by a list of values use the oneOf operator. All objects that have a matching value specified in the list are returned.

Example: Return attributes that input type is DATE, or DATE_TIME.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
        name
        inputType
      }
    }
  }
}

Query variables:

{
  "where": { "inputType": { "oneOf": ["DATE", "DATE_TIME"] }
}

Filtering with the `AND` operator

The AND operator allows for defining a list of conditions that must be met.

Example: Return attributes that have Author name, and slug "tom" or "james".

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "AND": [
      { "name": { "eq": "Author" } },
      { "slug": { "oneOf": ["tom", "james"] } }
    ]
  }
}

Filtering with the `OR` operator

The OR operator allows you to define a list of conditions, of which at least one must be fulfilled.

Example: Return attributes that have Author name, or input type DATE or DATE_TIME.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "OR": [
      { "name": { "eq": "Author" } }
      { "inputType": { "oneOf": ["DATE", "DATE_TIME"] } }
    ]
  }
}

Filtering with flat fields

If no operator is given, the provided conditions are combined with an AND operator.

Example: Return attributes that have Author name, and slug "tom" or "james".

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": { "name": { "eq": "Author" }, "slug": { "oneOf": ["tom", "james"] } }
}

note

Note that this is equivalent to the example with the AND operator.

Nested conditions

The operators can be nested, but it's not allowed to combine operators at the same level.

Example: Return attributes that are PRODUCT_TYPE type, and the id is QXR0cmlidXRlOjIx or QXR0cmlidXRlOjI3, or the attribute name is Size.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
        name
      }
    }
  }
}

Query variables:

{
  "where": {
    "AND": [
      { "type": { "eq": "PRODUCT_TYPE" } }
      {
        "OR": [
          { "ids": ["QXR0cmlidXRlOjIx", "QXR0cmlidXRlOjI3"] }
          { "name": { "eq": "Size" } }
        ]
      }
    ]
  }
}

Filtering by empty values

Each provided value in filters is treated explicitly.

Providing an empty list for a list input field will result in returning an empty list.

Example: Filtering products by empty list of ids.

Query:

query getProducts($where: ProductWhereInput) {
  products(where: $where, first: 10) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "ids": []
  }
}

Result:

{
  "data": {
    "products": {
      "edges": []
    }
  }
}

Providing the `null` value for a non-nullable field will result in returning an empty list.

Example: Filtering products by null value for name field.

query getProducts($where: ProductWhereInput) {
  products(where: $where, first: 10) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "name": { "eq": null }
  }
}

Result:

{
  "data": {
    "products": {
      "edges": []
    }
  }
}

Providing an empty value for a nullable field will return the instances with empty value

Example: Filtering attributes whose unit is null.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        unit
        id
        name
      }
    }
  }
}

Query variables:

{
  "where": {
    "unit": { "eq": null }
  }
}

Result:

{
  "data": {
    "attributes": {
      "edges": [
        {
          "node": {
            "unit": null,
            "id": "QXR0cmlidXRlOjQx",
            "name": "EBook Format"
          }
        },
        {
          "node": {
            "unit": null,
            "id": "QXR0cmlidXRlOjQw",
            "name": "Flavor"
          }
        },
        {
          "node": {
            "unit": null,
            "id": "QXR0cmlidXRlOjM2",
            "name": "Material"
          }
        }
      ]
    }
  }
}

Search filtering

To use the full-text search capabilities, use the root-level search argument.

Example: Search attributes by size value

query {
  attributes(first: 20, search: "size") {
    edges {
      node {
        id
        name
      }
    }
  }
}

Invalid examples

Mixing flat field filter and operator `AND`, `OR`

Example: Return attributes that name is Author and type is PRODUCT-TYPE.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "type": { "eq": "PRODUCT_TYPE}" },
    "AND": [{ "name": { "eq": "Author" } }]
  }
}

INSTEAD: Join both conditions into one AND filter input

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "AND": [
      { "name": { "eq": "Author" } },
      { "type": { "eq": "PRODUCT_TYPE" } }
    ]
  }
}

Mixing operators on the same level

Example: Return attributes that have DROPDOWN input type, and the slug is blue or green, or the attribute name is Size.

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
        name
      }
    }
  }
}

Query variables:

{
  "where": {
    "AND": [{ "inputType": { "eq": "DROPDOWN" } }]
    "OR": [{ "slug": { "oneOf": ["blue", "green"] } }, { "name": { "eq": "Size" } }]
  }
}

INSTEAD: Nest OR condition inside AND

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
        name
      }
    }
  }
}

Query variables:

{
  "where": {
      "AND": [
        { "inputType": { "eq": "DROPDOWN" } }
        {
          "OR": [{ "slug": { "oneOf": ["blue", "green"] } }, { "name": { "eq": "Size" } }]
        }
      ]
    }
}

Mixing `filter` and `where` options

query getAttributes(
  $where: AttributeWhereInput
  $filter: AttributeFilterInput
) {
  attributes(first: 20, where: $where, filter: $filter) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": { "AND": [{ "name": { "eq": "Author" } }] },
  "filter": { "type": "PRODUCT_TYPE" }
}

INSTEAD: Use filter or where

Mixing different operations

query getAttributes($where: AttributeWhereInput) {
  attributes(first: 20, where: $where) {
    edges {
      node {
        id
      }
    }
  }
}

Query variables:

{
  "where": {
    "AND": [{ "name": { "eq": "Author", "oneOf": ["Author", "Juice"] } }]
  }
}

INSTEAD: Use the eq or oneOf operation.

`Filter` vs `Where` Filtering

The where filtering is a new and more flexible solution compared to the older filter option. While both approaches allow filtering data, there are key differences and recommendations for their usage:

filter:
- The older filtering mechanism.
- Limited in flexibility and does not support complex conditions like AND/OR operators or nested conditions.
- Still available for backward compatibility and in areas where where filtering is not yet implemented.
where:
- The recommended and more powerful filtering mechanism.
- Supports advanced filtering capabilities such as:
  - Combining conditions with AND and OR operators.
  - Filtering by specific values (eq) or lists of values (oneOf).
  - Nested conditions for more complex queries.
- Provides a more consistent and structured approach to filtering.

note

You cannot use both filter and where options in the same query. If both are provided, an error will be raised. (See the example).

General approach​

Examples​

Filtering by a specific value​

Filtering by a list of values​

Filtering with the AND operator​

Filtering with the OR operator​

Filtering with flat fields​

Nested conditions​

Filtering by empty values​

Providing an empty list for a list input field will result in returning an empty list.​

Providing the null value for a non-nullable field will result in returning an empty list.​

Providing an empty value for a nullable field will return the instances with empty value​

Search filtering​

Invalid examples​

Mixing flat field filter and operator AND, OR​

Mixing operators on the same level​

Mixing filter and where options​

Mixing different operations​

Filter vs Where Filtering​

General approach

Examples

Filtering by a specific value

Filtering by a list of values

Filtering with the `AND` operator

Filtering with the `OR` operator

Filtering with flat fields

Nested conditions

Filtering by empty values

Providing an empty list for a list input field will result in returning an empty list.

Providing the `null` value for a non-nullable field will result in returning an empty list.

Providing an empty value for a nullable field will return the instances with empty value

Search filtering

Invalid examples

Mixing flat field filter and operator `AND`, `OR`

Mixing operators on the same level

Mixing `filter` and `where` options

Mixing different operations

`Filter` vs `Where` Filtering