On this page:

5.11Custom Search Parameters

 

The FHIR specification includes a rich set of default Search Parameters. For example, see the Patient Resource Search Parameters.

This list is only the default however. You can create your own Search Parameters in Smile CDR in order to index fields and extensions that are not indexed by default. You can also customize how Search Parameters behave.

In FHIR, a Search Parameter is defined using a special resource called SearchParameter. You can customize and update existing SearchParameters (which are automatically inserted into your database the first time the system starts up) and you can add new ones too.

5.11.1An Example Search Parameter

 

What follows is an example of a search parameter on an extension. We'll suppose that in our system we've defined an extension for a given patient's eye colour. Patient resources stored in our database will have the eye colour extension set, and we want to be able to search on this extension, too.

1. Create the Search Parameter

First, define a search parameter and upload it to your server. The following shows the SearchParameter resource:

{
	"resourceType": "SearchParameter",
	"title": "Eye Colour",
	"base": [ "Patient" ],
	"status": "active",
	"code": "eyecolour",
	"type": "token",
	"expression": "Patient.extension('http://acme.org/eyecolour')",
	"xpathUsage": "normal"
}

In Java, this can be created as follows:

// Create a search parameter definition
SearchParameter eyeColourSp = new SearchParameter();
eyeColourSp.addBase("Patient");
eyeColourSp.setCode("eyecolour");
eyeColourSp.setType(org.hl7.fhir.dstu3.model.Enumerations.SearchParamType.TOKEN);
eyeColourSp.setTitle("Eye Colour");
eyeColourSp.setExpression("Patient.extension('http://acme.org/eyecolour')");
eyeColourSp.setXpathUsage(org.hl7.fhir.dstu3.model.SearchParameter.XPathUsageType.NORMAL);
eyeColourSp.setStatus(org.hl7.fhir.dstu3.model.Enumerations.PublicationStatus.ACTIVE);

// Upload it to the server
client
	.create()
	.resource(eyeColourSp)
	.execute();

2. Upload Some Resources

Let's upload two Patient resources with different eye colours.

{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://acme.org/eyecolour",
      "valueCode": "blue"
    }
  ],
  "active": true
}
{
  "resourceType": "Patient",
  "extension": [
    {
      "url": "http://acme.org/eyecolour",
      "valueCode": "green"
    }
  ],
  "active": true
}

3. Search!

Finally, let's try searching: http://example.com:8000/Patient?eyecolour=blue

This produces a search result that contains only the matching resource:

{
  "resourceType": "Bundle",
  "id": "bc89e883-b9f7-4745-8c2f-24bf9277664d",
  "meta": {
    "lastUpdated": "2017-02-07T20:30:05.445-05:00"
  },
  "type": "searchset",
  "total": 1,
  "link": [
    {
      "relation": "self",
      "url": "http://example.com:8000/fhir/context/Patient?eyecolour=blue"
    }
  ],
  "entry": [
    {
      "fullUrl": "http://example.com:8000/fhir/context/Patient/2",
      "resource": {
        "resourceType": "Patient",
        "id": "2",
        "meta": {
          "versionId": "1",
          "lastUpdated": "2017-02-07T20:30:05.317-05:00"
        },
        "extension": [
          {
            "url": "http://acme.org/eyecolour",
            "valueCode": "blue"
          }
        ],
        "active": true
      },
      "search": {
        "mode": "match"
      }
    }
  ]
}

5.11.2Search Parameter Expressions

 

The SearchParameter.expression element determines the exact path within the resource that should be extracted and indexed when a target resource is being stored.

See FHIRPath Expressions for examples.

5.11.3Enforcing Uniqueness

 

This section outlines how to ensure that values are unique within a repository.

Unique Composite Search Parameters

Unique composite search parameters are special search parameters that are a combination of one or more existing search parameters. These search parameters enforce uniqueness for the values matched by the given search parameters across the entire repository.

Consider a repository that stores Encounter resources. These encounters have a subject (the Patient) and a date (the date of the encounter). This combination of parameters may be expressed using a search such as the following URL: https://try.smilecdr.com:8000/baseR4/Encounter?date=2017-07-09&subject=Patient/b765fe0d-34fa-4427-b540-1be4ec4acbda

Now, suppose you wish to enforce a business rule that a given Patient may only have one Encounter per day. A composite search parameter can be used to enforce this uniqueness by declaring that combinations of the Encounter:date and Encounter:subject search parameters are globally unique.

Unique Composite Search Parameters enforce this uniqueness using a unique database index enforced by the RDBMS, so they are consistent even under high concurrency. They are declared using a SearchParameter resource. The following example shows a SearchParameter resource for this case (R4+ syntax shown below):

{
  "resourceType": "SearchParameter",
  "extension": [
    {
      "url": "http://hapifhir.io/fhir/StructureDefinition/sp-unique",
      "valueBoolean": true
    }
  ],
  "status": "active",
  "code": "subject-and-date",
  "base": [
    "Encounter"
  ],
  "type": "composite",
  "expression": "Encounter",
  "component": [
    {
      "definition": "SearchParameter/123",
      "expression": "Encounter"
    },
    {
      "definition": "SearchParameter/456",
      "expression": "Encounter"
    }
  ]
}

The composite search parameter above contains two references to other SearchParameter resources (in this case, Encounter:patient and Encounter:date, which are represented by the IDs SearchParameter/123 and SearchParameter/456 respectively).

In order to create the composite search parameter, first the existing SearchParameter resources should be looked up to determine their respective IDs. This can be done using a query such as the following example: http://example.com:8000/SearchParameter?base=Encounter&code=date,patient

This returns a result such as the following (most of the content has been removed for readability):

{
  "resourceType": "Bundle",
  "type": "searchset",
  "entry": [
    {
      "resource": {
        "resourceType": "SearchParameter",
        "id": "123",
        "code": "patient"
      }
    },
    {
      "resource": {
        "resourceType": "SearchParameter",
        "id": "456",
        "code": "date"
      }
    }
  ]
}

Note that it is not necessary for the parameter to have more than one component. If a single search parameter should be unique, the composite search parameter may have a single component.

The http://hapifhir.io/fhir/StructureDefinition/sp-unique extension must exist in a search parameter in order for it to be indexed as a unique search parameter, and this extension should have a boolean value of true as shown above.