turbopuffer 2.4.0 → 2.6.0

data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi

@@ -0,0 +1,133 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # The current status of a copy operation.
+    module CopyFromNamespaceOperation
+      extend Turbopuffer::Internal::Type::Union
+
+      Variants =
+        T.type_alias do
+          T.any(
+            Turbopuffer::CopyFromNamespaceOperation::Running,
+            Turbopuffer::CopyFromNamespaceOperation::Finished
+          )
+        end
+
+      class Running < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::CopyFromNamespaceOperation::Running,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The time at which the operation started.
+        sig { returns(Time) }
+        attr_accessor :start_time
+
+        sig { returns(Symbol) }
+        attr_accessor :status
+
+        # A freeform description of the operation's progress. May be absent, and its
+        # format may change.
+        sig { returns(T.nilable(String)) }
+        attr_reader :progress
+
+        sig { params(progress: String).void }
+        attr_writer :progress
+
+        sig do
+          params(start_time: Time, progress: String, status: Symbol).returns(
+            T.attached_class
+          )
+        end
+        def self.new(
+          # The time at which the operation started.
+          start_time:,
+          # A freeform description of the operation's progress. May be absent, and its
+          # format may change.
+          progress: nil,
+          status: :running
+        )
+        end
+
+        sig do
+          override.returns(
+            { start_time: Time, status: Symbol, progress: String }
+          )
+        end
+        def to_hash
+        end
+      end
+
+      class Finished < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::CopyFromNamespaceOperation::Finished,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The time at which the operation finished.
+        sig { returns(Time) }
+        attr_accessor :finish_time
+
+        sig { returns(Turbopuffer::CopyFromNamespaceOperationResult::Variants) }
+        attr_accessor :result
+
+        # The time at which the operation started.
+        sig { returns(Time) }
+        attr_accessor :start_time
+
+        sig { returns(Symbol) }
+        attr_accessor :status
+
+        sig do
+          params(
+            finish_time: Time,
+            result:
+              T.any(
+                Turbopuffer::CopyFromNamespaceOperationResult::Success::OrHash,
+                Turbopuffer::CopyFromNamespaceOperationResult::Error::OrHash
+              ),
+            start_time: Time,
+            status: Symbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The time at which the operation finished.
+          finish_time:,
+          result:,
+          # The time at which the operation started.
+          start_time:,
+          status: :finished
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              finish_time: Time,
+              result: Turbopuffer::CopyFromNamespaceOperationResult::Variants,
+              start_time: Time,
+              status: Symbol
+            }
+          )
+        end
+        def to_hash
+        end
+      end
+
+      sig do
+        override.returns(
+          T::Array[Turbopuffer::CopyFromNamespaceOperation::Variants]
+        )
+      end
+      def self.variants
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi

@@ -0,0 +1,85 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    module CopyFromNamespaceOperationResult
+      extend Turbopuffer::Internal::Type::Union
+
+      Variants =
+        T.type_alias do
+          T.any(
+            Turbopuffer::CopyFromNamespaceOperationResult::Success,
+            Turbopuffer::CopyFromNamespaceOperationResult::Error
+          )
+        end
+
+      class Success < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::CopyFromNamespaceOperationResult::Success,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The response to a successful write request.
+        sig { returns(Turbopuffer::WriteResult) }
+        attr_reader :success
+
+        sig { params(success: Turbopuffer::WriteResult::OrHash).void }
+        attr_writer :success
+
+        sig do
+          params(success: Turbopuffer::WriteResult::OrHash).returns(
+            T.attached_class
+          )
+        end
+        def self.new(
+          # The response to a successful write request.
+          success:
+        )
+        end
+
+        sig { override.returns({ success: Turbopuffer::WriteResult }) }
+        def to_hash
+        end
+      end
+
+      class Error < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::CopyFromNamespaceOperationResult::Error,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        sig { returns(Turbopuffer::OperationError) }
+        attr_reader :error
+
+        sig { params(error: Turbopuffer::OperationError::OrHash).void }
+        attr_writer :error
+
+        sig do
+          params(error: Turbopuffer::OperationError::OrHash).returns(
+            T.attached_class
+          )
+        end
+        def self.new(error:)
+        end
+
+        sig { override.returns({ error: Turbopuffer::OperationError }) }
+        def to_hash
+        end
+      end
+
+      sig do
+        override.returns(
+          T::Array[Turbopuffer::CopyFromNamespaceOperationResult::Variants]
+        )
+      end
+      def self.variants
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_explain_query_params.rbi

@@ -104,6 +104,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
@@ -140,6 +148,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,
@@ -172,6 +181,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.
@@ -195,6 +207,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_metadata.rbi

@@ -45,6 +45,13 @@ module Turbopuffer
       end
       attr_writer :pinning
 
+      # Whether document and schema writes are rejected. Omitted when `false`.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :read_only
+
+      sig { params(read_only: T::Boolean).void }
+      attr_writer :read_only
+
       # 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
@@ -74,6 +81,7 @@ module Turbopuffer
           schema: T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig::OrHash],
           updated_at: Time,
           pinning: Turbopuffer::NamespaceMetadata::Pinning::OrHash,
+          read_only: T::Boolean,
           sharding: Turbopuffer::ShardingConfig::OrHash
         ).returns(T.attached_class)
       end
@@ -94,6 +102,8 @@ module Turbopuffer
         # Configuration for namespace pinning, along with the current status of the pinned
         # namespace.
         pinning: nil,
+        # Whether document and schema writes are rejected. Omitted when `false`.
+        read_only: 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
@@ -113,6 +123,7 @@ module Turbopuffer
             schema: T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig],
             updated_at: Time,
             pinning: Turbopuffer::NamespaceMetadata::Pinning,
+            read_only: T::Boolean,
             sharding: Turbopuffer::ShardingConfig
           }
         )
@@ -252,6 +263,13 @@ module Turbopuffer
           sig { returns(Integer) }
           attr_accessor :ready_replicas
 
+          # 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.
+          sig { returns(Integer) }
+          attr_accessor :replicas
+
           # The timestamp of the latest pinning status snapshot.
           sig { returns(Time) }
           attr_accessor :updated_at
@@ -265,6 +283,7 @@ module Turbopuffer
           sig do
             params(
               ready_replicas: Integer,
+              replicas: Integer,
               updated_at: Time,
               utilization: Float
             ).returns(T.attached_class)
@@ -272,6 +291,11 @@ module Turbopuffer
           def self.new(
             # The number of replicas that are warm and serving traffic.
             ready_replicas:,
+            # 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.
+            replicas:,
             # The timestamp of the latest pinning status snapshot.
             updated_at:,
             # Aggregate utilization for the pinned namespace, reported as a value between 0.0
@@ -282,7 +306,12 @@ module Turbopuffer
 
           sig do
             override.returns(
-              { ready_replicas: Integer, updated_at: Time, utilization: Float }
+              {
+                ready_replicas: Integer,
+                replicas: Integer,
+                updated_at: Time,
+                utilization: Float
+              }
             )
           end
           def to_hash

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
@@ -170,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
@@ -195,6 +229,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
           ).returns(T.attached_class)
@@ -222,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.
@@ -240,6 +278,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
             }
@@ -355,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

@@ -99,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
@@ -134,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,
@@ -166,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.
@@ -189,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