In the OpenLineage standard, what does a run event carry and what are facets used for?

## Why a standard exists at all Before an interchange format, every tool grew its own lineage representation, and stitching a pipeline that spans an ingestion tool, an orchestrator, a processing engine and a warehouse meant writing N×M adapters. **OpenLineage** defines one event format that producers emit and consumers ingest, so integrations are written once per tool rather than once per pair. It is also **push, at runtime**: the thing doing the work reports what it did. That means the recorded lineage reflects the execution that actually happened, including runs that failed and runs that read nothing. ## The core model: job, run, dataset Three entities carry almost everything. - **Job** — the recurring unit of work: a scheduled transformation, a task in a pipeline, a query. Identified by a **namespace** plus a **name**, so `warehouse-prod` and `warehouse-dev` do not collide. - **Run** — one execution of a job, identified by a **UUID** (`runId`). Runs are what carry timing, state and per-execution metrics. - **Dataset** — an input or output: a table, a file path, a topic. Also namespace plus name, where the namespace conventionally identifies the storage system or connection. An event ties them together: *this run of this job read these datasets and wrote those.* ## The run event A `RunEvent` carries an `eventTime`, an `eventType`, the `run` and `job` objects, `inputs` and `outputs` arrays, and a `producer` identifying the integration that emitted it. The event types are `START`, `RUNNING`, `COMPLETE`, `FAIL`, `ABORT` and `OTHER`. The important consequence is that **lineage is assembled from multiple events**: a `START` at the beginning, optionally `RUNNING` updates, and a terminal `COMPLETE` or `FAIL`. Both carry the same `runId`, and a consumer merges them. This is why you can know a run began, know what it intended to read, and still record that it failed — a state a static graph cannot express. ```json { "eventType": "COMPLETE", "eventTime": "2026-08-21T02:14:53.101Z", "run": { "runId": "3f1b9d2e-6c44-4d1a-9c31-0a7e5b2f8a10" }, "job": { "namespace": "warehouse-prod", "name": "build_orders_daily" }, "inputs": [ { "namespace": "warehouse-prod", "name": "raw.orders" } ], "outputs": [ { "namespace": "warehouse-prod", "name": "mart.orders_daily" } ] } ``` ## Facets: the extension mechanism If every useful piece of metadata were a core field, the specification would be enormous and every addition would be a breaking change. **Facets** solve that: optional, self-describing, independently versioned JSON objects attached to a run, a job, a dataset, or specifically to an input or an output dataset. Each declares the schema it conforms to, so a consumer that does not recognise a facet can ignore it without failing. Commonly used ones include: - **Dataset facets** — `schema` (field names and types), `dataSource` (where it lives), `columnLineage` (field-level edges, including the input fields behind each output field), `documentation`, `ownership`, `version`. - **Output dataset facets** — `outputStatistics`, carrying row count and size written by this run. This is the metric that turns lineage into observability: not just *that* a table was written, but how much. - **Input dataset facets** — `dataQualityMetrics`, carrying row counts and per-column statistics of what was read. - **Run facets** — `nominalTime` (the logical window the run covers, distinct from wall-clock start), `parent` (linking a task run to the run of its enclosing pipeline), `errorMessage` on failures. - **Job facets** — `sql` (the query text), `sourceCodeLocation`, `documentation`, `ownership`. Organisations can also define custom facets for internal metadata without forking the specification. ## Producers and consumers A **producer** is anything that emits events: an integration inside an orchestrator that reports each task run, a plugin in a processing engine, a wrapper around a transformation tool, or your own code posting to the HTTP endpoint. A **consumer** stores and serves them — **Marquez** is the reference implementation, exposing the accumulated graph and run history through an API and a UI, and several commercial catalogs ingest the same format. ## Why the model matters in an interview The interesting points are not the field names but the design choices they encode. Events rather than a static graph means lineage reflects reality including failures. Run-scoped identity means you can ask when a dataset was last produced and by which execution. Facets mean lineage, schema, statistics and quality metrics travel in **one** message, so the metadata store can answer "what fed this, how many rows, and was it fresh" without joining three systems. And a shared format means a pipeline crossing four tools can still produce one connected graph — provided all four agree on how datasets are named, which in practice is the hardest part of any real deployment.