turbopuffer 2.3.0 → 2.5.0

data/lib/turbopuffer.rb

@@ -68,6 +68,8 @@ require_relative "turbopuffer/models/client_namespaces_params"
 require_relative "turbopuffer/models/columns"
 require_relative "turbopuffer/models/contains_all_tokens_filter_params"
 require_relative "turbopuffer/models/contains_any_token_filter_params"
+require_relative "turbopuffer/models/copy_from_namespace_operation"
+require_relative "turbopuffer/models/copy_from_namespace_operation_result"
 require_relative "turbopuffer/models/copy_from_namespace_params"
 require_relative "turbopuffer/models/decay_params"
 require_relative "turbopuffer/models/distance_metric"
@@ -77,6 +79,9 @@ require_relative "turbopuffer/models/full_text_search"
 require_relative "turbopuffer/models/full_text_search_config"
 require_relative "turbopuffer/models/fuzzy_max_edit_distance"
 require_relative "turbopuffer/models/fuzzy_params"
+require_relative "turbopuffer/models/highlight_config_params"
+require_relative "turbopuffer/models/highlight_fragment_by"
+require_relative "turbopuffer/models/highlight_offset_units"
 require_relative "turbopuffer/models/id"
 require_relative "turbopuffer/models/include_attributes"
 require_relative "turbopuffer/models/language"
@@ -95,29 +100,36 @@ require_relative "turbopuffer/models/namespace_metadata"
 require_relative "turbopuffer/models/namespace_metadata_params"
 require_relative "turbopuffer/models/namespace_multi_query_params"
 require_relative "turbopuffer/models/namespace_multi_query_response"
+require_relative "turbopuffer/models/namespace_poll_copy_from_params"
 require_relative "turbopuffer/models/namespace_query_params"
 require_relative "turbopuffer/models/namespace_query_response"
 require_relative "turbopuffer/models/namespace_recall_params"
 require_relative "turbopuffer/models/namespace_recall_response"
 require_relative "turbopuffer/models/namespace_schema_params"
 require_relative "turbopuffer/models/namespace_schema_response"
+require_relative "turbopuffer/models/namespace_start_copy_from_params"
+require_relative "turbopuffer/models/namespace_start_copy_from_response"
 require_relative "turbopuffer/models/namespace_summary"
 require_relative "turbopuffer/models/namespace_update_metadata_params"
 require_relative "turbopuffer/models/namespace_update_schema_params"
 require_relative "turbopuffer/models/namespace_update_schema_response"
 require_relative "turbopuffer/models/namespace_write_params"
 require_relative "turbopuffer/models/namespace_write_response"
+require_relative "turbopuffer/models/operation_error"
 require_relative "turbopuffer/models/query_billing"
 require_relative "turbopuffer/models/query_performance"
+require_relative "turbopuffer/models/rerank_limit"
 require_relative "turbopuffer/models/row"
 require_relative "turbopuffer/models/rrf_params"
 require_relative "turbopuffer/models/saturate_params"
+require_relative "turbopuffer/models/sharding_config"
 require_relative "turbopuffer/models/sparse_distance_metric"
 require_relative "turbopuffer/models/tokenizer"
 require_relative "turbopuffer/models/vector"
 require_relative "turbopuffer/models/vector_encoding"
 require_relative "turbopuffer/models/write_billing"
 require_relative "turbopuffer/models/write_performance"
+require_relative "turbopuffer/models/write_result"
 require_relative "turbopuffer/models"
 require_relative "turbopuffer/resources/namespaces"
 require_relative "turbopuffer/namespace"

data/rbi/turbopuffer/client.rbi

@@ -10,7 +10,7 @@ module Turbopuffer
 
     DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
 
-    # API key used for authentication
+    # API key used for authentication.
     sig { returns(String) }
     attr_reader :api_key
 
