openapi: "3.1.0" info: title: turbopuffer API version: "0.0.1" description: turbopuffer is a fast search engine that combines vector and full-text search using object storage. termsOfService: https://turbopuffer.com/terms-of-service contact: info@turbopuffer.com servers: - url: https://{region}.turbopuffer.com description: Production API servers variables: region: description: The turbopuffer region to use. security: - bearerAuth: [] # Intentionally omitted endpoints: # # - get /v1/namespaces/{namespace} (export) # Deprecated in favor of paging over v2 query APIs. # (The columnar response format is not supported by Stainless.) # # - head /v1/namespaces/{namespace} # Deprecated in favor of collecting the document count via count queries # and the vector dimensionality via get /v1/namespaces/{namespace}/schema. # (HEAD requests are not supported by Stainless.) paths: /v1/namespaces: get: description: List namespaces. parameters: - name: cursor in: query description: Retrieve the next page of results. schema: { type: string } - name: prefix in: query description: Retrieve only the namespaces that match the prefix. schema: { type: string } - name: page_size in: query description: Limit the number of results per page. schema: { type: integer, format: int32, minimum: 1, maximum: 1000 } responses: "200": description: A JSON array of namespace metadata. content: application/json: schema: type: object properties: namespaces: type: array description: The list of namespaces. items: { $ref: "#/components/schemas/NamespaceSummary" } next_cursor: type: string description: The cursor to use to retrieve the next page of results. default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v1/namespaces/{namespace}/schema: get: description: Get namespace schema. parameters: - { $ref: "#/components/parameters/namespace" } responses: "200": description: The schema of the namespace. content: application/json: schema: description: The response to a successful namespace schema request. type: object additionalProperties: { $ref: "#/components/schemas/AttributeSchemaConfig" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } post: description: Update namespace schema. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: description: The desired schema for the namespace. type: object additionalProperties: { $ref: "#/components/schemas/AttributeSchema" } responses: "200": description: The schema of the namespace. content: application/json: schema: description: The updated schema for the namespace. type: object additionalProperties: { $ref: "#/components/schemas/AttributeSchemaConfig" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}/metadata: get: description: Get metadata about a namespace. parameters: - { $ref: "#/components/parameters/namespace" } responses: "200": description: The metadata of the namespace. content: application/json: schema: { $ref: "#/components/schemas/NamespaceMetadata" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v1/namespaces/{namespace}/metadata: patch: description: Update metadata configuration for a namespace. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: { $ref: "#/components/schemas/NamespaceMetadataPatch" } responses: "200": description: The updated metadata of the namespace. content: application/json: schema: { $ref: "#/components/schemas/NamespaceMetadata" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v1/namespaces/{namespace}/hint_cache_warm: get: description: Signal turbopuffer to prepare for low-latency requests. parameters: - { $ref: "#/components/parameters/namespace" } responses: "202": description: The status of the cache warm request. content: application/json: schema: description: The response to a successful cache warm request. type: object properties: status: const: "ACCEPTED" description: The status of the request. message: type: string required: [ status ] default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v1/namespaces/{namespace}/_debug/recall: post: description: Evaluate recall. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: type: object properties: num: type: integer description: The number of searches to run. top_k: type: integer description: Search for `top_k` nearest neighbors. filters: x-stainless-any: true description: Filter by attributes. Same syntax as the query endpoint. include_ground_truth: type: boolean description: Include ground truth data (query vectors and true nearest neighbors) in the response. default: false rank_by: description: > The ranking function to evaluate recall for. If provided, `num` must be either null or 1. x-stainless-any: true responses: "200": description: The status of the cache warm request. content: application/json: schema: description: The response to a successful cache warm request. type: object properties: avg_recall: description: The average recall of the queries. type: number avg_exhaustive_count: description: The average number of documents retrieved by the exhaustive searches. type: number avg_ann_count: description: The average number of documents retrieved by the approximate nearest neighbor searches. type: number ground_truth: description: Ground truth data including query vectors and true nearest neighbors. Only included when include_ground_truth is true. type: array items: type: object properties: query_vector: description: The query vector used for this search. type: array items: type: number nearest_neighbors: description: The true nearest neighbors with their distances and vectors. type: array items: { $ref: "#/components/schemas/Row" } required: [ query_vector, nearest_neighbors ] required: [ avg_recall, avg_exhaustive_count, avg_ann_count ] default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}: post: description: Create, update, or delete documents. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: { $ref: "#/components/schemas/Write" } responses: "200": description: The status of the request. content: application/json: schema: { $ref: "#/components/schemas/WriteResult" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } delete: description: Delete namespace. parameters: - { $ref: "#/components/parameters/namespace" } responses: "200": description: The status of the deletion request. content: application/json: schema: description: The response to a successful namespace deletion request. type: object properties: status: const: "OK" description: The status of the request. required: [ status ] default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}/query: post: description: Query, filter, full-text search and vector search documents. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: allOf: - { $ref: "#/components/schemas/QueryConfig" } - { $ref: "#/components/schemas/Query" } responses: "200": description: The schema of the namespace. content: application/json: schema: { $ref: "#/components/schemas/QueryResult" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}/query?stainless_overload=multiQuery: post: description: Issue multiple concurrent queries filter or search documents. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: allOf: - { $ref: "#/components/schemas/QueryConfig" } - type: object required: [ queries ] properties: queries: type: array items: { $ref: "#/components/schemas/Query" } rerank_by: description: > How to combine the rows returned by each sub-query into a single ranked list. x-stainless-any: true limit: description: Limits the total number of reranked documents returned. $ref: "#/components/schemas/RerankLimit" responses: "200": description: The schema of the namespace. content: application/json: schema: { $ref: "#/components/schemas/MultiQueryResult" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}?stainless_overload=branchFrom: post: description: Creates an instant, copy-on-write clone of a namespace. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: { $ref: "#/components/schemas/BranchFromNamespaceConfig" } responses: "200": description: The status of the request. content: application/json: schema: { $ref: "#/components/schemas/WriteResult" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}?stainless_overload=copyFrom: post: description: Copy all documents from another namespace into this one. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: allOf: - { $ref: "#/components/schemas/CopyFromNamespaceConfig" } - type: object properties: dest_encryption: description: > (Optional) The encryption configuration for the destination namespace. $ref: "#/components/schemas/Encryption" responses: "200": description: The status of the request. content: application/json: schema: { $ref: "#/components/schemas/WriteResult" } default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } /v2/namespaces/{namespace}/explain_query: post: description: Explain a query plan. parameters: - { $ref: "#/components/parameters/namespace" } requestBody: content: application/json: schema: allOf: - { $ref: "#/components/schemas/QueryConfig" } - { $ref: "#/components/schemas/Query" } responses: "200": description: The query plan explanation. content: application/json: schema: description: The response to a successful query explain. type: object properties: plan_text: type: string description: The textual representation of the query plan. default: description: An error response. content: application/json: schema: { $ref: "#/components/schemas/ErrorResponse" } components: parameters: namespace: name: namespace in: path required: true description: The name of the namespace. schema: { type: string } schemas: NamespaceSummary: description: A summary of a namespace. type: object properties: id: type: string description: The namespace ID. required: [ id ] NamespaceMetadata: description: Metadata about a namespace. type: object properties: schema: description: The schema of the namespace. type: object additionalProperties: { $ref: "#/components/schemas/AttributeSchemaConfig" } approx_row_count: type: integer format: int64 description: The approximate number of rows in the namespace. approx_logical_bytes: type: integer format: int64 description: The approximate number of logical bytes in the namespace. created_at: type: string format: date-time description: The timestamp when the namespace was created. updated_at: type: string format: date-time description: The timestamp when the namespace was last modified by a write operation. encryption: $ref: '#/components/schemas/Encryption' index: oneOf: - type: object title: index-up-to-date properties: status: const: up-to-date required: [ status ] - type: object title: index-updating properties: status: const: updating unindexed_bytes: type: integer description: The number of bytes in the namespace that are in the write-ahead log but have not yet been indexed. required: [ status, unindexed_bytes ] pinning: { $ref: "#/components/schemas/PinningConfigResponse" } sharding: { $ref: "#/components/schemas/ShardingConfig" } read_only: type: boolean description: > Whether document and schema writes are rejected. Omitted when `false`. required: [ schema, approx_logical_bytes, approx_row_count, created_at, updated_at, encryption, index ] NamespaceMetadataPatch: description: Request to update namespace metadata configuration. type: object properties: pinning: description: | Configuration for namespace pinning. - Missing field: no change to pinning configuration - `null` or `false`: explicitly remove pinning - `true`: enable pinning with default configuration - Object: set pinning configuration oneOf: - type: "null" - type: boolean # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/PinningConfig" } read_only: type: boolean description: > Set to `true` to reject document and schema writes, or `false` to allow them. Writes already in progress may still commit. Metadata updates remain available. Write: description: Create, update, or delete documents. type: object properties: upsert_columns: { $ref: "#/components/schemas/Columns" } upsert_rows: type: array items: { $ref: "#/components/schemas/Row" } patch_columns: { $ref: "#/components/schemas/Columns" } patch_rows: type: array items: { $ref: "#/components/schemas/Row" } deletes: type: array items: { $ref: "#/components/schemas/Id" } upsert_condition: description: > A condition evaluated against the current value of each document targeted by an upsert write. Only documents that pass the condition are upserted. x-stainless-any: true patch_condition: description: > A condition evaluated against the current value of each document targeted by a patch write. Only documents that pass the condition are patched. x-stainless-any: true delete_condition: description: > A condition evaluated against the current value of each document targeted by a delete write. Only documents that pass the condition are deleted. x-stainless-any: true distance_metric: { $ref: "#/components/schemas/DistanceMetric" } schema: description: > The schema of the attributes attached to the documents. type: object additionalProperties: { $ref: "#/components/schemas/AttributeSchema" } branch_from_namespace: { $ref: "#/components/schemas/BranchFromNamespaceParams" } copy_from_namespace: { $ref: "#/components/schemas/CopyFromNamespaceParams" } delete_by_filter: description: The filter specifying which documents to delete. x-stainless-any: true delete_by_filter_allow_partial: type: boolean description: Allow partial completion when filter matches too many documents. patch_by_filter: { $ref: "#/components/schemas/PatchByFilter" } patch_by_filter_allow_partial: type: boolean description: Allow partial completion when filter matches too many documents. return_affected_ids: type: boolean description: > If true, return the IDs of affected rows (deleted, patched, upserted) in the response. For filtered and conditional writes, only IDs for writes that succeeded will be included. default: false encryption: { $ref: "#/components/schemas/Encryption" } sharding: { $ref: "#/components/schemas/ShardingConfig" } disable_backpressure: type: boolean description: > Disables write throttling (HTTP 429 responses) during high-volume ingestion. PatchByFilter: description: The patch and filter specifying which documents to patch. required: [ patch, filters ] properties: patch: type: object additionalProperties: true filters: x-stainless-any: true description: Filter by attributes. Same syntax as the query endpoint. WriteBilling: description: The billing information for a write request. type: object properties: billable_logical_bytes_written: type: integer description: The number of billable logical bytes written to the namespace. query: { $ref: "#/components/schemas/QueryBilling" } required: [ billable_logical_bytes_written ] WritePerformance: description: The performance information for a write request. type: object properties: server_total_ms: type: integer description: Request time measured on the server, in milliseconds. required: [ server_total_ms ] WriteResult: description: The response to a successful write request. type: object properties: status: const: "OK" description: The status of the request. message: type: string description: A message describing the result of the write request. rows_affected: type: integer description: The number of rows affected by the write request. rows_upserted: type: integer description: The number of rows upserted by the write request. rows_patched: type: integer description: The number of rows patched by the write request. rows_deleted: type: integer description: The number of rows deleted by the write request. rows_remaining: type: boolean description: Whether more documents match the filter for partial operations. upserted_ids: type: array description: > The IDs of documents that were upserted. Only included when `return_affected_ids` is true and at least one document was upserted. items: { $ref: "#/components/schemas/Id" } patched_ids: type: array description: > The IDs of documents that were patched. Only included when `return_affected_ids` is true and at least one document was patched. items: { $ref: "#/components/schemas/Id" } deleted_ids: type: array description: > The IDs of documents that were deleted. Only included when `return_affected_ids` is true and at least one document was deleted. items: { $ref: "#/components/schemas/Id" } billing: { $ref: "#/components/schemas/WriteBilling" } performance: { $ref: "#/components/schemas/WritePerformance" } required: [ status, message, rows_affected, billing ] Query: description: Query, filter, full-text search and vector search documents. type: object properties: rank_by: description: > How to rank the documents in the namespace. x-stainless-any: true top_k: description: The number of results to return. type: integer filters: description: > Exact filters for attributes to refine search results for. Think of it as a SQL WHERE clause. x-stainless-any: true include_attributes: { $ref: "#/components/schemas/IncludeAttributes" } exclude_attributes: description: > List of attribute names to exclude from the response. All other attributes will be included in the response. type: array items: { type: string } aggregate_by: description: > Aggregations to compute over all documents in the namespace that match the filters. type: object additionalProperties: true group_by: description: > Groups documents by the specified attributes (the "group key") before computing aggregates. Aggregates are computed separately for each group. type: array items: { x-stainless-any: true } compute_attributes: description: > Computes additional values on documents returned by a query. Each key is the name of the computed attribute; each value is an expression describing how to compute it. type: object additionalProperties: true distance_metric: { $ref: "#/components/schemas/DistanceMetric" } limit: anyOf: - type: integer # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/Limit" } QueryConfig: description: Configuration options for a query. type: object properties: vector_encoding: { $ref: "#/components/schemas/VectorEncoding" } consistency: description: The consistency level for a query. type: object properties: level: anyOf: - const: strong description: > Strong consistency. Requires a round-trip to object storage to fetch the latest writes. - const: eventual description: > Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes. description: The query's consistency level. RerankLimit: anyOf: - type: integer # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - type: object required: [ total ] additionalProperties: false properties: total: type: integer QueryBilling: description: The billing information for a query. type: object properties: billable_logical_bytes_queried: type: integer description: The number of billable logical bytes queried from the namespace. billable_logical_bytes_returned: type: integer description: The number of billable logical bytes returned from the query. required: [ billable_logical_bytes_queried, billable_logical_bytes_returned ] QueryPerformance: description: The performance information for a query. type: object properties: cache_hit_ratio: type: number description: The ratio of cache hits to total cache lookups. cache_temperature: type: string description: A qualitative description of the cache hit ratio (`hot`, `warm`, or `cold`). server_total_ms: type: integer description: > Request time measured on the server, including time spent waiting for other queries to complete if the namespace was at its concurrency limit. query_execution_ms: type: integer description: > Request time measured on the server, excluding time spent waiting due to the namespace concurrency limit. exhaustive_search_count: type: integer description: The number of unindexed documents processed by the query. approx_namespace_size: type: integer description: the approximate number of documents in the namespace. required: - cache_hit_ratio - cache_temperature - server_total_ms - query_execution_ms - exhaustive_search_count - approx_namespace_size QueryResult: description: The result of a query. type: object allOf: - $ref: "#/components/schemas/SingleQueryResult" - type: object properties: performance: { $ref: "#/components/schemas/QueryPerformance" } billing: { $ref: "#/components/schemas/QueryBilling" } required: [ performance, billing ] MultiQueryResult: description: The result of a multi-query. type: object properties: results: type: array items: { $ref: "#/components/schemas/SingleQueryResult" } performance: { $ref: "#/components/schemas/QueryPerformance" } billing: { $ref: "#/components/schemas/QueryBilling" } required: [ performance, billing, results ] SingleQueryResult: type: object properties: aggregations: type: object additionalProperties: true aggregation_groups: type: array items: { $ref: "#/components/schemas/AggregationGroup" } rows: type: array items: { $ref: "#/components/schemas/Row" } Columns: description: > A list of documents in columnar format. Each key is a column name, mapped to an array of values for that column. type: object properties: id: type: array description: The IDs of the documents. items: { $ref: "#/components/schemas/Id" } vector: oneOf: - type: array description: The vector embeddings of the documents. items: { $ref: "#/components/schemas/Vector" } - { $ref: "#/components/schemas/Vector" } required: [ id ] additionalProperties: type: array items: x-stainless-any: true description: The attributes attached to each of the documents. AggregationGroup: description: A single aggregation group. type: object additionalProperties: true Row: description: A single document, in a row-based format. type: object properties: id: { $ref: "#/components/schemas/Id" } vector: { $ref: "#/components/schemas/Vector" } required: [ id ] additionalProperties: true Id: anyOf: - description: A UUID. type: string format: uuid - description: A string ID. type: string - description: An integer ID. type: integer description: An identifier for a document. Vector: description: A vector embedding associated with a document. oneOf: - description: A dense vector encoded as an array of floats. type: array items: type: number x-turbopuffer-width: 32 - description: A dense vector encoded as a base64 string. type: string VectorEncoding: description: The encoding to use for vectors in the response. oneOf: - const: float - const: base64 DistanceMetric: anyOf: - const: cosine_distance description: > Defined as `1 - cosine_similarity` and ranges from 0 to 2. Lower is better. - const: euclidean_squared description: Defined as `sum((x - y)^2)`. Lower is better. description: A function used to calculate vector similarity. Limit: description: Limits the documents returned by a query. type: object properties: total: description: Limits the total number of documents returned. type: integer per: description: > Limits the number of documents with the same value for a set of attributes (the "limit key") that can appear in the results. type: object properties: attributes: description: The attributes to include in the limit key. type: array items: { type: string } limit: description: > The maximum number of documents to return for each value of the limit key. type: integer required: [ attributes, limit ] required: [ total ] IncludeAttributes: oneOf: - description: > When `true`, include all attributes in the response. When `false`, include no attributes in the response. type: boolean - description: > Include exactly the specified attributes in the response. type: array items: { type: string } description: Whether to include attributes in the response. AttributeSchema: description: The schema for an attribute attached to a document. anyOf: - $ref: "#/components/schemas/AttributeType" # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/AttributeSchemaConfig" } AttributeSchemaConfig: description: > Detailed configuration for an attribute attached to a document. type: object properties: type: { $ref: "#/components/schemas/AttributeType" } filterable: description: > Whether or not the attributes can be used in filters. type: boolean regex: description: > Whether to enable Regex filters on this attribute. type: boolean glob: description: > Whether to enable Glob filters on this attribute. type: boolean fuzzy: description: > Whether to enable Fuzzy filters on this attribute. type: boolean full_text_search: { $ref: "#/components/schemas/FullTextSearch" } ann: { $ref: "#/components/schemas/Ann" } sparse_knn: { $ref: "#/components/schemas/SparseKnn" } embed: { $ref: "#/components/schemas/AttributeEmbed" } required: [ type ] AttributeType: description: > The data type of the attribute. Valid values: string, int, uint, float, uuid, datetime, bool, []string, []int, []uint, []float, []uuid, []datetime, []bool, [DIMS]f16, [DIMS]f32, {}f16. type: string # NOTE(benesch): it would be nice to use a stronger type than a string # here. Unfortunately the vector type includes an arbitrary dimension # (e.g., [384]f32), which means a simple string enum is not sufficiently # expressive to represent this type, and Stainless isn't able to do anything # interesting with the `pattern` constraint. So the `oneOf` below causes # more trouble than it's worth. # # oneOf: # - const: string # title: string # description: A string. # - const: uint # title: uint # description: An unsigned integer. # - const: uuid # title: uuid # description: A UUID. # - const: bool # title: bool # description: A boolean. # - const: datetime # title: datetime # description: A date and time. # - const: "[]string" # title: "string_array" # description: An array of strings. # - const: "[]uint" # title: "uint_array" # description: An array of unsigned integers. # - const: "[]uuid" # title: "uuid_array" # description: An array of UUIDs. # - const: "[]datetime" # title: "datetime_array" # description: An array of date and time values. # - type: string # pattern: "^\\[\\d+\\]f(16|32)$" # title: "vector" # description: > # A vector embedding of a specific dimensionality and element width. CopyFromNamespaceConfig: type: object properties: source_namespace: type: string description: The namespace to copy documents from. source_api_key: type: string description: (Optional) An API key for the organization containing the source namespace source_region: type: string description: (Optional) The region of the source namespace. required: [ source_namespace ] CopyFromNamespaceParams: oneOf: - type: string description: The namespace to copy documents from. # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/CopyFromNamespaceConfig" } FullTextSearch: description: > Whether this attribute can be used as part of a BM25 full-text search. Requires the `string` or `[]string` type, and by default, BM25-enabled attributes are not filterable. You can override this by setting `filterable: true`. oneOf: - type: boolean # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/FullTextSearchConfig" } FullTextSearchConfig: description: Configuration options for full-text search. type: object properties: k1: type: number description: > The `k1` term saturation parameter for BM25. Defaults to `1.2`. b: type: number description: > The `b` document length normalization parameter for BM25. Defaults to `0.75`. language: { $ref: "#/components/schemas/Language" } stemming: type: boolean description: > Language-specific stemming for the text. Defaults to `false` (i.e., do not stem). remove_stopwords: type: boolean description: > Removes common words from the text based on language. Defaults to `true` (i.e. remove common words). ascii_folding: type: boolean description: > Whether to convert each non-ASCII character in a token to its ASCII equivalent, if one exists (e.g., à -> a). Defaults to `false` (i.e., no folding). case_sensitive: type: boolean description: > Whether searching is case-sensitive. Defaults to `false` (i.e. case-insensitive). max_token_length: type: integer description: > Maximum length of a token in bytes. Tokens larger than this value during tokenization will be filtered out. Has to be between `1` and `254` (inclusive). Defaults to `39`. tokenizer: { $ref: "#/components/schemas/Tokenizer" } Language: description: > Describes the language of a text attribute. Defaults to `english`. oneOf: - const: arabic - const: danish - const: dutch - const: english - const: finnish - const: french - const: german - const: greek - const: hungarian - const: italian - const: norwegian - const: portuguese - const: romanian - const: russian - const: spanish - const: swedish - const: tamil - const: turkish Tokenizer: description: The tokenizer to use for full-text search on an attribute. Defaults to `word_v4`. oneOf: - const: pre_tokenized_array - const: word_v0 - const: word_v1 - const: word_v2 - const: word_v3 - const: word_v4 Ann: description: > Whether to create an approximate nearest neighbor index for the attribute. Can be a boolean or a detailed configuration object. oneOf: - type: boolean # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/AnnConfig" } AnnConfig: description: Configuration options for ANN (Approximate Nearest Neighbor) indexing. type: object properties: distance_metric: { $ref: "#/components/schemas/DistanceMetric" } late_interaction: type: boolean description: > Opt in to late-interaction (MUVERA) indexing. Only valid on fixed-dim `[][N]f32` vector array attributes, and is required to enable an ANN index on such attributes. Defaults to `false`. AttributeEmbed: description: > Whether to automatically embed this string attribute into a vector attribute. Can be a model name, a detailed configuration object, or `null` to remove an existing embedding configuration. oneOf: - type: string description: > The model to use for embedding. If you only specify a model, turbopuffer will generate a vector attribute for you to store the embedding. # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/AttributeEmbedConfig" } - type: "null" description: Disable automatic embedding for this attribute. AttributeEmbedConfig: description: Configuration options for automatic embedding. type: object properties: attribute: type: string description: > The name of an existing vector attribute to store embeddings in. If omitted, turbopuffer will generate a computed vector attribute named `$embed_`. model: type: string description: > The model to use for embedding. See our documentation for a list of models supported in each region. dims: type: integer description: > The dimensionality to embed at. If not set, will pick the default for this model. If you're storing embeddings in an existing attribute, this can be omitted, and may not be set to a value other than the dimensions of that attribute. required: [ model ] SparseKnn: description: > Whether to create a sparse kNN index for the attribute. Requires the `{}f16` type. type: object properties: distance_metric: { $ref: "#/components/schemas/SparseDistanceMetric" } required: [ distance_metric ] SparseDistanceMetric: anyOf: - const: dot_product description: > Defined as `sum(x * y)`. Higher is better. description: A function used to calculate sparse vector similarity. Encryption: description: The encryption configuration for a namespace. oneOf: - type: object description: Encrypt the namespace with a customer-managed encryption key (CMEK). title: customer-managed properties: mode: const: customer-managed key_name: type: string description: > The identifier of the CMEK key to use for encryption. For GCP, the fully-qualified resource name of the key. For AWS, the ARN of the key. required: [ mode, key_name ] - type: object description: Use the default server-side encryption (SSE). title: default properties: mode: const: default required: [ mode ] PinningConfig: description: Configuration for namespace pinning. type: object properties: replicas: type: integer format: int64 minimum: 1 description: The number of read replicas to provision. Defaults to 1 if not specified. PinningConfigResponse: description: > Configuration for namespace pinning, along with the current status of the pinned namespace. allOf: - $ref: "#/components/schemas/PinningConfig" - type: object properties: status: $ref: "#/components/schemas/PinningStatus" PinningStatus: description: Operational status for a pinned namespace. type: object properties: updated_at: type: string format: date-time description: The timestamp of the latest pinning status snapshot. ready_replicas: type: integer format: int64 description: The number of replicas that are warm and serving traffic. replicas: type: integer format: int64 description: > The number of running replicas for the namespace. Replicas are billed once running, even before they finish warming their caches and become ready to serve traffic. This count is updated independently and may briefly disagree with the other status fields. utilization: type: number description: > Aggregate utilization for the pinned namespace, reported as a value between 0.0 and 1.0. required: [ updated_at, ready_replicas, replicas, utilization ] ShardingConfig: description: > Configuration for namespace sharding, which partitions a namespace's documents across multiple internal shards to scale indexing and query throughput beyond a single machine. Sharding can only be configured on a namespace's inaugural write, and cannot be added to or changed on an existing namespace. type: object properties: num_shards: type: integer format: int32 minimum: 1 description: The number of shards to partition the namespace into. required: [ num_shards ] ErrorResponse: description: The response to an unsuccessful request. type: object required: - status - error properties: status: const: "error" description: The status of the request. error: type: string description: The error message. # Not currently supported by Stainless, but used by custom codegen we've # added on top. AggregateBy: description: > An aggregate function to compute over all documents in the namespace. anyOf: - type: array description: Count documents. prefixItems: - const: Count additionalItems: false - type: array description: Sum the values of the given attribute. prefixItems: - const: Sum - type: string title: attr description: > The name of the attribute to sum (must be of numeric type). additionalItems: false - type: array description: Count documents with a non-null value for the given attribute. prefixItems: - const: Count - type: string title: attr description: > The name of the attribute to count (only documents with non-null values for the attribute are counted). DEPRECATED. Use `Count` instead. x-turbopuffer-variant-name: CountDeprecated # Drop this variant if it conflicts with the `Count` variant. This # means the deprecation will be backwards incompatible in the SDKs # where it conflicts, but that's a price we're willing to pay. x-turbopuffer-variant-drop-on-conflict: true additionalItems: false GroupBy: description: Specifies a value to group documents by. anyOf: - description: An attribute name to group documents by. type: string x-turbopuffer-variant-name: Attr - description: > An expression to group documents by, with an explicit output attribute name. type: object x-turbopuffer-variant-name: Expr additionalProperties: $ref: "#/components/schemas/GroupByFunction" GroupByFunction: description: A function that produces group keys. anyOf: - description: > Use the `ForEachUnique` operator to explode an array attribute when grouping. Each unique element of the array becomes a separate group. type: array prefixItems: - const: ForEachUnique - type: string title: attr description: The name of the array attribute to explode. additionalItems: false Expr: description: An expression that computes a value. anyOf: - { $ref: "#/components/schemas/ExprRefNew" } - type: array description: > Embed the input text using the embedding model configured for the attribute the expression is evaluated against. prefixItems: - const: Embed - type: string title: value description: The input text to embed. additionalItems: false x-turbopuffer-variant-name: Embed - type: array description: > Embed the input text using the specified embedding model, overriding the model configured for the attribute the expression is evaluated against. prefixItems: - const: Embed - type: string title: value description: The input text to embed. - $ref: "#/components/schemas/EmbedParams" title: params additionalItems: false x-turbopuffer-variant-name: EmbedWithParams - { $ref: "#/components/schemas/ExprVectorDist" } - { $ref: "#/components/schemas/ExprHighlight" } - { $ref: "#/components/schemas/ExprHighlightWithConfig" } - $ref: "#/components/schemas/RankBy" title: Score EmbedParams: description: Additional (optional) parameters for the Embed expression. type: object properties: model: type: string description: > The model to use for embedding, overriding the model configured for the attribute. additionalProperties: false ExprRefNew: description: A reference to an attribute in a new document. type: object properties: $ref_new: description: The name of the attribute referenced in the new document. type: string title: attr required: [ $ref_new ] Bm25ClauseParams: # Can't start with 'RankBy', otherwise apigen will handle this description: Additional (optional) parameters for a single BM25 query clause. type: object properties: last_as_prefix: type: boolean description: Whether to treat the last token in the query input as a literal prefix. additionalProperties: false BranchFromNamespaceConfig: type: object properties: source_namespace: type: string description: The namespace to create an instant, copy-on-write clone of. required: [ source_namespace ] BranchFromNamespaceParams: oneOf: - type: string description: The namespace to create an instant, copy-on-write clone of. # Since Go doesn't support sum types, this syntax sugar is actually # an ergonomic loss. So just force Go users to always use the full # config by omitting this variant. x-stainless-skip: [ go ] - { $ref: "#/components/schemas/BranchFromNamespaceConfig" } ContainsAllTokensFilterParams: # Can't start with 'Filter', otherwise apigen will handle this description: Additional (optional) parameters for the ContainsAllTokens filter. type: object properties: last_as_prefix: type: boolean description: Whether to treat the last token in the query input as a literal prefix. additionalProperties: false ContainsAnyTokenFilterParams: # Can't start with 'Filter', otherwise apigen will handle this description: Additional (optional) parameters for the ContainsAnyToken filter. type: object properties: last_as_prefix: type: boolean description: Whether to treat the last token in the query input as a literal prefix. additionalProperties: false FuzzyMaxEditDistance: description: An edit distance threshold for the Fuzzy filter. type: object properties: min_query_chars: type: integer description: > Minimum number of characters in a query where this distance applies. Must be at least 3 · (distance + 1). distance: type: integer minimum: 0 maximum: 2 description: The maximum edit distance to allow. required: [ min_query_chars, distance ] additionalProperties: false FuzzyParams: description: Additional parameters for the Fuzzy filter. type: object properties: max_edit_distance: type: array minItems: 1 description: > Maximum edit distance allowed at each query length. Queries shorter than the first threshold return no matches. items: { $ref: "#/components/schemas/FuzzyMaxEditDistance" } case_sensitive: type: boolean description: > Whether searching with Fuzzy filter is case-sensitive. Defaults to `true` (i.e. case-sensitive). required: [ max_edit_distance ] additionalProperties: false SaturateParams: description: Additional parameters for the Saturate operator. type: object properties: midpoint: x-stainless-any: true description: The midpoint of the Saturate operator. exponent: type: number description: An exponent that helps further control the shape of the Saturate function. additionalProperties: false DecayParams: description: Additional parameters for the Decay operator. type: object properties: midpoint: x-stainless-any: true description: The midpoint of the Decay operator. exponent: type: number description: An exponent that helps further control the shape of the Decay function. additionalProperties: false Filter: anyOf: - type: array description: > Exact match for attribute value. If `null`, matches documents missing the attribute. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Eq - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Inverse of `Eq`. If value is `null`, matches documents with the attribute. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotEq - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Matches any attribute value contained in the provided list. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: In - type: array title: value description: The value of the filter. items: { x-stainless-any: true } additionalItems: false - type: array description: > Inverse of `In`, matches any attributes values not contained in the provided list. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotIn - type: array title: value description: The value of the filter. items: { x-stainless-any: true } additionalItems: false - type: array description: > Checks whether the selected array attribute contains the provided value. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Contains - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Inverse of Contains prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotContains - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Checks whether the selected array attribute contains any of the values provided (intersection filter). prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAny - type: array title: value description: The value of the filter. items: { x-stainless-any: true } additionalItems: false - type: array description: > Inverse of ContainsAny. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotContainsAny - type: array title: value description: The value of the filter. items: { x-stainless-any: true } additionalItems: false - type: array description: > For ints, this is a numeric less-than. For strings, lexicographic less-than. For datetimes, numeric less-than on millisecond representation. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Lt - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > For ints, this is a numeric less-than-or-equal. For strings, lexicographic less-than-or-equal. For datetimes, numeric less-than-or-equal on millisecond representation. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Lte - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > For ints, this is a numeric greater-than. For strings, lexicographic greater-than. For datetimes, numeric greater-than on millisecond representation. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Gt - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > For ints, this is a numeric greater-than-or-equal. For strings, lexicographic greater-than-or-equal. For datetimes, numeric greater-than-or-equal on millisecond representation. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Gte - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Checks whether any element of an array attribute is less than the provided value, using the same rules as `Lt`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: AnyLt - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Checks whether any element of an array attribute is less than or equal to the provided value, using the same rules as `Lte`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: AnyLte - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Checks whether any element of an array attribute is greater than the provided value, using the same rules as `Gt`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: AnyGt - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Checks whether any element of an array attribute is greater than or equal to the provided value, using the same rules as `Gte`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: AnyGte - x-stainless-any: true title: value description: The value of the filter. additionalItems: false - type: array description: > Unix-style glob match against string values. The full syntax is described in the Rust `globset` crate documentation. Glob patterns with a concrete prefix like "foo*" internally compile to efficient range queries. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Glob - type: string title: value description: The value of the filter. additionalItems: false - type: array description: > Inverse of `Glob`, Unix-style glob filters against string attributes values. The full syntax is described in the Rust `globset` crate documentation. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotGlob - type: string title: value description: The value of the filter. additionalItems: false - type: array description: > Case insensitive version of `Glob`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: IGlob - type: string title: value description: The value of the filter. additionalItems: false - type: array description: > Case insensitive version of `NotGlob`. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: NotIGlob - type: string title: value description: The value of the filter. additionalItems: false - type: array description: > Regular expression match against string values. Requires the regex schema attribute to be enabled before use. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Regex - type: string title: value description: The regular expression to match against. additionalItems: false - type: array description: > Fuzzy substring match against string values. Requires the fuzzy schema attribute to be enabled before use. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: Fuzzy - type: string title: value description: The string to fuzzy-match against. - $ref: "#/components/schemas/FuzzyParams" title: params additionalItems: false - type: array description: > Matches if all tokens in the input string are present in the attributes value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAllTokens - type: string title: value description: The string to search for. additionalItems: false - type: array description: > Matches if all tokens in the input string are present in the attributes value. Requires that the attribute is configured for full-text search. prefixItems: - type: string description: The name of the attribute to apply the filter to. title: attr - const: ContainsAllTokens - type: array items: { type: string } title: value description: The tokens to search for. additionalItems: false x-turbopuffer-variant-name: ContainsAllTokensArray - type: array description: > Matches if all tokens in the input string are present in the attributes value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAllTokens - type: string title: value description: The string to search for. - $ref: "#/components/schemas/ContainsAllTokensFilterParams" title: params additionalItems: false x-turbopuffer-variant-name: ContainsAllTokensWithParams - type: array description: > Matches if all tokens in the input string are present in the attributes value. Requires that the attribute is configured for full-text search. prefixItems: - type: string description: The name of the attribute to apply the filter to. title: attr - const: ContainsAllTokens - type: array items: { type: string } title: value description: The tokens to search for. - $ref: "#/components/schemas/ContainsAllTokensFilterParams" title: params additionalItems: false x-turbopuffer-variant-name: ContainsAllTokensArrayWithParams - type: array description: > Matches if any of the tokens in the input string are present in the attribute value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAnyToken - type: string title: value description: The string to search for. additionalItems: false - type: array description: > Matches if any of the tokens in the input string array are present in the attribute value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAnyToken - type: array items: { type: string } title: value description: The tokens to search for. additionalItems: false x-turbopuffer-variant-name: ContainsAnyTokenArray - type: array description: > Matches if any of the tokens in the input string are present in the attribute value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAnyToken - type: string title: value description: The string to search for. - $ref: "#/components/schemas/ContainsAnyTokenFilterParams" title: params additionalItems: false x-turbopuffer-variant-name: ContainsAnyTokenWithParams - type: array description: > Matches if any of the tokens in the input string array are present in the attribute value. Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsAnyToken - type: array items: { type: string } title: value description: The tokens to search for. - $ref: "#/components/schemas/ContainsAnyTokenFilterParams" title: params additionalItems: false x-turbopuffer-variant-name: ContainsAnyTokenArrayWithParams - type: array description: > Matches if all the tokens in the input string are present in the attribute value, in the correct order (i.e., as a phrase). Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsTokenSequence - type: string title: value description: The string to search for. additionalItems: false - type: array description: > Matches if all the tokens in the input string are present in the attribute value, in the correct order (i.e., as a phrase). Requires that the attribute is configured for full-text search. prefixItems: - type: string title: attr description: The name of the attribute to apply the filter to. - const: ContainsTokenSequence - type: array items: { type: string } title: value description: The tokens to search for. additionalItems: false x-turbopuffer-variant-name: ContainsTokenSequenceArray - type: array prefixItems: - const: Not - $ref: "#/components/schemas/Filter" title: filter additionalItems: false - type: array prefixItems: - const: And - type: array items: { $ref: "#/components/schemas/Filter" } title: filters additionalItems: false - type: array prefixItems: - const: Or - type: array items: { $ref: "#/components/schemas/Filter" } title: filters additionalItems: false RankByAnn: type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: ANN - type: array items: type: number x-turbopuffer-width: 32 title: value additionalItems: false RankByAnnMulti: type: array prefixItems: - type: string title: attr description: The name of the vector array attribute to rank by. - const: ANN - type: array items: type: array items: type: number x-turbopuffer-width: 32 title: value additionalItems: false RankByAnnExpr: type: array prefixItems: - type: string title: attr description: The name of the embedded attribute to rank by. - const: ANN - $ref: "#/components/schemas/Expr" title: expr additionalItems: false RankByKnn: type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: kNN - type: array items: type: number x-turbopuffer-width: 32 title: value additionalItems: false RankByKnnMulti: type: array prefixItems: - type: string title: attr description: The name of the vector array attribute to rank by. - const: kNN - type: array items: type: array items: type: number x-turbopuffer-width: 32 title: value additionalItems: false RankByKnnExpr: type: array prefixItems: - type: string title: attr description: The name of the embedded attribute to rank by. - const: kNN - $ref: "#/components/schemas/Expr" title: expr additionalItems: false RankBySparseKnn: type: array prefixItems: - type: string title: attr description: The name of the sparse vector attribute to rank by. - const: SparseKNN - type: object description: > A sparse vector represented as a map from string dimension names to float weights. For example: `{"token_a": 0.5, "token_b": 1.2}`. title: value additionalProperties: type: number additionalItems: false RankByText: anyOf: - type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: BM25 - type: string description: The string to search for. title: value additionalItems: false - type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: BM25 - type: array items: { type: string } title: value description: The tokens to search for. additionalItems: false x-turbopuffer-variant-name: BM25Array - type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: BM25 - type: string description: The string to search for. title: value - $ref: "#/components/schemas/Bm25ClauseParams" title: params additionalItems: false x-turbopuffer-variant-name: BM25WithParams - type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - const: BM25 - type: array items: { type: string } title: value description: The tokens to search for. - $ref: "#/components/schemas/Bm25ClauseParams" title: params additionalItems: false x-turbopuffer-variant-name: BM25ArrayWithParams - type: array prefixItems: - const: Sum - type: array items: { $ref: "#/components/schemas/RankByText" } title: subqueries additionalItems: false - type: array prefixItems: - const: Max - type: array items: { $ref: "#/components/schemas/RankByText" } title: subqueries additionalItems: false - type: array prefixItems: - const: Product - type: number title: weight description: The weight of the attribute. - $ref: "#/components/schemas/RankByText" title: subquery additionalItems: false - type: array prefixItems: - const: Product - $ref: "#/components/schemas/RankByText" title: subquery - type: number title: weight description: The weight of the attribute. additionalItems: false x-turbopuffer-variant-drop-on-conflict: true - $ref: "#/components/schemas/Filter" - type: array prefixItems: - const: Attribute - type: string title: attr description: the name of the attribute to rank by additionalItems: false - type: array prefixItems: - const: Saturate - $ref: "#/components/schemas/RankByText" title: subquery - $ref: "#/components/schemas/SaturateParams" title: params additionalItems: false - type: array prefixItems: - const: Decay - $ref: "#/components/schemas/RankByText" title: subquery - $ref: "#/components/schemas/DecayParams" title: params additionalItems: false - type: array prefixItems: - const: Dist - $ref: "#/components/schemas/RankByText" title: subquery - x-stainless-any: true title: origin additionalItems: false RankByAttributeOrder: anyOf: - const: asc description: Ascending order. - const: desc description: Descending order. RankByAttribute: type: array prefixItems: - type: string title: attr description: The name of the attribute to rank by. - $ref: "#/components/schemas/RankByAttributeOrder" title: order additionalItems: false RankByAttributes: type: array items: { $ref: "#/components/schemas/RankByAttribute" } description: > Order by multiple attributes. Results are sorted by the first attribute, then by the second attribute for ties, and so on. RankBy: anyOf: - { $ref: "#/components/schemas/RankByAnn" } - { $ref: "#/components/schemas/RankByAnnMulti" } - { $ref: "#/components/schemas/RankByAnnExpr" } - { $ref: "#/components/schemas/RankByKnn" } - { $ref: "#/components/schemas/RankByKnnMulti" } - { $ref: "#/components/schemas/RankByKnnExpr" } - { $ref: "#/components/schemas/RankBySparseKnn" } - { $ref: "#/components/schemas/RankByText" } - { $ref: "#/components/schemas/RankByAttribute" } - { $ref: "#/components/schemas/RankByAttributes" } RrfParams: description: Configuration options for RRF. type: object properties: rank_constant: type: integer description: > RRF rank constant (`k`). Must be greater than zero. Defaults to `60`. weights: type: array description: > A positive weight for each subquery, in the same order as `queries`. The number of weights must match the number of subqueries. When omitted, every subquery has a weight of `1`. items: type: number format: float exclusiveMinimum: 0 additionalProperties: false RerankBy: description: > Configuration for combining the rows returned by a multi-query into a single ranked list. anyOf: - type: array description: Rerank with RRF. prefixItems: - const: RRF additionalItems: false - type: array description: Rerank with RRF. prefixItems: - const: RRF - $ref: "#/components/schemas/RrfParams" additionalItems: false x-turbopuffer-variant-name: RrfWithParams ExprVectorDist: type: array description: The distance between a vector attribute and a query vector. prefixItems: - type: string title: attr description: The name of the vector attribute. - const: VectorDist - type: array items: type: number x-turbopuffer-width: 32 title: value additionalItems: false ExprHighlight: type: array description: Highlights matching fragments of a text attribute. prefixItems: - const: Highlight - type: string title: attr description: The name of the text attribute to highlight. additionalItems: false ExprHighlightWithConfig: type: array description: > Highlights matching fragments of a text attribute, with additional configuration. prefixItems: - const: Highlight - type: string title: attr description: The name of the text attribute to highlight. - $ref: "#/components/schemas/HighlightConfigParams" title: config additionalItems: false HighlightConfigParams: description: Additional (optional) parameters for the Highlight compute expression. type: object properties: rank_fragments_by: description: > How to rank candidate fragments within the attribute before selecting the top `fragment_limit`. Defaults to the query's `rank_by`. x-stainless-any: true fragment_by: { $ref: "#/components/schemas/HighlightFragmentBy" } fragment_limit: type: integer description: The maximum number of fragments to return. Defaults to `3`. include_offsets: { $ref: "#/components/schemas/HighlightOffsetUnits" } additionalProperties: false HighlightFragmentBy: description: How to split a text attribute into fragments for highlighting. anyOf: - const: none description: Treat the whole attribute as a single fragment. - const: sentence description: Split the attribute into sentences. This is the default. - const: paragraph description: Split the attribute into paragraphs. - const: word description: Split the attribute into individual words. HighlightOffsetUnits: description: The units to report highlighted fragment offsets in. anyOf: - const: utf-8 - const: utf-16 - const: codepoints HighlightMatch: description: > A single matched fragment for a `Highlight` compute attribute. A `Highlight` compute attribute's value in the response is an array of these objects, one per matching fragment. type: object properties: text: type: string description: The text of the matched fragment. fragment_range: description: > The `[start, end]` offset of this fragment within the original attribute value, in the units requested by `include_offsets`. Omitted if `include_offsets` was not set. type: array items: { type: integer } minItems: 2 maxItems: 2 match_ranges: description: > The `[start, end]` offsets of matched spans within `text`, in the units requested by `include_offsets`. Omitted if `include_offsets` was not set. type: array items: type: array items: { type: integer } minItems: 2 maxItems: 2 array_index: description: > The index into the array, if the highlighted attribute is an array of strings. Omitted for non-array attributes. type: integer required: [ text ] securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: API key