Current Build

Переводит компания Health Samurai . Приглашаем поучаствовать в русификации стандарта FHIR: GitHub , Email.

FHIR Infrastructure Рабочая группаУровень зрелости: 5Статус голосования: Пробное использование

Поиск ресурсов является основополагающим в механике FHIR. Операции поиска проходят по существующим ресурсам, отфильтровывая их в соответствии с параметрами, переданными операции поиска. Текст ниже описывает систему поиска в FHIR, начиная от простых случаев и заканчивая комплексными. Реализаторам потребуется реализовать только ту часть функциональности, которая им необходима для своих реализаций.

Типы параметров поискаПараметры для всех ресурсовПараметры результатов поиска
Number
Date/DateTime
String
Token
Reference
Composite
Quantity
URI
_id
_lastUpdated
_tag
_profile
_security
_text
_content
_list
_has
_type
_query
_sort
_count
_include
_revinclude
_summary
_elements
_contained
_containedType

Кроме этого, есть ещё один особый параметр _filter для альтернативного метода поиска.

Также есть отдельная страница, где перечислены все поисковые параметры.

В простейшем случае поиск выполняется операцией GET в RESTful-системе:

 GET [base]/[type]?name=value&...{&_format=[mime-type]}}

Для такого RESTful-поиска (см. определение в RESTful API) параметры представляют собой последовательность пар вида имя=[значение] (name=[value]), кодированных в URL [процентная кодировка] или в формате application/x-www-form-urlencoded для [запроса] POST:

 POST  [base]/[type]/_search{?[parameters]{&_format=[mime-type]}}

Сервер определяет, какие ресурсы из набора, который он обслуживает, соответствуют указанным критериям, и возвращает результаты в HTTP-ответе в виде bundle, который включает в себя ресурсы, являющиеся результатами этого поиска. Отметьте, что параметр _format работает с поиском так же, как и с другими операциями.

Операции поиска выполняются в одном из трех заданных контекстов, определяющих, в каком наборе ресурсов будет осуществляться поиск:

  • Определенный тип ресурса: GET [base]/[type]?parameter(s)
  • Определенный модуль, возможно с указанием типа ресурса в этом модуле: GET [base]/Patient/[id]/[type]?parameter(s)
  • Все ресурсы: GET [base]?parameter(s) (только параметры, общие для всех типов)

Операции поиска также могут быть реализованы в фреймворке обмена сообщениями.

Сервер определяет, какие из его ресурсов соответствуют критериям, содержащимся в параметрах поиска, как описано ниже. Однако у сервера имеется привилегия возвращать дополнительные результаты поиска, если он считает их релевантными. Примечание: имеется особый случай поиска наиболее релевантного контекста, в котором поисковый набор является неопределимым - Patient MPI Search.

Поиск с помощью GET может содержать регистрозависимую информацию в параметрах поиска. Поэтому рекомендуется использовать безопасную коммуникацию и контроль точек взаимодействия, см. Security Communications.

The response to any search operation is always a list of resources in a Bundle. An alternative approach is to use GraphQL.

Если сервер не может выполнить поисковый запрос, он возвращает ошибку. HTTP-код состояния 403 говорит о том, что сервер отказался выполнять поиск, в то время как другие коды 4xx и 5xx означают, что произошла некоторая ошибка. Если поиск не выполнился, сервер ДОЛЖЕН вернуть OperationOutcome в указанием причины неудачи. Примечание: пустой результат поиска не считается неудачей.

В некоторых случаях параметры могут вызвать ошибку. Например:

  • В параметре может быть указан несуществующий ресурс, например GET [base]/Observation?subject=101, где "101" не существует
  • В параметре может быть указан неизвестный код, напримерGET [base]/Observation?code=loinc|1234-1, где LOINC-код "1234-1" не известен серверу
  • В параметре может быть указано время вне допустимого диапазона, например GET [base]/Condition?onset=le1995, когда система имеет данные только начиная с 2001 года
  • В параметре может быть использован запрещённый или недопустимый модификатор, например GET [base]/Condition?onset:text=1995, где этот модификатор не может быть обработан сервером
  • Параметр даты/времени может иметь неправильный формат, например GET [base]/Condition?onset=23%20May%202009
  • Параметр может быть неизвестен или не поддерживаться (см. ниже)

Если содержимое параметра синтаксически неправильное, сервер ДОЛЖЕН вернуть ошибку. Однако если проблема в логическом условии (например указан неизвестный "subject" или "code"), сервер ДОЛЖЕН обработать поиск с указанным параметром - результатом будет пустой результат поиска, поскольку такой параметр не может быть выполнен.

В таких случаях процесс поиска МОЖЕТ включать OperationOutcome в поисковый набор, который содержит дополнительный подсказки и предупреждения относительно процесса поиска. В результаты поиска это входит в виде записи "entry" с search mode = outcome. Клиенты могут использовать эту информацию для улучшения последующих поисков.

Неизвестные и неподдерживаемые параметры

Сервер может получить от клиента параметры, которые он не распознаёт или распознаёт, но не поддерживает (либо вообще, либо в конкретном случае). В общем случае сервер ДОЛЖЕН игнорировать неизвестные или неподдерживаемые параметры по следующим причинам:

  • Различные HTTP-стеки и прокси могут добавлять параметры, которые клиент не контролирует.
  • Клиент может определить, какие параметры сервер использовал, рассматривая "self"-ссылку в ответе сервера (см. ниже)

Клиенты могут указывать желаемое поведение сервера, используя заголовок "prefer".

  • Prefer: handling=strict: Клиент говорит серверу возвращать ошибку для всех неизвестных или неподдерживаемых параметров.
  • Prefer: handling=lenient: Клиент говорит серверу игнорировать все неизвестные или неподдерживаемые параметры.

Сервер ДОЛЖЕН выполнять требование клиента, но не обязан это делать.

Эти параметры описаны здесь и применяются ко всем ресурсам: _content, _id, _lastUpdated, _profile, _query, _security, _source, _tag. Кроме того, параметры поиска _text и _filter (задокументированы ниже) также применяются ко всем ресурсом (как и параметры результатов поиска).

Параметр поиска _id относится к логическому id ресурса и может быть использован, когда в качестве контекста поиска указан тип ресурса:

 GET [base]/Patient?_id=23

В этом примере поиска ищется ресурс patient с указанным id (может быть только один ресурс с таким id). С функциональной точки зрения это эквивалентно простой операции чтения:

 GET [base]/Patient/23

Однако поиск с параметром _id возвращает бандл с запрашиваемым ресурсом, а не просто сам этот ресурс. Могут быть добавлены дополнительные параметры, которые предоставят дополнительную функциональность к этой базовой, эквивалентной чтению (например _include). Отметьте, что хотя параметр _id и имеет тип "токен", у него нет системы, так как сервер должен искать по точному соответствию с ним.

Параметр поиска _lastUpdated может использоваться для выбора ресурсов по дате их последнего изменения:

 GET [base]/Observation?_lastUpdated=gt2010-10-01

