GraphQL Filters

Filters are used in the recordsConnection query to specify criteria for specific records to be returned. They consist of a series of one or more conditions with a logical operator of "and" or "or." Filters can contain condition groups: nested conditions that take place of each condition in a filter. The primary example shown below of a request body and filter contains a condition group to illustrate the use of this grouping, but it is not necessary to use in your filter. The easiest way to create a filter is to go to the platform UI and create a filter, and then copy that filter criteria to use in your query. Note that reference subfield filters cannot be constructed this way and are only available in the API, so please refer to the documentation below for them. More about each filter type, including the reference subfield filters, is shown below this section.

Follow these steps to copy the filter from your UI: To go to the UI, open up the platform, go into a workspace table, and click the filter button here.

Once you have created a filter in the UI, you can copy the filter from the browser console and use it in a graphQL request inside the variables for that request. Here is an example of a browser console log showing the filter: And here is an example of a graphQL query body consistent with the example request shown in GraphQL API to filter a set of records. Note that it includes the filter along with any other variables pertinent to the query. It also includes a condition group to illustrate how this is used:

body: JSON.stringify({
    query: `
      query ExampleQuery($tableId: ID!, $filter: JSON) {
        recordsConnection(tableId: $tableId, filter: $filter) {
          edges {
            node {
              id
              fields {
                  fieldId 
                  value 
                  stringValue
                  }
            }
          }
        }
      }
    `,
    variables: {
      "tableId": "wksZbcuvFwooPY2JSbRD|tblDAfBe745NNcTHswrQ",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "contains"
          },
          "right": {
            "type": "input",
            "value": "uy"
          }
        },
        {
          "conditionGroup": [
            {
              "left": {
                "type": "field",
                "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
              },
              "comparison": {
                "operator": "contains"
              },
              "right": {
                "type": "input",
                "value": "a"
              }
            },
            {
              "left": {
                "type": "field",
                "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
              },
              "comparison": {
                "operator": "contains"
              },
              "right": {
                "type": "input",
                "value": "mp"
              }
            }
          ],
          "logicalOperator": "or"
        }
      ],
      "logicalOperator": "or"
    }
    
    }
  })

Examples of Filters for Each Type

Single-line Text Filter

The single-line text filter can be created in the console log as explained above. It supports the of "contains," "does-not-contain," "is," "is-not," "starts-with," "ends-with," "is-empty," "has-any-value" operators. A sample is given here for a "contains" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "contains"
          },
          "right": {
            "type": "input",
            "value": "asdf"
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Number Filter

The number filter can be created in the console log as explained above. It supports "is," "is-not," "is-more-than," "is-less-than," "is-empty," "has-any-value". A sample is given here for a "is-more-than" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Gn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3fx"
          },
          "comparison": {
            "operator": "is-more-than"
          },
          "right": {
            "type": "input",
            "value": 3000
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Currency Filter

The currency filter can be created in the console log as explained above. Similar to the number filter, it supports "is," "is-not," "is-more-than," "is-less-than," "is-empty," "has-any-value". Unlike the number filter, the currency is included in the right object. Without matching the currency, the row will not be returned for this filter. A sample is given here for a "is-more-than" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Gn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3fx"
          },
          "comparison": {
            "operator": "is-more-than"
          },
          "right": {
            "type": "input",
            "value": 3000
            "currency": "USD"
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Dropdown Filter

The dropdown filter can be created in the console log as explained above. It supports the of "has-any-of," "is", 'has-none-of", "is-empty," "has-any-value" operators. A sample is given here for a "has-any-of" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "has-any-of"
          },
          "right": {
            "type": "input",
            "value": ['Lincoln']
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Dropdown Multiple Filter

The dropdown multiple filter can be created in the console log as explained above. It supports the of "has-any-of," "has-all-of," "is", 'has-none-of", "is-empty," "has-any-value" operators. A sample is given here for a "has-any-of" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "has-any-of"
          },
          "right": {
            "type": "input",
            "value": ['Lincoln', 'Omaha']
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Reference Multiple Filter

The reference multiple filter can be created in the console log as explained above. Similar to dropdown multiple it supports the of "has-any-of," "has-all-of," "is", 'has-none-of", "is-empty," "has-any-value" operators. The values specified are the recordID. A sample is given here for a "has-any-of" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "has-any-of"
          },
          "right": {
            "type": "input",
            "value": ['wksARcgrLaJkqc2zvzKA|recDRQYYXT6FLAiatC7x', 'wksARcgrLaJkqc2zvzKA|recFYinCfj79cmsJHaCN']
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Single Reference Filter

The reference filter can be created in the console log as explained above. It supports "is," "is-not," "is-empty," "has-any-value". The value specified is the recordID. A sample is given here for an "is" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "is"
          },
          "right": {
            "type": "input",
            "value": "wksARcgrLaJkqc2zvzKA|recDRQYYXT6FLAiatC7x"
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Reference Subfield Filters

Reference subfield filters allow you to set a filter on a reference field in the current table that includes a filter for the referenced row (usually in another table). It uses the dot notation for fields to separate the reference field ID and the ID of the field in the referenced table. The field in the other table is filtered according to its type and operators available for that field. These filters are *only* available in the API, and not in the platform UI. They cannot contain more than one dot and so therefore cannot follow a reference of a reference. A sample is given here for a contains filter on a single-line text subfield:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldRLwBvjeqHZTEJXASe.wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3ft"
          },
          "comparison": {
            "operator": "contains"
          },
          "right": {
            "type": "input",
            "value": "Bo"
          }
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Attachment Filter

The attachment filter can be created in the console log as explained above. It supports the "is-empty" and "has-any-value" operators. A sample is given here for a "is-empty" filter:

{
      "tableId": "wksARcgrLaJkqc2zvzKA|tblnJkpPvq9RaJcgd3Fn",
      "filter": {
      "conditions": [
        {
          "left": {
            "type": "field",
            "value": "wksARcgrLaJkqc2zvzKA|fldDXnDqrwoz2PoPF3fz"
          },
          "comparison": {
            "operator": "is-empty"
          },
          "right": {}
        }
      ],
      "logicalOperator": "and"
    }
    
    }

Formula and Rollup Filters

The formula and rollup filters can be created in the console log as explained above. They support the "contains," "does-not-contain," "is," "is-not," "starts-with," "ends-with," "is-empty," "has-any-value" operators, as well as the "is-more-than," and "is-less-than" operators. For brevity examples are not given, but please refer to the single-line text and number filters for explicit examples.

Other Filter Types

If the type of filter needed isn't listed here, please contruct the filter in the platform UI with the instructions above and use that as an example to build your filter.

Resources

GraphQL Schema Documentation

Click here to view our full GraphQL schema documentation and all query options.

GraphQL Explorer

Click here to access the GraphQL Explorer, a web interface where you can test GraphQL requests against our API straight from your browser!

Pitchly Field Types/Returns

Click here to consult the full list of pitchly field types and sample return values for each type.