turbopuffer 2.3.0 → 2.5.0

data/rbi/turbopuffer/models/namespace_metadata_patch.rbi

@@ -20,11 +20,20 @@ module Turbopuffer
       sig { returns(T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig))) }
       attr_accessor :pinning
 
+      # 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.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :read_only
+
+      sig { params(read_only: T::Boolean).void }
+      attr_writer :read_only
+
       # Request to update namespace metadata configuration.
       sig do
         params(
           pinning:
-            T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig::OrHash))
+            T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig::OrHash)),
+          read_only: T::Boolean
         ).returns(T.attached_class)
       end
       def self.new(
@@ -34,13 +43,19 @@ module Turbopuffer
         # - `null` or `false`: explicitly remove pinning
         # - `true`: enable pinning with default configuration
         # - Object: set pinning configuration
-        pinning: nil
+        pinning: nil,
+        # 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.
+        read_only: nil
       )
       end
 
       sig do
         override.returns(
-          { pinning: T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig)) }
+          {
+            pinning: T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig)),
+            read_only: T::Boolean
+          }
         )
       end
       def to_hash

data/rbi/turbopuffer/models/namespace_multi_query_params.rbi

@@ -37,6 +37,23 @@ module Turbopuffer
       end
       attr_writer :consistency
 
+      # Limits the total number of reranked documents returned.
+      sig { returns(T.nilable(T.any(Integer, Turbopuffer::RerankLimit))) }
+      attr_reader :limit
+
+      sig do
+        params(limit: T.any(Integer, Turbopuffer::RerankLimit::OrHash)).void
+      end
+      attr_writer :limit
+
+      # Number of reranked documents to skip before returning results. Requires
+      # `rerank_by` and `limit`.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :offset
+
+      sig { params(offset: Integer).void }
+      attr_writer :offset
+
       # How to combine the rows returned by each sub-query into a single ranked list.
       sig { returns(T.nilable(T.anything)) }
       attr_reader :rerank_by
@@ -60,6 +77,8 @@ module Turbopuffer
           namespace: String,
           consistency:
             Turbopuffer::NamespaceMultiQueryParams::Consistency::OrHash,
+          limit: T.any(Integer, Turbopuffer::RerankLimit::OrHash),
+          offset: Integer,
           rerank_by: T.anything,
           vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
           request_options: Turbopuffer::RequestOptions::OrHash
@@ -70,6 +89,11 @@ module Turbopuffer
         namespace: nil,
         # The consistency level for a query.
         consistency: nil,
+        # Limits the total number of reranked documents returned.
+        limit: nil,
+        # Number of reranked documents to skip before returning results. Requires
+        # `rerank_by` and `limit`.
+        offset: nil,
         # How to combine the rows returned by each sub-query into a single ranked list.
         rerank_by: nil,
         # The encoding to use for vectors in the response.
@@ -84,6 +108,8 @@ module Turbopuffer
             namespace: String,
             queries: T::Array[Turbopuffer::NamespaceMultiQueryParams::Query],
             consistency: Turbopuffer::NamespaceMultiQueryParams::Consistency,
+            limit: T.any(Integer, Turbopuffer::RerankLimit),
+            offset: Integer,
             rerank_by: T.anything,
             vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
             request_options: Turbopuffer::RequestOptions
@@ -110,6 +136,15 @@ module Turbopuffer
         sig { params(aggregate_by: T::Hash[Symbol, T.anything]).void }
         attr_writer :aggregate_by
 
+        # 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.
+        sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+        attr_reader :compute_attributes
+
+        sig { params(compute_attributes: T::Hash[Symbol, T.anything]).void }
+        attr_writer :compute_attributes
+
         # A function used to calculate vector similarity.
         sig { returns(T.nilable(Turbopuffer::DistanceMetric::OrSymbol)) }
         attr_reader :distance_metric
@@ -161,6 +196,14 @@ module Turbopuffer
         sig { params(limit: T.any(Integer, Turbopuffer::Limit::OrHash)).void }
         attr_writer :limit
 
+        # Number of documents to skip before returning results. Supported only in v2
+        # queries with an explicit `rank_by` and `top_k` or `limit`.
+        sig { returns(T.nilable(Integer)) }
+        attr_reader :offset
+
+        sig { params(offset: Integer).void }
+        attr_writer :offset
+
         # How to rank the documents in the namespace.
         sig { returns(T.nilable(T.anything)) }
         attr_reader :rank_by
