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
@@ -0,0 +1,340 @@
1
+ # typed: strong
2
+
3
+ module Turbopuffer
4
+ module Internal
5
+ module Transport
6
+ # @api private
7
+ #
8
+ # Called by the client at fixed points of every request. Custom code installs one
9
+ # with `BaseClient#request_observer=`. A single observer is shared across
10
+ # concurrent requests, so per-request state belongs on the scope returned by
11
+ # `#start`. Anything an observer raises is logged and ignored.
12
+ class RequestObserver
13
+ # @api private
14
+ #
15
+ # Called once per logical request. Returns nil to not observe the request.
16
+ sig do
17
+ params(
18
+ info: Turbopuffer::Internal::Transport::RequestObserver::RequestInfo
19
+ ).returns(
20
+ T.nilable(
21
+ Turbopuffer::Internal::Transport::RequestObserver::RequestScope
22
+ )
23
+ )
24
+ end
25
+ def start(info)
26
+ end
27
+
28
+ # @api private
29
+ #
30
+ # Observes a single logical request.
31
+ class RequestScope
32
+ # @api private
33
+ #
34
+ # Called before each attempt is sent. Changes to `request[:headers]` only apply to this attempt.
35
+ sig do
36
+ params(attempt: Integer, request: T::Hash[Symbol, T.anything]).void
37
+ end
38
+ def attempt_begin(attempt, request)
39
+ end
40
+
41
+ # @api private
42
+ #
43
+ # Called after each attempt, success or failure.
44
+ sig do
45
+ params(
46
+ result:
47
+ Turbopuffer::Internal::Transport::RequestObserver::AttemptResult
48
+ ).void
49
+ end
50
+ def attempt_end(result)
51
+ end
52
+
53
+ # @api private
54
+ #
55
+ # Called at most once, after the response is parsed or when the request fails for good.
56
+ # Streamed responses don't finish.
57
+ sig do
58
+ params(
59
+ result:
60
+ Turbopuffer::Internal::Transport::RequestObserver::RequestResult
61
+ ).void
62
+ end
63
+ def finish(result)
64
+ end
65
+ end
66
+
67
+ # @api private
68
+ class RequestInfo
69
+ sig { returns(Symbol) }
70
+ def method
71
+ end
72
+
73
+ # The request path, e.g. `/v2/namespaces/a/query`.
74
+ sig { returns(String) }
75
+ def url
76
+ end
77
+
78
+ sig { params(method: Symbol, url: String).returns(T.attached_class) }
79
+ def self.new(method:, url:)
80
+ end
81
+ end
82
+
83
+ # @api private
84
+ class AttemptResult
85
+ sig { returns(Integer) }
86
+ def attempt
87
+ end
88
+
89
+ sig { returns(T::Hash[Symbol, T.anything]) }
90
+ def request
91
+ end
92
+
93
+ sig { returns(T.nilable(Net::HTTPResponse)) }
94
+ def response
95
+ end
96
+
97
+ sig { returns(T.nilable(Exception)) }
98
+ def error
99
+ end
100
+
101
+ sig { returns(T.nilable(Symbol)) }
102
+ def error_kind
103
+ end
104
+
105
+ sig { returns(T.nilable(T::Boolean)) }
106
+ def reached_server
107
+ end
108
+
109
+ sig do
110
+ returns(Turbopuffer::Internal::Transport::RequestObserver::Timings)
111
+ end
112
+ def timings
113
+ end
114
+
115
+ sig do
116
+ params(
117
+ attempt: Integer,
118
+ request: T::Hash[Symbol, T.anything],
119
+ response: T.nilable(Net::HTTPResponse),
120
+ error: T.nilable(Exception),
121
+ error_kind: T.nilable(Symbol),
122
+ reached_server: T.nilable(T::Boolean),
123
+ timings:
124
+ Turbopuffer::Internal::Transport::RequestObserver::Timings
125
+ ).returns(T.attached_class)
126
+ end
127
+ def self.new(
128
+ attempt:,
129
+ request:,
130
+ response:,
131
+ error:,
132
+ error_kind:,
133
+ reached_server:,
134
+ timings:
135
+ )
136
+ end
137
+ end
138
+
139
+ # @api private
140
+ class RequestResult
141
+ sig { returns(Integer) }
142
+ def retries
143
+ end
144
+
145
+ sig { returns(T.nilable(Net::HTTPResponse)) }
146
+ def response
147
+ end
148
+
149
+ sig { returns(T.nilable(Exception)) }
150
+ def error
151
+ end
152
+
153
+ sig { returns(T.nilable(Symbol)) }
154
+ def error_kind
155
+ end
156
+
157
+ sig { returns(T.anything) }
158
+ def parsed
159
+ end
160
+
161
+ sig do
162
+ returns(Turbopuffer::Internal::Transport::RequestObserver::Timings)
163
+ end
164
+ def timings
165
+ end
166
+
167
+ sig do
168
+ params(
169
+ retries: Integer,
170
+ response: T.nilable(Net::HTTPResponse),
171
+ error: T.nilable(Exception),
172
+ error_kind: T.nilable(Symbol),
173
+ parsed: T.anything,
174
+ timings:
175
+ Turbopuffer::Internal::Transport::RequestObserver::Timings
176
+ ).returns(T.attached_class)
177
+ end
178
+ def self.new(
179
+ retries:,
180
+ response:,
181
+ error:,
182
+ error_kind:,
183
+ parsed:,
184
+ timings:
185
+ )
186
+ end
187
+ end
188
+
189
+ # @api private
190
+ #
191
+ # Monotonic timestamps of one attempt in integer nanoseconds, from `RequestObserver.now`.
192
+ class Timings
193
+ sig { returns(T.nilable(Integer)) }
194
+ attr_accessor :attempt_begin
195
+
196
+ sig { returns(T.nilable(Integer)) }
197
+ attr_accessor :serialize_begin
198
+
199
+ sig { returns(T.nilable(Integer)) }
200
+ attr_accessor :serialize_end
201
+
202
+ sig { returns(T.nilable(Integer)) }
203
+ attr_accessor :request_ready
204
+
205
+ sig { returns(T.nilable(Integer)) }
206
+ attr_accessor :connect_begin
207
+
208
+ sig { returns(T.nilable(Integer)) }
209
+ attr_accessor :connect_end
210
+
211
+ sig { returns(T.nilable(Integer)) }
212
+ attr_accessor :send_begin
213
+
214
+ sig { returns(T.nilable(Integer)) }
215
+ attr_accessor :send_end
216
+
217
+ sig { returns(T.nilable(Integer)) }
218
+ attr_accessor :response_headers
219
+
220
+ sig { returns(T.nilable(Integer)) }
221
+ attr_accessor :body_end
222
+
223
+ sig { returns(T.nilable(Integer)) }
224
+ attr_accessor :deserialize_begin
225
+
226
+ sig { returns(T.nilable(Integer)) }
227
+ attr_accessor :deserialize_end
228
+
229
+ # Whether the attempt used an existing connection, nil when unknown.
230
+ sig { returns(T.nilable(T::Boolean)) }
231
+ attr_accessor :reused
232
+
233
+ sig { returns(T::Hash[Symbol, T.anything]) }
234
+ attr_reader :extra
235
+
236
+ # @api private
237
+ sig { returns(T.attached_class) }
238
+ def self.new
239
+ end
240
+ end
241
+
242
+ # @api private
243
+ CONNECT_ERRORS = T.let(T.unsafe(nil), T::Array[T::Class[Exception]])
244
+
245
+ class << self
246
+ # @api private
247
+ sig { returns(Integer) }
248
+ def now
249
+ end
250
+
251
+ # @api private
252
+ sig do
253
+ params(hook: Symbol, blk: T.proc.returns(T.anything)).returns(
254
+ T.anything
255
+ )
256
+ end
257
+ def call_safely(hook, &blk)
258
+ end
259
+
260
+ # @api private
261
+ sig do
262
+ params(
263
+ error: Exception,
264
+ timings:
265
+ Turbopuffer::Internal::Transport::RequestObserver::Timings
266
+ ).returns(Symbol)
267
+ end
268
+ def error_kind(error, timings)
269
+ end
270
+ end
271
+
272
+ # @api private
273
+ #
274
+ # Drives a scope through one logical request for the client.
275
+ class Observation
276
+ # @api private
277
+ sig do
278
+ params(
279
+ observer: Turbopuffer::Internal::Transport::RequestObserver,
280
+ request: T::Hash[Symbol, T.anything],
281
+ started_at: Integer,
282
+ path: String
283
+ ).returns(T.nilable(T.attached_class))
284
+ end
285
+ def self.start(observer, request, started_at, path:)
286
+ end
287
+
288
+ # @api private
289
+ sig do
290
+ params(
291
+ input: T::Hash[Symbol, T.anything],
292
+ retry_count: Integer
293
+ ).returns(T::Hash[Symbol, T.anything])
294
+ end
295
+ def attempt_begin(input, retry_count:)
296
+ end
297
+
298
+ # @api private
299
+ sig do
300
+ params(
301
+ status: T.any(Integer, Exception),
302
+ response: T.nilable(Net::HTTPResponse)
303
+ ).void
304
+ end
305
+ def attempt_end(status, response)
306
+ end
307
+
308
+ # @api private
309
+ sig { void }
310
+ def deserialize_begin
311
+ end
312
+
313
+ # @api private
314
+ sig do
315
+ params(
316
+ response: T.nilable(Net::HTTPResponse),
317
+ parsed: T.anything,
318
+ error: T.nilable(Exception)
319
+ ).void
320
+ end
321
+ def finish(response: nil, parsed: nil, error: nil)
322
+ end
323
+
324
+ # @api private
325
+ sig do
326
+ params(
327
+ scope:
328
+ Turbopuffer::Internal::Transport::RequestObserver::RequestScope,
329
+ body: T::Boolean,
330
+ started_at: Integer,
331
+ built_at: Integer
332
+ ).returns(T.attached_class)
333
+ end
334
+ def self.new(scope, body:, started_at:, built_at:)
335
+ end
336
+ end
337
+ end
338
+ end
339
+ end
340
+ end
@@ -27,6 +27,7 @@ module Turbopuffer
27
27
  sig { returns(String) }
