> ## Documentation Index
> Fetch the complete documentation index at: https://docs.cognite.com/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Cognite Data Fusion (CDF) is an industrial DataOps platform. Prefer English docs unless the user asks for another locale.
> Follow /_llms/ index links recursively until you reach page URLs ending in .md. Fetch those Markdown twins instead of HTML.
> For REST APIs, default to calendar version 20230101 (stable). Use 20230101-beta or 20230101-alpha only if the user is on a preview API. Cite paths under /api-reference/concepts/<version>/ and the Cdf-Version header. Prefer the Python SDK (cognite-sdk) unless the user is in JavaScript/TypeScript.
> Start here by task: platform overview /cdf/index.md; data modeling /cdf/dm/index.md; data integration /cdf/integration/index.md; access /cdf/access/index.md; CDF Toolkit /cdf/deploy/cdf_toolkit/index.md; REST quickstart /dev/quickstart.md; Python SDK https://cognite-sdk-python.readthedocs-hosted.com/en/stable/; Atlas AI /cdf/atlas_ai/concepts/index.md; Flows apps /cdf/flows/index.md; MCP and IDE setup /dev/guides/ide_ai_integration.md.
> For implementation work, also load /skill.md.

# Prepare aliases and match fields

> Step-by-step guide to populate names and aliases on match targets before entity matching tokenizes strings, applies blocking, or diagram annotation resolves tags.

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](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md) for assets (functional locations), tags, and identities, and [About entity matching](https://docs.cognite.com/cdf/integration/guides/contextualization/matching.md) for how tokenization and scoring work.

For production pipelines, the [CDF Entity Matching](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/entity_matching.md) 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/file_annotation.md) 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](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md#what-must-exist-before-you-match).
* 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](https://docs.cognite.com/cdf/dm/dm_reference/dm_core_data_model.md#describable-props).

> [!NOTE]
>
> A functional location is a `CogniteAsset` in the industrial knowledge graph. It is not a [location filter](https://docs.cognite.com/cdf/locations.md), which scopes search and 3D to a physical site.

> [!WARNING]
>
> 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](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md#keep-functional-location-tag-and-equipment-distinct).

**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](https://docs.cognite.com/cdf/integration/guides/contextualization/matching.md#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](https://docs.cognite.com/cdf/integration/concepts/transformation/index.md) or in a one-off load. [Aliases](https://docs.cognite.com/cdf/dm/dm_reference/dm_core_data_model.md#describable-props) also improve [search](https://docs.cognite.com/cdf/dm/dm_concepts/dm_smarter_search_results.md) 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](https://docs.cognite.com/cdf/integration/guides/contextualization/match_entities.md).
* In a production pipeline, the [CDF Entity Matching](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/entity_matching.md) 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](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/file_annotation.md) 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.

| Tier | What to add | Example |
| - | - | - |
| Mechanical | Normalized forms of the same tag (case, separators, leading zeros) | `P-101`, `P0101`, `P_101` |
| Synonym | Abbreviations, legacy names, alternate unit codes | `PT-101` for a row labeled *pressure transmitter 101* |
| Authoritative | Curated mapping tables from SMEs or master data | Old tag `P-101A` → current tag `P-101` after a rename project |

Prefer **authoritative** mapping tables and deterministic rules before fuzzy matching. See [Choose a contextualization approach](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md#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](https://docs.cognite.com/cdf/integration/guides/contextualization/match_entities.md) 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.

| Symptom | Likely cause | What to do |
| - | - | - |
| The model returns no suggested matches | Empty match fields, aliases that are only tokenizer-stripped forms of `name`, or missing abbreviations | Revisit steps 2 and 4; confirm shared tokens survive tokenization on a sample |
| Matches look correct in quick match but fail at scale | Blocking scope too wide (for example, two sites share tag prefixes) or stale alias lists | Narrow site or plant scope; reload authoritative rename mappings into `aliases` |
| Diagram tags do not resolve | Tag text missing from target `name` or `aliases`, or historical voided tags not added as aliases | Add P\&ID and control-system variants; survey deprecated tags (step 5). If aliases look correct, see [Troubleshooting interactive diagrams](https://docs.cognite.com/cdf/integration/guides/contextualization/troubleshooting.md) for diagram parsing configuration. |

## Next steps

* [Operate matching and annotation](https://docs.cognite.com/cdf/integration/guides/contextualization/operate_pipelines.md) to scope pipelines, configure incremental reruns, and preserve SME-confirmed links.
* [Match entities](https://docs.cognite.com/cdf/integration/guides/contextualization/match_entities.md) in Cognite Data Fusion, or deploy the [CDF Entity Matching](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/entity_matching.md) deployment pack for production pipelines.
* [Parse diagrams](https://docs.cognite.com/cdf/integration/guides/contextualization/parse_diagrams.md) or use the [File Annotation](https://docs.cognite.com/cdf/deploy/cdf_toolkit/references/packages/file_annotation.md) deployment pack once asset `name` and `aliases` resolve diagram tags.
* Return to [About contextualization](https://docs.cognite.com/cdf/integration/concepts/contextualization/overview.md) if you need to revisit enterprise identity or site scoping.