turbopuffer 2.9.0 → 2.11.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 (31) hide show
  1. checksums.yaml +4 -4
  2. data/CHANGELOG.md +22 -0
  3. data/README.md +10 -2
  4. data/lib/turbopuffer/client.rb +10 -1
  5. data/lib/turbopuffer/internal/telemetry.rb +86 -10
  6. data/lib/turbopuffer/internal/transport/base_client.rb +12 -1
  7. data/lib/turbopuffer/models/encryption.rb +11 -1
  8. data/lib/turbopuffer/models/namespace_explain_query_params.rb +50 -24
  9. data/lib/turbopuffer/models/namespace_multi_query_params.rb +50 -24
  10. data/lib/turbopuffer/models/namespace_query_params.rb +50 -24
  11. data/lib/turbopuffer/resources/namespaces.rb +3 -3
  12. data/lib/turbopuffer/version.rb +1 -1
  13. data/lib/turbopuffer.rb +0 -1
  14. data/manifest.yaml +0 -1
  15. data/rbi/turbopuffer/client.rbi +9 -2
  16. data/rbi/turbopuffer/internal/telemetry.rbi +43 -3
  17. data/rbi/turbopuffer/internal/transport/base_client.rbi +5 -0
  18. data/rbi/turbopuffer/models/encryption.rbi +29 -2
  19. data/rbi/turbopuffer/models/namespace_explain_query_params.rbi +84 -71
  20. data/rbi/turbopuffer/models/namespace_multi_query_params.rbi +86 -71
  21. data/rbi/turbopuffer/models/namespace_query_params.rbi +88 -71
  22. data/rbi/turbopuffer/resources/namespaces.rbi +13 -3
  23. data/sig/turbopuffer/client.rbs +4 -1
  24. data/sig/turbopuffer/internal/telemetry.rbs +14 -1
  25. data/sig/turbopuffer/internal/transport/base_client.rbs +3 -0
  26. data/sig/turbopuffer/models/encryption.rbs +22 -3
  27. data/sig/turbopuffer/models/namespace_explain_query_params.rbs +30 -28
  28. data/sig/turbopuffer/models/namespace_multi_query_params.rbs +30 -28
  29. data/sig/turbopuffer/models/namespace_query_params.rbs +30 -26
  30. data/sig/turbopuffer/resources/namespaces.rbs +3 -3
  31. metadata +3 -3
@@ -106,7 +106,7 @@ module Turbopuffer
106
106
  #
107
107
  # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
108
108
  #
109
- # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency] Body param: The consistency level for a query.
109
+ # @param consistency [Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceExplainQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
110
110
  #
111
111
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
112
112
  #
@@ -209,7 +209,7 @@ module Turbopuffer
209
209
  #
210
210
  # @param namespace [String] Path param: The name of the namespace.
211
211
  #
212
- # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency] Body param: The consistency level for a query.
212
+ # @param consistency [Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceMultiQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
213
213
  #
214
214
  # @param limit [Integer, Turbopuffer::Models::RerankLimit] Body param: Limits the total number of reranked documents returned.
215
215
  #
@@ -279,7 +279,7 @@ module Turbopuffer
279
279
  #
280
280
  # @param compute_attributes [Hash{Symbol=>Object}] Body param: Computes additional values on documents returned by a query. Each ke
281
281
  #
282
- # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency] Body param: The consistency level for a query.
282
+ # @param consistency [Turbopuffer::Models::NamespaceQueryParams::Consistency::Strong, Turbopuffer::Models::NamespaceQueryParams::Consistency::Eventual] Body param: The consistency level for a query.
283
283
  #
284
284
  # @param distance_metric [Symbol, Turbopuffer::Models::DistanceMetric] Body param: A function used to calculate vector similarity.
285
285
  #
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Turbopuffer
4
- VERSION = "2.9.0"
4
+ VERSION = "2.11.0"
5
5
  end
data/lib/turbopuffer.rb CHANGED
@@ -3,7 +3,6 @@
3
3
  # Standard libraries.
4
4
  # rubocop:disable Lint/RedundantRequireStatement
5
5
  require "English"
6
- require "base64"
7
6
  require "cgi"
8
7
  require "date"
9
8
  require "erb"
data/manifest.yaml CHANGED
@@ -1,6 +1,5 @@
1
1
  dependencies:
2
2
  - English
3
- - base64
4
3
  - cgi
5
4
  - date
6
5
  - erb
@@ -10,6 +10,8 @@ module Turbopuffer
10
10
 
11
11
  DEFAULT_MAX_RETRY_DELAY = T.let(8.0, Float)
12
12
 
13
+ DEFAULT_MAX_CONNECTIONS = T.let(T.unsafe(nil), Integer)
14
+
13
15
  # API key used for authentication.
14
16
  sig { returns(String) }
15
17
  attr_reader :api_key
@@ -70,7 +72,8 @@ module Turbopuffer
70
72
  max_retries: Integer,
71
73
  timeout: Float,
72
74
  initial_retry_delay: Float,
73
- max_retry_delay: Float
75
+ max_retry_delay: Float,
76
+ max_connections: Integer
74
77
  ).returns(T.attached_class)
75
78
  end
