# turbopuffer

> Store and search documents in turbopuffer: vector and full-text search, filtered lookups and counts, upsert, update and delete documents, and manage namespaces.

App · 20 actions. Web page: https://docs.lodol.com/docs/integrations/turbopuffer

## Actions

### Branch namespace

Make an instant copy of a namespace under a new name. The two are independent afterwards. turbopuffer bills a flat fee per branch.

**Inputs**

- Namespace to copy (`source_namespace`, text, required): The namespace to copy. Pick one, or type its name.
- New namespace name (`namespace`, text, required): Up to 128 letters, digits, '-', '_' or '.'. It must not exist yet.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `source_namespace` (text): The namespace it was copied from
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "namespace": "support-articles-test",
  "patched_ids": [],
  "rows_affected": 0,
  "rows_deleted": 0,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 0,
  "source_namespace": "support-articles",
  "upserted_ids": []
}
```

### Count documents

Count the documents that match a filter, in all or for each value of some attributes.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Filter (`filters`, list): Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.
- Count for each (`group_by`, list): Attributes to count separately for each value of.

**Outputs**

- `count` (number): How many match in all
- `group_count` (number): How many groups
- `groups` (list): One count for each group, when counting for each
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "count": 1200,
  "group_count": 2,
  "groups": [
    {
      "count": 1150,
      "group": {
        "status": "published"
      }
    },
    {
      "count": 50,
      "group": {
        "status": "draft"
      }
    }
  ],
  "namespace": "support-articles"
}
```

### Create namespace

Create an empty namespace, with the kind of ids its documents use and, optionally, attributes ready for full-text search. Writing documents to a new name also creates one.

**Inputs**

- New namespace name (`namespace`, text, required): Up to 128 letters, digits, '-', '_' or '.'. It must not exist yet.
- Document IDs are (`id_type`, text): The kind of ids its documents use. Defaults to text. One of: `string` (Text (default)), `uint` (Whole number), `uuid`.
- Full-text search on (`full_text_attributes`, list): Text attributes to make searchable with 'Full-text search'.
- Schema (`schema`, object): Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `schema` (object): The schema sent, by attribute name
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 0,
  "rows_deleted": 0,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 0,
  "schema": {
    "id": {
      "type": "string"
    },
    "title": {
      "full_text_search": true,
      "type": "string"
    }
  },
  "upserted_ids": []
}
```

### Delete documents

Delete documents by their ids. Ids that don't exist are skipped.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Document IDs (`document_ids`, list, required): The ids of the documents to delete.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [
    "article-0042"
  ],
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 1,
  "rows_deleted": 1,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 0,
  "upserted_ids": []
}
```

### Delete documents by filter

Delete every document that matches a filter, up to 5 million at a time.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Filter (`filters`, list, required): Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
- Allow partial (`allow_partial`, true/false): When more documents match than one request may change (5 million to delete, 50,000 to update), change that many and report the rest, instead of failing.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [
    "article-0043"
  ],
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 1,
  "rows_deleted": 1,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 0,
  "upserted_ids": []
}
```

### Delete namespace

Delete a namespace and every document in it. This cannot be undone.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.

**Outputs**

- `deleted` (true/false): True once deleted
- `namespace` (text): The namespace's name
- `status` (text): turbopuffer's status

**Example output**

```json
{
  "deleted": true,
  "namespace": "support-articles",
  "status": "ok"
}
```

### Evaluate recall

Measure how well vector search finds the true nearest documents: turbopuffer compares sample searches with exhaustive ones. Billed as queries.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Sample searches (`num`, number): How many searches to compare, 1 to 100. Defaults to 25. From 1 to 100.
- Results per search (`top_k`, number): How many nearest documents each finds. Defaults to 10. From 1 to 1000.
- Filter (`filters`, list): Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.

**Outputs**

- `avg_ann_count` (number): Average results of the vector searches
- `avg_exhaustive_count` (number): Average results of the exhaustive searches
- `avg_recall` (number): Share of the true nearest found, 0 to 1
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "avg_ann_count": 10.0,
  "avg_exhaustive_count": 10.0,
  "avg_recall": 0.98,
  "namespace": "support-articles"
}
```

