For AI agents: this page is also available as Markdown at /docs/compat-turbopuffer.md. Every docs page is: add .md to its URL. llms.txt lists them all.

turbopuffer compatibility

This page describes a compatibility layer for the turbopuffer SDKs. WarpSearch's own API under /v1 is the primary way to create collections and define schemas.

WarpSearch serves the turbopuffer HTTP API at https://api.warpsearch.io/compat/turbopuffer. The official turbopuffer SDKs for Python, TypeScript, Go, Java and Ruby work against it by changing configuration only: a base URL and a WarpSearch API key. Requests and responses keep turbopuffer's shapes, including $dist, rows, aggregations and multi-query results.

A turbopuffer namespace is a WarpSearch collection, so the same data can also be searched with the Elasticsearch, OpenSearch, Solr, SQL and MCP interfaces. Features that are not implemented yet fail with 501 and nothing is written, so you never get a silently wrong answer.

#Connect

Create an API key in the management console and use it as the turbopuffer API key. The SDKs send it as Authorization: Bearer ws_live_..., which WarpSearch accepts.

Remove the region. Every SDK refuses to start with region is set, but would be ignored when a region is configured and the base URL has no {region} placeholder. Delete the region argument and unset TURBOPUFFER_REGION.

  from turbopuffer import Turbopuffer

  tpuf = Turbopuffer(
-     region="gcp-us-central1",
-     api_key="tpuf_...",
+     base_url="https://api.warpsearch.io/compat/turbopuffer",
+     api_key="ws_live_...",
  )

import Turbopuffer from '@turbopuffer/turbopuffer';

const tpuf = new Turbopuffer({
  baseURL: 'https://api.warpsearch.io/compat/turbopuffer',
  apiKey: process.env['TURBOPUFFER_API_KEY'], // a ws_live_... key
});

If your code reads its settings from the environment, switching needs no code change at all:

export TURBOPUFFER_BASE_URL=https://api.warpsearch.io/compat/turbopuffer
export TURBOPUFFER_API_KEY=ws_live_...
unset TURBOPUFFER_REGION

Older or community clients that cannot change the URL can usually take a custom HTTP client (an httpx client in Python, a custom fetch in TypeScript, option.WithHTTPClient or option.WithMiddleware in Go) that rewrites the request host. Leave SDK compression at its default. The X-turbopuffer-Client-Telemetry header is accepted and ignored.

#Namespaces and collections

A namespace whose name is a valid WarpSearch collection name (1 to 64 characters, starting with a lowercase letter, only lowercase letters, digits and _, no __) uses that name directly. Any other turbopuffer name, with uppercase letters, - or . and up to 128 characters, is stored under a derived collection name: tp_ followed by 26 lowercase letters and digits. The turbopuffer API keeps using the original name everywhere, in writes, queries and the namespace list. The console shows the derived collection, with the original name in its turbopuffer_namespace metadata.

The first write creates the namespace, as does create_namespace: true. Creating one needs a key with the editor or admin role. Writes need writer, queries need viewer, and deleting a namespace needs admin. See API keys, roles and rate limits. For a derived tp_ name, a key limited to certain collection names must also cover the tp_ name. Plan limits on collections, request sizes, documents per request and rates apply as on every other API; see Limits and errors.

#Endpoints

Coming soon: explain_query, _debug/recall, copy_from_namespace, branch_from_namespace and the async copy operations, and PATCH on namespace metadata (pinning and read_only). They answer 501 today.

#Writes

Supported: upsert_rows, upsert_columns, deletes, distance_metric (cosine_distance or euclidean_squared), schema, create_namespace and return_affected_ids. disable_backpressure and sharding are accepted and ignored.

A write is committed before the response returns, so the next query sees it. Queries accept consistency: {"level": "eventual"} as well. Every upsert replaces the whole document, as in turbopuffer. IDs can be unsigned integers, UUIDs or strings of up to 64 bytes, and come back with the type you wrote.

Coming soon: patch_rows, patch_columns, patch_by_filter, delete_by_filter, upsert_condition, patch_condition, delete_condition, encryption, copy_from_namespace and branch_from_namespace. A request that contains any of them is rejected with 501 and nothing is written, even if it also contains upserts.

501 responses carry x-should-retry: false, so the SDKs raise at once instead of retrying. Errors use the body {"status":"error","error":"<message>"}. Authentication failures (401) and rate limiting (429, with Retry-After) use WarpSearch's standard error body; the SDKs act on the status code either way.

#Schema and types

