OMOP Vocabulary
Category: Data
Node id: omop-vocabulary
Standards: OMOP-CDM-5.4
Resolves OMOP concept_id=0 values using a 3-tier lookup: local crosswalk, in-memory cache, and optional remote vocabulary service
What it does
- 3-tier concept resolution: local crosswalk, in-memory cache, remote vocabulary service
- Batch resolution of concept_id=0 values across all OMOP tables
- Single concept lookup by code and vocabulary system
- Concept ID validation against known vocabularies
- Thread-safe in-memory LRU cache for repeated lookups
- Support for ICD-10, SNOMED, LOINC, RxNorm vocabularies
Use cases
- Resolve unmapped concept IDs after FHIR-to-OMOP conversion
- Look up OMOP standard concept IDs for medical codes
- Validate concept IDs before loading into OMOP CDM
- Enrich OMOP tables with proper vocabulary mappings
Runtime
- Performance tier:
variable
Input ports
| Name | Type | Required | Description |
|---|---|---|---|
omop_tables | json | No | OMOP table map with concept_id fields to resolve (for resolve operation) |
data | json | No | Alternative input: OMOP table map |
input | json | No | Alternative input: OMOP table map |
Output ports
| Name | Type | Required | Description |
|---|---|---|---|
result | json | No | Operation result: resolved omop_tables + resolution_stats (resolve), or concept_id/concept_name/domain_id/vocabulary_id/found (lookup), or valid/concept_name/domain_id (validate) |
success | boolean | No | Whether the operation succeeded |
Settings
Basic
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Operation | operation | enum | Yes | resolve | resolve, lookup, validate | Vocabulary operation |
| Code | code | string | No | Medical code to look up (for lookup operation) | ||
| Vocabulary System | system | string | No | Vocabulary system (e.g., ICD10CM, SNOMED, LOINC, RxNorm) for lookup | ||
| Concept ID | concept_id | number | No | OMOP concept_id to validate (for validate operation) |
Advanced
| Setting | Name | Type | Required | Default | Allowed values | Description |
|---|---|---|---|---|---|---|
| Vocabulary Endpoint | vocabulary_endpoint | string | No | Base URL of the OMOP vocabulary service (tietai-cie10-es-service) for Tier-3 "Maps to" lookups; a failed call fails the node | ||
| Timeout (seconds) | timeout_seconds | number | No | 30 | min 1 | Timeout for each remote vocabulary lookup |
| Remote Concurrency | remote_concurrency | number | No | 8 | min 1; max 32 | resolve: Tier-3 lookups run at once against vocabulary_endpoint (one per distinct vocabulary and code) |
| Remote Total Timeout (seconds) | remote_total_timeout_seconds | number | No | 300 | min 1; max 3600 | resolve: time budget for all Tier-3 lookups; running out of it fails the node |
Errors
| Code | Description |
|---|---|
NO_OMOP_TABLES | No OMOP tables found in inputs |
CODE_SYSTEM_REQUIRED | Code and system required for lookup operation |
CONCEPT_ID_REQUIRED | Non-zero concept_id required for validate operation |
REMOTE_LOOKUP_FAILED | vocabulary_endpoint was unreachable or answered with a non-200 status or a body that is not the OMOP vocabulary response; the node fails |
UNSUPPORTED_OPERATION | Operation not recognized |
Runtime notes
- Resolve operation mutates _concept_id fields in-place on the input OMOP tables and returns the updated tables
- Three-tier lookup order: local crosswalk (ICD10CM/SNOMED/LOINC/RxNorm), in-memory cache, then remote service
- Result shape varies by operation: resolve returns {omop_tables, resolution_stats}; lookup returns {concept_id, found, ...}; validate returns {valid, ...}
- vocabulary_endpoint is optional; without it, only local crosswalk and cache lookups are available
- Tier 3 calls GET {vocabulary_endpoint}/api/v1/omop/vocabulary/{vocabulary}/relationships/{code}?relationship_id=Maps to (tietai-cie10-es-service): exactly one target concept resolves; several are listed under ambiguous and left at 0; none stays unresolved
- Tier-3 lookups run on a pool of remote_concurrency workers, one call per distinct (vocabulary, code), within remote_total_timeout_seconds; the ambiguous list is ordered by vocabulary then code
- Any transport error, non-200 status or non-JSON answer from vocabulary_endpoint fails the node naming the URL and status — it is never counted as unresolved; the first failure cancels the lookups still running
- validate with vocabulary_endpoint calls GET {vocabulary_endpoint}/api/v1/omop/concept/{concept_id}; 404 means invalid
See Build any workflow for how to put nodes together and Ports, types and data flow for how port types connect.
Quelque chose n'est pas clair ? Envoyez vos commentaires sur la documentation par courriel.