turbopuffer 2.8.0 → 2.10.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (67) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +19 -0
  3. data/README.md +15 -1
  4. data/lib/turbopuffer/client.rb +7 -0
  5. data/lib/turbopuffer/internal/respond_async.rb +1 -1
  6. data/lib/turbopuffer/internal/telemetry.rb +538 -0
  7. data/lib/turbopuffer/internal/transport/base_client.rb +50 -21
  8. data/lib/turbopuffer/internal/transport/pooled_net_requester.rb +77 -2
  9. data/lib/turbopuffer/internal/transport/request_observer.rb +377 -0
  10. data/lib/turbopuffer/models/attribute_schema_config.rb +1 -0
  11. data/lib/turbopuffer/models/branch_from_namespace_params.rb +3 -0
  12. data/lib/turbopuffer/models/copy_from_namespace_operation.rb +8 -1
  13. data/lib/turbopuffer/models/copy_from_namespace_operation_result.rb +5 -3
  14. data/lib/turbopuffer/models/copy_from_namespace_params.rb +3 -0
  15. data/lib/turbopuffer/models/encryption.rb +11 -1
  16. data/lib/turbopuffer/models/full_text_search.rb +1 -0
  17. data/lib/turbopuffer/models/id.rb +1 -1
  18. data/lib/turbopuffer/models/namespace_explain_query_params.rb +50 -24
  19. data/lib/turbopuffer/models/namespace_hint_cache_warm_response.rb +2 -1
  20. data/lib/turbopuffer/models/namespace_metadata.rb +10 -1
  21. data/lib/turbopuffer/models/namespace_metadata_patch.rb +1 -0
  22. data/lib/turbopuffer/models/namespace_multi_query_params.rb +51 -24
  23. data/lib/turbopuffer/models/namespace_multi_query_response.rb +19 -2
  24. data/lib/turbopuffer/models/namespace_query_params.rb +50 -24
  25. data/lib/turbopuffer/models/namespace_query_response.rb +10 -2
  26. data/lib/turbopuffer/models/namespace_recall_response.rb +5 -0
  27. data/lib/turbopuffer/models/namespace_start_copy_from_response.rb +2 -0
  28. data/lib/turbopuffer/models/namespace_write_params.rb +3 -3
  29. data/lib/turbopuffer/models/operation_error.rb +2 -0
  30. data/lib/turbopuffer/models/write_result.rb +1 -1
  31. data/lib/turbopuffer/resources/namespaces.rb +4 -4
  32. data/lib/turbopuffer/version.rb +1 -1
  33. data/lib/turbopuffer.rb +2 -0
  34. data/rbi/turbopuffer/client.rbi +5 -0
  35. data/rbi/turbopuffer/internal/telemetry.rbi +315 -0
  36. data/rbi/turbopuffer/internal/transport/base_client.rbi +13 -2
  37. data/rbi/turbopuffer/internal/transport/pooled_net_requester.rbi +47 -1
  38. data/rbi/turbopuffer/internal/transport/request_observer.rbi +340 -0
  39. data/rbi/turbopuffer/models/branch_from_namespace_params.rbi +1 -0
  40. data/rbi/turbopuffer/models/copy_from_namespace_operation.rbi +4 -0
  41. data/rbi/turbopuffer/models/copy_from_namespace_operation_result.rbi +8 -3
  42. data/rbi/turbopuffer/models/copy_from_namespace_params.rbi +1 -0
  43. data/rbi/turbopuffer/models/encryption.rbi +29 -2
  44. data/rbi/turbopuffer/models/namespace_explain_query_params.rbi +84 -71
  45. data/rbi/turbopuffer/models/namespace_hint_cache_warm_response.rbi +2 -0
  46. data/rbi/turbopuffer/models/namespace_metadata.rbi +5 -0
  47. data/rbi/turbopuffer/models/namespace_multi_query_params.rbi +86 -71
  48. data/rbi/turbopuffer/models/namespace_multi_query_response.rbi +17 -1
  49. data/rbi/turbopuffer/models/namespace_query_params.rbi +88 -71
  50. data/rbi/turbopuffer/models/namespace_query_response.rbi +8 -1
  51. data/rbi/turbopuffer/models/namespace_recall_response.rbi +4 -0
  52. data/rbi/turbopuffer/models/namespace_start_copy_from_response.rbi +1 -0
  53. data/rbi/turbopuffer/models/namespace_write_params.rbi +3 -3
  54. data/rbi/turbopuffer/models/operation_error.rbi +1 -0
  55. data/rbi/turbopuffer/models/write_result.rbi +1 -1
  56. data/rbi/turbopuffer/resources/namespaces.rbi +15 -4
  57. data/sig/turbopuffer/client.rbs +1 -0
  58. data/sig/turbopuffer/internal/telemetry.rbs +142 -0
  59. data/sig/turbopuffer/internal/transport/base_client.rbs +5 -1
  60. data/sig/turbopuffer/internal/transport/pooled_net_requester.rbs +15 -1
  61. data/sig/turbopuffer/internal/transport/request_observer.rbs +153 -0
  62. data/sig/turbopuffer/models/encryption.rbs +22 -3
  63. data/sig/turbopuffer/models/namespace_explain_query_params.rbs +30 -28
  64. data/sig/turbopuffer/models/namespace_multi_query_params.rbs +30 -28
  65. data/sig/turbopuffer/models/namespace_query_params.rbs +30 -26
  66. data/sig/turbopuffer/resources/namespaces.rbs +3 -3
  67. metadata +9 -3
