{"id":2820,"library":"turbopuffer","title":"Turbopuffer Python Client","description":"The official Python client library for the Turbopuffer API, a serverless vector database designed for fast, low-cost vector search. It enables programmatic interaction with Turbopuffer services, including creating and managing namespaces, upserting vectors, and performing queries. The library is actively maintained with frequent releases, typically multiple minor versions per month.","status":"active","version":"1.21.0","language":"en","source_language":"en","source_url":"https://github.com/turbopuffer/turbopuffer-python","tags":["vector database","api client","embeddings","AI","vector search"],"install":[{"cmd":"pip install turbopuffer","lang":"bash","label":"Install Turbopuffer"}],"dependencies":[],"imports":[{"symbol":"turbopuffer","correct":"import turbopuffer as tp"}],"quickstart":{"code":"import turbopuffer as tp\nimport os\n\n# Ensure your API key is set as an environment variable (TURBOPUFFER_API_KEY)\napi_key = os.environ.get('TURBOPUFFER_API_KEY', 'YOUR_API_KEY')\n\nif not api_key or api_key == 'YOUR_API_KEY':\n    print(\"Warning: TURBOPUFFER_API_KEY environment variable not set. Using dummy key.\")\n\ntp.init(api_key=api_key)\n\nnamespace_name = \"my_first_namespace\"\n# Creating a namespace (idempotent operation)\n# You might get a 409 Conflict if it already exists, which is fine.\n# The library's methods generally handle existing resources gracefully.\n# For example, create_namespace will return the existing namespace if it already exists\n# instead of raising an error.\n\ntry:\n    namespace = tp.VectorDatabase.create_namespace(namespace_name)\n    print(f\"Namespace '{namespace_name}' created or retrieved successfully.\")\nexcept tp.APIStatusError as e:\n    if e.status_code == 409:\n        print(f\"Namespace '{namespace_name}' already exists. Retrieving it.\")\n        namespace = tp.VectorDatabase.get_namespace(namespace_name)\n    else:\n        raise\n\n# Upserting data\nvectors = [[0.1, 0.2, 0.3], [0.4, 0.5, 0.6]]\nids = [1, 2]\nmetadata = [{'text': 'hello'}, {'text': 'world'}]\n\nnamespace.upsert(ids=ids, vectors=vectors, metadata=metadata)\nprint(\"Vectors upserted.\")\n\n# Querying data\nquery_vector = [0.11, 0.22, 0.33]\nresults = namespace.query(vector=query_vector, top_k=1)\nprint(f\"Query results: {results.vectors[0]} with metadata {results.metadata[0]}.\")\n","lang":"python","description":"This quickstart initializes the Turbopuffer client, creates or retrieves a namespace, upserts sample vectors with metadata, and then performs a simple query. Ensure the `TURBOPUFFER_API_KEY` environment variable is set for authentication."},"warnings":[{"fix":"Remove the `queries` parameter from `recall()` method calls. If you need to perform queries, use the `query()` method instead.","message":"The `recall` endpoint in the `VectorDatabase` interface no longer accepts the `queries` parameter. Calls using this parameter will fail.","severity":"breaking","affected_versions":">=1.17.0"},{"fix":"Set `TURBOPUFFER_API_KEY` as an environment variable (e.g., `export TURBOPUFFER_API_KEY=\"your_key\"`) before running your application. The `tp.init()` call will automatically pick it up, or you can pass it explicitly via `tp.init(api_key=os.environ.get('TURBOPUFFER_API_KEY'))`.","message":"API key management is crucial. The client primarily authenticates via the `TURBOPUFFER_API_KEY` environment variable. Directly embedding API keys in code is discouraged.","severity":"gotcha","affected_versions":"All versions"},{"fix":"Validate your input data before calling `upsert`. For example, vectors should be `List[List[float]]`, IDs `List[int]`, and metadata `List[Dict[str, Any]]`.","message":"Ensure the data types and shapes for `ids`, `vectors`, and `metadata` in `upsert` operations match the expected format (lists of integers, lists of floats, and lists of dictionaries, respectively). Mismatched types can lead to errors or unexpected behavior.","severity":"gotcha","affected_versions":"All versions"}],"env_vars":null,"last_verified":"2026-04-10T00:00:00.000Z","next_check":"2026-07-09T00:00:00.000Z"}