Write-Audit-Publish (WAP) Pattern

Implement WAP by writing a Python script using the

bauplan

The three steps: Write (ingest to temp branch) → Audit (quality checks) → Publish (merge to main)

Branch safety: All operations happen on a temporary branch, NEVER on

main

Atomic multi-table operations:

merge_branch

Required User Input

Before writing the WAP script, you MUST ask the user for the following parameters:

1. S3 path (required): The S3 URI pattern for the source data (e.g.,

   s3://bucket/path/*.parquet

   )
2. Table name (required): The name for the target table
3. On success behavior (optional):

   • inspect

     (default): Keep the branch open for user inspection before merging

   • merge

     : Automatically merge to main and delete the branch
4. On failure behavior (optional):

   • keep

     (default): Leave the branch open for inspection/debugging

   • delete

     : Delete the failed branch

WAP Script Template

See wap_template.py for the complete template. Minimal usage:

from wap_template import wap_ingest

branch, success = wap_ingest(
    table_name="orders",
    s3_path="s3://my-bucket/data/*.parquet",
    namespace="bauplan",
    on_success="inspect",  # or "merge"
    on_failure="keep"      # or "delete"
)

Key SDK Methods

bauplan.Client()

client.info()

.user.username

client.create_branch(name, from_ref="main")

client.has_branch(name)

client.delete_branch(name)

client.create_table(table, search_uri, ...)

client.import_data(table, search_uri, ...)

client.query(query, ref)

client.merge_branch(source_ref, into_branch)

client.has_table(table, ref, namespace)

SDK Reference: For detailed method signatures, check https://docs.bauplanlabs.com/reference/bauplan

Workflow Checklist

Copy and track progress:

WAP Progress:
- [ ] Ask user for: S3 path, table name, on_success, on_failure
- [ ] Write script using wap_template.py
- [ ] Run script: python wap_script.py
- [ ] Verify output shows row count > 0
- [ ] If on_success="inspect": confirm branch ready for review
- [ ] If on_success="merge": confirm merge to main succeeded

Example Output

Successful run (on_success="inspect"):

$ python wap_script.py
Imported 15234 rows
WAP completed successfully. Branch 'alice.wap_orders_1704067200' ready for inspection.
To merge manually: client.merge_branch(source_ref='alice.wap_orders_1704067200', into_branch='main')

Successful run (on_success="merge"):

$ python wap_script.py
Imported 15234 rows
Successfully published orders to main
Cleaned up branch: alice.wap_orders_1704067200

Failed run (on_failure="keep"):

$ python wap_script.py
WAP failed: No data was imported
Branch 'alice.wap_orders_1704067200' preserved for inspection/debugging.

WAP on Existing Tables

To append data to an existing table, skip

create_table

import_data

# Table already exists on main - just import new data
client.import_data(
    table=table_name,
    search_uri=s3_path,
    namespace=namespace,
    branch=branch_name
)

This appends rows to the existing table schema. The audit and publish phases remain the same: the new rows are automatically sandboxed on the branch until merged.

CLI Merge After Inspection

When

on_success="inspect"

# 1. Checkout to main first (required before merging)
bauplan checkout main

# 2. Merge the WAP branch into main
bauplan branch merge <username>.wap_<table_name>_<timestamp>

# 3. Optionally delete the branch after successful merge
bauplan branch rm <username>.wap_<table_name>_<timestamp>

Note: You must be on

main

to run

bauplan branch merge

. The branch name is printed by the WAP script upon completion.