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:
| Column | Type | Meaning |
|---|---|---|
_dn_entity_resolution_key | text | A 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_sources | text | A 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 case | Why entity resolution metadata helps |
|---|---|
| Testing cross-system join logic | Your 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 services | Feed 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 completeness | Confirm 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: trueValidate 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_nameare masked by your policy exactly as normal._dn_entity_resolution_keyis 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_sourcesreflects 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: trueon each participating table inManifestTableFile- An
EntityResolutionSummaryaggregate in the full manifest: total entities resolved, per-source entity counts, tables augmented
These fields are signed as part of the certificate.
Related
- Test-data profiles and manifests — configure the
identity_graphpolicy reference and pininclude_entity_resolution_metadatain a profile - Test Data API overview
- Entity resolution example — a complete worked example in the datanivra-examples repository