Class: Turbopuffer::Resources::Namespaces

Inherits:
Object
  • Object
show all
Defined in:
lib/turbopuffer/resources/namespaces.rb,
sig/turbopuffer/resources/namespaces.rbs

Direct Known Subclasses

Namespace

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Namespaces

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Namespaces.

Parameters:



484
485
486
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 484

def initialize(client:)
  @client = client
end

Instance Method Details

#branch_from(source_namespace:, namespace: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceBranchFromResponse

Creates an instant, copy-on-write clone of a namespace.

Parameters:

  • source_namespace (String) —

    Body param: The namespace to create an instant, copy-on-write clone of.

  • namespace (String) —

    Path param: The name of the namespace.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



19
20
21
22
23
24
25
26
27
28
29
30
31
32
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 19

def branch_from(params)
  parsed, options = Turbopuffer::NamespaceBranchFromParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s?stainless_overload=branchFrom", namespace],
    body: {branch_from_namespace: parsed},
    model: Turbopuffer::Models::NamespaceBranchFromResponse,
    options: options
  )
end

#copy_from(source_namespace:, namespace: nil, dest_encryption: nil, source_api_key: nil, source_region: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceCopyFromResponse

Some parameter documentations has been truncated, see Models::NamespaceCopyFromParams for more details.

Copy all documents from another namespace into this one.

Parameters:

  • source_namespace (String) —

    Body param: The namespace to copy documents from.

  • namespace (String) —

    Path param: The name of the namespace.

  • dest_encryption (Turbopuffer::Models::Encryption::CustomerManaged, Turbopuffer::Models::Encryption::Default) —

    Body param: (Optional) The encryption configuration for the destination namespac

  • source_api_key (String) —

    Body param: (Optional) An API key for the organization containing the source nam

  • source_region (String) —

    Body param: (Optional) The region of the source namespace.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



56
57
58
59
60
61
62
63
64
65
66
67
68
69
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 56

def copy_from(params)
  parsed, options = Turbopuffer::NamespaceCopyFromParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s?stainless_overload=copyFrom", namespace],
    body: {copy_from_namespace: parsed},
    model: Turbopuffer::Models::NamespaceCopyFromResponse,
    options: options
  )
end

#delete_all(namespace: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceDeleteAllResponse

Delete namespace.

Parameters:

Returns:

See Also:



82
83
84
85
86
87
88
89
90
91
92
93
94
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 82

def delete_all(params = {})
  parsed, options = Turbopuffer::NamespaceDeleteAllParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :delete,
    path: ["v2/namespaces/%1$s", namespace],
    model: Turbopuffer::Models::NamespaceDeleteAllResponse,
    options: options
  )
end

#explain_query(namespace: nil, aggregate_by: nil, compute_attributes: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: nil, include_attributes: nil, limit: nil, rank_by: nil, top_k: nil, vector_encoding: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceExplainQueryResponse

Some parameter documentations has been truncated, see Models::NamespaceExplainQueryParams for more details.

Explain a query plan.

Parameters:

  • namespace (String) —

    Path param: The name of the namespace.

  • aggregate_by (Hash{Symbol=>Object}) —

    Body param: Aggregations to compute over all documents in the namespace that mat

  • compute_attributes (Hash{Symbol=>Object}) —

    Body param: Computes additional values on documents returned by a query. Each ke

  • consistency (Turbopuffer::Models::NamespaceExplainQueryParams::Consistency) —

    Body param: The consistency level for a query.

  • distance_metric (Symbol, Turbopuffer::Models::DistanceMetric) —

    Body param: A function used to calculate vector similarity.

  • exclude_attributes (Array<String>) —

    Body param: List of attribute names to exclude from the response. All other attr

  • filters (Object) —

    Body param: Exact filters for attributes to refine search results for. Think of

  • group_by (Array<Object>) —

    Body param: Groups documents by the specified attributes (the "group key") befor

  • include_attributes (Boolean, Array<String>) —

    Body param: Whether to include attributes in the response.

  • limit (Integer, Turbopuffer::Models::Limit) —

    Body param: Limits the documents returned by a query.

  • rank_by (Object) —

    Body param: How to rank the documents in the namespace.

  • top_k (Integer) —

    Body param: The number of results to return.

  • vector_encoding (Symbol, Turbopuffer::Models::VectorEncoding) —

    Body param: The encoding to use for vectors in the response.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



