Class: Turbopuffer::Resources::Namespaces

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

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:



471
472
473
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 471

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

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



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

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:



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

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, 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

  • 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<String>) —

    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:



130
131
132
133
134
135
136
137
138
139
140
141
142
143
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 130

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:



156
157
158
159
160
161
162
163
164
165
166
167
168
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 156

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:



181
182
183
184
185
186
187
188
189
190
191
192
193
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 181

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, vector_encoding: nil, request_options: {}) ⇒ Turbopuffer::Models::NamespaceMultiQueryResponse

Issue multiple concurrent queries filter or search documents.

Parameters:

Returns:

See Also:



212
213
214
215
216
217
218
219
220
221
222
223
224
225
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 212

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, 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

  • 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<String>) —

    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:



263
264
265
266
267
268
269
270
271
272
273
274
275
276
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 263

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:



302
303
304
305
306
307
308
309
310
311
312
313
314
315
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 302

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:



328
329
330
331
332
333
334
335
336
337
338
339
340
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 328

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:



358
359
360
361
362
363
364
365
366
367
368
369
370
371
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 358

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: ["v2/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:



386
387
388
389
390
391
392
393
394
395
396
397
398
399
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 386

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



453
454
455
456
457
458
459
460
461
462
463
464
465
466
 
# File 'lib/turbopuffer/resources/namespaces.rb', line 453

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