@@ -179,12 +222,14 @@ module Turbopuffer
         sig do
           params(
             aggregate_by: T::Hash[Symbol, T.anything],
+            compute_attributes: T::Hash[Symbol, T.anything],
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
             filters: T.anything,
             group_by: T::Array[T.anything],
             include_attributes: Turbopuffer::IncludeAttributes::Variants,
             limit: T.any(Integer, Turbopuffer::Limit::OrHash),
+            offset: Integer,
             rank_by: T.anything,
             top_k: Integer
           ).returns(T.attached_class)
@@ -193,6 +238,10 @@ module Turbopuffer
           # Aggregations to compute over all documents in the namespace that match the
           # filters.
           aggregate_by: nil,
+          # 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.
+          compute_attributes: nil,
           # A function used to calculate vector similarity.
           distance_metric: nil,
           # List of attribute names to exclude from the response. All other attributes will
@@ -208,6 +257,9 @@ module Turbopuffer
           include_attributes: nil,
           # Limits the documents returned by a query.
           limit: nil,
+          # Number of documents to skip before returning results. Supported only in v2
+          # queries with an explicit `rank_by` and `top_k` or `limit`.
+          offset: nil,
           # How to rank the documents in the namespace.
           rank_by: nil,
           # The number of results to return.
@@ -219,12 +271,14 @@ module Turbopuffer
           override.returns(
             {
               aggregate_by: T::Hash[Symbol, T.anything],
+              compute_attributes: T::Hash[Symbol, T.anything],
               distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
               exclude_attributes: T::Array[String],
               filters: T.anything,
               group_by: T::Array[T.anything],
               include_attributes: Turbopuffer::IncludeAttributes::Variants,
               limit: T.any(Integer, Turbopuffer::Limit),
+              offset: Integer,
               rank_by: T.anything,
               top_k: Integer
             }
@@ -340,6 +394,21 @@ module Turbopuffer
           end
         end
       end
+
+      # Limits the total number of reranked documents returned.
+      module Limit
+        extend Turbopuffer::Internal::Type::Union
+
+        Variants = T.type_alias { T.any(Integer, Turbopuffer::RerankLimit) }
+
+        sig do
+          override.returns(
+            T::Array[Turbopuffer::NamespaceMultiQueryParams::Limit::Variants]
+          )
+        end
+        def self.variants
+        end
+      end
     end
   end
 end

data/rbi/turbopuffer/models/namespace_poll_copy_from_params.rbi

@@ -0,0 +1,49 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespacePollCopyFromParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespacePollCopyFromParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      sig { returns(String) }
+      attr_accessor :token
+
+      sig do
+        params(
+          token: String,
+          namespace: String,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(token:, namespace: nil, request_options: {})
+      end
+
+      sig do
+        override.returns(
+          {
+            namespace: String,
+            token: String,
+            request_options: Turbopuffer::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_query_params.rbi

@@ -28,6 +28,15 @@ module Turbopuffer
       sig { params(aggregate_by: T::Hash[Symbol, T.anything]).void }
       attr_writer :aggregate_by
 
+      # 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.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :compute_attributes
+
+      sig { params(compute_attributes: T::Hash[Symbol, T.anything]).void }
+      attr_writer :compute_attributes
+
       # The consistency level for a query.
       sig { returns(T.nilable(Turbopuffer::NamespaceQueryParams::Consistency)) }
       attr_reader :consistency
@@ -90,6 +99,14 @@ module Turbopuffer
       sig { params(limit: T.any(Integer, Turbopuffer::Limit::OrHash)).void }
       attr_writer :limit
 
+      # Number of documents to skip before returning results. Supported only in v2
+      # queries with an explicit `rank_by` and `top_k` or `limit`.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :offset
+
+      sig { params(offset: Integer).void }
+      attr_writer :offset
+
       # How to rank the documents in the namespace.
       sig { returns(T.nilable(T.anything)) }
       attr_reader :rank_by
@@ -117,6 +134,7 @@ module Turbopuffer
         params(
           namespace: String,
           aggregate_by: T::Hash[Symbol, T.anything],
+          compute_attributes: T::Hash[Symbol, T.anything],
           consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash,
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
@@ -124,6 +142,7 @@ module Turbopuffer
           group_by: T::Array[T.anything],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           limit: T.any(Integer, Turbopuffer::Limit::OrHash),
+          offset: Integer,
           rank_by: T.anything,
           top_k: Integer,
           vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
@@ -135,6 +154,10 @@ module Turbopuffer
         # Aggregations to compute over all documents in the namespace that match the
         # filters.
         aggregate_by: nil,
+        # 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.
+        compute_attributes: nil,
         # The consistency level for a query.
         consistency: nil,
         # A function used to calculate vector similarity.
@@ -152,6 +175,9 @@ module Turbopuffer
         include_attributes: nil,
         # Limits the documents returned by a query.
         limit: nil,
+        # Number of documents to skip before returning results. Supported only in v2
+        # queries with an explicit `rank_by` and `top_k` or `limit`.
+        offset: nil,
         # How to rank the documents in the namespace.
         rank_by: nil,
         # The number of results to return.
@@ -167,6 +193,7 @@ module Turbopuffer
           {
             namespace: String,
             aggregate_by: T::Hash[Symbol, T.anything],
+            compute_attributes: T::Hash[Symbol, T.anything],
             consistency: Turbopuffer::NamespaceQueryParams::Consistency,
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
@@ -174,6 +201,7 @@ module Turbopuffer
             group_by: T::Array[T.anything],
             include_attributes: Turbopuffer::IncludeAttributes::Variants,
             limit: T.any(Integer, Turbopuffer::Limit),
+            offset: Integer,
             rank_by: T.anything,
             top_k: Integer,
             vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,

data/rbi/turbopuffer/models/namespace_start_copy_from_params.rbi

@@ -0,0 +1,113 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceStartCopyFromParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespaceStartCopyFromParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      # The namespace to copy documents from.
+      sig { returns(String) }
+      attr_accessor :source_namespace
+
+      # (Optional) The encryption configuration for the destination namespace.
+      sig do
+        returns(
+          T.nilable(
+            T.any(
+              Turbopuffer::Encryption::CustomerManaged,
+              Turbopuffer::Encryption::Default
+            )
+          )
+        )
+      end
+      attr_reader :dest_encryption
+
+      sig do
+        params(
+          dest_encryption:
+            T.any(
+              Turbopuffer::Encryption::CustomerManaged::OrHash,
+              Turbopuffer::Encryption::Default::OrHash
+            )
+        ).void
+      end
+      attr_writer :dest_encryption
+
+      # (Optional) An API key for the organization containing the source namespace
+      sig { returns(T.nilable(String)) }
+      attr_reader :source_api_key
+
+      sig { params(source_api_key: String).void }
+      attr_writer :source_api_key
+
+      # (Optional) The region of the source namespace.
+      sig { returns(T.nilable(String)) }
+      attr_reader :source_region
+
+      sig { params(source_region: String).void }
+      attr_writer :source_region
+
+      sig do
+        params(
+          source_namespace: String,
+          namespace: String,
+          dest_encryption:
+            T.any(
+              Turbopuffer::Encryption::CustomerManaged::OrHash,
+              Turbopuffer::Encryption::Default::OrHash
+            ),
+          source_api_key: String,
+          source_region: String,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The namespace to copy documents from.
+        source_namespace:,
+        namespace: nil,
+        # (Optional) The encryption configuration for the destination namespace.
+        dest_encryption: nil,
+        # (Optional) An API key for the organization containing the source namespace
+        source_api_key: nil,
+        # (Optional) The region of the source namespace.
+        source_region: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            namespace: String,
+            source_namespace: String,
+            dest_encryption:
+              T.any(
+                Turbopuffer::Encryption::CustomerManaged,
+                Turbopuffer::Encryption::Default
+              ),
+            source_api_key: String,
+            source_region: String,
+            request_options: Turbopuffer::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi

@@ -0,0 +1,30 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceStartCopyFromResponse < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::Models::NamespaceStartCopyFromResponse,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      # The token identifying the copy operation.
+      sig { returns(String) }
+      attr_accessor :token
+
+      sig { params(token: String).returns(T.attached_class) }
+      def self.new(
+        # The token identifying the copy operation.
+        token:
+      )
+      end
+
+      sig { override.returns({ token: String }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_write_params.rbi

@@ -209,6 +209,16 @@ module Turbopuffer
       end
       attr_writer :schema
 
+      # 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.
+      sig { returns(T.nilable(Turbopuffer::ShardingConfig)) }
+      attr_reader :sharding
+
+      sig { params(sharding: Turbopuffer::ShardingConfig::OrHash).void }
+      attr_writer :sharding
+
       # A list of documents in columnar format. Each key is a column name, mapped to an
       # array of values for that column.
       sig { returns(T.nilable(Turbopuffer::Columns)) }
@@ -267,6 +277,7 @@ module Turbopuffer
               Symbol,
               T.any(String, Turbopuffer::AttributeSchemaConfig::OrHash)
             ],
+          sharding: Turbopuffer::ShardingConfig::OrHash,
           upsert_columns: Turbopuffer::Columns::OrHash,
           upsert_condition: T.anything,
           upsert_rows: T::Array[Turbopuffer::Row::OrHash],
@@ -310,6 +321,11 @@ module Turbopuffer
         return_affected_ids: nil,
         # The schema of the attributes attached to the documents.
         schema: nil,
+        # 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.
+        sharding: nil,
         # A list of documents in columnar format. Each key is a column name, mapped to an
         # array of values for that column.
         upsert_columns: nil,
@@ -357,6 +373,7 @@ module Turbopuffer
                 Symbol,
                 T.any(String, Turbopuffer::AttributeSchemaConfig)
               ],
+            sharding: Turbopuffer::ShardingConfig,
             upsert_columns: Turbopuffer::Columns,
             upsert_condition: T.anything,
             upsert_rows: T::Array[Turbopuffer::Row],

data/rbi/turbopuffer/models/operation_error.rbi

@@ -0,0 +1,77 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class OperationError < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::OperationError, Turbopuffer::Internal::AnyHash)
+        end
+
+      # The response to an unsuccessful request.
+      sig { returns(Turbopuffer::OperationError::Detail) }
+      attr_reader :detail
+
+      sig { params(detail: Turbopuffer::OperationError::Detail::OrHash).void }
+      attr_writer :detail
+
+      # The HTTP status code of the operation's error.
+      sig { returns(Integer) }
+      attr_accessor :status_code
+
+      sig do
+        params(
+          detail: Turbopuffer::OperationError::Detail::OrHash,
+          status_code: Integer
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The response to an unsuccessful request.
+        detail:,
+        # The HTTP status code of the operation's error.
+        status_code:
+      )
+      end
+
+      sig do
+        override.returns(
+          { detail: Turbopuffer::OperationError::Detail, status_code: Integer }
+        )
+      end
+      def to_hash
+      end
+
+      class Detail < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::OperationError::Detail,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The error message.
+        sig { returns(String) }
+        attr_accessor :error
+
+        # The status of the request.
+        sig { returns(Symbol) }
+        attr_accessor :status
+
+        # The response to an unsuccessful request.
+        sig { params(error: String, status: Symbol).returns(T.attached_class) }
+        def self.new(
+          # The error message.
+          error:,
+          # The status of the request.
+          status: :error
+        )
+        end
+
+        sig { override.returns({ error: String, status: Symbol }) }
+        def to_hash
+        end
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/rerank_limit.rbi

@@ -0,0 +1,28 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class RerankLimit < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::RerankLimit, Turbopuffer::Internal::AnyHash)
+        end
+
+      # Limits the total number of documents returned after reranking.
+      sig { returns(Integer) }
+      attr_accessor :total
+
+      # Limits the total number of reranked documents returned.
+      sig { params(total: Integer).returns(T.attached_class) }
+      def self.new(
+        # Limits the total number of documents returned after reranking.
+        total:
+      )
+      end
+
+      sig { override.returns({ total: Integer }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/rrf_params.rbi

@@ -15,15 +15,34 @@ module Turbopuffer
       sig { params(rank_constant: Integer).void }
       attr_writer :rank_constant
 
+      # 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`.
+      sig { returns(T.nilable(T::Array[Float])) }
+      attr_reader :weights
+
+      sig { params(weights: T::Array[Float]).void }
+      attr_writer :weights
+
       # Configuration options for RRF.
-      sig { params(rank_constant: Integer).returns(T.attached_class) }
+      sig do
+        params(rank_constant: Integer, weights: T::Array[Float]).returns(
+          T.attached_class
+        )
+      end
       def self.new(
         # RRF rank constant (`k`). Must be greater than zero. Defaults to `60`.
-        rank_constant: nil
+        rank_constant: nil,
+        # 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`.
+        weights: nil
       )
       end
 
-      sig { override.returns({ rank_constant: Integer }) }
+      sig do
+        override.returns({ rank_constant: Integer, weights: T::Array[Float] })
+      end
       def to_hash
       end
     end

data/rbi/turbopuffer/models/sharding_config.rbi

@@ -0,0 +1,31 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class ShardingConfig < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::ShardingConfig, Turbopuffer::Internal::AnyHash)
+        end
+
+      # The number of shards to partition the namespace into.
+      sig { returns(Integer) }
+      attr_accessor :num_shards
+
+      # 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.
+      sig { params(num_shards: Integer).returns(T.attached_class) }
+      def self.new(
+        # The number of shards to partition the namespace into.
+        num_shards:
+      )
+      end
+
+      sig { override.returns({ num_shards: Integer }) }
+      def to_hash
+      end
+    end
+  end
+end