Retrieve a list of all data tables in a specified branch or reference of the user's Bauplan data catalog using a ref name.

Args: ref: a reference to a commit that is a state of the user data lake: can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. namespace: Optional namespace to use.

IMPORTANT: Always use this tool BEFORE generating code with generate_code to ensure you're referencing tables that actually exist.

Returns: TablesOut: object with list of table names

Retrieve schemas of all data tables in a specified branch or reference of the user's Bauplan data catalog as a list, using a branch name.

Args: ref: a reference to a commit that is a state of the user data lake: can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. namespace: Optional namespace table filter to use.

Returns: SchemasOut: Schema object with table fields

Retrieve the schema of a specified data table in the user's Bauplan data catalog using a table name, returning a schema object.

Args: ref: a reference to a commit that is a state of the user data lake: can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. table_name: Name of the specific table to get schema for. namespace: Optional namespace to use (defaults to "bauplan").

Returns: TableOut: Schema object with table fields for the specified table

Execute a SQL SELECT query on the user's Bauplan data catalog, returning results as a QueryOut object using a query, optional ref, and optional namespace. Executes a SQL query against the user's Bauplan data lake.

Args: query: SQL query to execute ref: a reference to a commit that is a state of the user data lake: can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. namespace: Optional namespace to use.

Returns: QueryOut: Response object with query results or error

Execute SQL SELECT queries on a specified table in the user's Bauplan data catalog, saving results to a CSV file, using a query and table name, returning a file path. Execute SELECT queries and save results directly to CSV file.

Note: CSV format only supports scalar data types (strings, numbers, booleans). Queries returning complex types (arrays, lists, nested objects) will fail. For complex data, use run_query tool instead or modify SQL to flatten/convert data.

Args: path: Output CSV file path where results will be saved. query: SQL query to execute (DuckDB SQL syntax). ref: Branch/reference to query against (optional). namespace: Namespace to use (optional). client_timeout: Timeout in seconds (defaults to 120).

Returns: QueryToCSVResult: Object indicating success/failure with execution details

Retrieve branches from the user's Bauplan data catalog as a list, with optional user and limit (integer) filters to reduce response size. Get branches from the Bauplan catalog with optional filtering. NOTE: This can return a large response. Always use limit parameter.

Args: name: Optional filter to get branches by name (substring match) user: Optional filter to get branches by user limit: Maximum number of branches to return (needs to be an integer, default 10)

Returns: BranchesOut: Object containing list of branches with their names and hashes

Retrieve commit history for a specified branch in the user's Bauplan data catalog as a list, with optional filters including date range (ISO format: YYYY-MM-DD) and limit (integer). Retrieve commit history from a Bauplan branch.

Args: ref: branch or commit hash to get commits from. Can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. message_filter: Optional filter for commit messages (substring match) author_username: Optional filter by author's username author_email: Optional filter by author's email date_start: Optional start date for filtering (ISO format: YYYY-MM-DD) date_end: Optional end date for filtering (ISO format: YYYY-MM-DD) limit: Maximum number of commits to return (default: 10)

Returns: CommitsOut: Object containing list of commits and total count

Retrieve namespaces for a branch from the user's Bauplan data catalog as a list. Use 'limit' (integer) to reduce response size. Get the namespaces of a branch using optional filters.

Args: ref: branch or commit hash to get namespaces from. Can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format. namespace: Optional filter for namespace names (substring match) limit: Optional maximum number of namespaces to return (default: 10)

Returns: NamespacesOut: Object containing list of namespaces and total count

Create a new branch in the user's Bauplan data catalog using a branch name, returning a confirmation.

Args: branch: Name of the new branch to create. Must follow the format <username.branch_name>. from_ref: Reference (branch/commit) to create the branch from. Can be either a branch name or a hash that starts with "@" and has 64 additional characters.

Returns: BranchCreated: Object indicating success/failure with branch details

Check if a specified branch exists in the user's Bauplan data catalog using a branch name. Check if a specific branch exists in the Bauplan catalog.

Args: branch: Name of the branch to check for existence.

Returns: BranchExists: Object indicating whether the branch exists with details

Create a new namespace in a specified branch of the user's Bauplan data catalog using a namespace name.

Args: namespace: Name of the namespace to create. branch: Branch name where the namespace will be created. Must follow the format <username.branch_name>.

Returns: NamespaceCreated: Object indicating success/failure with namespace details

Check if a specified namespace exists in a given branch of the user's Bauplan data catalog using a namespace name and branch name.

Args: namespace: Name of the namespace to check for existence. ref: The ref, branch name or tag name to check the namespace on.