28
28
  attr_accessor :source_namespace
29
29
 
30
+ # Configuration for branching from another namespace.
30
31
  sig { params(source_namespace: String).returns(T.attached_class) }
31
32
  def self.new(
32
33
  # The namespace to create an instant, copy-on-write clone of.
@@ -38,6 +38,7 @@ module Turbopuffer
38
38
  sig { params(progress: String).void }
39
39
  attr_writer :progress
40
40
 
41
+ # The copy is still in progress.
41
42
  sig do
42
43
  params(start_time: Time, progress: String, status: Symbol).returns(
43
44
  T.attached_class
@@ -75,6 +76,7 @@ module Turbopuffer
75
76
  sig { returns(Time) }
76
77
  attr_accessor :finish_time
77
78
 
79
+ # The result of the copy.
78
80
  sig { returns(Turbopuffer::CopyFromNamespaceOperationResult::Variants) }
79
81
  attr_accessor :result
80
82
 
@@ -85,6 +87,7 @@ module Turbopuffer
85
87
  sig { returns(Symbol) }
86
88
  attr_accessor :status
87
89
 
90
+ # The copy has finished, successfully or not.
88
91
  sig do
89
92
  params(
90
93
  finish_time: Time,
@@ -100,6 +103,7 @@ module Turbopuffer
100
103
  def self.new(
101
104
  # The time at which the operation finished.
102
105
  finish_time:,
106
+ # The result of the copy.
103
107
  result:,
104
108
  # The time at which the operation started.
105
109
  start_time:,
@@ -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
 
@@ -22,7 +23,7 @@ module Turbopuffer
22
23
  )
23
24
  end
24
25
 
25
- # The response to a successful write request.
26
+ # The copy succeeded, with the result of its write.
26
27
  sig { returns(Turbopuffer::WriteResult) }
27
28
  attr_reader :success
28
29
 
@@ -35,7 +36,7 @@ module Turbopuffer
35
36
  )
36
37
  end
37
38
  def self.new(
38
- # The response to a successful write request.
39
+ # The copy succeeded, with the result of its write.
39
40
  success:
40
41
  )
41
42
  end
@@ -54,6 +55,7 @@ module Turbopuffer
54
55
  )
55
56
  end
56
57
 
58
+ # The copy failed, with its error.
57
59
  sig { returns(Turbopuffer::OperationError) }
58
60
  attr_reader :error
59
61
 
@@ -65,7 +67,10 @@ module Turbopuffer
65
67
  T.attached_class
66
68
  )
