turbopuffer 2.3.0 → 2.5.0

data/rbi/turbopuffer/models/write_result.rbi

@@ -0,0 +1,159 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class WriteResult < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(Turbopuffer::WriteResult, Turbopuffer::Internal::AnyHash)
+        end
+
+      # The billing information for a write request.
+      sig { returns(Turbopuffer::WriteBilling) }
+      attr_reader :billing
+
+      sig { params(billing: Turbopuffer::WriteBilling::OrHash).void }
+      attr_writer :billing
+
+      # A message describing the result of the write request.
+      sig { returns(String) }
+      attr_accessor :message
+
+      # The number of rows affected by the write request.
+      sig { returns(Integer) }
+      attr_accessor :rows_affected
+
+      # The status of the request.
+      sig { returns(Symbol) }
+      attr_accessor :status
+
+      # The IDs of documents that were deleted. Only included when `return_affected_ids`
+      # is true and at least one document was deleted.
+      sig { returns(T.nilable(T::Array[Turbopuffer::ID::Variants])) }
+      attr_reader :deleted_ids
+
+      sig { params(deleted_ids: T::Array[Turbopuffer::ID::Variants]).void }
+      attr_writer :deleted_ids
+
+      # The IDs of documents that were patched. Only included when `return_affected_ids`
+      # is true and at least one document was patched.
+      sig { returns(T.nilable(T::Array[Turbopuffer::ID::Variants])) }
+      attr_reader :patched_ids
+
+      sig { params(patched_ids: T::Array[Turbopuffer::ID::Variants]).void }
+      attr_writer :patched_ids
+
+      # The performance information for a write request.
+      sig { returns(T.nilable(Turbopuffer::WritePerformance)) }
+      attr_reader :performance
+
+      sig { params(performance: Turbopuffer::WritePerformance::OrHash).void }
+      attr_writer :performance
+
+      # The number of rows deleted by the write request.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :rows_deleted
+
+      sig { params(rows_deleted: Integer).void }
+      attr_writer :rows_deleted
+
+      # The number of rows patched by the write request.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :rows_patched
+
+      sig { params(rows_patched: Integer).void }
+      attr_writer :rows_patched
+
+      # Whether more documents match the filter for partial operations.
+      sig { returns(T.nilable(T::Boolean)) }
+      attr_reader :rows_remaining
+
+      sig { params(rows_remaining: T::Boolean).void }
+      attr_writer :rows_remaining
+
+      # The number of rows upserted by the write request.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :rows_upserted
+
+      sig { params(rows_upserted: Integer).void }
+      attr_writer :rows_upserted
+
+      # The IDs of documents that were upserted. Only included when
+      # `return_affected_ids` is true and at least one document was upserted.
+      sig { returns(T.nilable(T::Array[Turbopuffer::ID::Variants])) }
+      attr_reader :upserted_ids
+
+      sig { params(upserted_ids: T::Array[Turbopuffer::ID::Variants]).void }
+      attr_writer :upserted_ids
+
+      # The response to a successful write request.
+      sig do
+        params(
+          billing: Turbopuffer::WriteBilling::OrHash,
+          message: String,
+          rows_affected: Integer,
+          deleted_ids: T::Array[Turbopuffer::ID::Variants],
+          patched_ids: T::Array[Turbopuffer::ID::Variants],
+          performance: Turbopuffer::WritePerformance::OrHash,
+          rows_deleted: Integer,
+          rows_patched: Integer,
+          rows_remaining: T::Boolean,
+          rows_upserted: Integer,
+          upserted_ids: T::Array[Turbopuffer::ID::Variants],
+          status: Symbol
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        # The billing information for a write request.
+        billing:,
+        # A message describing the result of the write request.
+        message:,
+        # The number of rows affected by the write request.
+        rows_affected:,
+        # The IDs of documents that were deleted. Only included when `return_affected_ids`
+        # is true and at least one document was deleted.
+        deleted_ids: nil,
+        # The IDs of documents that were patched. Only included when `return_affected_ids`
+        # is true and at least one document was patched.
+        patched_ids: nil,
+        # The performance information for a write request.
+        performance: nil,
+        # The number of rows deleted by the write request.
+        rows_deleted: nil,
+        # The number of rows patched by the write request.
+        rows_patched: nil,
+        # Whether more documents match the filter for partial operations.
+        rows_remaining: nil,
+        # The number of rows upserted by the write request.
+        rows_upserted: nil,
+        # The IDs of documents that were upserted. Only included when
+        # `return_affected_ids` is true and at least one document was upserted.
+        upserted_ids: nil,
+        # The status of the request.
+        status: :OK
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            billing: Turbopuffer::WriteBilling,
+            message: String,
+            rows_affected: Integer,
+            status: Symbol,
+            deleted_ids: T::Array[Turbopuffer::ID::Variants],
+            patched_ids: T::Array[Turbopuffer::ID::Variants],
+            performance: Turbopuffer::WritePerformance,
+            rows_deleted: Integer,
+            rows_patched: Integer,
+            rows_remaining: T::Boolean,
+            rows_upserted: Integer,
+            upserted_ids: T::Array[Turbopuffer::ID::Variants]
+          }
+        )
+      end
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models.rbi

@@ -31,6 +31,11 @@ module Turbopuffer
   ContainsAnyTokenFilterParams =
     Turbopuffer::Models::ContainsAnyTokenFilterParams
 
+  CopyFromNamespaceOperation = Turbopuffer::Models::CopyFromNamespaceOperation
+
+  CopyFromNamespaceOperationResult =
+    Turbopuffer::Models::CopyFromNamespaceOperationResult
+
   CopyFromNamespaceParams = Turbopuffer::Models::CopyFromNamespaceParams
 
   DecayParams = Turbopuffer::Models::DecayParams
@@ -49,6 +54,12 @@ module Turbopuffer
 
   FuzzyParams = Turbopuffer::Models::FuzzyParams
 
+  HighlightConfigParams = Turbopuffer::Models::HighlightConfigParams
+
+  HighlightFragmentBy = Turbopuffer::Models::HighlightFragmentBy
+
+  HighlightOffsetUnits = Turbopuffer::Models::HighlightOffsetUnits
+
   ID = Turbopuffer::Models::ID
 
   IncludeAttributes = Turbopuffer::Models::IncludeAttributes
@@ -76,12 +87,17 @@ module Turbopuffer
 
   NamespaceMultiQueryParams = Turbopuffer::Models::NamespaceMultiQueryParams
 
+  NamespacePollCopyFromParams = Turbopuffer::Models::NamespacePollCopyFromParams
+
   NamespaceQueryParams = Turbopuffer::Models::NamespaceQueryParams
 
   NamespaceRecallParams = Turbopuffer::Models::NamespaceRecallParams
 
   NamespaceSchemaParams = Turbopuffer::Models::NamespaceSchemaParams
 
+  NamespaceStartCopyFromParams =
+    Turbopuffer::Models::NamespaceStartCopyFromParams
+
   NamespaceSummary = Turbopuffer::Models::NamespaceSummary
 
   NamespaceUpdateMetadataParams =
@@ -91,18 +107,24 @@ module Turbopuffer
 
   NamespaceWriteParams = Turbopuffer::Models::NamespaceWriteParams
 
+  OperationError = Turbopuffer::Models::OperationError
+
   PinningConfig = Turbopuffer::Models::PinningConfig
 
   QueryBilling = Turbopuffer::Models::QueryBilling
 
   QueryPerformance = Turbopuffer::Models::QueryPerformance
 
+  RerankLimit = Turbopuffer::Models::RerankLimit
+
   Row = Turbopuffer::Models::Row
 
   RrfParams = Turbopuffer::Models::RrfParams
 
   SaturateParams = Turbopuffer::Models::SaturateParams
 
+  ShardingConfig = Turbopuffer::Models::ShardingConfig
+
   SparseDistanceMetric = Turbopuffer::Models::SparseDistanceMetric
 
   Tokenizer = Turbopuffer::Models::Tokenizer
@@ -114,4 +136,6 @@ module Turbopuffer
   WriteBilling = Turbopuffer::Models::WriteBilling
 
   WritePerformance = Turbopuffer::Models::WritePerformance
+
+  WriteResult = Turbopuffer::Models::WriteResult
 end

data/rbi/turbopuffer/resources/namespaces.rbi

@@ -71,6 +71,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,
@@ -79,6 +80,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,
@@ -91,6 +93,10 @@ module Turbopuffer
         # Body param: Aggregations to compute over all documents in the namespace that
         # match the filters.
         aggregate_by: nil,
+        # Body param: 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,
         # Body param: The consistency level for a query.
         consistency: nil,
         # Body param: A function used to calculate vector similarity.
@@ -108,6 +114,9 @@ module Turbopuffer
         include_attributes: nil,
         # Body param: Limits the documents returned by a query.
         limit: nil,
+        # Body param: 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,
         # Body param: How to rank the documents in the namespace.
         rank_by: nil,
         # Body param: The number of results to return.
@@ -154,6 +163,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
@@ -166,6 +177,11 @@ module Turbopuffer
         namespace: nil,
         # Body param: The consistency level for a query.
         consistency: nil,
+        # Body param: Limits the total number of reranked documents returned.
+        limit: nil,
+        # Body param: Number of reranked documents to skip before returning results.
+        # Requires `rerank_by` and `limit`.
+        offset: nil,
         # Body param: How to combine the rows returned by each sub-query into a single
         # ranked list.
         rerank_by: nil,
@@ -175,11 +191,29 @@ module Turbopuffer
       )
       end
 
+      # Retrieve the current status of a copy operation.
+      sig do
+        params(
+          token: String,
+          namespace: String,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::CopyFromNamespaceOperation::Variants)
+      end
+      def poll_copy_from(
+        # The operation token obtained when starting the copy.
+        token,
+        # The name of the namespace.
+        namespace: nil,
+        request_options: {}
+      )
+      end
+
       # Query, filter, full-text search and vector search documents.
       sig do
         params(
           namespace: T.nilable(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],
@@ -187,6 +221,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,
@@ -199,6 +234,10 @@ module Turbopuffer
         # Body param: Aggregations to compute over all documents in the namespace that
         # match the filters.
         aggregate_by: nil,
+        # Body param: 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,
         # Body param: The consistency level for a query.
         consistency: nil,
         # Body param: A function used to calculate vector similarity.
@@ -216,6 +255,9 @@ module Turbopuffer
         include_attributes: nil,
         # Body param: Limits the documents returned by a query.
         limit: nil,
+        # Body param: 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,
         # Body param: How to rank the documents in the namespace.
         rank_by: nil,
         # Body param: The number of results to return.
@@ -271,12 +313,47 @@ module Turbopuffer
       )
       end
 
+      # 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.
+      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(Turbopuffer::Models::NamespaceStartCopyFromResponse)
+      end
+      def start_copy_from(
+        # Body param: The namespace to copy documents from.
+        source_namespace:,
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: (Optional) The encryption configuration for the destination
+        # namespace.
+        dest_encryption: nil,
+        # Body param: (Optional) An API key for the organization containing the source
+        # namespace
+        source_api_key: nil,
+        # Body param: (Optional) The region of the source namespace.
+        source_region: nil,
+        request_options: {}
+      )
+      end
+
       # Update metadata configuration for a namespace.
       sig do
         params(
           namespace: String,
           pinning:
             T.nilable(T.any(T::Boolean, Turbopuffer::PinningConfig::OrHash)),
+          read_only: T::Boolean,
           request_options: Turbopuffer::RequestOptions::OrHash
         ).returns(Turbopuffer::NamespaceMetadata)
       end
@@ -290,6 +367,10 @@ module Turbopuffer
         # - `true`: enable pinning with default configuration
         # - Object: set pinning configuration
         pinning: nil,
+        # Body param: 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,
         request_options: {}
       )
       end
@@ -352,6 +433,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],
@@ -399,6 +481,11 @@ module Turbopuffer
         return_affected_ids: nil,
         # Body param: The schema of the attributes attached to the documents.
         schema: nil,
+        # Body param: 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,
         # Body param: 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,

data/sig/turbopuffer/models/attribute_schema_config.rbs

@@ -82,7 +82,10 @@ module Turbopuffer
         extend Turbopuffer::Internal::Type::Union
 
         type ann_config =
-          { distance_metric: Turbopuffer::Models::distance_metric }
+          {
+            distance_metric: Turbopuffer::Models::distance_metric,
+            late_interaction: bool
+          }
 
         class AnnConfig < Turbopuffer::Internal::Type::BaseModel
           attr_reader distance_metric: Turbopuffer::Models::distance_metric?
@@ -91,12 +94,18 @@ module Turbopuffer
             Turbopuffer::Models::distance_metric
           ) -> Turbopuffer::Models::distance_metric
 
+          attr_reader late_interaction: bool?
+
+          def late_interaction=: (bool) -> bool
+
           def initialize: (
-            ?distance_metric: Turbopuffer::Models::distance_metric
+            ?distance_metric: Turbopuffer::Models::distance_metric,
+            ?late_interaction: bool
           ) -> void
 
           def to_hash: -> {
-            distance_metric: Turbopuffer::Models::distance_metric
+            distance_metric: Turbopuffer::Models::distance_metric,
+            late_interaction: bool
           }
         end
 

data/sig/turbopuffer/models/copy_from_namespace_operation.rbs

@@ -0,0 +1,65 @@
+module Turbopuffer
+  module Models
+    type copy_from_namespace_operation =
+      Turbopuffer::CopyFromNamespaceOperation::Running
+      | Turbopuffer::CopyFromNamespaceOperation::Finished
+
+    module CopyFromNamespaceOperation
+      extend Turbopuffer::Internal::Type::Union
+
+      type running = { start_time: Time, status: :running, progress: String }
+
+      class Running < Turbopuffer::Internal::Type::BaseModel
+        attr_accessor start_time: Time
+
+        attr_accessor status: :running
+
+        attr_reader progress: String?
+
+        def progress=: (String) -> String
+
+        def initialize: (
+          start_time: Time,
+          ?progress: String,
+          ?status: :running
+        ) -> void
+
+        def to_hash: -> { start_time: Time, status: :running, progress: String }
+      end
+
+      type finished =
+        {
+          finish_time: Time,
+          result: Turbopuffer::Models::copy_from_namespace_operation_result,
+          start_time: Time,
+          status: :finished
+        }
+
+      class Finished < Turbopuffer::Internal::Type::BaseModel
+        attr_accessor finish_time: Time
+
+        attr_accessor result: Turbopuffer::Models::copy_from_namespace_operation_result
+
+        attr_accessor start_time: Time
+
+        attr_accessor status: :finished
+
+        def initialize: (
+          finish_time: Time,
+          result: Turbopuffer::Models::copy_from_namespace_operation_result,
+          start_time: Time,
+          ?status: :finished
+        ) -> void
+
+        def to_hash: -> {
+          finish_time: Time,
+          result: Turbopuffer::Models::copy_from_namespace_operation_result,
+          start_time: Time,
+          status: :finished
+        }
+      end
+
+      def self?.variants: -> ::Array[Turbopuffer::Models::copy_from_namespace_operation]
+    end
+  end
+end

data/sig/turbopuffer/models/copy_from_namespace_operation_result.rbs

