Skip to main content
Version: 3.x

Filtering

info

The where filtering approach was introduced in Saleor 3.11. For now, it's only available on the:

  • Attribute type (added in Saleor 3.11)
  • Product type (added in Saleor 3.15)
caution

This feature is in the Feature Preview stage, which means that it is available for experimentation and feedback. However, it is still undergoing development and is subject to modifications.

Introduction​

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, for now, only on the attributes query.

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"
          }
        }
      ]
    }
  }
}
Expand â–¼

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.

Was this page helpful?