@@ -10,8 +10,10 @@ module Turbopuffer
10
10
 
11
11
  discriminator :status
12
12
 
13
+ # The copy is still in progress.
13
14
  variant :running, -> { Turbopuffer::CopyFromNamespaceOperation::Running }
14
15
 
16
+ # The copy has finished, successfully or not.
15
17
  variant :finished, -> { Turbopuffer::CopyFromNamespaceOperation::Finished }
16
18
 
17
19
  class Running < Turbopuffer::Internal::Type::BaseModel
@@ -37,6 +39,8 @@ module Turbopuffer
37
39
  # Some parameter documentations has been truncated, see
38
40
  # {Turbopuffer::Models::CopyFromNamespaceOperation::Running} for more details.
39
41
  #
42
+ # The copy is still in progress.
43
+ #
40
44
  # @param start_time [Time] The time at which the operation started.
41
45
  #
42
46
  # @param progress [String] A freeform description of the operation's progress. May be absent, and its forma
@@ -52,6 +56,7 @@ module Turbopuffer
52
56
  required :finish_time, Time
53
57
 
54
58
  # @!attribute result
59
+ # The result of the copy.
55
60
  #
56
61
  # @return [Turbopuffer::Models::CopyFromNamespaceOperationResult::Success, Turbopuffer::Models::CopyFromNamespaceOperationResult::Error]
57
62
  required :result, union: -> { Turbopuffer::CopyFromNamespaceOperationResult }
@@ -68,9 +73,11 @@ module Turbopuffer
68
73
  required :status, const: :finished
69
74
 
70
75
  # @!method initialize(finish_time:, result:, start_time:, status: :finished)
76
+ # The copy has finished, successfully or not.
77
+ #
71
78
  # @param finish_time [Time] The time at which the operation finished.
72
79
  #
73
- # @param result [Turbopuffer::Models::CopyFromNamespaceOperationResult::Success, Turbopuffer::Models::CopyFromNamespaceOperationResult::Error]
80
+ # @param result [Turbopuffer::Models::CopyFromNamespaceOperationResult::Success, Turbopuffer::Models::CopyFromNamespaceOperationResult::Error] The result of the copy.
74
81
  #
75
82
  # @param start_time [Time] The time at which the operation started.
76
83
  #
@@ -2,6 +2,7 @@
2
2
 
3
3
  module Turbopuffer
4
4
  module Models
5
+ # The result of a finished copy operation.
5
6
  module CopyFromNamespaceOperationResult
6
7
  extend Turbopuffer::Internal::Type::Union
7
8
 
@@ -11,23 +12,24 @@ module Turbopuffer
11
12
 
12
13
  class Success < Turbopuffer::Internal::Type::BaseModel
13
14
  # @!attribute success
14
- # The response to a successful write request.
15
+ # The copy succeeded, with the result of its write.
15
16
  #
16
17
  # @return [Turbopuffer::Models::WriteResult]
