--- cuppy_hub: aws cuppy_path: examples/healthcare-master-data/02-identity-resolution-and-survivorship.md cuppy_section: docs cuppy_doc: WS0W-HVNJ cuppy_doc_uuid: 702782e2-481e-49f6-8685-f0f4c75f1687 cuppy_permalink: https://cuppy.io/aws/d/WS0W-HVNJ cuppy_version: 1 cuppy_updated: 2026-10-23T16:16:52.575Z cuppy_canonical: https://cuppy.io/aws/docs/examples/healthcare-master-data/02-identity-resolution-and-survivorship cuppy_mcp: https://cuppy.io/mcp cuppy_body_sha256: 68b70b434f351e933e9a1b5388fe895bde29054d35c4464603e31d9c2eee2c9a # cuppy_body_sha256 is over the document body ALONE, excluding both generated blocks. --- # Identity resolution and survivorship without an MDM licence This is the load-bearing document of the set. Identity resolution is the part of master data management that AWS sells as a service, and survivorship is the part it does not. Knowing exactly where the line falls is the difference between a sound design and a sales pitch. Everything attributed to AWS below is quoted from the pages listed in `provenance`, each read on 2026-10-21. Where that documentation is silent, this document records the silence rather than filling it. ## Two matching engines, and both of them link rather than merge AWS offers two managed matching capabilities relevant to a healthcare master. They solve different halves of the problem and neither produces a golden record. | Capability | Where it runs | Matching basis | Output | | --- | --- | --- | --- | | AWS Entity Resolution | Glue tables on S3 | Exact rules, or a preset ML model | Match groups with a match ID | | HealthLake resource matching | In the FHIR store | Healthcare identifiers, deterministic | A FHIR `Linkage` | The AWS Entity Resolution overview describes the service as one that "helps you match, link, and enhance related records stored across multiple applications, channels, and data stores", offering "rule-based matching, machine learning-based matching (ML matching), and data service provider-led matching". HealthLake's resource matching page is even more direct about its scope, and the sentence is worth memorising because it is AWS describing this exact use case: > "Resource matching identifies FHIR resources in a HealthLake data store that represent the same > real-world entity and links them without modifying or merging the original resources. When > aggregating data from multiple systems, resource matching connects the same entity written as > several separate resources so you can build an accurate, unified view without operating a master > data management system." Read the verb. It links. The same page states that "Resource matching is non-destructive: when it finds a match, it creates a FHIR `Linkage` resource that points to the linked resources and leaves the originals unchanged." ## What AWS Entity Resolution rule-based matching really is The glossary is unambiguous, and this is the point most often over-claimed: > "Rule-based matching is process designed to find exact matches. Rule-based matching is a > hierarchical set of waterfall matching rules ... All match keys provided within rule criteria must > match exactly for compared data to be declared a match." Exact, on normalised values. The service does normalise first — the overview says it removes "special characters and extra spaces, and formatting text to lowercase" by default, and the glossary gives the per-type rules, including an address rename map that turns `avenue` into `ave` and `street` into `st`. That normalisation absorbs formatting noise. It does not absorb a transposed digit in a date of birth, a nickname, or a misspelt surname. Approximate matching lives only in the ML option, and its field coverage is stated explicitly: the preset model "uses all input fields associated with name, email address, phone number, address, and date of birth data types", producing match groups each with "an associated confidence score of 0.0-1.0". Note what is not in that list: no medical record number, no member identifier, no NPI. Those columns can still be used as exact match keys in a rule, but they are not inputs to the probabilistic model. The attribute types the glossary offers as examples are "Name, Address, Phone number, or Email address", and normalisation "is only supported the group type for Name, Address, Phone, and Email". The consequence for a healthcare design is specific. Rule-based matching is the primary path for patient and provider identity because healthcare matching leans on scoped identifiers. ML matching is a useful second pass for demographic-only duplicates, and it is a consumer-oriented model applied to a clinical population — a limitation to state out loud rather than discover in production. Two further mechanics are worth holding. Rule order matters, because the default is a waterfall: "records matched at a higher rule level are excluded from subsequent rules", and the docs advise you "order your rules to find more precise matches first". Transitive matching is an opt-in alternative for Advanced rules under which "all records are processed across all rule levels". And every input row must carry a customer-supplied `Unique ID` — "a unique identifier that you designate and that must be assigned to each row of input data" — unique within a table, with a maximum length of 38 characters for a matching workflow. ## What HealthLake resource matching really is Deterministic, identifier-driven, and it tells you so: > "Resource matching links resources based on the healthcare identifiers present in your data. It > does not perform probabilistic or demographic fuzzy matching on names, dates of birth, or > addresses." The identifier model is genuinely well designed for this domain. Globally unique identifiers such as an NPI or SSN "are matched on value". Scoped identifiers such as an MRN "are only unique within a namespace" and are "matched on the combination of the identifying system and value, so that MRN `456` at one hospital is never linked to MRN `456` at another". It also reconciles identifier system URIs, treating an SSN under `http://hl7.org/fhir/sid/us-ssn` and under `urn:oid:2.16.840.1.113883.4.1` as the same identifier. The documented limits matter as much as the features: - "Resource matching does not apply priority ordering or conflict resolution between identifiers: any shared, non-placeholder identifier is enough to link two resources." - "Resource matching evaluates resources of the same type against one another ... It does not link resources of different types." - "A resource sharing an identifier with more than 100 other resources may not be matched against all of them." - "Resource matching is available as a preview capability and is subject to change." That last one is a compliance fact, not a roadmap note. See `04-security-and-hipaa.md`: the eligible services page extends eligibility to *generally available* features, so Preview status is an open question for PHI that must be settled with AWS rather than assumed. The two engines are complementary rather than redundant. HealthLake catches the no-doubt case where two systems carry the same MRN under the same assigning authority. Entity Resolution catches the hard case where a patient registered twice with no shared identifier at all. A design runs both and reconciles them, once the Preview question in `04-security-and-hipaa.md` is settled. ``` source systems landing + curation matching master --------------- ------------------ -------- ------ EHR ADT/HL7 ---\ +-------------------+ registration ----+--> S3 raw (immutable) --> Glue |AWS Entity | claims / payer ---/ | |Resolution |--> match groups provider roster --/ v |rules, then ML | (S3, match IDs) CRM / portal ----/ Glue Data Quality +-------------------+ | | v v +-------------------+ CUSTOM: survivorship, S3 curated ----------------->|HealthLake | crosswalk, trust rules FHIR-shaped |resource matching | | | |-> Linkage (preview)| v +---------------------->+-------------------+ golden record store (Aurora PostgreSQL) ``` ## Where the custom code begins Both engines hand you an assertion that two records refer to one entity. Everything a steward and a downstream consumer actually needs is on your side of the line. The cited pages contain no mention of golden records, survivorship, trust scores, merge rules, hierarchies or stewardship for either service. Asked directly, the Entity Resolution overview yielded no such statement. What you must build: 1. **Survivorship.** Choosing, attribute by attribute, which source wins — most recent, most trusted source, longest non-null, clinically validated. No AWS service cited here expresses per-attribute precedence. This is a rules table plus a deterministic evaluator. 2. **The golden record itself.** A durable, versioned, queryable master row per entity, with provenance per attribute. Aurora PostgreSQL is the natural home; the match output is a file in S3, not a record store. 3. **The crosswalk and a stable master identifier.** This is the sharpest gap. The glossary defines a match ID only as "the ID generated by AWS Entity Resolution and applied to each matched record set ... part of the matching workflow metadata that will be included in output". No page read today states that the match ID for a given real-world entity is identical across separate bulk runs. The one sentence about a match ID being "fixed upon its first match" is scoped to transitive matching within a run. Treat the enterprise identifier as yours: mint it, store it, and map match IDs to it on every run. Do not let an interviewer hear you assume AWS keeps it stable for you. 4. **Merge, unmerge and steward override.** A match is a suggestion. Clinicians reverse them. You need a decision store that survives reprocessing, so that a human "these are not the same patient" verdict is replayed as an override on the next run rather than silently re-merged. 5. **Reconciling the two engines.** A HealthLake `Linkage` and an Entity Resolution match group can disagree. Which wins, and who sees the conflict, is a policy you write. 6. **Hierarchies and affiliations.** Provider-to-organisation, organisation-to-parent, provider-to-location. FHIR offers representations, but `Organization.partOf` carries one parent and no dates, and HealthLake matching "does not link resources of different types". Dated, multi-dimensional relationship management is yours. ## Throughput and scale limits to quote accurately From the Entity Resolution quotas page, read 2026-10-21: | Quota | Default | Adjustable | | --- | --- | --- | | Concurrent matching jobs | 1 per Region | No | | Concurrent ID mapping jobs | 1 per Region | No | | Records per rule-based matching workflow | 100,000,000 | Yes | | Records per ML matching workflow | 600,000,000 in nine Regions | Yes | | Records per ML matching workflow | 150,000,000 in three Regions | Yes | | Matching workflows | 10 per Region | Yes | | Schema mappings | 50 per Region | Yes | | `GetMatchId` request rate | 50 per second | Yes | | `GenerateMatchId` request rate | 10 per second | Yes | The three smaller ML Regions are `af-south-1`, `ap-northeast-2` and `eu-west-2`. The nine larger ones include `us-east-1`, `us-east-2` and `us-west-2`. The first row is the operative constraint. One concurrent matching job per Region, marked not adjustable, means patient, provider, organisation and location workflows cannot run in parallel in a single account and Region. Serialise them with Step Functions, or separate them across accounts or Regions. The overview also states a maximum of 20 data inputs. Cadence differs by technique. Automatic incremental processing exists "for rule-based matching scenarios ... as soon as new data is available in your Amazon S3 bucket", and the glossary confirms automatic processing "is available for rule-based matching only". So event-triggered incremental matching is a rule-based capability. The glossary separately defines a `RecordConfidenceLevel` "for ML incremental matching", so some incremental ML path appears to exist, but the cited pages do not characterise how it is invoked. `07-cost-model.md` therefore models ML runs as full reprocessing and labels that a conservative assumption rather than a documented limit. ## Near-real-time matching: two different operations These are easy to conflate and the distinction matters for any synchronous registration or ADT path. `GetMatchId` "helps you synchronously retrieve an existing match ID"; the service "hashes those attributes for data protection and retrieves the corresponding match ID". It is a retrieval against already-matched results, defaulting to 50 requests per second. `GenerateMatchId` is the on-demand matcher. Its API reference states it "Generates or retrieves Match IDs for records using a rule-based matching workflow ... it processes your records against the workflow's matching rules to identify potential matches. For existing records, it retrieves their Match IDs and associated rules. For records without matches, it generates new Match IDs. The operation saves results to Amazon S3." Three constraints come with it. It is rule-based only and the workflow "must exist and be active". The `records` array takes a "Fixed number of 1 item", so it is one record per call, with a default rate of 10 requests per second. And "Additional charges apply for each API call". Its `processingType` is a genuine latency-versus-accuracy control worth knowing by name: | Mode | Documented behaviour | | --- | --- | | `CONSISTENT` | Immediate lookup and matching against all existing records, saved synchronously | | `EVENTUAL` | Immediate lookup or generation; record updates processed asynchronously | | `EVENTUAL_NO_LOOKUP` | Generates new match IDs without checking existing matches | `CONSISTENT` is the default and "provides highest accuracy but slower response time". `EVENTUAL_NO_LOOKUP` "should only be used for records known to be unique" — which is rarely true of a patient registration, so it is the wrong default for this domain. Advanced matching workflows do not support the field at all. ## One honest compliance nuance The Entity Resolution compliance validation page in its own user guide names PCI DSS and SOC 1/2/3 and does not mention HIPAA at all. The service's HIPAA eligibility comes from the HIPAA eligible services reference, where it is listed without a bracketed exclusion. Cite the eligibility list, not the service's compliance page, and know the difference if pressed. --- You are reading one file. The same content is free over MCP at https://cuppy.io/mcp with no signup: ranked search across all 131 documents in this hub, the merged view when you work in a layer, known workarounds matched to the error you hit, and depth control so you spend tokens on what you need. Start with the `_hello` tool. How to connect: https://cuppy.io/aws/ Something wrong in this document? Report it with the `session feedback` tool on the same endpoint.