cqframework/cql-translation-service

CQL to ELM 转换服务

镜像概述

CQL to ELM 转换服务是CQL到ELM转换库和CQL格式化器的微服务包装器，提供HTTP接口实现CQL（临床质量语言）到ELM（表达逻辑模型）的转换，以及CQL代码的格式化功能。该服务支持单文件和多文件处理，可通过Docker容器化部署，适用于***健康领域临床质量规则的处理和标准化。

版本对应关系

2.0.0版本起，CQL转换服务采用语义化版本，与底层CQL工具版本独立。以下是服务版本与CQL工具版本的对应关系：

核心功能与特性

• CQL到ELM转换：支持将CQL库转换为ELM JSON或XML格式
• CQL格式化：优化CQL代码格式，提升可读性和一致性
• 多文件处理：支持multipart/form-data格式提交多个CQL库，批量处理
• 可配置转换选项：通过查询参数控制转换行为，如注释、定位信息、结果类型等
• 容器化部署：提供Docker镜像，支持快速部署和扩展

使用场景

• ***信息系统中临床质量规则的解析与处理
• CQL代码的标准化格式化与验证
• 临床决策支持系统（CDSS）的规则转换与集成
• ***数据质量评估与报告生成

详细使用方法

翻译端点（/cql/translator）

处理CQL到ELM JSON/XML的转换，支持单文件和多文件请求。

简单转换请求

请求示例：

http
POST /cql/translator HTTP/1.1
Content-Type: application/cql
Accept: application/elm+json
Host: localhost:8080
Content-Length: 610

library CMS146 version '2'

using QUICK

valueset "Acute Pharyngitis": '2.16.840.1.113883.3.464.1003.102.12.1011'
...

响应示例：

http
HTTP/1.1 200 OK
Content-Type: application/elm+json
Date: Wed, 10 Feb 2016 22:15:33 GMT
Content-Length: 6932

{
  "library": {
    "identifier": {
      "id": "CMS146",
      "version": "2"
    },
    "usings": {"def": [
      {
        "localIdentifier": "System",
        "uri": "urn:hl7-org:elm-types:r1"
      },
      {
        "localId": "1",
        "localIdentifier": "QUICK",
        "uri": "http://hl7.org/fhir"
      }
    ]},
    "valueSets": {"def": [{
      "localId": "2",
      "name": "Acute Pharyngitis",
      "id": "2.16.840.1.113883.3.464.1003.102.12.1011",
      "accessLevel": "Public"
    },...]},
    ...
  }
}

多部分转换请求

支持提交多个CQL库（multipart/form-data格式），返回对应ELM结果。

请求示例：

http
POST /cql/translator HTTP/1.1
Content-Type: multipart/form-data; boundary=----WebKitFormBoundary7MA4YWxkTrZu0gW
Accept: multipart/form-data
Host: localhost:8080
content-length: 545

------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="HelloWorld"

library HelloWorld version '1.0.0'

using QDM

include Speaker version '1.0.0' called Speaker

define Hello: 'World'

define SpeakerName: Speaker.Name
------WebKitFormBoundary7MA4YWxkTrZu0gW
Content-Disposition: form-data; name="Speaker"

library Speaker version '1.0.0'

using QDM

define Name: 'Bob'
------WebKitFormBoundary7MA4YWxkTrZu0gW--

响应：返回包含多个ELM部分的multipart/form-data，每个部分对应一个输入CQL库。

转换选项

通过查询参数控制转换行为，适用于简单请求和多部分请求：

使用示例：

POST http://localhost:8080/cql/translator?annotations=true&result-types=true

注意：

• 2.0.0版本后，annotations默认值从true改为false，与CQL-to-ELM控制台客户端保持一致
• 不再支持通过multipart表单字段disablePromotion禁用列表提升，需使用disable-list-promotion查询参数

格式化端点（/cql/formatter）

处理CQL代码格式化，提升可读性，支持单文件和多文件请求。

简单格式化请求

请求示例：

http
POST /cql/formatter HTTP/1.1
Content-Type: application/cql
Accept: application/cql
Host: localhost:8080
Content-Length: 50

library HelloWorld using QDM define Hello: 'World'

响应示例：

http
HTTP/1.1 200 OK
Content-Type: application/cql
Content-Length: 59

library HelloWorld

using QDM

define Hello:
  'World'

多部分格式化请求

支持提交多个CQL库（multipart/form-data格式），返回格式化后的CQL代码。

请求示例：

http
POST /cql/formatter HTTP/1.1
Host: localhost:8080
Content-Type: multipart/form-data; boundary=X-INSOMNIA-BOUNDARY
Accept: multipart/form-data
Content-Length: 465

--X-INSOMNIA-BOUNDARY
Content-Disposition: form-data; name="Simple.cql"
library "SimpleLibrary" version '0.0.1' using FHIR version '4.0.1'
include "FHIRHelpers" version '4.0.1' called FHIRHelpers
context Patient define "MeaningOfLife": 42
--X-INSOMNIA-BOUNDARY
Content-Disposition: form-data; name="FHIRHelpers.cql"
library FHIRHelpers version '4.0.1' using FHIR version '4.0.1'
context Patient define "IsFakeFHIRHelpers": true
--X-INSOMNIA-BOUNDARY--

响应：返回包含多个格式化后CQL部分的multipart/form-data。

Docker部署

运行预构建镜像

bash
docker run -d -p 8080:8080 --restart unless-stopped cqframework/cql-translation-service:latest

无需额外环境变量或配置，服务默认监听8080端口

构建自定义镜像

单架构构建

bash
docker build -t [你的仓库]/cql-translation-service:latest .

多架构构建（如Intel和Mac M1）

bash
docker buildx build --platform linux/amd64,linux/arm64 -t [你的仓库]/cql-translation-service:latest . --push

注意：Docker不支持本地加载多平台构建，需配合--push参数推送到镜像仓库

环境变量

• CQL_TRANSLATOR_PORT：设置服务运行端口，默认值为8080

许可证

Copyright 2016-2023 The MITRE Corporation

基于Apache License 2.0许可。您可以在[***]"原样"分发，不提供任何明示或暗示的保证或条件。有关许可下权限和限制的具体语言，请参见许可。