Skip to main content

​
sqb freshness

Observes the current data version of each source and reports whether the data has changed since the last build. Does not write any state or trigger builds.

​
Usage

sqb --project-dir <path> freshness [flags]

​
Flags

FlagDescription
--stateCompare observations against stored freshness state from the last build
--fail-on-errorExit with code 1 if any source observation fails or is unknown
--fail-on-staleExit with code 1 if any source has changed, is unknown, or errored (requires --state)
--virtual-envRead previous state from the specified virtual environment instead of direct state
--jsonOutput as JSON instead of human-readable text
--json-outputWrite JSON output to a file path (also prints text to stdout unless --json is set)
--no-sql-validationSkip compile-time SQL syntax validation
--select, -sSelect specific sources or models (sources upstream of selected models are included)
--excludeExclude specific sources or models

​
Source selection

Without --select, all sources in the project are observed. When --select is provided, selectors work like other commands: you can select sources by name, or select models and their upstream sources are automatically included: 
# Observe all sources
sqb freshness

# Observe a specific source
sqb freshness --select raw_orders

# Observe sources upstream of a model
sqb freshness --select fact_orders

​
Observation without state

By default, sqb freshness observes the current data version of each source and reports what it found. No comparison is made against previous observations: 
sqb freshness

Source freshness

Observed (3)
  raw_customers  timestamp  2026-06-05T14:30:00  adapter
  raw_orders     timestamp  2026-06-05T15:45:00  column  tolerance 15m
  raw_payments   integer    42871                 column

Summary: observed=3 changed=0 unchanged=0 tolerated=0 unknown=0 errors=0
Sources without explicit freshness: config are auto-observed using the adapter strategy if the adapter supports table metadata. Sources that can’t be observed (expression sources, managed sources without freshness config on unsupported adapters) show as unknown.

​
Comparing against state

Use --state to compare current observations against the freshness state stored from the last successful build: 
sqb freshness --state

Source freshness

Changed (1)
  raw_orders     previous 2026-06-05T12:00:00  current 2026-06-05T15:45:00  tolerance 15m

Unchanged (1)
  raw_customers  previous 2026-06-05T14:30:00  current 2026-06-05T14:30:00

Tolerated (1)
  raw_payments   previous 2026-06-05T14:28:00  current 2026-06-05T14:30:00  tolerance 15m

Summary: observed=0 changed=1 unchanged=1 tolerated=1 unknown=0 errors=0

​
Statuses

StatusMeaning
observedSuccessfully observed (no state comparison)
changedData version differs from the stored state
unchangedData version matches the stored state exactly
toleratedData version differs but is within the lag_tolerance threshold
unknownNo freshness config and adapter metadata unavailable, or no previous state to compare against
errorObservation failed (e.g. source table does not exist, query error)

​
Virtual environment state

To compare against state stored in a virtual environment instead of standard mode state: 
sqb freshness --state --virtual-env pr_123

​
CI integration

Use --fail-on-error to fail the pipeline if any source can’t be observed: 
sqb freshness --fail-on-error
Use --fail-on-stale with --state to fail if any source has new data that hasn’t been built yet: 
sqb freshness --state --fail-on-stale
This is useful for CI gates that should block if source data has changed but the pipeline hasn’t run yet.

​
JSON output

sqb freshness --json

{
  "sources": [
    {
      "name": "raw_orders",
      "status": "observed",
      "strategy": "column",
      "value_kind": "timestamp",
      "current_data_version": "2026-06-05T15:45:00",
      "previous_data_version": null,
      "lag_tolerance": "15m",
      "target": {
        "database": null,
        "schema": "raw",
        "name": "orders"
      },
      "message": null
    }
  ],
  "summary": {
    "observed": 1,
    "changed": 0,
    "unchanged": 0,
    "tolerated": 0,
    "unknown": 0,
    "errors": 0
  }
}

​
See also