Querying Collections for Data Objects

Preview

This feature is subject to the "Pre-GA Offerings Terms" in the General Service Terms section of theService Specific Terms. Pre-GA features are available "as is" and might have limited support. For more information, see thelaunch stage descriptions.

The purpose of the Query API is to retrieve Data Objects from a Collectionusing a filter. This is similar to querying a database table and using a SQLWHERE clause. You can also use aggregation to get a count of Data Objectsmatching a filter.

Filter expression language

In addition to KNN/ANN search functionality, Vector Search 2.0 providesversatile query capabilities using a custom query language. The query languageis explained in the following table.

FilterDescriptionSupported TypesExample
$eqMatches Data Objects with field values that areequal to a specified value.Number, string, boolean{"genre": {"$eq": "documentary"}}
$neMatches Data Objects with field values that arenot equal to a specified value.Number, string, boolean{"genre": {"$ne": "drama"}}
$gtMatches Data Objects with field values that aregreater than a specified value.Number{"year": {"$gt": 2019}}
$gteMatches Data Objects with field values that aregreater than or equal to a specified value.Number{"year": {"$gte": 2020}}
$ltMatches Data Objects with field values that areless than a specified value.Number{"year": {"$lt": 2020}}
$lteMatches Data Objects with field values that areless than or equal to a specified value.Number{"year": {"$lte": 2020}}
$inMatches Data Objects with field values that arein a specified array.String{"genre": {"$in": ["comedy", "documentary"]}}
$ninMatches Data Objects with field values that arenot in a specified array.String{"genre": {"$nin": ["comedy", "documentary"]}}
$andJoins query clauses with a logicalAND.-{"$and": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$orJoins query clauses with a logicalOR.-{"$or": [{"genre": {"$eq": "drama"}}, {"year": {"$gte": 2020}}]}
$allSelects the documents where the array value of a field contains all specified values.-{"colors": {"$all": ["red", "blue"]}}
Note: Filter expressions cannot be nested deeper than two levels.

Querying Collections

The following example demonstrates how to use a filter to query for Data Objectsin the Collectionmovies.

#QueryDataObjectscurl -X POST \'https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/movies/dataObjects:query' \  -H 'Bearer $(gcloud auth print-access-token)' \  -H 'Content-Type: application/json' \  -d '{ \    "page_size": 10, \    "page_token": "", \    "filter": { \      "$or": [ \        { \          "director": { \            "$eq": "Akira Kurosawa" \          } \        }, \        { \          "$and": [ \            { \              "director": { \                "$eq": "David Fincher" \              } \            }, \            { \              "genre": { \                "$ne": "Thriller" \              } \            } \          ] \        } \      ] \    }, \    "output_fields": { \      "data_fields": "*", \      "vector_fields": "*", \      "metadata_fields": "*" \    } \  }'

The following example demonstrates how to count all Data Objects in theCollectionmovies.

curl -X POST \  'https://vectorsearch.googleapis.com/v1beta/projects/PROJECT_ID/locations/LOCATION/collections/movies/dataObjects:query' \  -H 'Bearer $(gcloud auth print-access-token)' \  -H 'Content-Type: application/json' \  -d '{ \    "aggregate": "count" \  }'

What's next?

Except as otherwise noted, the content of this page is licensed under theCreative Commons Attribution 4.0 License, and code samples are licensed under theApache 2.0 License. For details, see theGoogle Developers Site Policies. Java is a registered trademark of Oracle and/or its affiliates.

Last updated 2025-12-17 UTC.