Search Resource

Search resource provides fine-grained control over search parameters

Search resource defines search parameter or overrides the existing one. Search resources take precedence over SearchParameters. This may be useful for the performance optimization of built-in FHIR SearchParameters or for the implementation of complicated custom searches.

Example

PUT /Search/Patient.name
content-type: text/yaml
accept: text/yaml

name: name
resource:
  id: Patient
  resourceType: Entity
where: "{{table}}.resource->>'name' ilike {{param}}" # sql for search
format: "%?%" # parameter format for ilike 
order-by: "{{table}}.resource#>>'{name,0,family}'" # sql for ordering (using _sort)

Search resource structure

Key
Type
Description

name

string

Search parameter name

resource

object

Reference to the resource (resourceType is always Entity)

where

string

SQL to use in the WHERE expression.

Supports {{table}} and {{param}}

format

string

Replaces ? with the actual value provided in the search query. Useful to use in ILIKE SQL expression.

order-by

string

SQL to use in the ORDER BY expression.

Supports {{table}} and {{param}}.

Note that it is used only when _sort=<name> present in the query.

You can define Search resources for different token syntax forms and :text modifier. To refer to the system and code in SQL query use {{param.system}} and {{param.code}} accordingly. To refer to the value of the param with :text modifier use {{param.text}} When using the :text modifier you also need to specify "text-format", refer to {{param.text}} with ?. "text-format" is a format string which will be applied to{{param.text}} before inserting it into SQL query. It is useful for wrapping text with % for like or ilike. For example text-format: '%?%'

PUT /Search/<resourceType>.<parameter>
content-type: text/yaml
accept: text/yaml

resourceType: Search
name: <parameter>
resource: {id: <resourceType>, resourceType: Entity}
param-parser: token
token-sql:
  only-code: <SQL query for parameter={{param.code}}>
  no-system: <SQL query for parameter=|{{param.code}}>
  only-system: <SQL query for parameter={{param.system}}|>
  both: <SQL query for parameter={{param.system}}|{{param.code}}>
  text: <SQL query for parameter:text={{param.text}}>
  text-format: <format string {{param.text}}>

Allows use different reference types in "where" expression. Reference can be defined in several ways:

  • {{param.resourceType}} for ResourceType and {{param.id}} for resource id

  • {{param.id}} for resource id

  • {{param.url}} for resource url

PUT /Search/<resourceType>.<parameter>
content-type: text/yaml
accept: text/yaml

resourceType: Search
name: <parameter>
resource: {id: <resourceType>, resourceType: Entity}
param-parser: reference

Multi: array parameter

If you set multi = 'array', parameters will be coerced as PostgreSQL array.

# create patient resources
PUT /Patient/my-patient
content-type: text/yaml
accept: text/yaml

resourceType: Patient
id: my-patient
identifier:
 - value: id1

Examples

Search patient name with SQL ilike

# create patient resource
PUT /Patient/my-patient
content-type: text/yaml
accept: text/yaml

resourceType: Patient
id: my-patient
name:
 - family: johnson

Search if patient is deceased

PUT /Search/Patient.name
content-type: text/yaml
accept: text/yaml

resourceType: Search
id: Patient.deceased
name: deceased
resource:
  id: Patient
  resourceType: Entity
where: "coalesce((resource#>>'{deceased,boolean}')::boolean, resource ?? 'deceased', false) = {{param}}"

Token search

PUT /Search/ServiceRequest.identifier
content-type: text/yaml
accept: text/yaml

resourceType: Search
id: ServiceRequest.identifier
name: identifier
param-parser: token
token-sql:
  only-code: 'knife_extract_text({{table}}.resource, ''[["identifier","value"]]'') && ARRAY[{{param.code}}]'
  only-system: 'knife_extract_text({{table}}.resource, ''[["identifier",  "system"]]'') && ARRAY[{{param.system}}]'
  no-system: 'knife_extract_text({{table}}.resource, ''[["identifier","value"]]'') && ARRAY[{{param.code}}]'
  both: '(knife_extract_text({{table}}.resource, ''[["identifier","value"]]'') && ARRAY[{{param.code}}]) AND ({{table}}.resource->''identifier'' @> jsonb_build_array(jsonb_build_object(''system'', {{param.system}}::text, ''value'', {{param.code}}::text)))'
  text: 'array_to_string(knife_extract({{table}}.resource, ''[["identifier"]]''), '''') ilike {{param.text}}'
  text-format: '%?%'
where: '(knife_extract_text({{table}}.resource, ''[["identifier","value"]]'') && ARRAY[{{param.code}}]) AND ({{table}}.resource->''identifier'' @> jsonb_build_array(jsonb_build_object(''system'', {{param.system}}::text, ''value'', {{param.code}}::text)))'
resource: {id: ServiceRequest, resourceType: Entity}

Reference search by type/id

PUT /Search/Patient.generalPractitioner
content-type: text/yaml
accept: text/yaml

resourceType: Search
id: Patient.generalPractitioner
name: generalPractitioner
param-parser: reference
where: '{{table}}.resource->'generalPractitioner' @>  jsonb_build_array(jsonb_build_object('id', {{param.id}}::text, 'resourceType', {{param.resourceType}}::text)) '
resource: {id: Patient, resourceType: Entity}

Reference search by id

PUT /Search/Patient.generalPractitioner
content-type: text/yaml
accept: text/yaml

resourceType: Search
id: Patient.generalPractitioner
name: generalPractitioner
param-parser: reference
where: '{{table}}.resource->'generalPractitioner' @>  jsonb_build_array(jsonb_build_object('id', {{param.id}}::text))  '
resource: {id: Patient, resourceType: Entity}

Reference search by url

PUT /Search/Patient.myProfile
content-type: text/yaml
accept: text/yaml

resourceType: Search
id: Patient.myProfile
name: myProfile
param-parser: reference
where: '{{table}}.resource#>'{meta,profile}' @>  jsonb_build_array({{param.url}}::text) '
resource: {id: Patient, resourceType: Entity}

Last updated