Method: fhirStores.executeCohort

Full name: projects.locations.datasets.fhirStores.executeCohort

Executes and materializes a cohort definition from a FHIR store.

This method returns an Operation that can be used to track the status of the cohort execution by calling operations.get.

Immediate fatal errors appear in the error field, errors are also logged to Cloud Logging (see Viewing error logs in Cloud Logging). Otherwise, when the operation finishes, a detailed response of type ExecuteCohortResponse is returned in the response field. The metadata field type for this operation is OperationMetadata.

HTTP request

POST https://healthcare.googleapis.com/v1beta1/{name=projects/*/locations/*/datasets/*/fhirStores/*}:executeCohort

The URL uses gRPC Transcoding syntax.

Path parameters

Parameters
name

string

Required. The name of the FHIR store to query, in the format projects/{projectId}/locations/{locationId}/datasets/{datasetId}/fhirStores/{fhirStoreId}.

Authorization requires the following IAM permission on the specified resource name:

  • healthcare.fhirStores.export

Request body

The request body contains data with the following structure:

JSON representation 
{
  "_at": string,
  "validateOnly": boolean,

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "gcsDestination": {
    object(GcsDestination)
  }
  // End of mutually exclusive fields.

  // The following is a list of mutually exclusive fields. At most one of the
  // fields will be set in a response:
  "fhirpathQuery": {
    object(FHIRPathQuery)
  }
  // End of mutually exclusive fields.
}
Fields
_at

string(Timestamp format)

Optional. If provided, the queried resources will represent the state of the FHIR store at the given past timestamp. Runs the operation against the state of the store at this timestamp. State of the store is represented by the resource versions that were the current versions during the time specified or the resources that have not been updated since. Only works if the store has history enabled.

Although users should be able to use this field to reproduce previous runs of the operation and get consistent results, there are a few cases where the past state of the store can be altered, thus resulting in no guarantee of reproducibility. For example, resource versions can be deleted using the purge method, or modified using [fhirStores.importHistory][].

Uses RFC 3339, where generated output will always be Z-normalized and use 0, 3, 6 or 9 fractional digits. Offsets other than "Z" are also accepted. Examples: "2014-10-02T15:01:23Z", "2014-10-02T15:01:23.045123456Z" or "2014-10-02T15:01:23+05:30".
validateOnly

boolean

Optional. If true, the request will be validated but no cohort execution will be run.

The output destination of the queried resources.

To enable the Cloud Healthcare API to write to resources in your project such as Cloud Storage buckets, you must grant the Healthcare Service Agent account the required permissions. For steps to assign the permissions, see Exporting data to Cloud Storage. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
gcsDestination

object(GcsDestination)

The Cloud Storage output destination.

The Healthcare Service Agent account requires the roles/storage.objectAdmin role on the Cloud Storage location.

The exported outputs are organized by FHIR resource types. The server creates one or more objects per resource type depending on the volume of the resources exported. When there is only one object per resource type, the object name is in the form of {operation_id}_{resourceType}. When there are multiple objects for a given resource type, the object names are in the form of {operation_id}_{resourceType}-{index}-of-{total}.

Each object contains newline delimited JSON, and each line is a FHIR resource.
End of mutually exclusive fields.
The query or expression language used to filter the data. The following is a list of mutually exclusive fields. At most one of the fields will be set in a response:
fhirpathQuery

object(FHIRPathQuery)

Return resources that match the specified FHIRPath expressions.
End of mutually exclusive fields.

Response body

If successful, the response body contains an instance of Operation.

Authorization scopes

Requires one of the following OAuth scopes:

  • https://www.googleapis.com/auth/cloud-healthcare
  • https://www.googleapis.com/auth/cloud-platform

For more information, see the Authentication Overview.

FHIRPathQuery

A set of FHIRPath expressions that are used to filter the FHIR resources. These expressions do not maintain referential integrity on the resulting resources. Users are responsible for making sure the expressions are written in a way to ensure that if desired.

JSON representation 
{
  "expressions": [
    {
      object(Expression)
    }
  ],
  "engineVersion": string
}
Fields
expressions[]

object(Expression)

Required. List of FHIRPath expressions used for filtering the data.
engineVersion

string

Optional. FHIRPath engine version number, for example "1.0". Will use the latest version if not specified. For more details about the supported versions, see https://cloud.google.com/healthcare-api/private/docs/how-tos/fhir-execute-cohort#fhirpath-engine-versions.

Expression

A FHIRPath expression.

JSON representation 
{
  "fhirpathExpression": string,
  "label": string
}
Fields
fhirpathExpression

string

Required. FHIRPath expression used for evaluation against FHIR resources. Must be in the format [<ResourceType>/"Resource"/"DomainResource"].[expression] Expressions are applied per single FHIR resource, so they can't span multiple base resource types. For example, expressions like Patient.union(Encounter) are invalid. For expressions involving more than one resource or resource type, consider using the FHIRPath resolve() method.

Expressions are only allowed to evaluate to a boolean type or a single or collection of FHIR.Resource types. Expressions evaluating to boolean would include the base resource in the result if the expression evaluates to true. Expressions evaluating to one or more FHIR.Resource types will include those resources in the result, e.g. CareTeam.member.resolve().
label

string

Optional. Expressions with the same label will be grouped together under the same directory when exporting to Cloud Storage.