134
135
136
137
138
139
140
141
142
143
144
145
146
147
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 134

def explain_query(params = {})
  parsed, options = Turbopuffer::NamespaceExplainQueryParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s/explain_query", namespace],
    body: parsed,
    model: Turbopuffer::Models::NamespaceExplainQueryResponse,
    options: options
  )
end

#hint_cache_warm(namespace: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceHintCacheWarmResponse

Signal turbopuffer to prepare for low-latency requests.

Parameters:

Returns:

See Also:



160
161
162
163
164
165
166
167
168
169
170
171
172
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 160

def hint_cache_warm(params = {})
  parsed, options = Turbopuffer::NamespaceHintCacheWarmParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :get,
    path: ["v1/namespaces/%1$s/hint_cache_warm", namespace],
    model: Turbopuffer::Models::NamespaceHintCacheWarmResponse,
    options: options
  )
end

#metadata(namespace: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceMetadata

Get metadata about a namespace.

Parameters:

Returns:

See Also:



185
186
187
188
189
190
191
192
193
194
195
196
197
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 185

def metadata(params = {})
  parsed, options = Turbopuffer::NamespaceMetadataParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :get,
    path: ["v2/namespaces/%1$s/metadata", namespace],
    model: Turbopuffer::NamespaceMetadata,
    options: options
  )
end

#multi_query(queries:, namespace: nil, consistency: nil, rerank_by: nil, vector_encoding: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceMultiQueryResponse

Some parameter documentations has been truncated, see Models::NamespaceMultiQueryParams for more details.

Issue multiple concurrent queries filter or search documents.

Parameters:

Returns:

See Also:



221
222
223
224
225
226
227
228
229
230
231
232
233
234
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 221

def multi_query(params)
  parsed, options = Turbopuffer::NamespaceMultiQueryParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s/query?stainless_overload=multiQuery", namespace],
    body: parsed,
    model: Turbopuffer::Models::NamespaceMultiQueryResponse,
    options: options
  )
end

#query(namespace: nil, aggregate_by: nil, compute_attributes: nil, consistency: nil, distance_metric: nil, exclude_attributes: nil, filters: nil, group_by: nil, include_attributes: nil, limit: nil, rank_by: nil, top_k: nil, vector_encoding: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceQueryResponse

Some parameter documentations has been truncated, see Models::NamespaceQueryParams for more details.

Query, filter, full-text search and vector search documents.

Parameters:

  • namespace (String) —

    Path param: The name of the namespace.

  • aggregate_by (Hash{Symbol=>Object}) —

    Body param: Aggregations to compute over all documents in the namespace that mat

  • compute_attributes (Hash{Symbol=>Object}) —

    Body param: Computes additional values on documents returned by a query. Each ke

  • consistency (Turbopuffer::Models::NamespaceQueryParams::Consistency) —

    Body param: The consistency level for a query.

  • distance_metric (Symbol, Turbopuffer::Models::DistanceMetric) —

    Body param: A function used to calculate vector similarity.

  • exclude_attributes (Array<String>) —

    Body param: List of attribute names to exclude from the response. All other attr

  • filters (Object) —

    Body param: Exact filters for attributes to refine search results for. Think of

  • group_by (Array<Object>) —

    Body param: Groups documents by the specified attributes (the "group key") befor

  • include_attributes (Boolean, Array<String>) —

    Body param: Whether to include attributes in the response.

  • limit (Integer, Turbopuffer::Models::Limit) —

    Body param: Limits the documents returned by a query.

  • rank_by (Object) —

    Body param: How to rank the documents in the namespace.

  • top_k (Integer) —

    Body param: The number of results to return.

  • vector_encoding (Symbol, Turbopuffer::Models::VectorEncoding) —

    Body param: The encoding to use for vectors in the response.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



274
275
276
277
278
279
280
281
282
283
284
285
286
287
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 274

