This page is part of the FHIR Specification (v4.4.0: R5 Preview #2). 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
FHIR Infrastructure Work Group | Maturity Level: 2 | Standards Status: Trial Use |
_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 namePatient: given eq "peter" and birthdate ge 2014-10-10
- all patients with a given name of peter, born on or after 10-Oct 2014Observation: 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 nameObservation: 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 componentThe _filter syntax has the following features:
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:
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:
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 |
ServiceRequest | item | status = item-status code = item-code site = bodysite event = item-event |
ServiceRequest | item-event | status = item-past-status |
Note: