turbopuffer-ruby 0.2.3 → 0.2.4

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 5b1e5ee7c731fa9997237ad7f6d925613aa81d2e648db8fb45ea5e57a5c2ffa4
-  data.tar.gz: 5a290b29f1a20db2a0662d80905d1ec67ec7aaaeed1fc12ee75cbe4442c33ebe
+  metadata.gz: 4cdba184c47706f13e46349844edd154024ecb50b0cd898b1e472bee7122595f
+  data.tar.gz: d2a2652222e2e672c9069bc965ece1bac43351804670331410aa91462eaa1f7c
 SHA512:
-  metadata.gz: 74f87502fe4f218c32eb90940633c289eb11259086d2c361e3b37aa5211a082eb002448ab45ace5b49d1c10800061bbe85948b6a7fdef56ca98234f8ea3f3aac
-  data.tar.gz: e7ed69482a28c867bf5efc807151e50cbbe504a2cf5b1f10bf8ff5c9c9b6591d0ad579106e75b4df1db5c13b380c578c930391bddf357e033b4d6b02b92b3c50
+  metadata.gz: 0c42de89acf1dc7246fb9ef1ad915bb0e5d0c1bdb74b1d842851d3eeb576ed8ed3cc2047d6d255053b7a21bd7561dbf6a757620ff2ec9099ada4c9a98ddfc487
+  data.tar.gz: 25b6fdfc5c41998e5bb415ecebd39f6b8c6583047bf44a27714363044ffa7c70d86d53ae7e17379514885e8c4ac2191c1e7e292ea0d9aecb8e6b273ded29452d

data/CHANGELOG.md

@@ -1,5 +1,19 @@
 # Changelog
 