17
18
  required :success, -> { Turbopuffer::WriteResult }
18
19
 
19
20
  # @!method initialize(success:)
20
- # @param success [Turbopuffer::Models::WriteResult] The response to a successful write request.
21
+ # @param success [Turbopuffer::Models::WriteResult] The copy succeeded, with the result of its write.
21
22
  end
22
23
 
23
24
  class Error < Turbopuffer::Internal::Type::BaseModel
24
25
  # @!attribute error
26
+ # The copy failed, with its error.
25
27
  #
26
28
  # @return [Turbopuffer::Models::OperationError]
27
29
  required :error, -> { Turbopuffer::OperationError }
28
30
 
29
31
  # @!method initialize(error:)
30
- # @param error [Turbopuffer::Models::OperationError]
32
+ # @param error [Turbopuffer::Models::OperationError] The copy failed, with its error.
31
33
  end
32
34
 
33
35
  # @!method self.variants
@@ -9,6 +9,7 @@ module Turbopuffer
9
9
  # The namespace to copy documents from.
10
10
  variant String
11
11
 
12
+ # Configuration for copying documents from another namespace.
12
13
  variant -> { Turbopuffer::CopyFromNamespaceParams::CopyFromNamespaceConfig }
13
14
 
14
15
  class CopyFromNamespaceConfig < Turbopuffer::Internal::Type::BaseModel
@@ -31,6 +32,8 @@ module Turbopuffer
31
32
  optional :source_region, String
32
33
 
33
34
  # @!method initialize(source_namespace:, source_api_key: nil, source_region: nil)
35
+ # Configuration for copying documents from another namespace.
36
+ #
34
37
  # @param source_namespace [String] The namespace to copy documents from.
35
38
  #
36
39
  # @param source_api_key [String] (Optional) An API key for the organization containing the source namespace
@@ -25,7 +25,15 @@ module Turbopuffer
25
25
  # @return [Symbol, :"customer-managed"]
26
26
  required :mode, const: :"customer-managed"
27
27
 
28
- # @!method initialize(key_name:, mode: :"customer-managed")
28
+ # @!attribute encryption_context
29
+ # The AWS KMS encryption context to send with every request that uses the key.
30
+ # Only supported on AWS, and must be enabled for your organization. Keys may not
31
+ # start with `tpuf:` or `aws:`.
32
+ #
33
+ # @return [Hash{Symbol=>String}, nil]
34
+ optional :encryption_context, Turbopuffer::Internal::Type::HashOf[String]
35
+
36
+ # @!method initialize(key_name:, encryption_context: nil, mode: :"customer-managed")
29
37
  # Some parameter documentations has been truncated, see
30
38
  # {Turbopuffer::Models::Encryption::CustomerManaged} for more details.
31
39
  #
@@ -33,6 +41,8 @@ module Turbopuffer
33
41
  #
34
42
  # @param key_name [String] The identifier of the CMEK key to use for encryption. For GCP, the fully-qualifi
35
43
  #
44
+ # @param encryption_context [Hash{Symbol=>String}] The AWS KMS encryption context to send with every request that uses the key. Onl
45
+ #
36
46
  # @param mode [Symbol, :"customer-managed"]
37
47
  end
38
48
 
@@ -8,6 +8,7 @@ module Turbopuffer
8
8
  module FullTextSearch
9
9
  extend Turbopuffer::Internal::Type::Union
10
10
 
11
+ # Whether to enable full-text search with the default configuration.
11
12
  variant Turbopuffer::Internal::Type::Boolean
12
13
 
13
14
  # Configuration options for full-text search.
@@ -9,7 +9,7 @@ module Turbopuffer
9
9
  # A string ID.
10
10
  variant String
11
11
 
12
- # An integer ID.
12
+ # An unsigned 64-bit integer ID.
13
13
  variant Integer
14
14
 
15
15
  # @!method self.variants
@@ -30,8 +30,8 @@ module Turbopuffer
30
30
  # @!attribute consistency
31
31
  # The consistency level for a query.
32
32
  #
33
- # @return [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency, nil]
34
- optional :consistency, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency }
33
+ # @return [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual, nil]
34
+ optional :consistency, union: -> { Turbopuffer::NamespaceExplainQueryParams::Consistency }
35
35
 
