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.namecontent-type:text/yamlaccept:text/yamlname:nameresource:id:PatientresourceType:Entitywhere:"{{table}}.resource->>'name' ilike {{param}}"# sql for searchformat:"%?%"# 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.
Token search
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/yamlaccept:text/yamlresourceType:Searchname:<parameter>resource: {id:<resourceType>,resourceType:Entity}param-parser:tokentoken-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}}>
Reference search
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/yamlaccept:text/yamlresourceType:Searchname:<parameter>resource: {id:<resourceType>,resourceType:Entity}param-parser:reference
Multi: array parameter
If you set multi = 'array', parameters will be coerced as PostgreSQL array.
PUT /Patient/my-patient-1content-type:text/yamlaccept:text/yamlresourceType:Patientid:my-patient-1identifier: - value:id2
# create search resource PUT /Search/Patient.identifiercontent-type:text/yamlaccept:text/yamlresourceType:Searchid:Patient.identifiername:identifierresource:resourceType:Entityid:Patientwhere:knife_extract_text({{table}}.resource, '[["identifier","value"]]') && {{param}}multi:array
# execute searches and retrieve two patients# check query-sql field in response bundleGET /Patient?identifier=id1,id2,id3content-type:text/yamlaccept:text/yaml
# execute search for new parameter# check query-sql field in response bundleGET /Patient?name=johncontent-type:text/yamlaccept:text/yamlGET /Patient?_sort=namecontent-type:text/yamlaccept:text/yaml
GET /ServiceRequest?identifier=foocontent-type:text/yamlaccept:text/yaml# will result in querying with knife_extract(...) && ARRAY['foo']
GET /ServiceRequest?identifier:text=foocontent-type:text/yamlaccept:text/yaml# will result in querying with array_to_string(knife_extract (...)) ilike '%foo%'
GET /ServiceRequest?identifier:not=foocontent-type:text/yamlaccept:text/yaml# will result fallback to default implementation NOT resource @> '{"identifier": [{"value": "foo"}]}'
Reference search by type/id
PUT /Search/Patient.generalPractitionercontent-type:text/yamlaccept:text/yamlresourceType:Searchid:Patient.generalPractitionername:generalPractitionerparam-parser:referencewhere:'{{table}}.resource->'generalPractitioner' @> jsonb_build_array(jsonb_build_object('id', {{param.id}}::text, 'resourceType', {{param.resourceType}}::text)) 'resource: {id:Patient,resourceType:Entity}
# search Patient by Practitioner referenceGET /Patient?generalPractitioner=Practitioner/pract-1content-type:text/yamlaccept:text/yaml
Reference search by id
PUT /Search/Patient.generalPractitionercontent-type:text/yamlaccept:text/yamlresourceType:Searchid:Patient.generalPractitionername:generalPractitionerparam-parser:referencewhere:'{{table}}.resource->'generalPractitioner' @> jsonb_build_array(jsonb_build_object('id', {{param.id}}::text)) 'resource: {id:Patient,resourceType:Entity}
# search Patient by Pratitoner referenceGET /Patient?generalPractitioner=pract-1content-type:text/yamlaccept:text/yaml
Reference search by url
PUT /Search/Patient.myProfilecontent-type:text/yamlaccept:text/yamlresourceType:Searchid:Patient.myProfilename:myProfileparam-parser:referencewhere:'{{table}}.resource#>'{meta,profile}' @> jsonb_build_array({{param.url}}::text) 'resource: {id:Patient,resourceType:Entity}
# search Patient by profileGET /Patient?myProfile=http://hl7.org/fhir/us/core/StructureDefinition/us-core-patientcontent-type:text/yamlaccept:text/yaml