Namespaces

A namespace in bauplan is a logical container that helps organize tables within a data catalog. Namespaces provide a way to group related tables together.

bauplan namespaces enable organization of data assets in a hierarchical structure, similar to how directories organize files in a filesystem. By default, all tables are created in the ‘bauplan’ namespace if no namespace is provided.

Creating Namespaces

Namespaces can be created using either the Python SDK or CLI. When creating a namespace, you must specify both the namespace name and the branch where it should be created.

Using the Python SDK:

import bauplan

client = bauplan.Client()

# Create a new namespace
namespace = client.create_namespace(
    namespace='marketing_data',
    branch='my_new_branch'
)

Using the CLI:

bauplan branch checkout <YOUR_USERNAME>.<BRANCH_NAME>
bauplan namespace create marketing_data

Default Namespace

  • If not specified, tables are created in the ‘bauplan’ namespace

Using Namespaces with Tables

When working with tables, you can specify the namespace in line using dot notation. If you do not specify a namespace for the table, the system will take the default one or whatever you supplied as a parameter when running the pipeline.

# Create a table in a specific namespace
@bauplan.model(materialization_strategy='REPLACE')
@bauplan.python('3.11')
def create_marketing_metrics(
    data=bauplan.Model('marketing_data.raw_events')
):
    ...

Using the CLI:

# List all tables in a namespace
bauplan table --namespace marketing_data

# Run a DAG with tables in a namespace (if they do not have a namespace
# specified already in the code)
bauplan run --namespace marketing_data

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

# This is the equivalent with a parameter instead
bauplan query --namespace marketing_data "SELECT * FROM raw_events"

Best Practices

Organization

  • Use meaningful names that reflect the data domain

  • Group related tables within the same namespace

Naming Conventions

  • Establish consistent naming patterns across your organization

  • Use prefixes to indicate data environment or status

  • Document naming standards in your team’s guidelines