This page is part of the FHIR Specification (v4.0.1: R4 - Mixed Normative and STU ). This is the current published version in it's permanent home (it will always be available at this URL). For a full list of available versions, see the Directory of published versions

3.1.3 _filter Parameter

FHIR Infrastructure Work Group

Maturity Level : 2

Standards Status : Trial Use

3.1.3.1 Introduction

_filter is a parameter that can be used with the Search Operation . It uses the same set of standard parameters defined for the resources, and 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

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.
• 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      = paramPath 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 ")"
paramPath     = paramName (("[" filter "]") "." paramPath)
paramName     = nameCharStart (nameChar)*
nameCharStart = "_" / ALPHA
nameChar      = "_" / "-" / DIGIT / ALPHA
numberOrDate  = DIGIT (DateChar)*
dateChar      = DIGIT / "T" / "-" / "." / "+"

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.
• Rhe compareOp is always evaluated against the set of values produced by evaluating the param path.
• Rhe parameter names are those defined by the specification for search parameters, except for those defined below.
• Rhe date format is a standard XML (i.e. XSD) dateTime (including time zone).

3.1.3.2 Operators

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 time zone 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.

3.1.3.3 Additional Parameters

Some additional parameters are defined for the filter parameter ( to do: move these into the standard parameters ):

Resource Type	Parameter Name	Children
Observation	related	target = related-target Type = related-type
Group	characteristic	value = value code = characteristic
DocumentReference	relatesTo	code = relation target = relatesTo
ServiceRequest	event	status = event-status date = event-date
ServiceRequest	item	status = item-status code = item-code site = bodysite event = item-event
ServiceRequest	item-event	status = item-past-status date = item-date actor = actor

Note:

• Any time these names are used in a parameter, they must have a filter and a chained name under them.
• The first column is the resource type against which this name can be used.
• The second column is the parameter name that is used.
• The third column defines the names that can be used in the chained parameter, and in the filter, and shows which existing search parameters they equate to.
• For example, you could search on Observation for '_filter=related[type eq has-component].target re url'. "type" refers to the search parameter "related-type", and "target" to the search parameter "related-target".