Current Build

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

FHIR Infrastructure Work GroupMaturity Level: 5Ballot Status: Normative

Normative Candidate Note: This page is candidate normative content for R4 in the Infrastructure Package. Once normative, it will lose it's Maturity Level, and breaking changes will no longer be made.

Поиск ресурсов лежит в основе механики 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

Кроме этого, есть особые параметры _query и _filter для альтернативного метода поиска, а также параметры _format и _pretty, определенные для всех операций.

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

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

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

Для такого RESTful-поиска (см. определение в RESTful API) параметры представляют собой последовательность пар вида имя=[значение], кодированных в 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) (параметры, общие для всех типов). Если указан параметр _type, то все остальные параметры поиска должны быть общими для всех указанных типов. Если параметр _type не используется, все параметры должны быть общими для всех типов ресурсов.

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

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

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

Ответом на любую операцию поиска всегда будет список ресурсов в бандле. Альтернативным подходом выступает применение GraphQL.

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

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

  • В параметре может быть указан несуществующий ресурс, например GET [base]/Observation?subject=101, где "101" не существует.
  • Параметр может ссылаться на несуществующий ресурс, например GET [base]/Observation?patient.identifier=http://example.com/fhir/identifier/mrn|123456, где не существует пациента с MRN 123456.
  • В параметре может быть указан неизвестный код, например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 с дополнительными подсказками и предупреждениями относительно процесса поиска. Это будет элемент "Bundle.entry" с search mode = outcome. Клиенты могут использовать эту информацию для коррекции последующих запросов. Если, к примеру, клиент выполнил следующий поиск:

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

а пациента с MRN 123456 на сервере нету, то сервер вернет бандл с предупреждением.

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

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

  • Различные HTTP-стеки и прокси могут добавлять параметры, которые клиент не контролирует. Various HTTP stacks and proxies may add parameters that aren't under the control of the client
  • Клиент может определить, какие параметры сервер использовал, по "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 и имеет тип "токен", поскольку серверы должны искать по точному соответствию с ним, у него нет системы. Обратите внимание, что поиск по _id всегда чувствителен к регистру.

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

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

В этом примере мы ищем все ресурсы Observation, измененные после 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 и _security имеют тип "токен" (см. ниже), а _profile — тип "ссылка".

Кроме параметра _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, display, 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 (Reference or canonical).
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).
specialSpecial logic applies to this parameter per the description of the search parameter.

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

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

  • Для всех параметров (кроме их комбинаций): :missing, например gender:missing=true (или false). Поиск по gender:missing=true вернет все ресурсы, которые не имеют значения поля gender (что, как правило, приравнивается к отсутствию соответствующего элемента в ресурсе). Поиск по gender:missing=false вернет все ресурсы, имеющие значение поля gender. Для элементов простых типов данных :missing=true будет соответствовать всем элементам, где либо указанный элемент отсутствует, либо элемент содержит расширения, но значения не имеет (@value не указан).
  • Для строки: модификатор :exact возвращает результаты, которые полностью соответствуют указанному параметру, учитывая регистр и кобинированные символы. Отметьте, что обработка (расширенных) кластеров Графемы оставлена на усмотрение сервера, т.е. сервер решает, будет ли искать сопадение строкового параметра поиска по канонически эквивалентным символам или по фактически используемым кодам юникода, либо по :contains (независимо от регистра и комбинированных символов, поисковый текст имеет совпадение в любом месте строки), вместо дефолтного поведения (независимо от регистра и диакритичных знаков, частичное совпадение в начале строки).
  • Для токена: :text (поиск частичного совпадения в поле text элемента CodeableConcept или в поле display элемента Coding), вместо поиска по умолчанию, который использует коды. Другие модификаторы :in, :below, :above и :not-in описаны ниже.
  • Для ссылки: :[type], где [type] — это название типа ресурса, :identifier и, для некоторых параметров, :above и :below.
  • Для 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 входит в неявный диапазон любого времени в течение дня этой даты. Если целевым значением является Диапазон, Период или Расписание, тогда цель явным образом является диапазоном. Есть три типа диапазанов:

границы интервала Пределы, вытекающие из точности значения Число 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]=100Values that equal 100, to 3 significant figures precision, so this is actually searching for values in the range [99.5 ... 100.5)
[parameter]=100.00Values that equal 100, to 5 significant figures precision, so this is actually searching for values in the range [99.995 ... 100.005)
[parameter]=1e2Values that equal 100, to 1 significant figures precision, so this is actually searching for values in the range [95 ... 105)
[parameter]=lt100Values that are less than exactly 100
[parameter]=le100Values that are less or equal to exactly 100
[parameter]=gt100Values that are greater than exactly 100
[parameter]=ge100Values that are greater or equal to exactly 100
[parameter]=ne100Values that are not equal to 100 (actually, in the range 99.5 to 100.5)

Особенности поиска по числам:

  • When a number search is used against a resource element that stores a simple integer (e.g. ImmunizationRecommendation.recommendation.doseNumber), and the search parameter is not expressed using the exponential forms, and does not include any non-zero digits after a decimal point, the signficance issues cancel out and searching is based on exact matches. Note that if there are non-zero digits after a decimal point, there cannot be any matches
  • When a comparison prefix in the set lgt, lt, ge, le, sa & eb is provided, the implicit precision of the number is ignored, and they are treated as if they have arbitrarily high precision
  • The way search parameters operate in resources is not the same as whether two numbers are equal to each other in a mathematical sense
  • Searching on decimals involves an implicit range. The number of significant digits of the implicit range is the number of digits specified in the search parameter value, excluding leading zeros. So 100 and 1.00e2 both have the same number of significant digits - three

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

SearchDescription
 GET [base]/RiskAssessment?probability=gt0.8
Search for all the Risk Assessments wth probability great than 0.8 (could also be probability=gt8e-1 using exponential form)
 GET [base]/ImmunizationRecommendation?dose-number=2
Search for any immunization recommendation recommending a second dose

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

Формат параметра даты следующий: 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
  • "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