Types are inferred from the first non-null value written, or declared in schema. An attribute that has only ever been null is not created yet. Supported: string, int, uint (up to 2^63-1), float, uuid, datetime, bool, their array forms ([]string, []int, []uint, []float, []uuid, []datetime, []bool), and dense vectors [N]f32 and [N]f16. f16 vectors are stored at half precision; on the wire they stay float32.

Vectors can be sent as JSON number arrays or as base64 little-endian float32. Set vector_encoding: "base64" on a query to get them back in base64. A column named vector is a vector automatically. Other vector attributes need a schema entry with an [N]f32 type or ann: true. Every vector attribute gets an approximate index, built automatically as the namespace grows.

full_text_search: true, or a configuration object, makes a string attribute searchable with BM25.

On a full-text attribute, Eq matches as a phrase rather than by exact value, unless the attribute also has filterable: true.

Attribute names may use letters, digits, _, . and @, and must start with a letter or _; other names (for example with - or spaces) fail with 400. Attributes created through other WarpSearch APIs, such as the WarpSearch schema API or an Elasticsearch mapping, appear in the turbopuffer schema with the closest type.

Not supported: multi-vector []N f32 with late_interaction, sparse vectors ({}f16 and sparse_knn), bytes, [N]i8, and embed. They fail with 400 or 501.

#Queries

$dist is the vector distance for ANN and kNN (cosine_distance is 1 minus cosine similarity), the BM25 score for full text, and the RRF score after rerank_by. It is absent when you order by attributes. Documents without a value for the order attribute come last in both directions (turbopuffer puts them first when ascending). Null handling follows turbopuffer: Eq null matches documents without the attribute, NotEq null those with it, and Lt and Lte also match documents without it.

Responses have rows, aggregations, aggregation_groups, results for multi-query, billing (byte counts are always zero, since WarpSearch bills by its own plans) and performance (server_total_ms, query_execution_ms; cache fields report hot and 1.0).

Coming soon: the Attribute, Saturate, Decay and Dist rank expressions, SparseKNN, Embed in rank_by, compute_attributes (including Highlight), rerank_by with a model, IGlob and NotIGlob, Glob with [...] classes or {a,b} alternatives, and limit.per with several attributes or more than one row per value. They answer 501.

#Example

from turbopuffer import Turbopuffer

tpuf = Turbopuffer(
    base_url="https://api.warpsearch.io/compat/turbopuffer",
    api_key="ws_live_...",
)
ns = tpuf.namespace("docs")

ns.write(
    upsert_rows=[
        {"id": 1, "vector": [0.1, 0.9, 0.2], "text": "Fast hybrid search", "category": "guide"},
        {"id": 2, "vector": [0.8, 0.1, 0.3], "text": "Billing and plans", "category": "faq"},
    ],
    distance_metric="cosine_distance",
    schema={"text": {"type": "string", "full_text_search": True}},
)

ann = ns.query(
    rank_by=("vector", "ANN", [0.2, 0.8, 0.1]),
    filters=("category", "Eq", "guide"),
    top_k=10,
    include_attributes=["text"],
)
for row in ann.rows:
    print(row.id, row["$dist"], row["text"])

bm25 = ns.query(rank_by=("text", "BM25", "hybrid search"), top_k=10)

hybrid = ns.multi_query(
    queries=[
        {"rank_by": ("vector", "ANN", [0.2, 0.8, 0.1]), "top_k": 20},
        {"rank_by": ("text", "BM25", "hybrid search"), "top_k": 20},
    ],
    rerank_by=("RRF", {"rank_constant": 60}),
    limit=10,
)
print(hybrid.results[0].rows)

The same calls over HTTP:

curl -s -X POST https://api.warpsearch.io/compat/turbopuffer/v2/namespaces/docs \
  -H "Authorization: Bearer ws_live_..." \
  -H "Content-Type: application/json" \
  -d '{"upsert_rows": [{"id": 1, "vector": [0.1, 0.9, 0.2], "text": "Fast hybrid search"}],
       "distance_metric": "cosine_distance",
       "schema": {"text": {"type": "string", "full_text_search": true}}}'

curl -s -X POST https://api.warpsearch.io/compat/turbopuffer/v2/namespaces/docs/query \
  -H "Authorization: Bearer ws_live_..." \
  -H "Content-Type: application/json" \
  -d '{"rank_by": ["text", "BM25", "hybrid"], "top_k": 10, "include_attributes": ["text"]}'

#Differences from turbopuffer

To search the same collection with other interfaces, see Searching, Query languages, Vector search and Hybrid search. For limits and error codes, see Limits and errors.

View this page as Markdown