В этом примере поиска ищутся все Observations, измененные после 1-Окт 2010. При использовании этого параметра поиска приложениям следует принимать во внимание подходы к синхронизации (RESTful история или ресурс Subscription.

Поисковые параметры _tag, _profile и _security ищут совпадения по эквивалентным элементам в элементе meta. К примеру,

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

ищет все ресурсы Condition с тегом:

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

Таким же образом:

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

ограничивает поиск только ресурсами DiagnosticReport с тегом, что согласуется с определенным профилем. Вторая ссылка относительная и ссылается на локальный профиль на том же сервере.

Параметры _tag, _profile и _security имеют тип "токен" (см. ниже).

Кроме параметра _id, который применяется ко всем ресурсам, каждый тип FHIR-ресурса определяет свой собственный набор параметров поиска по именам, типам и значениям. Эти параметры поиска можно найти на той же самой странице, где и определения ресурса, также они опубликованы как часть стандартного заявления о возможностях - Capability statement (XML или JSON).

Как правило, заданные параметры поиска соответствуют одному элементу в ресурсе, однако это не является обязательным, и некоторые параметры поиска относятся к одному типу элемента в нескольких местах или относятся к их значениям.

Некоторые параметры поиска, заданные ресурсами, ассоциируются с более чем одним путем в ресурсе. Это означает, что соответствие такому параметру поиска выполняется в случае, когда любой из путей содержит совпадающее содержимое. Если путь соответствует, ресурс целиком возвращается в результатах поиска. Клиенту может потребоваться проверить ресурс, чтобы определить, который из путей содержит совпадение.

Серверам не обязательно реализовывать ни один из этих параметров поиска (за исключением параметра _id, описанного выше), и они могут определять свои собственные параметры.

Каждый параметр поиска указывается с типом, который определяет способ поведения параметра поиска. Далее следуют определения типов параметров:

numberSearch parameter SHALL be a number (a whole number, or a decimal).
dateSearch parameter is on a date/time. The date format is the standard XML format, though other formats may be supported.
stringSearch parameter is a simple string, like a name part. Search is case-insensitive and accent-insensitive. May match just the start of a string. String parameters may contain spaces.
tokenSearch parameter on a coded element or identifier. May be used to search through the text, displayname, code and code/codesystem (for codes) and label, system and key (for identifier). Its value is either a string or a pair of namespace and value, separated by a "|", depending on the modifier used.
referenceA reference to another resource.
compositeA composite search parameter that combines a search on two values together.
quantityA search parameter that searches on a quantity.
uriA search parameter that searches on a URI (RFC 3986).

К этим параметрам поиска могут также добавляться "модификаторы", которые управляют их поведением. Виды модификаторов, которые могут использоваться, зависят от типа параметра, который требуется модифицировать.

Параметры определены для каждого ресурса. К имени параметра может добавляться модификатор в виде суффикса. Такие модификаторы отделяются от имени параметра двоеточием. Модификаторами являются:

  • Для всех параметров (кроме комбинации): :missing, например gender:missing=true (or false). Поиск по gender:missing=true вернет все ресурсы, которые не имеют никакого значения параметра gender (что, как правило, приравнивается к отсутствию соответствующего элемента в ресурсе). Поиск по gender:missing=false вернет все ресурсы, имеющие значение параметра gender.
  • Для строки: :exact (совпадение должно быть точным, не частичным совпадением, чувствительным к регистру и диакритическим знакам), либо :contains (регистронезависимый и не чувствительный к диакритическим знакам, частичное совпадение в начале или в конце), вместо поведения по умолчанию (регистронезависимый и не чувствительный к диакритическим знакам, частичное совпадение в начале или в конце)
  • Для лексемы (token): :text (совпадение совершает частичные поиски по части text в CodeableConcept или части display в Coding), вместо поиска по умолчанию, который использует коды. Другие модификаторы :in, :below, :above и :not-in описаны ниже.
  • Для ссылки: :[type], где [type] - это имя типа ресурса.
  • Для uri: :below, :above означают, что вместо точного совпадения значению соответствует либо левосторонний поиск, либо наоборот.

Сервер ДОЛЖЕН отклонять любые запросы поиска, которые содержат суффиксы-модификаторы, которые сервер не поддерживает для данного параметра. К примеру, если сервер поддерживает параметр поиска name, но не его модификатор :exact, ему следует отклонять поиск с параметром name:exact=Bill и возвращать HTTP-ошибку 400 и OperationOutcome с чётким сообщением об ошибке.

Для упорядоченных параметров типа number, dateи quantity, префикс к значению параметра может быть использован для управления характером поиска совпадения. Чтобы избежать экранирования URL-строки и визуальной путаницы, используются следующие префиксы:

eq значение параметра в ресурсе равно указанному значению диапазон значения поиска целиком содержит диапазон искомого значения
ne значение этого параметра в ресурсе не равно указанному значению диапазон значения параметра поиска не полностью содержит диапазон искомого значения
gt значение этого параметра в ресурсе больше, чем указанное значение диапазон выше значения поиска пересекается (т. е. частично совпадает) с диапазоном искомого значения
lt значение этого параметра в ресурсе меньше, чем указанное значение диапазон ниже значения поиска пересекается (т. е. частично совпадает) с диапазоном искомого значения
ge значение этого параметра в ресурсе больше или равно указанному значению диапазон выше значения поиска пересекается (т. е. перекрывает) диапазон искомого значения, либо диапазон значения поиска полностью содержит диапазон искомого значения
le значение этого параметра в ресурсе меньше или равно указанному значению диапазон ниже значения поиска пересекается (т.е. перекрывает) диапазон искомого значения, либо диапазон значения поиска полностью содержит диапазон искомого значения
sa значение этого параметра в ресурсе начинается после указанного значения диапазон значения параметра не пересекается с диапазоном искомого значения, а диапазон выше поискового значения содержит диапазон искомого значения
eb значение параметра в ресурсе заканчивается до указанного значения диапазон поискового значения не пересекается с диапазоном искомого значения, а диапазон ниже поискового значения содержит диапазон искомого значения
ap значение этого параметра в ресурсе приблизительно равно указанному
Отметьте, что рекомендуемое значение приближения - 10% от указанного (либо для даты это будет 10% промежуток между текущим и датой), однако системы могут использовать и другие значения на свой выбор
диапазон поискового значения пересекается с диапазоном искомого значения

Если префикс не указан, то считается, что это eq. Обратите внимание, что способ работы параметров поиска отличается от способа работы операций над двумя числами в математическом смысле. sa (starts-after) и eb (ends-before) не используются для целых чисел.

Для каждого префикса, приведённого выше, указаны две интерпретации - назначение префикса и интерпретация этого параметра при применении к диапазонам. Интерпретация диапазонов приведена для десятичных чисел и дат.

границы интервала Пределы, вытекающие из точности значения Число 2.0 имеет диапазон от 1.95 до 2.05
Дата 2015-08-12 имеет диапазон от 00:00 до 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

Обсуждение надлежащего использования этих интервалов будет продолжено ниже.

Примеры поиска простых численных значений в ресурсе:

[parameter]=100Значения, равные 100 с точностью до 3 значимых знаков, таким образом это будет диапазон [99.5 ... 100.5)
[parameter]=100.00Значения, равные 100 с точностью до 5 значимых знаков, таким образом это будет диапазон [99.995 ... 100.005). Целые числа также равны 100.00, но не 100.01
[parameter]=lt100Значения меньше 100
[parameter]=le100Значения, которые меньше или равны 100
[parameter]=gt100Значения больше 100
[parameter]=ge100Значения, которые больше или равны 100
[parameter]=ne100Значения, которые не равны 100

Примечание: неточность не играет роли при вычислениях. Точность чисел полагается произвольно высокой. (То, как параметры поиска работают в ресурсах, отличается от того, являются ли два числа равными друг другу в математическом смысле).

Вот несколько примеров поиска:

ПоискОписание
 GET [base]/Encounter?length=gt20
Поиск всех визитов, длившихся более 20 дней
 GET [base]/ImmunizationRecommendation?deo-number=2
Поиск всех рекомендаций по иммунизации, рекомендующих вторую дозу

Параметр даты ищет по дате/времени или периоду. Как это принято для функциональности, связанной с датой/временем, хотя эти понятия и являются относительно простыми, имеется целый ряд тонкостей, связанных с обеспечением их согласованного поведения.

Формат параметра даты следующий: yyyy-mm-ddThh:mm:ss[Z|(+|-)hh:mm] (стандартный XML-формат).

Технически, им является любой из типов данных date, dateTime и instant; при этом может указываться любая степень точности даты, однако она ДОЛЖНА идти слева направо (т. е. нельзя указать месяц без года), за исключением того, что минуты ДОЛЖНЫ присутствовать, если указан час, и вы ДОЛЖНЫ указать часовой пояс, если присутствует время. Примечание: временнАя часть даты может состоять из часов и минут без секунд, в отличие от типа dateTime XML-схемы. Некоторые пользовательские агенты могут экранировать символы : в URL, и серверы ДОЛЖНЫ корректно обрабатывать это.

Параметры даты можно использовать со следующими типами данных:

dateВ диапазон этого значения входит день, месяц или год, смотря что указано
dateTimeЭто значение включает в себя диапазон в соответствии с указанным выше; например дата 2013-01-10 обозначает любое время от 00:00 10 января 2013 непосредственно до 00:00 11 января 2013
instantМгновением считается фиксированный момент времени с интервалом меньшим, чем точность системы, т. е. интервал с эффективной шириной 0
PeriodПериод, хотя верхняя или нижняя граница может быть в действительности не указана в ресурсах.
Timingуказанные детали расписания игнорируются и имеют значение только внешние пределы. К примеру, расписание "каждый второй день между 31 января 2013 г. и 24 марта 2013 г." включает в себя 1 февраля 2013 г., даже при том, что это нечетный день, не соответствующий правилу расписания. Это сделано для уменьшения загрузки сервера.

Неявно, опущенная нижняя граница "меньше", чем любая реальная дата. Опущенная верхняя граница "больше", чем любая реальная дата. Применение префиксов:

[parameter]=eq2013-01-14
  • 2013-01-14T00:00 подходит (очевидно)
  • 2013-01-14T10:00 подходит
  • 2013-01-15T00:00 не подходит, т.к. не входит в диапазон
[parameter]=ne2013-01-14
  • 2013-01-15T00:00 подходит, т.к. не входит в диапазон
  • 2013-01-14T00:00 не подходит, т.к. входит в диапазон
  • 2013-01-14T10:00 не подходит, т.к. входит в диапазон
[parameter]=lt2013-01-14T10:00
  • 2013-01-14 подходит, поскольку содержит часть 14 января 2013 до 10 утра
[parameter]=gt2013-01-14T10:00
  • 2013-01-14 подходит, поскольку содержит часть 14 января 2013 после 10 утра
[parameter]=ge2013-03-14
  • "с 21 января 2013 и далее" входит в указанный диапазон, поскольку он включает в себя любые даты позже 14 марта 2013
[parameter]=le2013-03-14
  • "с 21 января 2013 и далее" входит в указанный диапазон, поскольку он включает в себя любые даты до 14 марта 2013
[parameter]=sa2013-03-14
  • "с 15 марта 2013 и далее" подходит, поскольку that period starts after 14 марта 2013
  • "с 21 января 2013 и далее" не подходит, поскольку начинается до 14 марта 2013
  • "до 21 января 2013 включительно" не подходит, поскольку начинается (и заканчивается) до 14 марта 2013
[parameter]=eb2013-03-14
  • "с 15 марта 2013 и позже" не подходит, т.к. начинается после 14 марта 2013
  • "с 21 января 2013 и позже" не подходит, т.к. начинается до 14 марта 2013, однако заканчивается позже этой даты
  • "до 21 января 2013 включительно" не подходит, т.к.заканчивается до 14 марта 2013
[parameter]=ap2013-03-14
  • 14 марта 2013 - подходит, т.к. это точное совпадение
  • 21 января 2013 - не подходит, т.к. не рядом с 14 марта 2013
  • 15 января 2015 - не подходит, т.к. не рядом с 14 марта 2013. Обратите внимание, что точное значение здесь находится на усмотрении системы.

Другие примечания:

  • Когда параметр даты указан не полностью, совпадения с ним основываются на поведении интервалов, где:
    • Даты, где указан только год, эквивалентны интервалу, который начинается в первое мгновение 1го января до последнего мгновения 31го декабря, например 2000 эквивалентно интервалу [2000-01-01T00:00, 2000-12-31T23:59]
    • Даты, где указан год и месяц, эквивалентны интервалу, который начинается в первое мгновение первого дня месяца и заканчивается в последнее мгновение последнего дня этого месяца, например 2000-04 эквивалентно интервалу [2000-04-01T00:00, 2000-04-30T23:59].
  • Везде, где это возможно, система должна корректировать часовые пояса при совершении запросов. Даты не имеют часовых поясов, и часовые пояса не должны учитываться. Там, где и параметр поиска, и дата время элемента ресурса не имеют часового пояса, им следует присваивать локальный часовой пояс сервера.

Чтобы найти все процедуры в модуле patient, которые произошли за двухлетний период:

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

Для простого текстового поиска строковый параметр служит как входные данные для регистронезависимого и нечувствительного к диакритическим знакам поиска по последовательностям символов. По умолчанию, поле соответствует строковому запросу, если значение этого поля равно или начинается со значения указанного параметра, после того как они оба были приведены к одному регистру и диакритическим знакам. Модификатор :contains возвращает результаты. которые включают в себя значение указанного параметра в любом месте в пределах области поиска. Модификатор :exact возвращает результаты, которые соответствуют указанному параметру полностью, включая регистр и диакритические знаки.

Примеры:

[base]/Patient?given=eveВсе пациенты с именем, содержащим заданную часть "eve" в начале имени. Сюда войдут пациенты с (given) именами "Eve", "Evelyn".
[base]/Patient?given:contains=eveВсе пациенты с именем, содержащим заданную часть "eve" в любом месте имени. Сюда войдут пациенты с (given) именами "Eve", "Evelyn", а также "Severine".
[base]/Patient?given:exact=EveВсе пациенты с именем с заданной частью в точности "Eve". Примечание: сюда не войдут пациенты с (given) именами "eve" или "EVE".

Дополнительный модификатор :text можно использовать для указания поиска с расширенными возможностями управления текста (см. ниже), однако такую возможность предлагает только несколько серверов.

Когда строковый параметр поиска ссылается на типы HumanName и Address, поиск идёт по элементам типа "string" и не охватывает такие элементы, как use и period. Для надёжности, сервер должен искать по элементам фамилии независимо. Например оба поиска по фамилии Carreno и по фамилии Quinones должны вернуть пациента с фамилией "Carreno Quinones". Филиалы HL7 могут вводить особые рекомендации по работе поиска в соответствии с культурой их страны.

Решение о том, делать ли предварительную обработку имен, адресов и контактной информации для удаления символов-разделителей до нахождения соответствия, чтобы гарантировать непротиворечивое поведение, остаётся на усмотрение сервера. Например сервер мог бы удалить все пробелы и символы - из телефонных номеров. Что лучше всего подходит, варьируется в зависимости от культуры и контекста. Сервер может также использовать свободный текстовый поиск по этому свойству для достижения наилучших результатов. При поиске по целому имени и адресу (не по их частям), сервер может также использовать гибкое соответствие или свободный текстовый поиск по именам для достижения наилучших результатов.

Параметр URI относится к элементу URI (RFC 3986 ). Совпадения являются точными (регистр, диакритические знаки, экранирование), и весь URI целиком должен совпадать. С помощью модификатора :above или :below можно указать, что используется частичное совпадение. Например:

 GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123
 GET [base]/ValueSet?url=http://acme.org/fhir/
 GET [base]/ValueSet?url=urn:oid:1.2.3.4.5

Первый запрос - поиск набора значений с точным URL "http://acme.org/fhir/ValueSet/123". Второй запрос вернет все наборы значений, у которых URL начинается с "http://acme.org/fhir/". Обратное утверждение - поиск всех наборов значений, кроме данного конкретного URL - может пригодиться для поиска систем назначения имён, но не так полезно, чем поиск с :below. На третьей строке показан пример поиска по OID. Отметьте, что модификаторы :above и :below применяются только к URL-ссылкам, а не к URN-именам (т.е. к OID не применяются).

Отметьте, что для канонических URL-ссылок сервер ДОЛЖЕН поддерживать поиск по каноническим URL-ссылкам, ДОЛЖЕН автоматически обнаруживать в них часть |[version] и интерпретировать её как поиск по версии.

Тип "токен" - это параметр для поиска точного соответствия по строке символов, потенциально ограниченный некоторым URI. Используется в основном для типов данных code и identifier, где значение может иметь URI, который ограничивает его значение, где поиск выполняется по паре из Coding или Identifier. Токены также часто используют для поиска по другим полям, когда требуется точное соответствие - это URI, булевы значения и ContactPoints. В этих случаях часть параметра для поиска по URI не используется.

Поиск совпадения по токену должен быть буквальным (например не на основе отнесения к определённой категории или других особенностей использования кодовых систем), но не чувствительным к регистру. Для поиска с применением логики классификации используйте модификаторы ниже или перечисляйте все коды в иерархии. Синтаксис для такого значения будет одним из следующих:

  • [parameter]=[code]: значение [code] совпадает с Coding.code или Identifier.value не зависимо от значения свойства "system"
  • [parameter]=[system]|[code]: значение [code] совпадает с Coding.code или Identifier.value, а значение [system] совпадает со значением свойства "system" в Identifier или Coding
  • [parameter]=|[code]: значение [code] совпадает с Coding.code или Identifier.value, а Coding/Identifier не содержит свойства "system"
  • [parameter]=[system]|: любой элемент, в котором значение [system] совпадает со свойством "system" Identifier или Coding

Примечание: URI и код пространства имен необходимо корректно экранировать. Если систему указать невозможно (например это элемент типа uri), тогда используется просто форма [parameter]=[code].

Параметры поиска по лексемам используются для следующих типов данных:

Тип данных URI Код Комментарий
Coding Coding.system Coding.code
CodeableConcept CodeableConcept.coding.system CodeableConcept.coding.code Поиск совпадений по всем coding в CodeableConcept
Identifier Identifier.system Identifier.value
ContactPoint ContactPoint.use ContactPoint.value The use is prepended by http://hl7.org/fhir/contact-point-system/
code (implicit) code система определена в наборе значений (хотя обычно не требуется)
boolean (implicit) boolean Неявно это система http://hl7.org/fhir/special-values
string n/a string Токен иногда используют для поиска по строкам, чтобы указать поиск по точному соответствию как корректную стратегию по умолчанию

Примечание: Использование параметров поиска по лексемам для булевых полей: булевы значения "true" и "false" также представлены в виде формальных кодов в кодовой системе Special Values, которая полезна, когда булевы значения нужно представить в виде типа данных Coding. Пространство имён для этих кодов - http://hl7.org/fhir/special-values, однако обычно нет причин использовать это, поскольку достаточно и простых значений true или false.

Модификаторы :

Модификатор Применение
:text Этот параметр поиска обрабатывается как строка поиска по тексту, ассоциированному с кодом/значением - CodeableConcept.text, Coding.display, либо Identifier.type.text.
:not Изменяет на противоположное совпадение по коду, описанное в параграфе выше. 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 Параметром поиска является концепт с формой [system]|[code], и он проверяет, включает ли (subsumes) кодинг в ресурсе указанный в поиске код. Например поисковый концепт имеет связь "is-a" с кодингом в ресурсе, и сюда входит сам кодинг.
:below Параметром поиска является концепт с формой [system]|[code], и он проверяет, относится ли кодинг в ресурсе к указанному в поиске коду. Например кодинг в ресурсе имеет связь "is-a" с поисковым концептом, и сюда входит сам кодинг.
:in Параметром поиска является URI (относительный или абсолютный), который идентифицирует набор значений, и поисковый параметр проверяет, входит ли кодинг в указанный набор значений. Ссылка может быть буквальной (адрес, где находится этот набор значений) или логической (ссылка на ValueSet.identifier). Если сервер может обработать эту ссылку как буквальный URL, он это делает, иначе пытается найти соответствие в известных логических значениях ValueSet.url.
:not-in Параметром поиска является URI (относительный или абсолютный), который идентифицирует набор значений, и поисковый параметр проверяет, что кодинг не входит в указанный набор значений.

Большинство серверов будут обрабатывать только заранее известные/зарегистрированные/поддерживаемые внутренние наборы значений. Однако серверы по выбору могут принимать любые валидные ссылки на наборы значений. Серверы по выбору могут учитывать таблицы соответствий концептов при проверке связей категоризации (отнесения объекта к определённой категории).

Примеры запросов:

ПоискОписание
 GET [base]/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 [base]/Patient?gender=male
Search for any patient with a gender that has the code "male"
 GET [base]/Patient?gender:not=male
Search for any patient with a gender that does not have the code "male"
 GET [base]/Patient?active=true
Search for any patients that are active
 GET [base]/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 [base]/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 [base]/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 [base]/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 [base]/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 [base]/Condition?code:in=http://acme.org/fhir/ValueSet/cardiac-conditions
Search for any condition that is in the institutions list of cardiac conditions

Параметр quantity ищет по типу данных Quantity. Синтаксис для значения соответствует следующей форме:

  • [parameter]=[prefix][number]|[system]|[code] соответствует количеству с заданными единицами измерения

Префикс является необязательным и, как описано выше, зависит от того, как интерпретируются точность и операторы сравнения/диапазона. Примеры поиска:

ПоискОписание
 GET [base]/Observation?value=5.4|http://unitsofmeasure.org|mg
Search for all the observations with a value of 5.4 mg where mg is understood as a UCUM unit (system/code)
 GET [base]/Observation?value=5.4||mg
Search for all the observations with a value of 5.4 mg where the unit - either the code or the stated human unit (unit) are "mg"
 GET [base]/Observation?value=le5.4|http://unitsofmeasure.org|mg
Search for all the observations where the value of is less than 5.4 mg where mg is understood as a UCUM unit
 GET [base]/Observation?value=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

Поисковый процессор может решить выполнить поиск, основанный на канонических единицах измерений (например любое значение, которое может быть преобразовано в значение в миллиграммах, для случая выше).

Ссылочный параметр относится к ссылкам между ресурсами. Например найти все Conditions, где объектом ссылки является определённый пациент, где пациент выбирается по имени или идентификатору. Интерпретация параметра ссылка одна из двух:

  • [parameter]=[id] the logical [id] of a resource using a local reference (i.e. a relative reference)
  • [parameter]=[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)
  • [parameter]=[url] where the [url] is an absolute URL - a reference to a resource by its absolute location

Примечание: относительная ссылка, разрешаемая в то же значение, что и указанный абсолютный URL-адрес, либо наоборот, также считается совпадением. К примеру, если значением параметра поиска является Patient/123, тогда будут найдены подобные ссылки:

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

Если базовый адрес сервера http://example.org/fhir, тогда полный URL-адрес для этой ссылки будет ttp://example.org/fhir/Patient/123, что означает, что условию поиска будут соответствовать такие ссылки, как:

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

Кроме того, поиск reference=http://example.org/fhir/Patient/123 соответствует обеим ссылкам.

Некоторым ссылкам можно указывать на более чем один тип ресурса; например subject : Reference(Patient|Group|Device|..). В этом случае несколько ресурсов могут иметь одинаковый логический идентификатор. Серверы ДОЛЖНЫ отклонять поиск, где логический идентификатор ссылается более чем на один соответствующий поиску ресурс среди различных типов. Для того чтобы дать возможность клиенту выполнять поиск в таких ситуациях, тип указывается явно:

 GET [base]/Observation?subject=Patient/23

Это запрос возвращает все ресурсы observations, у которых "subject" ведёт на ресурс Patient с логическим идентификатором "23". Также определён модификатор, чтобы клиенты могли явно указывать нужный тип:

 GET [base]/Observation?subject:Patient=23

Этот запрос возвращает те же результаты, что и предыдущий. Модификатор становится полезным, когда используется в цепочечных запросах, о которых будет рассказано в следующем разделе. Примечание: модификатор [type] нельзя использовать со ссылкой на ресурс, расположенный на другом сервере, поскольку серверу обычно не известно, какой тип имеет этот ресурс. Однако, поскольку это абсолютные ссылки, не может возникнуть неоднозначность относительно типа.

В некоторых случаях параметры поиска определены неявно областью действия. К примеру, в ресурсе Observation есть элемент subject, это ссылка на один из нескольких типов. Этому элементу соответствует параметр поиска subject, который ищет по любому из возможных типов. Кроме этого, есть другой параметр поиска patient, который ищет по элементу Observation.subject, но ограничен ссылками только типа Patient. При использовании параметра поиска patient нет необходимости указывать модификатор ":Patient" или добавлять "Patient/" к строке поиска, т.к. это условие и так будет соблюдено.

Чтобы избавить клиента от необходимости выполнять серию операций поиска, ссылочные параметры могут быть "сцеплены" (объединены в последовательность) добавлением к ним точки ., за которой следует имя параметра поиска, указанного для целевого ресурса. Это может быть сделано рекурсивно, следуя логическому пути через граф связанных ресурсов, разделенных точкой .. К примеру дано, что ресурс DiagnosticReport имеет параметр поиска с именем subject, который обычно является ссылкой на ресурс Patient, и этот ресурс Patient содержит параметр name, который ищет по имени пациента, тогда поиск вида

 GET [base]/DiagnosticReport?subject.name=peter

- это запрос на возвращение всех лабораторных отчетов, в которых имеется объект, чье имя содержит "peter". Так как объект Diagnostic Report может быть одним из набора различных ресурсов, необходимо ограничить поиск определенным типом:

 GET [base]/DiagnosticReport?subject:Patient.name=peter

Этот запрос возвращает все лабораторные отчеты, имеющие в качестве объекта пациента, чье имя содержит "peter".

Примечание к расширенным возможностям поиска: Когда цепочечный параметр ищет ссылку на ресурс, целевым объектом которой может быть более одного типа ресурса, цепочка параметров может оканчиваться ссылкой на поисковые параметры с тем же самым именем на более чем одном типе ресурса одновременно. Серверы ДОЛЖНЫ отклонять поиск, в котором логический идентификатор ведёт на более чем один совпадающий ресурс среди различных типов. Например клиент должен указать тип явным образом, используя синтаксис во втором примере выше.

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 [base]/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 [base]/Patient?_has:Observation:subject:code=123,456), and multiple _has parameters are allowed (e.g. GET [base]/Patient?_has:Observation:subject:code=123&_has:Observation:subject:code=456). Note that each _has parameter is processed independently of other _has parameters.

