Core Concepts

Catalogian monitors product data feeds for changes. This page explains the five core concepts you'll encounter throughout the docs and API.

Source

A source is a connection to a data file. It can be a CSV uploaded through the dashboard, an HTTP URL that Catalogian fetches on a schedule, or an SFTP server. Each source has a name, a format (CSV, TSV, or JSONL), and a key field.

Sources are the top-level object in Catalogian. Everything — snapshots, delta events, webhooks, API keys — is scoped to a source.

{
  "id": "src_01j...",
  "name": "Acme Product Feed",
  "type": "http",
  "format": "csv",
  "keyField": "sku",
  "status": "active",
  "checkIntervalMinutes": 60,
  "url": "https://feeds.acme.com/products.csv"
}

Key Field

The key field is the column in your data that uniquely identifies each row. Catalogian uses it to track which rows are new, changed, or deleted across versions. You set it once when creating the source.

Common key fields: sku, id, product_id, gtin, upc.

Snapshot

A snapshot is a point-in-time copy of your source data. Every time Catalogian checks a source, it creates a new snapshot by ingesting the file and hashing each row. Snapshots are stored as key-value pairs: the key field value maps to the row's hash and full field data.

You can browse the current snapshot, search it, filter it, export it, or compare two snapshots side by side using the API or MCP tools.

Snapshot #5 (2026-03-19T08:00:00Z)
┌──────────┬──────────────────┬──────────────────────────────┐
│ row_key  │ row_hash         │ row_data                     │
├──────────┼──────────────────┼──────────────────────────────┤
│ sku-001  │ a3f2b8c1...      │ { "sku": "sku-001", ... }    │
│ sku-002  │ 7e9d4a12...      │ { "sku": "sku-002", ... }    │
│ sku-003  │ b1c5e8f3...      │ { "sku": "sku-003", ... }    │
└──────────┴──────────────────┴──────────────────────────────┘

Delta Event

A delta event is the diff between two consecutive snapshots. When Catalogian checks a source, it compares the new snapshot against the previous one and records exactly what changed:

• • New rows — keys present in the new snapshot but not the previous one
• • Changed rows — keys present in both, but the row hash differs (any field value changed)
• • Deleted rows — keys present in the previous snapshot but missing from the new one
• • Unchanged rows — keys present in both with identical hashes

Delta events include summary counts and up to 100 affected keys per category. For full row data (before/after values), use the delta rows endpoint.

{
  "id": "evt_01j...",
  "detectedAt": "2026-03-19T08:00:00.000Z",
  "newCount": 14,
  "changedCount": 3,
  "deletedCount": 1,
  "unchangedCount": 49982,
  "totalCount": 50000,
  "newKeys": ["sku-9001", "sku-9002"],
  "changedKeys": ["sku-1234", "sku-5678"],
  "deletedKeys": ["sku-0042"]
}

Check Interval

The check interval controls how often Catalogian fetches and diffs your source. Set it when creating or updating a source. The minimum interval depends on your plan:

You can also set a check anchor time (e.g. 06:00) to align checks to a specific time of day — useful when your vendor publishes feeds at a known hour.