### Find documents

Find the documents that match a filter, in order of an attribute, like a database query.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Filter (`filters`, list): Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.
- Order by (`order_by`, text): The attribute to sort by. Defaults to id.
- Order (`direction`, text): Defaults to highest first. One of: `desc` (Highest first (default)), `asc` (Lowest first).
- How many (`limit`, number): How many to return, 1 to 10,000. Defaults to 10. From 1 to 10000.
- Skip (`offset`, number): How many matching documents to skip first. From 0 to 9999.
- Attributes to return (`include_attributes`, list): Return only these attributes. Leave empty to return them all.

**Outputs**

- `count` (number): How many documents were returned
- `documents` (list): The documents found, best first
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "attributes": {
        "status": "published",
        "title": "Resetting your password"
      },
      "id": "article-0042",
      "score": null
    }
  ],
  "namespace": "support-articles"
}
```

### Full-text search

Find the documents whose text best matches some words, ranked by BM25. The attribute must have full-text search turned on.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Attribute (`attribute`, text, required): The text attribute to search, such as body.
- Search words (`query`, text, required): The words to look for.
- How many (`top_k`, number): How many documents to return, 1 to 10,000. Defaults to 10. From 1 to 10000.
- Filter (`filters`, list): Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.
- Attributes to return (`include_attributes`, list): Return only these attributes. Leave empty to return them all.
- Consistency (`consistency`, text): Strong includes every write so far. Defaults to strong. One of: `strong` (Strong: include every write (default)), `eventual` (Eventual: faster, may miss the latest writes).

**Outputs**

- `count` (number): How many documents were returned
- `documents` (list): The documents found, best first
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "attributes": {
        "status": "published",
        "title": "Resetting your password"
      },
      "id": "article-0042",
      "score": 7.25
    }
  ],
  "namespace": "support-articles"
}
```

### Get document

Get one document, with all its attributes, by its id.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Document ID (`document_id`, text, required): The document's id, from a search or an earlier step.

**Outputs**

