Author a contract in Soda Cloud
Once your dataset is onboarded, you can begin defining the expectations that make up your Data Contract.
Creating a Contract
To create a Data Contract, navigate to any onboarded dataset and click Create Contract.
This action requires the Manage contract permission on the dataset. Learn more about permissions here: Dataset Attributes & Responsibilities
You’ll be taken to the Contract Editor, a powerful interface where you can define your contract in two ways:
No-code view: Point-and-click UI to add quality checks and configure settings
Code view: YAML editor for full control and advanced use cases.
See language reference: Contract Language reference
You can switch between views at any time using the editor toggle in the top right corner.
Key Concepts in Contract Authoring
Understanding how to structure your contract is essential. Soda supports several types of checks and configuration options:
Filter: applies a global filter to limit which rows are considered across the entire contract (e.g., only the latest partition or rows from the past 7 days.)
Variables: help you parameterize your contract, making it flexible and adaptable to different contexts (e.g., environments, schedules, or partitions.)
Dataset-level Checks: rules that apply to the dataset as a whole, like row count, freshness, or schema checks.
Column-level Checks: rules that apply to individual columns, like missing values, uniqueness, ranges, or regex formats.
All visible columns are detected during onboarding. You can also manually add columns if needed.
Use Variables
Variables allow dynamic substitution of values in contracts. They help you:
Parameterize values that differ across environments, datasets, or schedules.
Reuse values in multiple places within the same contract to reduce duplication and improve maintainability.
You can define variables at the top of your contract:
Then use them throughout your contract using the ${var.VARIABLE_NAME} syntax.
For example:
filter: country = "${var.country}";
When running the contract, variable values must be provided unless a default is defined.
Variables are ideal for partitioned datasets, date-based rules, or customizing checks based on context.
Out of the box variables
Now: You can use ${soda.NOW} in your Contract to access the current timestamp.
Define Attributes
Use attributes to label, sort, and route your checks in Soda Cloud. Attributes help you organize checks by properties such as domain, priority, location, and sensitivity (e.g., PII).
Learn how to leverage attributes with Notifications and Browse datasets.
Apply Attributes to Checks
You can add attributes directly to individual checks. For example:
Set Default Attributes at the Top Level
You can also define default attributes at the dataset level. These attributes apply to all checks, unless overridden at the individual check level.
Attribute Validation in Soda Cloud
When publishing contract results to Soda Cloud, all check attributes must be pre-defined in Soda Cloud. If any attribute used in a contract is not registered in your Soda Cloud environment, the results will not be published, and the data contract scan will be marked as failed.
Learn how to configure attributes in Soda Cloud: Check and dataset attributes.
Testing the Contract
Before publishing, click Test to simulate a contract verification against your live data. Soda will:
Run all defined checks
Display which rules pass or fail
Surface profiling and diagnostic insights
This dry run helps ensure your contract behaves as expected, before making it official.
This action requires the "Manage contract" permission on the dataset. Learn more about permissions here: Dataset Attributes & Responsibilities
Test a contract on a data sample
You can test a contract on a sample of your data. Learn more at the onboarding Additional settings.
Publishing the Contract
Once you're happy with the results, click Publish.
Publishing sets this version as the source of truth for that dataset. From this point on:
Verifications will use the published version
All users see this contract as the authoritative definition of data quality for that dataset
Changes will require a new version or a proposal (depending on permissions)
Publishing ensures your data expectations are versioned, visible, and enforceable.
This action requires the Manage contract permission on the dataset. Learn more about permissions here: Dataset Attributes & Responsibilities
You’re now ready to start verifying your contract and monitoring your data.
Contract history
Contract history provides a snapshot view of all changes that have been made to a contract.
To access contract history:
Navigate to a dataset with an existing data contract.
Click on the icon next to Edit Contract, on the top right (or click on Edit Contract > ).
Review contract history by choosing a version on the left panel and inspecting it on the right panel.
Just as when a contract is being created or edited, you can toggle between the code and no-code views.
The code view allows to toggle diff and toggle split view.
Request history
While contract history allows to see the changes that a contract has undergone, request history provides an overview of the change requests that have been made over a specific contract.
View dataset request history
To access the request history of any dataset, navigate to the dataset > tab Requests.
The list of requests can be filtered by title key word and by state (Open, Done and Won't do)
From this view, you can also create a request.
This view provides a snapshot of each request, making visible:
The title, description (if any), and time of creation of the request
The state of the request (Open, Done and Won't do)
The icon, which indicates that the request has a proposal
The icon, which indicates that the request has comments
View organization request history
To access all request history in an organization, navigate to tab Requests on top of the page.
This page provides an overview of all requests made within the organization. The requests can be filtered by:
Title key word(s)
Status
User that created the request
Users that are participants in the request
Last updated
Was this helpful?