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

ActionWhat it does
Branch namespaceMake an instant copy of a namespace under a new name.
Count documentsCount the documents that match a filter, in all or for each value of some attributes.
Create namespaceCreate an empty namespace, with the kind of ids its documents use and, optionally, attributes ready for full-text search.
Delete documentsDelete documents by their ids.
Delete documents by filterDelete every document that matches a filter, up to 5 million at a time.
Delete namespaceDelete a namespace and every document in it.
Evaluate recallMeasure how well vector search finds the true nearest documents: turbopuffer compares sample searches with exhaustive ones.
Find documentsFind the documents that match a filter, in order of an attribute, like a database query.
Full-text searchFind the documents whose text best matches some words, ranked by BM25.
Get documentGet one document, with all its attributes, by its id.
Get namespace detailsGet 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 namespacesList the namespaces in the connection's region, optionally only those whose names start with some text.
Make namespace read-only or writableMake a namespace refuse document and schema writes, or accept them again.
Update documentChange some attributes of an existing document, keeping the rest.
Update documents by filterSet the same attributes on every document that matches a filter, up to 50,000 at a time.
Update namespace schemaTurn on full-text search for text attributes, or change other attributes' indexing, in place.
Upsert documentCreate one document, or overwrite the whole document with that id, from its attributes and vector.
Upsert documentsCreate documents, or overwrite whole documents with the same ids, from a list.
Vector searchFind the documents nearest a vector, nearest first.
Warm namespace cacheTell 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 copysource_namespacetextRequired
The namespace to copy. Pick one, or type its name.
New namespace namenamespacetextRequired
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Filterfilterslist
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 eachgroup_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 namenamespacetextRequired
Up to 128 letters, digits, '-', '_' or '.'. It must not exist yet.
Document IDs areid_typetext
The kind of ids its documents use. Defaults to text.One of: string (Text (default)), uint (Whole number), uuid.
Full-text search onfull_text_attributeslist
Text attributes to make searchable with 'Full-text search'.
Schemaschemaobject
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Document IDsdocument_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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
FilterfilterslistRequired
Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
Allow partialallow_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

NamespacenamespacetextRequired
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Sample searchesnumnumber
How many searches to compare, 1 to 100. Defaults to 25.From 1 to 100.
Results per searchtop_knumber
How many nearest documents each finds. Defaults to 10.From 1 to 1000.
Filterfilterslist
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Filterfilterslist
Only documents that match, in turbopuffer's filter format, such as ["And", [["status", "Eq", "published"], ["year", "Gte", 2024]]]. Leave empty for every document.
Order byorder_bytext
The attribute to sort by. Defaults to id.
Orderdirectiontext
Defaults to highest first.One of: desc (Highest first (default)), asc (Lowest first).
How manylimitnumber
How many to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
Skipoffsetnumber
How many matching documents to skip first.From 0 to 9999.
Attributes to returninclude_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"
}

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

Inputs

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
AttributeattributetextRequired
The text attribute to search, such as body.
Search wordsquerytextRequired
The words to look for.
How manytop_knumber
How many documents to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
Filterfilterslist
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 returninclude_attributeslist
Return only these attributes. Leave empty to return them all.
Consistencyconsistencytext
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Document IDdocument_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

NamespacenamespacetextRequired
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 withprefixtext
Only namespaces whose names start with this.
Page sizepage_sizenumber
How many to return, 1 to 1,000. Defaults to 100.From 1 to 1000.
Next page cursorcursortext
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
StatestatetextRequired
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Document IDdocument_idtextRequired
The document's id, from a search or an earlier step.
Attributes to changeattributesobjectRequired
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
FilterfilterslistRequired
Which documents, in turbopuffer's filter format, such as ["status", "Eq", "draft"].
Attributes to setattributesobjectRequired
The attributes to set and their new values.
Allow partialallow_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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Full-text search onfull_text_attributeslist
Text attributes to make searchable with 'Full-text search'.
Schemaschemaobject
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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Document IDdocument_idtextRequired
The document's id: text, a UUID or a whole number.
Attributesattributesobject
The document's attributes and their values.
Vectorvectortext
The document's embedding as numbers, such as [0.12, -0.4, 0.33], stored as its 'vector' attribute.
Distance metricdistance_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

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
DocumentsdocumentslistRequired
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 metricdistance_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).
Schemaschemaobject
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"
  ]
}

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

Inputs

NamespacenamespacetextRequired
The namespace. Pick one, or type its name.
Vectorvectortext
The query embedding as numbers, such as [0.12, -0.4, 0.33], with as many as the namespace's vectors.
Search textsearch_texttext
Text to search for instead of a vector, when the attribute searched embeds text natively.
Vector attributevector_attributetext
The attribute to search. Defaults to vector.
How manytop_knumber
How many documents to return, 1 to 10,000. Defaults to 10.From 1 to 10000.
Filterfilterslist
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 returninclude_attributeslist
Return only these attributes. Leave empty to return them all.
Consistencyconsistencytext
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

NamespacenamespacetextRequired
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"
}

On this page