36
36
  # @!attribute distance_metric
37
37
  # A function used to calculate vector similarity.
@@ -107,7 +107,7 @@ module Turbopuffer
107
107
  #
108
108
  # @param compute_attributes [Hash{Symbol=>Object}] Computes additional values on documents returned by a query. Each key is the nam
109
109
  #
110
- # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] The consistency level for a query.
110
+ # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual] The consistency level for a query.
111
111
  #
112
112
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] A function used to calculate vector similarity.
113
113
  #
@@ -131,33 +131,59 @@ module Turbopuffer
131
131
  #
132
132
  # @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}]
133
133
 
134
- class Consistency < Turbopuffer::Internal::Type::BaseModel
135
- # @!attribute level
136
- # The query's consistency level.
137
- #
138
- # @return [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level, nil]
139
- optional :level, enum: -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Level }
134
+ # The consistency level for a query.
135
+ module Consistency
136
+ extend Turbopuffer::Internal::Type::Union
137
+
138
+ discriminator :level
140
139
 
141
- # @!method initialize(level: nil)
142
- # The consistency level for a query.
143
- #
144
- # @param level [Symbol, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Level] The query's consistency level.
140
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
141
+ variant :strong, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong }
145
142
 
146
- # The query's consistency level.
147
- #
148
- # @see Turbopuffer::Models::NamespaceExplainQueryParams::Consistency#level
149
- module Level
150
- extend Turbopuffer::Internal::Type::Enum
143
+ # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
144
+ variant :eventual, -> { Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual }
151
145
 
152
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
153
- STRONG = :strong
146
+ class Strong < Turbopuffer::Internal::Type::BaseModel
147
+ # @!attribute level
148
+ #
149
+ # @return [Symbol, :strong]
150
+ required :level, const: :strong
154
151
 
155
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
156
- EVENTUAL = :eventual
152
+ # @!method initialize(level: :strong)
153
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
154
+ # writes.
155
+ #
156
+ # @param level [Symbol, :strong]
157
+ end
157
158
 
158
- # @!method self.values
159
- # @return [Array<Symbol>]
159
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
160
+ # @!attribute level
161
+ #
162
+ # @return [Symbol, :eventual]
163
+ required :level, const: :eventual
164
+
165
+ # @!attribute max_staleness_seconds
166
+ # How long the query may reuse the node's cached view of the namespace before
167
+ # refreshing it from object storage. Defaults to 60.
168
+ #
169
+ # @return [Integer, nil]
170
+ optional :max_staleness_seconds, Integer
171
+
172
+ # @!method initialize(max_staleness_seconds: nil, level: :eventual)
173
+ # Some parameter documentations has been truncated, see
174
+ # {Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual} for
175
+ # more details.
176
+ #
177
+ # Eventual consistency. Does not require a round-trip to object storage, but may
178
+ # not see the latest writes.
179
+ #
180
+ # @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
181
+ #
182
+ # @param level [Symbol, :eventual]
160
183
  end
184
+
185
+ # @!method self.variants
186
+ # @return [Array(Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual)]
161
187
  end
162
188
 
163
189
  # Limits the documents returned by a query.
@@ -11,6 +11,7 @@ module Turbopuffer
11
11
  required :status, const: :ACCEPTED
12
12
 
13
13
  # @!attribute message
14
+ # A message describing the result of the request.
14
15
  #
15
16
  # @return [String, nil]
16
17
  optional :message, String
@@ -18,7 +19,7 @@ module Turbopuffer
18
19
  # @!method initialize(message: nil, status: :ACCEPTED)
19
20
  # The response to a successful cache warm request.
20
21
  #
21
- # @param message [String]
22
+ # @param message [String] A message describing the result of the request.
22
23
  #
23
24
  # @param status [Symbol, :ACCEPTED] The status of the request.
24
25
  end
@@ -29,6 +29,7 @@ module Turbopuffer
29
29
  required :encryption, union: -> { Turbopuffer::Encryption }
30
30
 
31
31
  # @!attribute index
32
+ # The state of the namespace's index.
32
33
  #
33
34
  # @return [Turbopuffer::Models::NamespaceMetadata::Index::IndexUpToDate, Turbopuffer::Models::NamespaceMetadata::Index::IndexUpdating]
