Namespaces¶

Namespaces organize tables into isolated logical groups. The three root namespaces are raw, processed, and analytics — all namespaces are scoped under one of them: <root>.<namespace>.

Methods¶

Method	Description
`list(namespace_id?, limit, offset)`	List namespaces; omit `namespace_id` for root listing
`get_metadata(namespace_id)`	Get namespace metadata and ETag
`get_etag(namespace_id)`	Fetch only the current ETag (HEAD, no body)
`create(namespace_id, title, description, tags)`	Create a namespace
`update(namespace_id, etag?, title, description, tags)`	Update namespace metadata
`delete(namespace_id)`	Delete a namespace

Creating a namespace¶

    namespace, etag = client.namespaces.create(
        namespace_id='raw.my_namespace',
        title='My Namespace',
        description='A namespace for testing',
        tags=['test', 'example'],
        )

The method returns a tuple of (NamespaceResponse, etag_string).

Listing namespaces¶

List child namespaces under a parent, or omit namespace_id to list all root-level namespaces:

    response = client.namespaces.list(
        namespace_id='raw'
    )
    for ns in response.items:
        print(f'{ns.id}')

# All root namespaces (raw, processed, analytics, …)
response = client.namespaces.list()

Fetching only the ETag¶

get_etag() issues a HEAD request and returns the ETag string without transferring the namespace body. Useful when you need a fresh ETag before an update but don't need the metadata:

etag = client.namespaces.get_etag('raw.my_namespace')

Updating a namespace¶

    ns, etag = client.namespaces.get_metadata('raw.my_namespace')
    client.namespaces.update(
        namespace_id='raw.my_namespace',
        etag=etag,
        title='New title',
        description='Update description'
    )

When you don't have the ETag at hand you can omit it — the current ETag is fetched automatically via a HEAD request before the write:

# etag auto-fetched
client.namespaces.update('raw.my_namespace', title='New title')

Note

Pass an explicit ETag when you already have it (e.g. from a previous create or get_metadata call) to avoid the extra HEAD round-trip and to detect concurrent edits. If you receive a PreconditionFailedError, fetch the current ETag and retry.

Warning

update() is a PUT — it replaces ALL metadata fields. Omitted fields are reset to their defaults rather than left unchanged. Pass every field you want to keep.

Deleting a namespace¶

    client.namespaces.delete('raw.my_namespace')

Warning

A namespace can only be deleted if it contains no tables. Delete all tables in the namespace first. If you attempt to delete a non-empty namespace you receive a ConflictError.

Response formats¶

The list() method supports a prefer parameter controlling response verbosity, with the grammar model=namespace; format=minimal|summary|full:

    # Minimal response (just ID) — default
    response = client.namespaces.list(
        namespace_id='raw',
        prefer='model=namespace; format=minimal',
    )

    # Summary response (ID and metadata)
    response = client.namespaces.list(
        namespace_id='raw',
        prefer='model=namespace; format=summary',
    )

summary returns id plus metadata; minimal returns id only. As of the current server version, full on the list endpoint returns the same payload as minimal.