Searching for Data Objects

The purpose of the Search API is to find Data Objects that are similar to a given query and return a list of ranked results (ranked by similarity). The Search API also supports filtering.

The Search API offers a variety of ways to search for Data Objects: vector search, full text search, and semantic search. Additionally, multiple searches of any type can be combined together to achieve hybrid search.

Vector search

Vector search lets you provide your own query vector. This is the required method for searching embedding fields that don't have an embedding-config. If multiple vector_search fields are provided, results are combined using equal weights.

The following example demonstrates how to perform a vector search on a Collection with the ID COLLECTION_ID.

POST https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search

{
  "vector_search": {
    "search_field": "plot_embedding",
    "vector": {
      "values": [
        0.42426406871192845,
        0.565685424949238,
        0.7071067811865475
      ]
    },
    "filter": {
      "genre": {
        "$eq": "Thriller"
      }
    },
    "top_k": 5,
    "output_fields": {
      "data_fields": "*",
      "vector_fields": "*",
      "metadata_fields": "*"
    }
  }
}

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search"

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://vectorsearch.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects:search" | Select-Object -Expand Content

{
  "results": [
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1",
        "createTime": "2026-01-31T20:05:06Z",
        "updateTime": "2026-02-02T13:59:24Z",
        "data": {
          "year": 1991,
          "title": "The Silence of the Lambs",
          "director": "Jonathan Demme",
          "genre": "Thriller"
        },
        "vectors": {
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.697
    },
    {
      "dataObject": {
        "name": "projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2",
        "createTime": "2026-02-04T14:35:29Z",
        "updateTime": "2026-02-04T14:37:29Z",
        "data": {
          "year": 1995,
          "title": "Se7en",
          "director": "David Fincher",
          "genre": "Thriller"
        },
        "vectors": {
          "genre_embedding": {
            "dense": {
              "values": [
                0.3863801,
                0.73934346,
                0.16189057,
                0.5271367
              ]
            }
          },
          "plot_embedding": {
            "dense": {
              "values": [
                1,
                1,
                1
              ]
            }
          },
          "sparse_embedding": {
            "sparse": {
              "values": [
                1,
                6,
                3,
                2,
                8,
                5,
                2
              ],
              "indices": [
                4065,
                13326,
                17377,
                25918,
                28105,
                32683,
                42998
              ]
            }
          },
          "soundtrack_embedding": {
            "dense": {
              "values": [
                0.5920452,
                0.08301644,
                0.12647335,
                0.619643,
                0.49258286
              ]
            }
          }
        }
      },
      "distance": 1.75
    }
  ]
}

gcloud vector-search collections data-objects search \
  --vector-search-field="plot_embedding" \
  --vector-from-file=SEARCH_VECTOR_FILE \
  --json-filter='{"genre": {"$eq": "Thriller"}}' \
  --top-k=5 \
  --output-data-fields='*' \
  --output-vector-fields='*' \
  --output-metadata-fields='*' \
  --collection=COLLECTION_ID \
  --location=LOCATION \
  --project=PROJECT_ID

gcloud vector-search collections data-objects search `
  --vector-search-field="plot_embedding" `
  --vector-from-file=SEARCH_VECTOR_FILE `
  --json-filter='{"genre": {"$eq": "Thriller"}}' `
  --top-k=5 `
  --output-data-fields='*' `
  --output-vector-fields='*' `
  --output-metadata-fields='*' `
  --collection=COLLECTION_ID `
  --location=LOCATION `
  --project=PROJECT_ID

gcloud vector-search collections data-objects search ^
  --vector-search-field="plot_embedding" ^
  --vector-from-file=SEARCH_VECTOR_FILE ^
  --json-filter='{"genre": {"$eq": "Thriller"}}' ^
  --top-k=5 ^
  --output-data-fields='*' ^
  --output-vector-fields='*' ^
  --output-metadata-fields='*' ^
  --collection=COLLECTION_ID ^
  --location=LOCATION ^
  --project=PROJECT_ID

---
dataObject:
  createTime: '2026-01-31T20:05:06Z'
  data:
    director: Jonathan Demme
    genre: Thriller
    title: The Silence of the Lambs
    year: 1991
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/1
  updateTime: '2026-02-02T13:59:24Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.697
---
dataObject:
  createTime: '2026-02-04T14:35:29Z'
  data:
    director: David Fincher
    genre: Thriller
    title: Se7en
    year: 1995
  name: projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID/dataObjects/2
  updateTime: '2026-02-04T14:37:29Z'
  vectors:
    genre_embedding:
      dense:
        values:
        - 0.38638
        - 0.739343
        - 0.161891
        - 0.527137
    plot_embedding:
      dense:
        values:
        - 1.0
        - 1.0
        - 1.0
    soundtrack_embedding:
      dense:
        values:
        - 0.592045
        - 0.0830164
        - 0.126473
        - 0.619643
        - 0.492583
    sparse_embedding:
      sparse:
        indices:
        - 4065
        - 13326
        - 17377
        - 25918
        - 28105
        - 32683
        - 42998
        values:
        - 1.0
        - 6.0
        - 3.0
        - 2.0
        - 8.0
        - 5.0
        - 2.0