Returns: NamespaceExists: Object indicating whether the namespace exists with details

Create an empty table from an S3 URI identifying parquet, csv or JSONL files in S3. The table schema is automatically inferred from the files at the given search uri.

Args: table: Name of the table to create. search_uri: S3 URI to search for parquet files. branch: branch name. namespace: Optional namespace (defaults to "bauplan"). partitioned_by: Optional partitioning column. replace: Optional flag to replace existing table.

Returns: TableCreated: Object indicating success/failure with table details.

NOTE: This tool creates a ICEBERG table with the schema of the file(s) in the URI but it does not populate the table.

Generate a YAML schema plan for importing a table from an S3 URI in the user's Bauplan data catalog returning a job ID for tracking). Create a table import plan from an S3 location.

This operation will attempt to create a table based of schemas of N parquet files found by a given search uri. A YAML file containing the schema and plan is returned and if there are no conflicts, it is automatically applied.

Args: table: Name of the table to plan creation for. search_uri: S3 URI to search for parquet files. namespace: Optional namespace (defaults to "bauplan"). branch: Optional branch name. partitioned_by: Optional partitioning column. replace: Optional flag to replace existing table.

Returns: TablePlanCreated: Object indicating success/failure with job tracking details

Apply a provided table creation plan to resolve schema conflicts and create a new table in the system. Returns a job_id for tracking the asynchronous operation.

This function is used when schema conflicts exist after plan creation and need manual resolution. Most common schema conflict is two parquet files with the same column name but different datatype. Note: This is done automatically during table plan creation if no schema conflicts exist.

Args: plan: The plan dictionary or TableCreatePlanState to apply. debug: Whether to enable or disable debug mode (optional). args: Additional arguments for plan application (optional). priority: Job priority, 1-10 where 10 is highest priority (optional). verbose: Whether to enable or disable verbose mode (optional). client_timeout: Timeout in seconds (defaults to 120).

Returns: TablePlanApplied: Object indicating success/failure with job tracking details

Check if a specified table exists in a given branch of the user's Bauplan data catalog using a table name and branch name.

Args: table: Name of the table to check for existence. ref: A reference to a commit that is a state of the user data lake: can be either a hash that starts with "@" and has 64 additional characters or a branch name, that is a mnemonic reference to the last commit that follows the "username.name" format.

Returns: TableExists: Object indicating whether the table exists with details

Delete a specified table from the user's Bauplan data catalog using a table name. Delete a table from the user's Bauplan data lake.

Args: table: Name of the table to delete. branch: Branch name where the table will be deleted. Must follow the format <username.branch_name>.

Returns: TableDeleted: Object indicating whether the table was deleted with details

Import data into a specified existing table using a table name and data source.

Args: table: Name of the table to import data into, it needs to exist beforehand. search_uri: URI to search for data files to import. branch: branch name. namespace: Optional namespace (defaults to "bauplan").

Returns: DataImported: Object indicating success/failure with job details

Revert a specified table from a source reference to a target branch in the user's Bauplan data catalog using a table name, source reference, and target branch. Revert a table from a source reference to a target branch.

Args: table: The table to revert. source_ref: The name of the source ref. into_branch: The name of the target branch where the table will be reverted. replace: Optional, whether to replace the table if it already exists.

Returns: TableReverted: Object indicating success/failure with revert details

Run a pipeline from a specified directory and data ref, returning a job ID and success/failure to the caller.

Args: project_dir: The directory of the project containing the source code files and bauplan_project.yml. ref: The ref or branch name from which to run the project. namespace: The Namespace to run the job in. If not set, the job will be run in the default namespace. parameters: Parameters for templating DAGs. Keys are parameter names, values must be simple types (str, int, float, bool). dry_run: Whether to enable or disable dry-run mode for the run; models are not materialized (defaults to False). client_timeout: Seconds to timeout (defaults to 120).

Returns: RunState: Object indicating success/failure with job Id

Run a pipeline from provided source code files as a dictionary and a data ref, returning a job ID and success/failure to the caller.

Args: project_files: Dictionary mapping file names to source code as strings. Must contain bauplan_project.yml and .sql/.py files. ref: The ref or branch name from which to run the project. parameters: Parameters for templating DAGs. Keys are parameter names, values must be simple types (str, int, float, bool). Default: None.

Returns: RunState: Object indicating success/failure with job Id.

Retrieve a list of jobs in Bauplan, optionally filter by job id, status (COMPLETE, FAIL, ABORT, RUNNING), user name, start and end time (UTC, format '%m/%d/%y %H:%M:%S').