34
35
  required :index, union: -> { Turbopuffer::NamespaceMetadata::Index }
@@ -81,7 +82,7 @@ module Turbopuffer
81
82
  #
82
83
  # @param encryption [Turbopuffer::Models::Encryption::CustomerManaged, Turbopuffer::Models::Encryption::Default] The encryption configuration for a namespace.
83
84
  #
84
- # @param index [Turbopuffer::Models::NamespaceMetadata::Index::IndexUpToDate, Turbopuffer::Models::NamespaceMetadata::Index::IndexUpdating]
85
+ # @param index [Turbopuffer::Models::NamespaceMetadata::Index::IndexUpToDate, Turbopuffer::Models::NamespaceMetadata::Index::IndexUpdating] The state of the namespace's index.
85
86
  #
86
87
  # @param schema [Hash{Symbol=>Turbopuffer::Models::AttributeSchemaConfig}] The schema of the namespace.
87
88
  #
@@ -93,12 +94,16 @@ module Turbopuffer
93
94
  #
94
95
  # @param sharding [Turbopuffer::Models::ShardingConfig] Configuration for namespace sharding, which partitions a namespace's documents a
95
96
 
97
+ # The state of the namespace's index.
98
+ #
96
99
  # @see Turbopuffer::Models::NamespaceMetadata#index
97
100
  module Index
98
101
  extend Turbopuffer::Internal::Type::Union
99
102
 
103
+ # Every document in the namespace is indexed.
100
104
  variant -> { Turbopuffer::NamespaceMetadata::Index::IndexUpToDate }
101
105
 
106
+ # Some documents are in the write-ahead log and haven't been indexed yet.
102
107
  variant -> { Turbopuffer::NamespaceMetadata::Index::IndexUpdating }
103
108
 
104
109
  class IndexUpToDate < Turbopuffer::Internal::Type::BaseModel
@@ -108,6 +113,8 @@ module Turbopuffer
108
113
  required :status, const: :"up-to-date"
109
114
 
110
115
  # @!method initialize(status: :"up-to-date")
116
+ # Every document in the namespace is indexed.
117
+ #
111
118
  # @param status [Symbol, :"up-to-date"]
112
119
  end
113
120
 
@@ -134,6 +141,8 @@ module Turbopuffer
134
141
  # Some parameter documentations has been truncated, see
135
142
  # {Turbopuffer::Models::NamespaceMetadata::Index::IndexUpdating} for more details.
136
143
  #
144
+ # Some documents are in the write-ahead log and haven't been indexed yet.
145
+ #
137
146
  # @param unindexed_bytes [Integer] The number of bytes in the namespace that are in the write-ahead log but have no
138
147
  #
139
148
  # @param unindexed_rows [Integer] The number of rows in the write-ahead log that have not yet been indexed.
@@ -42,6 +42,7 @@ module Turbopuffer
42
42
  module Pinning
43
43
  extend Turbopuffer::Internal::Type::Union
44
44
 
45
+ # `true` to enable pinning with the default configuration, or `false` to remove pinning.
45
46
  variant Turbopuffer::Internal::Type::Boolean
46
47
 
47
48
  # Configuration for namespace pinning.
@@ -21,8 +21,8 @@ module Turbopuffer
21
21
  # @!attribute consistency
22
22
  # The consistency level for a query.
23
23
  #
24
- # @return [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency, nil]
25
- optional :consistency, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency }
24
+ # @return [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual, nil]
25
+ optional :consistency, union: -> { Turbopuffer::NamespaceMultiQueryParams::Consistency }
26
26
 
27
27
  # @!attribute limit
28
28
  # Limits the total number of reranked documents returned.
@@ -57,7 +57,7 @@ module Turbopuffer
57
57
  #
58
58
  # @param namespace [String]
59
59
  #
60
- # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency] The consistency level for a query.
60
+ # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual] The consistency level for a query.
61
61
  #
62
62
  # @param limit [Integer, Turbopuffer::Models::RerankLimit] Limits the total number of reranked documents returned.
63
63
  #
@@ -188,39 +188,66 @@ module Turbopuffer
188
188
  end
189
189
  end
