Python API

This reference explains how to use the Soda Core Python API to generate, test, publish, and verify data contracts using local execution (Soda Core) or remote execution (Soda Agent).

Installation

Soda Python Libraries

Publish a local Contract to Soda Cloud

Publishing a new version of a contract to Soda Cloud requires additional permissions in Soda Cloud.

• If you are publishing a new version for an existing dataset, you must have the Managed contract permission for that dataset.

• If you are publishing a new dataset, you must have the global permission Create new datasets and data sources with Soda Library.

Learn more about permissions in Soda Cloud Global and Dataset Roles

Use publish_contract to publish a contract to Soda Cloud:

from soda_core.contracts import publish_contract

result = publish_contract(
    contract_file_path="contract1.yaml",
    soda_cloud_file_path="path/to/soda_cloud.yml"
)

Parameter	Required	Type	Description
contract_file_path	Yes	str	Path to local contract file
soda_cloud_file_path	yes	str	Path to Soda Cloud config file

Configure Logging

To enable logging for contract operations, use:

from soda_core import configure_logging

# Enable or disable verbose logging
configure_logging(verbose=True)

To access logs after a verification run:

from soda_core.contracts import publish_contract

result = publish_contract(
    contract_file_path="contract1.yaml",
    soda_cloud_file_path="path/to/soda_cloud.yml"
)

result.get_logs()

Publish Result Object

Publish Verification Session Result

Represents the overall publication session (may include multiple contracts).

Attributes

• ContractPublicationResultList: list[ContractPublicationResult] : all per-contract publication results. See ContractPublicationResult

Methods

• get_logs() -> list[str] : publication logs across all contracts.

• get_errors() -> list[str] : publication errors across all contracts.

---

ContractPublicationResult

Immutable outcome for a single contract publishing.

Attributes

• contract: Optional[Contract] : See Contract

---

Contract

Describes the published contract (dataset identity and source info).

Attributes

• data_source_name str : name of the data source (as configured in Soda).

• dataset_prefix: str[] : hierarchical prefix (e.g., db, schema).

• dataset_name: str : name of the dataset (table/view).

• soda_qualified_dataset_name: str : full qualified dataset identifier.

• source: YamlFileContentInfo : reference to YAML source definition. See YamlFileContentInfo

• dataset_id: Optional[str]: the unique identifier of the dataset (only filled in when results are sent to Soda Cloud).

YamlFileContentInfo

Describes the published YAML.

Attributes

• source_content_str: Optional[str] : YAML provided inline.

• local_path: Optional[str] : local file path to the YAML.

Verify a Contract

Soda Library can verify contracts either locally (Soda Core) or remotely (Soda Agent). The returned session result objects share a common structure, but log/diagnostics availability differs by execution context.

Publishing verification results to Soda Cloud with publish=True requires additional permissions in Soda Cloud.

• If you are publishing to an existing dataset, you must have the Managed contract permission for that dataset.

• If you are publishing a new dataset, you must have the global permission Create new datasets and data sources with Soda Library.

Learn more about permissions in Soda Cloud Global and Dataset Roles

With Soda Core

Use verify_contract_locally to run the verification using local configuration and execution:

from soda_core.contracts import verify_contract_locally

result = verify_contract_locally(
    data_source_file_path="path/to/data_source.yml",
    contract_file_path="contract1.yaml", ## OR dataset_identifier="datasource/db/schema/dataset"
    soda_cloud_file_path="path/to/soda_cloud.yml",
    variables={"START_DATE": "2024-01-01"},
    publish=False,
)

Parameter	Required	Type	Description
data_source_file_path	Yes (or data_source_file_paths is required)	str	Path to data source file Data source reference for Soda Core
data_source_file_paths	Yes (or data_source_file_path is required)	[str]	Paths to data source files Data source reference for Soda Core . Required when using reconciliation checks to compare with a source dataset located in another data source.
contract_file_path	Yes (or dataset_identifier is required)	str	Path to local contract file
dataset_identifier	Yes (or contract_file_path is required)	str	Dataset identifier to fetch contracts from Soda Cloud Dataset fully qualified name
variables	No	dict	Variables to override in contract
publish	No	bool	Push results to Soda Cloud.
soda_cloud_file_path	No (unless publish is True)	str	Path to Soda Cloud config file

