Filtering Results

Filters narrow the results of a Client API search request. Some filters apply to every document; others are specific to a datasource.

This guide covers the general filters. To find the filters a datasource supports, see Datasource Filters.

Using the Platform API?

Platform Search uses a different filter model: filters, time_range, and filter discovery through List search filters. For a runnable example, see the Search with discovered filters recipe.

How to Use

To filter results by field, pass a list of facetFilter objects in requestOptions.facetFilters. requestOptions also requires facetBucketSize.

Each facetFilter object has the following relevant fields:

Field Name	Description
fieldName	the name of the field we are filtering by (eg “from” to facet by user, “type” for document type, etc). fieldName should be unique in the list of facetFilter objects.
values	a list of facetFilterValue objects. All values are OR’d between the same field name (we AND between different field names).

A facetFilterValue object has the following relevant fields:

Field Name	Description
value	string value that results are being filtered to.
relationType	One of EQUALS, ID_EQUALS, NOT_EQUALS, LT, or GT. See Time filters for LT and GT.

Basic Example

To return only PDF documents, set requestOptions.facetFilters to the following. This is equivalent to adding type:pdf to the query.

[
  {
    "fieldName": "type",
    "values": [
      {
        "relationType": "EQUALS",
        "value": "pdf"
      }
    ]
  }
]

Universal Field Names

Topbar Facet Field Names

Field Name	Description
last_updated_at	Filter by document last updated at
from	Filter by user who created/modified the document. Supports special value "me" for the current user
suggested	Filter by suggestion: my history for documents in the current user's history (my:history), or the go links value (has:golink). Copy go links and other values from facetResults
collection	Filter by collection name
type	Filter by document type

Entity Field Names

Field Name	Description
businessunit	Filter by business unit
city	Filter by city
country	Filter by country
industry	Filter by industry
location	Filter by location
region	Filter by region
roletype	Filter by role type
startafter	Filter by start date after
startbefore	Filter by start date before
state	Filter by state
title	Filter by title
reportsto	Filter by reporting to

Exceptions to the basic example

Time filters

Time filters are the only exception to the rule. The fieldName is always “last_updated_at”, and we use different relationTypes to specify different time ranges.

We support 2 types of values: specific dates and special values.

Specific dates

Use the “GT” and “LT” relationTypes to specify a date range. The ranges can also be open-ended (only include a GT or an LT). Each date value should be in the form YYYY-MM-DD passed in as a string. Note that when using GT and LT, the values are noninclusive (eg using {relationType=”GT”, value=”2023-06-17”} will include dates from 2023-06-18 and later).

All dates provided will begin with the “start of the day” (12:00 am). Dates will end at the end of the day (11:59:59 pm).

Closed date range example for filtering to documents from dates 6/16, 6/17, 6/18, 6/19:

[
  {
    "fieldName": "last_updated_at",
    "values": [
      {
        "relationType": "GT",
        "value": "2023-06-15"
      },
      {
        "relationType": "LT",
        "value": "2023-06-20"
      }
    ]
  }
]

Open date range example for filtering to documents from dates 6/11 onwards:

[
  {
    "fieldName": "last_updated_at",
    "values": [
      {
        "relationType": "GT",
        "value": "2023-06-10"
      }
    ]
  }
]

Special Values

For special values, we allow the values past_day, past_week, past_month, yesterday, today, past_n_days, past_n_weeks, past_n_months, past_n_years for the relation type EQUALS, where n is a number, ie 5 in past_5_days. For all past* prefixed values, we also support the last* prefix, they mean the same thing (ie last_week is a viable substitute for past_week).

We allow the values past_day, past_week, past_month, yesterday, and today for the relation type LT.

We allow the value yesterday for the relation type GT.

Use only the values listed above.

If you are used to using operators and values in the query string, here are some examples of translations of query string value to REST API value.

Sample:

updated:today becomes

[
  {
    "fieldName": "last_updated_at",
    "values": [{ "relationType": "EQUALS", "value": "today" }]
  }
]

before:past_week becomes

[
  {
    "fieldName": "last_updated_at",
    "values": [{ "relationType": "LT", "value": "past_week" }]
  }
]

after:yesterday becomes

[
  {
    "fieldName": "last_updated_at",
    "values": [{ "relationType": "GT", "value": "yesterday" }]
  }
]

Timezone considerations

Time filters use the user's timezone, except for past_day, past_week, past_month, and past_year with the relation type EQUALS. Those values do not account for timezone.

History filter

The my:history query operator shows only documents the user has viewed. In facetFilters, it is the suggested field with the value my history:

{
  "fieldName": "suggested",
  "values": [{ "relationType": "EQUALS", "value": "my history" }]
}

From filter (or any user filter):

To choose one person when several share a name, use the email address they sign in to Glean with as the value. For example, user@example.com and userone@example.com filter to different people named "User One".

The query from:"User One" updated:today type:document becomes:

[
  {
    "fieldName": "from",
    "values": [{ "relationType": "EQUALS", "value": "userone@example.com" }]
  },
  {
    "fieldName": "last_updated_at",
    "values": [{ "relationType": "EQUALS", "value": "today" }]
  },
  {
    "fieldName": "type",
    "values": [{ "relationType": "EQUALS", "value": "document" }]
  }
]