<!-- Generated by scripts/generate-llms.mjs from docs/connectors/turbopuffer.md. Do not edit. -->

Source: https://qbash.com/docs/connectors/turbopuffer

Turbopuffer is a search database for vector, full-text and hybrid queries. The connector calls the native [Turbopuffer API](https://turbopuffer.com/docs/api-overview) 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](https://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

| Method | What it does | Type |
| --- | --- | --- |
| `list_namespaces` | Lists namespaces, with a prefix filter and paging | Read |
| `get_namespace_metadata` | Reads a namespace's schema, size and index status | Read |
| `get_namespace_schema` | Reads a namespace's attribute schema | Read |
| `query_vectors` | Finds the nearest rows to a vector | Read |
| `query_full_text` | Ranks rows by BM25 full-text relevance | Read |
| `query_hybrid` | Combines vector and BM25 results with reciprocal rank fusion | Read |
| `query_with_filters` | Runs filtered and ordered queries, aggregations and group-by, including regex filters | Read |
| `upsert_rows` | Creates rows or replaces existing rows by id | Safe write |
| `conditional_upsert_rows` | Upserts only where the stored row meets a condition | Safe write |
| `patch_rows` | Updates only the listed attributes of existing rows | Safe write |

Methods are in the [SDK Reference](https://qbash.com/docs/sdk).

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

A query looks like this:

```python
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.
