Skip to main content
Prepare name, aliases, and the fields you use for matching before you train a model or run a pipeline. Entity matching compares strings. Diagram annotation looks up tag text against asset names and aliases. When match fields are empty or aliases do not survive tokenization, the model drops candidates in a blocking step. You get no suggested match, not an error. This procedure is for data engineers who already populated the industrial knowledge graph. Read About contextualization for assets (functional locations), tags, and identities, and About entity matching for how tokenization and scoring work. For production pipelines, the CDF Entity Matching deployment pack includes an aliases update function. It builds aliases from each instance’s name with regular expressions, on time series, assets, and files. Entity matching and File Annotation both use those aliases. File Annotation does not write its own. The name value still has to be something the pattern can match.

​
Prerequisites

Before you start:
  • Functional locations exist as CogniteAsset nodes with stable name values. See About contextualization.
  • You know which property entity matching reads on sources and targets (by default name on both sides; production pipelines often use aliases on time series).
  • You can write to the views that hold CogniteDescribable properties (name, aliases). See core data model.
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.
An empty match field or an alias that is only the tokenizer-stripped form of name causes a silent miss. Blocking removes non-similar targets before scoring. Poor alias preparation then looks like “the model found nothing.”

​
Populate targets and sources

1

Populate name on every match target

Set name on each CogniteAsset (and CogniteEquipment if you match to equipment) to the engineering tag or functional identifier you expect in source systems, for example P-101 or 11-PDN-26540J-60.Use the tag string from P&IDs and control systems, not a serial number or maintenance work-order ID. See About contextualization.
2

Add aliases that survive tokenization

Populate aliases on the same nodes with alternative strings entity matching should recognize. The entity matching tokenizer splits on letters and numbers and removes punctuation. See Detecting matches for the full rule set.Follow these rules when you build alias lists:
  • Store the full tag, not only a pre-stripped form. If name is 11-PDN-26540J-60, also add aliases such as PDN-26540J or 26540J-60 if sources use those variants. Do not store only 11, PDN, 26540 as your only aliases.
  • Keep leading zeros when they are significant in source data. If historians emit P-0101, add that form even when name is P-101.
  • Add abbreviations explicitly. If operators write PT for pressure transmitter, add both PT and the spelled-out form (or the reverse) as aliases. Blocking can then pair tokens across systems.
You can populate aliases during transformations or in a one-off load. Aliases also improve search when smarter search is enabled on your project.
3

Align source-side match fields

On time series or other sources, confirm the field configured in the matching pipeline contains comparable text.
  • In the Cognite Data Fusion (CDF) UI, check which match fields you select in Match entities.
  • In a production pipeline, the CDF Entity Matching deployment pack often uses aliases on the entity view. That pack’s aliases update function writes those aliases from name before matching, including on files that File Annotation reads. You still need a name the pattern can match.
If the source external ID embeds a tag, do not assume entity matching reads externalId unless you configure it as a match field.
4

Layer aliases from mechanical to authoritative

Build alias coverage in three tiers. Start simple before you rely on machine learning. The table below summarizes what to add at each tier.Prefer authoritative mapping tables and deterministic rules before fuzzy matching. See Choose a contextualization approach.
5

Survey rename and deprecated-tag artifacts

Search source systems and existing CDF loads for rename lists, deprecated tag spreadsheets, and engineering standards that define allowed abbreviations. Load those strings into aliases on the current CogniteAsset, not as new enterprise identities.If a tag was voided but still appears on old P&IDs, add it as an alias on the replacement asset. Diagram annotation needs that alias to resolve historical drawings.
6

Verify before you run matching

Spot-check a sample of sources against targets:
  1. Pick ten time series (or files) you expect to match.
  2. Read their configured match field and the target name / aliases.
  3. Confirm at least one shared token would survive tokenization. For example, 11-PDN-26540J-60 shares tokens PDN, 26540, and J with aliases that include those substrings.
  4. Run a small quick match or a scoped pipeline on that sample before you process the full data set.
If nothing matches, fix aliases and blocking scope before you tune model parameters.

​
Troubleshooting

If matching or diagram annotation still fails after you complete the steps above, use this table to narrow the cause before you tune model parameters or parser configuration.

​
Next steps

Last modified on October 28, 2026