How to Do an OMOP Standard Concept Lookup the Right Way
David Thompson, PhD
A standard concept lookup in OMOP is a controlled three-step translation, find the source concept, follow Maps to, then verify standard_concept = 'S'. When a clinician asks why the Pneumonia row disappeared from a cohort, the answer is usually that the source code never resolved to a standard concept in the first place.
That failure shows up fast in ETL and slowly in analytics. A code can look familiar, even “right,” and still land in the wrong place if the lookup skips vocabulary context, domain checks, or the standard concept flag.
Why OMOP Standard Concept Lookup Matters
A broken lookup doesn't just lose one row, it weakens every downstream query that depends on that row being comparable across sites. In OMOP, the analytics layer runs on standard concept_id values, not on raw source strings, so a missed translation means the event can't participate cleanly in cohort definitions, phenotype libraries, or network studies.
The schema tells you what the pipeline is doing
The core mental model is simple once you stop thinking of lookup as search. CONCEPT stores the vocabulary entry, CONCEPT_RELATIONSHIP stores the directed mapping, and CONCEPT_ANCESTOR stores the hierarchy for expansion. The OMOP CDM documentation spells out the fields that matter here, especially concept_id as the stable internal identifier, concept_code and vocabulary_id as the source-code pair, domain_id for target routing, and standard_concept where S marks the standard record. OHDSI CDM concept table documentation
The useful habit is to treat lookup as a controlled translation, not a free-text search. If the source code is already standard, the source and target can be the same record. If it isn't, the pipeline needs to preserve the original source value and map the analytic field to the standard concept, or to concept_id = 0, the deliberate “No matching concept” destination.
Practical rule: never overwrite the source just because you found a standard concept. Keep the original source code beside the mapped value so you can re-map when vocabularies shift.
The three-step translation is the part worth memorizing
The OHDSI vocabulary tutorial shows the exact flow with ICD-9 code 427.31, where the source concept is found first, then traversed through Maps to, then checked as a standard concept. That sequence is what keeps ETL deterministic when a code appears in one system but needs to land in another. The same tutorial also shows why vocabulary context matters, because the lookup is about the concept record, not the string alone. All of Us guidance on exploring OMOP concepts with SQL
The strongest shortcut is to remember the boundary between source and standard. A source code can be recognized by OMOP, mapped by OMOP, and still not be allowed into standard analytic fields unless it resolves to standard_concept = 'S'.
When the mapping is missing, forcing a broader ancestor is usually the wrong move. That hides uncertainty instead of surfacing it, and it makes later comparisons look cleaner than they really are.
Search Strategies That Actually Find Standard Concepts
Exact lookup is the default when you already know the coding system. If you have an ICD-10-CM, LOINC, RxNorm, HCPCS, or NDC code, start with the code plus vocabulary_id and keep the search deterministic. That's the cleanest path for ETL rows that arrive with structured codes, because it avoids the noise that comes from label search.
Match the lookup style to the input quality
Human-typed labels need a different approach. Constrained keyword search against concept_name works well when someone types “heart rate” or “metformin 500 mg,” but only if you narrow the vocabulary and domain so you don't pull plausible junk from the wrong terminology. Fuzzy and autocomplete search are useful when the input is messy, abbreviated, or copied from a user interface field with inconsistent formatting.
Semantic search belongs later in the decision order. Use it when the input comes from clinical notes, voice transcripts, or generated labels where the canonical wording doesn't match the source wording. That's where embedding-based retrieval earns its keep, but it also needs tighter review because similarity isn't the same as mapping correctness. OMOPHub keyword search vs semantic search
The formatting traps are boring, and they're still the ones that cause silent misses. Strip dots from ICD codes when the vocabulary expects the normalized form, normalize whitespace in long lab names, keep casing consistent in drug strings, and don't confuse an NDC package code with a product code.
If a lookup only works after you manually “fix” the code, the pipeline should own that normalization step, not the analyst.
| Input Type | Recommended Strategy | Why |
|---|---|---|
| Known structured code | Exact lookup with vocabulary context | Fast, deterministic, lowest review burden |
| Human-typed label | Constrained keyword search | Good balance of recall and precision |
| Typos or partial text | Fuzzy or autocomplete search | Recovers near-matches without manual cleanup |
| Noise, abbreviations, note text | Semantic search | Handles phrasing that doesn't mirror the canonical term |
The main trade-off is precision versus convenience. Exact lookup keeps the result set small and predictable, while semantic search broadens recall and pushes more validation work to the reviewer.
Walking Relationships and Expanding Concept Sets
Once the standard concept is in hand, the next job is usually expansion. A single concept rarely captures the clinical intent of an analysis, so the hierarchy table becomes the practical tool for building concept sets, especially for conditions and drugs where the hierarchy is strongest.
Use ancestor and descendant traversal for controlled breadth
CONCEPT_ANCESTOR gives you the parent-child structure without writing recursive SQL every time. If you start with a SNOMED disorder, you can walk upward to broader clinical categories or downward to more specific descendants, depending on whether you're trying to summarize, validate, or enrich a phenotype. The key is that the hierarchy is precomputed, so the query stays simple and repeatable.
A SNOMED-style concept set usually starts with a root concept, then pulls in descendants that share the same clinical idea. That's how you capture narrower terms without hand-curating every code, and it's why conditions and drugs behave more reliably than some other domains when you expand sets by hierarchy.
The caution is simple. Hierarchy-based expansion is powerful only when the underlying vocabulary has a clean hierarchy worth trusting. If the domain is partial or the concept family is loose, the set can look complete while still missing clinically relevant entries.
Production tools should materialize sets, not just eyeball them
FHIR $expand is the cleanest way to materialize a ValueSet when you already know the code and want the descendants collected in one output. For release comparison, $diff is the better tool because it shows what changed between vocabulary versions, which matters when ancestors shift or labels change after an ATHENA update. OMOPHub concept hierarchy API
Use batch expansion for jobs, not single-code expansion for every row. ETL workloads get much cleaner when you resolve in bulk and reserve one-off calls for debugging, phenotype review, or point-of-care translation.
REST, FHIR, and SDK Walkthroughs You Can Copy
A clean lookup pipeline keeps the same terminology decision available to ETL jobs, FHIR services, and notebook work. One REST surface can handle structured concept lookup, while the FHIR layer can resolve a source code into a standard concept and the right target table in the same call path.
REST and FHIR calls
A practical REST-first pattern is to query the vocabulary API for the concept, then let the server handle the mapping work. For FHIR-integrated workflows, a resolver can accept a system URI plus code and return the standard concept, domain, mapping type, and CDM target table together.
curl -X POST "https://api.omophub.com/v1/fhir/resolve" \
-H "Authorization: Bearer oh_your_api_key" \
-H "Content-Type: application/json" \
-d '{"system":"http://snomed.info/sct","code":"44054006","resource_type":"Condition"}'
That call pattern matches the actual translation flow. The code is identified first, then mapped, then routed to the correct domain. The FHIR terminology surface on https://fhir.omophub.com/fhir/r4 also supports $lookup, $validate-code, $translate, $expand, $subsumes, $find-matches, $closure, and $diff on the same endpoint, with R4, R4B, R5, and R6 available through the path prefix.
SDKs and agent tooling
Python, R, and TypeScript wrappers are most useful when the same mapping behavior has to work in notebooks, pipelines, and service code. The pattern stays the same across all three, call lookup with the code plus vocabulary context, traverse Maps to when needed, and batch requests when you can instead of resolving one code at a time.
The MCP Server matters when an LLM is in the loop. It gives agent tooling a vocabulary-backed source of truth instead of letting a model guess at codes or labels. That belongs after the system decision has already been made, because terminology should be resolved from managed vocabulary, not invented by the model.
| Endpoint or SDK action | Replaces in OMOP terms | Best use |
|---|---|---|
| REST concept lookup | Manual CONCEPT querying | Ad hoc search and debugging |
| FHIR resolve | CONCEPT plus CONCEPT_RELATIONSHIP traversal | Point-of-care or FHIR-aware systems |
FHIR $expand | Hierarchy-driven CONCEPT_ANCESTOR expansion | Concept set materialization |
| Batch lookup | Repeated single-row translation | ETL and nightly loads |
| SDK calls | Handwritten SQL and glue code | Repeatable application logic |
A managed vocabulary service is one of the few places where convenience and control can line up. For teams that want a single backend for API, FHIR, and SDK access, OMOPHub vocabulary SDK exposes that shared vocabulary layer without requiring everyone to stand up the same database locally.
Mapping the API to the SQL Workflow You Already Know
Legacy OMOP SQL still matters because it's the clearest way to see what the API is doing under the hood. The classic pattern is a join from CONCEPT to CONCEPT_RELATIONSHIP on Maps to, then a check that the target row is standard. The API just moves that controlled translation server-side so you don't have to write the join every time.
The SQL mental model stays the same
FHIR-first teams can line up the operations directly. $lookup corresponds to finding the concept row, $translate lines up with traversing CONCEPT_RELATIONSHIP, and $expand maps to hierarchy expansion through CONCEPT_ANCESTOR. That means you can adopt a terminology service without learning every CDM table upfront.
The production rule is to develop against the managed service, then cache locally for offline ETL where that makes sense. If a cache miss happens, or a newer vocabulary release introduces concepts you haven't seen yet, the managed API becomes the fallback rather than the exception.
Cache the answer, not the assumption. Vocabularies change often enough that the re-validation step needs to stay alive.
The value in this hybrid approach is operational, not theoretical. You get the convenience of a shared backend and still keep room for local persistence, auditability, or air-gapped production needs.
Use the same backend from SQL, Python, and R
The backend doesn't care whether the request came from a warehouse job, a notebook, or a service. What matters is that the code, vocabulary, and domain are explicit enough to make the translation deterministic and the target table obvious.
That's where the API beats ad hoc scripts. The same lookup logic can be reused by engineers, researchers, and product teams without each group rebuilding the vocabulary layer from scratch.
Real-World ETL and NLP Mapping Patterns
A nightly ETL load is the easiest place to see the workflow done properly. The source system sends diagnoses with dots, local formatting, and mixed vocabulary history, so the job normalizes the ICD-10-CM code, resolves it in batch, follows Maps to, checks the domain_id, and writes both the original source value and the resolved standard concept side by side.
ETL behaves best when the code path is deterministic
For diagnoses, the target usually lands in CONDITION_OCCURRENCE when the mapped concept is a condition. For drug rows, the same logic routes to DRUG_EXPOSURE after the source code has been normalized and mapped to the right standard drug concept. The important part is that the source value stays visible, because later re-mapping is easier when the original code wasn't thrown away.
NLP pipelines follow a looser path, but the same tiered decision order still holds. Extracted mentions like “type 2 diabetes” or “metformin 500 mg” should first try constrained semantic search, then validate the top candidate by checking standard_concept = 'S' and the right domain, then move to curator review if confidence stays weak.
The strongest operational habit is not to pretend every hit is equal. A code that arrives from a system of record deserves a different treatment than a label extracted from a note, and your pipeline should make that difference explicit.
Two scenarios, one decision order
- Known code first: resolve the source code with vocabulary context before you try anything fuzzy.
- Mapped source second: follow Maps to when the source concept is non-standard.
- Semantic review third: use ranking when the input is noisy, abbreviated, or note-derived.
- Curator review last: escalate only when the pipeline can't justify a standard concept confidently.
That decision order keeps the cheap cases cheap and the hard cases visible. It also prevents teams from hiding ambiguity behind a broad ancestor or a plausible label match.
Tips, Versioning, and FAQ
Week-two mistakes usually come from assumptions, not syntax. Filter by vocabulary_id early, check domain_id before reusing a concept in another path, keep unmapped source values as concept_id = 0 instead of guessing, and pin vocabulary versions so the mapping is traceable to a specific release.
Versioning should be part of the lookup contract
The OMOP vocabulary model includes validity dates on CONCEPT, so deprecation is not just a label change. When a vocabulary release changes, re-validate phenotypes and routing rules, especially if ancestor relationships shifted or a standard concept was replaced. The $diff operation is the cleanest way to inspect those changes before they reach production logic.
That version control also matters in ETL. If you cache results locally, keep the mapping lineage attached to each cached answer, because a lookup without the original source code is hard to justify later during review or remediation.
FAQ
How do I handle a source code with no standard mapping?
Keep the source value, set the analytic side to concept_id = 0 if there is no valid mapping, and do not force a broader concept just to make the row look complete. That keeps the unmapped case visible instead of distorting it.
How do I tell a standard from a non-standard concept in one field?
Check standard_concept. In OMOP, S marks the standard concept, while non-standard source concepts will not be marked that way even if they are fully recognized in the vocabulary.
Should I filter by domain before or after Maps to?
Check the source context first, then validate the target's domain_id after mapping. That keeps the source lookup deterministic and stops a plausible concept from landing in the wrong analytic table.
Is a managed vocabulary API good for production ETL or only prototyping?
It can work for both, as long as the pipeline keeps caching, audit, and versioning under control. The managed route is useful when you want the same vocabulary behavior in ETL, FHIR, and application code without rebuilding the lookup stack every time.
If you are mapping source codes into OMOP and do not want to keep recreating the same vocabulary plumbing, use OMOPHub. It provides a shared API, FHIR terminology access, and SDKs for the lookup, translation, and expansion steps that make OMOP standard concept lookup practical in production.
