View Metadata

GET/v1/namespaces/:namespace/metadata

Returns metadata about a namespace.

Response

schema
object

See the schema documentation.

approx_logical_bytes
integer

The approximate number of logical bytes in the namespace.

This is a coarse approximation and may change over time as turbopuffer's data representation evolves.

When using disable_backpressure, this metric will not be updated until all data has been indexed.

approx_row_count
integer

The approximate number of rows in the namespace.

When using disable_backpressure, this metric will not be updated until all data has been indexed.

created_at
string

The timestamp when the namespace was created, in ISO 8601 format.

Example: "2024-03-15T10:30:45Z"

last_write_at
string

The timestamp when the namespace's data was last modified, in ISO 8601 format.

Example: "2024-03-19T09:12:14Z"

updated_at
string

The timestamp when the namespace when the namespace's data or schema was last modified, in ISO 8601 format.

Example: "2024-04-16T09:27:32Z"

encryption
object

Describes how the namespace is encrypted.

Possible values include default server-side encryption and CMEK.

{
  "mode": "default"
}
index
object

The state of the index for the namespace. Contains the following fields:

  • status (string): updating or up-to-date

  • unindexed_bytes (integer):

    The number of bytes in the namespace that are in the write-ahead log but have not yet been indexed. Note that unindexed data is still searched by queries (see consistency for details).

    Only present when status is updating.

pinning
object

Namespace pinning provisions reserved compute for a namespace to provide predictable cost and performance for large namespaces with sustained query volume, with always-warm cache.

Only present when the namespace is pinned.

Contains the following fields:

  • replicas (integer): The number of read replicas configured for the namespace. Each replica increases read throughput.

  • status (object): Operational status for the pinned namespace. When available, includes the number of ready_replicas that are warm and able to serve traffic, along with the average utilization of all ready replicas.

    When utilization exceeds 90%, consider increasing replica count.

Example:

{
  "replicas": 2,
  "status": {
    "ready_replicas": 1,
    "utilization": 0.73
  }
}
branching
object

The state of branching for the namespace. Only present for branched namespaces. Contains the following fields:

  • parent (string): The namespace this was branched from.
branching
object

The state of branching for the namespace. Only present for branched namespaces. Contains the following fields:

  • parent (string): The namespace this was branched from.

Example

import turbopuffer

tpuf = turbopuffer.Turbopuffer(
    region="gcp-us-central1", # choose best region: https://turbopuffer.com/docs/regions
)

ns = tpuf.namespace(f"metadata-inspect-example-py")

metadata = ns.metadata()
print(metadata)  # returns a turbopuffer.NamespaceMetadata object

Billing

This request is billed as a query that returns zero rows.

Change Metadata

PATCH/v1/namespaces/:namespace/metadata

Updates metadata configuration for a namespace.

Updates the configuration for a namespace.

Currently used to configure namespace pinning.

Request

pinning
object

Configuration for namespace pinning, which provisions reserved compute for a namespace to provide predictable cost and performance for large namespaces with sustained query volume, with always-warm cache.

Set to null to remove pinning from a namespace.

Contains the following fields:

  • replicas (integer, optional): The number of read replicas to provision. Defaults to 1. Each replica runs on its own reserved node, increases read throughput, and multiplies pinning cost.
{
  "pinning": {
    "replicas": 2
  }
}

Response

Returns the updated namespace metadata. See View Metadata response fields for details.

Billing

This request is billed as a query that returns zero rows.