76
79
  def self.new(
@@ -92,7 +95,11 @@ module Turbopuffer
92
95
  max_retries: Turbopuffer::Client::DEFAULT_MAX_RETRIES,
93
96
  timeout: Turbopuffer::Client::DEFAULT_TIMEOUT_IN_SECONDS,
94
97
  initial_retry_delay: Turbopuffer::Client::DEFAULT_INITIAL_RETRY_DELAY,
95
- max_retry_delay: Turbopuffer::Client::DEFAULT_MAX_RETRY_DELAY
98
+ max_retry_delay: Turbopuffer::Client::DEFAULT_MAX_RETRY_DELAY,
99
+ # Max number of concurrent HTTP connections to each origin. When all are in use,
100
+ # requests wait for one to become free, with the wait counting towards the request
101
+ # timeout.
102
+ max_connections: Turbopuffer::Client::DEFAULT_MAX_CONNECTIONS
96
103
  )
97
104
  end
98
105
  end
@@ -9,6 +9,16 @@ module Turbopuffer
9
9
  ENV_VAR = T.let(T.unsafe(nil), String)
10
10
  HEADER = T.let(T.unsafe(nil), String)
11
11
  SAMPLE_RATE_HEADER = T.let(T.unsafe(nil), String)
12
+ # Sorted by ASCII value, so that encoded IDs sort like their bytes.
13
+ REQUEST_ID_ALPHABET = T.let(T.unsafe(nil), String)
14
+ # The bytes in a request ID before it's encoded.
15
+ REQUEST_ID_BYTES = T.let(T.unsafe(nil), Integer)
16
+ # The request header that carries the IDs of recorded requests.
17
+ REQUEST_ID_HEADER = T.let(T.unsafe(nil), String)
18
+ # The prefix of generated request IDs.
19
+ REQUEST_ID_PREFIX = T.let(T.unsafe(nil), String)
20
+ # The random bytes at the start of a request ID.
21
+ REQUEST_ID_RANDOM_BYTES = T.let(T.unsafe(nil), Integer)
12
22
 
13
23
  ENVELOPE_VERSION = T.let(T.unsafe(nil), Integer)
14
24
 
@@ -60,6 +70,24 @@ module Turbopuffer
60
70
  def random
61
71
  end
62
72
 
73
+ # @api private
74
+ #
75
+ # Encodes `bytes` in base32 with `REQUEST_ID_ALPHABET`, in RFC 4648's bit order without
76
+ # padding.
77
+ sig { params(bytes: String).returns(String) }
78
+ def encode_base32(bytes)
79
+ end
80
+
81
+ # @api private
82
+ #
83
+ # Generates the ID of a request that will be recorded. Its format is private to turbopuffer.
84
+ sig { params(now: Time, random: String).returns(String) }
85
+ def new_request_id(
86
+ now,
87
+ random: SecureRandom.random_bytes(REQUEST_ID_RANDOM_BYTES)
88
+ )
89
+ end
90
+
63
91
  # @api private
64
92
  #
65
93
  # Returns the buffer shared by clients with the same API key and base URL, or nil if
@@ -129,7 +157,15 @@ module Turbopuffer
129
157
 
130
158
  # @api private
131
159
  #
132
- # Samples and buffers a record for one request.
160
+ # Decides whether to record a request that's starting, returning the sample rate it was
161
+ # recorded at.
162
+ sig { returns(T.nilable(Float)) }
163
+ def sample
164
+ end
165
+
166
+ # @api private
167
+ #
168
+ # Buffers the record of a request sampled at `sample_rate`.
133
169
  sig do
134
170
  params(
135
171
  method: T.any(Symbol, String),
@@ -137,9 +173,11 @@ module Turbopuffer
137
173
  status: Integer,
138
174
  retries: Integer,
139
175
  durations: T::Hash[Symbol, Integer],
176
+ sample_rate: Float,
140
177
  server_total_ms: T.nilable(Numeric),
141
178
  error: T.nilable(String),
142
- reused: T.nilable(T::Boolean)
179
+ reused: T.nilable(T::Boolean),
180
+ request_id: T.nilable(String)
143
181
  ).void
144
182
  end
145
183
  def record(
@@ -148,9 +186,11 @@ module Turbopuffer
148
186
  status:,
149
187
  retries:,
150
188
  durations:,
189
+ sample_rate:,
151
190
  server_total_ms: nil,
152
191
  error: nil,
153
- reused: nil
192
+ reused: nil,
193
+ request_id: nil
154
194
  )
155
195
  end
156
196
 
@@ -132,6 +132,9 @@ module Turbopuffer
132
132
  sig { returns(Float) }
133
133
  attr_reader :max_retry_delay
134
134
 
135
+ sig { returns(Integer) }
136
+ attr_reader :max_connections
137
+
135
138
  sig { returns(T::Hash[String, String]) }
136
139
  attr_reader :headers
137
140
 
@@ -156,6 +159,7 @@ module Turbopuffer
156
159
  max_retries: Integer,
157
160
  initial_retry_delay: Float,
158
161
  max_retry_delay: Float,
162
+ max_connections: Integer,
159
163
  headers:
160
164
  T::Hash[
161
165
  String,
@@ -176,6 +180,7 @@ module Turbopuffer
176
180
  max_retries: 0,
177
181
  initial_retry_delay: 0.0,
178
182
  max_retry_delay: 0.0,
183
+ max_connections: Turbopuffer::Internal::Transport::PooledNetRequester::DEFAULT_MAX_CONNECTIONS,
179
184
  headers: {},
180
185
  idempotency_header: nil
181
186
  )
@@ -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.
@@ -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.