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:



560
561
562
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 560

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, offset: 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.

  • offset (Integer) —

    Body param: Number of documents to skip before returning results. Supported only

  • 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:



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

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:



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

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:



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

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, limit: nil, offset: 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:



227
228
229
230
231
232
233
234
235
236
237
238
239
240
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 227

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

#poll_copy_from(token, namespace: nil, request_options: {}) ⇒ Turbopuffer::Models::CopyFromNamespaceOperation::Running, Turbopuffer::Models::CopyFromNamespaceOperation::Finished

Retrieve the current status of a copy operation.

Parameters:

  • token (String) —

    The operation token obtained when starting the copy.

  • namespace (String) —

    The name of the namespace.

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

Returns:

See Also:



255
256
257
258
259
260
261
262
263
264
265
266
267
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 255

def poll_copy_from(token, params = {})
  parsed, options = Turbopuffer::NamespacePollCopyFromParams.dump_request(params)
  namespace =
    parsed.delete(:namespace) do
      @client.default_namespace
    end
  @client.request(
    method: :get,
    path: ["v1/namespaces/%1$s/operations/%2$s?stainless_overload=pollCopyFrom", namespace, token],
    model: Turbopuffer::CopyFromNamespaceOperation,
    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, offset: 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.

  • offset (Integer) —

    Body param: Number of documents to skip before returning results. Supported only

  • 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:



309
310
311
312
313
314
315
316
317
318
319
320
321
322
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 309

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:



348
349
350
351
352
353
354
355
356
357
358
359
360
361
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 348

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:



374
375
376
377
378
379
380
381
382
383
384
385
386
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 374

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

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

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

Start copying all documents from another namespace into this one. Returns an operation token without waiting for the copy to finish. Use the token to poll for progress and the result.

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:



412
413
414
415
416
417
418
419
420
421
422
423
424
425
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 412

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

#update_metadata(namespace: nil, pinning: nil, read_only: 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:

  • namespace (String) —

    Path param: The name of the namespace.

  • pinning (Boolean, Turbopuffer::Models::PinningConfig, nil) —

    Body param: Configuration for namespace pinning.

  • read_only (Boolean) —

    Body param: Set to true to reject document and schema writes, or false to al

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

Returns:

See Also:



445
446
447
448
449
450
451
452
453
454
455
456
457
458
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 445

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:



473
474
475
476
477
478
479
480
481
482
483
484
485
486
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 473

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:



542
543
544
545
546
547
548
549
550
551
552
553
554
555
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 542

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