With Soda Agent

Use verify_contract_on_agent to run verification remotely via Soda Agent.

from soda_core.contracts import verify_contract_on_agent

result = verify_contract_on_agent(
    contract_file_path="path/to/contract.yaml", ## OR dataset_identifier="datasource/db/schema/dataset"
    soda_cloud_file_path="path/to/soda_cloud.yml",
    variables={"COUNTRY": "US"},
    publish=True,
)

Parameter	Required	Type	Description
contract_file_path	Yes (or dataset_identifier is required)	str	Path to local contract file
dataset_identifier	Yes (or contract_file_path is required)	str	Dataset identifier to fetch contract from Soda Cloud Dataset fully qualified name
variables	No	dict	Variables to override in contract
publish	No	bool	Push results to Soda Cloud.
soda_cloud_file_path	Yes	str	Path to Soda Cloud config file
blocking_timeout_in_minutes	No	int	How long to wait for the agent to return results (default: 60 minutes)

---

Configure Logging

To enable logging for contract operations, use:

from soda_core import configure_logging

# Enable or disable verbose logging
configure_logging(verbose=True)

To access logs after a verification run:

from soda_core.contracts import verify_contract_on_agent

result = verify_contract_on_agent(
    contract_file_path="path/to/contract.yaml", 
    soda_cloud_file_path="path/to/soda_cloud.yml",
)

result.get_logs()

---

Verification Result Object

Running a verification returns a ContractVerificationSessionResult that aggregates results for one or more contracts verified in a single session. Use it to read logs and errors across contracts and to compute aggregate pass/fail counts. Each contract gets a ContractVerificationResult per-check CheckResult entries and derived counters.

---

Contract Verification Session Result

Represents the overall verification session (may include multiple contracts).

Attributes available for Soda Core and Soda Agent scans

• contract_verification_results: list[ContractVerificationResult] : all per-contract results. See ContractVerificationResult

• has_errors: bool : true if any contract has execution errors.

• has_excluded: bool : true if any contract has any excluded checks.

• is_failed: bool : true if any contract has failed checks. Ignores execution errors.

• is_passed: bool : true if all contracts have no failed checks. Ignores execution errors.

• is_warned: bool : true if any contract has warned checks. Ignores execution errors.

• is_ok: bool : true if all contracts are both not failed and have no errors.

Attributes only available for Soda Core scans

• number_of_checks: int : sum across contract.

• number_of_checks_excluded: sum across contract.

• number_of_checks_passed: int : sum across contract.

• number_of_checks_failed: int : sum across contract.

• started_timestamp: timestamp : verification start timestamp

• data_timestamp: timestamp : Effective timestamp of the contract. In the future, It will be possible to overwrite the value for backfilling use case.

• ended_timestamp: timestamp : verification end timestamp

Methods

• get_logs() -> list[str] : concatenated logs from all contracts.

• get_logs_str() -> str : newline-joined logs.

• get_errors() -> list[str] / get_errors_str() -> str : aggregated error lines from logs.

---

ContractVerificationResult

Immutable outcome for a single contract: status, timing, measurements, and per-check results.

Attributes available for Soda Core and Soda Agent scans

• contract: Contract : See Contract

• status: ContractVerificationStatus : FAILED, PASSED, WARNED, ERROR, or UNKNOWN. See ContractVerificationStatus

• sending_results_to_soda_cloud_failed: bool : whether publishing failed.

• log_records: Optional[list[logging.LogRecord]] : detailed logs.

• has_errors: bool : true if status is ERROR.

• is_failed: bool : true if status is FAILED. (Only checks, not execution errors.)

• is_warned: bool : true if status is WARNED. (Ignores execution errors.)

• is_passed: bool : true if status is PASSED. (Ignores execution errors.)

• is_ok: bool : not failed and not in error.

• number_of_checks: int / number_of_checks_passed: int / number_of_checks_failed: int : counts derived from check_results.

Attributes only available for Soda Core scans

• data_source: DataSource : See DataSource

