This page is part of the FHIR Specification (v0.4.0: DSTU 2 Draft). The current version which supercedes this version is 5.0.0. For a full list of available versions, see the Directory of published versions . Page versions: R5 R4B R4 R3 R2

2.1.2 _filter Parameter

2.1.2.1 Introduction

The _filter parameter 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.

Here's some example 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: name 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 that 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.

This is the 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    = ALPHA (nameChar)*
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
• 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).

2.1.2.2 Operators

This table summarises the comparison operations available:

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

Notes:

• 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

2.1.2.3 Additional Parameters

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

Explanation:

• 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 prameter 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" here refers to the search parameter "related-type", and "target" to the search parameter "related-target"