GraphQL Lineage Tracking
Trace data from GraphQL operations through type definitions to model entities. Operations reference type definitions, type definitions use schemas, and schemas track lineage to properties in the data model.
GraphQL lineage tracking connects operations to the data model. Operations reference type definitions with field-level lineage to entity properties in model.neoarc. This creates full traceability from GraphQL query to canonical data model.
The GraphQL Lineage Chain
Lineage flows through the GraphQL type system:
How It Works
GraphQL operations reference schemas that serve as type definitions. Each schema field contains lineage entries mapping to model entity properties using sourceType: "graph" with graphFilePath: "model.neoarc".
{
"sourceType": "graph",
"graphFilePath": "model.neoarc",
"nodeName": "Product",
"nodeId": "b2c3d4e5-f6a7-4b8c-9d0e-1f2a3b4c5d6e",
"propertyName": "Name"
}Query Operation Lineage
Query operations retrieve data with full lineage tracking. The return type schema contains lineage entries for each field, mapping to the corresponding model entity properties.
| GraphQL Field | Schema Field | Model Entity | Model Property |
|---|---|---|---|
| id | id | Product | ProductId |
| name | name | Product | Name |
| description | description | Product | Description |
| price | price | Product | Price |
| sku | sku | Product | SKU |
| category | categoryId | Product | CategoryId |
Mutation Operation Lineage
Mutations modify data with lineage tracking on both input and return types. Input types map input fields to model properties, while return types trace the response data back to the model.
Subscription Operation Lineage
Subscriptions provide real-time data with the same lineage tracking. The return type schema traces fields to model properties identically to queries and mutations.
Tracing from Operation to Model
Cross-Entity Lineage
GraphQL types often span multiple model entities. A schema for an Order type might map fields to both the Order entity and related entities such as Customer and Product.
| Schema Field | Model Entity | Model Property | Notes |
|---|---|---|---|
| id | Order | OrderId | Primary identifier |
| customerId | Customer | CustomerId | Reference to Customer entity |
| totalAmount | Order | TotalAmount | Order total |
| status | Order | Status | Current order status |
| createdAt | Order | CreatedAt | Order creation timestamp |
Lineage Through Interfaces
When GraphQL types implement interfaces, lineage tracks through the implementations:
Custom Scalar Lineage
Custom scalars can have lineage notes documenting how the model property maps to the GraphQL scalar type:
| Scalar | Model Property Type | Transformation |
|---|---|---|
| DateTime | Timestamp | ISO 8601 serialisation |
| Money | Decimal | String serialisation to avoid precision loss |
| EmailAddress | String | RFC 5322 validation applied |
Visualising in the Intent Graph
The Intent Graph captures the full GraphQL lineage chain:
| Edge | From | To | Meaning |
|---|---|---|---|
| depends-on | GraphQL Operation | Schema | Operation uses this schema for arguments or return types |
| maps-to | Schema Field | Model Property | Field traces to this model entity property |
| derived-from | Schema Field | Schema Field | Inherited field from parent schema |