Row Diffs — How Catalogian Detects Changes

Catalogian compares records row by row. Every row is identified by its key field. When a row's content changes between two snapshots, Catalogian records the full before and after state of the entire row: every field. This is what makes Catalogian especially useful for AI agents: when an agent asks "what changed?", it gets the complete row context automatically, without needing to make a follow-up request for more detail.

How row comparison works

Catalogian hashes each row using its key field as identifier. When the hash changes between snapshots, the full row is re-stored. The delta rows endpoint returns:

• • row_data — the current (new) values of every field in the row
• • previous_data — the prior snapshot's values of every field
• • field_diff — a convenience map of only the fields that changed, with before/after pairs

The comparison unit is the row, not the field — you always get the full picture.

The delta rows response

When a row changes, the response includes the complete row state before and after the change. The primary data is row_data (current) and previous_data (prior snapshot):

{
  "key": "nc75443737",
  "changeType": "changed",
  "row_data": {
    "id": "nc75443737",
    "time": "2026-09-28T10:11:39.970Z",
    "place": "7 km WNW of Cobb, CA",
    "mag": "1.4",
    "status": "reviewed"
  },
  "previous_data": {
    "id": "nc75443737",
    "time": "2026-09-28T10:11:39.970Z",
    "place": "7 km WNW of Cobb, CA",
    "mag": "1.2",
    "status": "automatic"
  },
  "field_diff": {
    "mag": {
      "before": "1.2",
      "after": "1.4"
    },
    "status": {
      "before": "automatic",
      "after": "reviewed"
    }
  }
}

Since the full row is always available, field_diff is provided as a convenience — a pre-computed map of which fields changed, so you don't have to diff row_data and previous_data yourself. In this example, only mag and status changed. The other fields (id, time, place) are identical in both snapshots, so they don't appear in field_diff.

Why full-row data matters for AI agents

When an AI agent processes a change event, having the full row context — not just the changed fields — means the agent can reason about the change without additional API calls.

Consider a magnitude revision on nc75443737. With full-row diffs, the agent knows the new magnitude AND the place, time, and review status, all in one response. It can immediately decide whether to update a dashboard, send an alert, or refresh a model input: no follow-up request needed.

With field-level-only diffs, the agent would see that mag changed from "1.2" to "1.4", but it wouldn't know where the event was, when it happened, or whether it was reviewed; it would need to re-fetch the current row for context. Catalogian eliminates that round trip.

New rows

For rows with changeType: "new", the response includes row_data but no previous_data or field_diff (since there was no prior version):

{
  "key": "nc75443740",
  "changeType": "new",
  "row_data": {
    "id": "nc75443740",
    "time": "2026-09-28T18:22:41.180Z",
    "place": "12 km NE of Ridgecrest, CA",
    "mag": "2.6",
    "status": "automatic"
  },
  "previous_data": null,
  "field_diff": null
}

Deleted rows

For deleted rows, previous_data contains the last known values.row_data is null:

{
  "key": "nc75443001",
  "changeType": "deleted",
  "row_data": null,
  "previous_data": {
    "id": "nc75443001",
    "time": "2026-09-27T21:03:12.900Z",
    "place": "9 km SW of Livermore, CA",
    "mag": "1.4",
    "status": "automatic"
  },
  "field_diff": null
}

Querying row diffs

Fetch changed rows with the delta rows endpoint:

GET https://api.catalogian.com/v1/sources/:id/delta/:deltaEventId/rows?changeType=changed
Authorization: Bearer cat_live_...

You can filter by change type (new, changed, or deleted) and paginate with cursor and limit.

Common use cases

• •AI agent workflows: Agents read row diffs to auto-update downstream systems — full row context means no follow-up queries
• •Autonomous data sync: An agent detects a magnitude revision, sees the full row, and updates the right dashboard in one step
• •Value monitoring: Filter for rows where field_diff.mag exists to detect value changes
• •Status alerts: Watch for status flipping from "automatic" to "reviewed"
• •Audit trails: Log every row change with timestamps for compliance