190
190
 
191
- class Consistency < Turbopuffer::Internal::Type::BaseModel
192
- # @!attribute level
193
- # The query's consistency level.
194
- #
195
- # @return [Symbol, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Level, nil]
196
- optional :level, enum: -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Level }
191
+ # The consistency level for a query.
192
+ module Consistency
193
+ extend Turbopuffer::Internal::Type::Union
197
194
 
198
- # @!method initialize(level: nil)
199
- # The consistency level for a query.
200
- #
201
- # @param level [Symbol, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Level] The query's consistency level.
195
+ discriminator :level
202
196
 
203
- # The query's consistency level.
204
- #
205
- # @see Turbopuffer::Models::NamespaceMultiQueryParams::Consistency#level
206
- module Level
207
- extend Turbopuffer::Internal::Type::Enum
197
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
198
+ variant :strong, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong }
208
199
 
209
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
210
- STRONG = :strong
200
+ # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
201
+ variant :eventual, -> { Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual }
211
202
 
212
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
213
- EVENTUAL = :eventual
203
+ class Strong < Turbopuffer::Internal::Type::BaseModel
204
+ # @!attribute level
205
+ #
206
+ # @return [Symbol, :strong]
207
+ required :level, const: :strong
214
208
 
215
- # @!method self.values
216
- # @return [Array<Symbol>]
209
+ # @!method initialize(level: :strong)
210
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
211
+ # writes.
212
+ #
213
+ # @param level [Symbol, :strong]
217
214
  end
215
+
216
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
217
+ # @!attribute level
218
+ #
219
+ # @return [Symbol, :eventual]
220
+ required :level, const: :eventual
221
+
222
+ # @!attribute max_staleness_seconds
223
+ # How long the query may reuse the node's cached view of the namespace before
224
+ # refreshing it from object storage. Defaults to 60.
225
+ #
226
+ # @return [Integer, nil]
227
+ optional :max_staleness_seconds, Integer
228
+
229
+ # @!method initialize(max_staleness_seconds: nil, level: :eventual)
230
+ # Some parameter documentations has been truncated, see
231
+ # {Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual} for more
232
+ # details.
233
+ #
234
+ # Eventual consistency. Does not require a round-trip to object storage, but may
235
+ # not see the latest writes.
236
+ #
237
+ # @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
238
+ #
239
+ # @param level [Symbol, :eventual]
240
+ end
241
+
242
+ # @!method self.variants
243
+ # @return [Array(Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual)]
218
244
  end
219
245
 
220
246
  # Limits the total number of reranked documents returned.
221
247
  module Limit
222
248
  extend Turbopuffer::Internal::Type::Union
223
249
 
250
+ # Limits the total number of reranked documents returned.
224
251
  variant Integer
225
252
 
226
253
  # Limits the total number of reranked documents returned.
@@ -17,19 +17,24 @@ module Turbopuffer
17
17
  required :performance, -> { Turbopuffer::QueryPerformance }
18
18
 
19
19
  # @!attribute results
20
+ # The results of each subquery, in the same order as `queries`. With `rerank_by`,
21
+ # a single result combining the subqueries' rows.
20
22
  #
21
23
  # @return [Array<Turbopuffer::Models::NamespaceMultiQueryResponse::Result>]
22
24
  required :results,
23
25
  -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Models::NamespaceMultiQueryResponse::Result] }
24
26
 
25
27
  # @!method initialize(billing:, performance:, results:)
28
+ # Some parameter documentations has been truncated, see
29
+ # {Turbopuffer::Models::NamespaceMultiQueryResponse} for more details.
30
+ #
26
31
  # The result of a multi-query.
27
32
  #
28
33
  # @param billing [Turbopuffer::Models::QueryBilling] The billing information for a query.
29
34
  #
30
35
  # @param performance [Turbopuffer::Models::QueryPerformance] The performance information for a query.
31
36
  #
32
- # @param results [Array<Turbopuffer::Models::NamespaceMultiQueryResponse::Result>]
37
+ # @param results [Array<Turbopuffer::Models::NamespaceMultiQueryResponse::Result>] The results of each subquery, in the same order as `queries`. With `rerank_by`,
33
38
 
34
39
  class Result < Turbopuffer::Internal::Type::BaseModel
