## Client

```python
bauplan.Client(profile: str | None, api_key: str | None, client_timeout: int | None, config_file_path: str | None)
```

A client for the Bauplan API.

**Parameters:**
- `profile` (str | None): The Bauplan config profile name to use to determine api_key.
- `api_key` (str | None): Your unique Bauplan API key; mutually exclusive with `profile`. If not provided, fetch precedence is 1) environment `BAUPLAN_API_KEY` 2) .bauplan/config.yml
- `client_timeout` (int | None): The client timeout in seconds for all the requests.
- `config_file_path` (str | None): The path to the Bauplan config file to use. If not provided, ~/.bauplan/config.yaml will be used. Note that this disables any environment-based configuration.

### apply_table_creation_plan

```python
def apply_table_creation_plan(plan: TableCreatePlanState | str, *, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Apply a plan for creating a table. It is done automatically during the
table plan creation if no schema conflicts exist. Otherwise, if schema
conflicts exist, then this function is used to apply them after the
schema conflicts are resolved. The most common schema conflict is two
parquet files with the same column name but different datatypes.

  **Parameters:**
  - `plan` ([TableCreatePlanState](/reference/bauplan-state#bauplan-state-tablecreateplanstate) | str): The plan to apply.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

  **Raises:**
  - `[bauplan.exceptions.TableCreatePlanApplyStatusError](/reference/bauplan-exceptions#bauplan-exceptions-tablecreateplanapplystatuserror)`: if the table creation plan apply fails.

### cancel_job

```python
def cancel_job(job_id: str)
```

EXPERIMENTAL: Cancel a job by ID.

  **Parameters:**
  - `job_id` (str): A job ID

### create_branch

```python
def create_branch(branch: str | Branch, from_ref: str | Ref, *, if_not_exists: bool = False)
```

Create a new branch at a given ref.
The branch name should follow the convention of `username.branch_name`,
otherwise non-admin users won't be able to complete the operation.

  **Parameters:**
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the new branch.
  - `from_ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The name of the base branch; either a branch like "main" or ref like "main@[sha]".
  - `if_not_exists` (bool): If set to `True`, the branch will not be created if it already exists.

  **Raises:**
  - `[bauplan.exceptions.CreateBranchForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-createbranchforbiddenerror)`: if the user does not have access to create the branch.
  - `[bauplan.exceptions.BranchExistsError](/reference/bauplan-exceptions#bauplan-exceptions-branchexistserror)`: if the branch already exists.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the source ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### create_external_table_from_metadata

```python
def create_external_table_from_metadata(table: str | Table, metadata_json_uri: str, *, namespace: str | Namespace, branch: str | Branch | None, overwrite: bool = False)
```

Create an external table from an Iceberg metadata.json file.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The name of the table to create.
  - `metadata_json_uri` (str): The S3 URI pointing to the Iceberg table's metadata.json file.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace)): The namespace for the table (required).
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch) | None): The branch name in which to create the table. Defaults to the active branch, or 'main'.
  - `overwrite` (bool): Whether to overwrite an existing table with the same name (default: False).

  **Raises:**
  - `ValueError`: if metadata_json_uri is empty or invalid, or if table parameter is invalid.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `[bauplan.exceptions.InvalidDataError](/reference/bauplan-exceptions#bauplan-exceptions-invaliddataerror)`: if the metadata location is within the warehouse directory.
  - `[bauplan.exceptions.UpdateConflictError](/reference/bauplan-exceptions#bauplan-exceptions-updateconflicterror)`: if a table with the same name already exists and overwrite=False.
  - `[bauplan.exceptions.BauplanError](/reference/bauplan-exceptions#bauplan-exceptions-bauplanerror)`: for other API errors during registration or retrieval.

### create_external_table_from_parquet

```python
def create_external_table_from_parquet(table: str | Table, search_patterns: list[str], *, branch: str | Branch | None, namespace: str | Namespace | None, overwrite: bool = False, args: dict[str, str] | None, priority: int | None, client_timeout: int | None, detach: bool = False)
```

Creates an external table from S3 files.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The name of the external table to create.
  - `search_patterns` (list[str]): List of search_patterns for files to create the external table from. Must resolve to parquet files
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch) | None): Branch in which to create the table.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): Namespace of the table. If not specified, namespace will be inferred from table name or default settings.
  - `overwrite` (bool): Whether to delete and recreate the table if it already exists.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.
  - `detach` (bool): Whether to detach the job and return immediately without waiting for the job to finish.

### create_namespace

```python
def create_namespace(namespace: str | Namespace, branch: str | Branch, *, commit_body: str | None, commit_properties: dict[str, str] | None, if_not_exists: bool = False)
```

