About contextualization

Contextualization in Cognite Data Fusion (CDF) is how you create relationships on a populated industrial knowledge graph. Matching and diagram parsing link time series, files, and diagram tags to nodes that already represent your plant. Document parsing can create new instances or populate properties on existing instances.

Why contextualization matters

When relationships connect time series, files, and equipment to the same asset (functional location), applications can navigate from one resource to everything linked to it. Select a tag to see its time series, or traverse a flow line to collect pressure readings from each instrument along the path. The resource-to-asset diagram shows time series, files, diagrams, and equipment pointing at a shared CogniteAsset node on the graph.

Time series, files, diagrams, and equipment linked to a shared CogniteAsset node.

How contextualization works

At a high level:

Populate the enterprise graph. Functional locations, equipment, and shared name and aliases values exist on the enterprise layer before you link resources from other systems.
Prepare match fields. Aliases, abbreviations, and site scoping support tokenization and blocking. See Prepare aliases and match fields.
Match or annotate. Use transformations, entity matching, or diagram parsing to create relationships to existing nodes. Use document parsing to create instances or populate properties on existing ones.
Validate quality. Review coverage, orphans, and confidence before you tune models. See Understanding contextualization quality.

Keep functional location, tag, and equipment distinct

Industrial systems talk about the same pump in three ways. Keep those as separate entities in CDF. A replacement, a rename, or a serial number must not rewrite the hierarchy.

A functional location is a CogniteAsset in the industrial knowledge graph. It is not a location filter, which scopes search and 3D to a physical site.

Concept	What it is	Typical type in the core data model
Functional location	A place in the plant that performs a function, such as a pump slot in a station.	CogniteAsset
Tag	The engineering identifier used on P&IDs and in control systems, for example `P-101`.	Often the `name` and aliases of that asset, not a serial number
Equipment	The physical device currently installed there.	CogniteEquipment

When you replace a failed pump, the functional location and the tag stay. You relate a new equipment instance to the same functional location. If you store the serial number in the tag name, matching and diagram annotation break the next time the device changes. Source systems use different field names for functional locations, tags, and equipment. Treat mappings as project-specific. Do not promote a maintenance work-order ID or a historian point ID into the functional location identity. The equipment replacement diagram shows the CogniteAsset staying in place while only the CogniteEquipment instance changes.

Equipment replacement: the CogniteAsset stays while the CogniteEquipment instance changes.

Give each object a stable identity

Matching and annotation need three kinds of identity. Mixing them is a common reason rebuilds and incremental runs fail.

Enterprise identity is the instance ID in CDF: a space plus externalId. See Spaces, instances, and direct relations for how spaces work. This is the key other resources should point at. Govern it, and keep it stable. Follow the resource naming reference for space and externalId.
Source identity is lineage back to the system you extracted from. Store it on CogniteSourceable (sourceId, sourceContext, source). Do not use a raw source key as the enterprise externalId. Source encodings change; enterprise identity should survive a replay.
Native resource identity belongs to the time series, file, or other resource itself. A time series keeps its own externalId. Never reuse that value as the asset’s enterprise identity, and never reuse one entity’s ID for another.

Do not promote a source-system key to enterprise identity, and do not reuse a time series or file ID as an asset ID. Those shortcuts make matching look easy once and make every later load harder.

What must exist before you match

Run contextualization on the enterprise layer of your model, after source data is mapped into a shared structure. See Designing scalable data models for source, enterprise, and solution layers. Do not match in the source layer, and do not treat solution views as the system of record for links. Before you run matching or annotation, confirm that:

The enterprise graph is populated: functional locations (and tags) exist as CogniteAsset nodes, and physical devices as CogniteEquipment where you need that split.
Spaces, instances, and direct relations are decided, including how you will isolate sites or plants later.
Business keys stay stable across reloads. Replay loads must reuse the same enterprise identities instead of creating new IDs.
name and aliases are populated on the nodes you will match.
Entity matching compares strings. Empty match fields, aliases that are only the stripped form of the name, or missing abbreviations cause silent misses, not visible errors.
Keep forms that survive tokenization (how the model breaks strings into tokens for comparison), including leading zeros where they are significant. See About entity matching for tokenization and blocking.

Standards-based enterprise models such as the ISA Data Model and the Oil and Gas Data Model are starting points for a graph, not a substitute for populating it.

Use one asset hierarchy

If several source systems each bring a hierarchy, pick one master CogniteAsset parent/children tree. See Building an asset hierarchy for how to structure it. Relate the other trees to that master. Matching scoped to two competing asset trees will collide on common tags such as P-101 at different sites.

Choose a contextualization approach

Use the simplest tool that can link a time series, file, or diagram tag to the asset (functional location) it belongs to. Prefer deterministic joins and explicit mapping tables before fuzzy matching. Scope candidates by site, plant, or unit. Identical tags at two sites must not land in the same match candidate set.

Situation	Approach
Source and target share an exact business key	Write the relationship. See About transformations.
Names differ across systems, or you need rules plus machine learning	See About entity matching in CDF, or the CDF Entity Matching deployment pack for production pipelines.
Engineering diagrams such as P&IDs	See About diagram parsing for data modeling or Create interactive diagrams. For production volumes, see the File Annotation deployment pack.
Documents with key-value data	See About document parsing (public preview).

Next steps

Confirm the enterprise model and hierarchy: Designing scalable data models and Building an asset hierarchy.
Prepare aliases and match fields, then Match entities or deploy the CDF Entity Matching deployment pack.
Link diagrams with Parse diagrams or the File Annotation deployment pack.
Interpret results with Understanding contextualization quality, then measure in-scope coverage with the Contextualization Quality Dashboard deployment pack.