turbopuffer-ruby 0.2.4 → 0.2.6

checksums.yaml

@@ -1,7 +1,7 @@
 ---
 SHA256:
-  metadata.gz: 4cdba184c47706f13e46349844edd154024ecb50b0cd898b1e472bee7122595f
-  data.tar.gz: d2a2652222e2e672c9069bc965ece1bac43351804670331410aa91462eaa1f7c
+  metadata.gz: e68ecf643e3ef570edf2c61bfb412c27d9c2c17fbaf5e4c614c7d5aa2afa3e05
+  data.tar.gz: '095f4ccefed27b4a1479ecdb5c10a88a7a2017f1aa4f25188c321b206765aba4'
 SHA512:
-  metadata.gz: 0c42de89acf1dc7246fb9ef1ad915bb0e5d0c1bdb74b1d842851d3eeb576ed8ed3cc2047d6d255053b7a21bd7561dbf6a757620ff2ec9099ada4c9a98ddfc487
-  data.tar.gz: 25b6fdfc5c41998e5bb415ecebd39f6b8c6583047bf44a27714363044ffa7c70d86d53ae7e17379514885e8c4ac2191c1e7e292ea0d9aecb8e6b273ded29452d
+  metadata.gz: febffe23d0069251a67e807e34cb502bf9a40bd819e755c72a7c6c369898143145767c6fb8362c2e66138247abc9886dd04154c37be11aeaf20cb05230249314
+  data.tar.gz: d6be41a93adaf04d4c3eacb77ff1e9efff4fe2d38ad616f5d70da99b5e8834f31c9babded64d1a1f84645d6a4fc9146bbb625647890ad1adbe1683ecaf24b41b

data/CHANGELOG.md

@@ -1,5 +1,29 @@
 # Changelog
 
