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
@@ -15,6 +15,7 @@ module Turbopuffer
15
15
  sig { returns(Symbol) }
16
16
  attr_accessor :status
17
17
 
18
+ # A message describing the result of the request.
18
19
  sig { returns(T.nilable(String)) }
19
20
  attr_reader :message
20
21
 
@@ -24,6 +25,7 @@ module Turbopuffer
24
25
  # The response to a successful cache warm request.
25
26
  sig { params(message: String, status: Symbol).returns(T.attached_class) }
26
27
  def self.new(
28
+ # A message describing the result of the request.
27
29
  message: nil,
28
30
  # The status of the request.
29
31
  status: :ACCEPTED
@@ -24,6 +24,7 @@ module Turbopuffer
24
24
  sig { returns(Turbopuffer::Encryption::Variants) }
25
25
  attr_accessor :encryption
26
26
 
27
+ # The state of the namespace's index.
27
28
  sig { returns(Turbopuffer::NamespaceMetadata::Index::Variants) }
28
29
  attr_accessor :index
29
30
 
@@ -94,6 +95,7 @@ module Turbopuffer
94
95
  created_at:,
95
96
  # The encryption configuration for a namespace.
96
97
  encryption:,
98
+ # The state of the namespace's index.
97
99
  index:,
98
100
  # The schema of the namespace.
99
101
  schema:,
@@ -131,6 +133,7 @@ module Turbopuffer
131
133
  def to_hash
132
134
  end
133
135
 
136
+ # The state of the namespace's index.
134
137
  module Index
135
138
  extend Turbopuffer::Internal::Type::Union
136
139
 
@@ -154,6 +157,7 @@ module Turbopuffer
154
157
  sig { returns(Symbol) }
155
158
  attr_accessor :status
156
159
 
160
+ # Every document in the namespace is indexed.
157
161
  sig { params(status: Symbol).returns(T.attached_class) }
158
162
  def self.new(status: :"up-to-date")
159
163
  end
@@ -184,6 +188,7 @@ module Turbopuffer
184
188
  sig { returns(Integer) }
185
189
  attr_accessor :unindexed_rows
186
190
 
191
+ # Some documents are in the write-ahead log and haven't been indexed yet.
187
192
  sig do
188
193
  params(
189
194
  unindexed_bytes: Integer,
@@ -25,14 +25,24 @@ module Turbopuffer
25
25
 
26
26
  # The consistency level for a query.
27
27
  sig do
28
- returns(T.nilable(Turbopuffer::NamespaceMultiQueryParams::Consistency))
28
+ returns(
29
+ T.nilable(
30
+ T.any(
31
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong,
32
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual
33
+ )
34
+ )
35
+ )
29
36
  end
30
37
  attr_reader :consistency
31
38
 
32
39
  sig do
33
40
  params(
34
41
  consistency:
35
- Turbopuffer::NamespaceMultiQueryParams::Consistency::OrHash
42
+ T.any(
43
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong::OrHash,
44
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual::OrHash
45
+ )
36
46
  ).void
37
47
  end
38
48
  attr_writer :consistency
@@ -76,7 +86,10 @@ module Turbopuffer
76
86
  T::Array[Turbopuffer::NamespaceMultiQueryParams::Query::OrHash],
77
87
  namespace: String,
78
88
  consistency:
79
- Turbopuffer::NamespaceMultiQueryParams::Consistency::OrHash,
89
+ T.any(
90
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong::OrHash,
91
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual::OrHash
92
+ ),
80
93
  limit: T.any(Integer, Turbopuffer::RerankLimit::OrHash),
81
94
  offset: Integer,
82
95
  rerank_by: T.anything,
@@ -107,7 +120,11 @@ module Turbopuffer
107
120
  {
108
121
  namespace: String,
109
122
  queries: T::Array[Turbopuffer::NamespaceMultiQueryParams::Query],
110
- consistency: Turbopuffer::NamespaceMultiQueryParams::Consistency,
123
+ consistency:
124
+ T.any(
125
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong,
126
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual
127
+ ),
111
128
  limit: T.any(Integer, Turbopuffer::RerankLimit),
112
129
  offset: Integer,
113
130
  rerank_by: T.anything,
@@ -305,94 +322,92 @@ module Turbopuffer
305
322
  end
306
323
  end
307
324
 
308
- class Consistency < Turbopuffer::Internal::Type::BaseModel
309
- OrHash =
325
+ # The consistency level for a query.
326
+ module Consistency
327
+ extend Turbopuffer::Internal::Type::Union
328
+
329
+ Variants =
310
330
  T.type_alias do
311
331
  T.any(
312
- Turbopuffer::NamespaceMultiQueryParams::Consistency,
313
- Turbopuffer::Internal::AnyHash
332
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong,
333
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual
314
334
  )
315
335
  end
316
336
 
317
- # The query's consistency level.
318
- sig do
319
- returns(
320
- T.nilable(
321
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::OrSymbol
322
- )
323
- )
324
- end
325
- attr_reader :level
337
+ class Strong < Turbopuffer::Internal::Type::BaseModel
338
+ OrHash =
339
+ T.type_alias do
340
+ T.any(
341
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong,
342
+ Turbopuffer::Internal::AnyHash
343
+ )
344
+ end
326
345
 
327
- sig do
328
- params(
329
- level:
330
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::OrSymbol
331
- ).void
332
- end
333
- attr_writer :level
346
+ sig { returns(Symbol) }
347
+ attr_accessor :level
334
348
 
335
- # The consistency level for a query.
336
- sig do
337
- params(
338
- level:
339
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::OrSymbol
340
- ).returns(T.attached_class)
341
- end
342
- def self.new(
343
- # The query's consistency level.
344
- level: nil
345
- )
346
- end
349
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
350
+ # writes.
351
+ sig { params(level: Symbol).returns(T.attached_class) }
352
+ def self.new(level: :strong)
353
+ end
347
354
 
348
- sig do
349
- override.returns(
350
- {
351
- level:
352
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::OrSymbol
353
- }
354
- )
355
- end
356
- def to_hash
355
+ sig { override.returns({ level: Symbol }) }
356
+ def to_hash
357
+ end
357
358
  end
358
359
 
359
- # The query's consistency level.
360
- module Level
361
- extend Turbopuffer::Internal::Type::Enum
362
-
363
- TaggedSymbol =
360
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
361
+ OrHash =
364
362
  T.type_alias do
365
- T.all(
366
- Symbol,
367
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level
363
+ T.any(
364
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual,
365
+ Turbopuffer::Internal::AnyHash
368
366
  )
369
367
  end
370
- OrSymbol = T.type_alias { T.any(Symbol, String) }
371
368
 
372
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
373
- STRONG =
374
- T.let(
375
- :strong,
376
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::TaggedSymbol
377
- )
369
+ sig { returns(Symbol) }
370
+ attr_accessor :level
378
371
 
379
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
380
- EVENTUAL =
381
- T.let(
382
- :eventual,
383
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::TaggedSymbol
384
- )
372
+ # How long the query may reuse the node's cached view of the namespace before
373
+ # refreshing it from object storage. Defaults to 60.
374
+ sig { returns(T.nilable(Integer)) }
375
+ attr_reader :max_staleness_seconds
376
+
377
+ sig { params(max_staleness_seconds: Integer).void }
378
+ attr_writer :max_staleness_seconds
385
379
 
380
+ # Eventual consistency. Does not require a round-trip to object storage, but may
381
+ # not see the latest writes.
386
382
  sig do
387
- override.returns(
388
- T::Array[
389
- Turbopuffer::NamespaceMultiQueryParams::Consistency::Level::TaggedSymbol
390
- ]
383
+ params(max_staleness_seconds: Integer, level: Symbol).returns(
384
+ T.attached_class
391
385
  )
392
386
  end
393
- def self.values
387
+ def self.new(
388
+ # How long the query may reuse the node's cached view of the namespace before
389
+ # refreshing it from object storage. Defaults to 60.
390
+ max_staleness_seconds: nil,
391
+ level: :eventual
392
+ )
393
+ end
394
+
395
+ sig do
396
+ override.returns({ level: Symbol, max_staleness_seconds: Integer })
397
+ end
398
+ def to_hash
394
399
  end
395
400
  end
401
+
402
+ sig do
403
+ override.returns(
404
+ T::Array[
405
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Variants
406
+ ]
407
+ )
408
+ end
409
+ def self.variants
410
+ end
396
411
  end
397
412
 
398
413
  # Limits the total number of reranked documents returned.
@@ -25,6 +25,8 @@ module Turbopuffer
25
25
  sig { params(performance: Turbopuffer::QueryPerformance::OrHash).void }
26
26
  attr_writer :performance
27
27
 
28
+ # The results of each subquery, in the same order as `queries`. With `rerank_by`,
29
+ # a single result combining the subqueries' rows.
28
30
  sig do
29
31
  returns(
30
32
  T::Array[Turbopuffer::Models::NamespaceMultiQueryResponse::Result]
@@ -48,6 +50,8 @@ module Turbopuffer
48
50
  billing:,
49
51
  # The performance information for a query.
50
52
  performance:,
53
+ # The results of each subquery, in the same order as `queries`. With `rerank_by`,
54
+ # a single result combining the subqueries' rows.
51
55
  results:
52
56
  )
53
57
  end
@@ -88,12 +92,18 @@ module Turbopuffer
88
92
  sig { params(aggregations: T::Hash[Symbol, T.anything]).void }
89
93
  attr_writer :aggregations
90
94
 
95
+ # The documents that matched the query, ordered by `rank_by`. Only present when
96
+ # `rank_by` is set.
91
97
  sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
92
98
  attr_reader :rows
93
99
 
94
100
  sig { params(rows: T::Array[Turbopuffer::Row::OrHash]).void }
95
101
  attr_writer :rows
96
102
 
103
+ # The result of a query, or of one subquery of a multi-query. With `aggregate_by`,
104
+ # `aggregations` maps each aggregation's label to its value. With `group_by` as
105
+ # well, `aggregation_groups` holds one object per group instead, with its group
106
+ # key and the value of each aggregation.
97
107
  sig do
98
108
  params(
99
109
  aggregation_groups: T::Array[T::Hash[Symbol, T.anything]],
@@ -101,7 +111,13 @@ module Turbopuffer
101
111
  rows: T::Array[Turbopuffer::Row::OrHash]
102
112
  ).returns(T.attached_class)
103
113
  end
104
- def self.new(aggregation_groups: nil, aggregations: nil, rows: nil)
114
+ def self.new(
115
+ aggregation_groups: nil,
116
+ aggregations: nil,
117
+ # The documents that matched the query, ordered by `rank_by`. Only present when
118
+ # `rank_by` is set.
119
+ rows: nil
120
+ )
105
121
  end
106
122
 
107
123
  sig do
@@ -38,12 +38,25 @@ module Turbopuffer
38
38
  attr_writer :compute_attributes
39
39
 
40
40
  # The consistency level for a query.
41
- sig { returns(T.nilable(Turbopuffer::NamespaceQueryParams::Consistency)) }
41
+ sig do
42
+ returns(
43
+ T.nilable(
44
+ T.any(
45
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong,
46
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual
47
+ )
48
+ )
49
+ )
50
+ end
42
51
  attr_reader :consistency
43
52
 
44
53
  sig do
45
54
  params(
46
- consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash
55
+ consistency:
56
+ T.any(
57
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong::OrHash,
58
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual::OrHash
59
+ )
47
60
  ).void
48
61
  end
49
62
  attr_writer :consistency
@@ -142,7 +155,11 @@ module Turbopuffer
142
155
  namespace: String,
143
156
  aggregate_by: T::Hash[Symbol, T.anything],
144
157
  compute_attributes: T::Hash[Symbol, T.anything],
145
- consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash,
158
+ consistency:
159
+ T.any(
160
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong::OrHash,
161
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual::OrHash
162
+ ),
146
163
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
147
164
  exclude_attributes: T::Array[String],
148
165
  filters: T.anything,
@@ -204,7 +221,11 @@ module Turbopuffer
204
221
  namespace: String,
205
222
  aggregate_by: T::Hash[Symbol, T.anything],
206
223
  compute_attributes: T::Hash[Symbol, T.anything],
207
- consistency: Turbopuffer::NamespaceQueryParams::Consistency,
224
+ consistency:
225
+ T.any(
226
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong,
227
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual
228
+ ),
208
229
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
209
230
  exclude_attributes: T::Array[String],
210
231
  filters: T.anything,
@@ -223,94 +244,90 @@ module Turbopuffer
223
244
  def to_hash
224
245
  end
225
246
 
226
- class Consistency < Turbopuffer::Internal::Type::BaseModel
227
- OrHash =
247
+ # The consistency level for a query.
248
+ module Consistency
249
+ extend Turbopuffer::Internal::Type::Union
250
+
251
+ Variants =
228
252
  T.type_alias do
229
253
  T.any(
230
- Turbopuffer::NamespaceQueryParams::Consistency,
231
- Turbopuffer::Internal::AnyHash
254
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong,
255
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual
232
256
  )
233
257
  end
234
258
 
235
- # The query's consistency level.
236
- sig do
237
- returns(
238
- T.nilable(
239
- Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
240
- )
241
- )
242
- end
243
- attr_reader :level
259
+ class Strong < Turbopuffer::Internal::Type::BaseModel
260
+ OrHash =
261
+ T.type_alias do
262
+ T.any(
263
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong,
264
+ Turbopuffer::Internal::AnyHash
265
+ )
266
+ end
244
267
 
245
- sig do
246
- params(
247
- level:
248
- Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
249
- ).void
250
- end
251
- attr_writer :level
268
+ sig { returns(Symbol) }
269
+ attr_accessor :level
252
270
 
253
- # The consistency level for a query.
254
- sig do
255
- params(
256
- level:
257
- Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
258
- ).returns(T.attached_class)
259
- end
260
- def self.new(
261
- # The query's consistency level.
262
- level: nil
263
- )
264
- end
271
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
272
+ # writes.
273
+ sig { params(level: Symbol).returns(T.attached_class) }
274
+ def self.new(level: :strong)
275
+ end
265
276
 
266
- sig do
267
- override.returns(
268
- {
269
- level:
270
- Turbopuffer::NamespaceQueryParams::Consistency::Level::OrSymbol
271
- }
272
- )
273
- end
274
- def to_hash
277
+ sig { override.returns({ level: Symbol }) }
278
+ def to_hash
279
+ end
275
280
  end
276
281
 
277
- # The query's consistency level.
278
- module Level
279
- extend Turbopuffer::Internal::Type::Enum
280
-
281
- TaggedSymbol =
282
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
283
+ OrHash =
282
284
  T.type_alias do
283
- T.all(
284
- Symbol,
285
- Turbopuffer::NamespaceQueryParams::Consistency::Level
285
+ T.any(
286
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual,
287
+ Turbopuffer::Internal::AnyHash
286
288
  )
287
289
  end
288
- OrSymbol = T.type_alias { T.any(Symbol, String) }
289
290
 
290
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
291
- STRONG =
292
- T.let(
293
- :strong,
294
- Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
295
- )
291
+ sig { returns(Symbol) }
292
+ attr_accessor :level
296
293
 
297
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
298
- EVENTUAL =
299
- T.let(
300
- :eventual,
301
- Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
302
- )
294
+ # How long the query may reuse the node's cached view of the namespace before
295
+ # refreshing it from object storage. Defaults to 60.
296
+ sig { returns(T.nilable(Integer)) }
297
+ attr_reader :max_staleness_seconds
298
+
299
+ sig { params(max_staleness_seconds: Integer).void }
300
+ attr_writer :max_staleness_seconds
303
301
 
302
+ # Eventual consistency. Does not require a round-trip to object storage, but may
303
+ # not see the latest writes.
304
304
  sig do
305
- override.returns(
306
- T::Array[
307
- Turbopuffer::NamespaceQueryParams::Consistency::Level::TaggedSymbol
308
- ]
305
+ params(max_staleness_seconds: Integer, level: Symbol).returns(
306
+ T.attached_class
309
307
  )
310
308
  end
311
- def self.values
309
+ def self.new(
310
+ # How long the query may reuse the node's cached view of the namespace before
311
+ # refreshing it from object storage. Defaults to 60.
312
+ max_staleness_seconds: nil,
313
+ level: :eventual
314
+ )
315
+ end
316
+
317
+ sig do
318
+ override.returns({ level: Symbol, max_staleness_seconds: Integer })
319
+ end
320
+ def to_hash
312
321
  end
313
322
  end
323
+
324
+ sig do
325
+ override.returns(
326
+ T::Array[Turbopuffer::NamespaceQueryParams::Consistency::Variants]
327
+ )
328
+ end
329
+ def self.variants
330
+ end
314
331
  end
315
332
 
316
333
  # Limits the documents returned by a query.
@@ -39,13 +39,18 @@ module Turbopuffer
39
39
  sig { params(aggregations: T::Hash[Symbol, T.anything]).void }
40
40
  attr_writer :aggregations
41
41
 
42
+ # The documents that matched the query, ordered by `rank_by`. Only present when
43
+ # `rank_by` is set.
42
44
  sig { returns(T.nilable(T::Array[Turbopuffer::Row])) }
43
45
  attr_reader :rows
44
46
 
45
47
  sig { params(rows: T::Array[Turbopuffer::Row::OrHash]).void }
46
48
  attr_writer :rows
47
49
 
48
- # The result of a query.
50
+ # The result of a query. With `aggregate_by`, `aggregations` maps each
51
+ # aggregation's label to its value. With `group_by` as well, `aggregation_groups`
52
+ # holds one object per group instead, with its group key and the value of each
53
+ # aggregation.
49
54
  sig do
50
55
  params(
51
56
  billing: Turbopuffer::QueryBilling::OrHash,
@@ -62,6 +67,8 @@ module Turbopuffer
62
67
  performance:,
63
68
  aggregation_groups: nil,
64
69
  aggregations: nil,
70
+ # The documents that matched the query, ordered by `rank_by`. Only present when
71
+ # `rank_by` is set.
65
72
  rows: nil
66
73
  )
67
74
  end
@@ -104,6 +104,10 @@ module Turbopuffer
104
104
  sig { returns(T::Array[Float]) }
105
105
  attr_accessor :query_vector
106
106
 
107
+ # One of the searches the evaluation ran: its query vector, sampled at random from
108
+ # the namespace's vectors unless `rank_by` is set, and the query's true nearest
109
+ # neighbors, found by exhaustive search. Recall compares these neighbors to the
110
+ # results of the approximate nearest neighbor (ANN) search.
107
111
  sig do
108
112
  params(
109
113
  nearest_neighbors: T::Array[Turbopuffer::Row::OrHash],
@@ -15,6 +15,7 @@ module Turbopuffer
15
15
  sig { returns(String) }
16
16
  attr_accessor :token
17
17
 
18
+ # The response to a successful request to start a copy.
18
19
  sig { params(token: String).returns(T.attached_class) }
19
20
  def self.new(
20
21
  # The token identifying the copy operation.
@@ -147,7 +147,7 @@ module Turbopuffer
147
147
  end
148
148
  attr_writer :encryption
149
149
 
150
- # The patch and filter specifying which documents to patch.
150
+ # Sets the attributes in `patch` on every document that matches `filters`.
151
151
  sig do
152
152
  returns(T.nilable(Turbopuffer::NamespaceWriteParams::PatchByFilter))
153
153
  end
@@ -337,7 +337,7 @@ module Turbopuffer
337
337
  distance_metric: nil,
338
338
  # The encryption configuration for a namespace.
339
339
  encryption: nil,
340
- # The patch and filter specifying which documents to patch.
340
+ # Sets the attributes in `patch` on every document that matches `filters`.
341
341
  patch_by_filter: nil,
342
342
  # Allow partial completion when filter matches too many documents.
343
343
  patch_by_filter_allow_partial: nil,
@@ -438,7 +438,7 @@ module Turbopuffer
438
438
  sig { returns(T::Hash[Symbol, T.anything]) }
439
439
  attr_accessor :patch
440
440
 
441
- # The patch and filter specifying which documents to patch.
441
+ # Sets the attributes in `patch` on every document that matches `filters`.
442
442
  sig do
443
443
  params(
444
444
  filters: T.anything,
@@ -19,6 +19,7 @@ module Turbopuffer
19
19
  sig { returns(Integer) }
20
20
  attr_accessor :status_code
21
21
 
22
+ # The error of an asynchronous operation that failed.
22
23
  sig do
23
24
  params(
24
25
  detail: Turbopuffer::OperationError::Detail::OrHash,
@@ -86,7 +86,7 @@ module Turbopuffer
86
86
  sig { params(upserted_ids: T::Array[Turbopuffer::ID::Variants]).void }
87
87
  attr_writer :upserted_ids
88
88
 
89
- # The response to a successful write request.
89
+ # The copy succeeded, with the result of its write.
90
90
  sig do
91
91
  params(
92
92
  billing: Turbopuffer::WriteBilling::OrHash,
@@ -73,7 +73,10 @@ module Turbopuffer
73
73
  aggregate_by: T::Hash[Symbol, T.anything],
74
74
  compute_attributes: T::Hash[Symbol, T.anything],
75
75
  consistency:
76
- Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash,
76
+ T.any(
77
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong::OrHash,
78
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual::OrHash
79
+ ),
77
80
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
78
81
  exclude_attributes: T::Array[String],
79
82
  filters: T.anything,
@@ -162,7 +165,10 @@ module Turbopuffer
162
165
  T::Array[Turbopuffer::NamespaceMultiQueryParams::Query::OrHash],
163
166
  namespace: String,
164
167
  consistency:
165
- Turbopuffer::NamespaceMultiQueryParams::Consistency::OrHash,
168
+ T.any(
169
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Strong::OrHash,
170
+ Turbopuffer::NamespaceMultiQueryParams::Consistency::Eventual::OrHash
171
+ ),
166
172
  limit: T.any(Integer, Turbopuffer::RerankLimit::OrHash),
167
173
  offset: Integer,
168
174
  rerank_by: T.anything,
@@ -214,7 +220,11 @@ module Turbopuffer
214
220
  namespace: T.nilable(String),
215
221
  aggregate_by: T::Hash[Symbol, T.anything],
216
222
  compute_attributes: T::Hash[Symbol, T.anything],
217
- consistency: Turbopuffer::NamespaceQueryParams::Consistency::OrHash,
223
+ consistency:
224
+ T.any(
225
+ Turbopuffer::NamespaceQueryParams::Consistency::Strong::OrHash,
226
+ Turbopuffer::NamespaceQueryParams::Consistency::Eventual::OrHash
227
+ ),
218
228
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
219
229
  exclude_attributes: T::Array[String],
220
230
  filters: T.anything,
@@ -481,7 +491,8 @@ module Turbopuffer
481
491
  distance_metric: nil,
482
492
  # Body param: The encryption configuration for a namespace.
483
493
  encryption: nil,
484
- # Body param: The patch and filter specifying which documents to patch.
494
+ # Body param: Sets the attributes in `patch` on every document that matches
495
+ # `filters`.
485
496
  patch_by_filter: nil,
486
497
  # Body param: Allow partial completion when filter matches too many documents.
487
498
  patch_by_filter_allow_partial: nil,