Skip to main content

Filter expressions in Momento Vector Index

Filter expressions further refine the results of a search. While the vector similarity search ranks items by vector similarity to the query vector, the filter expression applies an additional where clause on the item metadata or ids. Only items satisfying the expression appear in the results.

They are used in the filter parameter of the search (searchAndFetchVectors) command.

Each language provides a convenience to create filter expressions. The following is the API reference for the filter expressions.

Overview

Here we demo the entire API reference for filter expressions. Broadly we group the expressions into two categories:

For this example we will use a hypothetical dataset of movies (think IMDB) with the following schema:

FieldTypeDescription
movie_titlestringThe title of the movie.
yearintThe year the movie was released.
gross_revenue_millionsfloatThe gross revenue of the movie in millions of dollars.
in_theatersbooleanWhether the movie is currently in theaters.
actorsstring[]The list of actors in the movie.
directorsstring[]The list of directors of the movie.
/*
* For convenience, a filter expression factory can be imported as follows:
* import { VectorFilterExpressions as F } from '@gomomento/sdk';
*/

// Is the movie titled "The Matrix"?
F.equals('movie_title', 'The Matrix');

// Is the movie not titled "The Matrix"?
F.not(F.equals('movie_title', 'The Matrix'));

// Was the movie released in 1999?
F.equals('year', 1999);

// Did the movie gross 463.5 million dollars?
F.equals('gross_revenue_millions', 463.5);

// Was the movie in theaters?
F.equals('in_theaters', true);

// Was the movie released after 1990?
F.greaterThan('year', 1990);

// Was the movie released in or after 2020?
F.greaterThanOrEqual('year', 2020);

// Was the movie released before 2000?
F.lessThan('year', 2000);

// Was the movie released in or before 2000?
F.lessThanOrEqual('year', 2000);

// Was "Keanu Reeves" one of the actors?
F.listContains('actors', 'Keanu Reeves');

// Is the ID one of the following?
F.idInSet(['tt0133093', 'tt0234215', 'tt0242653']);

// Was the movie directed by "Lana Wachowski" and released after 2000?
F.and(F.listContains('directors', 'Lana Wachowski'), F.greaterThan('year', 2000));

// Was the movie directed by "Lana Wachowski" or released after 2000?
F.or(F.listContains('directors', 'Lana Wachowski'), F.greaterThan('year', 2000));

// Was "Keanu Reeves" not one of the actors?
F.not(F.listContains('actors', 'Keanu Reeves'));

Comparison expressions

Comparison expressions directly compare a field's value and a specified value. They are the basic building blocks of filter expressions.

tip

The numeric comparison expressions (greaterThan, greaterThanOrEquals, lessThan, lessThanOrEquals) are only supported for numeric-valued fields. The expression will not be satisfied if the item does not have a value for the field or if the value is not a number.

Equals

Tests if a field's value exactly matches a given value.

NameTypeDescription
fieldstringThe name of the field to be compared.
valuestring | number | booleanThe value to test for exact match against the field's value.
tip

To express not equals, chain the not expression with the equals expression.

Greater than

Tests if a field's value is greater than a specified value.

NameTypeDescription
fieldstringThe name of the field to be compared.
valuenumberThe threshold value to test against.

Greater than or equals

Tests if a field's value is greater than or equals a specified value.

NameTypeDescription
fieldstringThe name of the field to be compared.
valuenumberThe threshold value to test against.

Less than

Tests if a field's value is less than a specified value.

NameTypeDescription
fieldstringThe name of the field to be compared.
valuenumberThe threshold value to test against.

Less than or equals

Tests if a field's value is less than or equals a specified value.

NameTypeDescription
fieldstringThe name of the field to be compared.
valuenumberThe threshold value to test against.

List contains

Tests if a field's list of values includes a specified value.

NameTypeDescription
fieldstringThe name of the field containing a list of values.
valuestringThe value to test for inclusion in the field's list.

Id in set

Tests if an item's id is in a specified set of ids.

NameTypeDescription
idsstring[]The set of ids to test for inclusion.

Logical expressions

Logical expressions combine or modify filter expressions. Instead of directly comparing against item data like comparison expressions, they operate on other filter expressions.

And

Combines two filter expressions and returns items that satisfy both.

NameTypeDescription
firstExpressionVectorFilterExpressionThe first expression to evaluate.
secondExpressionVectorFilterExpressionThe second expression to evaluate.

Or

Combines two filter expressions and returns items that satisfy either one or both.

NameTypeDescription
firstExpressionVectorFilterExpressionThe first expression to evaluate.
secondExpressionVectorFilterExpressionThe second expression to evaluate.

Not

Negates the result of a filter expression.

NameTypeDescription
expressionVectorFilterExpressionThe expression to negate.