distance: 1.75

from google.cloud import vectorsearch_v1

# Create the client
data_object_search_service_client = vectorsearch_v1.DataObjectSearchServiceClient()

# Initialize request
vector_search = vectorsearch_v1.VectorSearch(
    search_field="plot_embedding",
    vector={"values": [0.1, 0.2, 0.3]},
    filter={"genre": {"$eq": "Thriller"}},
    top_k=5,
)
request = vectorsearch_v1.SearchDataObjectsRequest(
    parent="projects/PROJECT_ID/locations/LOCATION/collections/COLLECTION_ID",
    vector_search=vector_search,
)

# Make the request
response = data_object_search_service_client.search_data_objects(request=request)

# Handle the response
print(response)

Text search

This performs full-text search without sparse vectors. The default "word" query dialect treats the entire input as individual search terms with an implicit AND operator. You can set enhanced_query to true to expand search terms, handle stemming, stop word removal, and allow for additional search operators:

• OR: A case-sensitive disjunction operator that matches documents containing at least one of the specified terms. It only applies to the two adjacent terms.

• ": (double quotes) for phrase search.

• -: The negation operator. It excludes documents containing any terms it is placed before.

Advanced text search

Agent Retrieval text search API lets you express text searches through structured queries containing one or more subqueries, allowing you to:

• Match against specific Data Objects fields.

• Specify the type of match to perform:

  • Per term, case-insensitive

  • Exactly, case-sensitive

• Include per-language enhancements to match on term stems, synonyms, misspellings, and stop words (such as "a", "an", and "the").

• Use AND, OR, and NOT boolean operators to combine subqueries.

• Control evaluation order by grouping subqueries together.

• Boost score contributions to influence rankings.

There are three types of subqueries:

• Text: Provides the search text and one or more fields to match against.

• Unary: Applies a NOT operation on a single subquery.

• Combined: Applies the AND or OR operator to combine subqueries, and can be used to group other combined subqueries to control evaluation order.

The examples on this page use the Collection demonstrated in the following table. It contains six Data Objects and defines the following fields in its data schema: the strings ID, Title, Description, and the string array Keywords.

Text subqueries

Text queries match against one or more fields in a Data Object. All structured queries must contain at least one text query.

The following example defines a basic text query:

"text_search": {
  "structured_query": {
    "text": {
      "text": "fox vs dog"
    }
  }
}

By default, the text is split into individual terms, and each term is searched for in the fields specified. In the preceding example, the terms "fox", "vs", and "dog" are searched for in the Title field.

Text queries have the following optional parameters:

• fields: An array of fields to match against. If not specified, the default is to match against all fields. Fields are matched with an implicit OR operator.

• match_type: The type of match to perform. The match type can be EXACT, which specifies the field must match the search text exactly. If the field is a string array, a match is performed against any element in the array.

• enhancement: Specifies enabled and a languageCode, allowing matches to be performed against synonyms, stems, misspellings, and stop words in the language specified for languageCode (for example, en-US). The default is no enhancement.

• boost: Optional. A multiplier to apply to the score of the query. The default is 1.0.

Match type

The match_type parameter specifies how search text matches a field's value.

The parameter's value can be:

• EXACT: The field must match the query term exactly. If the field is a string array, a match is performed against any element in the array.

The following example specifies the EXACT match type:

"text_search": {
  "structured_query": {
    "text": {
      "text": "Fox vs Dog",
      "fields": [ "Title" ],
      "match_type": "EXACT"
    }
  }
}

Match type for string arrays

The results of the query are shown in the following table:

When the field is a string array, the search text is matched against any array element.

The following example shows how to search for the exact text wild in the Keywords string array:

"text_search": {
  "structured_query": {
    "text": {
      "text": "wild",
      "fields": [ "Keywords" ],
      "match_type": "EXACT"
    }
  }
}

The results of the query are shown in the following table:

Query enhancements

Search queries can include an optional queryEnhancement parameter to specify language-specific enhancements. This includes matching against synonyms, stems (for example, the "jump" stem "jumping"), incorrect spellings, and stop words (such as "a", "an", and "the").

The parameter is an object with the following properties:

• enabled: A boolean that specifies whether to enable enhancements.

• languageCode: A string that specifies the language for the enhancements (for example, en-US).

The following example enables enhancements for the en-US language:

"text_search": {
  "structured_query": {
    "text": {
      "text": {
        "text": "jump",
        "fields": [ "Description" ],
        "queryEnhancement": {
          "enabled": true,
          "languageCode": "en-US"
        }
      }
    }
  }
}

