Namespaces

A namespace in Bauplan is a logical container that groups related tables, similar to schemas in a relational database or folders in a filesystem.

By default, tables are created in the bauplan namespace. You can override this per table, per project, or per run.

Namespaces are useful for:

  • Organizing tables by team, project, or domain (e.g. ml.features, analytics.events)

  • Preventing name collisions across teams

  • Isolating environments (e.g. dev/test/prod)

Using namespaces

You can create a namespace using either the Python SDK or the CLI.

Python:

import bauplan

client = bauplan.Client()
client.create_namespace(
    namespace='marketing_data',
    branch='ciro.feature_campaign_v2'
)

CLI:

bauplan branch checkout ciro.feature_campaign_v2
bauplan namespace create marketing_data

You can reference a table in a namespace either using dot notation:

# Query with fully qualified table name
bauplan query "SELECT * FROM marketing_data.raw_events"

or passing the namespace to the query API as a parameter:

bauplan query "SELECT * FROM raw_events" --namespace marketing_data