{"id":7840,"library":"upstash-vector","title":"Upstash Vector Python SDK","description":"The `upstash-vector` SDK is a lightweight, HTTP-based Upstash Vector client designed for Python. It seamlessly operates in both serverless and serverful environments, ensuring optimal compatibility across various connection setups. This SDK simplifies interaction with Upstash Vector through the Upstash Vector API. It is designed to work with Python versions 3.8 and above.","status":"active","version":"0.8.0","language":"en","source_language":"en","source_url":"https://github.com/upstash/vector-py","tags":["vector database","serverless","embedding","AI","vector search"],"install":[{"cmd":"pip install upstash-vector","lang":"bash","label":"Install via pip"}],"dependencies":[],"imports":[{"symbol":"Index","correct":"from upstash_vector import Index"}],"quickstart":{"code":"import os\nimport random\nfrom upstash_vector import Index\n\n# Initialize the index client using environment variables\n# Ensure UPSTASH_VECTOR_REST_URL and UPSTASH_VECTOR_REST_TOKEN are set\nindex = Index(\n    url=os.environ.get('UPSTASH_VECTOR_REST_URL', 'YOUR_UPSTASH_VECTOR_REST_URL'),\n    token=os.environ.get('UPSTASH_VECTOR_REST_TOKEN', 'YOUR_UPSTASH_VECTOR_REST_TOKEN')\n)\n\ndef main():\n    # Define the dimension based on your index configuration (e.g., 128)\n    dimension = 128 \n\n    # Generate a random vector for upsert\n    vector_to_upsert = [random.random() for _ in range(dimension)]\n    \n    # Additional metadata associated with the vector (optional)\n    metadata = {\"text\": \"example test for metadata\", \"source\": \"quickstart\"}\n    \n    # Upsert the vector into the index\n    response = index.upsert(vectors=[\n        (\"id-for-vector-1\", vector_to_upsert, metadata)\n    ])\n    print(f\"Upsert response: {response}\")\n\n    # Fetch the upserted vector\n    fetched_vectors = index.fetch(ids=[\"id-for-vector-1\"], include_vectors=True, include_metadata=True)\n    if fetched_vectors and fetched_vectors[0]:\n        print(f\"Fetched vector: {fetched_vectors[0].id}, Metadata: {fetched_vectors[0].metadata}\")\n    else:\n        print(\"Vector not found or fetch failed.\")\n\n    # Query for similar vectors\n    query_vector = [random.random() for _ in range(dimension)] # Example query vector\n    query_results = index.query(\n        vector=query_vector,\n        top_k=1,\n        include_vectors=False,\n        include_metadata=True\n    )\n    print(f\"Query results: {query_results}\")\n\nif __name__ == \"__main__\":\n    main()","lang":"python","description":"Initializes the Upstash Vector client, upserts a sample vector with metadata, fetches it, and performs a similarity query. Credentials are loaded from environment variables (preferred) or can be replaced with direct values. Ensure your Upstash Vector index is created with the correct dimension."},"warnings":[{"fix":"Initialize `index = Index.from_env()` or `index = Index(url=..., token=...)` globally or at module level, rather than inside a function that is called on every request.","message":"For optimal performance and connection reuse in serverless environments, it is recommended to initialize the `Index` client outside of request handlers.","severity":"gotcha","affected_versions":"All versions"},{"fix":"To opt out of telemetry, pass `allow_telemetry=False` during client initialization: `Index(url=..., token=..., allow_telemetry=False)` or `Index.from_env(allow_telemetry=False)`.","message":"The SDK sends anonymous telemetry data by default (SDK version, platform, Python runtime version).","severity":"gotcha","affected_versions":"All versions"},{"fix":"Review the official Upstash Vector documentation for the updated usage pattern of `resumable query` and adapt your code accordingly.","message":"The Resumable Query API underwent changes in version `0.6.0`.","severity":"breaking","affected_versions":"v0.6.0 and later (if upgrading from <0.6.0)"},{"fix":"Upgrade to v0.8.0 or later to leverage more efficient `range`, `fetch`, and `delete` operations with `prefix` or `filter` arguments. Review the changelog for specific API changes.","message":"Version `0.8.0` introduced new capabilities for ranging, fetching, and deleting vectors using `id prefix` or `metadata filters`. Previous versions lacked these granular filtering options.","severity":"gotcha","affected_versions":"prior to v0.8.0"}],"env_vars":null,"last_verified":"2026-04-16T00:00:00.000Z","next_check":"2026-07-15T00:00:00.000Z","problems":[{"fix":"Ensure `UPSTASH_VECTOR_REST_URL` and `UPSTASH_VECTOR_REST_TOKEN` are correctly set in your environment. Alternatively, pass the `url` and `token` directly to the `Index` constructor: `Index(url=\"YOUR_URL\", token=\"YOUR_TOKEN\")`.","cause":"The `UPSTASH_VECTOR_REST_URL` environment variable is not set or is misspelled when attempting to initialize `Index.from_env()`.","error":"KeyError: 'UPSTASH_VECTOR_REST_URL'"},{"fix":"Verify your `UPSTASH_VECTOR_REST_TOKEN` in the Upstash Console and ensure it's accurately configured in your environment variables or passed correctly to the `Index` constructor.","cause":"The `UPSTASH_VECTOR_REST_TOKEN` provided is incorrect, expired, or does not have sufficient permissions to access the Upstash Vector index.","error":"upstash_vector.errors.UpstashVectorException: Unauthorized"},{"fix":"Ensure that the vectors you provide for `upsert`, `query`, or `update` operations exactly match the dimension configured for your index in the Upstash Console.","cause":"The vector being upserted (inserted or updated) has a different dimension (number of elements) than what is configured for your Upstash Vector index.","error":"upstash_vector.errors.UpstashVectorException: Vector dimension mismatch. Expected X, got Y."},{"fix":"To retrieve the actual vector values, you must explicitly set `include_vectors=True` in your `fetch` or `range` calls: `index.fetch(ids=['id'], include_vectors=True)`.","cause":"When calling `index.fetch()` or `index.range()`, the `include_vectors` parameter was not explicitly set to `True` (it defaults to `False` or is recommended as `False` for performance if not needed).","error":"AttributeError: 'UpstashVectorFetchResult' object has no attribute 'vector'"}]}