@@ -0,0 +1,33 @@
+module Turbopuffer
+  module Models
+    type copy_from_namespace_operation_result =
+      Turbopuffer::CopyFromNamespaceOperationResult::Success
+      | Turbopuffer::CopyFromNamespaceOperationResult::Error
+
+    module CopyFromNamespaceOperationResult
+      extend Turbopuffer::Internal::Type::Union
+
+      type success = { success: Turbopuffer::WriteResult }
+
+      class Success < Turbopuffer::Internal::Type::BaseModel
+        attr_accessor success: Turbopuffer::WriteResult
+
+        def initialize: (success: Turbopuffer::WriteResult) -> void
+
+        def to_hash: -> { success: Turbopuffer::WriteResult }
+      end
+
+      type error = { error: Turbopuffer::OperationError }
+
+      class Error < Turbopuffer::Internal::Type::BaseModel
+        attr_accessor error: Turbopuffer::OperationError
+
+        def initialize: (error: Turbopuffer::OperationError) -> void
+
+        def to_hash: -> { error: Turbopuffer::OperationError }
+      end
+
+      def self?.variants: -> ::Array[Turbopuffer::Models::copy_from_namespace_operation_result]
+    end
+  end
+end

data/sig/turbopuffer/models/highlight_config_params.rbs

@@ -0,0 +1,47 @@
+module Turbopuffer
+  module Models
+    type highlight_config_params =
+      {
+        fragment_by: Turbopuffer::Models::highlight_fragment_by,
+        fragment_limit: Integer,
+        include_offsets: Turbopuffer::Models::highlight_offset_units,
+        rank_fragments_by: top
+      }
+
+    class HighlightConfigParams < Turbopuffer::Internal::Type::BaseModel
+      attr_reader fragment_by: Turbopuffer::Models::highlight_fragment_by?
+
+      def fragment_by=: (
+        Turbopuffer::Models::highlight_fragment_by
+      ) -> Turbopuffer::Models::highlight_fragment_by
+
+      attr_reader fragment_limit: Integer?
+
+      def fragment_limit=: (Integer) -> Integer
+
+      attr_reader include_offsets: Turbopuffer::Models::highlight_offset_units?
+
+      def include_offsets=: (
+        Turbopuffer::Models::highlight_offset_units
+      ) -> Turbopuffer::Models::highlight_offset_units
+
+      attr_reader rank_fragments_by: top?
+
+      def rank_fragments_by=: (top) -> top
+
+      def initialize: (
+        ?fragment_by: Turbopuffer::Models::highlight_fragment_by,
+        ?fragment_limit: Integer,
+        ?include_offsets: Turbopuffer::Models::highlight_offset_units,
+        ?rank_fragments_by: top
+      ) -> void
+
+      def to_hash: -> {
+        fragment_by: Turbopuffer::Models::highlight_fragment_by,
+        fragment_limit: Integer,
+        include_offsets: Turbopuffer::Models::highlight_offset_units,
+        rank_fragments_by: top
+      }
+    end
+  end
+end

data/sig/turbopuffer/models/highlight_fragment_by.rbs

@@ -0,0 +1,23 @@
+module Turbopuffer
+  module Models
+    type highlight_fragment_by = :none | :sentence | :paragraph | :word
+
+    module HighlightFragmentBy
+      extend Turbopuffer::Internal::Type::Enum
+
+      # Treat the whole attribute as a single fragment.
+      NONE: :none
+
+      # Split the attribute into sentences. This is the default.
+      SENTENCE: :sentence
+
+      # Split the attribute into paragraphs.
+      PARAGRAPH: :paragraph
+
+      # Split the attribute into individual words.
+      WORD: :word
+
+      def self?.values: -> ::Array[Turbopuffer::Models::highlight_fragment_by]
+    end
+  end
+end

data/sig/turbopuffer/models/highlight_offset_units.rbs

@@ -0,0 +1,15 @@
+module Turbopuffer
+  module Models
+    type highlight_offset_units = :"utf-8" | :"utf-16" | :codepoints
+
+    module HighlightOffsetUnits
+      extend Turbopuffer::Internal::Type::Enum
+
+      UTF_8: :"utf-8"
+      UTF_16: :"utf-16"
+      CODEPOINTS: :codepoints
+
+      def self?.values: -> ::Array[Turbopuffer::Models::highlight_offset_units]
+    end
+  end
+end