Skip to Content
Puppi
Concepts

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.