DuckDB Data Contract Smoke Tests

A data contract that only runs after production has already changed is not a contract. It is a postmortem with better formatting.

The practical problem

DuckDB is useful in Open Data Infrastructure because it can run serious SQL checks close to the developer workflow. The point is not that DuckDB replaces the lakehouse. The point is that local and CI-friendly checks can catch obvious contract failures before the shared platform has to absorb them.

DuckDB supports SQL constraints and works well with local files, which makes it a practical smoke-test engine for schema, nullability, uniqueness, grain, sample distribution, and policy flags. That is enough to turn many contract failures from platform incidents into pull request feedback.

Smoke tests should test the contract, not the demo

A useful smoke test starts with the promises the data product makes. Which columns exist? Which fields are required? What is the grain? Which values are accepted? Which sample rows prove that the shape is not accidentally empty? Which policy columns must be present before downstream systems touch the table?

Those checks can run against a local extract, a staged file, or a small candidate table. The result should be attached to the change record, not hidden in a developer terminal. A failed smoke test should say which contract promise broke and which downstream consumers care.

Where this fits in ODI

Open Data Infrastructure needs shared controls and local feedback. If every contract check requires the production warehouse, teams avoid running checks until late. If every check is local but disconnected from catalog metadata, nobody trusts the result.

The better pattern connects DuckDB smoke tests to catalog metadata, data product ownership, lineage, and CI evidence. Local execution stays fast, while the contract still belongs to the shared infrastructure layer.

What breaks first

• Teams test column presence but ignore grain, accepted values, and policy fields.
• The test data is so synthetic that it never exercises real failure modes.
• Smoke tests pass locally but are not tied to lineage or the data product version.
• CI treats every failed contract as a generic SQL error instead of a consumer risk.

Questions to ask

Ask which data contract promises can be tested before production. Ask whether the smoke-test result is attached to the change, the data product version, and the downstream consumer list. Ask whether policy and freshness are part of the test or left for later.

For adjacent patterns, read DuckDB as an agent evaluation harness, data product SLAs in ODI, and semantic contracts in Open Data Infrastructure.

Sources to start with

These primary sources anchor the technical claims in this guide.

• DuckDB SQL constraints
• DuckDB sqllogictest documentation
• DataHub data contracts
• OpenLineage documentation

The best data contract failure is the one that never gets promoted.