• data_timestamp: Optional[datetime] : data time context (if any).

• started_timestamp: datetime / ended_timestamp: datetime : execution window.

• measurements: list[Measurement] — See Measurement

• check_results: list[CheckResult] — See CheckResult

• scan_id: Optional[str]: the id of the scan (filled in when results are sent to soda-cloud)

Methods

• get_logs() -> list[str] / get_logs_str() -> str : pull message text from log records.

• get_errors() -> list[str] / get_errors_str() -> str : log lines at error level or higher.

---

CheckResult

Represents the outcome of a single check in the contract.

Attributes

• check: Check : See Check

• outcome: CheckOutcome : PASSED, WARNED, FAILED, or NOT_EVALUATED. See CheckOutcome

• threshold_value: Optional[float|int] : threshold applied.

• diagnostic_metric_values: Optional[dict[str, float|int|str]] : diagnostic metrics.

• is_passed: bool / is_failed: bool / is_not_evaluated: bool : convenience flags.

• outcome_emoticon: str : Unicode for quick visual status.

Methods

• log_table_row() -> dict : compact, user-friendly log row (includes diagnostics).

• log_table_row_diagnostics(verbose: bool=True) -> str : formatted diagnostic string; uses _log_console_format(...) for short form.

---

CheckOutcome

PASSED, WARNED, FAILED, NOT_EVALUATED.

---

Measurement

Metric container captured during verification.

Attributes

• metric_id: str : unique identifier of the metric.

• metric_name: Optional[str] : name of the metric.

• value: Any : captured value of the metric.

---

ContractVerificationStatus

Execution status of a contract. Drives is_failed, is_passed, and has_errors.

Values

• UNKNOWN : status not determined.

• FAILED : contract executed and one or more checks failed.

• WARNED: contract executed and one or more checks warned.

• PASSED : contract executed and all checks passed.

• ERROR : execution error occurred.

---

Check

Represents the executed check definition (identity, type, threshold, etc.).

Attributes

• type: str : check type (e.g., missing, row_count).

• name: Optional[str] : ame of the check.

• qualifier: Optional[str] : string to distinguish multiple checks of same type.

• identity: str : unique identifier of the check, used to correlate results in Soda Cloud. It is automatically generated based on the check path in the contract.

• column_name: Optional[str] : column the check applies to (if applicable).

• threshold: Optional[Threshold] : threshold configuration for this check.

• attributes: dict[str, Any] : metadata attributes (for Soda Cloud, routing, etc.).

• location: str : where in the contract YAML the check is defined.

---

Threshold

Configured numeric boundaries for a check outcome.

Attributes

• must_be: Optional[float|int] : value must equal the configured number.

• must_not_be: Optional[float|int] : value must not equal the configured number.

• must_be_greater_than: Optional[float|int] : value must be strictly greater than.

• must_be_greater_than_or_equal: Optional[float|int] : value must be greater than or equal.

• must_be_less_than: Optional[float|int] : value must be strictly less than.

• must_be_less_than_or_equal: Optional[float|int] : value must be less than or equal.

• must_be_between: Optional[dict] : value must be within the specified range.

• must_be_not_between: Optional[dict] : value must not be within the specified range.

---

Contract

Describes the verified contract (dataset identity and source info).

Attributes

• data_source_name str : name of the data source (as configured in Soda).

• dataset_prefix: str[] : hierarchical prefix (e.g., db, schema).

• dataset_name: str : name of the dataset (table/view).

• source: YamlFileContentInfo : reference to YAML source definition. See YamlFileContentInfo

• dataset_id: Optional[str]: the unique identifier of the dataset (only filled in when results are sent to Soda Cloud).

---

YamlFileContentInfo

Describes where the YAML was loaded from.

Attributes

• source_content_str: Optional[str] : YAML provided inline.

• local_path: Optional[str] : local file path to the YAML.

---

DataSource

Represents the data source used for verification.

Attributes

• name: str : logical name of the data source.

• type: str : type of the data source (e.g., Postgres, Snowflake, BigQuery).

---

---

You are not logged in to Soda and are viewing the default public documentation. Learn more about Documentation access & licensing.