- `attributes` (object): Every attribute of the document
- `id` (text): The document's id: text, a UUID or a whole number
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "attributes": {
    "status": "published",
    "title": "Resetting your password"
  },
  "id": "article-0042",
  "namespace": "support-articles"
}
```

### Get namespace details

Get a namespace's schema, approximate document count and size, when it was created and last written, and whether its index is up to date.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.

**Outputs**

- `approx_logical_bytes` (number): About how many bytes of data it holds
- `approx_row_count` (number): About how many documents it holds
- `created_at` (text): When it was created (ISO 8601)
- `index_status` (text): up-to-date, or updating while new writes are indexed
- `last_write_at` (text): When its data last changed (ISO 8601)
- `namespace` (text): The namespace's name
- `read_only` (true/false): True when it refuses writes
- `schema` (object): Each attribute's type and indexing, by attribute name
- `unindexed_rows` (number): Documents written but not yet indexed
- `updated_at` (text): When its data or schema last changed (ISO 8601)

**Example output**

```json
{
  "approx_logical_bytes": 4718592,
  "approx_row_count": 1200,
  "created_at": "2026-10-01T09:00:00Z",
  "index_status": "up-to-date",
  "last_write_at": "2026-11-10T16:20:00Z",
  "namespace": "support-articles",
  "read_only": false,
  "schema": {
    "id": {
      "type": "string"
    },
    "title": {
      "full_text_search": true,
      "type": "string"
    }
  },
  "unindexed_rows": 0,
  "updated_at": "2026-11-10T16:20:00Z"
}
```

### List namespaces

List the namespaces in the connection's region, optionally only those whose names start with some text. Gets one page; to see more, run it again with the next page it gives.

**Inputs**

- Name starts with (`prefix`, text): Only namespaces whose names start with this.
- Page size (`page_size`, number): How many to return, 1 to 1,000. Defaults to 100. From 1 to 1000.
- Next page cursor (`cursor`, text): The 'next_cursor' from an earlier page.

**Outputs**

- `count` (number): How many on this page
- `namespaces` (list): The namespaces
- `next_cursor` (text): Cursor for the next page, empty on the last

**Example output**

```json
{
  "count": 2,
  "namespaces": [
    {
      "id": "support-articles"
    },
    {
      "id": "product-docs"
    }
  ],
  "next_cursor": ""
}
```

### Make namespace read-only or writable

Make a namespace refuse document and schema writes, or accept them again. Returns the namespace's details.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- State (`state`, text, required): Read-only refuses writes; writable allows them. One of: `read_only` (Read-only: refuse writes), `writable` (Writable: allow writes).

**Outputs**

- `approx_logical_bytes` (number): About how many bytes of data it holds
- `approx_row_count` (number): About how many documents it holds
- `created_at` (text): When it was created (ISO 8601)
- `index_status` (text): up-to-date, or updating while new writes are indexed
- `last_write_at` (text): When its data last changed (ISO 8601)
- `namespace` (text): The namespace's name
- `read_only` (true/false): True when it refuses writes
- `schema` (object): Each attribute's type and indexing, by attribute name
- `unindexed_rows` (number): Documents written but not yet indexed
- `updated_at` (text): When its data or schema last changed (ISO 8601)

**Example output**

```json
{
  "approx_logical_bytes": 4718592,
  "approx_row_count": 1200,
  "created_at": "2026-10-01T09:00:00Z",
  "index_status": "up-to-date",
  "last_write_at": "2026-11-10T16:20:00Z",
  "namespace": "support-articles",
  "read_only": true,
  "schema": {
    "id": {
      "type": "string"
    },
    "title": {
      "full_text_search": true,
      "type": "string"
    }
  },
  "unindexed_rows": 0,
  "updated_at": "2026-11-10T16:20:00Z"
}
```

### Update document

Change some attributes of an existing document, keeping the rest. Vectors can't be changed this way; upsert the document instead.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Document ID (`document_id`, text, required): The document's id, from a search or an earlier step.
- Attributes to change (`attributes`, object, required): The attributes to set and their new values.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `document_id` (text): The document's id, as sent
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "document_id": "article-0042",
  "namespace": "support-articles",
  "patched_ids": [
    "article-0042"
  ],
  "rows_affected": 1,
  "rows_deleted": 0,
  "rows_patched": 1,
  "rows_remaining": false,
  "rows_upserted": 0,
  "upserted_ids": []
}
```

### Update documents by filter

Set the same attributes on every document that matches a filter, up to 50,000 at a time.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Filter (`filters`, list, required): Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
- Attributes to set (`attributes`, object, required): The attributes to set and their new values.
- Allow partial (`allow_partial`, true/false): When more documents match than one request may change (5 million to delete, 50,000 to update), change that many and report the rest, instead of failing.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "namespace": "support-articles",
  "patched_ids": [
    "article-0042",
    "article-0043"
  ],
  "rows_affected": 2,
  "rows_deleted": 0,
  "rows_patched": 2,
  "rows_remaining": false,
  "rows_upserted": 0,
  "upserted_ids": []
}
```

### Update namespace schema

Turn on full-text search for text attributes, or change other attributes' indexing, in place. A new index takes a few minutes to build before searches can use it.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Full-text search on (`full_text_attributes`, list): Text attributes to make searchable with 'Full-text search'.
- Schema (`schema`, object): Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `schema` (object): The schema sent, by attribute name
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 0,
  "rows_deleted": 0,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 0,
  "schema": {
    "title": {
      "full_text_search": true,
      "type": "string"
    }
  },
  "upserted_ids": []
}
```

### Upsert document