The _has parameter can be chained, like this:

GET [base]/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.

Составные параметры поиска поддерживают объединение отдельных значений с помощью $. Например результатом операции поиска будет пересечение ресурсов, которые соответствуют критериям каждого поискового параметра по отдельности. Если параметр повторяется, например /Patient?language=FR&language=NL, тогда это соответствует пациенту, который говорит на обоих языках. Этот параметр поиска называется "AND", поскольку предполагается, что сервер вернёт только те результаты, которые соответствуют обоим значениям.

Если вместо этого поиск должен найти пациентов, которые говорят на одном из этих языков, тогда это будет один параметр с несколькими значениями, разделёнными запятой ,. Например /Patient?language=FR,NL. Этот параметр поиска называется "OR", поскольку предполагается, что сервер вернёт результаты, которые соответствуют одному из значений.

AND и OR параметры можно комбинировать, например /Patient?language=FR,NL&language=EN относится к любому пациенту, который говорит по-английски, а также по-французски или по-голландски.

Такой подход позволяет использовать простые комбинации AND/OR-значений, но не даёт возможности поиска на основе пар значений, например все наблюдения со значением натрия >150 ммоль/л (особенно в качестве последнего критерия цепочечного поиска), или поиск по Group.characteristic, где вам нужно найти комбинацию ключ/значение, а не пересечение отдельных совпадений по ключу и значению. Другим примером будут пространственные координаты при выполнении географических поисков.

