工作组: FHIR Infrastructure 成熟度: Normative标准状态: Normative

对资源进行搜索是FHIR机制的基础。搜索操作通过提供的参数过滤现有的一组资源。 下面由浅入深的对FHIR搜索框架进行介绍。实施者可根据实际需求的复杂程度来选择实现的内容。

搜索参数类型适用于所有资源的参数作用于搜索结果的参数
数字(Number)
日期与时间(Date/DateTime)
字符串(String)
令牌(Token)
引用(Reference)
组合(Composite)
数量(Quantity)
统一资源标识(URI)
专业(Special)
_id
_lastUpdated
_tag
_profile
_security
_text
_content
_list
_has
_type
_sort
_count
_include
_revinclude
_summary
_total
_elements
_contained
_containedType

除上表外,所有的其它参数请参见完整的搜索参数清单,其中以下几个通用参数比较特殊:

请注意,搜索参数名称区分大小写,虽然此规范中没有名称相同但大小写不同的参数。 客户端应该使用正确的大小写,服务器不能额外定义名称相同但大小写不同的参数。

实施者应该始终将搜索的安全问题牢记在心。

提交语法

在最简单的情况下,搜索是在RESTful框架中执行GET动作来完成的:

 GET [基地址]/[资源类型]?[参数名1]=[参数值]&[参数名2]=[参数值]&...{&_format=[媒体类型]}

或者通过POST动作来完成:

 POST [基地址]/[资源类型]/_search?{[参数名1]=[参数值]&[参数名2]=[参数值]&...{&_format=[媒体类型]}}

上述语法中的中括号是需要整体替换的内容,大括号是可选内容。

第一行命令的语法是通过GET动作实现的,它将参数以“?[参数名]=[参数值]”的明码形式直接输入在URL地址中。

第二行命令的语法是通过POST动作实现的,它的参数可以在_search参数后直接输入到URL地址中(大括号中的可选内容), 也可以输入到格式为URL编码的Body消息体中提交(HEAD头的Content-Type设置为“application/x-www-form-urlencoded” )。 当同时在URL地址中和Body消息体中输入了参数时,所有参数是以“并且”的关系同时生效。

对于GET和POST的详细信息请参见:FHIR RESTful API中的定义搜索

返回结果

服务器将符合条件的资源以bundle资源包的形式返回到HTTP的响应中,资源包中的资源即搜索结果。 注意,_format参数的值为媒体类型,它适用于搜索和其他交互。

搜索操作 在三个定义的上下文的其中之一上执行,这些上下文控制了被搜索的资源集:

  • 指定的资源类源: GET [基地址]/[资源类型]?参数(多个)
  • 指定的 逻辑区块 , 可能在该逻辑区块中指定了资源类型: GET [基地址]/[逻辑区块]/[id]/[资源类型]?参数(多个)
  • 所有资源类型: GET [基地址]?参数(多个) (所有类型通用的参数)。 如果包含_type参数,则所有其他搜索参数必须对所有指定的类型通用。 如果不包含_type参数,则所有参数必须对所有资源类型都通用。

搜索操作也可以在 消息框架中实现。

哪些资源符合搜索参数(下面将逐一描述)中包含的条件是由服务器确定的。服务器有权返回额外的相关搜索结果。 注意:有一个相关性最强的特殊搜索:患者主索引(MPI)搜索,在其上下文中的搜索集是不确定的。

使用GET搜索可能会在搜索参数中包含敏感信息。因此,建议使用安全通信和终结点管理,详请参阅 安全通信

所有搜索操作的响应始终是一系列包含在资源捆束包中的资源。另一种方法是使用GraphQL

如果服务器无法执行搜索请求,则可能返回错误。HTTP状态码403 表示服务器拒绝执行搜索,而其他4xx5xx 状态码表示发生了某种错误。当搜索失败时,服务器应该 返回一个详细描述失败原因的操作结果资源 。注意:搜索返回的空结果不是失败。

在某些情况下,参数可能会导致错误,或者可能无法匹配上任何内容。例如:

  • 参数可能指向不存在的资源,例如:
      GET [基地址]/Observation?subject=101 , 不存在 "101" 的目标。
      GET [基地址]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456 ,没有MRN号码为123456的患者
  • 参数可能指向不存在的编码,例如: GET [基地址]/Observation?code=loinc|1234-1 , 服务器不能识别值为"1234-1" 的LOINC编码
  • 参数指定的时间可能超出范围,例如: GET [基地址]/Condition?onset=le1995 ,查询小于等于1995年的病症与诊断资源,但系统只能追溯刚才2001年的数据
  • 参数可能使用非法或不支持的修饰符,例如: GET [基地址]/Condition?onset:text=1995 ,服务器不能处理此修饰符
  • 日期时间参数的格式可能不正确,例如: GET [基地址]/Condition?onset=23%20May%202009
  • 使用未知或不支持的参数 (详见下)

注意:传入空参数不会出错误-它们只是被服务器忽略。

如果参数的内容语法有误,服务器 应该 返回一个错误。但如果是逻辑错误(如,未知目标或编码),则服务器 应该 处理搜索请求,包括处理参数,并返回一个空的搜索结果集,因为无法满足参数的请求。

在这种情况下,搜索过程可能在搜索结果集中有一个包含了搜索过程相关提示和警告的 操作结果资源 ,它的OperationOutcome.issues.severity的编码值不能 fatal error 。此操作结果资源将作为资源捆束的一个输出类型条目(Bundle.entry.search.mode=outcome)包含在搜索结果中。 客户端可以使用此信息来改良进一步的搜索。例如,如果客户端执行了以下搜索:

GET [基地址]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456

由于没有MRN号码为123456的患者,服务器会返回一个带有警告的资源捆束

未知或不支持的参数

服务器可能从客户端接收到他们无法识别的参数,或者可能接收到他们识别但不支持的参数(通用参数或特定搜索参数)。 通常,服务器应该忽略未知或不支持的参数,原因如下:

  • 各种HTTP堆栈和代理可能会添加不受客户端控制的参数。
  • 客户端可以通过检查返回中的自包含链接来确定服务器使用的参数(请参见下面的内容)

客户机可以使用prefer头指定服务器的行为方式

  • Prefer: handling=strict: 客户端请求服务器在遇到未知或不支持的参数时返回错误
  • Prefer: handling=lenient: 客户端请求服务器忽略任何未知或不支持的参数

服务器应该满足客户机的请求,但这不是强制要求。

这些参数适用于所有资源: _content, _id , _lastUpdated, _profile, _query, _security , _source, _tag . 除些之外, _text _filter , (详见下) 作为作用于搜索结果的参数,同样适用于所有资源。

搜索参数 _id是指资源的逻辑ID,当搜索语句中指定了资源类型时,可以使用该参数,如:

 GET [基地址]/Patient?_id=23

此搜索将查找具有指定ID的患者资源(指定ID只能有一个资源)。从功能上讲,这相当于一个简单的 Read操作 :

 GET [基地址]/Patient/23

但是,带有参数_id的搜索将返回一个包含所请求资源的资源捆束,而不仅仅是资源本身。 可以通过添加额外的参数,使其在等效于Read操作的基础上提供额外的功能(例如,_include)。 注意,由于服务器应该做到完全匹配,所以_id参数属于令牌数据类型,但是_id参数却没有令牌类型的“system”属性。 请注意, 与_id上的匹配是区分大小写的。

搜索参数_lastUpdated可用于根据最新更改时间获取资源:

 GET [基地址]/Observation?_lastUpdated=gt2010-10-01

此搜索找到自2010年10月1日以来所有变更过的观测资源。 使用此搜索参数时,应用程序应考虑同步方法(RESTful历史记录订阅资源)。

搜索参数_tag,、 _profile _security 搜索meta 元素中的等效元素。例如:

 GET [基地址]/Condition?_tag=http://acme.org/codes|needs-review

搜索带有以下标签的所有Condition资源:

{
  "system" : "http://acme.org/codes",
  "code" : "needs-review"
}

以同样的方式搜索profile定义为"lipid"的DiagnosticReport资源:

 GET [基地址]/DiagnosticReport?_profile=http://hl7.org/fhir/StructureDefinition/lipid
 GET [基地址]/DiagnosticReport?_profile=Profile/lipid

第一个请求是通过定义profile的绝对URL来搜索符合条件的DiagnosticReport资源。第二个请求是通过相对地址搜索与profile定义在同一服务器上的DiagnosticReport资源。

_tag _security 参数是令牌类型(参见 token令牌), 而 _profile引用类型参数

所有的资源都支持_id参数,除此之外,每种资源类型都定义了一系列它们自己的专属搜索参数,包括了参数名、参数类型、参数说明。 本规范中这些搜索参数的文档呈现在其资源介绍页面的底部,并且作为本规范的一部分以能力声明(XMLJSON)的形式发布。

一般情况下,定义的搜索参数是和资源的某个元素一一对应的,但这不是必须的。 一些搜索参数会对应到资源中多条路径的相同类型的元素,或者与继承自元素的值相对应。