Args: job_id: Optional filter by job ID status: Optional filter by job status, either COMPLETE, FAIL, ABORT or RUNNING user_name: Optional filter by user name start_time: Optional filter by job start time, UTC time, '%m/%d/%y %H:%M:%S', e.g. '09/19/22 13:55:26' end_time: Optional filter by job finish time, UTC time, '%m/%d/%y %H:%M:%S', e.g. '09/19/22 13:55:26'

Returns: JobsList: Object containing list of jobs with their details

Retrieve details of a job by job ID, such as user logs, code snapshot, project id. Get details of a specific job by its ID.

Human_readable_status in the response will be "Failed" for failed jobs, "Completed" for completed jobs.

Args: job_id: The ID of the job to retrieve.

Returns: JobInfo: Object containing job details id (str): The ID of the job. kind (str): The kind of job. user (str): The user who created the job. human_readable_status (str): Human-readable status of the job. created_at (Optional[str]): ISO formatted creation timestamp of the job. finished_at (Optional[str]): ISO formatted finish timestamp of the job. status (str): The status of the job. logs (Optional[str]): Concatenated user logs from the job. code_snapshot_path (Optional[Path]): Path to the code snapshot directory. ref (Optional[str]): The data commit reference when the job was run, i.e. the state of source tables for the job at that time. transactional_branch (Optional[str]): The transactional branch that was open when the job was run. project_yml (Optional[str]): The contents of the bauplan_project.yml file from the snapshot. project_files (Optional[dict[str, str]]): A dictionary of other project files from the snapshot, with filenames as keys and file contents as values.

Cancel a running job in the Bauplan system by its job_id and return the updated job status.

Args: job_id: The ID of the job to cancel.

Returns: JobInfo: Object containing updated job details after cancellation

Merge a source branch into a target branch in the user's Bauplan data catalog using source and target branch names. Branch names must follow the format <username.branch_name>.

Args: source_ref: The branch to merge from. The name must follow the format <username.branch_name>. into_branch: The target branch to merge into. The name must follow the format <username.branch_name>. commit_message: Optional custom commit message for the merge commit_body: Optional additional commit body/description

Returns: MergeResult: Object indicating success/failure with merge details

Delete a specified branch from the user's Bauplan data catalog using a branch name.

Args: branch: Name of the branch to delete. Must follow the format <username.branch_name>.

Returns: BranchDeleted: Object indicating success/failure of the deletion

Delete a specified namespace from a given branch in the user's Bauplan data catalog using a namespace name and branch name. Delete a namespace from a specific branch of the user's Bauplan catalog.

Args: namespace: Name of the namespace to delete. branch: Branch name containing the namespace to delete. Must follow the format <username.branch_name>.

Returns: NamespaceDeleted: Object indicating success/failure of the deletion

Retrieve tags from the user's Bauplan data catalog as a list, with optional filter_by_name and limit (integer) to reduce response size. Get the tags using optional filters.

Args: filter_by_name: Optional filter for tag names (substring match) limit: Optional maximum number of tags to return

Returns: TagsOut: Object containing list of tags and total count

Create a new tag in a specified branch of the user's Bauplan data catalog using a tag name. Create a new tag in a specific branch of the user's Bauplan catalog.

Args: tag: Name of the tag to create. from_ref: Reference (branch or commit) from which to create the tag.

Returns: TagCreated: Object indicating success/failure with tag details

Check if a specified tag exists in the user's Bauplan data catalog using a tag name.

Args: tag: Name of the tag to check for existence.

Returns: TagExists: Object indicating whether the tag exists with details

Delete a specified tag from the user's Bauplan data catalog using a tag name.

Args: tag: Name of the tag to delete.

Returns: TagDeleted: Object indicating success/failure of the deletion

Retrieve user information about the current authenticated Bauplan user. Get information about the current authenticated user.

Args:

Returns: UserInfo: Object containing username and full name of the authenticated user

Get detailed instructions for specific Bauplan use cases to be used to solve the task, possibly suggesting further tool usage.

Args: use_case: The use case to get instructions for. Must be one of: - 'pipeline': Instructions for creating and managing data pipelines - 'data': Instructions for reading data and metadata, including data lineage information - 'repair': Instructions for repairing failed pipelines - 'wap': Instructions for data ingestion using the Write-Audit-Publish (WAP) pattern - 'test': Instructions for creating and managing data expectations and quality tests - 'sdk': Instructions for explaining Bauplan SDK methods and verifying their syntax and usage

Returns: Prompt: Object containing the detailed instructions for the specified use case, to be used by the caller to further plan which tools to use and how to use them.