{"id":2960,"library":"google-cloud-vectorsearch","title":"Google Cloud Vector Search Client Library","description":"The `google-cloud-vectorsearch` Python client library provides access to Google Cloud's Vector Search service (part of Vertex AI), enabling users to store, manage, and query large-scale vector embeddings for similarity search. As of version 0.9.0, it is in a pre-GA state, with frequent updates released as part of the broader `google-cloud-python` monorepo.","status":"active","version":"0.9.0","language":"en","source_language":"en","source_url":"https://github.com/googleapis/google-cloud-python/tree/main/packages/google-cloud-vectorsearch","tags":["google cloud","vertex ai","vector search","embeddings","similarity search","ai platform"],"install":[{"cmd":"pip install google-cloud-vectorsearch","lang":"bash","label":"Install latest version"}],"dependencies":[],"imports":[{"note":"While the underlying API is `v1beta`, the idiomatic import for the client library simplifies to `google.cloud.vectorsearch`.","wrong":"from google.cloud.vectorsearch_v1beta import VectorSearchServiceClient","symbol":"VectorSearchServiceClient","correct":"from google.cloud import vectorsearch\nclient = vectorsearch.VectorSearchServiceClient()"}],"quickstart":{"code":"import os\nfrom google.cloud import vectorsearch\n\n# Set your GCP Project ID and Location\nproject_id = os.environ.get(\"GCP_PROJECT_ID\", \"your-gcp-project-id\")\nlocation = os.environ.get(\"GCP_REGION\", \"us-central1\") # e.g., 'us-central1'\n\n# Set your Vector Search Index Endpoint ID and Deployed Index ID\n# These must point to an existing, deployed index endpoint in your project.\nindex_endpoint_id = os.environ.get(\"VECTORSEARCH_INDEX_ENDPOINT_ID\", \"your-index-endpoint-id\")\ndeployed_index_id = os.environ.get(\"VECTORSEARCH_DEPLOYED_INDEX_ID\", \"your-deployed-index-id\")\n\n# Initialize the client\ntry:\n    client = vectorsearch.VectorSearchServiceClient()\n    index_endpoint_name = client.index_endpoint_path(\n        project=project_id, location=location, index_endpoint=index_endpoint_id\n    )\n\n    # Define a query vector (replace with your actual embedding)\n    # The dimension must match the index's dimension. Example for 1536 dimensions:\n    query_vector = [0.1] * 1536 # Placeholder: adjust dimensions as needed\n    num_neighbors = 5\n\n    # Perform a vector search (match)\n    print(f\"Searching for {num_neighbors} neighbors in index endpoint: {index_endpoint_name}...\")\n    response = client.match(\n        index_endpoint=index_endpoint_name,\n        deployed_index_id=deployed_index_id,\n        queries=[\n            vectorsearch.MatchQuery(\n                vector=query_vector,\n                # Optional: Add filters if your index supports them\n                # restrict_filters=[vectorsearch.RestrictFilter(namespace=\"color\", allow_tokens=[\"red\"])],\n                # numeric_filters=[vectorsearch.NumericFilter(value_int=vectorsearch.IntFilter(value=10), field_name=\"price\")],\n            )\n        ],\n        # Optional: Set to True to retrieve full datapoint metadata\n        # return_full_datapoint=True\n    )\n\n    if response.results:\n        print(f\"Found {len(response.results[0].matches)} matches for the first query:\")\n        for match in response.results[0].matches:\n            print(f\"  ID: {match.id}, Distance: {match.distance:.4f}\")\n            if match.datapoint:\n                print(f\"    Datapoint ID: {match.datapoint.datapoint_id}\")\n                # Access other datapoint fields like match.datapoint.metadata, match.datapoint.restricts, etc.\n    else:\n        print(\"No results found. Check your query, index, and endpoint configuration.\")\n\nexcept Exception as e:\n    print(f\"An error occurred: {e}\")\n    print(\"Please ensure you have authenticated to GCP (e.g., `gcloud auth application-default login`),\")\n    print(\"your project, location, index endpoint, and deployed index IDs are correct, and the index is deployed.\")\n","lang":"python","description":"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`."},"warnings":[{"fix":"Monitor GitHub releases and official documentation for breaking changes. Pin your dependency to a specific 0.x version and test thoroughly before upgrading.","message":"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.","severity":"breaking","affected_versions":"<1.0.0"},{"fix":"Follow Google Cloud's standard authentication guides for Python client libraries. For local development, `gcloud auth application-default login` is often sufficient.","message":"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).","severity":"gotcha","affected_versions":"All"},{"fix":"Always use the client library's path helpers (e.g., `client.index_endpoint_path()`) to construct resource names to ensure correct formatting.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Verify in the Google Cloud Console (Vertex AI > Vector Search > Index Endpoints) that your chosen index is actively deployed to the specified `IndexEndpoint`.","message":"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.","severity":"gotcha","affected_versions":"All"},{"fix":"Ensure your embedding model produces vectors of the same dimension as your index configuration. Adjust the `query_vector` in examples accordingly.","message":"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.","severity":"gotcha","affected_versions":"All"}],"env_vars":null,"last_verified":"2026-04-11T00:00:00.000Z","next_check":"2026-07-10T00:00:00.000Z"}