资源的某些专属搜索参数不仅只关联到资源的一个路径,这意味着,只要任何一条路径中存在匹配的内容,搜索参数都会命中,并将整个资源作为搜索的返回结果。客户端可能需要进一步处理这个资源才能判断搜索参数是与资源哪条路径中的元素值相匹配的。

服务器必须支持_id参数,但并不强制要求服务器实现其它在3.1.1.4.1节所述“通用搜索参数”。 另外,服务器也可以根据需求自定义搜索参数。

搜索参数的类型决定了其搜索的方式,以下是本规范已定义的参数类型:

number 数字搜索型,搜索参数必须是一个数字(整数或小数)。
date 日期搜索型,搜索参数是一个日期或时间。日期格式是标准XML格式,也可能支持其它格式。
string 字符串搜索型,搜索参数是不区分大小写和重音的简单字符串,并可能支持“以……开始”的局部匹配模式,参数中允许包含空格字符。
token 令牌搜索型,搜索参数是一个编码元素或者是一个标识符。 它既支持对编码类型中的text、display,、code、system元素进行匹配,又支持对标识符类型中的system和key的匹配。 此类型的参数可以使用“后缀修饰符”,根据使用的后缀修饰符,此类型的参数既可以是一个字符串,也可以是“namespace|value”形式的键值对。
reference 引用搜索型,对另一个资源的引用。可以引用资源的实例地址或官方定义地址。
composite 组合搜索型,此类型的搜索将多个目标匹配值合并在一起搜索,即多条件搜索。
quantity 数量搜索型,搜索参数对数量进行搜索,即带数量单位的搜索。
uriURI搜索型, 搜索参数是一个遵循RFC 3986编码规范的URI地址。
special 特殊搜索,此类搜索有着自己特有的搜索逻辑。

搜索参数还可以使用“后缀修饰符”来控制其匹配方式。 搜索参数的类型决定了它可以支持哪些“后缀修饰符”(详见下小节)。

参数在每个资源中分别定义,在参数之后可能会以“:修饰符种类”的形式(即用冒号来分隔参数名和修饰符)添加一个后缀修饰符。 后缀修饰符的名称及其支持的搜索参数类型如下:

  • :missing修饰符,它支持除“组合搜索型”之外的所有类型的搜索参数。 例如, gender:missing=true ,意为:搜索所有带有gender元素的资源类型,返回资源实例中缺失gender元素或未对gender元素赋值的所有资源实例。 反之,gender:missing=false则意为:搜索所有带有gender元素的资源类型,返回已对gender元素赋值的所有资源实例。 For simple data type elements, :missing=true will match on all elements where either the underlying element is omitted or where the element is present with extensions but no @value is specified 当 :missing=true 修饰符作用于资源的元素是简单数据类型时,搜索匹配资源的条件为:资源实例缺失此元素或此元素中仅包含了扩展元素而没有为其赋值(元素缺失@value属性)。
  • :exact 修饰符,它和字符串搜索型的参数配合使用,以支持区分大小写区和支持对“组合字符编码”的搜索。 注意,对 扩展字型簇 extended grapheme clusters (由一组Unicode编码按序列组合后生成的单个人类文字) 的支持由服务器自己决定。即:当搜索参数的值是一串Unicode编码时,服务端系统自行决定搜索是匹配其等效转换后的文字还是匹配Unicode编码中的字符。
  • :contains 修饰符,它也和字符串搜索型的参数配合使用,且不支持区分大小写区和“组合字符编码”的搜索。它用于模糊搜索,只要资源的元素值中有一部分内容和搜索参数值相同,无论是头部相同还是中间部分相同或者是尾部相同,都会命中目标。
  • :text 修饰符,它和令牌搜索型的参数配合使用,用于对CodeableConcept数据类型中的text元素或对Coding数据类型中的display元素的搜索。而不使用此修饰符时搜索的是code元素。
  • :in:below,、:above:not-in 这些修饰符都和令牌搜索型的参数配合使用,具体用法在下文介绍。
  • :[type] 修饰符,其中[type]指的是FHIR的资源类型(如: :Patient ),它和引用搜索型的参数配合使用。
  • :identifier 修饰符,也是和引用搜索型的参数参数配合使用,以支持通过标识符类型的数据(以“system|value”的形式)来匹配引用类型的元素。
  • :below :above 修饰符,它和URI搜索型的参数配合使用。 使用此修饰符后不需要提供URI的完整值进行匹配,只需“左匹配”(使用:above匹配开头部分)或“右匹配”(即使用:below匹配结尾部分)。

如果服务端系统不支持提交的“后缀修饰符”,服务器必须明确拒绝此搜索请求。 例如,如果服务器支持name搜索参数,但不支持与 :exact 修饰符一起使用,则当收到 name:exact=Bill 的搜索请求时, 必须 返回一个HTTP 400错误状态和一个包含 明确错误信息 OperationOutcome资源 来拒绝此请求。

数字搜索型 日期搜索型 数量搜索型 这几种搜索类型的参数值是“可排序、可比较”的。可以在参数之前使用“前缀比较符”来控制匹配的性质(相等、大于、晚于等)。 为了避免URL转义并增强易读性,“前缀比较符”使用以下代码表示:

eq 等于:资源中被匹配的元素值(下简称“目标值”)等于搜索参数提供的值(下简称“搜索值”) 时段在期间内:搜索值的值内范围完全包含目标值的值内范围
ne 不等于:目标值不等于搜索值 时段在期间外:在搜索值的值内范围不完全包含目标值的值内范围
gt 大于:目标值大于搜索值 结束时间晚于,搜索值的值上范围与目标值的值内范围相交(即部分重叠)
lt 小于:目标值小于搜索值 开始时间早于:搜索值的值下范围与目标值的值内范围相交(即部分重叠)
ge 大于等于:目标值大于等于搜索值 结束时间晚于或时段在期间内:搜索值的值上范围与目标值的值内范围相交(即部分重叠),或者搜索值的值内范围完全包含目标值的值内范围
le 小于等于:目标值小于等于搜索值 开始时间早于或时段在期间内:搜索值的值下范围与目标值的值内范围相交(即部分重叠),或者搜索值的值内范围完全包含目标值的值内范围
sa 在……之后开始,目标值在搜索值之后开始 目标值的开始时间晚于搜索值的结束时间:搜索值的值内范围与目标值的值内范围不重叠,并且搜索值的值上范围包含目标值的值内范围
eb 在……之前结束,目标值在搜索值之前结束 目标值的结束时间早于搜索值的开始时间:搜索值的范围与目标值的范围不重叠,并且搜索值的值下范围包含目标值的值内范围
ap 近似于,目标值与搜索值大致相同。值的偏差建议控制在搜索值 的10%以内(对于日期型搜索,偏差范围是当前时间和搜索值之间的间隔时间的10%),但服务端系统可根据情况调整偏差范围。 搜索值的值内范围与目标值的值内范围部分重叠

如果没有指定前缀比较符,则默认用“eq”。 注意,搜索参数的运作机制和两个数字之间在数学意义上的运算机制不两只。sa(在……之后开始)和eb(在……之前结束)不用于整数值,而是用于小数。

上表中对前缀比较符的解释有两种,一是对前缀用途的解释;二是对参数值范围的解释。如果参数值是小数和日期类型时,参数值范围是隐式的(即范围是以某种默认规则的形式存在)例如,数字2.0的隐式范围为1.95到2.05,日期2015-08-12的隐式范围为该天的所有时间。如果 搜索总是对隐式或显式为范围的值执行。如果目标值的数据类型是 Range, a Period, or a Timing,则目标值的范围是显式的。 值的范围有以下三种:

值内范围 范围跨度由数值的精度决定 数字2.0的值内范围为:1.95到2.05(不含)
日期2015-08-12的值内范围为:2015-18-12T00:00:00到2015-18-13T00:00:00之间(包含起点,不含终点)
值下范围 数值(不含数值本身)之前的范围 数字2.0的值下范围为:小于它的所有值,(即:<2.00000000000000000000)。
时间点2015-08-12T05:23:45的值下范围为:早于2015-08-12T05:23:45.000000000000000的所有时间。
值上范围 数值(包含数值本身)之后的范围 数字2.0的值上范围为:大于等于它的所有值,(即:>=2.00000000000000000000)。
时间点2015-08-12T05:23:45的值上范围为:晚于等于2015-08-12T05:23:45.000000000000000的所有时间。

后文将进一步讨论值的范围的正确用法。

针对资源中的简单数值进行搜索。示例如下:

