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
                    description: A message describing the result of the request.
                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
                  minimum: 0
                  description: The number of searches to run.
                top_k:
                  type: integer
                  minimum: 0
                  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
                      description: >
                        One of the searches the evaluation ran: its query vector,
                        sampled at random from the namespace's vectors unless
                        `rank_by` is set, and the query's true nearest neighbors,
                        found by exhaustive search. Recall compares these
                        neighbors to the results of the approximate nearest
                        neighbor (ANN) search.
                      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" }
                - type: object
                  properties:
                    rerank_by: { $ref: "#/components/schemas/RerankModelParams" }

      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.
                      anyOf:
                        - type: integer
                          description: Limits the total number of reranked documents returned.
                          minimum: 0
                          # 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/RerankLimit" }
                    offset:
                      description: Number of reranked documents to skip before returning results. Requires `rerank_by` and `limit`.
                      type: integer
                      minimum: 0
      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: { $ref: "#/components/schemas/CopyFromNamespaceRequest" }
      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}/async?stainless_overload=startCopyFrom:
    post:
      description: >
        Start copying all documents from another namespace into this one.
        Returns an operation token without waiting for the copy to finish.
        Use the token to poll for progress and the result.
      parameters:
        - { $ref: "#/components/parameters/namespace" }
      requestBody:
        content:
          application/json:
            schema: { $ref: "#/components/schemas/CopyFromNamespaceRequest" }
      responses:
        "202":
          description: The copy was accepted for asynchronous execution.
          headers:
            Location:
              description: The URL at which to poll the operation status.
              schema: { type: string }
          content:
            application/json:
              schema:
                type: object
                required: [ token ]
                description: The response to a successful request to start a copy.
                properties:
                  token:
                    type: string
                    description: The token identifying the copy operation.
        default:
          description: An error response.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/ErrorResponse" }

  /v1/namespaces/{namespace}/operations/{token}?stainless_overload=pollCopyFrom:
    get:
      description: Retrieve the current status of a copy operation.
      parameters:
        - { $ref: "#/components/parameters/namespace" }
        - name: token
          in: path
          required: true
          description: The operation token obtained when starting the copy.
          schema: { type: string }
      responses:
        "200":
          description: The current status of the copy operation.
          content:
            application/json:
              schema: { $ref: "#/components/schemas/CopyFromNamespaceOperation" }
        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
          minimum: 0
          format: int64
          description: The approximate number of rows in the namespace.
        approx_logical_bytes:
          type: integer
          minimum: 0
          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:
          description: The state of the namespace's index.
          oneOf:
            - type: object
              title: index-up-to-date
              description: Every document in the namespace is indexed.
              properties:
                status:
                  const: up-to-date
              required: [ status ]
            - type: object
              title: index-updating
              description: Some documents are in the write-ahead log and haven't been indexed yet.
              properties:
                status:
                  const: updating
                unindexed_bytes:
                  type: integer
                  minimum: 0
                  description: The number of bytes in the namespace that are in the write-ahead log but have not yet been indexed.
                unindexed_rows:
                  type: integer
                  minimum: 0
                  description: The number of rows in the write-ahead log that have not yet been indexed.
              required: [ status, unindexed_bytes, unindexed_rows ]
        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
              description: >
                `true` to enable pinning with the default configuration, or `false`
                to remove pinning.
              # 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.
        create_namespace:
          type: boolean
          description: >
            If `true`, ensures the namespace is created, even if the request
            writes no documents. Creating an empty namespace requires the `id`
            type to be declared in `schema`. If `false`, a namespace is never
            created, and a 404 is returned if it does not exist. If omitted, a
            namespace is created by the first request that writes documents.
    PatchByFilter:
      description: Sets the attributes in `patch` on every document that matches `filters`.
      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
          minimum: 0
          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
          minimum: 0
          description: Request time measured on the server, in milliseconds.
        embedding_tokens:
          type: integer
          minimum: 0
          description: >
            The number of tokens embedded. Only set when using a native embedding model.
        embedding_ms:
          type: integer
          minimum: 0
          description: >
            Time spent embedding text, in milliseconds. Only set when using a native embedding model.
      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
          minimum: 0
          description: The number of rows affected by the write request.
        rows_upserted:
          type: integer
          minimum: 0
          description: The number of rows upserted by the write request.
        rows_patched:
          type: integer
          minimum: 0
          description: The number of rows patched by the write request.
        rows_deleted:
          type: integer
          minimum: 0
          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
          minimum: 0
        offset:
          description: >
            Number of documents to skip before returning results. Supported only
            in v2 queries with an explicit `rank_by` and `top_k` or `limit`.
          type: integer
          minimum: 0
        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
              minimum: 0
              # 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.
          discriminator:
            propertyName: level
          oneOf:
            - type: object
              title: strong
              description: >
                Strong consistency. Requires a round-trip to object storage
                to fetch the latest writes.
              additionalProperties: false
              required: [ level ]
              properties:
                level:
                  const: strong
            - type: object
              title: eventual
              description: >
                Eventual consistency. Does not require a round-trip to
                object storage, but may not see the latest writes.
              required: [ level ]
              properties:
                level:
                  const: eventual
                max_staleness_seconds:
                  type: integer
                  minimum: 1
                  maximum: 3600
                  description: >
                    How long the query may reuse the node's cached view of the
                    namespace before refreshing it from object storage.
                    Defaults to 60.
    RerankLimit:
      description: Limits the total number of reranked documents returned.
      type: object
      additionalProperties: false
      properties:
        total:
          description: Limits the total number of documents returned after reranking.
          type: integer
          minimum: 0
      required: [ total ]
    QueryBilling:
      description: The billing information for a query.
      type: object
      properties:
        billable_logical_bytes_queried:
          type: integer
          minimum: 0
          description: The number of billable logical bytes queried from the namespace.
        billable_logical_bytes_returned:
          type: integer
          minimum: 0
          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
          minimum: 0
          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
          minimum: 0
          description: >
            Request time measured on the server, excluding time spent waiting due to the namespace concurrency limit.
        exhaustive_search_count:
          type: integer
          minimum: 0
          description: The number of unindexed documents processed by the query.
        approx_namespace_size:
          type: integer
          minimum: 0
          description: the approximate number of documents in the namespace.
        embedding_tokens:
          type: integer
          minimum: 0
          description: >
            The number of tokens embedded. Only set when using a native embedding model.
        embedding_ms:
          type: integer
          minimum: 0
          description: >
            Time spent embedding text, in milliseconds. Only set when using a native embedding model.
      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. With `aggregate_by`, `aggregations` maps each
        aggregation's label to its value. With `group_by` as well,
        `aggregation_groups` holds one object per group instead, with its group
        key and the value of each aggregation.
      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" }
          description: >
            The results of each subquery, in the same order as `queries`. With
            `rerank_by`, a single result combining the subqueries' rows.
        performance: { $ref: "#/components/schemas/QueryPerformance" }
        billing: { $ref: "#/components/schemas/QueryBilling" }
      required: [ performance, billing, results ]
    SingleQueryResult:
      description: >
        The result of a query, or of one subquery of a multi-query. With
        `aggregate_by`, `aggregations` maps each aggregation's label to its
        value. With `group_by` as well, `aggregation_groups` holds one object
        per group instead, with its group key and the value of each
        aggregation.
      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" }
          description: >
            The documents that matched the query, ordered by `rank_by`. Only
            present when `rank_by` is set.
    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 unsigned 64-bit integer ID.
          type: integer
          minimum: 0
      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
          minimum: 0
        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
              minimum: 0
          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" }
        - { $ref: "#/components/schemas/AttributeSchemaDrop" }
    AttributeSchemaDrop:
      description: >
        Drops the attribute from the namespace. Cannot be combined with other
        schema settings.
      type: object
      properties:
        drop:
          description: Must be `true`.
          type: boolean
      required: [ drop ]
    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.
    CopyFromNamespaceOperation:
      description: The current status of a copy operation.
      discriminator:
        propertyName: status
      oneOf:
        - type: object
          title: running
          description: The copy is still in progress.
          required: [ status, start_time ]
          properties:
            status:
              const: running
            start_time:
              type: string
              format: date-time
              description: The time at which the operation started.
            progress:
              type: string
              description: >
                A freeform description of the operation's progress.
                May be absent, and its format may change.
        - type: object
          title: finished
          description: The copy has finished, successfully or not.
          required: [ status, start_time, finish_time, result ]
          properties:
            status:
              const: finished
            start_time:
              type: string
              format: date-time
              description: The time at which the operation started.
            finish_time:
              type: string
              format: date-time
              description: The time at which the operation finished.
            result:
              $ref: "#/components/schemas/CopyFromNamespaceOperationResult"
              description: The result of the copy.
    CopyFromNamespaceOperationResult:
      description: The result of a finished copy operation.
      oneOf:
        - type: object
          title: success
          required: [ success ]
          properties:
            success:
              allOf:
                - $ref: "#/components/schemas/WriteResult"
              description: The copy succeeded, with the result of its write.
        - type: object
          title: error
          required: [ error ]
          properties:
            error:
              $ref: "#/components/schemas/OperationError"
              description: The copy failed, with its error.
    OperationError:
      type: object
      description: The error of an asynchronous operation that failed.
      required: [ status_code, detail ]
      properties:
        status_code:
          type: integer
          minimum: 0
          description: The HTTP status code of the operation's error.
        detail:
          $ref: "#/components/schemas/ErrorResponse"
    CopyFromNamespaceRequest:
      allOf:
        - { $ref: "#/components/schemas/CopyFromNamespaceConfig" }
        - type: object
          properties:
            dest_encryption:
              description: >
                (Optional) The encryption configuration for the
                destination namespace.
              $ref: "#/components/schemas/Encryption"
    CopyFromNamespaceConfig:
      type: object
      description: Configuration for copying documents from another namespace.
      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
          description: Whether to enable full-text search with the default configuration.
          # 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
          minimum: 0
          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
          description: Whether to create an ANN index with the default configuration.
          # 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_<attribute>`.
        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
          minimum: 0
          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.
            encryption_context:
              type: object
              additionalProperties: { type: string }
              description: >
                The AWS KMS encryption context to send with every request that
                uses the key. Only supported on AWS, and must be enabled for
                your organization. Keys may not start with `tpuf:` or `aws:`.
          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
          minimum: 0
          format: int64
          description: The number of replicas that are warm and serving traffic.
        replicas:
          type: integer
          minimum: 0
          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
          description: >
            The score of a ranking function, e.g. to return the score of one clause
            of a composite `rank_by`.
    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
      description: Configuration for branching from another namespace.
      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
          minimum: 0
          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
          description: Matches documents that don't match the filter.
          prefixItems:
            - const: Not
            - $ref: "#/components/schemas/Filter"
              title: filter
              description: The filter to negate.
          additionalItems: false
        - type: array
          description: Matches documents that match all of the filters.
          prefixItems:
            - const: And
            - type: array
              items: { $ref: "#/components/schemas/Filter" }
              title: filters
              description: The filters to combine.
          additionalItems: false
        - type: array
          description: Matches documents that match at least one of the filters.
          prefixItems:
            - const: Or
            - type: array
              items: { $ref: "#/components/schemas/Filter" }
              title: filters
              description: The filters to combine.
          additionalItems: false
    RankByAnn:
      type: array
      description: >
        Rank by approximate nearest neighbor (ANN) search, ordering documents by
        the distance between their vector and the query vector, closest first.
      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
          description: The query vector.
      additionalItems: false
    RankByAnnMulti:
      type: array
      description: >
        Rank by approximate nearest neighbor (ANN) search with late interaction.
        A document's distance is the sum of the distances from each query vector
        to its closest vector in the document's vector 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
          description: The query vectors, e.g. one per query token.
      additionalItems: false
    RankByAnnExpr:
      type: array
      description: >
        Rank by approximate nearest neighbor (ANN) search, with the query vector
        computed by an expression, e.g. by embedding text with `Embed`.
      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
      description: >
        Rank by exact nearest neighbor (kNN) search, ordering documents by the
        distance between their vector and the query vector, closest first.
        Requires `filters`.
      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
          description: The query vector.
      additionalItems: false
    RankByKnnMulti:
      type: array
      description: >
        Rank by exact nearest neighbor (kNN) search with late interaction. A
        document's distance is the sum of the distances from each query vector
        to its closest vector in the document's vector 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
          description: The query vectors, e.g. one per query token.
      additionalItems: false
    RankByKnnExpr:
      type: array
      description: >
        Rank by exact nearest neighbor (kNN) search, with the query vector
        computed by an expression, e.g. by embedding text with `Embed`. Requires
        `filters`.
      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
      description: >
        Rank by the distance between a sparse vector attribute and a sparse
        query vector.
      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:
      description: >
        Rank by BM25 (Best Matching 25, a classic full-text search scoring function,
        which scores documents higher when they contain more of the query's terms,
        especially rare ones), or by combining scores with operators like `Sum`,
        `Max`, and `Product`.
      anyOf:
        - type: array
          description: >
            Rank by how relevant an attribute is to a query string, using BM25 (Best
            Matching 25, a classic full-text search scoring function, which scores
            documents higher when they contain more of the query's terms, especially
            rare ones).
          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
          description: >
            Rank by how relevant an attribute is to a list of query tokens, using
            BM25 (Best Matching 25, a classic full-text search scoring function,
            which scores documents higher when they contain more of the query's
            terms, especially rare ones).
          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
          description: >
            Rank by how relevant an attribute is to a query string, using BM25 (Best
            Matching 25, a classic full-text search scoring function, which scores
            documents higher when they contain more of the query's terms, especially
            rare ones), with additional parameters.
          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
          description: >
            Rank by how relevant an attribute is to a list of query tokens, using
            BM25 (Best Matching 25, a classic full-text search scoring function,
            which scores documents higher when they contain more of the query's
            terms, especially rare ones), with additional parameters.
          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
          description: Sum the scores of the subqueries.
          prefixItems:
            - const: Sum
            - type: array
              items: { $ref: "#/components/schemas/RankByText" }
              title: subqueries
              description: The subqueries whose scores to sum.
          additionalItems: false
        - type: array
          description: Use the highest score of the subqueries.
          prefixItems:
            - const: Max
            - type: array
              items: { $ref: "#/components/schemas/RankByText" }
              title: subqueries
              description: The subqueries whose highest score to use.
          additionalItems: false
        - type: array
          description: >
            Multiply a subquery's score by a non-negative weight, e.g. to boost one
            attribute over others.
          prefixItems:
            - const: Product
            - type: number
              title: weight
              description: The weight of the attribute.
            - $ref: "#/components/schemas/RankByText"
              title: subquery
              description: The subquery whose score to multiply.
          additionalItems: false
        - type: array
          description: >
            Multiply a subquery's score by a non-negative weight, e.g. to boost one
            attribute over others.
          prefixItems:
            - const: Product
            - $ref: "#/components/schemas/RankByText"
              title: subquery
              description: The subquery whose score to multiply.
            - type: number
              title: weight
              description: The weight of the attribute.
          additionalItems: false
          x-turbopuffer-variant-drop-on-conflict: true
        - $ref: "#/components/schemas/Filter"
          description: >
            Score documents that match a filter 1, and other documents 0, e.g. to
            boost documents that match some criteria.

        - type: array
          description: >
            Use the value of a numeric attribute as the score. Attributes of signed
            types, like `int` and `float`, must be wrapped in `Max` or `Saturate`,
            since scores can't be negative.
          prefixItems:
            - const: Attribute
            - type: string
              title: attr
              description: The name of the attribute to rank by.
          additionalItems: false
        - type: array
          description: >
            Map a non-negative score into `[0, 1)` with `x^exponent / (x^exponent +
            midpoint^exponent)`, e.g. to combine an attribute's value with scores
            from BM25 (Best Matching 25, a classic full-text search scoring
            function, which scores documents higher when they contain more of the
            query's terms, especially rare ones).
          prefixItems:
            - const: Saturate
            - $ref: "#/components/schemas/RankByText"
              title: subquery
              description: The subquery whose score to saturate.
            - $ref: "#/components/schemas/SaturateParams"
              title: params
          additionalItems: false
        - type: array
          description: >
            Map a non-negative score into `(0, 1]` with `midpoint^exponent /
            (x^exponent + midpoint^exponent)`, the inverse of `Saturate`, e.g. for
            an attribute whose higher values make documents less relevant.
          prefixItems:
            - const: Decay
            - $ref: "#/components/schemas/RankByText"
              title: subquery
              description: The subquery whose score to decay.
            - $ref: "#/components/schemas/DecayParams"
              title: params
          additionalItems: false
        - type: array
          description: >
            The distance between a subquery's value and an origin, e.g. to boost
            recent documents by passing the distance from now to `Decay`.
          prefixItems:
            - const: Dist
            - $ref: "#/components/schemas/RankByText"
              title: subquery
              description: >
                The subquery whose distance from `origin` to compute, e.g. an
                `Attribute`.
            - x-stainless-any: true
              title: origin
              description: The value to compute the distance from, e.g. a timestamp.
          additionalItems: false
    RankByAttributeOrder:
      anyOf:
        - const: asc
          description: Ascending order.
        - const: desc
          description: Descending order.
    RankByAttribute:
      type: array
      description: Order documents by the value of an attribute, like SQL's `ORDER BY`.
      prefixItems:
        - type: string
          title: attr
          description: The name of the attribute to rank by.
        - $ref: "#/components/schemas/RankByAttributeOrder"
          title: order
          description: The direction to order in.
      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:
      description: >
        How to rank documents: by vector distance, full-text search relevance,
        or the value of an attribute.
      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
          minimum: 1
          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
    RerankModelParams:
      description: Rerank retrieved candidates with a model.
      type: object
      properties:
        model:
          type: string
          description: Which reranking model to use.
        attribute:
          type: string
          description: >
            The string attribute to score. Must be included in `include_attributes`
            in every query.
        query:
          type: string
          description: The query text to score each document against.
      required: [ model, attribute, query ]
      additionalProperties: false
    RerankBy:
      description: >
        Configuration for combining the rows returned by a multi-query into a
        single ranked list, using RRF or a reranking model.
      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
        - $ref: "#/components/schemas/RerankModelParams"
          x-turbopuffer-variant-name: Model
    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
          description: The query vector.
      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
          minimum: 0
          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, minimum: 0 }
          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, minimum: 0 }
            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
          minimum: 0
      required: [ text ]

  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API key