This page is part of the FHIR Specification v6.0.0-ballot1: Release 6 Ballot (1st Draft) (see Ballot Notes). The current version is 5.0.0. For a full list of available versions, see the Directory of published versions

3.2.3 _filter Parameter

FHIR Infrastructure Work Group

Maturity Level: 2

Standards Status: Trial Use

3.2.3.1 Introduction

_filter is a parameter that can be used with the Search Operation. Filter requests have access to the same set of search parameters that are available to the search operation in that resource context on the server (e.g., standard parameters, parameters for each resource, etc.). The _filter parameter provides a syntax for expressing a set of query expressions on the underlying resources.

Examples of filters:

• Patient: name co "pet" - all patients with the characters "pet" in a given or family name
• Patient: given eq "peter" and birthdate ge 2014-10-10 - all patients with a given name of peter, born on or after 10-Oct 2014
• Observation: code eq http://loinc.org|1234-5 - all observations with the LOINC code "1234-5"
• Observation: subject.name co "pet" - all observations on a patient with the characters "pet" in a given or family name
• Observation: related[type eq "has-component"].target pr true - all observations that have component observations (note: this uses one of the search parameters defined for this mechanism, see below)
• Observation: related[type eq has-component].target re Observation/4 - all observations that have Observation/v as a component
• Observation: subject.id eq 3425 and code-value-quantity eq code$loinc|12907-2,value$ge150|http://unitsofmeasure.org|mmol/L - all observations for a particular patient that have a LOINC code of "12907-2" (Sodium [Moles/volume] in Red Blood Cells) AND a value greater than "150 mmol/L"
• Patient: given eq "peter" and birthdate ge 2014-10-10 and _has:Observation:patient:code eq http://loinc.org|1234-5 - all patients with a given name of peter, born on or after 10-Oct 2014 that have an observation referring to them with a LOINC code of 1234-5

The _filter syntax has the following features:

• A filter can be a logical one (x or x, or x and x, or not x).
• A filter can contain other filters in a set of parentheses: "()".
• A filter can be a test - path operation value, where operation is taken from the table below, and value is either a "true", "false", a JSON string, or a token (any sequence of non-whitespace characters, excluding ")" and "]". Values are never case sensitive.
• A 'path' is a name, with chained searches done by name.name etc.as per existing source. There can also be a filter: name[filter].name.
• Reverse chaining is also allowed, using _has:Resource:index1:index2 as the parameter
• The name is one of the defined search parameters that are used with the other search mechanism, with some special exemptions defined below.

Note: The only difference between a "string" value and a "token" value is that a string can contain spaces and ')' and ']'. There is otherwise no significant difference between them.

Formal grammar for the syntax:

filter        = paramExp / logExp / ("not") "(" filter ")"
logExp        = filter ("and" / "or" filter)+
paramExp      = paramValue SP compareOp SP compValue
compareOp     = (see table below)
compValue     = string / numberOrDate / token
string        = json string
token         = any sequence of non-whitespace characters (by Unicode rules) except "]" and ")"
paramValue    = hasSpecifier / paramPath
hasSpecifier  = "_has:" resource ":" index ":" index
resource      = ALPHA (DIGIT / ALPHA)*
index         = nameCharStart (nameChar)*
paramPath     = paramName (("[" filter "]") "." paramValue)
paramName     = nameCharStart (nameChar)*
nameCharStart = "_" / ALPHA
nameChar      = "_" / "-" / DIGIT / ALPHA
numberOrDate  = DIGIT (DateChar)*
dateChar      = DIGIT / "T" / "-" / "." / "+" / ":" / "Z"

Notes about using the syntax:

• Logical expressions are evaluated left to right, with no precedence between "and" and "or". If there is ambiguity, use parentheses to be explicit.
• The compareOp is always evaluated against the set of values produced by evaluating the param path.
• The parameter names are those defined by the specification for search parameters, except for those defined below.
• The date format is a standard XML (i.e. XSD) dateTime (including timezone).

3.2.3.2 Operators

This table summarizes the comparison operations available:

For detailed rules about the operators eq, ne, le, ge, lt, gt, sa, and eb see Search Prefixes.

The interpretation of the operation depends on the type of the search parameter it is being evaluated against. This table contains those details:

Note:

• For token, the format is the same as the existing search parameter.
• For convenience, the codes "loinc", "snomed", "rxnorm" and "ucum" are predefined and can be used in place of their associated full namespace.
• The evaluation of composite search parameters is very complex; only the codes eq and ne are appropriate in this case