Tables¶

The tables resource manages table schemas within namespaces.

Methods¶

Method	Description
`list(namespace_id, limit, offset)`	List tables in a namespace
`get_metadata(table_id)`	Get table schema, metadata, and ETag
`get_etag(table_id)`	Fetch only the current ETag (HEAD, no body)
`create(table_id, columns, sort_by, partition_by, ...)`	Create a table
`update_metadata(table_id, etag?, ...)`	Update title, description, tags, sources
`update_schema(table_id, columns, etag?)`	Replace the column schema
`delete(table_id)`	Delete a table and all its data

Creating a table¶

Tables live within namespaces, so you need an existing namespace before creating a table.

    client.namespaces.create(
        namespace_id='raw.table_namespace'
    )

    table, etag = client.tables.create(
        table_id='raw.table_namespace.my_table',
        columns=[
            {'name': 'col_str', 'data_type': 'string', 'required': True},
            {'name': 'col_float', 'data_type': 'float32'}
        ]
    )
    print(f'Created table: {table.id}')

Listing tables¶

    response = client.tables.list(namespace_id='raw.table_namespace')

    for table in response.items:
        print(table.id)

Fetching only the ETag¶

get_etag() issues a HEAD request and returns the ETag without fetching the full table metadata:

etag = client.tables.get_etag('raw.events.log')

Updating metadata¶

The etag parameter is optional — when omitted it is fetched automatically:

    table, etag = client.tables.get_metadata(
        table_id='raw.table_namespace.my_table'
        )

    updated_table, etag = client.tables.update_metadata(
        table_id='raw.table_namespace.my_table',
        etag=etag,
        title='My table'
    )

    print(f'Updated: {updated_table.metadata.title}')

Updating the schema¶

    updated_table, _ = client.tables.update_schema(
        table_id='raw.table_namespace.my_table',
        etag=etag,
        columns=[
            {'name': 'col_str', 'data_type': 'string', 'required': True},
            {'name': 'col_float', 'data_type': 'float32'},
            {'name': 'new_col_int', 'data_type': 'int32'},
        ]
    )

    print(f'new schema: {updated_table.columns}')

Warning

update_schema() is destructive. Any column present in the current schema but absent from the new schema will be permanently dropped along with its data.

Deleting a table¶

    client.tables.delete('raw.table_namespace.my_table')

Data lineage¶

Both create() and update_metadata() accept optional lineage fields:

sources — list of source table IDs (dot-separated) this table derives from, e.g. ['raw.orders', 'raw.customers']. The server stores them as split path arrays.
external_sources — list of ExternalSource objects (or plain dicts) describing external data references. Each has name (str), url (str), and optional license (str).

    table, etag = client.tables.create(
    'raw.table_namespace.my_super_table',
    columns=[
            {'name': 'col_str', 'data_type': 'string', 'required': True},
            {'name': 'col_float', 'data_type': 'float32'},
            {'name': 'new_col_int', 'data_type': 'int32'},
        ],
    sources=['raw.orders', 'raw.customers'],
    external_sources=[
        {'name': 'Open Data Portal', 'url': 'https://data.gov/dataset'}
    ],
)

Supported data types¶

Type	Description
`'boolean'`	True / False
`'string'`	UTF-8 text
`'categorical'`	Low-cardinality enumerated string
`'int32'`, `'int64'`	Integer
`'float32'`, `'float64'`	Floating-point
`'decimal'`	High-precision decimal
`'date'`	Calendar date
`'datetime'`	Date and time
`'time'`	Time of day
`'unknown'`	Untyped / deferred