Documentation

Entity resolution metadata

Opt-in columns that surface DataNivra's deterministic cross-system entity linkage directly in provisioned tables, so each masked row carries a stable pseudonymous identity key alongside its masked values.

What it is

When an identity graph is active on a dataset, DataNivra's engine already links the same real entity across multiple source systems — a patient in an EHR, the same person in a billing system, and the same individual in a claims system all resolve to one internal entity. That linkage drives subsetting, referential integrity and consistent pseudonymization across tables.

Entity resolution metadata (ERM-01) makes that linkage visible in the provisioned data itself. When you enable the feature, DataNivra appends two columns to every table that participates in the identity graph:

ColumnTypeMeaning
_dn_entity_resolution_keytextA stable, deterministic pseudonym for the resolved entity. Identical across tables and datasets for the same real entity, different for different entities. Never contains or reversibly encodes a source identifier.
_dn_entity_resolution_sourcestextA JSON array of the source system names that contributed identity evidence for this entity (for example ["ehr","billing"]). Useful for understanding coverage and debugging linkage quality.

Both columns are NULL for rows that do not participate in a resolved entity (unlinked rows). Columns appear only on tables that the identity graph covers.

When to use it

Use caseWhy entity resolution metadata helps
Testing cross-system join logicYour test joins patients.ehr to patients.billing using _dn_entity_resolution_key — a stable pseudonymous key that works like a real primary key for the same entity across systems
Validating entity reconciliation servicesFeed masked data into your MDM or entity-matching service and compare its output against the _dn_entity_resolution_key ground truth
Debugging identity graph coverage_dn_entity_resolution_sources tells you which source systems resolved each entity; rows with only one source system are unresolved candidates
Auditing test data completenessConfirm that your subset contains the right mix of multi-source and single-source entities

Requirements

  • An identity graph must be configured in the dataset policy. Without one, the feature is accepted but produces no effect (no columns are appended).
  • Agent ≥ 0.6.2. Earlier versions do not have the column-injection code. The agent version is recorded in the certification report.

Enabling it

The flag is include_entity_resolution_metadata: true. It is false by default and can be set either on the dataset request (once, per request) or pinned in the test-data profile (so every invocation of that profile always gets the columns).

On a one-off dataset request (console or API)

In the console, check Include entity resolution metadata on the dataset request form under Build → Dataset Requests → New request. Over the API:

{
  "include_entity_resolution_metadata": true
}

in the POST /v1/dataset-requests body.

In a test-data profile (YAML manifest)

apiVersion: datanivra.io/v1alpha1
kind: TestDataProfile
metadata:
  name: healthcare-with-resolution
spec:
  sources:
    - { source_id: "...", kind: PostgreSQLSource }
  masking_policy: { policy_id: "...", kind: MaskingPolicy, version: 3, checksum: "..." }
  identity_graph:  { policy_id: "...", kind: IdentityGraph,  version: 2, checksum: "..." }
  scenarios:
    - { name: integration, tables: { patients: 500 } }
  include_entity_resolution_metadata: true        # ← all invocations of this profile get the columns
  target_pool: [{ target_ref: "...", kind: PostgreSQLTarget }]

In a test-data request manifest

If the profile does not pin it, the invoker can enable it per-request:

apiVersion: datanivra.io/v1alpha1
kind: TestDataRequest
metadata:
  name: healthcare-with-resolution-pr
spec:
  profile: { name: healthcare-integration, version: 1 }
  purpose_ref: QA-1234
  include_entity_resolution_metadata: true

Validate locally: datanivra test-data validate request.yaml.

What the columns look like

After provisioning, the identity tables in your target environment contain:

 patient_id | first_name | last_name | _dn_entity_resolution_key        | _dn_entity_resolution_sources
------------+------------+-----------+----------------------------------+-------------------------------
 10001      | Synthetic  | Patient-A | dn:erk:3f8a1b2c4d5e6f7a8b9c0d1e | ["ehr","billing"]
 10002      | Synthetic  | Patient-B | dn:erk:7c2d3e4f5a6b7c8d9e0f1a2b | ["ehr"]
 10003      | Synthetic  | Patient-C | dn:erk:1a2b3c4d5e6f7a8b9c0d1e2f | ["ehr","billing","claims"]
  • patient_id, first_name, last_name are masked by your policy exactly as normal.
  • _dn_entity_resolution_key is a pseudonym derived deterministically from the entity's internal identity — the same real patient always produces the same key, in every dataset, as long as the masking key and identity graph are unchanged.
  • _dn_entity_resolution_sources reflects which source systems the entity resolved across.

Privacy and security

The entity resolution key is a pseudonym, not a reversible encoding of any source identifier. It is derived from the internal entity ID using the same masking key that governs the rest of the dataset. Rotating the masking key changes all keys; this is by design and consistent with DataNivra's deterministic pseudonymization guarantees. The key carries no PII and does not expose the original source system record IDs.

The CONTROL_METADATA field classification applies to include_entity_resolution_metadata; it never crosses the customer boundary as raw data.

Certification report

When entity resolution metadata is included, the certification report records:

  • entity_resolution_metadata_included: true on each participating table in ManifestTableFile
  • An EntityResolutionSummary aggregate in the full manifest: total entities resolved, per-source entity counts, tables augmented

These fields are signed as part of the certificate.

← All documentation