FHIR Search for client developers by Mirjam Baltus

1. FHIR Search
for client developers
Mirjam Baltus
FHIR Developer Days
November 24, 2014
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

2. Who am I?
 Name: Mirjam Baltus-Bakker
 Company: Furore, Amsterdam
 Background:
 ICT trainer
 Furore FHIR team
 Contact:
 m.baltus@furore.com
2
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

3. Searching FHIR
 Understanding search
 Basic search
 Search parameters
 Parameter types
 More complex searches
 Search using the API
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

4. Basic search
 Syntax
GET [base-url]/[resourcetype](?parameters)
 Getting all patients
GET http://acme.org/fhir/Patient
 Always returns a paged feed
 Use _count for number of results per page
4
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

5. Basic search
 Special case of the “real” search operation:
http://acme.org/fhir/Patient?_id=23
http://acme.org/fhir/Patient/23
http://acme.org/fhir/Patient?name=eve
 OperationOutcome resource
5
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

6. Searching FHIR
 Understanding search
 Basic search

 Search parameters
 Parameter types
 More complex searches
 Search using the API
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

7. Search (patient)
Each resource has a set of “standard” search parameters,
so not every element can be searched!:
Our last search
used this one
7
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

8. Conformance
8
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

9. Searching FHIR
 Understanding search
 Basic search


 Search parameters
 Parameter types
 More complex searches
 Search using the API
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

10. Search (patient)
Each search parameter has a ‘type’
Parameter
Type
10
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

11. Parameter types
11
 number: =, =<, =<=, =>, =>=
 Significant digits matter
 date: =, =<, =<=, =>, =>=
Search for [param]=>param]=2013-2013-01-01-14 14T10:returns
00
resources where [param] is between
2013-01-14T00:00 and 2013-01-14T23:59
 Matches calculated using interval operations
includes resources where [param] has
a value of 2013-01-14
 Precision turns all dates into intervals
 string: =
 “contains” search, ignoring case, accents
 Can use :exact to be case and accent-sensitive
http://acme.org/fhir/Patient?name:exact=Eve
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

12. Parameter types (cont’d)
12
 token: =
 [code] matches codes/identifier values
independent of system
http://acme.org/fhir/Patient?gender=M
 [system]|[code/value] matches a specified code or
identifier within the specified system
http://acme.org/fhir/Patient?
 |[code/value] gender=matches v3/AdministrativeGender|the specified code or
M
identifier in instances where no system is declared
 :text performs a string search on
CodeableConcept.text, Coding.display and
Identifier.label
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

13. Parameter types (cont’d)
13
 quantity: =, =<, =>, =<=, =>=
 [comparator][number]|[system]|[code]
http://acme.org/fhir/Observation?
 Follows rules for number + token together for
value + units of quantity
value=5.4|http://unitsofmeasure.org|mg
 reference: =
 Either the local or absolute id
 :type filters resource type
http://acme.org/fhir/DiagnosticReport?
subject=Patient/23
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

14. Ok I get it…or not?
http://acme.org/fhir/Patient/ 406 hits
http://acme.org/fhir/Patient?gender=M 234 hits
http://acme.org/fhir/Patient?gender=F 167 hits
Total: 234 + 167 = 401
http://acme.org/fhir/Patient/ 406 hits
http://acme.org/fhir/Patient?gender=M 234 hits
http://acme.org/fhir/Patient?gender=F 167 hits
http://acme.org/fhir/Patient?gender:missing=true 5 hits
Total: 234 + 167 + 5 = 406
14
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

15. Searching FHIR
 Understanding search
 Basic search


 Search parameters
 Parameter types

 More complex searches
 Search using the API
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

16. Combining parameters
 Specifying multiple parameters finds
resources matching all params  “AND”
 Parameters may list multiple values  “OR”
 Try:
http://acme.org/fhir/Patient?
birthdate=1972-11-30&language=nl,fr
16
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

17. Chained searches
 Patient has a search for “name”.
 Observation has a search for “subject” (the
id of the Patient, Group or Device)
 How do I find Observations for a patient,
searching using his name?
17
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

18. 2 queries in 1
 You (as a client) don’t need to do separate
operations, just one:
http://acme.org/fhir/Observation?
subject:.Pnatmiee=njti.mname=jim
But note: this still only works on the predefined
search parameters. You cannot just use any
property of the resource.
18
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

19. More optimalizations
 Say we do:
http://acme.org/fhir/DiagnosticReport?
date=2013-03-11
We get back: a Bundle with 0..* “DiagnosticReports”
 Now, usually, wouldn’t we want the Patient
information too? => Need to do “N” queries
for the DiagnosticReport’s “subject”
 Quicker: _include=DiagnosticReport.subject
Returns both DiagnosticReports + Patients
19
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

20. Summary
 Some resources can be “big”
 e.g. Patient with pictures & lots of contacts
 10MB JSON result set is bad when you’re an
Android app presenting a list of 100 patients for a
clinician to scroll through
 Solution: _summary=true strips a
resource’s elements down to those most
likely to be useful in a “list” view.
22
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

21. Sorting
 Use _sort:asc or _sort:desc to control sort
 E.g.
Observation?_sort:asc=name&_sort:desc
=date
 Sorts observations of the same type together,
newest first
23
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

22. Searching FHIR
 Understanding search
 Basic search


 Search parameters
 Parameter types

 More complex searches


 Search using the API
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

23. Search using the API
 Demo in .Net
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

24. Final words
 FHIR has a lot of query capability
 However . . .
 Almost all of it is optional
 So how do you design a client when you have no
clue what the server will support?
 The more generic you want your client to be, the less
you should rely on sophisticated server capabilities
 Always check the response to see what parameters
were actually used
26
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.

25. Questions?
 http://hl7.org/fhir m.baltus@furore.com
27
© 2014 HL7 ® International. Licensed under Creative Commons. HL7 & Health Level Seven are registered trademarks of Health Level Seven International. Reg. U.S. TM Office.