© 2025 turbopuffer Inc.
Terms of serviceData Processing AgreementPrivacy PolicySecurity & Compliance- SOC2 Type 2 certified
- HIPAA compliant
Query, filter, full-text search and vector search documents.
Latency
Percentile
Latency
Exact filters for attributes to refine search results for. Think of it as a SQL WHERE clause.
See Filtering Parameters below for details.
When combined with a vector, the query planner will automatically combine the attribute index and the approximate nearest neighbor index for best performance and recall. See our post on Native Filtering for details.
For the best performance, separate documents into namespaces instead of filtering where possible. See also Performance.
Example: ["And", [["id", "Gte", 1000], ["permissions", "In", ["3d7a7296-3d6a-4796-8fb0-f90406b1f621", "92ef7c95-a212-43a4-ae4e-0ebc96a65764"]]]]
Optionally the vector to search for.
It must have the same number of dimensions as the vectors in the namespace.
Example: [0.1, 0.2, 0.3, ..., 76.8]
Used for BM25 full-text search or ordering by attributes.
Currently, you can pass a rank_by parameter or a vector parameter, but not both. If neither is passed, results are sorted by ID.
For hybrid search, you must do multiple queries (e.g. BM25 + vector) and combine the results client-side with e.g. reciprocal-rank fusion. We encourage users to write a strong query layer abstraction, as it's not uncommon to do 6 turbopuffer queries per user query.
Order by attribute example: ["timestamp", "desc"]
BM25: ["text", "BM25", "fox jumping"]
BM25 with multiple, weighted fields: ["Sum", [["Product", [2, ["title", "BM25", "fox jumping"]], ["content", "BM25", "fox jumping"]]]]
The function used to calculate vector similarity. Possible values are cosine_distance or euclidean_squared.
cosine_distance is defined as 1 - cosine_similarity and ranges from 0 to 2.
Lower is better.
euclidean_squared is defined as sum((x - y)^2). Lower is better.
Number of results to return.
Return vectors for the search results. Vectors are large and slow to deserialize on the client, so use this option only if you need them.
List of attribute names to return in the response. Can be set to true to
return all attributes. Return only the ones you need for best performance.
The encoding format to use for the vectors in the response. The supported
formats are float and base64.
If float, vectors are returned as arrays of numbers.
If base64, vectors are returned as base64-encoded strings representing the
vectors serialized in little-endian float32 binary format.
Choose between strong and eventual read-after-write consistency.
{"level": "strong"}{"level": "eventual"}Strong consistency requires a round-trip to object storage to fetch the latest writes before returning a query result, ensuring up-to-date data but adding latency. Eventual consistency removes this requirement, potentially reducing latency while causing stale reads in some cases. Benchmarking on a vector workload (768 dims, 1M docs, ~3GB) shows a p50 warm latency of 16 ms for strong consistency and 10 ms for eventual consistency.
Most queries are served by the same node that handles writes, so updates are usually visible immediately. Over 99.99% of queries return consistent data. Here's a more specific breakdown based on our monitoring data:
| % of queries | maximum lag (<= time) |
|---|---|
| 99.9970% | 0s (strongly consistent) |
| 99.9973% | 1s |
| 99.9975% | 10s |
| 99.9976% | 60s |
| 100% | 1h |
In rare cases (eg. namespace routing changes during scaling) reads may briefly return stale data until its cache updates. This query staleness is typically limited to ~100ms (as the commit log entry is updated in the background), with a strict upper bound of 1 hour (currently non-configurable but subject to future tuning). However, the cache is refreshed on every query, so the latest writes should appear on the next request.
When you need to filter documents, you can combine filters with vector search or use them alone. Here's an example of finding recent public documents:
Filter-only (no vector or FTS/BM25) queries can specify a rank_by parameter to order results by a specific attribute (i.e. SQL ORDER BY). For example, to order by timestamp in descending order:
Ordering by multiple attributes isn't yet implemented.
Similar to SQL, the ordering of results is not guaranteed when multiple documents have the same attribute value for the rank_by parameter. Array attributes aren't supported.
The FTS attribute must be configured with full_text_search set in the schema
when writing documents. See Schema documentation and
the Full-Text Search guide for more details.
For an example of hybrid search (combining both vector and BM25 results), see Hybrid Search.
You can combine BM25 full-text search with filters to limit results to a specific subset of documents.
Aggregations combine the results of multiple sub-queries into a single score. Specifically, the following operators are supported:
Sum: Sum the scores of the sub-queries.Max: Use the maximum score of sub-queries as the score.Aggregations can be nested. For example:
"rank_by": ["Sum", [
["Max", [
["title", "BM25", "whale facts"],
["description", "BM25", "whale facts"]
]],
["content", "BM25", "huge whale"]
]]
You can specify a weight / boost per-field by using the Product operator inside a rank_by.
For example, to apply a 2x score multiplier on the title sub-query:
"rank_by": ["Sum", [
["Product", [2, ["title", "BM25", "quick fox"]]],
["content", "BM25", "quick fox"]
]]
A simple form of phrase matching is supported with the ContainsAllTokens filter. This filter matches documents that contain all the tokens present in the filter input string:
"filters": ["text", "ContainsAllTokens", "lazy walrus"]
Specifically, this filter would match a document containing "walrus is super lazy", but not a document containing only "lazy." Combining this with a Not filter can help exclude unwanted results:
"filters": ["Not", ["text", "ContainsAllTokens", "polar bear"]]
Full phrase matching, i.e. requiring the exact phrase "lazy walrus", with the terms adjacent and in that order, is not yet supported.
Filters allow you to narrow down results by applying exact conditions to attributes. Conditions are arrays with an attribute name, operation, and value, for example:
["attr_name", "Eq", 42]["page_id", "In", ["page1", "page2"]]["user_migrated_at", "NotEq", null]Values must have the same type as the attribute's value, or an array of that type for operators like In.
Conditions can be combined using {And,Or} operations:
// basic And condition
"filters": ["And", [
["attr_name", "Eq", 42],
["page_id", "In", ["page1", "page2"]]
]]
// conditions can be nested
"filters": ["And", [
["page_id", "In", ["page1", "page2"]],
["Or", [
["public", "Eq", 1],
["permission_id", "In", ["3iQK2VC4", "wzw8zpnQ"]]
]]
]]
// legacy API: an object may provided instead (implicitly And)
"filters": {
"attr_name": ["Eq", 42],
"page_id": ["In", ["page1", "page2"]],
}
Filters can also be applied to the id field, which refers to the document ID.
Matches if all of the filters match.
Matches if at least one of the filters matches.
Matches if the filter does not match.
Exact match for id or attributes values. If value is null, matches documents missing the attribute.
Inverse of Eq, for attributes values. If value is null, matches documents with the attribute.
Matches any id or attributes values contained in the provided list. If both the provided value and the target document field are arrays, then this checks if any elements of the two sets intersect.
Inverse of In, matches any attributes values not contained in the provided list.
For ints, this is a numeric less-than on attributes values. For strings, lexicographic less-than. For datetimes, numeric less-than on millisecond representation.
For ints, this is a numeric less-than-or-equal on attributes values. For strings, lexicographic less-than-or-equal. For datetimes, numeric less-than-or-equal on millisecond representation.
For ints, this is a numeric greater-than on attributes values. For strings, lexicographic greater-than. For datetimes, numeric greater-than on millisecond representation.
For ints, this is a numeric greater-than-or-equal on attributes values. For strings, lexicographic greater-than-or-equal. For datetimes, numeric greater-than-or-equal on millisecond representation.
Unix-style glob match against string attributes values. The full syntax is described in the globset documentation. Glob patterns with a concrete prefix like "foo*" internally compile to efficient range queries
Inverse of Glob, Unix-style glob filters against string attributes values. The full syntax is described in the globset documentation.
Case insensitive version of Glob.
Case insensitive version of NotGlob.
Matches if all tokens in the input string are present in the attributes value. Requires that the attribute is configured for full-text search.
Using nested And and Or filters:
If you need to paginate the entire namespace, use the more performant Export endpoint.
By default, results are sorted in ascending ID order, which allows pagination with an ID greater-than filter for filter-only queries. You can specify a rank_by parameter to order results by attributes, see Ordering by Attributes.
Currently paginating beyond the first page for full-text search and vector
search is not supported. Pass a larger top_k value to get more results and
paginate client-side. If you need a higher limit, please contact us.