+## 0.2.6 (2025-08-18)
+
+Full Changelog: [v0.2.5...v0.2.6](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.5...v0.2.6)
+
+### Bug Fixes
+
+* **api:** add support for `group_by` query parameter ([c4e6261](https://github.com/turbopuffer/turbopuffer-ruby/commit/c4e626148df5642d654e5ae739d07588fcd4ad5d))
+* remove 200 error code for hint_cache_warm API call (always 202 now) ([bbd6d75](https://github.com/turbopuffer/turbopuffer-ruby/commit/bbd6d759e25a1b7b4dd8e3208acc1089f1d35f36))
+
+
+### Chores
+
+* **internal:** codegen related update ([880022b](https://github.com/turbopuffer/turbopuffer-ruby/commit/880022bea36595da811d14bd5a2e610624b283eb))
+
+## 0.2.5 (2025-08-11)
+
+Full Changelog: [v0.2.4...v0.2.5](https://github.com/turbopuffer/turbopuffer-ruby/compare/v0.2.4...v0.2.5)
+
+### Chores
+
+* collect metadata from type DSL ([79bb9bd](https://github.com/turbopuffer/turbopuffer-ruby/commit/79bb9bd39297006af6693580f09d35c1c801500f))
+* **internal:** update comment in script ([0b151c0](https://github.com/turbopuffer/turbopuffer-ruby/commit/0b151c035ce5ba8785c3499247843428ba8267bd))
+* update @stainless-api/prism-cli to v5.15.0 ([bb9a4b1](https://github.com/turbopuffer/turbopuffer-ruby/commit/bb9a4b1de0ac931671b2abeefa9c4cf8a67bae63))
+
 ## 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)

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.4"
+gem "turbopuffer-ruby", "~> 0.2.6"
 ```
 
 <!-- x-release-please-end -->

data/lib/turbopuffer/internal/type/array_of.rb

@@ -148,6 +148,7 @@ module Turbopuffer
         #   @option spec [Boolean] :"nil?"
         def initialize(type_info, spec = {})
           @item_type_fn = Turbopuffer::Internal::Type::Converter.type_info(type_info || spec)
+          @meta = Turbopuffer::Internal::Type::Converter.meta_info(type_info, spec)
           @nilable = spec.fetch(:nil?, false)
         end
 

data/lib/turbopuffer/internal/type/base_model.rb

@@ -52,6 +52,7 @@ module Turbopuffer
           #
           #   @option spec [Boolean] :"nil?"
           private def add_field(name_sym, required:, type_info:, spec:)
+            meta = Turbopuffer::Internal::Type::Converter.meta_info(type_info, spec)
             type_fn, info =
               case type_info
               in Proc | Turbopuffer::Internal::Type::Converter | Class
@@ -81,7 +82,8 @@ module Turbopuffer
                 required: required,
                 nilable: nilable,
                 const: const,
-                type_fn: type_fn
+                type_fn: type_fn,
+                meta: meta
               }
 
             define_method(setter) do |value|

data/lib/turbopuffer/internal/type/converter.rb

@@ -98,6 +98,33 @@ module Turbopuffer
             end
           end
 
+          # @api private
+          #
+          # @param type_info [Hash{Symbol=>Object}, Proc, Turbopuffer::Internal::Type::Converter, Class] .
+          #
+          #   @option type_info [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+          #
+          #   @option type_info [Proc] :enum
+          #
+          #   @option type_info [Proc] :union
+          #
+          #   @option type_info [Boolean] :"nil?"
+          #
+          # @param spec [Hash{Symbol=>Object}, Proc, Turbopuffer::Internal::Type::Converter, Class] .
+          #
+          #   @option spec [NilClass, TrueClass, FalseClass, Integer, Float, Symbol] :const
+          #
+          #   @option spec [Proc] :enum
+          #
+          #   @option spec [Proc] :union
+          #
+          #   @option spec [Boolean] :"nil?"
+          #
+          # @return [Hash{Symbol=>Object}]
+          def meta_info(type_info, spec)
+            [spec, type_info].grep(Hash).first.to_h.except(:const, :enum, :union, :nil?)
+          end
+
           # @api private
           #
           # @param translate_names [Boolean]

data/lib/turbopuffer/internal/type/hash_of.rb

@@ -168,6 +168,7 @@ module Turbopuffer
         #   @option spec [Boolean] :"nil?"
         def initialize(type_info, spec = {})
           @item_type_fn = Turbopuffer::Internal::Type::Converter.type_info(type_info || spec)
+          @meta = Turbopuffer::Internal::Type::Converter.meta_info(type_info, spec)
           @nilable = spec.fetch(:nil?, false)
         end
 

data/lib/turbopuffer/internal/type/union.rb

@@ -23,20 +23,20 @@ module Turbopuffer
         #
         # All of the specified variant info for this union.
         #
-        # @return [Array<Array(Symbol, Proc)>]
+        # @return [Array<Array(Symbol, Proc, Hash{Symbol=>Object})>]
         private def known_variants = (@known_variants ||= [])
 
         # @api private
         #
-        # @return [Array<Array(Symbol, Object)>]
+        # @return [Array<Array(Symbol, Object, Hash{Symbol=>Object})>]
         protected def derefed_variants
-          known_variants.map { |key, variant_fn| [key, variant_fn.call] }
+          known_variants.map { |key, variant_fn, meta| [key, variant_fn.call, meta] }
         end
 
         # All of the specified variants for this union.
         #
         # @return [Array<Object>]
-        def variants = derefed_variants.map(&:last)
+        def variants = derefed_variants.map { _2 }
 
         # @api private
         #
@@ -62,12 +62,13 @@ module Turbopuffer
         #
         #   @option spec [Boolean] :"nil?"
         private def variant(key, spec = nil)
+          meta = Turbopuffer::Internal::Type::Converter.meta_info(nil, spec)
           variant_info =
             case key
             in Symbol
-              [key, Turbopuffer::Internal::Type::Converter.type_info(spec)]
+              [key, Turbopuffer::Internal::Type::Converter.type_info(spec), meta]
             in Proc | Turbopuffer::Internal::Type::Converter | Class | Hash
-              [nil, Turbopuffer::Internal::Type::Converter.type_info(key)]
+              [nil, Turbopuffer::Internal::Type::Converter.type_info(key), meta]
             end
 
           known_variants << variant_info
@@ -90,7 +91,8 @@ module Turbopuffer
             return nil if key == Turbopuffer::Internal::OMIT
 
             key = key.to_sym if key.is_a?(String)
-            known_variants.find { |k,| k == key }&.last&.call
+            _, found = known_variants.find { |k,| k == key }
+            found&.call
           else
             nil
           end

data/lib/turbopuffer/models/namespace_explain_query_params.rb

@@ -45,6 +45,13 @@ module Turbopuffer
       #   @return [Object, nil]
       optional :filters, Turbopuffer::Internal::Type::Unknown
 
+      # @!attribute group_by
+      #   Groups documents by the specified attributes (the "group key") before computing
+      #   aggregates. Aggregates are computed separately for each group.
+      #
+      #   @return [Array<String>, nil]
+      optional :group_by, Turbopuffer::Internal::Type::ArrayOf[String]
+
       # @!attribute include_attributes
       #   Whether to include attributes in the response.
       #
@@ -69,7 +76,7 @@ module Turbopuffer
       #   @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: {})
+      # @!method initialize(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: 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.
       #
@@ -85,6 +92,8 @@ module Turbopuffer
       #
       #   @param filters [Object] Exact filters for attributes to refine search results for. Think of it as a SQL
       #
+      #   @param group_by [Array<String>] Groups documents by the specified attributes (the "group key") before computing
+      #
       #   @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.

data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb

@@ -7,20 +7,20 @@ module Turbopuffer
       # @!attribute status
       #   The status of the request.
       #
-      #   @return [Symbol, :OK]
-      required :status, const: :OK
+      #   @return [Symbol, :ACCEPTED]
+      required :status, const: :ACCEPTED
 
       # @!attribute message
       #
       #   @return [String, nil]
       optional :message, String
 
-      # @!method initialize(message: nil, status: :OK)
+      # @!method initialize(message: nil, status: :ACCEPTED)
       #   The response to a successful cache warm request.
       #
       #   @param message [String]
       #
-      #   @param status [Symbol, :OK] The status of the request.
+      #   @param status [Symbol, :ACCEPTED] The status of the request.
     end
   end
 end

data/lib/turbopuffer/models/namespace_multi_query_response.rb

@@ -32,6 +32,11 @@ module Turbopuffer
       #   @param results [Array<Turbopuffer::Models::NamespaceMultiQueryResponse::Result>]
 
       class Result < Turbopuffer::Internal::Type::BaseModel
+        # @!attribute aggregation_groups
+        #
+        #   @return [Array<Turbopuffer::Models::Row>, nil]
+        optional :aggregation_groups, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
+
         # @!attribute aggregations
         #
         #   @return [Hash{Symbol=>Object}, nil]
@@ -42,7 +47,8 @@ module Turbopuffer
         #   @return [Array<Turbopuffer::Models::Row>, nil]
         optional :rows, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
 
-        # @!method initialize(aggregations: nil, rows: nil)
+        # @!method initialize(aggregation_groups: nil, aggregations: nil, rows: nil)
+        #   @param aggregation_groups [Array<Turbopuffer::Models::Row>]
         #   @param aggregations [Hash{Symbol=>Object}]
         #   @param rows [Array<Turbopuffer::Models::Row>]
       end

data/lib/turbopuffer/models/namespace_query_params.rb

@@ -45,6 +45,13 @@ module Turbopuffer
       #   @return [Object, nil]
       optional :filters, Turbopuffer::Internal::Type::Unknown
 
+      # @!attribute group_by
+      #   Groups documents by the specified attributes (the "group key") before computing
+      #   aggregates. Aggregates are computed separately for each group.
+      #
+      #   @return [Array<String>, nil]
+      optional :group_by, Turbopuffer::Internal::Type::ArrayOf[String]
+
       # @!attribute include_attributes
       #   Whether to include attributes in the response.
       #
@@ -69,7 +76,7 @@ module Turbopuffer
       #   @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: {})
+      # @!method initialize(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: nil, include_attributes: nil, rank_by: nil, top_k: nil, vector_encoding: nil, request_options: {})
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::NamespaceQueryParams} for more details.
       #
@@ -85,6 +92,8 @@ module Turbopuffer
       #
       #   @param filters [Object] Exact filters for attributes to refine search results for. Think of it as a SQL
       #
+      #   @param group_by [Array<String>] Groups documents by the specified attributes (the "group key") before computing
+      #
       #   @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.

data/lib/turbopuffer/models/namespace_query_response.rb

@@ -16,6 +16,11 @@ module Turbopuffer
       #   @return [Turbopuffer::Models::QueryPerformance]
       required :performance, -> { Turbopuffer::QueryPerformance }
 
+      # @!attribute aggregation_groups
+      #
+      #   @return [Array<Turbopuffer::Models::Row>, nil]
+      optional :aggregation_groups, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
+
       # @!attribute aggregations
       #
       #   @return [Hash{Symbol=>Object}, nil]
@@ -26,13 +31,15 @@ module Turbopuffer
       #   @return [Array<Turbopuffer::Models::Row>, nil]
       optional :rows, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
 
-      # @!method initialize(billing:, performance:, aggregations: nil, rows: nil)
+      # @!method initialize(billing:, performance:, aggregation_groups: nil, aggregations: nil, rows: nil)
       #   The result of a query.
       #
       #   @param billing [Turbopuffer::Models::QueryBilling] The billing information for a query.
       #
       #   @param performance [Turbopuffer::Models::QueryPerformance] The performance information for a query.
       #
+      #   @param aggregation_groups [Array<Turbopuffer::Models::Row>]
+      #
       #   @param aggregations [Hash{Symbol=>Object}]
       #
       #   @param rows [Array<Turbopuffer::Models::Row>]

data/lib/turbopuffer/models/query.rb

@@ -30,6 +30,13 @@ module Turbopuffer
       #   @return [Object, nil]
       optional :filters, Turbopuffer::Internal::Type::Unknown
 
+      # @!attribute group_by
+      #   Groups documents by the specified attributes (the "group key") before computing
+      #   aggregates. Aggregates are computed separately for each group.
+      #
+      #   @return [Array<String>, nil]
+      optional :group_by, Turbopuffer::Internal::Type::ArrayOf[String]
+
       # @!attribute include_attributes
       #   Whether to include attributes in the response.
       #
@@ -48,7 +55,7 @@ module Turbopuffer
       #   @return [Integer, nil]
       optional :top_k, Integer
 
-      # @!method initialize(aggregate_by: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, include_attributes: nil, rank_by: nil, top_k: nil)
+      # @!method initialize(aggregate_by: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: nil, include_attributes: nil, rank_by: nil, top_k: nil)
       #   Some parameter documentations has been truncated, see
       #   {Turbopuffer::Models::Query} for more details.
       #
@@ -62,6 +69,8 @@ module Turbopuffer
       #
       #   @param filters [Object] Exact filters for attributes to refine search results for. Think of it as a SQL
       #
+      #   @param group_by [Array<String>] Groups documents by the specified attributes (the "group key") before computing
+      #
       #   @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.

data/lib/turbopuffer/resources/namespaces.rb

@@ -33,7 +33,7 @@ module Turbopuffer
       #
       # 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: {})
+      # @overload explain_query(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: 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.
       #
@@ -47,6 +47,8 @@ module Turbopuffer
       #
       # @param filters [Object] Body param: Exact filters for attributes to refine search results for. Think of
       #
+      # @param group_by [Array<String>] Body param: Groups documents by the specified attributes (the "group key") befor
+      #
       # @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.
@@ -162,7 +164,7 @@ module Turbopuffer
       #
       # Query, filter, full-text search and vector search documents.
       #
-      # @overload 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: {})
+      # @overload query(namespace: nil, aggregate_by: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: 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.
       #
@@ -176,6 +178,8 @@ module Turbopuffer
       #
       # @param filters [Object] Body param: Exact filters for attributes to refine search results for. Think of
       #
+      # @param group_by [Array<String>] Body param: Groups documents by the specified attributes (the "group key") befor
+      #
       # @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.

data/lib/turbopuffer/version.rb

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

data/rbi/turbopuffer/internal/type/converter.rbi

@@ -90,6 +90,60 @@ module Turbopuffer
           def self.type_info(spec)
           end
 
+          # @api private
+          sig do
+            params(
+              type_info:
+                T.any(
+                  {
+                    const:
+                      T.nilable(
+                        T.any(NilClass, T::Boolean, Integer, Float, Symbol)
+                      ),
+                    enum:
+                      T.nilable(
+                        T.proc.returns(
+                          Turbopuffer::Internal::Type::Converter::Input
+                        )
+                      ),
+                    union:
+                      T.nilable(
+                        T.proc.returns(
+                          Turbopuffer::Internal::Type::Converter::Input
+                        )
+                      )
+                  },
+                  T.proc.returns(Turbopuffer::Internal::Type::Converter::Input),
+                  Turbopuffer::Internal::Type::Converter::Input
+                ),
+              spec:
+                T.any(
+                  {
+                    const:
+                      T.nilable(
+                        T.any(NilClass, T::Boolean, Integer, Float, Symbol)
+                      ),
+                    enum:
+                      T.nilable(
+                        T.proc.returns(
+                          Turbopuffer::Internal::Type::Converter::Input
+                        )
+                      ),
+                    union:
+                      T.nilable(
+                        T.proc.returns(
+                          Turbopuffer::Internal::Type::Converter::Input
+                        )
+                      )
+                  },
+                  T.proc.returns(Turbopuffer::Internal::Type::Converter::Input),
+                  Turbopuffer::Internal::Type::Converter::Input
+                )
+            ).returns(Turbopuffer::Internal::AnyHash)
+          end
+          def self.meta_info(type_info, spec)
+          end
+
           # @api private
           sig do
             params(translate_names: T::Boolean).returns(

data/rbi/turbopuffer/internal/type/union.rbi

@@ -16,7 +16,8 @@ module Turbopuffer
             T::Array[
               [
                 T.nilable(Symbol),
-                T.proc.returns(Turbopuffer::Internal::Type::Converter::Input)
+                T.proc.returns(Turbopuffer::Internal::Type::Converter::Input),
+                Turbopuffer::Internal::AnyHash
               ]
             ]
           )
@@ -25,7 +26,13 @@ module Turbopuffer
         end
 
         # @api private
-        sig { returns(T::Array[[T.nilable(Symbol), T.anything]]) }
+        sig do
+          returns(
+            T::Array[
+              [T.nilable(Symbol), T.anything, Turbopuffer::Internal::AnyHash]
+            ]
+          )
+        end
         protected def derefed_variants
         end
 

data/rbi/turbopuffer/models/namespace_explain_query_params.rbi

@@ -69,6 +69,14 @@ module Turbopuffer
       sig { params(filters: T.anything).void }
       attr_writer :filters
 
+      # Groups documents by the specified attributes (the "group key") before computing
+      # aggregates. Aggregates are computed separately for each group.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :group_by
+
+      sig { params(group_by: T::Array[String]).void }
+      attr_writer :group_by
+
       # Whether to include attributes in the response.
       sig { returns(T.nilable(Turbopuffer::IncludeAttributes::Variants)) }
       attr_reader :include_attributes
@@ -112,6 +120,7 @@ module Turbopuffer
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
           filters: T.anything,
+          group_by: T::Array[String],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           rank_by: T.anything,
           top_k: Integer,
@@ -134,6 +143,9 @@ module Turbopuffer
         # Exact filters for attributes to refine search results for. Think of it as a SQL
         # WHERE clause.
         filters: nil,
+        # Groups documents by the specified attributes (the "group key") before computing
+        # aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
         # Whether to include attributes in the response.
         include_attributes: nil,
         # How to rank the documents in the namespace.
@@ -155,6 +167,7 @@ module Turbopuffer
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
             filters: T.anything,
+            group_by: T::Array[String],
             include_attributes: Turbopuffer::IncludeAttributes::Variants,
             rank_by: T.anything,
             top_k: Integer,

data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi

@@ -26,7 +26,7 @@ module Turbopuffer
       def self.new(
         message: nil,
         # The status of the request.
-        status: :OK
+        status: :ACCEPTED
       )
       end
 

data/rbi/turbopuffer/models/namespace_multi_query_response.rbi

@@ -74,6 +74,14 @@ module Turbopuffer
             )
           end
 
+        sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
+        attr_reader :aggregation_groups
+
+        sig do
+          params(aggregation_groups: T::Array[Turbopuffer::Row::OrHash]).void
+        end
+        attr_writer :aggregation_groups
+
         sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
         attr_reader :aggregations
 
@@ -88,16 +96,18 @@ module Turbopuffer
 
         sig do
           params(
+            aggregation_groups: T::Array[Turbopuffer::Row::OrHash],
             aggregations: T::Hash[Symbol, T.anything],
             rows: T::Array[Turbopuffer::Row::OrHash]
           ).returns(T.attached_class)
         end
-        def self.new(aggregations: nil, rows: nil)
+        def self.new(aggregation_groups: nil, aggregations: nil, rows: nil)
         end
 
         sig do
           override.returns(
             {
+              aggregation_groups: T::Array[Turbopuffer::Row],
               aggregations: T::Hash[Symbol, T.anything],
               rows: T::Array[Turbopuffer::Row]
             }

data/rbi/turbopuffer/models/namespace_query_params.rbi

@@ -64,6 +64,14 @@ module Turbopuffer
       sig { params(filters: T.anything).void }
       attr_writer :filters
 
+      # Groups documents by the specified attributes (the "group key") before computing
+      # aggregates. Aggregates are computed separately for each group.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :group_by
+
+      sig { params(group_by: T::Array[String]).void }
+      attr_writer :group_by
+
       # Whether to include attributes in the response.
       sig { returns(T.nilable(Turbopuffer::IncludeAttributes::Variants)) }
       attr_reader :include_attributes
@@ -106,6 +114,7 @@ module Turbopuffer
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
           filters: T.anything,
+          group_by: T::Array[String],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           rank_by: T.anything,
           top_k: Integer,
@@ -128,6 +137,9 @@ module Turbopuffer
         # Exact filters for attributes to refine search results for. Think of it as a SQL
         # WHERE clause.
         filters: nil,
+        # Groups documents by the specified attributes (the "group key") before computing
+        # aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
         # Whether to include attributes in the response.
         include_attributes: nil,
         # How to rank the documents in the namespace.
@@ -149,6 +161,7 @@ module Turbopuffer
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
             filters: T.anything,
+            group_by: T::Array[String],
             include_attributes: Turbopuffer::IncludeAttributes::Variants,
             rank_by: T.anything,
             top_k: Integer,

data/rbi/turbopuffer/models/namespace_query_response.rbi

@@ -25,6 +25,14 @@ module Turbopuffer
       sig { params(performance: Turbopuffer::QueryPerformance::OrHash).void }
       attr_writer :performance
 
+      sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
+      attr_reader :aggregation_groups
+
+      sig do
+        params(aggregation_groups: T::Array[Turbopuffer::Row::OrHash]).void
+      end
+      attr_writer :aggregation_groups
+
       sig { returns(T.nilable(T::Hash[Symbol, T.anything])) }
       attr_reader :aggregations
 
@@ -42,6 +50,7 @@ module Turbopuffer
         params(
           billing: Turbopuffer::QueryBilling::OrHash,
           performance: Turbopuffer::QueryPerformance::OrHash,
+          aggregation_groups: T::Array[Turbopuffer::Row::OrHash],
           aggregations: T::Hash[Symbol, T.anything],
           rows: T::Array[Turbopuffer::Row::OrHash]
         ).returns(T.attached_class)
@@ -51,6 +60,7 @@ module Turbopuffer
         billing:,
         # The performance information for a query.
         performance:,
+        aggregation_groups: nil,
         aggregations: nil,
         rows: nil
       )
@@ -61,6 +71,7 @@ module Turbopuffer
           {
             billing: Turbopuffer::QueryBilling,
             performance: Turbopuffer::QueryPerformance,
+            aggregation_groups: T::Array[Turbopuffer::Row],
             aggregations: T::Hash[Symbol, T.anything],
             rows: T::Array[Turbopuffer::Row]
           }

data/rbi/turbopuffer/models/query.rbi

@@ -41,6 +41,14 @@ module Turbopuffer
       sig { params(filters: T.anything).void }
       attr_writer :filters
 
+      # Groups documents by the specified attributes (the "group key") before computing
+      # aggregates. Aggregates are computed separately for each group.
+      sig { returns(T.nilable(T::Array[String])) }
+      attr_reader :group_by
+
+      sig { params(group_by: T::Array[String]).void }
+      attr_writer :group_by
+
       # Whether to include attributes in the response.
       sig { returns(T.nilable(Turbopuffer::IncludeAttributes::Variants)) }
       attr_reader :include_attributes
@@ -73,6 +81,7 @@ module Turbopuffer
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
           filters: T.anything,
+          group_by: T::Array[String],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           rank_by: T.anything,
           top_k: Integer
@@ -90,6 +99,9 @@ module Turbopuffer
         # Exact filters for attributes to refine search results for. Think of it as a SQL
         # WHERE clause.
         filters: nil,
+        # Groups documents by the specified attributes (the "group key") before computing
+        # aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
         # Whether to include attributes in the response.
         include_attributes: nil,
         # How to rank the documents in the namespace.
@@ -106,6 +118,7 @@ module Turbopuffer
             distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
             exclude_attributes: T::Array[String],
             filters: T.anything,
+            group_by: T::Array[String],
             include_attributes: Turbopuffer::IncludeAttributes::Variants,
             rank_by: T.anything,
             top_k: Integer

data/rbi/turbopuffer/resources/namespaces.rbi

@@ -27,6 +27,7 @@ module Turbopuffer
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
           filters: T.anything,
+          group_by: T::Array[String],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           rank_by: T.anything,
           top_k: Integer,
@@ -50,6 +51,9 @@ module Turbopuffer
         # Body param: Exact filters for attributes to refine search results for. Think of
         # it as a SQL WHERE clause.
         filters: nil,
+        # Body param: Groups documents by the specified attributes (the "group key")
+        # before computing aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
         # Body param: Whether to include attributes in the response.
         include_attributes: nil,
         # Body param: How to rank the documents in the namespace.
@@ -123,6 +127,7 @@ module Turbopuffer
           distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
           exclude_attributes: T::Array[String],
           filters: T.anything,
+          group_by: T::Array[String],
           include_attributes: Turbopuffer::IncludeAttributes::Variants,
           rank_by: T.anything,
           top_k: Integer,
@@ -146,6 +151,9 @@ module Turbopuffer
         # Body param: Exact filters for attributes to refine search results for. Think of
         # it as a SQL WHERE clause.
         filters: nil,
+        # Body param: Groups documents by the specified attributes (the "group key")
+        # before computing aggregates. Aggregates are computed separately for each group.
+        group_by: nil,
         # Body param: Whether to include attributes in the response.
         include_attributes: nil,
         # Body param: How to rank the documents in the namespace.

data/sig/turbopuffer/internal/type/converter.rbs

@@ -39,6 +39,23 @@ module Turbopuffer
           | Turbopuffer::Internal::Type::Converter::input spec
         ) -> (^-> top)
 
+        def self.meta_info: (
+          {
+            const: (nil | bool | Integer | Float | Symbol)?,
+            enum: ^-> Turbopuffer::Internal::Type::Converter::input?,
+            union: ^-> Turbopuffer::Internal::Type::Converter::input?
+          }
+          | ^-> Turbopuffer::Internal::Type::Converter::input
+          | Turbopuffer::Internal::Type::Converter::input type_info,
+          {
+            const: (nil | bool | Integer | Float | Symbol)?,
+            enum: ^-> Turbopuffer::Internal::Type::Converter::input?,
+            union: ^-> Turbopuffer::Internal::Type::Converter::input?
+          }
+          | ^-> Turbopuffer::Internal::Type::Converter::input
+          | Turbopuffer::Internal::Type::Converter::input spec
+        ) -> ::Hash[Symbol, top]
+
         def self.new_coerce_state: (
           ?translate_names: bool
         ) -> Turbopuffer::Internal::Type::Converter::coerce_state

data/sig/turbopuffer/internal/type/union.rbs

@@ -5,9 +5,9 @@ module Turbopuffer
         include Turbopuffer::Internal::Type::Converter
         include Turbopuffer::Internal::Util::SorbetRuntimeSupport
 
-        private def self.known_variants: -> ::Array[[Symbol?, (^-> Turbopuffer::Internal::Type::Converter::input)]]
+        private def self.known_variants: -> ::Array[[Symbol?, (^-> Turbopuffer::Internal::Type::Converter::input), ::Hash[Symbol, top]]]
 
-        def self.derefed_variants: -> ::Array[[Symbol?, top]]
+        def self.derefed_variants: -> ::Array[[Symbol?, top, ::Hash[Symbol, top]]]
 
         def self.variants: -> ::Array[top]
 

data/sig/turbopuffer/models/namespace_explain_query_params.rbs

@@ -8,6 +8,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer,
@@ -47,6 +48,10 @@ module Turbopuffer
 
       def filters=: (top) -> top
 
+      attr_reader group_by: ::Array[String]?
+
+      def group_by=: (::Array[String]) -> ::Array[String]
+
       attr_reader include_attributes: Turbopuffer::Models::include_attributes?
 
       def include_attributes=: (
@@ -74,6 +79,7 @@ module Turbopuffer
         ?distance_metric: Turbopuffer::Models::distance_metric,
         ?exclude_attributes: ::Array[String],
         ?filters: top,
+        ?group_by: ::Array[String],
         ?include_attributes: Turbopuffer::Models::include_attributes,
         ?rank_by: top,
         ?top_k: Integer,
@@ -88,6 +94,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer,

data/sig/turbopuffer/models/namespace_hint_cache_warm_response.rbs

@@ -1,17 +1,18 @@
 module Turbopuffer
   module Models
-    type namespace_hint_cache_warm_response = { status: :OK, message: String }
+    type namespace_hint_cache_warm_response =
+      { status: :ACCEPTED, message: String }
 
     class NamespaceHintCacheWarmResponse < Turbopuffer::Internal::Type::BaseModel
-      attr_accessor status: :OK
+      attr_accessor status: :ACCEPTED
 
       attr_reader message: String?
 
       def message=: (String) -> String
 
-      def initialize: (?message: String, ?status: :OK) -> void
+      def initialize: (?message: String, ?status: :ACCEPTED) -> void
 
-      def to_hash: -> { status: :OK, message: String }
+      def to_hash: -> { status: :ACCEPTED, message: String }
     end
   end
 end

data/sig/turbopuffer/models/namespace_multi_query_response.rbs

@@ -27,9 +27,19 @@ module Turbopuffer
       }
 
       type result =
-        { aggregations: ::Hash[Symbol, top], rows: ::Array[Turbopuffer::Row] }
+        {
+          aggregation_groups: ::Array[Turbopuffer::Row],
+          aggregations: ::Hash[Symbol, top],
+          rows: ::Array[Turbopuffer::Row]
+        }
 
       class Result < Turbopuffer::Internal::Type::BaseModel
+        attr_reader aggregation_groups: ::Array[Turbopuffer::Row]?
+
+        def aggregation_groups=: (
+          ::Array[Turbopuffer::Row]
+        ) -> ::Array[Turbopuffer::Row]
+
         attr_reader aggregations: ::Hash[Symbol, top]?
 
         def aggregations=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
@@ -39,11 +49,13 @@ module Turbopuffer
         def rows=: (::Array[Turbopuffer::Row]) -> ::Array[Turbopuffer::Row]
 
         def initialize: (
+          ?aggregation_groups: ::Array[Turbopuffer::Row],
           ?aggregations: ::Hash[Symbol, top],
           ?rows: ::Array[Turbopuffer::Row]
         ) -> void
 
         def to_hash: -> {
+          aggregation_groups: ::Array[Turbopuffer::Row],
           aggregations: ::Hash[Symbol, top],
           rows: ::Array[Turbopuffer::Row]
         }

data/sig/turbopuffer/models/namespace_query_params.rbs

@@ -8,6 +8,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer,
@@ -47,6 +48,10 @@ module Turbopuffer
 
       def filters=: (top) -> top
 
+      attr_reader group_by: ::Array[String]?
+
+      def group_by=: (::Array[String]) -> ::Array[String]
+
       attr_reader include_attributes: Turbopuffer::Models::include_attributes?
 
       def include_attributes=: (
@@ -74,6 +79,7 @@ module Turbopuffer
         ?distance_metric: Turbopuffer::Models::distance_metric,
         ?exclude_attributes: ::Array[String],
         ?filters: top,
+        ?group_by: ::Array[String],
         ?include_attributes: Turbopuffer::Models::include_attributes,
         ?rank_by: top,
         ?top_k: Integer,
@@ -88,6 +94,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer,

data/sig/turbopuffer/models/namespace_query_response.rbs

@@ -4,6 +4,7 @@ module Turbopuffer
       {
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
+        aggregation_groups: ::Array[Turbopuffer::Row],
         aggregations: ::Hash[Symbol, top],
         rows: ::Array[Turbopuffer::Row]
       }
@@ -13,6 +14,12 @@ module Turbopuffer
 
       attr_accessor performance: Turbopuffer::QueryPerformance
 
+      attr_reader aggregation_groups: ::Array[Turbopuffer::Row]?
+
+      def aggregation_groups=: (
+        ::Array[Turbopuffer::Row]
+      ) -> ::Array[Turbopuffer::Row]
+
       attr_reader aggregations: ::Hash[Symbol, top]?
 
       def aggregations=: (::Hash[Symbol, top]) -> ::Hash[Symbol, top]
@@ -24,6 +31,7 @@ module Turbopuffer
       def initialize: (
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
+        ?aggregation_groups: ::Array[Turbopuffer::Row],
         ?aggregations: ::Hash[Symbol, top],
         ?rows: ::Array[Turbopuffer::Row]
       ) -> void
@@ -31,6 +39,7 @@ module Turbopuffer
       def to_hash: -> {
         billing: Turbopuffer::QueryBilling,
         performance: Turbopuffer::QueryPerformance,
+        aggregation_groups: ::Array[Turbopuffer::Row],
         aggregations: ::Hash[Symbol, top],
         rows: ::Array[Turbopuffer::Row]
       }

data/sig/turbopuffer/models/query.rbs

@@ -6,6 +6,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer
@@ -30,6 +31,10 @@ module Turbopuffer
 
       def filters=: (top) -> top
 
+      attr_reader group_by: ::Array[String]?
+
+      def group_by=: (::Array[String]) -> ::Array[String]
+
       attr_reader include_attributes: Turbopuffer::Models::include_attributes?
 
       def include_attributes=: (
@@ -49,6 +54,7 @@ module Turbopuffer
         ?distance_metric: Turbopuffer::Models::distance_metric,
         ?exclude_attributes: ::Array[String],
         ?filters: top,
+        ?group_by: ::Array[String],
         ?include_attributes: Turbopuffer::Models::include_attributes,
         ?rank_by: top,
         ?top_k: Integer
@@ -59,6 +65,7 @@ module Turbopuffer
         distance_metric: Turbopuffer::Models::distance_metric,
         exclude_attributes: ::Array[String],
         filters: top,
+        group_by: ::Array[String],
         include_attributes: Turbopuffer::Models::include_attributes,
         rank_by: top,
         top_k: Integer

data/sig/turbopuffer/resources/namespaces.rbs

@@ -13,6 +13,7 @@ module Turbopuffer
         ?distance_metric: Turbopuffer::Models::distance_metric,
         ?exclude_attributes: ::Array[String],
         ?filters: top,
+        ?group_by: ::Array[String],
         ?include_attributes: Turbopuffer::Models::include_attributes,
         ?rank_by: top,
         ?top_k: Integer,
@@ -45,6 +46,7 @@ module Turbopuffer
         ?distance_metric: Turbopuffer::Models::distance_metric,
         ?exclude_attributes: ::Array[String],
         ?filters: top,
+        ?group_by: ::Array[String],
         ?include_attributes: Turbopuffer::Models::include_attributes,
         ?rank_by: top,
         ?top_k: Integer,

metadata

@@ -1,14 +1,14 @@
 --- !ruby/object:Gem::Specification
 name: turbopuffer-ruby
 version: !ruby/object:Gem::Version
-  version: 0.2.4
+  version: 0.2.6
 platform: ruby
 authors:
 - Turbopuffer
 autorequire:
 bindir: bin
 cert_chain: []
-date: 2025-08-08 00:00:00.000000000 Z
+date: 2025-08-18 00:00:00.000000000 Z
 dependencies:
 - !ruby/object:Gem::Dependency
   name: connection_pool