[参数]=100 等于100的值,精确到3个有效位数,所以这实际上是在搜索范围[99.5 ... 100.5)
[参数]=100.00 等于100的值,精确到5个有效位数,所以这实际上是在搜索范围 [99.995 ... 100.005)
[参数]=1e2即1*102,等于100的值,精确到1个有效位数,所以这实际上是在搜索范围 [95 ... 105)
[参数]=lt100小于100(精确值)的值
[参数]=le100小于等于100(精确值)的值
[参数]=gt100大于100(精确值)的值
[参数]=ge100大于等于100(精确值)的值
[参数]=ne100不等于100的值 (确切的说, 是[99.5 ... 100.5)范围之外的值

数字搜索型还有以下一些注意事项:

  • 当目标值是一个整数类型(如:ImmunizationRecommendation.recommendation.doseNumber),并搜索值不是使用的指数形式且不带非零小数位,则不存在有效位数的问题。此时的搜索为精确匹配。注意,如果搜索值带有非零小数位,则不能有任何匹配项。
  • 当使用了 lgt、lt、ge、le、sa或eb前缀比较符时,则将其视为精确值,即忽略数字值内范围中的隐式精度。
  • 资源数字搜索型参数的运行机制与数学意义上比较两个数字的值的概念是不同的。
  • 对数字的搜索包含一个隐式范围,即上述“值的范围”。隐式范围的有效位数是以搜索值为准,不包括前导零。另外,虽然100、1.00e2、1e2三个数的值都等于100,但100和1.00e2的有效位数都是3,而1e2的有效位是1。

面上是关于数字搜索型的几个例子:

搜索语句描述
 GET [基地址]/RiskAssessment?probability=gt0.8
搜索概率大于0.8的所有RiskAssessment资源(也可以使用指数形式:probability=gt8e-1
 GET [基地址]/ImmunizationRecommendation?dose-number=2
寻找任何推荐第二次注射的免疫建议 搜索建议进行第二次接种的所有ImmunizationRecommendation资源

日期搜索型是对日期/时间或时段的搜索。和其它与日期/时间相关的功能一样,虽然一眼就能知道是什么意思,但却有很多需要注意的细节。

日期搜索型的参数格式为: yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm]。 这是 XML中使用的标准格式。

Technically, this is any of the date, dateTime, and instant data types; e.g. Any degree of precision can be provided, but it SHALL be populated from the left (e.g. can't specify a month without a year), except that the minutes SHALL be present if an hour is present, and you SHOULD provide a time zone if the time part is present. Note: Time can consist of hours and minutes with no seconds, unlike the XML Schema dateTime type. Some user agents may escape the : characters in the URL, and servers SHALL handle this correctly.

Date parameters may be used with the following data types:

dateThe range of the value is the day, month, or year as specified
dateTime The range of the value as defined above; e.g. For example, the date 2013-01-10 specifies all the time from 00:00 on 10-Jan 2013 to immediately before 00:00 on 11-Jan 2013
instantAn instant is considered a fixed point in time with an interval smaller than the precision of the system, i.e. an interval with an effective width of 0
PeriodExplicit, though the upper or lower bound might not actually be specified in resources.
Timing the specified scheduling details are ignored and only the outer limits matter. For instance, a schedule that specifies every second day between 31-Jan 2013 and 24-Mar 2013 includes 1-Feb 2013, even though that is on an odd day that is not specified by the period. This is to keep the server load processing queries reasonable.

Implicitly, a missing lower boundary is "less than" any actual date. A missing upper boundary is "greater than" any actual date. The use of the prefixes:

[参数]=eq2013-01-14
  • 2013-01-14T00:00 matches (obviously)
  • 2013-01-14T10:00 matches
  • 2013-01-15T00:00 does not match - it's not in the range
[参数]=ne2013-01-14
  • 2013-01-15T00:00 matches - it's not in the range
  • 2013-01-14T00:00 does not match - it's in the range
  • 2013-01-14T10:00 does not match - it's in the range
[参数]=lt2013-01-14T10:00
  • 2013-01-14 matches, because it includes the part of 14-Jan 2013 before 10am
[参数]=gt2013-01-14T10:00
  • 2013-01-14 matches, because it includes the part of 14-Jan 2013 after 10am
[参数]=ge2013-03-14
  • "from 21-Jan 2013 onwards" is included because that period may include times after 14-Mar 2013
[参数]=le2013-03-14
  • "from 21-Jan 2013 onwards" is included because that period may include times before 14-Mar 2013
[参数]=sa2013-03-14
  • "from 15-Mar 2013 onwards" is included because that period starts after 14-Mar 2013
  • "from 21-Jan 2013 onwards" is not included because that period starts before 14-Mar 2013
  • "before and including 21-Jan 2013" is not included because that period starts (and ends) before 14-Mar 2013
[参数]=eb2013-03-14
  • "from 15-Mar 2013 onwards" is not included because that period starts after 14-Mar 2013
  • "from 21-Jan 2013 onwards" is not included because that period starts before 14-Mar 2013, but does not end before it
  • "before and including 21-Jan 2013" is included because that period ends before 14-Mar 2013
[参数]=ap2013-03-14
  • 14-Mar 2013 is included - as it exactly matches
  • 21-Jan 2013 is not included because that is near 14-Mar 2013
  • 15-Jun 2015 is not included - as it is not near 14-Mar 2013. Note that the exact value here is at the discretion of the system

Other notes:

  • When the date parameter is not fully specified, matches against it are based on the behavior of intervals, where:
    • Dates with only the year specified are equivalent to an interval that starts at the first instant of January 1st to the last instant of December 31st, e.g. 2000 is equivalent to an interval of [2000-01-01T00:00, 2000-12-31T23:59].
    • Dates with the year and month are equivalent to an interval that starts at the first instant of the first day of the month and ends on the last instant of the last day of the month, e.g. 2000-04 is equivalent to an interval of [2000-04-01T00:00, 2000-04-30T23:59].
  • Where possible, the system should correct for time zones when performing queries. Dates do not have time zones, and time zones should not be considered. Where both search parameters and resource element date times do not have time zones, the servers local time zone should be assumed.

To search for all the procedures in a patient compartment that occurred over a 2-year period:

 GET [基地址]/Patient/23/Procedure?date=ge2010-01-01&date=le2011-12-31

Managing time zones and offsets and their impact on search is a very difficult area. The FHIR implementation community is still investigating and debating the best way to handle time zones. Implementation guides may make additional rules in this regard.

Future versions of this specification may impose rules around the use of time zones with dates. Implementers and authors of implementation guides should be aware of ongoing work in this area.

Implementer feedback is welcome on the issue tracker or chat.fhir.org .

 

For a simple string search, a string parameter serves as the input for a search against sequences of characters. This search is insensitive to casing and included combining characters, like accents or other diacritical marks. Punctuation and non-significant whitespace (e.g. repeated space characters, tab vs space) should also be ignored. By default, a field matches a string query if the value of the field equals or starts with the supplied parameter value, after both have been normalized by case and combining characters. Therefore, the default string search only operates on the base characters of the string parameter. The :contains modifier returns results that include the supplied parameter value anywhere within the field being searched. The :exact modifier returns results that match the entire supplied parameter, including casing and accents.

Examples:

[基地址]/Patient?given=eveAny patients with a name containing a given part with "eve" at the start of the name. This would include patients with the given name "Eve", "Evelyn".
[基地址]/Patient?given:contains=eveAny patients with a name with a given part containing "eve" at any position. This would include patients with the given name "Eve", "Evelyn", and also "Severine".
[基地址]/Patient?given:exact=EveAny patients with a name with a given part that is exactly "Eve". Note: This would not include patients with the given name "eve" or "EVE".

An additional modifier :text can be used to specify a search with advanced text handling (see below) though only a few servers are expected to offer this facility.

When a string search parameter refers to the types HumanName and Address, the search covers the elements of type string, and does not cover elements such as use and period. For robust search, servers should search the parts of a family name independently. E.g. searching either "Carreno" or "Quinones" should match a family name of "Carreno Quinones". HL7 affiliates may make more specific recommendations about how search should work in their specific culture.

It is at the discretion of the server whether to pre-process names, addresses, and contact details to remove separator characters prior to matching in order to ensure more consistent behavior. For example, a server might remove all spaces and - characters from phone numbers. What is most appropriate varies depending on culture and context. A server may also use a free-text style searches on this property to achieve the best results.
When searching whole names and addresses (not parts), servers may also use flexible match or a free-text style searches on names to achieve the best results.

The uri parameter refers to an element that contains a URI (RFC 3986 ). By default, matches are precise (e.g. case, accent, and escape) sensitive, and the entire URI must match. The modifier :above or :below can be used to indicate that partial matching is used. For example:

 GET [基地址]/ValueSet?url=http://acme.org/fhir/ValueSet/123
 GET [基地址]/ValueSet?url:below=http://acme.org/fhir/
 GET [基地址]/ValueSet?url:above=http://acme.org/fhir/ValueSet/123/_history/5
 GET [基地址]/ValueSet?url=urn:oid:1.2.3.4.5
  • The first line is a request to find any value set with the exact url "http://acme.org/fhir/ValueSet/123"
  • The second line performs a search that will return any value sets that have a URL that starts with "http://acme.org/fhir/"
  • The third line shows the converse - search for any value set above a given specific URL. This will match on any value set with the specified URL, but also on http://acme.org/ValueSet/123. Note that there are not many use cases where :above is useful as compared to the :below search
  • The fourth line shows an example of searching by an OID. Note that the :above and :below modifiers only apply to URLs, and not URNS such as OIDs

The search type uri is used with elements of type uri and url. The type reference is used for the types Reference and canonical. Note that for uri parameters that refer to the Canonical URLs of the conformance and knowledge resources (e.g. StructureDefinition, ValueSet, PlanDefinition etc), servers SHOULD support searching by canonical references, and SHOULD support automatically detecting a |[version] portion as part of the search parameter, and interpreting that portion as a search on the version.

token令牌类型是一个参数,它对一个字符串提供接近精确的匹配搜索,其范围可能由URI确定。 它主要用于当 code identifier 类型的值可能由一个URI规定其含义和范围时,用编码或标识符的“码|值对”参数执行搜索。 当其他一些类型需要精确匹配时也可以使用令牌,如 uris booleans ContactPoints 类型,在这些情况下则不使用URI定义的范围与含义。

For tokens, matches are literal (e.g. not based on subsumption or other code system features). Match is case sensitive unless the underlying semantics for the context indicate that the token should be interpreted case-insensitively (see, e.g. CodeSystem.caseSensitive). Note that matches on _id are always case sensitive. If the underlying data type is string then the search is not case sensitive.

Note: There are many challenging issues around case sensitivity and token searches. Some code systems are case sensitive (e.g. UCUM) while others are known not to be. For many code systems, it's ambiguous. Other kinds of values are also ambiguous. When in doubt, servers SHOULD treat tokens in a case-insensitive manner, on the grounds that including undesired data has less safety implications than excluding desired behavior. Clients SHOULD always use the correct case when possible, and allow for the server to perform case-insensitive matching.

To use subsumption-based logic, use the modifiers below, or list all the codes in the hierarchy. The syntax for the value is one of the following:

  • [参数]=[code]: the value of [code] matches a Coding.code or Identifier.value irrespective of the value of the system property
  • [参数]=[system]|[code]: the value of [code] matches a Coding.code or Identifier.value, and the value of [system] matches the system property of the Identifier or Coding
  • [参数]=|[code]: the value of [code] matches a Coding.code or Identifier.value, and the Coding/Identifier has no system property
  • [参数]=[system]|: any element where the value of [system] matches the system property of the Identifier or Coding

Notes:

  • The namespace URI and code both must be escaped correctly. If a system is not applicable (e.g. an element of type uri, then just the form [参数]=[code] is used.
  • For token parameters on elements of type ContactPoint, uri, or boolean, the presence of the pipe symbol SHALL NOT be used - only the [参数]=[code] form is allowed

Token search parameters are used for the following data types:

Data Type URI Code Comments
Coding Coding.system Coding.code
CodeableConcept CodeableConcept.coding.system CodeableConcept.coding.code Matches against any coding in the CodeableConcept
Identifier Identifier.system Identifier.value Clients can search by type not system using the :of-type modifier, see below. To search on a CDA II.root - which may appear in either Identifier.system or Identifier.value, use the syntax identifier=|[root],[root]
ContactPoint ContactPoint.value At the discretion of the server, token searches on ContactPoint may use special handling, such as ignoring punctuation, performing partial searches etc.
code (implicit) code the system is defined in the value set (though it's not usually needed)
boolean boolean The implicit system for boolean values is http://hl7.org/fhir/special-values but this is never actually used
uri uri
string n/a string Token is sometimes used for string to indicate that exact matching is the correct default search strategy

Note: The use of token search parameters for boolean fields: the boolean values "true" and "false" are also represented as formal codes in the Special Values code system, which is useful when boolean values need to be represented in a Coding data type. The namespace for these codes is http://hl7.org/fhir/special-values, though there is usually no reason to use this, as a simple true or false is sufficient.

Modifiers:

Modifier Use
:text The search parameter is processed as a string that searches text associated with the code/value - either CodeableConcept.text, Coding.display, or Identifier.type.text. In this case, the search functions as a normal string search
:not Reverse the code matching described in the paragraph above: return all resources that do not have a matching item. Note that this includes resources that have no value for the parameter - e.g. ?gender:not=male includes all patients that do not have gender = male, including patients that do not have a gender at all
:above The search parameter is a concept with the form [system]|[code], and the search parameter tests whether the coding in a resource subsumes the specified search code. For example, the search concept has an is-a relationship with the coding in the resource, and this includes the coding itself.
:below the search parameter is a concept with the form [system]|[code], and the search parameter tests whether the coding in a resource is subsumed by the specified search code. For example, the coding in the resource has an is-a relationship with the search concept, and this includes the coding itself.
:in The search parameter is a URI (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is in the specified value set. The reference may be literal (to an address where the value set can be found) or logical (a reference to ValueSet.url). If the server can treat the reference as a literal URL, it does, else it tries to match known logical ValueSet.url values.
:not-in The search parameter is a URI (relative or absolute) that identifies a value set, and the search parameter tests whether the coding is not in the specified value set.
:of-type The search parameter has the format system|code|value, where the system and code refer to a Identifier.type.coding.system and .code, and match if any of the type codes match. All 3 parts must be present

Most servers will only process value sets that are already known/registered/supported internally. However, servers can elect to accept any valid reference to a value set. Servers may elect to consider concept mappings when testing for subsumption relationships.

Example searches:

SearchDescription
 GET [基地址]/Patient?identifier=http://acme.org/patient|2345
Search for all the patients with an identifier with key = "2345" in the system "http://acme.org/patient"
 GET [基地址]/Patient?gender=male
Search for any patient with a gender that has the code "male"
 GET [基地址]/Patient?gender:not=male
Search for any patient with a gender that does not have the code "male". Note that for :not, the search does not return any resources that have a gen
 GET [基地址]/Composition?section=48765-2
Search for any Composition that contains an Allergies and adverse reaction section
 GET [基地址]/Composition?section:not=48765-2
Search for any Composition that does not contain an Allergies and adverse reaction section. Note that this search does not return "any document that has a section that is not an Allergies and adverse reaction section" (e.g. in the presence of multiple possible matches, the negation applies to the set, not each individual entry)
 GET [基地址]/Patient?active=true
Search for any patients that are active
 GET [基地址]/Condition?code=http://acme.org/conditions/codes|ha125
Search for any condition with a code "ha125" in the code system "http://acme.org/conditions/codes"
 GET [基地址]/Condition?code=ha125
Search for any condition with a code "ha125". Note that there is not often any useful overlap in literal symbols between code systems, so the previous example is generally preferred
 GET [基地址]/Condition?code:text=headache
Search for any Condition with a code that has a text "headache" associated with it (either in the text, or a display)
 GET [基地址]/Condition?code:in=http%3A%2F%2Fsnomed.info%2Fsct%3Ffhir_vs%3Disa%2F126851005
Search for any condition in the SNOMED CT value set "http://snomed.info/sct?fhir_vs=isa/126851005" that includes all descendants of "Neoplasm of liver"
 GET [基地址]/Condition?code:below=126851005
Search for any condition that is subsumed by the SNOMED CT Code "Neoplasm of liver". Note: This is the same outcome as the previous search
 GET [基地址]/Condition?code:in=http://acme.org/fhir/ValueSet/cardiac-conditions
Search for any condition that is in the institutions list of cardiac conditions
 GET [基地址]/Patient?identifier:otype=http://terminology.hl7.org/CodeSystem/v2-0203|MR|446053
Search for the Medical Record Number 446053 - this is useful where the system id for the MRN is not known

The :below modifier is also very useful with searching mime types, such as for DocumentReference.contenttype which refers to Attachment.contentType. A simple search such as:

GET [基地址]/DocumentReference?contenttype=text/xml

will miss documents with a mime type such as text/xml; charset=UTF-8. This search will find all text/xml documents:

GET [基地址]/DocumentReference?contenttype:below=text/xml

For ease of processing on the server, servers are only required to support :below on the base part of the mime type; servers are not required to sort between different parameters and do formal subsumption logic.

A quantity parameter searches on the Quantity data type. The syntax for the value follows the form:

  • [参数]=[prefix][number]|[system]|[code] matches a quantity with the given unit

The prefix is optional, and is as described above, both regarding how precision and comparator/range operators are interpreted. Like a number parameter, the number part of the search value can be a decimal in exponential format. The system and code follow the same pattern as token parameters are also optional. Example searches:

SearchDescription
 GET [基地址]/Observation?value-quantity=5.4|http://unitsofmeasure.org|mg
Search for all the observations with a value of 5.4(+/-0.05) mg where mg is understood as a UCUM unit (system/code)
 GET [基地址]/Observation?value-quantity=5.40e-3|http://unitsofmeasure.org|g
Search for all the observations with a value of 0.0054(+/-0.000005) g where g is understood as a UCUM unit (system/code)
 GET [基地址]/Observation?value-quantity=5.4||mg
Search for all the observations with a value of 5.4(+/-0.05) mg where the unit - either the code (code) or the stated human unit (unit) are "mg"
 GET [基地址]/Observation?value-quantity=5.4
Search for all the observations with a value of 5.4(+/-0.05) irrespective of the unit
 GET [基地址]/Observation?value-quantity=le5.4|http://unitsofmeasure.org|mg
Search for all the observations where the value of is less than 5.4 mg exactly where mg is understood as a UCUM unit
 GET [基地址]/Observation?value-quantity=ap5.4|http://unitsofmeasure.org|mg
Search for all the observations where the value of is about 5.4 mg where mg is understood as a UCUM unit (typically, within 10% of the value - see above)

Specifying a system and a code for the search implies that the search is based on a particular code system - usually UCUM , and that a precise (and potentially canonical) match is desired. In this case, it is inappropriate to search on the human display for the unit, which can be is uncontrolled and may unpredictable.

The search processor may choose to perform a search based on canonical units (e.g. any value where the units can be converted to a value in mg in the case above). For example, an observation may have a value of 23 mm/hr. This is equal to 0.23 m/hr. The search processer can choose to normalise all the values to a canonical unit such as 6.4e-6 m/sec, and convert search terms to the same units (m/sec). Such conversions can be performed based on the semantics defined in UCUM

A reference parameter refers to references between resources. For example, find all Conditions where the subject reference is a particular patient, where the patient is selected by name or identifier. The interpretation of a reference parameter is either:

  • [参数]=[id] the logical [id] of a resource using a local reference (i.e. a relative reference)
  • [参数]=[type]/[id] the logical [id] of a resource of a specified type using a local reference (i.e. a relative reference), for when the reference can point to different types of resources (e.g. Observation.subject)
  • [参数]=[url] where the [url] is an absolute URL - a reference to a resource by its absolute location, or by it's canonical URL

Note: A relative reference resolving to the same value as a specified absolute URL, or vice versa, qualifies as a match. For example, if the search parameter value is Patient/123, then this will find references like this:

 <patient>
   <reference value="Patient/123"/>
 </patient>

If the server base address is http://example.org/fhir, then the full URL for that reference is http://example.org/fhir/Patient/123, which means that the search term also matches patient references like this:

 <patient>
   <reference value="http://example.org/fhir/Patient/123"/>
 </patient>

In addition, searching for reference=http://example.org/fhir/Patient/123 will also match both references.

Some references may point to more than one type of resource; e.g. subject: Reference(Patient|Group|Device|..). In these cases, multiple resources may have the same logical identifier. Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types. In order to allow the client to perform a search in these situations the type is specified explicitly:

 GET [基地址]/Observation?subject=Patient/23

This searches for any observations where the subject refers to the patient resource with the logical identifier "23". A modifier is also defined to allow the client to be explicit about the intended type:

 GET [基地址]/Observation?subject:Patient=23

This has the same effect as the previous search. The modifier becomes useful when used with chaining as explained in the next section. Note: The [type] modifier can't be used with a reference to a resource found on another server, since the server would not usually know what type that resource has. However, since these are absolute references, there can be no ambiguity about the type.

In some cases, search parameters are defined with an implicitly limited scope. For example, Observation has an element subject, which is a reference to one of a number of types. This has a matching search parameter subject, which refers to any of the possible types. In addition to this, there is another search parameter patient, which also refers to Observation.subject, but is limited to only include references of type Patient. When using the patient search parameter, there is no need to specify ":Patient" as a modifier, or "Patient/" in the search value, as this must always be true.

References are also allowed to have an identifier. The modifier :identifier allows for searching by the identifier rather than the literal reference:

 GET [基地址]/Observation?subject:identifier=http://acme.org/fhir/identifier/mrn|123456

This is a search for all observations that reference a patient by a particular patient MRN. When the :identifier modifier is used, the search value works as a token search. The :identifier modifier is not supported on canonical elements since they do not have an identifier separate from the reference itself.

Chaining is not supported when using the :identifier modifier, nor are chaining, includes or reverse includes supported for reference elements that do not have a reference element.

The reference search parameter is mostly used for resource elements of type Reference or canonical. However, it is also be used to search resource elements of type Resource - i.e. where one resource is directly nested within another - see the Bundle search parameters 'message' and 'composition' as an example of this.

Elements of type Reference may contain a versioned reference:

   <evidence>
      <reference value="Observation/123/_history/234234"/>
  </evidence>

When searching on versioned references, the following rules apply:

  • If a resource has a reference that is versioned, and chaining is performed, the criteria should ideally be evaluated against the version referenced, but most systems will not be capable of this because search is only defined to function against the current version of a resource
  • Where a search does not act on the referenced version, search results SHOULD contain a OperationOutcome with a warning that indicates the discrepancy
  • If a resource has a reference that is versioned and _include is performed, the specified version SHOULD be provided.

Elements of type canonical may contain a version specific reference, but this version is different in both meaning and format to version specific references that might be found in a Reference:

   <valueSet value="http://hl7.org/fhir/ValueSet/example|3.0"/>

This version is a reference to the business version of the resource.

For canonical references, servers SHOULD support searching by Canonical URLs, and SHOULD support automatically detecting a |[version] portion as part of the search parameter and interpreting that portion as a search on the business version of the target resource. The modifier :below is used with canonical references, to control whether the version is considered in the search. The search:

GET {base]/Observation?definition:below=http:http://acme.com/some-profile

matches all of these element values:

  • http://acme.com/some-profile|1.0
  • http://acme.com/some-profile|1.1
  • http://acme.com/some-profile|2.0

The search:

GET {base]/Observation?definition:below=http:http://acme.com/some-profile|1

matches the first two element values.

资源的循环引用是指A资源类型中的某个元素引用的资源类型也是A。当这种循环引用形成了严格的层级结构时,可以使用:above:below后缀修饰符在层级结构中进行传递性搜索。如:

GET [基地址]/Procedure?location:below=42

搜索返回的Procedure资源实例是根据Procedure.location来匹配的。由于Location资源中的partOf元素引用的资源类型也是Location,这就构成了一个循环引用。并且此循环引用的意义是“此地是属于另一地的一部分,以此类推”,它形成了严格的层级结构。所以可以使用:below后缀修饰符在Location.partOf的层级结构中进行传递性搜索。 即,此搜索不仅仅以id为42的Location资源实例B作为匹配条件,而且将B “之下”(属于B的一部分)的所有Location资源实例都作为匹配条件。换句话说,搜索条件是:Procedure资源的Procedure.location.id=42,或者Procedure.location.partOf.id=42或者Procedure.location.partOf.partOf.id=42,以此类推。无论partOf有多少个层级,只要它属于B,那么在此Location上发生的Procedure都符合搜索条件。

GET [基地址]/MedicationAdministration?context:above=21

搜索返回的MedicationAdministration资源实例是根据MedicationAdministration.context来匹配的。由于Encounter资源中的partOf元素引用的资源类型也是Encounter,这就构成了一个循环引用。并且此循环引用的意义是“在管理上或时间上,此医疗活动是另一个医疗活动其中的一部分,以此类推”,它形成了严格的层级结构。所以可以使用:above后缀修饰符在Encounter.partOf的层级结构中进行传递性搜索。 即,此搜索不仅仅以id为21的Encounter资源实例C匹配条件,而且将C “之上”(C的父级)的所有Encounter资源实例都作为匹配条件。 换句话说,搜索条件是:MedicationAdministration资源的MedicationAdministration.context=Encounter/21?_revinclude=Encounter:partOf(关于“反向包含”_revinclude将在后文介绍)或者反向包含中的每个Encounter中再次反向包含的Encounter,以此类推。无论反向包含有多少个层级,只要Encounter是C的父级Encounter,那么在此Encounter期间的MedicationAdministration都符合搜索条件。

服务器通过定义搜索参数资源的Modifiers元素来说明是否支持:above/:below后缀修饰符。

In order to save a client from performing a series of search operations, reference parameters may be "chained" by appending them with a period (.) followed by the name of a search parameter defined for the target resource. This can be done recursively, following a logical path through a graph of related resources, separated by .. For instance, given that the resource DiagnosticReport has a search parameter named subject, which is usually a reference to a Patient resource, and the Patient resource includes a parameter name which searches on patient name, then the search

 GET [基地址]/DiagnosticReport?subject.name=peter

is a request to return all the lab reports that have a subject whose name includes "peter". Because the Diagnostic Report subject can be one of a set of different resources, it's necessary to limit the search to a particular type:

 GET [基地址]/DiagnosticReport?subject:Patient.name=peter

This request returns all the lab reports that have a subject which is a patient, whose name includes "peter".

Note that chained parameters are applied independently to the target resource. For example,

GET Patient?general-practitioner.name=Joe&general-practitioner.address-state=MN

may return Patients cared for by Joe from CA and Jane from MN: no one practitioner need satisfy both conditions. E.g. the chains are evaluated separately. For use cases where the joins must be evaluated in groups, there are either Composite search parameters, or the _filter parameter.

Advanced Search Note: Where a chained parameter searches a resource reference that may have more than one type of resource as its target, the parameter chain may end up referring to search parameters with the same name on more than one kind of resource at once. Servers SHOULD reject a search where the logical id refers to more than one matching resource across different types. For example, the client has to specify the type explicitly using the syntax in the second example above.

The _has parameter provides limited support for reverse chaining - that is, selecting resources based on the properties of resources that refer to them (instead of chaining, above, where resources can be selected based on the properties of resources that they refer to). Here is an example of the _has parameter:

GET [基地址]/Patient?_has:Observation:patient:code=1234-5

This requests the server to return Patient resources, where the patient resource is referred to by at least one Observation where the observation has a code of 1234, and where the Observation refers to the patient resource in the patient search parameter.

"Or" searches are allowed (e.g. GET [基地址]/Patient?_has:Observation:patient:code=123,456), and multiple _has parameters are allowed (e.g. GET [基地址]/Patient?_has:Observation:patient:code=123&_has:Observation:patient:code=456). Note that each _has parameter is processed independently of other _has parameters.

The _has parameter can be chained, like this:

GET [基地址]/Patient?_has:Observation:patient:_has:AuditEvent:entity:user=MyUserId

Fetch all the patients that have an Observation where the observation has an audit event from a specific user.

Composite search parameters support joining single values with a $. For example, the result of the search operation is the intersection of the resources that match the criteria specified by each individual search parameter. If a parameter repeats, such as /Patient?language=FR&language=NL, then this matches a patient who speaks both languages. This is known as an AND search parameter, since the server is expected to respond only with results which match both values.

If, instead, the search is to find patients that speak either language, then this is a single parameter with multiple values, separated by a ,. For example, /Patient?language=FR,NL. This is known as an OR search parameter, since the server is expected to respond with results which match either value. Every search parameter may be used with comma-separated values in this fashion; this includes the use of search parameters with modifiers, such as `?code:text=this,that.

AND parameters and OR parameters may also be combined, for example: /Patient?language=FR,NL&language=EN would refer to any patient who speaks English, as well as either French or Dutch.

This approach allows for simple combinations of and/or values, but doesn't allow a search based on a pair of values, such as all observations with a sodium value >150 mmol/L (particularly as the end criteria of a chained search), or searching on Group.characteristic where you need find a combination of key/value, not an intersection of separate matches on key and value. Another example is spatial coordinates when doing geographical searches.

To allow these searches, a resource may also specify composite parameters that take sequences of single values that match other defined parameters as an argument. The matching parameter of each component in such a sequence is documented in the definition of the parameter. These sequences are formed by joining the single values with a $. Note: This sequence is a single value and itself can be composed into a set of values, so that, for example, multiple matching characteristic-value parameters can be specified as GET [基地址]/Group?characteristic-value=gender$mixed,owner$Eve.

Note: Modifiers are not used on composite parameters.

Examples of using composite parameters:

SearchDescription
 GET [基地址]/DiagnosticReport?result.code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L
Search for all diagnostic reports that contain on observation with a potassium value of >5.4 mmol/L (UCUM)
 GET [基地址]/Observation?component-code-value-quantity=http://loinc.org|8480-6$lt60
Search for all the observations with a systolic blood pressure < 60. Note that in this case, the unit is assumed (everyone uses mmHg)
 GET [基地址]/Group?characteristic-value=gender$mixed
Search for all groups that have a characteristic "gender" with a text value of "mixed"
 GET [基地址]/Questionnaire?context-type-value=focus$http://snomed.info/sct|408934002
Search for all questionnaires that have a clinical focus = "Substance abuse prevention assessment (procedure)"

Consider the case of searching for all AllergyIntolerance resources:

GET [基地址]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active

This search will only return resources that have a value for clinicalStatus:

{
  "resourceType" : "AllergyIntolerance",
   "clinicalStatus": {
    "coding": [
      {
        "system": "http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical",
        "code": "active"
      }
    ]
  }
}

Resources missing a clinicalStatus will not be returned. This is probably unsafe - it would not usually be appropriate to ignore AllergyIntolerance warnings with an unknown clinical status, and only return resources with an explicit clinicalStatus. Instead, it might be desired to return AllergyIntolerance resources with either an explicit value for clinicalStatus, or none:

GET [基地址]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active
GET [基地址]/AllergyIntolerance?clinical-status:missing=true

Note that this is 2 separate queries. They can be combined in a batch, but not in a single operation. This query will always return an empty list, as no resource can satisfy both criteria at once:

GET [基地址]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active&clinical-status:missing=true

There is no way to use the :missing modifier and mix with a value using the comma syntax documented above for composite search parameters.

An alternative approach is to use the _filter parameter, for servers that support this parameter.

In the rules described above, special rules are defined for the characters $, ,, and |. As a consequence, if these characters appear in an actual parameter value, they must be differentiated from their use as separator characters. When any of these characters appear in an actual parameter value, they must be prepended by the character \, which also must be used to prepend itself. Therefore, param=xxx$xxx indicates that it is a composite parameter, while param=xx\$xx indicates that the parameter has the literal value xx$xx. The parameter value xx\xx is illegal, and the parameter value param=xx\\xx indicates a literal value of xx\xx. This means that:

GET [基地址]/Observation?code=a,b

is a request for any Observation that has a code of either a or b, whereas:

GET [基地址]/Observation?code=a\,b

is a request for any Observation that has a code of a,b.

This escaping is at a different level to the % encoding that applies to all URL parameters. Standard % escaping still applies, such that these URLs have the same meaning:

GET [基地址]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124,125
GET [基地址]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124%2CValueSet/125

As do these URLs:

GET [基地址]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,125
GET [基地址]/ValueSet?url=http%58%47%47acme%46org%47fhir%47ValueSet%47123%44http%58%47%47acme%46org%47fhir%47ValueSet%47124%92%46125

This specification defines this additional form of escape because the escape syntax using \ applies to all parameter values after they have been 'unescaped' on the server while being read from the HTTP headers.

The special text search parameters, _text and _content, search on the narrative of the resource, and the entire content of the resource respectively. Just like string parameters using the :text modifier, these parameters SHOULD support a sophisticated search functionality of the type offered by typical text indexing services. The value of the parameter is a text-based search, which may involve searching multiple words with thesaurus and proximity considerations, and logical operations such as AND, OR etc. For example:

 GET [基地址]/Condition?_text=(bone OR liver) and metastases

This request returns all Condition resources with the word "metastases" and either "bone" or "liver" in the narrative. The server MAY choose to search for related words as well.

Implementers could consider using the rules specified by the OData specification for the $search parameter . Typical implementations would use Lucene, Solr, an SQL-based full text search, or some similar indexing service.

A few parameters have the type 'special'. That indicates that the way this parameter works is unique to the parameter and described with the parameter. The general modifiers and comparators do not apply, except as stated in the description.

Implementers will generally need to do special implementations for these parameters. These parameters are special:

The _list parameter allows for the retrieval of resources that are referenced by a List resource.

 GET [基地址]/Patient?_list=42

This request returns all Patient resources that are referenced from the list found at [基地址]/List/42) in List.entry.item. While it is possible to retrieve the list, and then iterate the entries in the list fetching each patient, using a list as a search criterion allows for additional search criteria to be specified. For instance:

 GET [基地址]/Patient?_list=42&gender=female

This request will return all female patients in the list. The server can return the list referred to in the search parameter as an included resource, but is not required to do so. In addition, a system can support searching by lists by their logical function. For example:

 GET [基地址]/AllergyIntolerance?patient=42&_list=$current-allergies

This request will return all allergies in patient 42's "Current Allergy List". The server returns all relevant AllergyIntolerance resources, and can also choose to return the list. For further information, refer to the definition of "$current-allergies", and the List Operation "Find". Note: Servers are not required to make these lists available to the clients as list resources, but may choose to do so.

The search mechanism described above is flexible, and easy to implement for simple cases, but is limited in its ability to express combination queries. To complement this mechanism, the "_filter" search expression parameter can be used.

For example, "Find all the observations for patient with a name including peter that have a LOINC code 1234-5":

GET [基地址]/Observation?code=http://loinc.org|1234-5&subject.name=peter

Using the _filter parameter, the search would be expressed like this:

GET [基地址]/Observation?_filter=code eq http://loinc.org|1234-5 and subject.name co "peter"

The _filter parameter is described in detail on the "_Filter Parameter" page.

通常,搜索是对针对某一已知类型的资源的,例如

GET [基地址]/Observation?[参数]...

但在某些情况下,不是在固定类型的资源上执行搜索:

  • 跨所有资源类型使用搜索 (GET [基地址]?[参数]...)
  • 将搜索用于 消息
  • 某些搜索的规范是在其他服务中执行,例如,决策支持使用场景

在这些情况下,搜索条件可能需要指定应用于搜索的一个或多个资源类型。这可以通过使用_type参数来完成:

GET [基地址]/?_type=Observation,Condition&[其它参数]...

如果未指定任何类型,则只能使用全局性搜索参数,即:适用于所有资源的基础参数 。如果指定了多个资源类型,则可以使用这些资源类型所共有的搜索参数。(参见 搜索参数注册表).

从技术上讲,_type参数是资源类型值集上的令牌参数。

客户端可以使用_sort参数指定返回结果的顺序,该参数可以使用逗号分隔列表来指定排序规则的优先级:

GET [基地址]/Observation?_sort=status,-date,category

逗号分隔列表中的每一项都是一个搜索参数,默认按升序排列,可以选择使用“-”前缀来表示降序。

注:

  • 排序时,服务器只会返回资源内容,而不会显式的返回资源使用的排序值。
  • 要按相关性排序,请使用_score参数。
  • 服务器将排序作为搜索参数的一部份返回请参见下文
  • 搜索参数可以引用重复的元素,因此单个资源的给定搜索参数可以有多个值。 在这种情况下,排序基于多个参数的集合中最早出现的项,以指定的排序顺序对返回资源进行排序。 In this case, the sort is based on the item in the set of multiple parameters that comes earliest in the specified sort order when ordering the returned resources.
  • 在对字符串搜索参数进行排序时,应在不区分大小写的基础上执行排序。 重音符号可以被忽略,也可以根据领域约定进行排序。
  • 此规范没有为跨服务器排序的符合性指定严格的规则。 一般来说,这并不像过滤(filtering)的符合性那样重要(尽管那只是一个小变量)。 排序的目的是以“合理”的顺序为最终用户提供数据。“合理”可能因用例和领域而异,特别对于重音字符来说尤为明显。

“ _total”参数处于 试用 状态,等待真实场景使用的经验。

返回的资源捆束(Bundle)带有一个total元素,它表示符合搜索参数要求的资源总数。

注意Bundle.total表示匹配的总数,而不是在特定响应中返回的资源数(请参见接下来介绍的分页)。

根据服务器的设计方式,为服务器提供精确数量的匹配资源可能非常困难。为了帮助减少服务器负载,客户端可以提供_total参数来 表示它对总数的需求,此参数可以使用下表中的值:

none 不需要返回总数,客户端不会使用。
estimate 对匹配资源的数量进行粗略估计就足够了
accurate 客户端请求服务器提供精确的匹配资源总数

Bundle.total元素仍然是可选的,服务器可以忽略_total参数: 它只是一个优化提示,可能会使服务器节省一些工作。

为了使客户端、服务器和网络的负载最小化,服务器可以使用分页来返回结果。 搜索结果集含有一些用于客户端请求其分页的URL,其中包含了所需的搜索参数集。 对于简单的RESTful搜索,页面链接包含在返回的bundle的link元素中.

通常,服务器在获取页面时会在链接里提供自己的参数,用于管理搜索的状态。 客户端不需要理解或处理这些参数。

_count参数被定义为一条关于在单个页面中应该返回多少资源的指令。 服务器返回的资源不能超过请求的数量,即使它们不支持分页,但返回的资源可能少于客户端请求的数量。 服务器应该在其返回的页面链接中重复原始的_count参数,以便后续的分页请求遵守原始的_count。 注意:如何在搜索过程中处理资源的持续更新由搜索引擎自行决定。

注意:_sort _count 的组合只能返回满足特定条件的最新资源 ——设置条件,再按日期降序排列,并将_count设为1,这样,将返回最后一个匹配的资源。

如果_count的值为0,则应将其视为与参数 _summary=count 的作用一样:服务器返回一个带有Bundle.total元素的资源捆束,这个元素值即为匹配的资源总数。这个资源捆束里没有任何条目,也没有“上一页”、“下一页”、“最后一页”的链接。 注意Bundle.total只包含匹配资源的总数。 它不会对诸如 操作结果 这样的额外资源计数,也不会对可能返回的包含资源(included resources)计数。 同样地,_count参数只适用于 entry.search.mode = search 的资源,不包括包含资源 操作结果 资源。

_count参数对 Bundle.total 的值没有影响,因为后者表示匹配的总数,而前者是单次响应的资源捆束返回的总数。

客户端可以请求引擎返回与搜索结果相关的资源,以减少相关资源重复检索的总体网络延迟。这叫做“包含资源”,它在客户端搜索临床资源时很有用,但对于返回的“包含资源”,客户端还需要临床资源引用到的目标(患者)资源。 客户端可以使用_include参数指示在结果中包含目标资源。 另一种情况是,客户端希望获取特定资源以及引用该资源的任何资源。 例如,客户端可能希望获取一个药品处方资源(MedicationRequest),以及引用处方的所有出处(Provenance)资源。 这被称为“反向包含”,可以通过_revinclude 参数来实现。

_include _revinclude 都基于搜索参数,而不是资源中的路径,因为连接工作(joins),比如链接(chaining)已经由搜索参数完成。

每个_include参数都要指定一个要与之连接的搜索参数:

 GET [基地址]/MedicationRequest?_include=MedicationRequest:patient
 GET [基地址]/MedicationRequest?_revinclude=Provenance:target

第一个搜索请求所有符合匹配条件的药品处方资源(MedicationRequest),并包含结果集中药品处方所指向(引用)的所有患者(Patient)资源。 第二个搜索请求所有符合匹配条件的药品处方资源(MedicationRequest),并返回引用它们的所有出处(Provenance)资源。

_include_revinclude的参数值由“:”字符分隔的三部分组成:

  1. 源资源的名称,连接(join)来自的此源资源。
  2. 搜索参数的名称, 此参数必须为引用类型
  3. (可选)特定的目标资源类型(当搜索参数引用多个可能的目标类型时)

_include_revinclude 参数不能以包含多个值的方式来指定不同的包含条件,而是以重复这些参数来实现的。

对于每个返回的资源,服务器会对符合连接表达式条件的资源进行标识,并将 entry.search.mode 设置为“include”(在某些搜索中,不清楚哪些资源匹配,哪些资源包含)。 如果没有引用或没有匹配的资源,则无法包含该资源(例如在其他服务器上),服务器会将其忽略该并不会返回任何错误。

当且仅当包含:iterate修饰符时,包含过程可以是迭代的。 例如,接下来的这个搜索返回符合发药(Medication Dispense)资源条件的所有 药品处方(MedicationRequest) 资源及其处方从业者(Practitioner)资源:

GET [基地址]/MedicationDispense?_include=MedicationDispense:prescription
    &_include:iterate=MedicationRequest:performer&criteria...

这种技术也适用于循环关系。 例如下面的两个对观测资源的搜索: 第一个包括 hasMember元素引用的所有相关的观测资源,但仅包括直接引用的成员。 第二个搜索要求_include参数基于 hasMember 元素迭代执行来实现包含,因此除了直接引用的成员外,还包含所有引用成员下引用的观测资源,逐层迭代。

GET [基地址]/Observation?_include=Observation:hasMember&criteria...
GET [基地址]/Observation?_include:iterate=Observation:hasMember&criteria...

_include _revinclude 都可以使用通配符“*”作为搜索参数名称,表示将搜索目标资源所包含的所有引用类型(type=reference)都作为搜索参数。 但客户端和服务器在执行此操作时都需要注意不要请求或返回太多的资源。 最值得注意的是,使用迭代通配符包含可能会获取完整的患者记录,甚至更多信息: 资源被组织到一个相互连接的网络中,广泛的_include路径最终可能会跨越服务器上的所有可能路径。 使用迭代和_include通配符对服务器的要求很高,可能会显著降低搜索性能。

包含的迭代计算深度由服务器决定。 服务器应该将迭代计算次数限制在适当的级别,并且没有义务满足在搜索结果中包含附加资源的请求。 因为迭代搜索通常是资源密集型的,所以它不是默认行为。

当搜索结果被分页时,搜索结果的每一页都应该含有匹配的“包含资源”的内容,这样每个分页的内部资源是连贯一致的,可以作为一个独立的包来使用。

注意:在考虑使用_include和_revienclude参数时,实施者还应该考虑使用 GraphQL(图谱查询语言) (GraphDefinition) 是否更合适其使用场景。

By default, search results only include resources that are not contained in other resources. A chained condition will be evaluated inside contained resources. To illustrate this, consider a MedicationRequest resource that has a contained Medication resource specifying a custom formulation that has ingredient with a itemCodeableConcept "abc" in "http://acme.com./medications". In this case, a search:

GET MedicationRequest?medication.ingredient-code=abc

will include the MedicationRequest resource in the results. However, this search:

GET Medication?ingredient-code=abc

will not include the contained Medication resource in the results, since either the wrong type of resource would be returned, or the contained resource would be returned without its container resource, which provides context to the contained resource.

Clients can modify this behavior using the _contained parameter, which can have one of the following values:

  • false (default): Do not return contained resources
  • true: return only contained resources
  • both: return both contained and non-contained (normal) resources

When contained resources are being returned, the server should return either the container resource, or the contained resource alone. The client can specify which by using the _containedType parameter, which can have one of the following values:

  • container (default): Return the container resources
  • contained: return only the contained resource

When returning a container resource, the server simply puts this in the search results:

<Bundle>
  ...
  <entry>
    <resource>
      <MedicationRequest>
        <id value="23">
        ....
        <contained>
          <Medication>
            <id value="m1">
            ...
          </Medication>
        <contained>

      </MedicationRequest>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>

In the case of returning container resources, the server SHALL populate the entry.search.mode element, as shown, so that the client can pick apart matches and includes (since the usual approach of doing it by type might not work).

If the return type is the contained resource, this must be done slightly differently:

<Bundle>
  ...
  <entry>
    <fullUrl value="http://example.com/fhir/MedicationRequest/23#m1"/>
    <resource>
      <Medication>
        <id value="m1">
        ...
      </Medication>
    </resource>
    <search>
      <mode value="match"/>
    </search>
  </entry>
</Bundle>

In this case, the fullUrl informs the client that this is a contained resource, along with indicating the identity of the containing resource.

If the _include path selects a reference that refers to a resource on another server, the server can elect to include that resource in the search results for the convenience of the client.

If the _include path selects a reference that refers to an entity that is not a Resource, such as an image attachment, the server may also elect to include this in the returned results as a Binary resource. For example, the include path may point to an attachment which is by reference, like this:

 <content>
   <contentType>image/jpeg</contentType>
   <url>http://example.org/images/2343434/234234.jpg</url>
 </content>

The server can retrieve the target of this reference, and add it to the results for the convenience of the client.

当搜索“包含资源”返回分页结果时,与主资源相关的所有“包含资源”也应该作为分页的一部分返回,即使其中一些资源实例之前已返回到以前的一些分页。 这种方法允许发送方和接收方避免缓存其他页面的结果。

The client can request the server to return only a portion of the resources by using the parameter _summary:

   GET [基地址]/ValueSet?_summary=true

The _summary parameter requests the server to return a subset of the resource. It can contain one of the following values:

trueReturn a limited subset of elements from the resource. This subset SHOULD consist solely of all supported elements that are marked as "summary" in the base definition of the resource(s) (see ElementDefinition.isSummary)
textReturn only the "text" element, the 'id' element, the 'meta' element, and only top-level mandatory elements
dataRemove the text element
countSearch only: just return a count of the matching resources, without returning the actual matches
falseReturn all parts of the resource(s)

The intent of the _summary parameter is to reduce the total processing load on server, client, and resources between them such as the network. It is most useful for resources that are large, particularly ones that include images or elements that may repeat many times. The purpose of the summary form is to allow a client to quickly retrieve a large set of resources, and let a user pick the appropriate one. The summary for an element is defined to allow a user to quickly sort and filter the resources, and typically omit important content on the basis that the entire resource will be retrieved when the user selects a resource.

Servers are not obliged to return just a summary as requested. There are only a limited number of summary forms defined for resources in order to allow servers to store the summarized form(s) in advance. Servers SHOULD mark the resources with the tag SUBSETTED to ensure that the incomplete resource is not accidentally used to overwrite a complete resource.

Note that the _include and _revinclude parameters cannot be mixed with _summary=text.

Implementation Note: There is some question about the inclusion of extensions in the summary. Additional rules may be made around this in the future.

If one of the summary views defined above is not appropriate, a client can request a specific set of elements be returned as part of a resource in the search results using the _elements parameter:

   GET [基地址]/Patient?_elements=identifier,active,link

The _elements parameter consists of a comma-separated list of base element names such as, elements defined at the root level in the resource. Only elements that are listed are to be returned. Clients SHOULD list all mandatory and modifier elements in a resource as part of the list of elements. The list of elements does not apply to included resources.

Servers are not obliged to return just the requested elements. Servers SHOULD always return mandatory elements whether they are requested or not. Servers SHOULD mark the resources with the tag SUBSETTED to ensure that the incomplete resource is not actually used to overwrite a complete resource.

Where a search specifies a non-deterministic sort, the search algorithm may generate a ranking score to indicate which resources meet the specified criteria better than others. The server can return this score in entry.score:

  <entry>
    <score value=".45"/>
    <Patient>
      ... patient data ...
    </Patient>
  </entry>

The score is a decimal number with a value between (and including) 0 and 1, where 1 is best match, and 0 is least match.

In order to allow the client to be confident about what search parameters were used as criteria by the server, the server SHALL return the parameters that were actually used to process the search. Applications processing search results SHALL check these returned values where necessary. For example, if the server did not support some of the filters specified in the search, a client might manually apply those filters to the retrieved result set, display a warning message to the user or take some other action.

In the case of a RESTful search, these parameters are encoded in the self link in the bundle that is returned:

  <link>
    <relation value="self"/>
    <url value="http://example.org/Patient?name=peter"/>
  </link>

In other respects, servers have considerable discretion with regards to supporting search:

  • Servers can choose which parameters to support (other than _id above).
  • Servers can choose when and where to implement parameter chaining, and when and where they support the _include parameter.
  • Servers can declare additional parameters in the profiles referenced from their Capability statements. Servers should define search parameters starting with a "-" character to ensure that the names they choose do not clash with future parameters defined by this specification.
  • Servers are not required to enforce case sensitivity on parameter names, though the names are case sensitive (and URLs are generally case-sensitive).
  • Servers may choose how many results to return, though the client can use _count as above
  • Servers can choose how to sort the return results, though they SHOULD honor the _sort parameter.

The search framework described above is a useful framework for providing a simple search based on indexed criteria, but more sophisticated query capability is needed to handle precise queries, complex decision support-based requests, and direct queries that have human resolution.

More advanced search operations are specified by the _query parameter:

   GET [基地址]/Patient?_query=name&parameters...

The _query parameter names a custom search profile that describes a specific query operation. The named query may define additional named parameters that are used with that particular named query. Servers can define their own additional named queries to meet their own uses using an OperationDefinition.

There can only ever be one _query parameter in a set of search parameters. Servers processing search requests SHALL refuse to process a search request if they do not recognize the _query parameter value.

The results of a search operation are only guaranteed to be current at the instant the operation is executed. After the operation is executed, ongoing actions performed on the resources against which the search was executed will render the results increasingly stale. The significance of this depends on the nature of the search, and the kind of use that is being made of the results.

This is particularly relevant when the server is returning the results in a series of pages. It is at the discretion of the search engine of how to handle ongoing updates to the resources while the search is proceeding.

Performing a search operation does not change the set of resources on the server, with the exception of the creation of Audit Event resources auditing the search itself.

Common Parameters defined for all resources:
NameTypeDescriptionPaths
_idtokenResource id (not a full URL)Resource.id
_lastUpdateddateDate last updated. Server has discretion on the boundary precisionResource.meta.lastUpdated
_tagtokenSearch by a resource tagResource.meta.tag
_profileuriSearch for all resources tagged with a profileResource.meta.profile
_securitytokenSearch by a security labelResource.meta.security
_textstringText search against the narrative
_contentstringText search against the entire resource
_liststringAll resources in nominated list (by id, not a full URL)
_querystringCustom named query
Search Control Parameters:
NameTypeDescriptionAllowable Content
_sortstringOrder to sort results in (can repeat for inner sort orders)Name of a valid search parameter
_countnumber Number of results per pageWhole number
_includestringOther resources to include in the search results that search matches point toSourceType:searchParam(:targetType)
_revincludestringOther resources to include in the search results when they refer to search matchesSourceType:searchParam(:targetType)
_summarystringJust return the summary elements (for resources where this is defined)true | false (false is default)
_containedstringWhether to return resources contained in other resources in the search matchestrue | false | both (false is default)
_containedTypestringIf returning contained resources, whether to return the contained or container resourcescontainer | contained

Cross-map between search parameter types and Data types:

Data Type number date reference quantity uri string token
Primitive Types
base64Binary Not used in search
boolean N N N N N N Y . true|false (System = http://hl7.org/fhir/special-values but not usually needed)
canonical N N N N N N N
code N N N N N N Y . (System, if desired, is defined in the underlying value set for each code)
date N Y N N N N N
dateTime N Y N N N N N
decimal Y N N N N N N
id N N N N N N Y
instant N Y N N N N N
integer Y N N N N N N
markdown Not used in search
oid Not used in search (but see uri)
positiveInt Not used in search (but see integer)
string N N N N N Y Y
time Not used in search
unsignedInt Not used in search (but see integer)
uri N N Y N Y N N
url Not used in search (but see uri)
uuid Not used in search (but see uri)
Data Types
Address N N N N N Y search on any string element in the address N
Age Not used in search
Annotation Not used in search
Attachment Not used in search
CodeableConcept N N N N N N Y
Coding N N N N N N Y
Count Not used in search
ContactPoint N N N N N N Y
Distance Not used in search
Duration N N N Y N N N
HumanName N N N N N Y Search on any string element in the name N
Identifier N N N N N N Y
Money N N N Y N N N
Period N Y N N N N N
Quantity N N N Y N N N
Range N N N Y N N N
Ratio Not used in search
Reference N N Y N N N N
SampledData Not used in search
Signature Not used in search
Timing N Y N N N N N