This page describes how to configure a FHIR store to support custom search parameters for fields and extensions that are not covered by the FHIR standard search parameters.
Custom search parameters can be useful in many situations, including the following:
- You need to search for a field in a FHIR resource, but there isn't a supported search parameter for the field.
- You need to search in extensions added to the FHIR data model.
Overview
By default, searching for FHIR resources supports the standard search parameters defined in the FHIR specification, with some exclusions documented in the FHIR capability statement or FHIR conformance statement.
You can create one or more custom search parameters and
configure the FHIR store to support them in queries through the search
method. Custom search parameters are useful in the following situations:
- To search in fields not covered by standard search parameters.
- To search in extensions to the FHIR data model.
Many FHIR implementation guides define search parameters, which you can use in your searches.
Custom search parameters support the same search behavior, including advanced FHIR search features as standard search parameters, such as the following:
- modifiers
_include
and_revinclude
- chained search
_sort
To enable a custom search for your FHIR store, you must first create one or more
SearchParameter
resources that define the search behavior. SearchParameter
is a standard FHIR resource type that can be created, updated, or deleted using
the same methods as any other resource type. See
Create a search parameter resource in the store.
SearchParameter
resources in a FHIR store do not take effect until configured
using the configureSearch
method. This method enables a list of custom search parameters. Each time it is called,
it replaces the previous list of parameters. A long-running operation is triggered for
configureSearch
to reindex all relevant resources within the store according
to the new search configuration. All new and updated resources after the method
call are indexed according to the new configuration. Any index data for
custom search parameters that are no longer in the configuration are removed.
For more details on how to use configureSearch
, see Enable the custom search parameter for your FHIR store.
The store's CapabilityStatement
, retrieved through the fhir.capabilities
method, lists both standard and custom search parameters. Search
parameters for a resource are found in the rest.resource.searchParam
field.
Create a custom FHIR search
Create a SearchParameter resource in the FHIR store
The following samples show how to create a custom search parameter resource
using the projects.locations.datasets.fhirStores.fhir.create
method. You can also use the projects.locations.datasets.fhirStores.import
method.
For descriptions of the relevant fields of search parameters, see SearchParameter resource fields.
curl
The following sample shows a POST
request using curl
.
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"resourceType\": \"SearchParameter\", \"url\": \"CANONICAL_URL\", \"base\": [\"RESOURCE_TYPE\"], \"code\": \"SEARCH_PARAMETER_CODE\", \"name\": \"SEARCH_PARAMETER_NAME\", \"type\": \"SEARCH_PARAMETER_TYPE\", \"expression\": \"SEARCH_PARAMETER_EXPRESSION\", \"status\": \"active\", \"description\": \"SEARCH_PARAMETER_DESCRIPTION\" }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"
If the request is successful, the server returns the response in JSON format:
{ "resourceType": "SearchParameter", "url": "CANONICAL_URL", "base": ["RESOURCE_TYPE"], "code": "SEARCH_PARAMETER_CODE", "name": "SEARCH_PARAMETER_NAME", "type": "SEARCH_PARAMETER_TYPE", "expression": "SEARCH_PARAMETER_EXPRESSION", "status": "active", "description": "SEARCH_PARAMETER_DESCRIPTION", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, }
PowerShell
The following sample shows a POST
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $SearchParameter = '{ "resourceType": "SearchParameter", "url": "CANONICAL_URL", "base": ["RESOURCE_TYPE"], "code": "SEARCH_PARAMETER_CODE", "name": "SEARCH_PARAMETER_NAME", "type": "SEARCH_PARAMETER_TYPE", "expression": "SEARCH_PARAMETER_EXPRESSION", "status": "active", "description": "SEARCH_PARAMETER_DESCRIPTION" }' Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $SearchParameter ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter" | ConvertTo-Json
If the request is successful, the server returns the response in JSON format:
{ "resourceType": "SearchParameter", "url": "CANONICAL_URL", "base": ["RESOURCE_TYPE"], "code": "SEARCH_PARAMETER_CODE", "name": "SEARCH_PARAMETER_NAME", "type": "SEARCH_PARAMETER_TYPE", "expression": "SEARCH_PARAMETER_EXPRESSION", "status": "active", "description": "SEARCH_PARAMETER_DESCRIPTION", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, }
Enable the custom search parameter for your FHIR store
To enable one or more custom search parameters for your FHIR store, make a
POST
request to the [store base URL]:configureSearch
method and specify the
canonical URL for each search parameter that you are enabling.
Canonical URLs are specified in either of the following formats:
uri
: Selects the largestversion
available in the store for that URI.uri|version
Selects a specific version.
For example, if the store contains versions 1.0.0
and 1.0.1
for search parameters with the http://example.com/search
URI,
the canonical URL http://example.com/search|1.0.0
selects the 1.0.0
version. The canonical URL http://example.com/search
selects the
1.0.1
version.
The list of URLs provided to this method replaces any previous configuration
and removes custom search parameters that were previously in effect. The
configuration is cached based on the contents of the SearchParameter
resources that existed at the time configureSearch
was called. The
configuration will not be updated if the SearchParameter
resources are updated
or deleted until configureSearch
is called again.
When the [store base URL]:configureSearch
method call is successful, the
return value is the name of a long-running operation to reindex the resources in
the store according to the new configuration. You can view the status of the
long-running operation using the operations.get
method, and you can cancel it using the operations.cancel
method. The status contains a counter indicating how many resources have been
successfully reindexed.
Searches on the store continue to function normally while the long-running operation runs, except that custom search parameters that are added or changed by this operation return partial results. Canceling the operation is safe, but results in the partial indexing of the custom search parameters. It is important to complete an entire successful reindexing operation before searching with newly added or changed parameters.
If there are errors, they are displayed in Cloud Logging.
The configureSearch
method can also be used with the option
"validate_only": true
to validate the specified search parameters without
modifying the store configuration and without reindexing any data.
The following samples show how to enable one or more custom search parameters
for your FHIR store using the
projects.locations.datasets.fhirStores.configureSearch
method.
curl
The following sample shows a POST
request using curl
.
curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"canonicalUrls\": [\"CANONICAL_URL1\",\"CANONICAL_URL2\"], }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
The response contains an operation name. To track the status of the operation,
you can use the
Operation get
method:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
If the long-running operation is still running, the server returns a response with the number of FHIR resources pending reindexing in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.ConfigureSearch", "createTime": "CREATE_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", "counter": { "pending": "PENDING_COUNT" } } }
When the LRO finishes, the server returns a response with the status of the operation in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.configureSearch", "createTime": "CREATE_TIME", "endTime": "END_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", "counter": { "success": "SUCCESS_COUNT" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty", } }
If the LRO succeeds, the response contains the number of FHIR resources successfully reindexed and a google.protobuf.Empty
response type.
PowerShell
The following sample shows a POST
request using Windows PowerShell.
$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $configureSearch = '{ "canonical_urls": [ "CANONICAL_URL1", "CANONICAL_URL2" ] }' Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $configureSearch ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
The response contains an operation name. To track the status of the operation,
you can use the
Operation get
method:
curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID"
If the long-running operation is still running, the server returns a response with the number of FHIR resources pending reindexing in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1beta1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1beta1.fhir.FhirStoreService.ConfigureSearch", "createTime": "CREATE_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", "counter": { "pending": "PENDING_COUNT" } } }
When the LRO finishes, the server returns a response with the status of the operation in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID", "metadata": { "@type": "type.googleapis.com/google.cloud.healthcare.v1.OperationMetadata", "apiMethodName": "google.cloud.healthcare.v1.fhir.FhirService.configureSearch", "createTime": "CREATE_TIME", "endTime": "END_TIME", "logsUrl": "https://console.cloud.google.com/logs/query/CLOUD_LOGGING_URL", "counter": { "success": "SUCCESS_COUNT" } }, "done": true, "response": { "@type": "type.googleapis.com/google.protobuf.Empty", } }
If the LRO succeeds, the response contains the number of FHIR resources successfully reindexed and a google.protobuf.Empty
response type.
Search for resources with a custom search
You can search using a custom SearchParameter the same way as any
other search. Use the code
value from the search parameter resource as the key
for the search query. For more information, see Searching for FHIR resources.
SearchParameter resource fields
The following section describes the fields of the SearchParameter resource that are relevant to custom searches. These fields are available in both the STU3 and R4 versions of FHIR.
uri
and version
The uri
field, which is required, and the version
fields, which are optional, define the canonical url for the SearchParameter resource. The
combination of uri
and version
must be unique within the FHIR store.
The canonical URL is the URL used in the configureSearch
call.
name
, description
, and status
The name
, description
, and status
fields are required but have no
functional effect.
base
The base
field lists the FHIR resource types to which this search
applies.
If there is more than one type, the expression
field must have a clause
for each type. There is no difference between defining one parameter on two
types or defining one parameter for each type. Defining one parameter for
multiple resource types makes the definitions more compact.
code
The code
field defines the key to use in a FHIR search query. For example,
if code
is defined as payment-type
and base
is defined as Claim
, a search query using this parameter would be
Claim?payment-type=ABC
.
The code
field can't have the same value as any other standard or
custom search parameter on the same resource type. The standard
search parameters can't be redefined or modified using custom search
parameters. The configureSearch
method rejects duplicate search parameters.
The value of the code
field must meet the following requirements:
- Must start with a letter
- Can't be longer than 64 characters
- Must contain only the following:
- Alphanumeric characters
- Hyphen character
-
- Underscore character
_
The FHIR standard convention for the code
field is lowercase with dashes.
type
The type
field defines the search parameter type. The search parameter type
determines the semantics of the search conditions as defined in the
FHIR search specification.
This value of type
must be compatible with the data type of the field
specified by the expression
field. If it is not, configureSearch
rejects
the custom search parameter.
The type
field must be defined as one of the following:
number
date
string
token
reference
quantity
uri
The composite
and special
types are not supported.
expression
The expression
field defines which fields or extensions the search parameter
queries. This field uses a limited set of the syntax and functions of FHIRPath.
Field syntax
The expression
field is defined as a path starting with the resource type and followed
by one or more fields separated by .
, for example, Patient.contact.name.given
. The
field structure of FHIR data can be found in the FHIR resources
and FHIR datatypes.
Multiple clauses
The expression
field can contain multiple clauses separated by |
. In this case, the
search parameter matches if any of the clauses match the resource. For
example, a search parameter with the expression Patient.name.given | Patient.name.family
matches either of those two fields. Use multiple clauses when more
than one resource type is specified in base
. For example Patient.name.given | Practitioner.name.given
for a search parameter that applies to both Patient
and Practitioner
.
.as([data type])
Use the function .as([data type])
when a field has more than one potential
data type. For example, the Observation.value
field can contain many different
types, such as Quantity
and String
, which work with different search types.
You can select these search types with Observation.value.as(Quantity)
or
Observation.value.as(String)
.
Selecting extensions
You can select extensions with the .extension([canonical url])
function.
Because extensions contain a value
field that can contain any data type, the
full path is defined as .extension([canonical url]).value.as([data type])
.
Complex extensions can use multiple .extension()
components, for example
Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-citizenship').extension('code').value.as(CodeableConcept)
.
You can also use the .extension.where(url='[canonical url]')
function to
select extensions. This is the only context where the where()
function is
allowed.
No other FHIRPath functions are supported.
target
If the type
field is defined as reference
, the target
field must contain
one or more FHIR resource types that define which resource types can be the target
of this reference search.
For example, if the Patient.generalPractitioner
field allows references to
Practitioner
, PractitionerRole
, and Organization
, a search parameter can specifically match references to Practitioner
, PractitionerRole
, or Organization
.
To match all target types of references, include all types in the target
field.
modifier
, comparator
, multipleOr
, multipleAnd
, and chain
The modifier
, comparator
, multipleOr
, multipleAnd
, and
chain
fields are ignored. The options and functionality available with a custom
search parameter are the same as those supported by the FHIR store on a
standard search parameter of the same type.
Use search parameters from an implementation guide
If you are implementing search parameters obtained from a FHIR implementation
guide, import the SearchParameter
resources from your implementation guide's
JSON file into the FHIR store using either of the following methods:
In some instances, you must convert a published search parameter for
the Cloud Healthcare API to support it. If the search parameters are not converted,
the configureSearch
method rejects them. The following constraints apply to search
parameters from implementation guides:
If the search parameter is identical to parameters in the base FHIR specification, the
configureSearch
method rejects the duplicate search parameters. Omit such duplicates when callingconfigureSearch
. For more information, seecode
.If the search parameter only contains an
xpath
expression, convert the expression to an equivalent FHIRPath expression and use it in theexpression
field. For more information, seeexpression
.The
composite
andspecial
search parameter types are not supported.The alternate type-casting syntax
([field] as [data type])
is not supported. Convert to the supported equivalent[field].as([data type])
. For more information, see.as([data type])
.The
[reference field].where(resolve() is [resource type])
convention for constraining the type of a referenced resource is not supported. Remove thewhere()
clause and store the referenced resource type in theSearchParameter.target
field instead. For more information, seetarget
.Some implementation guides use expressions for extensions that omit some of the path components required by the Cloud Healthcare API FHIR store. For example,
Patient.extension('url')
must be modified toPatient.extension('url').value.as([data type])
, andPatient.extension('url').extension.value
must be modified toPatient.extension('url').extension('url2').value.as([data type])
.
Examples
Use a custom search to search on an extension field
The following steps show an example of searching for text within
the mothersMaidenName
extension in Patient resources.
Create a sample Patient resource:
curl
The following sample shows how to create a Patient resource by making a
POST
request usingcurl
. This Patient resource has themothersMaidenName
extension set toMarca
.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"name\": [ { \"use\": \"official\", \"family\": \"Smith\", \"given\": [ \"Darcy\" ] } ], \"gender\": \"female\", \"birthDate\": \"1970-01-01\", \"resourceType\": \"Patient\", \"extension\": [ { \"url\": \"http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName\", \"valueString\": \"Marca\" } ] }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient"
If the request is successful, the server returns a response similar to the following sample in JSON format:
{ "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "valueString": "Marca" } ] }
PowerShell
The following sample shows how to create a Patient resource by making a
POST
request using Windows PowerShell. This Patient resource has themothersMaidenName
extension set toMarca
.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $Patient = '{ "name": [ { "use": "official", "family": "Smith", "given": [ "Darcy" ] } ], "gender": "female", "birthDate": "1970-01-01", "resourceType": "Patient", "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "valueString": "Marca" } ] }' Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json; charset=utf-8" ` -Body $Patient ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient" | ConvertTo-Json
If the request is successful, the server returns a response similar to the following sample in JSON format:
{ "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "valueString": "Marca" } ] }
Create a custom search parameter resource:
curl
The following sample shows how to create the custom search parameter resource for the
mothersMaidenName
extension by making aPOST
request usingcurl
.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"resourceType\": \"SearchParameter\", \"url\": \"http://example.com/SearchParameter/patient-mothersMaidenName\", \"base\": [\"Patient\"], \"code\": \"mothers-maiden-name\", \"name\": \"mothers-maiden-name\", \"type\": \"string\", \"expression\": \"Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)\", \"status\": \"active\", \"description\": \"search on mother's maiden name\" }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"
If the request is successful, the server returns the response in JSON format:
{
"resourceType": "SearchParameter",
"url": "http://example.com/SearchParameter/patient-mothersMaidenName",
"base": ["Patient"],
"code": "mothers-maiden-name",
"name": "mothers-maiden-name",
"type": "string",
"expression": "Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)",
"status": "active",
"description": "search on mother's maiden name",
"meta": {
"lastUpdated": "2020-01-01T00:00:00+00:00",
"versionId": "VERSION_ID"
},
}PowerShell
The following shows how to create the custom search parameter resource for the `mothersMaidenName` extension by making a `POST` request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $SearchParameter = '{ "resourceType": "SearchParameter", "url": "http://example.com/SearchParameter/patient-mothersMaidenName", "base": ["Patient"], "code": "mothers-maiden-name", "name": "mothers-maiden-name", "type": "string", "expression": "Patient.extension(''http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName'').value.as(String)", "status": "active", "description": "search on mother''s maiden name" }' Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $SearchParameter ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"
If the request is successful, the server returns the response in JSON format:
{
"resourceType": "SearchParameter",
"url": "http://example.com/SearchParameter/patient-mothersMaidenName",
"base": ["Patient"],
"code": "mothers-maiden-name",
"name": "mothers-maiden-name",
"type": "string",
"expression": "Patient.extension('http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName').value.as(String)",
"status": "active",
"description": "search on mother's maiden name",
"meta": {
"lastUpdated": "2020-01-01T00:00:00+00:00",
"versionId": "VERSION_ID"
},
}expression
field, use the function.as([data type])
. For example, to specify the search expression for a boolean value, use.value.as(Boolean)
. For more information, see.as([data type])
.Enable the search parameter:
curl
To enable the custom search parameter, make a
POST
request and specify the canonical URL for each search parameter that you are enabling.The following sample shows a
POST
request usingcurl
.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"canonicalUrls\": [\"http://example.com/SearchParameter/patient-mothersMaidenName\"], }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
PowerShell
To enable the custom search parameter, make a
POST
request and specify the canonical URL for each search parameter that you are enabling.The following sample shows a
POST
request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $configureSearch = '{ "canonicalUrls": "http://example.com/SearchParameter/patient-mothersMaidenName" }' ` Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $configureSearch ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
Search using the custom search parameter:
curl
The following sample shows how to search Patient resources for the string
Marca
in themothersMaidenName
extension by making aGET
request usingcurl
.curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?mothers-maiden-name:exact=Marca"
If the request is successful, the server returns the response as a FHIR
Bundle
in JSON format. TheBundle.type
issearchset
and the search results are entries in theBundle.entry
array. In this example, the request returns a single Patient resource including the data inside that resource:{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "valueString": "Marca" } ] }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
The following sample shows how to search Patient resources for the string `Marca` in the `mothersMaidenName` extension by making a `GET` request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?mothers-maiden-name:exact=Marca" | ConvertTo-Json
If the request is successful, the server returns the response as a FHIR
Bundle
in JSON format. TheBundle.type
issearchset
and the search results are entries in theBundle.entry
array. In this example, the request returns a single Patient resource including the data inside that resource:{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/StructureDefinition/patient-mothersMaidenName", "valueString": "Marca" } ] }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?family%3Aexact=Smith" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
Use a custom search to search on a 2-level extension field
The following steps show how to search for the code within the us-core-ethnicity
extension in a Patient resource.
Create a sample Patient resource:
curl
The following sample shows how to create a Patient resource by making a
POST
request usingcurl
. This Patient resource has theus-core-ethnicity
extension set.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"name\": [ { \"use\": \"official\", \"family\": \"Smith\", \"given\": [ \"Darcy\" ] } ], \"gender\": \"female\", \"birthDate\": \"1970-01-01\", \"resourceType\": \"Patient\", \"extension\": [ { \"url\": \"http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity\", \"extension\": [ { \"url\" : \"ombCategory\", \"valueCoding\" : { \"system\" : \"urn:oid:2.16.840.1.113883.6.238\", \"code\" : \"2028-9\", \"display\" : \"Asian\" } } ] } ] }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient"
If the request is successful, the server returns a response similar to the following sample in JSON format:
{ "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity", "extension": [ { "url" : "ombCategory", "valueCoding" : { "system" : "urn:oid:2.16.840.1.113883.6.238", "code" : "2028-9", "display" : "Asian" } } ] } ] }
PowerShell
The following sample shows how to create a Patient resource by making a
POST
request using Windows PowerShell. This Patient resource has theus-core-ethnicity
extension set.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $Patient = '{ "name": [ { "use": "official", "family": "Smith", "given": [ "Darcy" ] } ], "gender": "female", "birthDate": "1970-01-01", "resourceType": "Patient", "extension": [ { "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity", "extension": [ { "url" : "ombCategory", "valueCoding" : { "system" : "urn:oid:2.16.840.1.113883.6.238", "code" : "2028-9", "display" : "Asian" } } ] } ] }' Invoke-RestMethod ` -Method Post ` -Headers $headers ` -ContentType: "application/fhir+json; charset=utf-8" ` -Body $Patient ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient" | ConvertTo-Json
If the request is successful, the server returns a response similar to the following sample in JSON format:
{ "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity", "extension": [ { "url" : "ombCategory", "valueCoding" : { "system" : "urn:oid:2.16.840.1.113883.6.238", "code" : "2028-9", "display" : "Asian" } } ] } ] }
Create a custom search parameter resource:
curl
The following sample shows how to create the custom search parameter resource for theus-core-ethnicity
extension by making aPOST
request usingcurl
.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"resourceType\": \"SearchParameter\", \"url\": \"http://example.com/SearchParameter/patient-us-core-ethnicity\", \"base\": [\"Patient\"], \"code\": \"ethnicity\", \"name\": \"ethnicity\", \"type\": \"token\", \"expression\": \"Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)\", \"status\": \"active\", \"description\": \"search on the ombCategory of a patient.\" }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"
If the request is successful, the server returns the response in JSON format:
{ "resourceType": "SearchParameter", "url": "http://example.com/SearchParameter/patient-us-core-ethnicity", "base": ["Patient"], "code": "ethnicity", "name": "ethnicity", "type": "token", "expression": "Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)", "status": "active", "description": "search on the ombCategory of a patient.", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, }
PowerShell
The following sample shows how to create the custom search parameter resource for the `mothersMaidenName` extension by making a `POST` request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $SearchParameter = '{ "resourceType": "SearchParameter", "url": "http://example.com/SearchParameter/patient-us-core-ethnicity", "base": ["Patient"], "code": "ethnicity", "name": "ethnicity", "type": "token", "expression": "Patient.extension(''http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity'').extension(''ombCategory'').value.as(Coding)", "status": "active", "description": "search on the ombCategory of a patient." }' Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $SearchParameter ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/SearchParameter"
If the request is successful, the server returns the response in JSON format:
{ "resourceType": "SearchParameter", "url": "http://example.com/SearchParameter/patient-us-core-ethnicity", "base": ["Patient"], "code": "ethnicity", "name": "ethnicity", "type": "token", "expression": "Patient.extension('http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity').extension('ombCategory').value.as(Coding)", "status": "active", "description": "search on the ombCategory of a patient.", "meta": { "lastUpdated": "2020-01-01T00:00:00+00:00", "versionId": "VERSION_ID" }, }
Enable the search parameter:
curl
To enable the custom search parameter, make a
POST
request and specify the canonical URL for each search parameter that you are enabling.The following sample shows a
POST
request usingcurl
.curl -X POST \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ -H "Content-Type: application/json; charset=utf-8" \ --data "{ \"canonicalUrls\": [\"http://example.com/SearchParameter/patient-us-core-ethnicity\"], }" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
PowerShell
To enable the custom search parameter, make a
POST
request and specify the canonical URL for each search parameter that you are enabling.The following sample shows a
POST
request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } $configureSearch = '{ "canonicalUrls": "http://example.com/SearchParameter/patient-us-core-ethnicity" }' ` Invoke-WebRequest ` -Method Post ` -Headers $headers ` -ContentType: "application/json; charset=utf-8" ` -Body $configureSearch ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID:configureSearch"
If the request is successful, the server returns the response in JSON format:
{ "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/operations/OPERATION_ID" }
Search using the custom search parameter:
curl
The following sample shows how to search Patient resources for the code
urn:oid:2.16.840.1.113883.6.238|2028-9
in theus-core-ethnicity
extension by making aGET
request usingcurl
.curl -X GET \ -H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \ "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9"
If the request is successful, the server returns the response as a FHIR
Bundle
in JSON format. TheBundle.type
issearchset
and the search results are entries in theBundle.entry
array. In this example, the request returns a single Patient resource including the data inside that resource:{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity", "extension": [ { "url" : "ombCategory", "valueCoding" : { "system" : "urn:oid:2.16.840.1.113883.6.238", "code" : "2028-9", "display" : "Asian" } } ] } ] }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }
PowerShell
The following sample shows how to search Patient resources for the code `urn:oid:2.16.840.1.113883.6.238|2028-9` in the `us-core-ethnicity` extension by making a `GET` request using Windows PowerShell.$cred = gcloud auth application-default print-access-token $headers = @{ Authorization = "Bearer $cred" } Invoke-RestMethod ` -Method Get ` -Headers $headers ` -Uri "https://healthcare.googleapis.com/v1beta1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9 | ConvertTo-Json
If the request is successful, the server returns the response as a FHIR
Bundle
in JSON format. TheBundle.type
issearchset
and the search results are entries in theBundle.entry
array. In this example, the request returns a single Patient resource including the data inside that resource:{ "entry": [ { "fullUrl": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/PATIENT_ID", "resource": { "birthDate": "1970-01-01", "gender": "female", "id": "PATIENT_ID", "meta": { "lastUpdated": "LAST_UPDATED", "versionId": "VERSION_ID" }, "name": [ { "family": "Smith", "given": [ "Darcy" ], "use": "official" } ], "resourceType": "Patient" "extension": [ { "url": "http://hl7.org/fhir/us/core/StructureDefinition/us-core-ethnicity", "extension": [ { "url" : "ombCategory", "valueCoding" : { "system" : "urn:oid:2.16.840.1.113883.6.238", "code" : "2028-9", "display" : "Asian" } } ] } ] }, "search": { "mode": "match" } } ], "link": [ { "url": "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID/fhir/Patient/?ethnicity=urn:oid:2.16.840.1.113883.6.238|2028-9" } ], "resourceType": "Bundle", "total": 1, "type": "searchset" }