Row Diffs — How Catalogian Detects Changes

Catalogian compares feeds 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": "sku-1234",
  "changeType": "changed",
  "row_data": {
    "sku": "sku-1234",
    "name": "Premium Widget",
    "price": "34.99",
    "in_stock": "true",
    "category": "Widgets"
  },
  "previous_data": {
    "sku": "sku-1234",
    "name": "Premium Widget",
    "price": "29.99",
    "in_stock": "false",
    "category": "Widgets"
  },
  "field_diff": {
    "price": {
      "before": "29.99",
      "after": "34.99"
    },
    "in_stock": {
      "before": "false",
      "after": "true"
    }
  }
}

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 price and in_stock changed. The other fields (name, category) 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 price change on SKU-1234. With full-row diffs, the agent knows the new price AND the product name, category, and current stock level, all in one response. It can immediately decide whether to update a listing, send an alert, or adjust a recommendation — no follow-up request needed.

With field-level-only diffs, the agent would see that price changed from "29.99" to "34.99", but it wouldn't know what product that is, whether it's in stock, or what category it belongs to — 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": "sku-9001",
  "changeType": "new",
  "row_data": {
    "sku": "sku-9001",
    "name": "New Gadget",
    "price": "19.99",
    "in_stock": "true"
  },
  "previous_data": null,
  "field_diff": null
}

Deleted rows

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

{
  "key": "sku-0042",
  "changeType": "deleted",
  "row_data": null,
  "previous_data": {
    "sku": "sku-0042",
    "name": "Discontinued Item",
    "price": "5.99",
    "in_stock": "false"
  },
  "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 catalog sync: An agent detects a price change, sees the full product row, and updates the correct listing in one step
• •Price monitoring: Filter for rows where field_diff.price exists to detect price changes
• •Stock alerts: Watch for in_stock flipping from "true" to "false"
• •Audit trails: Log every row change with timestamps for compliance