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.
Etwas unklar? Senden Sie Feedback zur Dokumentation per E-Mail..