35
40
  # @!attribute aggregation_groups
@@ -44,14 +49,26 @@ module Turbopuffer
44
49
  optional :aggregations, Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]
45
50
 
46
51
  # @!attribute rows
52
+ # The documents that matched the query, ordered by `rank_by`. Only present when
53
+ # `rank_by` is set.
47
54
  #
48
55
  # @return [Array<Turbopuffer::Models::Row>, nil]
49
56
  optional :rows, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
50
57
 
51
58
  # @!method initialize(aggregation_groups: nil, aggregations: nil, rows: nil)
59
+ # Some parameter documentations has been truncated, see
60
+ # {Turbopuffer::Models::NamespaceMultiQueryResponse::Result} for more details.
61
+ #
62
+ # The result of a query, or of one subquery of a multi-query. With `aggregate_by`,
63
+ # `aggregations` maps each aggregation's label to its value. With `group_by` as
64
+ # well, `aggregation_groups` holds one object per group instead, with its group
65
+ # key and the value of each aggregation.
66
+ #
52
67
  # @param aggregation_groups [Array<Hash{Symbol=>Object}>]
68
+ #
53
69
  # @param aggregations [Hash{Symbol=>Object}]
54
- # @param rows [Array<Turbopuffer::Models::Row>]
70
+ #
71
+ # @param rows [Array<Turbopuffer::Models::Row>] The documents that matched the query, ordered by `rank_by`. Only present when `r
55
72
  end
56
73
  end
57
74
  end
@@ -30,8 +30,8 @@ module Turbopuffer
30
30
  # @!attribute consistency
31
31
  # The consistency level for a query.
32
32
  #
33
- # @return [Turbopuffer::Models::NamespaceQueryParams::Consistency, nil]
34
- optional :consistency, -> { Turbopuffer::NamespaceQueryParams::Consistency }
33
+ # @return [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual, nil]
34
+ optional :consistency, union: -> { Turbopuffer::NamespaceQueryParams::Consistency }
35
35
 
36
36
  # @!attribute distance_metric
37
37
  # A function used to calculate vector similarity.
@@ -113,7 +113,7 @@ module Turbopuffer
113
113
  #
114
114
  # @param compute_attributes [Hash{Symbol=>Object}] Computes additional values on documents returned by a query. Each key is the nam
115
115
  #
116
- # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency] The consistency level for a query.
116
+ # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual] The consistency level for a query.
117
117
  #
118
118
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] A function used to calculate vector similarity.
119
119
  #
@@ -139,33 +139,59 @@ module Turbopuffer
139
139
  #
140
140
  # @param request_options [Turbopuffer::RequestOptions, Hash{Symbol=>Object}]
141
141
 
142
- class Consistency < Turbopuffer::Internal::Type::BaseModel
143
- # @!attribute level
144
- # The query's consistency level.
145
- #
146
- # @return [Symbol, Turbopuffer::Models::NamespaceQueryParams::Consistency::Level, nil]
147
- optional :level, enum: -> { Turbopuffer::NamespaceQueryParams::Consistency::Level }
142
+ # The consistency level for a query.
143
+ module Consistency
144
+ extend Turbopuffer::Internal::Type::Union
145
+
146
+ discriminator :level
148
147
 
149
- # @!method initialize(level: nil)
150
- # The consistency level for a query.
151
- #
152
- # @param level [Symbol, Turbopuffer::Models::NamespaceQueryParams::Consistency::Level] The query's consistency level.
148
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
149
+ variant :strong, -> { Turbopuffer::NamespaceQueryParams::Consistency::Strong }
153
150
 
154
- # The query's consistency level.
155
- #
156
- # @see Turbopuffer::Models::NamespaceQueryParams::Consistency#level
157
- module Level
158
- extend Turbopuffer::Internal::Type::Enum
151
+ # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
152
+ variant :eventual, -> { Turbopuffer::NamespaceQueryParams::Consistency::Eventual }
159
153
 
160
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
161
- STRONG = :strong
154
+ class Strong < Turbopuffer::Internal::Type::BaseModel
155
+ # @!attribute level
156
+ #
157
+ # @return [Symbol, :strong]
158
+ required :level, const: :strong
162
159
 