Чтобы подобные поиски были возможны, ресурс может также указать составные параметры, которые принимают последовательности отдельных значений, которые соответствуют другим заданным параметрам в качестве аргумента. Соответствующий параметр каждого компонента в такой последовательности документируется в определении этого параметра. Эти последовательности формируются присоединением отдельных значений символом $. Примечание: эта последовательность является отдельным значением и сама может состоять из набора значений, чтобы, к примеру, несколько соответствующих параметров в состоянии на сегодняшнюю дату можно было указать как state-on-date=new$2013-05-04,active$2013-05-05.

Примечание: модификаторы в составных параметрах не используются.

Примеры использования составных параметров:

ЗапросОписание
 GET [base]/DiagnosticReport?result.code-value-quantity=http://loinc.org|2823-3$gt5.4|http://unitsofmeasure.org|mmol/L
Поиск всех диагностических отчётов, которые содержат наблюдение со показателем калия >5.4 ммоль/л (UCUM)
 GET [base]/Observation?component-code-value-quantity=http://loinc.org|8480-6$lt60
Поиск всех наблюдений с показателем систолического кровяного давления < 60. Отметьте, что в этом случае единицы измерения предполагаются (все используют мм рт. ст.)
 GET [base]/Group?characteristic-value=gender$mixed
Поиск всех групп с характеристикой "gender", имеющей текстовое значение "mixed"

Consider the case of searching for all AllergyIntolerance resources:

GET [base]/AllergyIntolerance?clinical-status=active

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

{
  "resourceType" : "AllergyIntolerance",
  "clinicalStatus" : "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 [base]/AllergyIntolerance?clinical-status=active
GET [base]/AllergyIntolerance?clinical-status:exists=false

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 [base]/AllergyIntolerance?clinical-status=active&clinical-status:exists=false

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

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

В правилах, описанных выше, введены особые правила для символом $, , и |. Как следствие, если эти символы появляются в реальном значении параметра, они должны различаться от своего использования в качестве символов-разделителей. Когда любой из этих символов появляется в реально значении параметра, они должны экранироваться символом \, который также должен использоваться для экранирования самого себя. Следовательно param=xxx$xxx означает, что это составной параметр, а param=xx\$xx означает, что этот параметр имеет буквальное значение xx$xx. Значение параметра xx\xx является допустимым, а значение параметра param=xx\\xx означает, что это буквальное значение xx\xx.

Данная спецификация задаёт эту дополнительную форму экранирования не случайно. Классическое экранирование вида %xx, являющееся частью стандартных HTTP URL-адресов, гарантирует, что символ будет передан на FHIR-сервере корректно, в то время как , против \ становится важным, как только он достигает сервера и запрос начинает обрабатываться. Поэтому:

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

использует URL-экранирование для гарантии того, что FHIR-сервер получит:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124,125

Этот запрос сравнит этот URL с тремя значениями: последнее является относительным и некорректным URL, что маловероятно является фактическим намерением. Однако:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,125

эквивалентно:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\%2C125

что означает: url = http://.....123 OR http://....124,125 .

Особые параметры поиска по тексту _text и _content ищут по описательной части ресурса и полному содержимому ресурса соответственно. Эти параметры ДОЛЖНЫ поддерживать функциональность сложного поиска этого типа, предлагаемого типичными службами индексирования текста. Значение этого параметра - это поиск на основе текста, который может включать поиск нескольких слов со словарём и соображения родства, а также такие логические операции, как AND, OR и др. Например:

 GET [base]/Condition?_text=(bone OR liver) and metastases

Этот запрос возвращает все ресурсы Condition со словом "metastases" и либо словом "bone", либо "liver" в описательной части. Сервер МОЖЕТ решить также искать родственные слова.

Примечание к DSTU: проблемы, связанные со стандартизацией текстового поиска, решены не полностью. Во время периода пробного использования данной спецификации, мы рекомендуем системам использовать правила, описанные спецификацией OData для параметра $search . Типичные реализации могут использовать Lucene - полнотекстовый поиск на основе SQL, или какую-нибудь службу индексирования.

Будем благодарны за ваши отзывы .

Параметр _list позволяет извлекать ресурсы, на которые ссылается ресурс List.

 GET [base]/Patient?_list=42

Этот запрос возвращает все ресурсы Patient, на которые есть ссылки в списке, найденном по пути [base]/List/42 в List.entry.item. Хотя и можно извлечь список и затем пройти по записям в этом списке, извлекая каждого пациента, использование списка в качестве критерия поиска позволяет указывать дополнительные критерии поиска. К примеру:

 GET [base]/Patient?_list=42&gender=female

Этот запрос вернёт всех пациентов женского пола из списка. Сервер может вернуть список, на который ссылается параметр поиска, в качестве включённого ресурса, но не обязан делать это. Дополнительно, система может поддерживать поиск по спискам в качестве своей логической функции. Например:

 GET [base]/AllergyIntolerance?patient=42&_list=$current-allergies

Этот запрос вернёт все аллергии из "Текущего списка аллергий" пациента с идентификатором 42. Сервер вернёт все релевантные ресурсы AllergyIntolerance, а также может по желанию вернуть этот список. За более подробной информацией обращайтесь к определению "$current-allergies" и операции со списками "Find". Примечание: серверы не обязаны давать клиентам доступ к этим спискам как к ресурсам List, но могут делать это по желанию.

Механизм поиска, описанный выше, является гибким и легко реализуемым для простых случаев, однако он ограничен в своей возможности выражать комбинированные запросы. В дополнение к этому механизму можно использовать параметр "_filter".

Например "найти все наблюдения пациента с именем, включающим peter, где есть LOINC-код 1234-5":

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

Используя параметр _filter, запрос может быть выражен так:

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

Более подробно параметр _filter описан на странице "Параметр _Filter".

Обычно поиск вызывается по известному типу ресурса, например:

GET [base]/Observation?params...

Однако в некоторых обстоятельствах поиск выполняется без фиксированного типа ресурса:

  • Использование поиска по всем типам ресурсов (GET [base]?params...)
  • Использование поиска в обмене сообщениями
  • Некоторые спецификации поиска внутри других сервисов, например применение поддержки принятия решений

В этих случаях в критериях поиска может потребоваться указать один или несколько типов ресурсов, по которым будет вестись поиск. Это можно сделать с помощью параметра _type:

GET [base]/?_type=Observation,Condition&other params...

Отметьте, что только базовые параметры поиска можно использовать для глобального поиска наподобие этого, которые применяются ко всем ресурсам. В других контекстах для поиска по нескольким типам можно использовать специфичные для ресурсов параметры поиска, однако для определения корректной модели поведения в таких случаях потребуется опыт реализации.

Technically, the _type parameter is a token parameter on the Resource Types Value Set.

Клиент может указать, в каком порядке вернуть результаты, с помощью параметра _sort, который может содержать список правил сортировки, отделённых [друг от друга] запятыми, в порядке приоритета:

GET [base]/Observation?_sort=status,-date,category

Каждый элемент в разделённом запятыми списке - это параметр поиска с необязательным префиксом '-'. Этот префикс обозначает обратный (убывающий) порядок; если он отсутствует, то такой параметр применяется в порядке возрастания.

Примечания:

  • При сортировке реально используемое значение сортировки не возвращается явным образом сервером для содержимого каждого ресурса.
  • Для сортировки по релевантности используйте _score.
  • Сервер возвращает тип сортировки, которую он выполняет, в рамках возвращаемых параметров поиска (см. ниже).
  • Параметр поиска может указывать на повторяющийся элемент, поэтому может быть несколько значений для заданного параметра поиска для отдельного ресурса. В таком случае сортировка будет основываться на элементе в наборе нескольких параметров, который идёт раньше всех в указанном порядке сортировки при упорядочивании возвращаемых ресурсов.
  • При сортировке по строковым параметрам поиска, сортировка ДОЛЖНА выполняться независимо от регистра. Диакритические знаки можно либо игнорировать, либо сортировать по принятому соглашению.
  • This specification does not specify exacts rules for consistency of sorting across servers. In general, this is deemed to be not as essential as consistency of filtering (though even that is a little variable). The purpose of sorting is to provide data in a "reasonable" order for end-users. "Reasonable" may vary by use case and realm, particularly for accented characters.

Для того чтобы сохранять нагрузку на клиентов, серверы и сеть минимальной, сервер может по желанию возвращать результаты в виде серии страниц. Набор результатов поиска содержит URL-ссылки, которые клиент использует для запроса дополнительных страниц из поискового набора. Для простого RESTful поиска ссылки на эти страницы содержатся в возвращаемом бандле.

Как правило, сервер предоставляет свои собственные параметры в ссылках, которые он использует для управления состоянием поиска при извлечении страниц. Эти параметры не требуется понимать или обрабатывать клиенту.

Параметр _count определён в качестве подсказки серверу относительно того, сколько ресурсов необходимо вернуть на одной странице. Серверы НЕ ДОЛЖНЫ возвращать больше ресурсов, чем запрашивается, даже если не поддерживают разбивку на страницы, однако они могут возвращать меньшее количество, чем запрашивает клиент. Сервер должен повторять первоначальный параметр _count в своих возвращаемых ссылках на страницы, чтобы последующие запросы с разбивкой на страницы учитывали первоначальный _count. Примечание: способ обработки текущих обновлений ресурсов во время выполнения поиска остаётся на усмотрение поисковой системы.

Примечание: комбинацию _sort и _count можно использовать для возвращения только самого свежего ресурса, который соответствует определённым критериям - задать критерии и затем отсортировать по дате в обратном порядке с _count=1. Таким образом будет возвращён самый свежий подходящий ресурс.

Если _count имеет значение 0, это следует интерпретировать так же, как и _summary=count: сервер возвращает бандл, который сообщает общее количество совпадающих ресурсов в Bundle.total, но без записей и ссылок на пред/след/последнюю [страницу]. Note that the Bundle.total only include the total number of matching resources. It does not count extra resources such as OperationOutcome or included resources that may also be returned.

Клиенты могут запросить, чтобы система вернула ресурсы, связанные с результатами поиска, чтобы уменьшить общую сетевую задержку повторяющихся извлечений связанных ресурсов. Это полезно, когда клиент ищет клинический ресурс, однако для каждого такого возвращаемого ресурса клиенту также требуется ресурс-субъект (пациент), к которому относится данный клинический ресурс. Клиент может использовать параметр _include для указания, что ресурсы-субъекты должны быть включены в результаты. Альтернативным сценарием может быть такой, когда клиент хочет извлечь конкретный ресурс и все ресурсы, которые ссылаются на него. Например клиент может пожелать извлечь MedicationRequest и все ресурсы Provenance, которые ссылаются на это предписание. Это называется обратным включением и указывается с помощью параметра _revinclude.

Оба параметра _include и _revinclude основываются на параметрах поиска, а не на путях в ресурсе, так как объединения, такие как chaining, уже сделаны параметром поиска.

Каждый параметр _include описывает параметр поиска для объединения:

 GET [base]/MedicationRequest?_include=MedicationRequest:patient&criteria...
 GET [base]/MedicationRequest?_revinclude=Provenance:target&criteria...

Первый поисковый запрос запрашивает все подходящие MedicationRequests, чтобы включить всех пациентов, к которым относятся предписания медикаментов в наборе результатов. Второй поисковый запрос запрашивает все подходящие рецепты (предписания) и возвращает все ресурсы Provenance, которые к ним относятся.

Значения для обоих параметров _include и _revinclude содержат три части, разделённые двоеточием :

  1. Имя исходного ресурса, из которого идёт объединение
  2. Имя параметра поиска, который должен быть типа reference
  3. (Необязательно) Конкретный тип целевого ресурса (для случаев, когда параметр поиска ведёт на несколько возможных целевых типов)

Параметры _include и _revInclude не включают множественные значения. Вместо этого эти параметры повторяются для каждого отдельного критерия включения.

Для каждого возвращаемого ресурса сервер определяет ресурсы, которые соответствуют критериям поиска, выраженным в объединении, и добавляет к результатам с entry.search.mode установленным в значение "include" (в некоторых поисковых запросах не очевидно, какие ресурсы являются совпадениями, а какие - включениями-инклюдами). If there is no reference, or no matching resource, the resource cannot be retrieved (e.g. on a different server), then the resource is omitted, and no error is returned.

Процесс включения может быть рекурсивным, если используется модификатор :recurse. Например следующий поисковый запрос возвращает все ресурсы Medication Request и их ресурсы prescribing Practitioner для соответствующих поиску ресурсов Medication Dispense:

GET [base]/MedicationDispense?_include=MedicationDispense:authorizingPrescription
    &_include:recurse=MedicationRequest:prescriber&criteria...

Этот способ также применяется к циркулярным [рекурсивным] взаимосвязям. Например первый из этих двух поисковых запросов включает все связанные с целевыми взаимосвязями наблюдения, но только с теми, что связаны напрямую. Второй запрос запрашивает _include на основе параметра related, который выполняется рекурсивно, таким образом он извлечёт наблюдения, которые имеют прямую связь, а также все наблюдения, связанные со всеми наблюдениями, включёнными через _include.

GET [base]/Observation?_include=Observation:related-target&criteria...
GET [base]/Observation?_include:recurse=Observation:related-target&criteria...

В обоих параметрах _include и _revInclude можно использовать специальный символ "*" в качестве имени параметра поиска для обозначения, что любой поисковый параметр с типом reference будет включен. Хотя и клиентам, и серверам необходимо заботиться о том, чтобы не запрашивать или не возвращать слишком много ресурсов при выполнении таких запросов. В частности использование рекурсивных включений может привести к извлечению всей карты пациента и даже более того: ресурсы организованы в сопряжённую сеть и заданные в достаточно общем виде пути _include могут в итоге включить все возможные пути на сервере. Для серверов такие рекурсивные и со звёздочкой инклюды (_include) являются достаточно требовательными и могут существенно замедлить время ответа на поиск.

На усмотрение сервера, насколько глубоко рекурсивно вычислять включения. Предполагается, что серверы будут ограничивать число итераций, выполняемых до уместного уровня, и что они не обязаны учитывать запросы на включение дополнительных ресурсов в результаты поиска.

Когда результаты поиска разбиваются на страницы, каждая страница результатов поиска должна включать все соответствующие инклюды для ресурсов на каждой странице, чтобы каждая страница была отдельным связным пакетом.

По умолчанию результаты поиска включают только те ресурсы, которые не являются вложенными в другие ресурсы. Цепочечное условие будет вычисляться внутри вложенных ресурсов. Для иллюстрации этого рассмотрим ресурс MedicationRequest, который содержит вложенный ресурс Medication, описывающий пользовательскую рецептуру, где есть ингредиент с itemCodeableConcept "abc" в "http://acme.com./medications". В таком случае поисковый запрос:

GET MedicationRequest?medication.ingredient-code=abc

будет включать в результаты ресурс MedicationRequest. Однако следующий поисковый запрос:

GET Medication?ingredient-code=abc

не будет включать в результаты вложенный ресурс Medication, поскольку либо неправильный тип ресурса был бы возвращён, либо вложенный ресурс был бы возвращён без своего ресурса-контейнера, который обеспечивает контекст для вложенного ресурса.

Клиенты могут менять эту модель поведения с помощью параметра _contained, который может иметь одно из следующих значений:

  • false (по умолчанию): не возвращать вложенные ресурсы
  • true: вернуть только вложенные ресурсы
  • both: вернуть и вложенные, и не вложенные (обычные) ресурсы

При возвращении вложенных ресурсов, сервер должен вернуть либо ресурс-контейнер, либо только вложенный ресурс отдельно. Клиент может указать способ через параметр _containedType, который может иметь одно из следующих значений:

  • container (по умолчанию): вернуть ресурсы-контейнеры
  • contained: вернуть только вложенный ресурс

При возвращении ресурса-контейнера, сервер просто помещает его в результаты поиска:

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

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

В случае возвращения ресурсов-контейнеров, сервер ДОЛЖЕН заполнить элемент entry.search.mode так, чтобы клиент мог разделить совпадения и инклюды (стандартный подход сделать это исходя из типа может не сработать). Если типом результата является вложенный ресурс, это следует делать по-другому: 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 may 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>

В этом случае fullUrl сообщает клиенту о том, что это вложенный ресурс, наряду с указанием идентификатора содержащего его ресурса.

Если путь в параметре _include выбирает ссылку, которая ведёт на ресурс на другом сервере, то сервер может по своему выбору включить тот ресурс в результаты поиска для удобства клиента.

Если путь параметра _include выбирает ссылку, которая ведёт на сущность, не являющуюся ресурсом, например на вложение-картинку, сервер может также по своему выбору включать это в возвращаемые результаты в виде ресурса Binary. Например путь включения может указывать на вложение с помощью ссылки следующим образом:

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

Сервер может извлекать целевой объект этой ссылки и добавлять его к результатам для удобства клиента.

При возвращении разбитых на страницы результатов поиска с включением ресурсов через _include, все включенные ресурсы, связанные с главными ресурсами, возвращёнными на странице, ДОЛЖНЫ тоже возвращаться в рамках этой же самой страницы, даже если некоторые из экземпляров этих ресурсов ранее были возвращены на предыдущих страницах. Такой подход позволяет как отправителю, так и получателю избежать кеширования результатов других страниц.

Клиент может запросить сервер вернуть только часть ресурсов с помощью параметра _summary:

   GET [base]/ValueSet?_summary=true

Параметр _summary запрашивает сервер вернуть подмножество ресурса. Он может иметь одно из следующих значений:

trueВернуть только те элементы, которые помечены как "суммарные" в базовых определениях ресурсов (см. ElementDefinition.isSummary)
textВернуть только элемент "text", элемент 'id', 'meta' и только верхнеуровневые обязательные элементы
dataУбрать элемент "text"
countТолько поиск: вернуть только количество соответствующих ресурсов, не возвращая сами совпадения
falseВернуть все части ресурсов

Параметр _summary предназначен для уменьшения общей процессинговой загрузки сервера, клиента и ресурсов между ними, таких как сеть. Он наиболее полезен для больших ресурсов, в честности тех, что включают в себя изображения или элементы, которые могут повторяться много раз. Назначение суммарной формы в том, чтобы позволить клиенту быстро извлечь большой набор ресурсов и позволить пользователю выбрать подходящий. Свойство суммарности для элемента задаётся для того, чтобы позволить пользователю быстро сортировать и фильтровать ресурсы, как правило опуская важное содержимое на основании того, что весь ресурс целиком будет извлечён уже после того, как пользователь выберет ресурс.

Серверы не обязаны возвращать всего лишь суммарные элементы по запросу. Имеется ограниченное количество суммарных форм, определённых для ресурсов, чтобы позволить серверам сохранять суммарные формы заранее. Серверы ДОЛЖНЫ помечать ресурсы тегом SUBSETTED для гарантии того, что неполный ресурс не будет случайно использован для перезаписи полного ресурса.

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

STU Note: There are open issues around the definitions of which elements are in the summary for each resource. There are 2 kinds of problems in the existing definitions:

  • Elements are marked as 'include in summary', but their parent element is not
  • Elements have minimum cardinality > 0, but are not included in the summary (and their parent element is) - so sumarised resources will not be schema valid

These issues will be resolved for FHIR Release 4. In the meantime, implementers may choose to override which elements are marked as 'included in summary', and implementations may vary.

Feedback on which elements should be in the summaries is welcome here .

Если одно из суммарных представлений, определённых выше, не подходит, клиент может запросить вернуть особый набор элементов как часть ресурса, используя параметр _elements:

   GET [base]/Patient?_elements=identifier,active,link

Параметр _elements состоит из списка имён базовых элементов, разделённых запятыми, то есть элементов, определённых на корневом уровне в этом ресурсе. Только те элементы, которые перечислены, должны быть возвращены. Клиенты ДОЛЖНЫ перечислять все обязательные элементы и элементы-модификаторы в ресурсе в рамках этого списка элементов. Этот список элементов не применяется к включенным ресурсам.

Серверы не обязаны возвращать только лишь запрашиваемые элементы. Серверы ДОЛЖНЫ всегда возвращать обязательные элементы независимо от того, запрашивались они или нет. Серверы ДОЛЖНЫ помечать ресурсы тегом SUBSETTED для гарантии того, что неполный ресурс не будет случайно использован для перезаписи полного ресурса.

Где поиск указывает неопределённую сортировку, поисковый алгоритм может создать некоторый вид рейтинговой оценки для обозначения, какие результаты удовлетворяют указанным критериям лучше, чем другие. Сервер может верннуть эту оценку в entry.score:

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

Балл - это десятичное число со значением между (и включая) 0 и 1, где 1 - это наилучшее соответствие, а 0 - наименьшее соответствие.

Для того, чтобы позволить клиенту быть уверенным о том, какие параметра поиска были использованы в качестве критериев сервером, сервер ДОЛЖЕН вернуть параметры, которые были фактически использованы при обработке поиска. Приложения, обрабатывающие результаты поиска, ДОЛЖНЫ проверить эти возвращённые значения, где это необходимо. Например, если сервер не поддерживает некоторые из фильтров, указанных в поиске, клиент мог бы вручную применить эти фильтры к полученному итоговому набору, показать предупреждающее сообщение пользователю или предпринять какое-то другое действие.

В случае RESTful-поиска эти параметры кодируются в ссылку типа "self" в бандле, который будет возвращён:

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

В остальном, серверы обладают значительной свободой действий в отношении поддержки поиска:

  • Серверы могут выбирать, какие параметры поддерживать (за исключением _id, описанного выше).
  • Серверы могут выбирать, когда и где реализовывать цепочечные параметры, а также когда и где они будут поддерживать параметр _include.
  • Серверы могут декларировать дополнительные параметры в профилях, на которые ссылаются их заявления о Capability. Серверы должны определять параметры поиска, начинающиеся с символа "-", чтобы гарантировать отсутствие конфликтов имён, которые они выберут, с будущими параметрами, определяемыми в рамках самой спецификации.
  • Серверам не требуется обеспечивать соблюдение чувствительности к регистру имён параметров, хотя эти имена и являются чувствительными к регистру (и URL-адреса, как правило, являются чувствительными к регистру).
  • Серверы могут выбирать, сколько результатов возвращать, хотя клиент может использовать _count, как описано выше.
  • Серверы могут выбирать, каким образом сортировать возвращаемые результаты, хотя они ДОЛЖНЫ учитывать параметр _sort.

Система поиска, описанная выше - это полезный фреймворк для обеспечения простого поиска, основанного на индексируемых критериях, однако нужна возможность создания более сложных запросов для обработки точных запросов, сложных запросов на основе поддержки принятия решений и прямых запросов, интерпретируемых человеком.

Более расширенные операции поиска задаются с помощью параметра _query:

   GET [base]/Patient?_query=name&parameters...

Параметр _query называет пользовательский профиль поиска, который описывает конкретную операцию запроса. Именованный запрос может задавать дополнительные именованные параметры, которые используются с определённым именованным запросом. Серверы могут определять свои собственные дополнительные именованные запросы для удовлетворения своих собственных нужд с помощью OperationDefinition.

В наборе параметров поиска может быть только один параметр _query. Серверы обрабатывающие поисковые запросы, ДОЛЖНЫ отказывать обрабатывать поисковый запрос, если они не понимают значение параметра _query.

Результаты операции поиска будут гарантированно текущими только на момент выполнения операции. После выполнения операции текущие действия над ресурсами, по которым выполнялся поиск, делают результаты всё более устаревшими. Значимость этого зависит от характера поиска, а также вида использования результатов.

Особенно это имеет значение, когда сервер возвращает результаты в виде серии страниц. Способ обработки текущих обновлений ресурсов во время выполнения поиска остаётся на усмотрение поисковой системы.

Примечание: выполнение операции поиска не изменяет набор ресурсов на сервере, за исключением создания ресурсов Audit Event для ведения аудита самого поиска.

Общие параметры, определённые для всех ресурсов:
ИмяТипОписаниеПути
_idtokenИдентификатор ресурса (а не полный URL) Resource.id
_lastUpdateddateДата последнего обновления. Сервер может по своему усмотрению устанавливать границы точности Resource.meta.lastUpdated
_tagtokenПоиск по тегу ресурса Resource.meta.tag
_profileuriПоиск всех ресурсов, помеченных профилем Resource.meta.profile
_securitytokenПоиск по метке уровня безопасности Resource.meta.security
_textstringТекстовый поиск по описательной части
_contentstringТекстовый поиск по всему ресурсу целиком
_liststringВсе ресурсы в названном списке (по идентификатору, а не полному URL)
_querystringCustom named query
Search Control Parameters:
ИмяТипОписаниеДопустимое содержимое
_sortstringПорядок сортировки результатов (может повторяться для внутренних порядков сортировки) Имя допустимого параметра поиска
_countnumber Количество результатов на странице Общее количество
_includestringДругие ресурсы для включения в результаты поиска, на которые указывают найденные при поиске совпадения SourceType:searchParam(:targetType)
_revincludestringДругие ресурсы для включения в результаты поиска, когда они ссылаются на найденные при поиске совпадения SourceType:searchParam(:targetType)
_summarystringПросто верните суммарные элементы (для ресурсов, где это определено) true | false (false is default)
_containedstringВозвращать ли ресурсы, вложенные в другие ресурсы при поиске совпадений true | false | both (false is default)
_containedTypestringВозвращать ли вложенные или родительские ресурсы при возвращении вложенных ресурсов container | contained

Перекрёстное отображение между типами параметров поиска и типами данных:

Data Type number date string token reference quantity uri
boolean N N N Y . true|false (System = http://hl7.org/fhir/special-values, однако обычно не требуется ) N N N
code N N N Y . Система, при желании, определяется в лежащем в основе наборе значений для каждого кода N N N
date N Y N N N N N
dateTime N Y N N N N N
decimal Y N N N N N N
instant N Y N N N N N
integer Y N N N N N N
string N N Y Y N N N
uri N N N N Y N Y
Address N N Y Поиск по любому строковому элементу в адресе N N N N
Annotation N N N N N N N
CodeableConcept N N N Y N N N
Coding N N N Y N N N
ContactPoint N N N Y N N N
Duration Y N N N N N N
HumanName N N Y Поиск по любому строковому элементу в имени N N N N
Identifier N N N Y N N N
Period N Y N N N N N
Quantity N N N N N Y N
Range N N N N N N N
Reference N N N N Y N N
SampledData N N N N N N N
Timing N Y N N N N N