Create a new namespace at a given branch.

  **Parameters:**
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace)): The name of the namespace.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to create the namespace on.
  - `commit_body` (str | None): Optional, the commit body to attach to the operation.
  - `commit_properties` (dict[str, str] | None): Optional, a list of properties to attach to the commit.
  - `if_not_exists` (bool): If set to `True`, the namespace will not be created if it already exists.

  **Raises:**
  - `[bauplan.exceptions.CreateNamespaceForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-createnamespaceforbiddenerror)`: if the user does not have access to create the namespace.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotABranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notabranchreferror)`: if the object is not a branch.
  - `[bauplan.exceptions.NotAWriteBranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notawritebranchreferror)`: if the destination branch is not a writable ref.
  - `[bauplan.exceptions.NamespaceExistsError](/reference/bauplan-exceptions#bauplan-exceptions-namespaceexistserror)`: if the namespace already exists.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### create_table

```python
def create_table(table: str | Table, search_uri: str, *, branch: str | Branch | None, namespace: str | Namespace | None, partitioned_by: str | None, replace: bool | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Create a table from an S3 location.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table which will be created.
  - `search_uri` (str): The location of the files to scan for schema.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch) | None): The branch name in which to create the table.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): Optional argument specifying the namespace. If not specified, it will be inferred based on table location or the default.
  - `partitioned_by` (str | None): Optional argument specifying the table partitioning.
  - `replace` (bool | None): Replace the table if it already exists.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

  **Raises:**
  - `[bauplan.exceptions.TableCreatePlanStatusError](/reference/bauplan-exceptions#bauplan-exceptions-tablecreateplanstatuserror)`: if the table creation plan fails.
  - `[bauplan.exceptions.TableCreatePlanApplyStatusError](/reference/bauplan-exceptions#bauplan-exceptions-tablecreateplanapplystatuserror)`: if the table creation plan apply fails.

### create_tag

```python
def create_tag(tag: str | Tag, from_ref: str | Ref, *, if_not_exists: bool = False)
```

Create a new tag at a given ref.

  **Parameters:**
  - `tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The name of the new tag.
  - `from_ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The name of the base branch; either a branch like "main" or ref like "main@[sha]".
  - `if_not_exists` (bool): If set to `True`, the tag will not be created if it already exists.

  **Raises:**
  - `[bauplan.exceptions.CreateTagForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-createtagforbiddenerror)`: if the user does not have access to create the tag.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.TagExistsError](/reference/bauplan-exceptions#bauplan-exceptions-tagexistserror)`: if the tag already exists.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### delete_branch

```python
def delete_branch(branch: str | Branch, *, if_exists: bool = False)
```

Delete a branch.

  **Parameters:**
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to delete.
  - `if_exists` (bool): If set to `True`, the branch will not raise an error if it does not exist.

  **Raises:**
  - `[bauplan.exceptions.DeleteBranchForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-deletebranchforbiddenerror)`: if the user does not have access to delete the branch.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotABranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notabranchreferror)`: if the object is not a branch.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### delete_namespace

```python
def delete_namespace(namespace: str | Namespace, branch: str | Branch, *, if_exists: bool = False, commit_body: str | None, commit_properties: dict[str, str] | None)
```

Delete a namespace.

  **Parameters:**
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace)): The name of the namespace to delete.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to delete the namespace from.
  - `if_exists` (bool): If set to `True`, the namespace will not raise an error if it does not exist.
  - `commit_body` (str | None): Optional, the commit body to attach to the operation.
  - `commit_properties` (dict[str, str] | None): Optional, a list of properties to attach to the commit.

  **Raises:**
  - `[bauplan.exceptions.DeleteNamespaceForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-deletenamespaceforbiddenerror)`: if the user does not have access to delete the namespace.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotABranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notabranchreferror)`: if the object is not a branch.
  - `[bauplan.exceptions.NotAWriteBranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notawritebranchreferror)`: if the destination branch is not a writable ref.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.NamespaceIsNotEmptyError](/reference/bauplan-exceptions#bauplan-exceptions-namespaceisnotemptyerror)`: if the namespace is not empty.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### delete_table

```python
def delete_table(table: str | Table, branch: str | Branch, *, namespace: str | Namespace | None, if_exists: bool = False, commit_body: str | None, commit_properties: dict[str, str] | None)
```

Drop a table.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table to delete.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The branch on which the table is stored.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The namespace of the table to delete.
  - `if_exists` (bool): If set to `True`, the table will not raise an error if it does not exist.
  - `commit_body` (str | None): Optional, the commit body message to attach to the commit.
  - `commit_properties` (dict[str, str] | None): Optional, a list of properties to attach to the commit.

  **Raises:**
  - `[bauplan.exceptions.DeleteTableForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-deletetableforbiddenerror)`: if the user does not have access to delete the table.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotAWriteBranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notawritebranchreferror)`: if the destination branch is not a writable ref.
  - `[bauplan.exceptions.MergeConflictError](/reference/bauplan-exceptions#bauplan-exceptions-mergeconflicterror)`: if the delete operation results in a conflict.
  - `[bauplan.exceptions.TableNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tablenotfounderror)`: if the table does not exist.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.NamespaceUnresolvedError](/reference/bauplan-exceptions#bauplan-exceptions-namespaceunresolvederror)`: if conflicting namespaces names are specified.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### delete_tag

```python
def delete_tag(tag: str | Tag, *, if_exists: bool = False)
```

Delete a tag.

  **Parameters:**
  - `tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The name of the tag to delete.
  - `if_exists` (bool): If set to `True`, the tag will not raise an error if it does not exist.

  **Raises:**
  - `[bauplan.exceptions.DeleteTagForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-deletetagforbiddenerror)`: if the user does not have access to delete the tag.
  - `[bauplan.exceptions.TagNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tagnotfounderror)`: if the tag does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotATagRefError](/reference/bauplan-exceptions#bauplan-exceptions-notatagreferror)`: if the object is not a tag.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_branch

```python
def get_branch(branch: str | Branch)
```

Get the branch.

  **Parameters:**
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to retrieve.

  **Raises:**
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.NotABranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notabranchreferror)`: if the object is not a branch.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.ForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-forbiddenerror)`: if the user does not have access to the branch.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_branches