The results of the query are shown in the following table:

If queryEnhancement was not specified or enabled was false, no match would be made.

Combined subqueries

Combined queries apply a boolean operation to two or more subqueries. The supported operations are AND and OR.

Combined queries have the following properties:

• op: The boolean operator to apply to the subqueries. The value can be AND or OR.

• subQueries: An array of subqueries to combine. These can be any of the supported subquery types, including other combined queries. There is a maximum nesting depth of 2.

  • boost: Optional. A multiplier to apply to the score of the query. The default is 1.0.

Conjunction (AND)

The AND operator matches Data Objects that contain the terms of all subqueries.

The following example demonstrates how to combine three text queries using the AND operator:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

In the example, matches are only made if all three subqueries match.

The results of the query are shown in the following table:

When a text subquery has multiple fields to match on, an implicit OR is applied, as shown in the following example:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

In the preceding example:

• The first subquery matches the case-insensitive term Brown in either the Title or Description field.

• The second subquery matches the case-insensitive term quick in the Description field.

• The third subquery matches the case-insensitive terms forest and predator in any of the values in the Keywords string array field.

• If all three subqueries match, a match is made on the combined query.

The results of the query are shown in the following table:

Disjunction (OR)

The OR operator matches Data Objects that contain the terms of at least one of the subqueries.

The following example demonstrates how to combine three text queries using the OR operator:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title", "Description" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        }
      ]
    }
  }
}

In the example, a match is made if any of the three subqueries match.

The results of the query are shown in the following table:

Grouping

Combined subqueries can be nested within other combined subqueries in order to control the evaluation order.

The following example demonstrates how to group subqueries:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "combine": {
            "op": "OR",
            "subQueries": [
              {
                "text": {
                  "text": "Fox",
                  "fields": [ "Title" ]
                }
              },
              {
                "text": {
                  "text": "jumps",
                  "fields": [ "Description" ]
                }
              }
            ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "domestic",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

The preceding example is equivalent to the following: (Case-insensitive Fox in Title OR case-insensitive jumps in Description) AND NOT case-insensitive domestic in any of the Keywords elements.

The following table shows the results of the query:

Unary subqueries

Unary subqueries apply a boolean operation to a single subquery in a structured query. The NOT operator is the only supported unary operation.

Unary queries have the following properties:

• op: The boolean operator to apply to the subquery. The value can be NOT.

• subQuery: The subquery to apply the unary operation to.

  • boost: Optional. A multiplier to apply to the score of the query. The default is 1.0.

Negation (NOT)

The NOT operator matches Data Objects that don't contain the terms of the subquery.

The following example demonstrates how to use the NOT operator:

"text_search": {
  "structured_query": {
    "unary": {
      "op": "NOT",
      "subQuery": {
        "text": {
          "text": "dog",
          "fields": [ "Description" ]
        }
      }
    }
  }
}

The results of the query are shown in the following table:

When applied to a string array, the NOT operator matches a Data Object if the term is not contained in any of the array's elements.

In the example, a match is made if the case-insensitive term orange is not contained in any element of the Keywords string array.

"text_search": {
  "structured_query": {
    "combine": {
      "op": "AND",
      "subQueries": [
        {
          "text": {
            "text": "Brown",
            "fields": [ "Title" ]
          }
        },
        {
          "text": {
            "text": "quick",
            "fields": [ "Description" ]
          }
        },
        {
          "text": {
            "text": "forest predator",
            "fields": [ "Keywords" ]
          }
        },
        {
          "unary": {
            "op": "NOT",
            "subQuery": {
              "text": {
                "text": "orange",
                "fields": [ "Keywords" ]
              }
            }
          }
        }
      ]
    }
  }
}

The results of the query are shown in the following table:

Boosting

Any subquery can have a boost parameter to apply a multiplier to the score of the subquery. By default, all subqueries have a boost of 1.0.

The following example demonstrates how to boost a subquery:

"text_search": {
  "structured_query": {
    "combine": {
      "op": "OR",
      "subQueries": [
        {
          "text": {
            "text": "fox",
            "fields": [ "Title" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "jumps",
            "fields": [ "Description" ]
          },
          "boost": 1.0
        },
        {
          "text": {
            "text": "interaction",
            "fields": [ "Keywords" ]
          },
          "boost": 5.0
        }
      ]
    }
  }
}

The results of the query are shown in the following table:

Semantic search

This search converts your text query into embeddings to find results based on semantic meaning. It uses the embedding-config defined in your schema to generate the query embedding. If multiple vector_search fields are provided, results are combined using equal weights.

Searching using hybrid search

Use batch_search_data_objects to execute multiple searches in parallel (vector search, text search, and semantic search). The results can optionally be combined and ranked using the ReciprocalRankFusion Ranker, which merges result sets using the Reciprocal Rank Fusion (RFF) algorithm.