Skip to main content

Article Search Filters

By default, the research and search/recommendation agents use all articles in a dataset to find information relevant for answering questions. This search can be restricted by specifying article filters in the articleFilters field of ResearchRequest and RecommendRequest, respectively. Article filters are constraints applied to the metadata fields indexed with the articles. If the metadata fields satisfy the constraints, the article is eligible for information retrieval; otherwise, it is ignored.

  • It is only possible to filter by fields that were actually indexed, and these fields must be configured for each API key before the articles are sent to the Indexing API.
  • There is one exception: the filters may always contain the special articleId key to enable filtering by article IDs, for example: "articleId": "(\\"1\\" OR \\"2\\" OR \\"3\\" OR \\"4\\")"

The articleFilters field in the API request is a map where keys are the names of the indexed article or paragraph metadata fields and values are constraints for the indexed field values in a Solr-like format.

Constraint types:

  • Primitive value constraint The constraint value must not start and end with brackets ( \[, {, ( ) and their closing counterparts ( ), }, \] ). Such a value is interpreted as a primitive type value (e.g., a string foo or a number 1), and an exact match of the indexed field’s value is required. All characters are interpreted literally, so you should not use escaping.
  • Date-range query The constraint value is a date range such as: \[2025-01-01T00:00:00Z TO NOW\] The indexed field’s value must be a date that falls within the range.
  • Negated query (values that must not match) Example: (-"europe")
  • Query with logical OR Example: ("Donald Tusk" OR "Donald Trump" OR "Donald Duck")
  • Complex query Example: (Donald AND \-"Trump" AND ("Walt Disney \\(company\\)" OR Hollywood))

Examples of constraints for various article metadata fields:

# requires publishDate filed to be after 2025-01-01 midnight UTC
"publishDate": "[2025-01-01T00:00:00Z TO NOW]"
 
# selects articles with "Donald Trump" entity
"entities": "Donald Trump"
 
# selects articles without "Donald Trump" entity
"entities": "(-\"Donald Trump\")" 
 
# articles from "europe" but not "sport" sections
"sections": "(\"europe\" AND -\"sport\")"

Indexed fields types​

In general, constraint values are assumed to be valid Solr filters and must be applicable to the type of the constrained field in the Solr index. For example, a date-range filter should only be used on date fields. A mismatch between constraints and the fields that they are applied to may result in API errors or unexpected behavior. Refer to the Solr documentation for more details.

Character escaping​

Characters such as +, -, " and : have special meaning in constraint values and must be escaped when used literally.

Multiple filters​

When filters for several indexed fields are specified, they must all be satisfied at the same time for an article to be selected. All field constraints are implicitly joined by the logical AND operator.