Materializations
Read the recorded result of an attempt, and the latest pointer.
A materialization is the record that an attempt produced a version of an asset. The attempt is the work. The materialization is the result: where the rows were written, the columns that were observed, the row count, the upstream materialization ids it read, and the check results.
The record is appended. A later run writes a new materialization. The old one stays. The fields that change afterwards are checks, when a check result is recorded, and verified_at, when a later attempt confirms the current result is still current.
Inspect an asset
latest is a pointer on the asset. It names the materialization readers treat as current.
puppi assets --env prod
puppi assets core/customer --env prod Environment flags are in the CLI reference.
puppi assets prints every asset in the active deployment: role, dependencies, the latest id, the row count, the staleness verdict, and the next scheduled run. puppi assets <key> adds the materialization history.
The engine keeps the data for the newest two materializations of an asset. Older records remain as history. puppi rollback will not point at them.
A run that fails its checks can still write a materialization. If a blocking check fails, that row is quarantined and latest stays on the previous one. See Quarantine.
When a source writes nothing new
A source runs when a run or a schedule reaches it. Afterwards the engine may decide nothing arrived.
An append source writes no materialization when the cursor did not advance and the attempt emitted no rows. A full_refresh source writes no materialization when its content hash matches the hash on the current latest. The attempt is skipped, and verified_at is stamped on the current latest.
The first run of an asset always writes a materialization, including an empty one. An empty asset and an asset that has never run are different records. A full_refresh source whose adapter returns no content hash writes a materialization on every run.
Returning without emitting is not a skip. A full_refresh source that emits nothing writes an empty copy, and that copy becomes latest.
Skip a fetch
ctx.latest is the table of the current latest materialization, or null on the first run. On a file asset it is { meta, sha256, bytes, contentType } instead. ctx.unchanged() ends the attempt without writing. The engine records skipped and stamps verified_at on that latest. The same call works for an append source: the committed cursor stays where it is. On the first run there is no latest to stamp, and the attempt fails. A call after emit or emitFile throws.
run: async (ctx) => {
const response = await fetch("https://api.example.com/events");
const events = (await response.json()) as { id: string; created_at: string }[];
const newest = events.at(-1)?.created_at;
if (ctx.latest && newest) {
const { rows } = await ctx.query<{ created_at: string | null }>(
`select max(created_at) as created_at from ${ctx.latest}`,
);
if (rows[0]?.created_at === newest) return ctx.unchanged();
}
await ctx.emit(events);
}; What puppi try skips
puppi try prints rows and the contract verdict. It writes no materialization, moves no latest, and records no lineage. Those happen on a run the engine planned.