+## 0.2.4 (2025-08-01)
+
+Full Changelog: [v0.2.3...v0.2.4](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.3...v0.2.4)
+
+### Bug Fixes
+
+* **api:** api update ([900bd73](https://github.com/turbopuffer/turbopuffer-ruby/commit/900bd73a945bdb8af7d1c23d7f44a359a154c1aa))
+* **api:** api update ([d63b961](https://github.com/turbopuffer/turbopuffer-ruby/commit/d63b9613a0827be0969a218a29df23934ef8c46f))
+
+
+### Chores
+
+* **internal:** increase visibility of internal helper method ([fc6e1e7](https://github.com/turbopuffer/turbopuffer-ruby/commit/fc6e1e7c7a5824c751d32bb3f88ab8c716f763cf))
+
 ## 0.2.3 (2025-07-29)
 
 Full Changelog: [v0.2.2...v0.2.3](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.2...v0.2.3)

data/README.md

@@ -17,7 +17,7 @@ To use this gem, install via Bundler by adding the following to your application
 <!-- x-release-please-start-version -->
 
 ```ruby
-gem "turbopuffer-ruby", "~> 0.2.3"
+gem "turbopuffer-ruby", "~> 0.2.4"
 ```
 
 <!-- x-release-please-end -->
@@ -259,25 +259,25 @@ turbopuffer.namespace("products").write(**params)
 Since this library does not depend on `sorbet-runtime`, it cannot provide [`T::Enum`](https://sorbet.org/docs/tenum) instances. Instead, we provide "tagged symbols" instead, which is always a primitive at runtime:
 
 ```ruby
-# :float
-puts(Turbopuffer::VectorEncoding::FLOAT)
+# :cosine_distance
+puts(Turbopuffer::DistanceMetric::COSINE_DISTANCE)
 
-# Revealed type: `T.all(Turbopuffer::VectorEncoding, Symbol)`
-T.reveal_type(Turbopuffer::VectorEncoding::FLOAT)
+# Revealed type: `T.all(Turbopuffer::DistanceMetric, Symbol)`
+T.reveal_type(Turbopuffer::DistanceMetric::COSINE_DISTANCE)
 ```
 
 Enum parameters have a "relaxed" type, so you can either pass in enum constants or their literal value:
 
 ```ruby
 # Using the enum constants preserves the tagged type information:
-turbopuffer.namespaces.multi_query(
-  vector_encoding: Turbopuffer::VectorEncoding::FLOAT,
+turbopuffer.namespaces.explain_query(
+  distance_metric: Turbopuffer::DistanceMetric::COSINE_DISTANCE,
   # …
 )
 
 # Literal values are also permissible:
-turbopuffer.namespaces.multi_query(
-  vector_encoding: :float,
+turbopuffer.namespaces.explain_query(
+  distance_metric: :cosine_distance,
   # …
 )
 ```

data/lib/turbopuffer/internal/transport/base_client.rb

@@ -365,7 +365,7 @@ module Turbopuffer
         #
         # @raise [Turbopuffer::Errors::APIError]
         # @return [Array(Integer, Net::HTTPResponse, Enumerable<String>)]
-        private def send_request(request, redirect_count:, retry_count:, send_retry_header:)
+        def send_request(request, redirect_count:, retry_count:, send_retry_header:)
           url, headers, max_retries, timeout = request.fetch_values(:url, :headers, :max_retries, :timeout)
           input = {**request.except(:timeout), deadline: Turbopuffer::Internal::Util.monotonic_secs + timeout}
 

data/lib/turbopuffer/models/full_text_search_config.rb

@@ -28,6 +28,14 @@ module Turbopuffer
       #   @return [Symbol, Turbopuffer::Models::Language, nil]
       optional :language, enum: -> { Turbopuffer::Language }
 
+      # @!attribute max_token_length
+      #   Maximum length of a token in bytes. Tokens larger than this value during
+      #   tokenization will be filtered out. Has to be between `1` and `254` (inclusive).
+      #   Defaults to `39`.
+      #
+      #   @return [Integer, nil]
+      optional :max_token_length, Integer
+
       # @!attribute remove_stopwords
       #   Removes common words from the text based on language. Defaults to `true` (i.e.
       #   remove common words).
@@ -48,7 +56,7 @@ module Turbopuffer
       #   @return [Symbol, Turbopuffer::Models::Tokenizer, nil]
       optional :tokenizer, enum: -> { Turbopuffer::Tokenizer }
 
-      # @!method initialize(b: nil, case_sensitive: nil, k1: nil, language: nil, remove_stopwords: nil, stemming: nil, tokenizer: nil)
+      # @!method initialize(b: nil, case_sensitive: nil, k1: nil, language: nil, max_token_length: nil, remove_stopwords: nil, stemming: nil, tokenizer: nil)
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::FullTextSearchConfig} for more details.
       #
@@ -62,6 +70,8 @@ module Turbopuffer
       #
       #   @param language [Symbol, Turbopuffer::Models::Language] Describes the language of a text attribute. Defaults to `english`.
       #
+      #   @param max_token_length [Integer] Maximum length of a token in bytes. Tokens larger than this value during tokeniz
+      #
       #   @param remove_stopwords [Boolean] Removes common words from the text based on language. Defaults to `true` (i.e. r
       #
       #   @param stemming [Boolean] Language-specific stemming for the text. Defaults to `false` (i.e., do not stem)

data/lib/turbopuffer/models/namespace_explain_query_params.rb

@@ -0,0 +1,128 @@
+# frozen_string_literal: true
+
+module Turbopuffer
+  module Models
+    # @see Turbopuffer::Resources::Namespaces#explain_query
+    class NamespaceExplainQueryParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      # @!attribute namespace
+      #
+      #   @return [String, nil]
+      optional :namespace, String
+
+      # @!attribute aggregate_by
+      #   Aggregations to compute over all documents in the namespace that match the
+      #   filters.
+      #
+      #   @return [Hash{Symbol=>Object}, nil]
+      optional :aggregate_by, Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]
+
+      # @!attribute consistency
+      #   The consistency level for a query.
+      #
+      #   @return [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency, nil]
+      optional :consistency, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency }
+
+      # @!attribute distance_metric
+      #   A function used to calculate vector similarity.
+      #
+      #   @return [Symbol, Turbopuffer::Models::DistanceMetric, nil]
+      optional :distance_metric, enum: -> { Turbopuffer::DistanceMetric }
+
+      # @!attribute exclude_attributes
+      #   List of attribute names to exclude from the response. All other attributes will
+      #   be included in the response.
+      #
+      #   @return [Array<String>, nil]
+      optional :exclude_attributes, Turbopuffer::Internal::Type::ArrayOf[String]
+
+      # @!attribute filters
+      #   Exact filters for attributes to refine search results for. Think of it as a SQL
+      #   WHERE clause.
+      #
+      #   @return [Object, nil]
+      optional :filters, Turbopuffer::Internal::Type::Unknown
+
+      # @!attribute include_attributes
+      #   Whether to include attributes in the response.
+      #
+      #   @return [Boolean, Array<String>, nil]
+      optional :include_attributes, union: -> { Turbopuffer::IncludeAttributes }
+
+      # @!attribute rank_by
+      #   How to rank the documents in the namespace.
+      #
+      #   @return [Object, nil]
+      optional :rank_by, Turbopuffer::Internal::Type::Unknown
+
+      # @!attribute top_k
+      #   The number of results to return.
+      #
+      #   @return [Integer, nil]
+      optional :top_k, Integer
+
+      # @!attribute vector_encoding
+      #   The encoding to use for vectors in the response.
+      #
+      #   @return [Symbol, Turbopuffer::Models::VectorEncoding, nil]
+      optional :vector_encoding, enum: -> { Turbopuffer::VectorEncoding }
+
+      # @!method initialize(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, include_attributes: nil, rank_by: nil, top_k: nil, vector_encoding: nil, request_options: {})
+      #   Some parameter documentations has been truncated, see
+      #   {Turbopuffer::Models::NamespaceExplainQueryParams} for more details.
+      #
+      #   @param namespace [String]
+      #
+      #   @param aggregate_by [Hash{Symbol=>Object}] Aggregations to compute over all documents in the namespace that match the filte
+      #
+      #   @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] The consistency level for a query.
+      #
+      #   @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] A function used to calculate vector similarity.
+      #
+      #   @param exclude_attributes [Array<String>] List of attribute names to exclude from the response. All other attributes will
+      #
+      #   @param filters [Object] Exact filters for attributes to refine search results for. Think of it as a SQL
+      #
+      #   @param include_attributes [Boolean, Array<String>] Whether to include attributes in the response.
+      #
+      #   @param rank_by [Object] How to rank the documents in the namespace.
+      #
+      #   @param top_k [Integer] The number of results to return.
+      #
+      #   @param vector_encoding [Symbol, Turbopuffer::Models::VectorEncoding] The encoding to use for vectors in the response.
+      #
+      #   @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}]
+
+      class Consistency < Turbopuffer::Internal::Type::BaseModel
+        # @!attribute level
+        #   The query's consistency level.
+        #
+        #   @return [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level, nil]
+        optional :level, enum: -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Level }
+
+        # @!method initialize(level: nil)
+        #   The consistency level for a query.
+        #
+        #   @param level [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level] The query's consistency level.
+
+        # The query's consistency level.
+        #
+        # @see Turbopuffer::Models::NamespaceExplainQueryParams::Consistency#level
+        module Level
+          extend Turbopuffer::Internal::Type::Enum
+
+          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+          STRONG = :strong
+
+          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+          EVENTUAL = :eventual
+
+          # @!method self.values
+          #   @return [Array<Symbol>]
+        end
+      end
+    end
+  end
+end

data/lib/turbopuffer/models/namespace_explain_query_response.rb

@@ -0,0 +1,19 @@
+# frozen_string_literal: true
+
+module Turbopuffer
+  module Models
+    # @see Turbopuffer::Resources::Namespaces#explain_query
+    class NamespaceExplainQueryResponse < Turbopuffer::Internal::Type::BaseModel
+      # @!attribute plan_text
+      #   The textual representation of the query plan.
+      #
+      #   @return [String, nil]
+      optional :plan_text, String
+
+      # @!method initialize(plan_text: nil)
+      #   The response to a successful query explain.
+      #
+      #   @param plan_text [String] The textual representation of the query plan.
+    end
+  end
+end

data/lib/turbopuffer/models.rb

@@ -63,6 +63,8 @@ module Turbopuffer
 
   NamespaceDeleteAllParams = Turbopuffer::Models::NamespaceDeleteAllParams
 
+  NamespaceExplainQueryParams = Turbopuffer::Models::NamespaceExplainQueryParams
+
   NamespaceHintCacheWarmParams = Turbopuffer::Models::NamespaceHintCacheWarmParams
 
   NamespaceMetadata = Turbopuffer::Models::NamespaceMetadata

data/lib/turbopuffer/resources/namespaces.rb

@@ -28,6 +28,53 @@ module Turbopuffer
         )
       end
 
+      # Some parameter documentations has been truncated, see
+      # {Turbopuffer::Models::NamespaceExplainQueryParams} for more details.
+      #
+      # Explain a query plan.
+      #
+      # @overload explain_query(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, include_attributes: nil, rank_by: nil, top_k: nil, vector_encoding: nil, request_options: {})
+      #
+      # @param namespace [String] Path param: The name of the namespace.
+      #
+      # @param aggregate_by [Hash{Symbol=>Object}] Body param: Aggregations to compute over all documents in the namespace that mat
+      #
+      # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] Body param: The consistency level for a query.
+      #
+      # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
+      #
+      # @param exclude_attributes [Array<String>] Body param: List of attribute names to exclude from the response. All other attr
+      #
+      # @param filters [Object] Body param: Exact filters for attributes to refine search results for. Think of
+      #
+      # @param include_attributes [Boolean, Array<String>] Body param: Whether to include attributes in the response.
+      #
+      # @param rank_by [Object] Body param: How to rank the documents in the namespace.
+      #
+      # @param top_k [Integer] Body param: The number of results to return.
+      #
+      # @param vector_encoding [Symbol, Turbopuffer::Models::VectorEncoding] Body param: The encoding to use for vectors in the response.
+      #
+      # @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil]
+      #
+      # @return [Turbopuffer::Models::NamespaceExplainQueryResponse]
+      #
+      # @see Turbopuffer::Models::NamespaceExplainQueryParams
+      def explain_query(params = {})
+        parsed, options = Turbopuffer::NamespaceExplainQueryParams.dump_request(params)
+        namespace =
+          parsed.delete(:namespace) do
+            @client.default_namespace
+          end
+        @client.request(
+          method: :post,
+          path: ["v2/namespaces/%1$s/explain_query", namespace],
+          body: parsed,
+          model: Turbopuffer::Models::NamespaceExplainQueryResponse,
+          options: options
+        )
+      end
+
       # Warm the cache for a namespace.
       #
       # @overload hint_cache_warm(namespace: nil, request_options: {})

data/lib/turbopuffer/version.rb

@@ -1,5 +1,5 @@
 # frozen_string_literal: true
 
 module Turbopuffer
-  VERSION = "0.2.3"
+  VERSION = "0.2.4"
 end

data/lib/turbopuffer.rb

@@ -64,6 +64,8 @@ require_relative "turbopuffer/models/include_attributes"
 require_relative "turbopuffer/models/language"
 require_relative "turbopuffer/models/namespace_delete_all_params"
 require_relative "turbopuffer/models/namespace_delete_all_response"
+require_relative "turbopuffer/models/namespace_explain_query_params"
+require_relative "turbopuffer/models/namespace_explain_query_response"
 require_relative "turbopuffer/models/namespace_hint_cache_warm_params"
 require_relative "turbopuffer/models/namespace_hint_cache_warm_response"
 require_relative "turbopuffer/models/namespace_metadata"

data/rbi/turbopuffer/internal/transport/base_client.rbi

@@ -218,7 +218,7 @@ module Turbopuffer
             send_retry_header: T::Boolean
           ).returns([Integer, Net::HTTPResponse, T::Enumerable[String]])
         end
-        private def send_request(
+        def send_request(
           request,
           redirect_count:,
           retry_count:,

data/rbi/turbopuffer/models/full_text_search_config.rbi

@@ -40,6 +40,15 @@ module Turbopuffer
       sig { params(language: Turbopuffer::Language::OrSymbol).void }
       attr_writer :language
 
+      # Maximum length of a token in bytes. Tokens larger than this value during
+      # tokenization will be filtered out. Has to be between `1` and `254` (inclusive).
+      # Defaults to `39`.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :max_token_length
+
+      sig { params(max_token_length: Integer).void }
+      attr_writer :max_token_length
+
       # Removes common words from the text based on language. Defaults to `true` (i.e.
       # remove common words).
       sig { returns(T.nilable(T::Boolean)) }
@@ -70,6 +79,7 @@ module Turbopuffer
           case_sensitive: T::Boolean,
           k1: Float,
           language: Turbopuffer::Language::OrSymbol,
+          max_token_length: Integer,
           remove_stopwords: T::Boolean,
           stemming: T::Boolean,
           tokenizer: Turbopuffer::Tokenizer::OrSymbol
@@ -85,6 +95,10 @@ module Turbopuffer
         k1: nil,
         # Describes the language of a text attribute. Defaults to `english`.
         language: nil,
+        # Maximum length of a token in bytes. Tokens larger than this value during
+        # tokenization will be filtered out. Has to be between `1` and `254` (inclusive).
+        # Defaults to `39`.
+        max_token_length: nil,
         # Removes common words from the text based on language. Defaults to `true` (i.e.
         # remove common words).
         remove_stopwords: nil,
@@ -103,6 +117,7 @@ module Turbopuffer
             case_sensitive: T::Boolean,
             k1: Float,
             language: Turbopuffer::Language::OrSymbol,
+            max_token_length: Integer,
             remove_stopwords: T::Boolean,
             stemming: T::Boolean,
             tokenizer: Turbopuffer::Tokenizer::OrSymbol

data/rbi/turbopuffer/models/namespace_explain_query_params.rbi

@@ -0,0 +1,260 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceExplainQueryParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::NamespaceExplainQueryParams,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      sig { returns(T.nilable(String)) }
+      attr_reader :namespace
+
+      sig { params(namespace: String).void }
+      attr_writer :namespace
+
+      # Aggregations to compute over all documents in the namespace that match the
+      # filters.
+      sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
+      attr_reader :aggregate_by
+
+      sig { params(aggregate_by: T::Hash[Symbol, T.anything]).void }
+      attr_writer :aggregate_by
+
+      # The consistency level for a query.
+      sig do
+        returns(
+          T.nilable(Turbopuffer::NamespaceExplainQueryParams::Consistency)
+        )
+      end
+      attr_reader :consistency
+
+      sig do
+        params(
+          consistency:
+            Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash
+        ).void
+      end
+      attr_writer :consistency
+
+      # A function used to calculate vector similarity.
+      sig { returns(T.nilable(Turbopuffer::DistanceMetric::OrSymbol)) }
+      attr_reader :distance_metric
+
+      sig do
+        params(distance_metric: Turbopuffer::DistanceMetric::OrSymbol).void
+      end
+      attr_writer :distance_metric
+
+      # List of attribute names to exclude from the response. All other attributes will
+      # be included in the response.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :exclude_attributes
+
+      sig { params(exclude_attributes: T::Array[String]).void }
+      attr_writer :exclude_attributes
+
+      # Exact filters for attributes to refine search results for. Think of it as a SQL
+      # WHERE clause.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :filters
+
+      sig { params(filters: T.anything).void }
+      attr_writer :filters
+
+      # Whether to include attributes in the response.
+      sig { returns(T.nilable(Turbopuffer::IncludeAttributes::Variants)) }
+      attr_reader :include_attributes
+
+      sig do
+        params(
+          include_attributes: Turbopuffer::IncludeAttributes::Variants
+        ).void
+      end
+      attr_writer :include_attributes
+
+      # How to rank the documents in the namespace.
+      sig { returns(T.nilable(T.anything)) }
+      attr_reader :rank_by
+
+      sig { params(rank_by: T.anything).void }
+      attr_writer :rank_by
+
+      # The number of results to return.
+      sig { returns(T.nilable(Integer)) }
+      attr_reader :top_k
+
+      sig { params(top_k: Integer).void }
+      attr_writer :top_k
+
+      # The encoding to use for vectors in the response.
+      sig { returns(T.nilable(Turbopuffer::VectorEncoding::OrSymbol)) }
+      attr_reader :vector_encoding
+
+      sig do
+        params(vector_encoding: Turbopuffer::VectorEncoding::OrSymbol).void
+      end
+      attr_writer :vector_encoding
+
+      sig do
+        params(
+          namespace: String,
+          aggregate_by: T::Hash[Symbol, T.anything],
+          consistency:
+            Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash,
+          distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+          exclude_attributes: T::Array[String],
+          filters: T.anything,
+          include_attributes: Turbopuffer::IncludeAttributes::Variants,
+          rank_by: T.anything,
+          top_k: Integer,
+          vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(T.attached_class)
+      end
+      def self.new(
+        namespace: nil,
+        # Aggregations to compute over all documents in the namespace that match the
+        # filters.
+        aggregate_by: nil,
+        # The consistency level for a query.
+        consistency: nil,
+        # A function used to calculate vector similarity.
+        distance_metric: nil,
+        # List of attribute names to exclude from the response. All other attributes will
+        # be included in the response.
+        exclude_attributes: nil,
+        # Exact filters for attributes to refine search results for. Think of it as a SQL
+        # WHERE clause.
+        filters: nil,
+        # Whether to include attributes in the response.
+        include_attributes: nil,
+        # How to rank the documents in the namespace.
+        rank_by: nil,
+        # The number of results to return.
+        top_k: nil,
+        # The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
+      sig do
+        override.returns(
+          {
+            namespace: String,
+            aggregate_by: T::Hash[Symbol, T.anything],
+            consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
+            distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+            exclude_attributes: T::Array[String],
+            filters: T.anything,
+            include_attributes: Turbopuffer::IncludeAttributes::Variants,
+            rank_by: T.anything,
+            top_k: Integer,
+            vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+            request_options: Turbopuffer::RequestOptions
+          }
+        )
+      end
+      def to_hash
+      end
+
+      class Consistency < Turbopuffer::Internal::Type::BaseModel
+        OrHash =
+          T.type_alias do
+            T.any(
+              Turbopuffer::NamespaceExplainQueryParams::Consistency,
+              Turbopuffer::Internal::AnyHash
+            )
+          end
+
+        # The query's consistency level.
+        sig do
+          returns(
+            T.nilable(
+              Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
+            )
+          )
+        end
+        attr_reader :level
+
+        sig do
+          params(
+            level:
+              Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
+          ).void
+        end
+        attr_writer :level
+
+        # The consistency level for a query.
+        sig do
+          params(
+            level:
+              Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
+          ).returns(T.attached_class)
+        end
+        def self.new(
+          # The query's consistency level.
+          level: nil
+        )
+        end
+
+        sig do
+          override.returns(
+            {
+              level:
+                Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
+            }
+          )
+        end
+        def to_hash
+        end
+
+        # The query's consistency level.
+        module Level
+          extend Turbopuffer::Internal::Type::Enum
+
+          TaggedSymbol =
+            T.type_alias do
+              T.all(
+                Symbol,
+                Turbopuffer::NamespaceExplainQueryParams::Consistency::Level
+              )
+            end
+          OrSymbol = T.type_alias { T.any(Symbol, String) }
+
+          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+          STRONG =
+            T.let(
+              :strong,
+              Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
+            )
+
+          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+          EVENTUAL =
+            T.let(
+              :eventual,
+              Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
+            )
+
+          sig do
+            override.returns(
+              T::Array[
+                Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
+              ]
+            )
+          end
+          def self.values
+          end
+        end
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models/namespace_explain_query_response.rbi

@@ -0,0 +1,34 @@
+# typed: strong
+
+module Turbopuffer
+  module Models
+    class NamespaceExplainQueryResponse < Turbopuffer::Internal::Type::BaseModel
+      OrHash =
+        T.type_alias do
+          T.any(
+            Turbopuffer::Models::NamespaceExplainQueryResponse,
+            Turbopuffer::Internal::AnyHash
+          )
+        end
+
+      # The textual representation of the query plan.
+      sig { returns(T.nilable(String)) }
+      attr_reader :plan_text
+
+      sig { params(plan_text: String).void }
+      attr_writer :plan_text
+
+      # The response to a successful query explain.
+      sig { params(plan_text: String).returns(T.attached_class) }
+      def self.new(
+        # The textual representation of the query plan.
+        plan_text: nil
+      )
+      end
+
+      sig { override.returns({ plan_text: String }) }
+      def to_hash
+      end
+    end
+  end
+end

data/rbi/turbopuffer/models.rbi

@@ -25,6 +25,8 @@ module Turbopuffer
 
   NamespaceDeleteAllParams = Turbopuffer::Models::NamespaceDeleteAllParams
 
+  NamespaceExplainQueryParams = Turbopuffer::Models::NamespaceExplainQueryParams
+
   NamespaceHintCacheWarmParams =
     Turbopuffer::Models::NamespaceHintCacheWarmParams
 

data/rbi/turbopuffer/resources/namespaces.rbi

@@ -17,6 +17,51 @@ module Turbopuffer
       )
       end
 
+      # Explain a query plan.
+      sig do
+        params(
+          namespace: String,
+          aggregate_by: T::Hash[Symbol, T.anything],
+          consistency:
+            Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash,
+          distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
+          exclude_attributes: T::Array[String],
+          filters: T.anything,
+          include_attributes: Turbopuffer::IncludeAttributes::Variants,
+          rank_by: T.anything,
+          top_k: Integer,
+          vector_encoding: Turbopuffer::VectorEncoding::OrSymbol,
+          request_options: Turbopuffer::RequestOptions::OrHash
+        ).returns(Turbopuffer::Models::NamespaceExplainQueryResponse)
+      end
+      def explain_query(
+        # Path param: The name of the namespace.
+        namespace: nil,
+        # Body param: Aggregations to compute over all documents in the namespace that
+        # match the filters.
+        aggregate_by: nil,
+        # Body param: The consistency level for a query.
+        consistency: nil,
+        # Body param: A function used to calculate vector similarity.
+        distance_metric: nil,
+        # Body param: List of attribute names to exclude from the response. All other
+        # attributes will be included in the response.
+        exclude_attributes: nil,
+        # Body param: Exact filters for attributes to refine search results for. Think of
+        # it as a SQL WHERE clause.
+        filters: nil,
+        # Body param: Whether to include attributes in the response.
+        include_attributes: nil,
+        # Body param: How to rank the documents in the namespace.
+        rank_by: nil,
+        # Body param: The number of results to return.
+        top_k: nil,
+        # Body param: The encoding to use for vectors in the response.
+        vector_encoding: nil,
+        request_options: {}
+      )
+      end
+
       # Warm the cache for a namespace.
       sig do
         params(

data/sig/turbopuffer/internal/transport/base_client.rbs

@@ -99,7 +99,7 @@ module Turbopuffer
           retry_count: Integer
         ) -> Float
 
-        private def send_request: (
+        def send_request: (
           Turbopuffer::Internal::Transport::BaseClient::request_input request,
           redirect_count: Integer,
           retry_count: Integer,

data/sig/turbopuffer/models/full_text_search_config.rbs

@@ -6,6 +6,7 @@ module Turbopuffer
         case_sensitive: bool,
         :k1 => Float,
         language: Turbopuffer::Models::language,
+        max_token_length: Integer,
         remove_stopwords: bool,
         stemming: bool,
         tokenizer: Turbopuffer::Models::tokenizer
@@ -30,6 +31,10 @@ module Turbopuffer
         Turbopuffer::Models::language
       ) -> Turbopuffer::Models::language
 
+      attr_reader max_token_length: Integer?
+
+      def max_token_length=: (Integer) -> Integer
+
       attr_reader remove_stopwords: bool?
 
       def remove_stopwords=: (bool) -> bool
@@ -49,6 +54,7 @@ module Turbopuffer
         ?case_sensitive: bool,
         ?k1: Float,
         ?language: Turbopuffer::Models::language,
+        ?max_token_length: Integer,
         ?remove_stopwords: bool,
         ?stemming: bool,
         ?tokenizer: Turbopuffer::Models::tokenizer
@@ -59,6 +65,7 @@ module Turbopuffer
         case_sensitive: bool,
         :k1 => Float,
         language: Turbopuffer::Models::language,
+        max_token_length: Integer,
         remove_stopwords: bool,
         stemming: bool,
         tokenizer: Turbopuffer::Models::tokenizer

data/sig/turbopuffer/models/namespace_explain_query_params.rbs

@@ -0,0 +1,134 @@
+module Turbopuffer
+  module Models
+    type namespace_explain_query_params =
+      {
+        namespace: String,
+        aggregate_by: ::Hash[Symbol, top],
+        consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
+        distance_metric: Turbopuffer::Models::distance_metric,
+        exclude_attributes: ::Array[String],
+        filters: top,
+        include_attributes: Turbopuffer::Models::include_attributes,
+        rank_by: top,
+        top_k: Integer,
+        vector_encoding: Turbopuffer::Models::vector_encoding
+      }
+      & Turbopuffer::Internal::Type::request_parameters
+
+    class NamespaceExplainQueryParams < Turbopuffer::Internal::Type::BaseModel
+      extend Turbopuffer::Internal::Type::RequestParameters::Converter
+      include Turbopuffer::Internal::Type::RequestParameters
+
+      attr_reader namespace: String?
+
+      def namespace=: (String) -> String
+
+      attr_reader aggregate_by: ::Hash[Symbol, top]?
+
+      def aggregate_by=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
+
+      attr_reader consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency?
+
+      def consistency=: (
+        Turbopuffer::NamespaceExplainQueryParams::Consistency
+      ) -> Turbopuffer::NamespaceExplainQueryParams::Consistency
+
+      attr_reader distance_metric: Turbopuffer::Models::distance_metric?
+
+      def distance_metric=: (
+        Turbopuffer::Models::distance_metric
+      ) -> Turbopuffer::Models::distance_metric
+
+      attr_reader exclude_attributes: ::Array[String]?
+
+      def exclude_attributes=: (::Array[String]) -> ::Array[String]
+
+      attr_reader filters: top?
+
+      def filters=: (top) -> top
+
+      attr_reader include_attributes: Turbopuffer::Models::include_attributes?
+
+      def include_attributes=: (
+        Turbopuffer::Models::include_attributes
+      ) -> Turbopuffer::Models::include_attributes
+
+      attr_reader rank_by: top?
+
+      def rank_by=: (top) -> top
+
+      attr_reader top_k: Integer?
+
+      def top_k=: (Integer) -> Integer
+
+      attr_reader vector_encoding: Turbopuffer::Models::vector_encoding?
+
+      def vector_encoding=: (
+        Turbopuffer::Models::vector_encoding
+      ) -> Turbopuffer::Models::vector_encoding
+
+      def initialize: (
+        ?namespace: String,
+        ?aggregate_by: ::Hash[Symbol, top],
+        ?consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
+        ?distance_metric: Turbopuffer::Models::distance_metric,
+        ?exclude_attributes: ::Array[String],
+        ?filters: top,
+        ?include_attributes: Turbopuffer::Models::include_attributes,
+        ?rank_by: top,
+        ?top_k: Integer,
+        ?vector_encoding: Turbopuffer::Models::vector_encoding,
+        ?request_options: Turbopuffer::request_opts
+      ) -> void
+
+      def to_hash: -> {
+        namespace: String,
+        aggregate_by: ::Hash[Symbol, top],
+        consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
+        distance_metric: Turbopuffer::Models::distance_metric,
+        exclude_attributes: ::Array[String],
+        filters: top,
+        include_attributes: Turbopuffer::Models::include_attributes,
+        rank_by: top,
+        top_k: Integer,
+        vector_encoding: Turbopuffer::Models::vector_encoding,
+        request_options: Turbopuffer::RequestOptions
+      }
+
+      type consistency =
+        {
+          level: Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level
+        }
+
+      class Consistency < Turbopuffer::Internal::Type::BaseModel
+        attr_reader level: Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level?
+
+        def level=: (
+          Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level
+        ) -> Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level
+
+        def initialize: (
+          ?level: Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level
+        ) -> void
+
+        def to_hash: -> {
+          level: Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level
+        }
+
+        type level = :strong | :eventual
+
+        module Level
+          extend Turbopuffer::Internal::Type::Enum
+
+          # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
+          STRONG: :strong
+
+          # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
+          EVENTUAL: :eventual
+
+          def self?.values: -> ::Array[Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::level]
+        end
+      end
+    end
+  end
+end

data/sig/turbopuffer/models/namespace_explain_query_response.rbs

@@ -0,0 +1,15 @@
+module Turbopuffer
+  module Models
+    type namespace_explain_query_response = { plan_text: String }
+
+    class NamespaceExplainQueryResponse < Turbopuffer::Internal::Type::BaseModel
+      attr_reader plan_text: String?
+
+      def plan_text=: (String) -> String
+
+      def initialize: (?plan_text: String) -> void
+
+      def to_hash: -> { plan_text: String }
+    end
+  end
+end

data/sig/turbopuffer/models.rbs

@@ -23,6 +23,8 @@ module Turbopuffer
 
   class NamespaceDeleteAllParams = Turbopuffer::Models::NamespaceDeleteAllParams
 
+  class NamespaceExplainQueryParams = Turbopuffer::Models::NamespaceExplainQueryParams
+
   class NamespaceHintCacheWarmParams = Turbopuffer::Models::NamespaceHintCacheWarmParams
 
   class NamespaceMetadata = Turbopuffer::Models::NamespaceMetadata

data/sig/turbopuffer/resources/namespaces.rbs

@@ -6,6 +6,20 @@ module Turbopuffer
         ?request_options: Turbopuffer::request_opts
       ) -> Turbopuffer::Models::NamespaceDeleteAllResponse
 
+      def explain_query: (
+        ?namespace: String,
+        ?aggregate_by: ::Hash[Symbol, top],
+        ?consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
+        ?distance_metric: Turbopuffer::Models::distance_metric,
+        ?exclude_attributes: ::Array[String],
+        ?filters: top,
+        ?include_attributes: Turbopuffer::Models::include_attributes,
+        ?rank_by: top,
+        ?top_k: Integer,
+        ?vector_encoding: Turbopuffer::Models::vector_encoding,
+        ?request_options: Turbopuffer::request_opts
+      ) -> Turbopuffer::Models::NamespaceExplainQueryResponse
+
       def hint_cache_warm: (
         ?namespace: String,
         ?request_options: Turbopuffer::request_opts

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbopuffer-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.3
+  version: 0.2.4
 platform: ruby
 authors:
 - Turbopuffer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-07-29 00:00:00.000000000 Z
+date: 2025-08-08 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool
@@ -69,6 +69,8 @@ files:
 - lib/turbopuffer/models/language.rb
 - lib/turbopuffer/models/namespace_delete_all_params.rb
 - lib/turbopuffer/models/namespace_delete_all_response.rb
+- lib/turbopuffer/models/namespace_explain_query_params.rb
+- lib/turbopuffer/models/namespace_explain_query_response.rb
 - lib/turbopuffer/models/namespace_hint_cache_warm_params.rb
 - lib/turbopuffer/models/namespace_hint_cache_warm_response.rb
 - lib/turbopuffer/models/namespace_metadata.rb
@@ -132,6 +134,8 @@ files:
 - rbi/turbopuffer/models/language.rbi
 - rbi/turbopuffer/models/namespace_delete_all_params.rbi
 - rbi/turbopuffer/models/namespace_delete_all_response.rbi
+- rbi/turbopuffer/models/namespace_explain_query_params.rbi
+- rbi/turbopuffer/models/namespace_explain_query_response.rbi
 - rbi/turbopuffer/models/namespace_hint_cache_warm_params.rbi
 - rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi
 - rbi/turbopuffer/models/namespace_metadata.rbi
@@ -194,6 +198,8 @@ files:
 - sig/turbopuffer/models/language.rbs
 - sig/turbopuffer/models/namespace_delete_all_params.rbs
 - sig/turbopuffer/models/namespace_delete_all_response.rbs
+- sig/turbopuffer/models/namespace_explain_query_params.rbs
+- sig/turbopuffer/models/namespace_explain_query_response.rbs
 - sig/turbopuffer/models/namespace_hint_cache_warm_params.rbs
 - sig/turbopuffer/models/namespace_hint_cache_warm_response.rbs
 - sig/turbopuffer/models/namespace_metadata.rbs