cqframework / cqframework/cql-execution
Support Advanced Terminology API
Nobody has claimed this yet.
- Dominant language
- JavaScript
- Stars
- 84
- Forks
- 38
- Avg merge
- 1d 20h
- Merged PRs (30d)
- 1
Description
Currently, the TerminologyProvider (a.k.a. CodeService) API in cql-execution is quite simple:
export interface TerminologyProvider {
findValueSetsByOid: (oid: string) => ValueSet[] | Promise<ValueSet[]>;
findValueSet: (oid: string, version?: string) => ValueSet | Promise<ValueSet> | null;
}
This allows for easy implementation of terminology providers because it pushes most of the terminology operations to the CQL engine itself. The terminology provider need only support simple lookups and return the expanded value set(s). This, however, has performance implications since large value sets must be stored in memory and membership lookup is done by iterating the full set of codes. It also doesn't support other terminology-related operations like subsumption and code system membership.
We should introduce a v2 TerminologyProvider API that allows terminology operations to be implemented by the provider. This would allow for the provider to be backed by a terminology service or a database that can do operations more efficiently. It would also allow for implementation of advanced terminology operations that are not supported by the current engine.
The Java CQL Engine provides a fairly simple TerminologyProvider API (here) that currently supports in (VS membership), expand (VS expansion), and lookup (code display lookup). I think we can borrow some from that, but would suggest that we also cover a bit more ground:
// Notional AdvanceTerminologyProvider... VERY subject to change!
export interface AdvancedTerminologyProvider {
capabilities: () => TerminologyCapabilities;
inValueSet: (code: Code | Code[], valueSet: ValueSetInfo) => Promise<boolean>;
expandValueSet: (valueSet: ValueSetInfo) => Promise<ExpandedValueSet>;
inCodeSystem: (code: Code | Code[], codeSystem: CodeSystemInfo) => Promise<boolean>;
expandCodeSystem: (codeSystem: CodeSystemInfo) => Promise<ExpandedCodeSystem>;
subsumes: (subsuming: Code | Concept, subsumed: Code | Concept) => Promise<boolean>
}
The cql-execution framework can check a terminology provide to see if it has a capabilities function, and if so, inspect its capabilities and then call it as appropriate. If it doesn't have a capabilities function, then it's assumed to be a v1 provider. We should continue to support both.
This design is still very subject to change and there are some open questions:
- Does it make sense for a terminology provider to advertise its capabilities? Or should the engine just always try (and know that sometimes it won't work).
- If a terminology provider can't process one of these requests, should it throw? Or return null?
Contributor guide
No contributing guide indexed for this repository
First steps
- Read the whole issue, then the project's contributing guide.
- Comment on the issue to say you are picking it up — it saves two people doing the same work.
- Fork the repository and make your change on a branch.
- Open a pull request that references the issue number.
Research direction
Start with src/types/cql-code-service.interfaces.ts, especially the existing TerminologyProvider interface, then compare the Java CQL Engine TerminologyProvider linked in the issue. Clarify the v2 operation and capability design, including v1 compatibility and error behavior; the issue is done only when those open questions are resolved and the resulting API is implemented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- typescript
- Domain
- api, backend-api-design
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Stale
- Clarity
- Needs clarification
- Newbie friendliness
- 25/100