```python
def get_branches(*, name: str | None, user: str | None, limit: int | None)
```

Get the available data branches in the Bauplan catalog.

  **Parameters:**
  - `name` (str | None): Filter the branches by name.
  - `user` (str | None): Filter the branches by user.
  - `limit` (int | None): Optional, max number of branches to get.

### get_commits

```python
def get_commits(ref: str | Ref, *, filter_by_message: str | None, filter_by_author_username: str | None, filter_by_author_name: str | None, filter_by_author_email: str | None, filter_by_authored_date: str | datetime | None, filter_by_authored_date_start_at: str | datetime | None, filter_by_authored_date_end_at: str | datetime | None, filter_by_parent_hash: str | None, filter_by_properties: dict[str, str] | None, filter: str | None, limit: int | None)
```

Get the commits for the target branch or ref.

  **Parameters:**
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref or branch to get the commits from.
  - `filter_by_message` (str | None): Optional, filter the commits by message (can be a string or a regex like '^abc.*$')
  - `filter_by_author_username` (str | None): Optional, filter the commits by author username (can be a string or a regex like '^abc.*$')
  - `filter_by_author_name` (str | None): Optional, filter the commits by author name (can be a string or a regex like '^abc.*$')
  - `filter_by_author_email` (str | None): Optional, filter the commits by author email (can be a string or a regex like '^abc.*$')
  - `filter_by_authored_date` (str | datetime | None): Optional, filter the commits by the exact authored date.
  - `filter_by_authored_date_start_at` (str | datetime | None): Optional, filter the commits by authored date start at.
  - `filter_by_authored_date_end_at` (str | datetime | None): Optional, filter the commits by authored date end at.
  - `filter_by_parent_hash` (str | None): Optional, filter the commits by parent hash.
  - `filter_by_properties` (dict[str, str] | None): Optional, filter the commits by commit properties.
  - `filter` (str | None): Optional, a CEL filter expression to filter the commits.
  - `limit` (int | None): Optional, max number of commits to get.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_job

```python
def get_job(job_id: str)
```

EXPERIMENTAL: Get a job by ID.

  **Parameters:**
  - `job_id` (str): A job ID

### get_job_context

```python
def get_job_context(job: str | Job, *, include_logs: bool = False, include_snapshot: bool = False)
```

