Skip to main content

Connect Turbopuffer

Turbopuffer is a search database for vector, full-text and hybrid queries. The connector calls the native Turbopuffer API with your own API key, so a Task can list namespaces, run queries and write rows.

Turbopuffer has no free plan and no trial. You need a paid plan before you can create a key. The Launch plan has a $16 per month minimum usage commitment.

Add a credential​

  1. Go to turbopuffer.com/join and create an account.
  2. Pick the Launch plan.
  3. Finish the billing steps. Turbopuffer bills by usage for storage, writes and queries, and the monthly minimum applies even when usage is lower.
  4. In the Turbopuffer dashboard, create an API key. Choose only the permissions that let the key list namespaces, query and write rows, where the dashboard offers them. Avoid admin keys. The Turbopuffer docs say that listing namespaces needs a key with list or admin permission. The full set of permission names is not confirmed here, so follow what your dashboard shows.
  5. Copy the key when it is created. Also note the region of your namespaces, for example gcp-us-central1.
  6. In qbash, open Connectors → Turbopuffer and add a credential. Give it a name, paste the key into API Key and enter the region.
  7. Add Turbopuffer to your Task and select the saved credential.

qbash encrypts the key. Saving checks the key format and the region format only. It does not contact Turbopuffer, so a wrong key or region shows up on the first call.

When editing a credential, leave API Key blank to keep the saved key.

Region​

Turbopuffer runs one API host per region. qbash builds the host from your region setting as https://<region>.turbopuffer.com. Use the region your namespaces live in. A key used against a different region returns an error.

Methods​

MethodWhat it doesType
list_namespacesLists namespaces, with a prefix filter and pagingRead
get_namespace_metadataReads a namespace's schema, size and index statusRead
get_namespace_schemaReads a namespace's attribute schemaRead
query_vectorsFinds the nearest rows to a vectorRead
query_full_textRanks rows by BM25 full-text relevanceRead
query_hybridCombines vector and BM25 results with reciprocal rank fusionRead
query_with_filtersRuns filtered and ordered queries, aggregations and group-by, including regex filtersRead
upsert_rowsCreates rows or replaces existing rows by idSafe write
conditional_upsert_rowsUpserts only where the stored row meets a conditionSafe write
patch_rowsUpdates only the listed attributes of existing rowsSafe write

Methods are in the SDK Reference.

page = qbash.integrations.turbopuffer.list_namespaces(prefix="docs-", page_size=50)
qbash.output(page)

A query looks like this:

result = qbash.integrations.turbopuffer.query_full_text(
namespace="docs",
attribute="content",
query="refund policy",
top_k=5,
include_attributes=["title"],
)
qbash.output(result["rows"])

Details that change results​

  • A first write to a new namespace creates it. Pick a clear name for test namespaces.
  • upsert_rows replaces a row with the same id entirely. Use patch_rows to change a few attributes, or conditional_upsert_rows to skip stale updates.
  • Patches to ids that do not exist are ignored.
  • The schema is part of the namespace metadata. get_namespace_schema returns only that part.
  • Hybrid queries apply the same filters to both the vector and the text search. The fused ranking comes back as a single result, so read the rows from results[0].rows.
  • Each method makes one request. A timeout on a write can leave the outcome unknown, so read the rows back before repeating it.

What the connector leaves out​

The connector cannot delete namespaces, delete rows, delete by filter or branch and copy namespaces. These can remove or overwrite data in bulk. Export, cache warming and recall evaluation are also not included.