163
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
164
- EVENTUAL = :eventual
160
+ # @!method initialize(level: :strong)
161
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
162
+ # writes.
163
+ #
164
+ # @param level [Symbol, :strong]
165
+ end
165
166
 
166
- # @!method self.values
167
- # @return [Array<Symbol>]
167
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
168
+ # @!attribute level
169
+ #
170
+ # @return [Symbol, :eventual]
171
+ required :level, const: :eventual
172
+
173
+ # @!attribute max_staleness_seconds
174
+ # How long the query may reuse the node's cached view of the namespace before
175
+ # refreshing it from object storage. Defaults to 60.
176
+ #
177
+ # @return [Integer, nil]
178
+ optional :max_staleness_seconds, Integer
179
+
180
+ # @!method initialize(max_staleness_seconds: nil, level: :eventual)
181
+ # Some parameter documentations has been truncated, see
182
+ # {Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual} for more
183
+ # details.
184
+ #
185
+ # Eventual consistency. Does not require a round-trip to object storage, but may
186
+ # not see the latest writes.
187
+ #
188
+ # @param max_staleness_seconds [Integer] How long the query may reuse the node's cached view of the namespace before refr
189
+ #
190
+ # @param level [Symbol, :eventual]
168
191
  end
192
+
193
+ # @!method self.variants
194
+ # @return [Array(Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual)]
169
195
  end
170
196
 
171
197
  # Limits the documents returned by a query.
@@ -28,12 +28,20 @@ module Turbopuffer
28
28
  optional :aggregations, Turbopuffer::Internal::Type::HashOf[Turbopuffer::Internal::Type::Unknown]
29
29
 
30
30
  # @!attribute rows
31
+ # The documents that matched the query, ordered by `rank_by`. Only present when
32
+ # `rank_by` is set.
31
33
  #
32
34
  # @return [Array<Turbopuffer::Models::Row>, nil]
33
35
  optional :rows, -> { Turbopuffer::Internal::Type::ArrayOf[Turbopuffer::Row] }
34
36
 
35
37
  # @!method initialize(billing:, performance:, aggregation_groups: nil, aggregations: nil, rows: nil)
36
- # The result of a query.
38
+ # Some parameter documentations has been truncated, see
39
+ # {Turbopuffer::Models::NamespaceQueryResponse} for more details.
40
+ #
41
+ # The result of a query. With `aggregate_by`, `aggregations` maps each
42
+ # aggregation's label to its value. With `group_by` as well, `aggregation_groups`
43
+ # holds one object per group instead, with its group key and the value of each
44
+ # aggregation.
37
45
  #
38
46
  # @param billing [Turbopuffer::Models::QueryBilling] The billing information for a query.
39
47
  #
@@ -43,7 +51,7 @@ module Turbopuffer
43
51
  #
44
52
  # @param aggregations [Hash{Symbol=>Object}]
45
53
  #
46
- # @param rows [Array<Turbopuffer::Models::Row>]
54
+ # @param rows [Array<Turbopuffer::Models::Row>] The documents that matched the query, ordered by `rank_by`. Only present when `r
47
55
  end
48
56
  end
49
57
  end
@@ -59,6 +59,11 @@ module Turbopuffer
59
59
  required :query_vector, Turbopuffer::Internal::Type::ArrayOf[Float]
60
60
 
61
61
  # @!method initialize(nearest_neighbors:, query_vector:)
62
+ # One of the searches the evaluation ran: its query vector, sampled at random from
63
+ # the namespace's vectors unless `rank_by` is set, and the query's true nearest
64
+ # neighbors, found by exhaustive search. Recall compares these neighbors to the
65
+ # results of the approximate nearest neighbor (ANN) search.
66
+ #
62
67
  # @param nearest_neighbors [Array<Turbopuffer::Models::Row>] The true nearest neighbors with their distances and vectors.
63
68
  #
64
69
  # @param query_vector [Array<Float>] The query vector used for this search.
@@ -11,6 +11,8 @@ module Turbopuffer
11
11
  required :token, String
12
12
 
13
13
  # @!method initialize(token:)
14
+ # The response to a successful request to start a copy.
15
+ #
14
16
  # @param token [String] The token identifying the copy operation.
15
17
  end
16
18
  end