EXPERIMENTAL: Get context for a job by ID.

  **Parameters:**
  - `job` (str | [Job](/reference/bauplan-schema#bauplan-schema-job)): Union[str, Job]: A job ID or a Job instance.
  - `include_logs` (bool): bool: Whether to include logs in the response.
  - `include_snapshot` (bool): bool: Whether to include the code snapshot in the response.

### get_job_contexts

```python
def get_job_contexts(jobs: str | list[str] | list[Job], *, include_logs: bool = False, include_snapshot: bool = False)
```

EXPERIMENTAL: Get context for multiple jobs.

  **Parameters:**
  - `jobs` (str | list[str] | list[[Job](/reference/bauplan-schema#bauplan-schema-job)]): list[Union[str, Job]]: A list of job IDs or Job instances.
  - `include_logs` (bool): bool: Whether to include logs in the response.
  - `include_snapshot` (bool): bool: Whether to include the code snapshot in the response.

### get_job_logs

```python
def get_job_logs(job: str | Job)
```

EXPERIMENTAL: Get logs for a job.

  **Parameters:**
  - `job` (str | [Job](/reference/bauplan-schema#bauplan-schema-job)): Union[str, Job]: A job ID or a Job instance.

### get_jobs

```python
def get_jobs(*, all_users: bool = False, filter_by_ids: str | list[str] | list[Job] | None, filter_by_users: str | list[str] | None, filter_by_kinds: str | JobKind | list[str] | list[JobKind] | None, filter_by_statuses: str | JobState | list[str] | list[JobState] | None, filter_by_created_after: datetime | None, filter_by_created_before: datetime | None, limit: int | None)
```

Get jobs with optional filtering.

  **Parameters:**
  - `all_users` (bool): Optional[bool]: Whether to list jobs from all users or only the current user.
  - `filter_by_ids` (str | list[str] | list[[Job](/reference/bauplan-schema#bauplan-schema-job)] | None): Optional[Union[str, List[str]]]: Optional, filter by job IDs.
  - `filter_by_users` (str | list[str] | None): Optional[Union[str, List[str]]]: Optional, filter by job users.
  - `filter_by_kinds` (str | [JobKind](/reference/bauplan-schema#bauplan-schema-jobkind) | list[str] | list[[JobKind](/reference/bauplan-schema#bauplan-schema-jobkind)] | None): Optional[Union[str, JobKind, List[Union[str, JobKind]]]]: Optional, filter by job kinds.
  - `filter_by_statuses` (str | [JobState](/reference/bauplan-schema#bauplan-schema-jobstate) | list[str] | list[[JobState](/reference/bauplan-schema#bauplan-schema-jobstate)] | None): Optional[Union[str, JobState, List[Union[str, JobState]]]]: Optional, filter by job statuses.
  - `filter_by_created_after` (datetime | None): Optional[datetime]: Optional, filter jobs created after this datetime.
  - `filter_by_created_before` (datetime | None): Optional[datetime]: Optional, filter jobs created before this datetime.
  - `limit` (int | None): Optional[int]: Optional, max number of jobs to return.

### get_namespace

```python
def get_namespace(namespace: str | Namespace, ref: str | Ref)
```

Get a namespace.

  **Parameters:**
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace)): The name of the namespace to get.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref, branch name or tag name to check the namespace on.

  **Raises:**
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_namespaces

```python
def get_namespaces(ref: str | Ref, *, filter_by_name: str | None, limit: int | None)
```

Get the available data namespaces in the Bauplan catalog branch.

  **Parameters:**
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref, branch name or tag name to retrieve the namespaces from.
  - `filter_by_name` (str | None): Optional, filter the namespaces by name.
  - `limit` (int | None): Optional, max number of namespaces to get.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_table

```python
def get_table(table: str | Table, ref: str | Ref, *, namespace: str | Namespace | None)
```

Get the table data and metadata for a table in the target branch.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table to retrieve.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref, branch name or tag name to get the table from.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The namespace of the table to retrieve.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.NamespaceUnresolvedError](/reference/bauplan-exceptions#bauplan-exceptions-namespaceunresolvederror)`: if conflicting namespaces names are specified.
  - `[bauplan.exceptions.TableNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tablenotfounderror)`: if the table does not exist.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_tables

```python
def get_tables(ref: str | Ref, *, filter_by_name: str | None, filter_by_namespace: str | Namespace | None, limit: int | None)
```

Get the tables and views in the target branch.

  **Parameters:**
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref or branch to get the tables from.
  - `filter_by_name` (str | None): Optional, the table name to filter by.
  - `filter_by_namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): Optional, the namespace to get filtered tables from.
  - `limit` (int | None): Optional, max number of tables to get.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.TableNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tablenotfounderror)`: if the table does not exist.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_tag

```python
def get_tag(tag: str | Tag)
```

Get the tag.

  **Parameters:**
  - `tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The name of the tag to retrieve.

  **Raises:**
  - `[bauplan.exceptions.TagNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tagnotfounderror)`: if the tag does not exist.
  - `[bauplan.exceptions.NotATagRefError](/reference/bauplan-exceptions#bauplan-exceptions-notatagreferror)`: if the object is not a tag.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### get_tags

```python
def get_tags(*, filter_by_name: str | None, limit: int | None)
```

Get all the tags.

  **Parameters:**
  - `filter_by_name` (str | None): Optional, filter the tags by name.
  - `limit` (int | None): Optional, max number of tags to get.

  **Raises:**
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### has_branch

```python
def has_branch(branch: str | Branch)
```

Check if a branch exists.

  **Parameters:**
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to check.

  **Raises:**
  - `[bauplan.exceptions.ForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-forbiddenerror)`: if the user does not have access to the branch.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### has_namespace

```python
def has_namespace(namespace: str | Namespace, ref: str | Ref)
```

Check if a namespace exists.

  **Parameters:**
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace)): The name of the namespace to check.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref, branch name or tag name to check the namespace on.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### has_table

```python
def has_table(table: str | Table, ref: str | Ref, *, namespace: str | Namespace | None)
```

Check if a table exists.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table to retrieve.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The ref, branch name or tag name to get the table from.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The namespace of the table to check.

  **Raises:**
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.NamespaceNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-namespacenotfounderror)`: if the namespace does not exist.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### has_tag

```python
def has_tag(tag: str | Tag)
```

Check if a tag exists.

  **Parameters:**
  - `tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The tag to retrieve.

  **Raises:**
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### import_data

```python
def import_data(table: str | Table, search_uri: str, *, branch: str | Branch | None, namespace: str | Namespace | None, continue_on_error: bool = False, import_duplicate_files: bool = False, best_effort: bool = False, preview: str | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None, detach: bool = False)
```

Imports data into an already existing table.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): Previously created table into which data will be imported.
  - `search_uri` (str): URI to scan for files to import.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch) | None): Branch in which to import the table.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): Namespace of the table. If not specified, namespace will be inferred from table name or default settings.
  - `continue_on_error` (bool): Do not fail the import even if 1 data import fails.
  - `import_duplicate_files` (bool): Ignore prevention of importing s3 files that were already imported.
  - `best_effort` (bool): Don't fail if schema of table does not match.
  - `preview` (str | None): Whether to enable or disable preview mode for the import.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.
  - `detach` (bool): Whether to detach the job and return immediately without waiting for the job to finish.

### info

```python
def info(*, client_timeout: int | None)
```

Fetch organization & account information.

  **Parameters:**
  - `client_timeout` (int | None): timeout in seconds.

### merge_branch

```python
def merge_branch(source_ref: str | Ref, into_branch: str | Branch, *, commit_message: str | None, commit_body: str | None, commit_properties: dict[str, str] | None)
```

Merge one branch into another.

  **Parameters:**
  - `source_ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The name of the merge source; either a branch like "main" or ref like "main@[sha]".
  - `into_branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the merge target.
  - `commit_message` (str | None): Optional, the commit message.
  - `commit_body` (str | None): Optional, the commit body.
  - `commit_properties` (dict[str, str] | None): Optional, a list of properties to attach to the merge.

  **Raises:**
  - `[bauplan.exceptions.MergeForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-mergeforbiddenerror)`: if the user does not have access to merge the branch.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the destination branch does not exist.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if the branch head hash has changed.
  - `[bauplan.exceptions.NotAWriteBranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notawritebranchreferror)`: if the destination branch is not a writable ref.
  - `[bauplan.exceptions.MergeConflictError](/reference/bauplan-exceptions#bauplan-exceptions-mergeconflicterror)`: if the merge operation results in a conflict.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the source ref does not exist.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### plan_table_creation

```python
def plan_table_creation(table: str | Table, search_uri: str, *, branch: str | Branch | None, namespace: str | Namespace | None, partitioned_by: str | None, replace: bool | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Create a table import plan from an S3 location.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table which will be created.
  - `search_uri` (str): The location of the files to scan for schema.
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch) | None): The branch name in which to create the table.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): Optional argument specifying the namespace. If not specified, it will be inferred based on table location or the default.
  - `partitioned_by` (str | None): Optional argument specifying the table partitioning.
  - `replace` (bool | None): Replace the table if it already exists.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

  **Raises:**
  - `[bauplan.exceptions.TableCreatePlanStatusError](/reference/bauplan-exceptions#bauplan-exceptions-tablecreateplanstatuserror)`: if the table creation plan fails.

### query

```python
def query(query: str, *, ref: str | Ref | None, max_rows: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Execute a SQL query and return the results as a pyarrow.Table.
Note that this function uses Arrow also internally, resulting
in a fast data transfer.

  **Parameters:**
  - `query` (str): The Bauplan query to execute. Column and table names are case-sensitive.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to query from.
  - `max_rows` (int | None): The maximum number of rows to return; default: `None` (no limit).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the query in. If not set, the query will be run in the default namespace for your account.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

### query_to_csv_file

```python
def query_to_csv_file(path: str | pathlib.Path, query: str, *, ref: str | Ref | None, max_rows: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Export the results of a SQL query to a file in CSV format.

  **Parameters:**
  - `path` (str | pathlib.Path): The name or path of the file csv to write the results to.
  - `query` (str): The Bauplan query to execute. Column and table names are case-sensitive.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to query from.
  - `max_rows` (int | None): The maximum number of rows to return; default: `None` (no limit).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the query in. If not set, the query will be run in the default namespace for your account.
  - `priority` (int | None): No description
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

### query_to_generator

```python
def query_to_generator(query: str, *, ref: str | Ref | None, max_rows: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Execute a SQL query and return the results as a generator, where each row is
a Python dictionary.

  **Parameters:**
  - `query` (str): The Bauplan query to execute. Column and table names are case-sensitive.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to query from.
  - `max_rows` (int | None): The maximum number of rows to return; default: `None` (no limit).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the query in. If not set, the query will be run in the default namespace for your account.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

### query_to_json_file

```python
def query_to_json_file(path: str | pathlib.Path, query: str, *, file_format: Literal['json', 'jsonl'] = 'json', ref: str | Ref | None, max_rows: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Export the results of a SQL query to a file in JSON format.

  **Parameters:**
  - `path` (str | pathlib.Path): The name or path of the file json to write the results to.
  - `query` (str): The Bauplan query to execute. Column and table names are case-sensitive.
  - `file_format` (Literal['json', 'jsonl']): The format to write the results in; default: `json`. Allowed values are 'json' and 'jsonl'.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to query from.
  - `max_rows` (int | None): The maximum number of rows to return; default: `None` (no limit).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the query in. If not set, the query will be run in the default namespace for your account.
  - `priority` (int | None): No description
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

### query_to_parquet_file

```python
def query_to_parquet_file(path: str | pathlib.Path, query: str, *, ref: str | Ref | None, max_rows: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Export the results of a SQL query to a file in Parquet format.

  **Parameters:**
  - `path` (str | pathlib.Path): The name or path of the file parquet to write the results to.
  - `query` (str): The Bauplan query to execute. Column and table names are case-sensitive.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to query from.
  - `max_rows` (int | None): The maximum number of rows to return; default: `None` (no limit).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the query in. If not set, the query will be run in the default namespace for your account.
  - `priority` (int | None): No description
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

### rename_branch

```python
def rename_branch(branch: str | Branch, new_branch: str | Branch)
```

Rename an existing branch.
The branch name should follow the convention of "username.branch_name",
otherwise non-admin users won't be able to complete the operation.

  **Parameters:**
  - `branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the branch to rename.
  - `new_branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the new branch.

  **Raises:**
  - `[bauplan.exceptions.RenameBranchForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-renamebranchforbiddenerror)`: if the user does not have access to rename the branch.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the branch does not exist.
  - `[bauplan.exceptions.BranchExistsError](/reference/bauplan-exceptions#bauplan-exceptions-branchexistserror)`: if the new branch name already exists.
  - `[bauplan.exceptions.NotABranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notabranchreferror)`: if the object is not a branch.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### rename_tag

```python
def rename_tag(tag: str | Tag, new_tag: str | Tag)
```

Rename an existing tag.

  **Parameters:**
  - `tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The name of the tag to rename.
  - `new_tag` (str | [Tag](/reference/bauplan-schema#bauplan-schema-tag)): The name of the new tag.

  **Raises:**
  - `[bauplan.exceptions.RenameTagForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-renametagforbiddenerror)`: if the user does not have access to rename the tag.
  - `[bauplan.exceptions.TagNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tagnotfounderror)`: if the tag does not exist.
  - `[bauplan.exceptions.TagExistsError](/reference/bauplan-exceptions#bauplan-exceptions-tagexistserror)`: if the new tag name already exists.
  - `[bauplan.exceptions.NotATagRefError](/reference/bauplan-exceptions#bauplan-exceptions-notatagreferror)`: if the object is not a tag.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format is invalid.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the user's credentials are invalid.
  - `ValueError`: if one or more parameters are invalid.

### revert_table

```python
def revert_table(table: str | Table, *, namespace: str | Namespace | None, source_ref: str | Ref, into_branch: str | Branch, replace: bool | None, commit_body: str | None, commit_properties: dict[str, str] | None)
```

Revert a table to a previous state.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table to revert.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The namespace of the table to revert.
  - `source_ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref)): The name of the source ref; either a branch like "main" or ref like "main@[sha]".
  - `into_branch` (str | [Branch](/reference/bauplan-schema#bauplan-schema-branch)): The name of the target branch where the table will be reverted.
  - `replace` (bool | None): Optional, whether to replace the table if it already exists.
  - `commit_body` (str | None): Optional, the commit body message to attach to the operation.
  - `commit_properties` (dict[str, str] | None): Optional, a list of properties to attach to the operation.

  **Raises:**
  - `ValueError`: if the table identifier is invalid, source_ref or branch_name is blank, the source entry is not Iceberg, a snapshot_id is missing, or a path validation error occurs.
  - `[bauplan.exceptions.InvalidRefError](/reference/bauplan-exceptions#bauplan-exceptions-invalidreferror)`: if the ref format from Nessie is invalid.
  - `[bauplan.exceptions.NotAWriteBranchRefError](/reference/bauplan-exceptions#bauplan-exceptions-notawritebranchreferror)`: if the destination ref is not a branch.
  - `[bauplan.exceptions.SameRefError](/reference/bauplan-exceptions#bauplan-exceptions-samereferror)`: if the source and destination have the same hash.
  - `[bauplan.exceptions.UnauthorizedError](/reference/bauplan-exceptions#bauplan-exceptions-unauthorizederror)`: if the JWT is invalid or the auth session is missing.
  - `[bauplan.exceptions.ForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-forbiddenerror)`: if the user lacks writer role.
  - `[bauplan.exceptions.RevertTableForbiddenError](/reference/bauplan-exceptions#bauplan-exceptions-reverttableforbiddenerror)`: if there is a zone/workspace restriction on the destination branch.
  - `[bauplan.exceptions.RefNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-refnotfounderror)`: if the source ref doesn't exist.
  - `[bauplan.exceptions.TableNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-tablenotfounderror)`: if the source table is not found on the source ref.
  - `[bauplan.exceptions.BranchNotFoundError](/reference/bauplan-exceptions#bauplan-exceptions-branchnotfounderror)`: if the destination branch doesn't exist.
  - `[bauplan.exceptions.NamespaceUnresolvedError](/reference/bauplan-exceptions#bauplan-exceptions-namespaceunresolvederror)`: if the namespace cannot be resolved.
  - `[bauplan.exceptions.BranchHeadChangedError](/reference/bauplan-exceptions#bauplan-exceptions-branchheadchangederror)`: if a concurrent modification changed the branch head.
  - `[bauplan.exceptions.RevertDestinationTableExistsError](/reference/bauplan-exceptions#bauplan-exceptions-revertdestinationtableexistserror)`: if the destination table exists and the replace flag is not set.
  - `[bauplan.exceptions.RevertIdenticalTableError](/reference/bauplan-exceptions#bauplan-exceptions-revertidenticaltableerror)`: if the source and destination have the same snapshot.
  - `[bauplan.exceptions.MergeConflictError](/reference/bauplan-exceptions#bauplan-exceptions-mergeconflicterror)`: if there is a merge conflict during the transactional revert.

### run

```python
def run(project_dir: str, *, ref: str | Ref | None, namespace: str | Namespace | None, parameters: dict[str, str | int | float | bool | None] | None, cache: Literal['on', 'off'] | None, transaction: Literal['on', 'off'] | None, dry_run: bool | None, strict: Literal['on', 'off'] | None, preview: str | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None, detach: bool = False)
```

Run a Bauplan project and return the state of the run. This is the equivalent of
running through the CLI the `bauplan run` command. All parameters default to 'off'/false unless otherwise specified.

  **Parameters:**
  - `project_dir` (str): The directory of the project (where the `bauplan_project.yml` or `bauplan_project.yaml` file is located).
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name from which to run the project.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the job in. If not set, the job will be run in the default namespace.
  - `parameters` (dict[str, str | int | float | bool | None] | None): Parameters for templating into SQL or Python models.
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the run. Defaults to 'on'.
  - `transaction` (Literal['on', 'off'] | None): Whether to enable or disable transaction mode for the run. Defaults to 'on'.
  - `dry_run` (bool | None): Whether to enable or disable dry-run mode for the run; models are not materialized.
  - `strict` (Literal['on', 'off'] | None): Whether to enable or disable strict schema validation.
  - `preview` (str | None): Whether to enable or disable preview mode for the run.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.
  - `detach` (bool): Whether to detach the run and return immediately instead of blocking on log streaming.

### scan

```python
def scan(table: str | Table, *, ref: str | Ref | None, columns: list[str] | None, filters: str | None, limit: int | None, cache: Literal['on', 'off'] | None, namespace: str | Namespace | None, args: dict[str, str] | None, priority: int | None, client_timeout: int | None)
```

Execute a table scan (with optional filters) and return the results as an arrow Table.

  **Parameters:**
  - `table` (str | [Table](/reference/bauplan-schema#bauplan-schema-table)): The table to scan.
  - `ref` (str | [Ref](/reference/bauplan-schema#bauplan-schema-ref) | None): The ref, branch name or tag name to scan from.
  - `columns` (list[str] | None): The columns to return (default: `None`).
  - `filters` (str | None): The filters to apply (default: `None`).
  - `limit` (int | None): The maximum number of rows to return (default: `None`).
  - `cache` (Literal['on', 'off'] | None): Whether to enable or disable caching for the query.
  - `namespace` (str | [Namespace](/reference/bauplan-schema#bauplan-schema-namespace) | None): The Namespace to run the scan in. If not set, the scan will be run in the default namespace for your account.
  - `priority` (int | None): Optional job priority (1-10, where 10 is highest priority).
  - `client_timeout` (int | None): seconds to timeout; this also cancels the remote job execution. Defaults to 1800 seconds.

The kind/type of a job.

The execution state of a job.

## Model

```python
bauplan.Model(name: str, columns: Optional[List[str]], filter: Optional[str], ref: Optional[str], connector: Optional[str], connector_config_key: Optional[str], connector_config_uri: Optional[str])
```

Bases: `pyarrow.Table`

Represents a model (dataframe/table representing a DAG step) as an input
to a function.

**Parameters:**
- `name` (str): The name of the model.
- `columns` (Optional[List[str]]): The list of columns in the model. If the arg is not provided, the model will load all columns.
- `filter` (Optional[str]): The optional filter for the model. Defaults to None.
- `ref` (Optional[str]): The optional reference to the model. Defaults to None.
- `connector` (Optional[str]): The connector type for the model (defaults to Bauplan SQL). Allowed values are 'snowflake' and 'dremio'.
- `connector_config_key` (Optional[str]): The key name if the SSM key is custom with the pattern `bauplan/connectors/<connector_type>/<key>`.
- `connector_config_uri` (Optional[str]): Full SSM uri if completely custom path, e.g. `ssm://us-west-2/123456789012/baubau/dremio`.

## Parameter

```python
bauplan.Parameter(param_name: str)
```

Represents a parameter that can be used to "template" values
passed to a model during a run or query with, e.g.,
``bauplan run --parameter interest_rate=2.0``.

**Parameters:**
- `param_name` (str): No description

The type of a ref.

## expectation

```python
def expectation(**kwargs: Any = {})
```

Decorator that defines a Bauplan expectation.

## extras

```python
def extras(*args = ())
```

Decorator that defines the `bauplan` package extras to install.

## model

```python
def model(name: Optional[str], columns: Optional[List[str]], partitioned_by: Optional[Union[str, List[str], Tuple[str, ...]]], materialization_strategy: Optional[ModelMaterializationStrategy], cache_strategy: Optional[ModelCacheStrategy], internet_access: Optional[bool], overwrite_filter: Optional[str], **kwargs: Any = {})
```

Decorator that specifies a Bauplan model.

**Parameters:**
- `name` (Optional[str]): the name of the model (e.g. 'users'); if missing the function name is used.
- `columns` (Optional[List[str]]): the columns of the output dataframe after the model runs (e.g. ['id', 'name', 'email']). Use ['*'] as a wildcard.
- `partitioned_by` (Optional[Union[str, List[str], Tuple[str, ...]]]): the columns to partition the data by.
- `materialization_strategy` (Optional[ModelMaterializationStrategy]): the materialization strategy to use.
- `cache_strategy` (Optional[ModelCacheStrategy]): the cache strategy to use.
- `internet_access` (Optional[bool]): whether the model requires internet access.
- `overwrite_filter` (Optional[str]): the overwrite filter expression.

## python

```python
def python(version: Optional[str], pip: Optional[Dict[str, str]], **kwargs: Any = {})
```

Decorator that defines a Python environment for a Bauplan function (e.g. a model or expectation). It is used to
specify directly in code the configuration of the Python environment required to run the function, i.e.
the Python version and the Python packages required.

**Parameters:**
- `version` (Optional[str]): The python version for the interpreter (e.g. ``'3.11'``).
- `pip` (Optional[Dict[str, str]]): A dictionary of dependencies (and versions) required by the function (e.g. ``{'requests': '2.26.0'}``).

## resources

```python
def resources(cpus: Optional[Union[int, float]], memory: Optional[Union[int, str]], memory_swap: Optional[Union[int, str]], timeout: Optional[int], **kwargs: Any = {})
```

Decorator that defines the resources required by a Bauplan function (e.g. a model or expectation). It is used to
specify directly in code the configuration of the resources required to run the function.

**Parameters:**
- `cpus` (Optional[Union[int, float]]): The number of CPUs required by the function (e.g: ``0.5``)
- `memory` (Optional[Union[int, str]]): The amount of memory required by the function (e.g: ``1G``, ``1000``)
- `memory_swap` (Optional[Union[int, str]]): The amount of swap memory required by the function (e.g: ``1G``, ``1000``)
- `timeout` (Optional[int]): The maximum time the function is allowed to run (e.g: ``60``)