turbopuffer
App · 20 actions
Store and search documents in turbopuffer: vector and full-text search, filtered lookups and counts, upsert, update and delete documents, and manage namespaces.
Actions
| Action | What it does |
|---|---|
| Branch namespace | Make an instant copy of a namespace under a new name. |
| Count documents | Count the documents that match a filter, in all or for each value of some attributes. |
| Create namespace | Create an empty namespace, with the kind of ids its documents use and, optionally, attributes ready for full-text search. |
| Delete documents | Delete documents by their ids. |
| Delete documents by filter | Delete every document that matches a filter, up to 5 million at a time. |
| Delete namespace | Delete a namespace and every document in it. |
| Evaluate recall | Measure how well vector search finds the true nearest documents: turbopuffer compares sample searches with exhaustive ones. |
| Find documents | Find the documents that match a filter, in order of an attribute, like a database query. |
| Full-text search | Find the documents whose text best matches some words, ranked by BM25. |
| Get document | Get one document, with all its attributes, by its id. |
| 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. |
| List namespaces | List the namespaces in the connection's region, optionally only those whose names start with some text. |
| Make namespace read-only or writable | Make a namespace refuse document and schema writes, or accept them again. |
| Update document | Change some attributes of an existing document, keeping the rest. |
| Update documents by filter | Set the same attributes on every document that matches a filter, up to 50,000 at a time. |
| Update namespace schema | Turn on full-text search for text attributes, or change other attributes' indexing, in place. |
| Upsert document | Create one document, or overwrite the whole document with that id, from its attributes and vector. |
| Upsert documents | Create documents, or overwrite whole documents with the same ids, from a list. |
| Vector search | Find the documents nearest a vector, nearest first. |
| Warm namespace cache | Tell turbopuffer that searches of a namespace are coming, so it gets it ready and the first ones are fast. |
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_namespacetextRequired - The namespace to copy. Pick one, or type its name.
- New namespace name
namespacetextRequired - Up to 128 letters, digits, '-', '_' or '.'. It must not exist yet.
Outputs
deleted_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
source_namespacetext- The namespace it was copied from
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Filter
filterslist - 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_bylist - Attributes to count separately for each value of.
Outputs
countnumber- How many match in all
group_countnumber- How many groups
groupslist- One count for each group, when counting for each
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - Up to 128 letters, digits, '-', '_' or '.'. It must not exist yet.
- Document IDs are
id_typetext - 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_attributeslist - Text attributes to make searchable with 'Full-text search'.
- Schema
schemaobject - Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.
Outputs
deleted_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
schemaobject- The schema sent, by attribute name
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Document IDs
document_idslistRequired - The ids of the documents to delete.
Outputs
deleted_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Filter
filterslistRequired - Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
- Allow partial
allow_partialtrue/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_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
Outputs
deletedtrue/false- True once deleted
namespacetext- The namespace's name
statustext- turbopuffer's status
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Sample searches
numnumber - How many searches to compare, 1 to 100. Defaults to 25.From 1 to 100.
- Results per search
top_knumber - How many nearest documents each finds. Defaults to 10.From 1 to 1000.
- Filter
filterslist - 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_countnumber- Average results of the vector searches
avg_exhaustive_countnumber- Average results of the exhaustive searches
avg_recallnumber- Share of the true nearest found, 0 to 1
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Filter
filterslist - 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_bytext - The attribute to sort by. Defaults to id.
- Order
directiontext - Defaults to highest first.One of:
desc(Highest first (default)),asc(Lowest first). - How many
limitnumber - How many to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
- Skip
offsetnumber - How many matching documents to skip first.From 0 to 9999.
- Attributes to return
include_attributeslist - Return only these attributes. Leave empty to return them all.
Outputs
countnumber- How many documents were returned
documentslist- The documents found, best first
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Attribute
attributetextRequired - The text attribute to search, such as body.
- Search words
querytextRequired - The words to look for.
- How many
top_knumber - How many documents to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
- Filter
filterslist - 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_attributeslist - Return only these attributes. Leave empty to return them all.
- Consistency
consistencytext - 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
countnumber- How many documents were returned
documentslist- The documents found, best first
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Document ID
document_idtextRequired - The document's id, from a search or an earlier step.
Outputs
attributesobject- Every attribute of the document
idtext- The document's id: text, a UUID or a whole number
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
Outputs
approx_logical_bytesnumber- About how many bytes of data it holds
approx_row_countnumber- About how many documents it holds
created_attext- When it was created (ISO 8601)
index_statustext- up-to-date, or updating while new writes are indexed
last_write_attext- When its data last changed (ISO 8601)
namespacetext- The namespace's name
read_onlytrue/false- True when it refuses writes
schemaobject- Each attribute's type and indexing, by attribute name
unindexed_rowsnumber- Documents written but not yet indexed
updated_attext- When its data or schema last changed (ISO 8601)
Example output
{
"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
prefixtext - Only namespaces whose names start with this.
- Page size
page_sizenumber - How many to return, 1 to 1,000. Defaults to 100.From 1 to 1000.
- Next page cursor
cursortext - The 'next_cursor' from an earlier page.
Outputs
countnumber- How many on this page
namespaceslist- The namespaces
next_cursortext- Cursor for the next page, empty on the last
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- State
statetextRequired - Read-only refuses writes; writable allows them.One of:
read_only(Read-only: refuse writes),writable(Writable: allow writes).
Outputs
approx_logical_bytesnumber- About how many bytes of data it holds
approx_row_countnumber- About how many documents it holds
created_attext- When it was created (ISO 8601)
index_statustext- up-to-date, or updating while new writes are indexed
last_write_attext- When its data last changed (ISO 8601)
namespacetext- The namespace's name
read_onlytrue/false- True when it refuses writes
schemaobject- Each attribute's type and indexing, by attribute name
unindexed_rowsnumber- Documents written but not yet indexed
updated_attext- When its data or schema last changed (ISO 8601)
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Document ID
document_idtextRequired - The document's id, from a search or an earlier step.
- Attributes to change
attributesobjectRequired - The attributes to set and their new values.
Outputs
deleted_idslist- Ids of the documents deleted
document_idtext- The document's id, as sent
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Filter
filterslistRequired - Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
- Attributes to set
attributesobjectRequired - The attributes to set and their new values.
- Allow partial
allow_partialtrue/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_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Full-text search on
full_text_attributeslist - Text attributes to make searchable with 'Full-text search'.
- Schema
schemaobject - Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.
Outputs
deleted_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
schemaobject- The schema sent, by attribute name
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Document ID
document_idtextRequired - The document's id: text, a UUID or a whole number.
- Attributes
attributesobject - The document's attributes and their values.
- Vector
vectortext - The document's embedding as numbers, such as [0.12, -0.4, 0.33], stored as its 'vector' attribute.
- Distance metric
distance_metrictext - 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_idslist- Ids of the documents deleted
document_idtext- The document's id, as sent
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Documents
documentslistRequired - 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_metrictext - 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
schemaobject - Attribute types and indexing in turbopuffer's schema format, such as {"published_at": "datetime", "secret": {"type": "string", "filterable": false}}.
Outputs
deleted_idslist- Ids of the documents deleted
namespacetext- The namespace's name
patched_idslist- Ids of the documents updated
rows_affectednumber- Documents written in all
rows_deletednumber- Documents deleted
rows_patchednumber- Documents updated
rows_remainingtrue/false- True when more documents match the filter: run the step again for them
rows_upsertednumber- Documents created or overwritten
upserted_idslist- Ids of the documents created or overwritten
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
- Vector
vectortext - The query embedding as numbers, such as [0.12, -0.4, 0.33], with as many as the namespace's vectors.
- Search text
search_texttext - Text to search for instead of a vector, when the attribute searched embeds text natively.
- Vector attribute
vector_attributetext - The attribute to search. Defaults to vector.
- How many
top_knumber - How many documents to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
- Filter
filterslist - 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_attributeslist - Return only these attributes. Leave empty to return them all.
- Consistency
consistencytext - 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
countnumber- How many documents were returned
documentslist- The documents found, best first
namespacetext- The namespace's name
Example output
{
"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
namespacetextRequired - The namespace. Pick one, or type its name.
Outputs
messagetext- turbopuffer's reply
namespacetext- The namespace's name
statustext- ACCEPTED once heard
Example output
{
"message": "cache warm hint accepted",
"namespace": "support-articles",
"status": "ACCEPTED"
}