Google Cloud Vector Search Client Library

Warnings

• breaking The library is currently in version 0.x (pre-1.0 GA release). This means the API is not yet stable and breaking changes may occur without major version increments. Always refer to release notes for updates.
  Fix: Monitor GitHub releases and official documentation for breaking changes. Pin your dependency to a specific 0.x version and test thoroughly before upgrading.
• gotcha Authentication is required. Ensure your environment is correctly authenticated to Google Cloud (e.g., via `gcloud auth application-default login` or by setting the `GOOGLE_APPLICATION_CREDENTIALS` environment variable).
  Fix: Follow Google Cloud's standard authentication guides for Python client libraries. For local development, `gcloud auth application-default login` is often sufficient.
• gotcha Correct resource path formatting is critical. Google Cloud resources are identified by specific paths (e.g., `projects/PROJECT_ID/locations/LOCATION/indexEndpoints/INDEX_ENDPOINT_ID`). Misformed paths will result in `NotFound` or `InvalidArgument` errors.
  Fix: Always use the client library's path helpers (e.g., `client.index_endpoint_path()`) to construct resource names to ensure correct formatting.
• gotcha A Vector Search index must be *deployed* to an `IndexEndpoint` to be queryable. Creating an index or an endpoint alone is not enough; an index must be explicitly deployed to the endpoint.
  Fix: Verify in the Google Cloud Console (Vertex AI > Vector Search > Index Endpoints) that your chosen index is actively deployed to the specified `IndexEndpoint`.
• gotcha The dimension of your query vectors MUST exactly match the dimension of the vectors in your deployed index. A mismatch will result in an `InvalidArgument` error.
  Fix: Ensure your embedding model produces vectors of the same dimension as your index configuration. Adjust the `query_vector` in examples accordingly.

Install

• pip install google-cloud-vectorsearch Install latest version

Imports

• VectorSearchServiceClient

  from google.cloud import vectorsearch
  client = vectorsearch.VectorSearchServiceClient()

  While the underlying API is `v1beta`, the idiomatic import for the client library simplifies to `google.cloud.vectorsearch`.

Quickstart

This quickstart demonstrates how to instantiate the `VectorSearchServiceClient` and perform a basic vector similarity search (`match`). It assumes you have an existing Vector Search index endpoint with a deployed index. Remember to set the environment variables or replace the placeholder strings for `project_id`, `location`, `index_endpoint_id`, and `deployed_index_id`.

import os
from google.cloud import vectorsearch

# Set your GCP Project ID and Location
project_id = os.environ.get("GCP_PROJECT_ID", "your-gcp-project-id")
location = os.environ.get("GCP_REGION", "us-central1") # e.g., 'us-central1'

# Set your Vector Search Index Endpoint ID and Deployed Index ID
# These must point to an existing, deployed index endpoint in your project.
index_endpoint_id = os.environ.get("VECTORSEARCH_INDEX_ENDPOINT_ID", "your-index-endpoint-id")
deployed_index_id = os.environ.get("VECTORSEARCH_DEPLOYED_INDEX_ID", "your-deployed-index-id")

# Initialize the client
try:
    client = vectorsearch.VectorSearchServiceClient()
    index_endpoint_name = client.index_endpoint_path(
        project=project_id, location=location, index_endpoint=index_endpoint_id
    )

    # Define a query vector (replace with your actual embedding)
    # The dimension must match the index's dimension. Example for 1536 dimensions:
    query_vector = [0.1] * 1536 # Placeholder: adjust dimensions as needed
    num_neighbors = 5

    # Perform a vector search (match)
    print(f"Searching for {num_neighbors} neighbors in index endpoint: {index_endpoint_name}...")
    response = client.match(
        index_endpoint=index_endpoint_name,
        deployed_index_id=deployed_index_id,
        queries=[
            vectorsearch.MatchQuery(
                vector=query_vector,
                # Optional: Add filters if your index supports them
                # restrict_filters=[vectorsearch.RestrictFilter(namespace="color", allow_tokens=["red"])],
                # numeric_filters=[vectorsearch.NumericFilter(value_int=vectorsearch.IntFilter(value=10), field_name="price")],
            )
        ],
        # Optional: Set to True to retrieve full datapoint metadata
        # return_full_datapoint=True
    )

    if response.results:
        print(f"Found {len(response.results[0].matches)} matches for the first query:")
        for match in response.results[0].matches:
            print(f"  ID: {match.id}, Distance: {match.distance:.4f}")
            if match.datapoint:
                print(f"    Datapoint ID: {match.datapoint.datapoint_id}")
                # Access other datapoint fields like match.datapoint.metadata, match.datapoint.restricts, etc.
    else:
        print("No results found. Check your query, index, and endpoint configuration.")

except Exception as e:
    print(f"An error occurred: {e}")
    print("Please ensure you have authenticated to GCP (e.g., `gcloud auth application-default login`),")
    print("your project, location, index endpoint, and deployed index IDs are correct, and the index is deployed.")