Filtering Results
Filters are a powerful tool to narrow down your search results. We support filters that are generalized to every document, as well as filters that are specific to different datasources.
This guide will focus on our general filters and how to utilize them.
How to Use
In order to filter search results to show documents that match certain fields via the /search REST API, you need to construct a list of facetFilter objects and pass it into the requestOptions object.
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 | can take on the values below: |
Basic Example
To filter to only the document type pdf search results, you would send the following in the facetFilter field. This is the equivalent of adding “type:pdf” to your search query.
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 |
my | Filter by documents that are in the current user’s history. Supports special value “history” |
collection | Filter by collection name |
has | Filter by whether a document has a specific field. Supports special value “golink” to filter by documents with a golink |
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:
Open date range example for filtering to documents from dates 6/11 onwards:
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,today for the relation type LT.
We allow the values yesterday for the relation type GT.
If you pass in an invalid special value, you will get an 422 error letting you know you have an invalid operator. Invalid special values for time filters are the only case in which a 422 error is returned.
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
before:past_week becomes
after:yesterday becomes
Timezone considerations
We factor in user’s timezone for all queries except when you use the value past_week, past_year, past_month and past_day with the relationType EQUALS. (these are handled by built-in elastic date aggregation that doesn’t account for timezone).
History filter
my: facet will only ever have the value “history”. It filters to show only documents the user has viewed before. The object always looks like this:
From filter (or any user filter):
If you would like to specify a specific user, for example, if there are 2 people with the same name, “User one”, you can specify which one you mean by using the email address they authenticated with Glean as the value . IE user@glean.com and userone@glean.com would facet by different “User One”s even if they have the same name.
Sample query:
Was this page helpful?