Manage namespaces & tables¶

This guide walks through creating and managing namespaces and table schemas.

1. Create a namespace¶

Namespaces organize tables into logical groups:

    namespace, etag = client.namespaces.create(
        namespace_id='raw.observatorio',
        title='Observatorio Data',
        description='Raw observational data',
        tags=['raw', 'observations'],
    )
    print(f'Created namespace: {namespace.id}')

2. Define table schema¶

Define a table with columns and optional sorting/partitioning:

    schema = [
        ColumnSchema(name='id', data_type='int64'),
        ColumnSchema(name='name', data_type='string'),
        ColumnSchema(name='recorded_at', data_type='datetime'),
        ColumnSchema(name='active', data_type='boolean'),
    ]

    table, etag = client.tables.create(
        table_id='raw.observatorio.records',
        columns=schema,
        sort_by=[ColumnSorting(name='recorded_at')],
        partition_by=[ColumnPartitioning(name='recorded_at')],
        title='Observation Records',
        description='Raw field observations',
        tags=['observations'],
    )
    print(f'Created table: {table.id}')

3. List tables in a namespace¶

    response = client.tables.list(namespace_id='raw.observatorio')
    print(f'Found {len(response.items)} tables:')
    for t in response.items:
        print(f'  {t.id}')

4. Update table metadata¶

Change title, description, or tags without modifying the schema:

    table, etag = client.tables.get_metadata(
        table_id='raw.observatorio.records'
    )
    updated_table, new_etag = client.tables.update_metadata(
        table_id='raw.observatorio.records',
        etag=etag,
        title='Field Observations',
        description='Updated description',
        tags=['observations', 'field'],
    )
    print(f'Updated: {updated_table.metadata.title}')

5. Update table schema¶

Add new columns or modify existing ones:

    table, etag = client.tables.get_metadata(
        table_id='raw.observatorio.records'
    )
    new_schema = [
        ColumnSchema(name='id', data_type='int64'),
        ColumnSchema(name='name', data_type='string'),
        ColumnSchema(name='recorded_at', data_type='datetime'),
        ColumnSchema(name='active', data_type='boolean'),
        ColumnSchema(name='notes', data_type='string'),
    ]
    updated_table, new_etag = client.tables.update_schema(
        table_id='raw.observatorio.records',
        etag=etag,
        columns=new_schema,
    )
    print('Schema updated')

Warning

update_schema() is destructive. If you remove a column from the schema, it will be permanently deleted along with all its data.

6. Delete table¶

    client.tables.delete(table_id='raw.observatorio.records')
    print('Table deleted')

7. Delete namespace¶

A namespace can only be deleted if it's empty:

    response = client.tables.list(namespace_id='raw.observatorio')
    for t in response.items:
        client.tables.delete(table_id=t.id)

    client.namespaces.delete(namespace_id='raw.observatorio')
    print('Namespace deleted')

If you try to delete a non-empty namespace, you'll get a ConflictError:

    client.tables.create(
        table_id='raw.observatorio.temp',
        columns=[ColumnSchema(name='id', data_type='int64')],
    )
    try:
        client.namespaces.delete(namespace_id='raw.observatorio')
    except ConflictError:
        print('Namespace is not empty')

Complete workflow example¶

    namespace, _ = client.namespaces.create(
        namespace_id='raw.weather',
        title='Weather',
    )
    table, etag = client.tables.create(
        table_id='raw.weather.stations',
        columns=[
            {'name': 'station_id', 'data_type': 'int64'},
            {'name': 'city', 'data_type': 'string'},
        ],
        title='Weather stations',
    )
    print(f'Created {table.id}')

    client.tables.delete(table_id='raw.weather.stations')
    client.namespaces.delete(namespace_id='raw.weather')
    print('Cleaned up')