67
69
  end
68
- def self.new(error:)
70
+ def self.new(
71
+ # The copy failed, with its error.
72
+ error:
73
+ )
69
74
  end
70
75
 
71
76
  sig { override.returns({ error: Turbopuffer::OperationError }) }
@@ -41,6 +41,7 @@ module Turbopuffer
41
41
  sig { params(source_region: String).void }
42
42
  attr_writer :source_region
43
43
 
44
+ # Configuration for copying documents from another namespace.
44
45
  sig do
45
46
  params(
46
47
  source_namespace: String,
@@ -31,17 +31,44 @@ module Turbopuffer
31
31
  sig { returns(Symbol) }
32
32
  attr_accessor :mode
33
33
 
34
+ # The AWS KMS encryption context to send with every request that uses the key.
35
+ # Only supported on AWS, and must be enabled for your organization. Keys may not
36
+ # start with `tpuf:` or `aws:`.
37
+ sig { returns(T.nilable(T::Hash[Symbol, String])) }
38
+ attr_reader :encryption_context
39
+
40
+ sig { params(encryption_context: T::Hash[Symbol, String]).void }
41
+ attr_writer :encryption_context
42
+
34
43
  # Encrypt the namespace with a customer-managed encryption key (CMEK).
35
- sig { params(key_name: String, mode: Symbol).returns(T.attached_class) }
44
+ sig do
45
+ params(
46
+ key_name: String,
47
+ encryption_context: T::Hash[Symbol, String],
48
+ mode: Symbol
49
+ ).returns(T.attached_class)
50
+ end
36
51
  def self.new(
37
52
  # The identifier of the CMEK key to use for encryption. For GCP, the
38
53
  # fully-qualified resource name of the key. For AWS, the ARN of the key.
39
54
  key_name:,
55
+ # The AWS KMS encryption context to send with every request that uses the key.
56
+ # Only supported on AWS, and must be enabled for your organization. Keys may not
57
+ # start with `tpuf:` or `aws:`.
58
+ encryption_context: nil,
40
59
  mode: :"customer-managed"
41
60
  )
42
61
  end
43
62
 
44
- sig { override.returns({ key_name: String, mode: Symbol }) }
63
+ sig do
64
+ override.returns(
65
+ {
66
+ key_name: String,
67
+ mode: Symbol,
68
+ encryption_context: T::Hash[Symbol, String]
69
+ }
70
+ )
71
+ end
45
72
  def to_hash
46
73
  end
47
74
  end
@@ -40,7 +40,12 @@ module Turbopuffer
40
40
  # The consistency level for a query.
41
41
  sig do
42
42
  returns(
43
- T.nilable(Turbopuffer::NamespaceExplainQueryParams::Consistency)
43
+ T.nilable(
44
+ T.any(
45
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong,
46
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual
47
+ )
48
+ )
44
49
  )
45
50
  end
46
51
  attr_reader :consistency
@@ -48,7 +53,10 @@ module Turbopuffer
48
53
  sig do
49
54
  params(
50
55
  consistency:
51
- Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash
56
+ T.any(
57
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong::OrHash,
58
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual::OrHash
59
+ )
52
60
  ).void
53
61
  end
54
62
  attr_writer :consistency
@@ -141,7 +149,10 @@ module Turbopuffer
141
149
  aggregate_by: T::Hash[Symbol, T.anything],
142
150
  compute_attributes: T::Hash[Symbol, T.anything],
143
151
  consistency:
144
- Turbopuffer::NamespaceExplainQueryParams::Consistency::OrHash,
152
+ T.any(
153
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong::OrHash,
154
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual::OrHash
155
+ ),
145
156
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
146
157
  exclude_attributes: T::Array[String],
147
158
  filters: T.anything,
@@ -200,7 +211,11 @@ module Turbopuffer
200
211
  namespace: String,
201
212
  aggregate_by: T::Hash[Symbol, T.anything],
202
213
  compute_attributes: T::Hash[Symbol, T.anything],
203
- consistency: Turbopuffer::NamespaceExplainQueryParams::Consistency,
214
+ consistency:
215
+ T.any(
216
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong,
217
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual
218
+ ),
204
219
  distance_metric: Turbopuffer::DistanceMetric::OrSymbol,
205
220
  exclude_attributes: T::Array[String],
206
221
  filters: T.anything,
@@ -218,94 +233,92 @@ module Turbopuffer
218
233
  def to_hash
219
234
  end
220
235
 
221
- class Consistency < Turbopuffer::Internal::Type::BaseModel
222
- OrHash =
236
+ # The consistency level for a query.
237
+ module Consistency
238
+ extend Turbopuffer::Internal::Type::Union
239
+
240
+ Variants =
223
241
  T.type_alias do
224
242
  T.any(
225
- Turbopuffer::NamespaceExplainQueryParams::Consistency,
226
- Turbopuffer::Internal::AnyHash
243
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong,
244
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual
227
245
  )
228
246
  end
229
247
 
230
- # The query's consistency level.
231
- sig do
232
- returns(
233
- T.nilable(
234
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
235
- )
236
- )
237
- end
238
- attr_reader :level
248
+ class Strong < Turbopuffer::Internal::Type::BaseModel
249
+ OrHash =
250
+ T.type_alias do
251
+ T.any(
252
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Strong,
253
+ Turbopuffer::Internal::AnyHash
254
+ )
255
+ end
239
256
 
240
- sig do
241
- params(
242
- level:
243
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
244
- ).void
245
- end
246
- attr_writer :level
257
+ sig { returns(Symbol) }
258
+ attr_accessor :level
247
259
 
248
- # The consistency level for a query.
249
- sig do
250
- params(
251
- level:
252
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
253
- ).returns(T.attached_class)
254
- end
255
- def self.new(
256
- # The query's consistency level.
257
- level: nil
258
- )
259
- end
260
+ # Strong consistency. Requires a round-trip to object storage to fetch the latest
261
+ # writes.
262
+ sig { params(level: Symbol).returns(T.attached_class) }
263
+ def self.new(level: :strong)
264
+ end
260
265
 
261
- sig do
262
- override.returns(
263
- {
264
- level:
265
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::OrSymbol
266
- }
267
- )
268
- end
269
- def to_hash
266
+ sig { override.returns({ level: Symbol }) }
267
+ def to_hash
268
+ end
270
269
  end
271
270
 
272
- # The query's consistency level.
273
- module Level
274
- extend Turbopuffer::Internal::Type::Enum
275
-
276
- TaggedSymbol =
271
+ class Eventual < Turbopuffer::Internal::Type::BaseModel
272
+ OrHash =
277
273
  T.type_alias do
278
- T.all(
279
- Symbol,
280
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level
274
+ T.any(
275
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Eventual,
276
+ Turbopuffer::Internal::AnyHash
281
277
  )
282
278
  end
283
- OrSymbol = T.type_alias { T.any(Symbol, String) }
284
279
 
285
- # Strong consistency. Requires a round-trip to object storage to fetch the latest writes.
286
- STRONG =
287
- T.let(
288
- :strong,
289
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
290
- )
280
+ sig { returns(Symbol) }
281
+ attr_accessor :level
291
282
 
292
- # Eventual consistency. Does not require a round-trip to object storage, but may not see the latest writes.
293
- EVENTUAL =
294
- T.let(
295
- :eventual,
296
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
297
- )
283
+ # How long the query may reuse the node's cached view of the namespace before
284
+ # refreshing it from object storage. Defaults to 60.
285
+ sig { returns(T.nilable(Integer)) }
286
+ attr_reader :max_staleness_seconds
298
287
 
288
+ sig { params(max_staleness_seconds: Integer).void }
289
+ attr_writer :max_staleness_seconds
290
+
291
+ # Eventual consistency. Does not require a round-trip to object storage, but may
292
+ # not see the latest writes.
299
293
  sig do
300
- override.returns(
301
- T::Array[
302
- Turbopuffer::NamespaceExplainQueryParams::Consistency::Level::TaggedSymbol
303
- ]
294
+ params(max_staleness_seconds: Integer, level: Symbol).returns(
295
+ T.attached_class
304
296
  )
305
297
  end
306
- def self.values
298
+ def self.new(
299
+ # How long the query may reuse the node's cached view of the namespace before
300
+ # refreshing it from object storage. Defaults to 60.
301
+ max_staleness_seconds: nil,
302
+ level: :eventual
303
+ )
304
+ end
305
+
306
+ sig do
307
+ override.returns({ level: Symbol, max_staleness_seconds: Integer })
308
+ end
309
+ def to_hash
307
310
  end
308
311
  end
312
+
313
+ sig do
314
+ override.returns(
315
+ T::Array[
316
+ Turbopuffer::NamespaceExplainQueryParams::Consistency::Variants
317
+ ]
318
+ )
319
+ end
320
+ def self.variants
321
+ end
309
322
  end
310
323
 
311
324
  # Limits the documents returned by a query.