@@ -73,7 +73,7 @@ module Turbopuffer
       ).returns(T.attached_class)
     end
     def self.new(
-      # API key used for authentication Defaults to `ENV["TURBOPUFFER_API_KEY"]`
+      # API key used for authentication. Defaults to `ENV["TURBOPUFFER_API_KEY"]`
       api_key: ENV["TURBOPUFFER_API_KEY"],
       # The turbopuffer region to use. Defaults to `ENV["TURBOPUFFER_REGION"]`
       region: ENV["TURBOPUFFER_REGION"],

data/rbi/turbopuffer/models/attribute_schema_config.rbi

@@ -210,21 +210,38 @@ module Turbopuffer
           end
           attr_writer :distance_metric
 
+          # 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`.
+          sig { returns(T.nilable(T::Boolean)) }
+          attr_reader :late_interaction
+
+          sig { params(late_interaction: T::Boolean).void }
+          attr_writer :late_interaction
+
           # Configuration options for ANN (Approximate Nearest Neighbor) indexing.
           sig do
             params(
-              distance_metric: Turbopuffer::DistanceMetric::OrSymbol
+              distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+              late_interaction: T::Boolean
             ).returns(T.attached_class)
           end
           def self.new(
             # A function used to calculate vector similarity.
-            distance_metric: nil
+            distance_metric: nil,
+            # 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`.
+            late_interaction: nil
           )
           end
 
           sig do
             override.returns(
-              { distance_metric: Turbopuffer::DistanceMetric::OrSymbol }
+              {
+                distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+                late_interaction: T::Boolean
+              }
             )
           end
           def to_hash

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/highlight_config_params.rbi

@@ -0,0 +1,85 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class HighlightConfigParams < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::HighlightConfigParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      # How to split a text attribute into fragments for highlighting.
+      sig { returns(T.nilable(Turbopuffer::HighlightFragmentBy::OrSymbol)) }
+      attr_reader :fragment_by
+
+      sig do
+        params(fragment_by: Turbopuffer::HighlightFragmentBy::OrSymbol).void
+      end
+      attr_writer :fragment_by
+
+      # The maximum number of fragments to return. Defaults to `3`.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :fragment_limit
+
+      sig { params(fragment_limit: Integer).void }
+      attr_writer :fragment_limit
+
+      # The units to report highlighted fragment offsets in.
+      sig { returns(T.nilable(Turbopuffer::HighlightOffsetUnits::OrSymbol)) }
+      attr_reader :include_offsets
+
+      sig do
+        params(
+          include_offsets: Turbopuffer::HighlightOffsetUnits::OrSymbol
+        ).void
+      end
+      attr_writer :include_offsets
+
+      # How to rank candidate fragments within the attribute before selecting the top
+      # `fragment_limit`. Defaults to the query's `rank_by`.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :rank_fragments_by
+
+      sig { params(rank_fragments_by: T.anything).void }
+      attr_writer :rank_fragments_by
+
+      # Additional (optional) parameters for the Highlight compute expression.
+      sig do
+        params(
+          fragment_by: Turbopuffer::HighlightFragmentBy::OrSymbol,
+          fragment_limit: Integer,
+          include_offsets: Turbopuffer::HighlightOffsetUnits::OrSymbol,
+          rank_fragments_by: T.anything
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # How to split a text attribute into fragments for highlighting.
+        fragment_by: nil,
+        # The maximum number of fragments to return. Defaults to `3`.
+        fragment_limit: nil,
+        # The units to report highlighted fragment offsets in.
+        include_offsets: nil,
+        # How to rank candidate fragments within the attribute before selecting the top
+        # `fragment_limit`. Defaults to the query's `rank_by`.
+        rank_fragments_by: nil
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            fragment_by: Turbopuffer::HighlightFragmentBy::OrSymbol,
+            fragment_limit: Integer,
+            include_offsets: Turbopuffer::HighlightOffsetUnits::OrSymbol,
+            rank_fragments_by: T.anything
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/highlight_fragment_by.rbi

@@ -0,0 +1,36 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # How to split a text attribute into fragments for highlighting.
+    module HighlightFragmentBy
+      extend Turbopuffer::Internal::Type::Enum
+
+      TaggedSymbol =
+        T.type_alias { T.all(Symbol, Turbopuffer::HighlightFragmentBy) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      # Treat the whole attribute as a single fragment.
+      NONE = T.let(:none, Turbopuffer::HighlightFragmentBy::TaggedSymbol)
+
+      # Split the attribute into sentences. This is the default.
+      SENTENCE =
+        T.let(:sentence, Turbopuffer::HighlightFragmentBy::TaggedSymbol)
+
+      # Split the attribute into paragraphs.
+      PARAGRAPH =
+        T.let(:paragraph, Turbopuffer::HighlightFragmentBy::TaggedSymbol)
+
+      # Split the attribute into individual words.
+      WORD = T.let(:word, Turbopuffer::HighlightFragmentBy::TaggedSymbol)
+
+      sig do
+        override.returns(
+          T::Array[Turbopuffer::HighlightFragmentBy::TaggedSymbol]
+        )
+      end
+      def self.values
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/highlight_offset_units.rbi

@@ -0,0 +1,27 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    # The units to report highlighted fragment offsets in.
+    module HighlightOffsetUnits
+      extend Turbopuffer::Internal::Type::Enum
+
+      TaggedSymbol =
+        T.type_alias { T.all(Symbol, Turbopuffer::HighlightOffsetUnits) }
+      OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+      UTF_8 = T.let(:"utf-8", Turbopuffer::HighlightOffsetUnits::TaggedSymbol)
+      UTF_16 = T.let(:"utf-16", Turbopuffer::HighlightOffsetUnits::TaggedSymbol)
+      CODEPOINTS =
+        T.let(:codepoints, Turbopuffer::HighlightOffsetUnits::TaggedSymbol)
+
+      sig do
+        override.returns(
+          T::Array[Turbopuffer::HighlightOffsetUnits::TaggedSymbol]
+        )
+      end
+      def self.values
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_explain_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 do
         returns(
@@ -95,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
@@ -122,6 +139,7 @@ module Turbopuffer
         params(
           namespace: String,
           aggregate_by: T::Hash[Symbol, T.anything],
+          compute_attributes: T::Hash[Symbol, T.anything],
           consistency:
             Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash,
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
@@ -130,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,
@@ -141,6 +160,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.
@@ -158,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.
@@ -173,6 +199,7 @@ module Turbopuffer
           {
             namespace: String,
             aggregate_by: T::Hash[Symbol, T.anything],
+            compute_attributes: T::Hash[Symbol, T.anything],
             consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
@@ -180,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,23 @@ 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
+      # 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
+
       # Metadata about a namespace.
       sig do
         params(
@@ -63,7 +80,9 @@ module Turbopuffer
             ),
           schema: T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig::OrHash],
           updated_at: Time,
-          pinning: Turbopuffer::NamespaceMetadata::Pinning::OrHash
+          pinning: Turbopuffer::NamespaceMetadata::Pinning::OrHash,
+          read_only: T::Boolean,
+          sharding: Turbopuffer::ShardingConfig::OrHash
         ).returns(T.attached_class)
       end
       def self.new(
@@ -82,7 +101,14 @@ module Turbopuffer
         updated_at:,
         # Configuration for namespace pinning, along with the current status of the pinned
         # namespace.
-        pinning: nil
+        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
+        # write, and cannot be added to or changed on an existing namespace.
+        sharding: nil
       )
       end
 
@@ -96,7 +122,9 @@ module Turbopuffer
             index: Turbopuffer::NamespaceMetadata::Index::Variants,
             schema: T::Hash[Symbol, Turbopuffer::AttributeSchemaConfig],
             updated_at: Time,
-            pinning: Turbopuffer::NamespaceMetadata::Pinning
+            pinning: Turbopuffer::NamespaceMetadata::Pinning,
+            read_only: T::Boolean,
+            sharding: Turbopuffer::ShardingConfig
           }
         )
       end
@@ -235,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
@@ -248,6 +283,7 @@ module Turbopuffer
           sig do
             params(
               ready_replicas: Integer,
+              replicas: Integer,
               updated_at: Time,
               utilization: Float
             ).returns(T.attached_class)
@@ -255,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
@@ -265,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