Create one document, or overwrite the whole document with that id, from its attributes and vector.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Document ID (`document_id`, text, required): The document's id: text, a UUID or a whole number.
- Attributes (`attributes`, object): The document's attributes and their values.
- Vector (`vector`, text): The document's embedding as numbers, such as [0.12, -0.4, 0.33], stored as its 'vector' attribute.
- Distance metric (`distance_metric`, text): How vectors are compared, set when a namespace first gets vectors. Defaults to cosine distance. One of: `cosine_distance` (Cosine distance), `euclidean_squared` (Euclidean squared).

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `document_id` (text): The document's id, as sent
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "document_id": "article-0042",
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 1,
  "rows_deleted": 0,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 1,
  "upserted_ids": [
    "article-0042"
  ]
}
```

### Upsert documents

Create documents, or overwrite whole documents with the same ids, from a list. Creates the namespace if it doesn't exist.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Documents (`documents`, list, required): A list of documents, each an object with an 'id' and any attributes, such as [{"id": "a1", "title": "Hello", "vector": [0.1, 0.2]}]. Every document needs the namespace's vectors, if it has any.
- Distance metric (`distance_metric`, text): How vectors are compared, set when a namespace first gets vectors. Defaults to cosine distance. One of: `cosine_distance` (Cosine distance), `euclidean_squared` (Euclidean squared).
- Schema (`schema`, object): Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.

**Outputs**

- `deleted_ids` (list): Ids of the documents deleted
- `namespace` (text): The namespace's name
- `patched_ids` (list): Ids of the documents updated
- `rows_affected` (number): Documents written in all
- `rows_deleted` (number): Documents deleted
- `rows_patched` (number): Documents updated
- `rows_remaining` (true/false): True when more documents match the filter: run the step again for them
- `rows_upserted` (number): Documents created or overwritten
- `upserted_ids` (list): Ids of the documents created or overwritten

**Example output**

```json
{
  "deleted_ids": [],
  "namespace": "support-articles",
  "patched_ids": [],
  "rows_affected": 2,
  "rows_deleted": 0,
  "rows_patched": 0,
  "rows_remaining": false,
  "rows_upserted": 2,
  "upserted_ids": [
    "article-0042",
    "article-0043"
  ]
}
```

### Vector search

Find the documents nearest a vector, nearest first. For a namespace that embeds text itself, give search text instead.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.
- Vector (`vector`, text): The query embedding as numbers, such as [0.12, -0.4, 0.33], with as many as the namespace's vectors.
- Search text (`search_text`, text): Text to search for instead of a vector, when the attribute searched embeds text natively.
- Vector attribute (`vector_attribute`, text): The attribute to search. Defaults to vector.
- How many (`top_k`, number): How many documents to return, 1 to 10,000. Defaults to 10. From 1 to 10000.
- Filter (`filters`, list): Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.
- Attributes to return (`include_attributes`, list): Return only these attributes. Leave empty to return them all.
- Consistency (`consistency`, text): Strong includes every write so far. Defaults to strong. One of: `strong` (Strong: include every write (default)), `eventual` (Eventual: faster, may miss the latest writes).

**Outputs**

- `count` (number): How many documents were returned
- `documents` (list): The documents found, best first
- `namespace` (text): The namespace's name

**Example output**

```json
{
  "count": 1,
  "documents": [
    {
      "attributes": {
        "status": "published",
        "title": "Resetting your password"
      },
      "id": "article-0042",
      "score": 0.1834
    }
  ],
  "namespace": "support-articles"
}
```

### Warm namespace cache

Tell turbopuffer that searches of a namespace are coming, so it gets it ready and the first ones are fast.

**Inputs**

- Namespace (`namespace`, text, required): The namespace. Pick one, or type its name.

**Outputs**

- `message` (text): turbopuffer's reply
- `namespace` (text): The namespace's name
- `status` (text): ACCEPTED once heard

**Example output**

```json
{
  "message": "cache warm hint accepted",
  "namespace": "support-articles",
  "status": "ACCEPTED"
}
```
