Release 5

This page is part of the FHIR Specification (v5.0.0: R5 - STU). This is the current published version. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

FHIR Infrastructure icon Work GroupMaturity Level: 2Standards Status: Trial Use

_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).

This table summarizes the comparison operations available:

Operation Definition
eq an item in the set has an equal value
ne An item in the set has an unequal value
co An item in the set contains this value
sw An item in the set starts with this value
ew An item in the set ends with this value
gt / lt / ge / le A value in the set is (greater than, less than, greater or equal, less or equal) the given value
ap A value in the set is approximately the same as this value.
Note that the recommended value for the approximation is 10% of the stated value (or for a date, 10% of the gap between now and the date), but systems may choose other values where appropriate
sa The value starts after the specified value
eb The value ends before the specified value
pr The set is empty or not (value is false or true)
po True if a (implied) date period in the set overlaps with the implied period in the value
ss True if the value subsumes a concept in the set
sb True if the value is subsumed by a concept in the set
in True if one of the concepts is in the nominated value set by URI, either a relative, literal or logical vs
ni True if none of the concepts are in the nominated value set by URI, either a relative, literal or logical vs
re True if one of the references in set points to the given URL

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:

Operation String Number Date Token Reference Quantity
eq Character sequence is the same (case insensitive) Number is the same incl same precision Date is the same including same precision and timezone if provided Token is the same, including namespace if specified (case insensitive) n/a Unit and value are the same
ne (same)
Co Character sequence matches somewhere (case insensitive) An item in the set's implicit imprecision includes the stated value An item in the set's implicit period includes the stated value n/a n/a n/a?
sw Character sequence matches from first digit (left most, when L->R) (case insensitive) n/a n/a n/a n/a n/a
ew Character sequence matches up to last digit (right most, when L->R) (case insensitive) n/a n/a n/a n/a n/a
gt / lt / ge / le Based on Integer comparison of Unicode code points of starting character (trimmed) (case insensitive) Based on numerical comparison Based on date period comparison per 2.2.2.3 n/a n/a Based on numerical comparison if units are the same (or are canonicalized)
pr
po n/a n/a Based on date period comparison per 2.2.2.3 n/a n/a
ss n/a n/a n/a Based on logical subsumption; potentially catering for mapping between tx n/a n/a
sb n/a n/a n/a Based on logical subsumption; potentially catering for mapping between tx n/a n/a
in n/a n/a n/a Based on logical subsumption; potentially catering for mapping between tx n/a n/a
re n/a n/a n/a n/a Relative or absolute url n/a

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