def query(params = {})
  parsed, options = Turbopuffer::NamespaceQueryParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s/query", namespace],
    body: parsed,
    model: Turbopuffer::Models::NamespaceQueryResponse,
    options: options
  )
end

#recall(namespace: nil, filters: nil, include_ground_truth: nil, num: nil, rank_by: nil, top_k: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceRecallResponse

Some parameter documentations has been truncated, see Models::NamespaceRecallParams for more details.

Evaluate recall.

Parameters:

  • namespace (String) —

    Path param: The name of the namespace.

  • filters (Object) —

    Body param: Filter by attributes. Same syntax as the query endpoint.

  • include_ground_truth (Boolean) —

    Body param: Include ground truth data (query vectors and true nearest neighbors)

  • num (Integer) —

    Body param: The number of searches to run.

  • rank_by (Object) —

    Body param: The ranking function to evaluate recall for. If provided, num must

  • top_k (Integer) —

    Body param: Search for top_k nearest neighbors.

  • request_options (Turbopuffer::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



313
314
315
316
317
318
319
320
321
322
323
324
325
326
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 313

def recall(params = {})
  parsed, options = Turbopuffer::NamespaceRecallParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v1/namespaces/%1$s/_debug/recall", namespace],
    body: parsed,
    model: Turbopuffer::Models::NamespaceRecallResponse,
    options: options
  )
end

#schema(namespace: nil, request_options: {}) ⇒ Hash{Symbol=>Turbopuffer::Models::AttributeSchemaConfig}

Get namespace schema.

Parameters:

Returns:

See Also:



339
340
341
342
343
344
345
346
347
348
349
350
351
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 339

def schema(params = {})
  parsed, options = Turbopuffer::NamespaceSchemaParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :get,
    path: ["v1/namespaces/%1$s/schema", namespace],
    model: Turbopuffer::Internal::Type::HashOf[Turbopuffer::AttributeSchemaConfig],
    options: options
  )
end

#update_metadata(namespace: nil, pinning: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceMetadata

Some parameter documentations has been truncated, see Models::NamespaceUpdateMetadataParams for more details.

Update metadata configuration for a namespace.

Parameters:

Returns:

See Also:



369
370
371
372
373
374
375
376
377
378
379
380
381
382
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 369

def update_metadata(params = {})
  parsed, options = Turbopuffer::NamespaceUpdateMetadataParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :patch,
    path: ["v1/namespaces/%1$s/metadata", namespace],
    body: parsed,
    model: Turbopuffer::NamespaceMetadata,
    options: options
  )
end

#update_schema(namespace: nil, schema: nil, request_options: {}) ⇒ Hash{Symbol=>Turbopuffer::Models::AttributeSchemaConfig}

Update namespace schema.

Parameters:

Returns:

See Also:



397
398
399
400
401
402
403
404
405
406
407
408
409
410
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 397

def update_schema(params = {})
  parsed, options = Turbopuffer::NamespaceUpdateSchemaParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v1/namespaces/%1$s/schema", namespace],
    body: parsed[:schema],
    model: Turbopuffer::Internal::Type::HashOf[Turbopuffer::AttributeSchemaConfig],
    options: options
  )
end

#write(namespace: nil, branch_from_namespace: nil, copy_from_namespace: nil, delete_by_filter: nil, delete_by_filter_allow_partial: nil, delete_condition: nil, deletes: nil, disable_backpressure: nil, distance_metric: nil, encryption: nil, patch_by_filter: nil, patch_by_filter_allow_partial: nil, patch_columns: nil, patch_condition: nil, patch_rows: nil, return_affected_ids: nil, schema: nil, sharding: nil, upsert_columns: nil, upsert_condition: nil, upsert_rows: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceWriteResponse

Some parameter documentations has been truncated, see Models::NamespaceWriteParams for more details.

Create, update, or delete documents.

Parameters:

Returns:

See Also:



466
467
468
469
470
471
472
473
474
475
476
477
478
479
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 466

def write(params = {})
  parsed, options = Turbopuffer::NamespaceWriteParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :post,
    path: ["v2/namespaces/%1$s", namespace],
    body: parsed,
    model: Turbopuffer::Models::NamespaceWriteResponse,
    options: {max_retries: 6, **options}
  )
end