Custom Search Parameter

Aidbox has multiple options to provide custom searches.

Define SearchParameter resource

You can define custom search params by just creating SearchParameter resource. Let's say you want to search patient by city:

PUT /SearchParameter/Patient.city
​
name: city
type: token
resource: {id: Patient, resourceType: Entity}
expression: [[address, city]]

Now let's test new search parameter

GET /Patient?city=New-York
​
# resourceType: Bundle
type: searchset
entry: [...]
total: 10
query-sql: 
- | 
  SELECT "patient".* FROM "patient" 
  WHERE ("patient".resource @> '{"address":[{"city":"NY"}]}')
   LIMIT 100 OFFSET 0

Aidbox format example

Be aware of the Aidbox format in "expression".

In this example, the ["value", "string"] expression is used to look into FHIR valueString field:

PUT /fhir/SearchParameter/Observation.value-string
content-type: application/json
accept: application/json

{
  "name": "value-string",
  "type": "string",
  "resource": {
    "id": "Observation",
    "resourceType": "Entity"
  },
  "expression": [
    [
     "value", "string" 
    ]
  ],
  "id": "Observation.value-string",
  "resourceType": "SearchParameter"
}

Define custom SearchParameter with extension

If you have defined first-class extension, you have to use Aidbox format for the SearchParameter expression. If you use FHIR format, you don't need to create Attribute and the expression path should be in FHIR format.

First-class extension

PUT /Attribute/ServiceRequest.precondition

resourceType: Attribute
description: "The condition or state of the patient, prior or during the diagnostic procedure or test, for example, fasting, at-rest, or post-operative. This captures circumstances that may influence the measured value and have bearing on the interpretation of the result."
resource: {id: ServiceRequest, resourceType: Entity}
path: [precondition]
id: ServiceRequest.precondition
type: {id: CodeableConcept, resourceType: Entity}
isCollection: true
extensionUrl: "http://hl7.org/fhir/StructureDefinition/servicerequest-precondition"

SearchParameter (First-class extension)

PUT /SearchParameter/ServiceRequest.precondition

name: precondition
type: token
resource: {id: ServiceRequest, resourceType: Entity}
expression: [[precondition, coding]]

SearchParameter (FHIR extension)

PUT /SearchParameter/ServiceRequest.precondition

name: precondition
type: token
resource: {id: ServiceRequest, resourceType: Entity}
expression:
- [extension, {url: 'http://hl7.org/fhir/StructureDefinition/servicerequest-precondition'}, 
value, CodeableConcept, coding, code]

If you use Zen IG then first-class extensions are generated from zen-schemas. You have to use Aidbox format for the custom SearchParameter expression (check tab #3 in the example above).

Custom SearchParameter with Zen

Most of the Search Parameters from IG work with Zen by default, also you can make a new one.

Assuming you already know how to use configuration projects, let's learn how to create zen search parameter by example:

{ns main
 import #{aidbox.search-parameter.v1
          aidbox
          aidbox.repository.v1}

 zen-config
 {...}

 my-parameter
 {:zen/tags #{aidbox.search-parameter.v1/search-parameter}
  :name "brthdt"
  :type :date
  :resource {:resourceType "Entity" :id "Patient"}
  :expression [["birthDate"]]}

 patient-repository
 {:zen/tags #{aidbox.repository.v1/repository}
  :resourceType "Patient"
  :extra-parameter-sources :all ; allow to use SearchParameters from outside of repo
  :search-parameters #{my-parameter}}

 repositories
 {:zen/tags #{aidbox/service}
  :engine aidbox.repository.v1/engine
  :repositories #{patient-repository}
  :load-default true}

 box {:zen/tags #{aidbox/system}
      :config   zen-config
      :services
      {:repositories repositories}}}

First we import aidbox.search-parameter.v1 and aidbox.repository.v1 namespaces from edn files. These are zen-namespaces we need to make an aidbox/service which name is repositories.

This service is our concept of wrapping resourceType-specific entities, as search parameters, indexes, and more, into one entity, called repository. We will add indexes for search parameters soon.

We have one repository for Patient resourceType: patient-repository. It contains :search-parameters key with new SearchParameter my-parameter.

SearchParameter must contain:

• type: FHIR Search Parameter types

• resource, containing resourceType and id

• jsonknife expression containing path in the resource to search for

• name to use in search

After your Aidbox loads the service, you can use new search parameter:

GET /Patient?brthd=lt2023

You can always look into the definition of Aidbox-specific namespaces in Profiles page

Formal Zen SearchParameters description:

pageZen Search Parameters

Composite search parameter

Read Composite Search Parameters first.

Composite search parameter must contain additional key: components. It must be a nested array in following structure:

[ <paths-to-search-for-value1> <paths-to-search-for-value2> ...]

In this example we create SearchParameter with name composite-string-date which will look for two parts: one is string, the other is date.

 {ns ...
 import #{...
          aidbox.search-parameter.draft
          ...}

 our-param-composite-string-date
 {:zen/tags #{aidbox.search-parameter.draft/composite-search-parameter}
  :name "composite-string-date"
  :type :composite
  :resource {:resourceType "Entity" :id "SomeType"}
  :expression [[]]
  :components [[["name" "given"] ["name" "family"]] [["mydate"]]]
  :search-types [:string :date]}

This request

GET /SomeType?composite-string-date=somename$2023-08-01

will search somename in name.given and name.family, 2023-08-01 in mydate in SomeType resources.