[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

Managing timezones 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 timezones. Implementation guides may make additional rules in this regard.

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

Implementer feedback is welcome on the HL7 wiki or chat.fhir.org .

 

Для простого текстового поиска строковый параметр служит как входные данные для поиска по последовательности символов. Такой поиск будет нечувствительным к регистру и входящим комбинированным символам как ударения и другие диакритические знаки. Пунктуация и несущественные пробелы (например повторяющийся символ пробела, табуляция вместо пробела) также должны игнорироваться. По умолчанию, поле соответствует строке поиска, если значение поля равно или начинается с указанного значения параметра, после того как оба были приведены к одному регистру и нормализованы по комбинированным символам. Таким образом, строковый поиск по умолчанию работает только на базовых символах строкового параметра. Модификатор :contains возвращает результаты, которые включают в себя значение указанного параметра в любом месте искомого поля. Модификатор :exact возвращает результаты, которые соответствуют указанному параметру полностью, включая регистр и диакритические знаки. 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.

Примеры:

[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 можно указать, что используется частичное совпадение. Например: 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 [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123
 GET [base]/ValueSet?url:below=http://acme.org/fhir/
 GET [base]/ValueSet?url:above=http://acme.org/fhir/ValueSet/123/_history/5
 GET [base]/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.

Тип "токен" - это параметр для поиска близкого к точному соответствия по строке символов, потенциально ограниченный некоторым URI. Используется в основном для типов данных code и identifier, где значение может иметь URI, который ограничивает его значение, где поиск выполняется по паре из Coding или Identifier. Токены также часто используют для поиска по другим полям, когда требуется точное соответствие - это URI, булевы значения и ContactPoints. В этих случаях часть параметра для поиска по URI не используется. A token type is a parameter that provides a close to exact match search on a string of characters, potentially scoped by a URI. It is mostly used against a code or identifier data type where the value may have a URI that scopes its meaning, where the search is performed against the pair from a Coding or an Identifier. Tokens are also used against other fields where exact matches are required - uris, booleans, and ContactPoints. In these cases, the URI portion is not used.

Поиск совпадения по токену должен быть буквальным (например не на основе отнесения к определённой категории или других особенностей использования кодовых систем). Совпадение должно быть чувствительным к регистру, если только лежащая в основе семантика контекста указывает, что токен следует интерпретировать регистронезависимо (см. например CodeSystem.caseSensitive). Отметьте, что совпадения по _id всегда чувствительны к регистру. Если в основе лежит тип данных string, тогда поиск будет нечувствительным к регистру. 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.

Примечание: С чувствительностью к регистру и поиском по токенам связано несколько сложных вопросов. Некоторые кодовые системы чувствительны к регистру (например UCUM), другие - нет. Для большинства кодовых систем это неоднозначно. Другие иды значений также являются неоднозначными. При сомнениях серверам следует обрабатывать токены регистронезависимым образом на том основании, что включение нежелательных данных имеет меньше последствий безопасности, чем исключение желательного поведения. Клиентам следует всегда использовать правильный регистр, где это возможно, и позволять серверу выполнять поиск совпадений вне зависимости от регистра. There are many challenging issues around case senstivity 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:

  • [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

Примечания:

  • 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 [parameter]=[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 [parameter]=[code] form is allowed

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

Тип данных URI Код Комментарий
Coding Coding.system Coding.code
CodeableConcept CodeableConcept.coding.system CodeableConcept.coding.code Поиск совпадений по всем coding в CodeableConcept
Identifier Identifier.system Identifier.value Клиенты могут искать по type, а не system, используя модификатор :of-type, см. ниже. Для поиска по CDA II.root - который может быть в Identifier.system или в Identifier.value, используйте синтаксис identifier=|[root],[root]. 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 система определена в наборе значений (хотя обычно не требуется)
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 Токен иногда используют для поиска по строкам, чтобы указать поиск по точному соответствию как корректную стратегию по умолчанию

Примечание: Использование параметров поиска по лексемам для булевых полей: булевы значения "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 (относительный или абсолютный), который идентифицирует набор значений, и поисковый параметр проверяет, что кодинг не входит в указанный набор значений.
: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

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

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

ПоискОписание
 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". Note that for :not, the search does not return any resources that have a gen
 GET [base]/Composition?section=48765-2
Search for any Composition that contains an Allergies and adverse reaction section
 GET [base]/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 [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
 GET [base]/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 [base]/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 [base]/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.

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

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

Префикс является необязательным и, как описано выше, зависит от того, как интерпретируются точность и операторы сравнения/диапазона. Как числовой параметр, числовая часть поискового значения может быть десятичным числом в экспоненциальном формате. system и code следуют тому же шаблону, что и параметр токен, и являются необязательными. Примеры поиска: 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 [base]/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 [base]/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 [base]/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 [base]/Observation?value-quantity=5.4
Search for all the observations with a value of 5.4(+/-0.05) irrespective of the unit
 GET [base]/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 [base]/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.

Поисковый процессор может решить выполнить поиск, основанный на канонических единицах измерений (например любое значение, которое может быть преобразовано в значение в миллиграммах, для случая выше). Например, наблюдение моежт иметь значение 23 mm/hr. Это равно 0.23 m/hr. Процессор поиска может нормализовать все значения до каноничных единиц, например 6.4e-6 m/sec, и преобразовать условия поиска в те же единицы измерения (m/sec). Подобные преобразования могут выполняться на основе семантики, описанной в UCUM . 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

Ссылочный параметр относится к ссылкам между ресурсами. Например найти все 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, or by it's canonical URL

Примечание: относительная ссылка, разрешаемая в то же значение, что и указанный абсолютный 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/" к строке поиска, т.к. это условие и так будет соблюдено.

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

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

Some references are circular - that is, the reference points to another resource of the same type. When the reference establishes a strict hierarchy, the modifiers :above and :below may be used to search transitively through the hierarchy:

GET [base]/Procedure?location:below=42

This search returns no only all procedures that occurred at location with id 42, but also any procedures that occurred in locations that are part of location with id 42.

GET [base]/MedicationAdministration?encounter:above=21

Returns all medication administrations that happened during encounter with id 21 or during any "parent" encounter of that encounter.

Servers indicate that :above/:below is supported on a search parameter by defining them as Modifiers on the Search Parameter definition.

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

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

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

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

Этот запрос возвращает все лабораторные отчеты, имеющие в качестве объекта пациента, чье имя содержит "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.

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

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:patient:code=123,456), and multiple _has parameters are allowed (e.g. GET [base]/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 [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", поскольку предполагается, что сервер вернёт результаты, которые соответствуют одному из значений. Каждый параметр поиска можно использовать со значениями, перечисленными через запятую таким образом; включат применение параметров поиска с модификаторами, например `?code:text=this,that. 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 и OR параметры можно комбинировать, например /Patient?language=FR,NL&language=EN относится к любому пациенту, который говорит по-английски, а также по-французски или по-голландски.

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

Чтобы подобные поиски были возможны, ресурс может также указать составные параметры, которые принимают последовательности отдельных значений, которые соответствуют другим заданным параметрам в качестве аргумента. Соответствующий параметр каждого компонента в такой последовательности документируется в определении этого параметра. Эти последовательности формируются присоединением отдельных значений символом $. Примечание: эта последовательность является отдельным значением и сама может состоять из набора значений, чтобы, к примеру, несколько соответствующих параметров характеристика-значение можно было указать как GET [base]/Group?characteristic-value=gender$mixed,owner$Eve. 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 [base]/Group?characteristic-value=gender$mixed,owner$Eve.

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

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

ЗапросОписание
 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"
 GET [base]/Questionnaire?context-type-value=focus$http://snomed.info/sct|408934002
Search for all questionnaires that have a cliical focus = "Substance abuse prevention assessment (procedure)"

Consider the case of searching for all AllergyIntolerance resources:

GET [base]/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 [base]/AllergyIntolerance?clinical-status=http://terminology.hl7.org/CodeSystem/allergyintolerance-clinical|active
GET [base]/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 [base]/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.

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

GET [base]/Observation?code=a,b

это запрос на все ресурсы Observation, в которых код равен a или b, тогда как: is a request for any Observation that has a code of either a or b, where as:

GET [base]/Observation?code=a\,b

это запрос на все ресурсы Observation, имеющие код 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 [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%2CValueSet/125

As do these URLs:

GET [base]/ValueSet?url=http://acme.org/fhir/ValueSet/123,http://acme.org/fhir/ValueSet/124\,125
GET [base]/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.

Особые параметры поиска по тексту _text и _content ищут по описательной части ресурса и полному содержимому ресурса соответственно. Точно как и строковые параметры, использующие модификатор :text, эти параметры должны поддерживать продвинутый поиск по типу, предложенному оыбными службами индексации текста. Значение этого параметра - это поиск на основе текста, который может включать поиск нескольких слов со словарём и соображения родства, а также такие логические операции, как AND, OR и др. Например: 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 [base]/Condition?_text=(bone OR liver) and metastases

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

Implementers could consider using the rules specified by the 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. 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:

Параметр _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". 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.

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

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

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

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

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

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

GET [base]/Observation?params...

Однако в некоторых обстоятельствах поиск выполняется без фиксированного типа ресурса: However, in some circumstances, a search is executed where there is no fixed type of resource:

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

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

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

Если тип не указан, то только базовые параметры поиска, которые применяются ко всем ресурсам, можно использовать для глобального поиска наподобие этого. Если задано несколько типов, тогда можно использовать любые параметры поиска, общие для всего набора указанных ресурсов (см. search parameter registry). If no type is specified, the only search parameters that be can be used in global search like this are the base parameters that apply to all resources. If multiple types are specified, any search parameters shared across the entire set of specified resources may be used (see search parameter registry).

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

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

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

Каждый элемент в разделённом запятыми списке - это параметр поиска с необязательным префиксом '-'. Этот префикс обозначает обратный (убывающий) порядок; если он отсутствует, то такой параметр применяется в порядке возрастания. Each item in the comma separated list is a search parameter, optionally with a '-' prefix. The prefix indicates decreasing order; in its absence, the parameter is applied in increasing order.

Примечания:

  • При сортировке реально используемое значение сортировки не возвращается явным образом сервером для содержимого каждого ресурса.
  • Для сортировки по релевантности используйте _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.

The _total parameter has the status trial-use pending real world experience of it's use.

The return Bundle has an element total which is the number of resources that match the search parameters.

Note that Bundle.total represents the total number of matches, not how many resources are returned in a particular response (see paging, immediately below).

Providing a precise number of matching resources may be onerous for the server, depending on how the server is designed. To help reduce the server load, a client can provide the parameter _total to indicate it's preference with regard to the total, which can have one of the following values:

noneThere is no need to populate the total count; the client will not use it
estimateA rough estimate of the number of matching resources is sufficient
accurateThe client requests that the server provide an exact total of the number of matching resources

The Bundle.total element is still optional, and the servers can ignore the _total parameter: it is just an optimization hint, that might possibly save the server some work.

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

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

Параметр _count определён в качестве инструкции серверу относительно того, сколько ресурсов необходимо вернуть на одной странице. Серверы НЕ ДОЛЖНЫ возвращать больше ресурсов, чем запрашивается, даже если не поддерживают разбивку на страницы, однако они могут возвращать меньшее количество, чем запрашивает клиент. Сервер должен повторять первоначальный параметр _count в своих возвращаемых ссылках на страницы, чтобы последующие запросы с разбивкой на страницы учитывали первоначальный _count. Примечание: способ обработки текущих обновлений ресурсов во время выполнения поиска остаётся на усмотрение поисковой системы. The parameter _count is defined as an instruction to the server regarding how many resources should be returned in a single page. Servers SHALL NOT return more resources than requested, even if they don't support paging, but are allowed to return less than the client requested. The server should repeat the original _count parameter in its returned page links so that subsequent paging requests honor the original _count. Note: It is at the discretion of the search engine as to how to handle ongoing updates to the resources while the search is proceeding.

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

Если _count имеет значение 0, это следует интерпретировать так же, как и _summary=count: сервер возвращает бандл, который сообщает общее количество совпадающих ресурсов в Bundle.total, но без записей и ссылок на пред/след/последнюю страницы. Отметьте, что Bundle.total содержит только общее число совпадающих ресурсов. Он не учитывает такие ресурсы как OperationOutcome или included, которые тоже могут быть найдены в результате поиска. Точно так же, параметр _count применяется только к ресурсам с entry.search.mode = search и не включает в себя вложенные ресурсы и результаты операций. if _count has the value 0, this shall be treated the same as _summary=count: the server returns a bundle that reports the total number of resources that match in Bundle.total, but with no entries, and no prev/next/last links. 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. In the same way, the _count parameter only applies to resources with entry.search.mode = search, and does not include included resources or operation outcomes.

Параметр _count не влияет на значение элемента Bundle.total, поскольку последний показывает общее число совпадений, а не количество результатов в одном ответном ресурсе Bundle. The _count parameter has no impact on the value of Bundle.total as the latter represents the total number of matches, not how many are returned in a single Bundle response.

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

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

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

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

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

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

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

Параметры _include и _revinclude не включают множественные значения. Вместо этого эти параметры повторяются для каждого отдельного критерия включения. _include and _revinclude parameters do not include multiple values. Instead, the parameters are repeated for each different include criteria.

Для каждого возвращаемого ресурса сервер определяет ресурсы, которые соответствуют критериям поиска, выраженным в объединении, и добавляет к результатам с entry.search.mode установленным в значение "include" (в некоторых поисковых запросах не очевидно, какие ресурсы являются совпадениями, а какие - включениями-инклюдами). Если нет ссылки или нет совпадения, ресурс нельзя извлечь (например на другом сервере), тогда такой ресурс опускается и ошибка не возвращается. For each returned resource, the server identifies the resources that meet the criteria expressed in the join, and adds to the results, with the entry.search.mode set to "include" (in some searches, it is not obvious which resources are matches, and which are includes). 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.

Процесс включения может быть итеративным, если (и только если) используется модификатор :iterate. Например следующий поисковый запрос возвращает все ресурсы Medication Request и их ресурсы prescribing Practitioner для соответствующих поиску ресурсов Medication Dispense: The inclusion process can be iterative, if (and only if) the modifier :iterate is included. For example, this search returns all Medication Request resources and their prescribing Practitioner Resources for the matching Medication Dispense resources:

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

Этот способ также применяется к циркулярным [рекурсивным] взаимосвязям. Например первый из этих двух поисковых запросов включает все связанные с целевыми взаимосвязями наблюдения, но только с теми, что связаны напрямую. Второй запрос запрашивает _include на основе параметра related, который выполняется итеративно, таким образом он извлечёт наблюдения, которые имеют прямую связь, а также все наблюдения, связанные со всеми наблюдениями, включёнными через _include. This technique applies to circular relationships as well. For example, the first of these two searches includes any related observations to the target relationships, but only those directly related. The second search asks for the _include based on related parameter to be executed iteratively, so it will retrieve observations that are directly related, and also any related observations to any other included observation.

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

В обоих параметрах _include и _revinclude можно использовать специальный символ "*" в качестве имени параметра поиска для обозначения, что любой поисковый параметр с типом reference будет включен. Хотя и клиентам, и серверам необходимо заботиться о том, чтобы не запрашивать или не возвращать слишком много ресурсов при выполнении таких запросов. В частности использование итеративных включений по шаблонам подстановки может привести к извлечению всей карты пациента и даже более того: ресурсы организованы в сопряжённую сеть и заданные в достаточно общем виде пути _include могут в итоге включить все возможные пути на сервере. Для серверов такие итеративные и с шаблонами подстановки инклюды (_include) являются достаточно требовательными и могут существенно замедлить время ответа на поиск. Both _include and _revinclude use the wild card "*" for the search parameter name, indicating that any search parameter of type=reference be included. Though both clients and servers need to take care not to request or return too many resources when doing this. Most notably, using iterative wildcards inclusions might lead to the retrieval of the full patient's record, or even more than that: resources are organized into an interlinked network and broad _include paths may eventually traverse all possible paths on the server. For servers, these iterative and wildcard _includes are demanding and may slow the search response time significantly.

На усмотрение сервера, насколько глубоко итеративно вычислять включения. Предполагается, что серверы будут ограничивать число итераций, выполняемых до уместного уровня, и что они не обязаны учитывать запросы на включение дополнительных ресурсов в результаты поиска. It is at the server's discretion how deep to iteratively evaluate the inclusions. Servers are expected to limit the number of iterations done to an appropriate level and are not obliged to honor requests to include additional resources in the search results. Because iterative search is generally resource intensive, it is not the default behavior.

Когда результаты поиска разбиваются на страницы, каждая страница результатов поиска должна включать все соответствующие инклюды для ресурсов на каждой странице, чтобы каждая страница была отдельным связным пакетом. When search results are paged, each page of search results should include the matching includes for the resources in each page, so that each page stands alone as a coherent package.

Примечание: рассматривая возможность применения _include и _revinclude, реализаторам необходимо также учитывать использование GraphQL и/или GraphDefinition как более подходящие подходы в их контектсте. Note: when considering using _include and _revinclude, implementers should also consider whether using GraphQL and/or GraphDefinition are more appropriate approaches in their context.

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

будет включать в результаты ресурс 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 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>

В этом случае 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Вернуть только ограниченное подмножество элементов ресурса. Это подмножество должно состоять только из поддерживаемых элементов, помеченных как "summary" в базовом определении ресурса (см. ElementDefinition.isSummary) Return 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)
textВернуть только элемент "text", элемент 'id', 'meta' и только верхнеуровневые обязательные элементы Return only the "text" element, the 'id' element, the 'meta' element, and only top-level mandatory elements
dataУбрать элемент "text" Remove the text element
countТолько поиск: вернуть только количество соответствующих ресурсов, не возвращая сами совпадения Search only: just return a count of the matching resources, without returning the actual matches
falseВернуть все части ресурсов Return all parts of the resource(s)

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

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

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.

Если одно из суммарных представлений, определённых выше, не подходит, клиент может запросить вернуть особый набор элементов как часть ресурса в результатах поиска, используя параметр _elements: 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 [base]/Patient?_elements=identifier,active,link

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

Серверы не обязаны возвращать только лишь запрашиваемые элементы. Серверы ДОЛЖНЫ всегда возвращать обязательные элементы независимо от того, запрашивались они или нет. Серверы ДОЛЖНЫ помечать ресурсы тегом 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 для ведения аудита самого поиска. 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.

Общие параметры, определённые для всех ресурсов:
ИмяТипОписаниеПути
_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 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