Transmitir cambios de recursos FHIR a BigQuery

En esta página, se explica cómo configurar un almacén de FHIR para exportar automáticamente los recursos de FHIR a tablas de BigQuery cada vez que se crea, actualiza, aplica parches o borra un recurso de FHIR. Este proceso se denomina transmisión de BigQuery.

Puedes usar la transmisión de BigQuery para hacer lo siguiente:

Sincronizar los datos en un almacén de FHIR con un conjunto de datos de BigQuery casi en tiempo real
Realiza consultas complejas sobre los datos de FHIR sin necesidad de exportarlos a BigQuery cada vez que quieras analizar los datos.

Para mejorar el rendimiento de las consultas y reducir los costos, puedes configurar la transmisión de BigQuery a tablas particionadas. Para obtener instrucciones, consulta Transmite recursos de FHIR a tablas particionadas.

Antes de comenzar

Consulta Exporta recursos de FHIR a BigQuery para comprender cómo funciona el proceso de exportación.

Limitaciones

Si importas recursos de FHIR desde Cloud Storage, los cambios no se transmitirán a BigQuery.

Configura permisos de BigQuery

Para habilitar la transmisión de BigQuery, debes otorgar permisos adicionales a la cuenta de servicio del agente de servicio de Cloud Healthcare. Para obtener más información, consulta Permisos de BigQuery para el almacén de datos de FHIR.

Configura la transmisión de BigQuery en un almacén de FHIR

Para habilitar la transmisión de BigQuery, configura el objeto StreamConfigs en tu almacén de FHIR. En StreamConfigs, puedes configurar el arreglo resourceTypes[] para controlar a qué tipos de recursos de FHIR se aplica la transmisión de BigQuery. Si no especificas resourceTypes[], la transmisión de BigQuery se aplica a todos los tipos de recursos de FHIR.

Para obtener explicaciones sobre otros parámetros de configuración disponibles en StreamConfigs, como BigQueryDestination, consulta Exporta recursos de FHIR.

En los siguientes ejemplos, se muestra cómo habilitar la transmisión de BigQuery en un almacén de FHIR existente.

Console

Para configurar la transmisión de BigQuery en un almacén de FHIR existente mediante la consola de Google Cloud, completa los siguientes pasos:

En la consola de Google Cloud, ve a la página Conjuntos de datos.

Ir a Conjuntos de datos
Selecciona el conjunto de datos que contenga el almacén de FHIR que deseas editar.
En la lista Almacenes de datos, haz clic en el almacén de FHIR que quieres editar.
En la sección Transmisión de BigQuery, completa los siguientes pasos:
1. Haz clic en Agregar nueva configuración de transmisión.
2. En la sección Nueva configuración de transmisión, haz clic en Explorar para seleccionar el conjunto de datos de BigQuery en el que deseas transmitir los recursos de FHIR modificados.
3. En el menú desplegable Tipo de esquema (Schema type), selecciona el esquema de salida para la tabla de BigQuery. Los siguientes esquemas se encuentran disponibles:
  - Analytics. Un esquema basado en el documento SQL en FHIR. Debido a que BigQuery solo permite 10,000 columnas por tabla, no se generan esquemas para los campos Parameters.parameter.resource, Bundle.entry.resource y Bundle.entry.response.outcome.
  - Analytics V2. Un esquema similar al de Analytics, con compatibilidad adicional para lo siguiente:
    - Extensiones con varios valores para el mismo url
    - Recursos de FHIR contenidos
    El esquema de Analytics V2 utiliza más espacio en la tabla de destino que el esquema de Analytics.
4. Selecciona un nivel de profundidad en el control deslizante de Profundidad de la estructura recursiva para establecer la profundidad en todas las estructuras recursivas en el esquema de salida. De forma predeterminada, el valor recurrente es 2.
5. En la lista Selecciona tipos de recursos de FHIR, selecciona los tipos de recursos que quieres transmitir.
Haz clic en Listo para guardar la configuración de transmisión.

gcloud

Gcloud CLI no admite esta acción. En su lugar, usa la consola de Google Cloud, curl, PowerShell o tu lenguaje preferido.

REST

Para configurar la transmisión de BigQuery en un almacén de FHIR existente, usa el método projects.locations.datasets.fhirStores.patch.

En los siguientes ejemplos, no se especifica el arreglo resourceTypes[], por lo que la transmisión de BigQuery está habilitada para todos los tipos de recursos de FHIR.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_IDEl ID de tu proyecto de Google Cloud.
LOCATION: La ubicación del conjunto de datos
DATASET_ID es el conjunto de datos superior del almacén de FHIR
FHIR_STORE_ID: El ID del almacén de FHIR
BIGQUERY_DATASET_ID: Es el nombre de un conjunto de datos existente de BigQuery en el que transmites cambios de recursos de FHIR.
SCHEMA_TYPE: Un valor para la enumeración SchemaType. Usa uno de los siguientes valores:
- ANALYTICS: Es un esquema basado en el documento SQL en FHIR. Debido a que BigQuery solo permite 10,000 columnas por tabla, no se generan esquemas para los campos Parameters.parameter.resource, Bundle.entry.resource y Bundle.entry.response.outcome.
- ANALYTICS_V2: Es un esquema similar a ANALYTICS, con compatibilidad adicional para lo siguiente:
  - Extensiones con varios valores para el mismo url
  - Recursos de FHIR contenidos
  ANALYTICS_V2 usa más espacio en la tabla de destino que ANALYTICS
  .
WRITE_DISPOSITION: Un valor para la enumeración WriteDisposition. Usa uno de los siguientes valores:
- WRITE_EMPTY. Exporta datos solo si las tablas de destino de BigQuery están vacías.
- WRITE_TRUNCATE. Borra todos los datos existentes en las tablas de BigQuery antes de escribir los recursos de FHIR.
- WRITE_APPEND. Adjuntar datos a las tablas de BigQuery de destino

Cuerpo JSON de la solicitud:

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Nota: Con el siguiente comando, se supone que accediste a la CLI de gcloud con tu cuenta de usuario a través de la ejecución de gcloud init o gcloud auth login, o a través del uso de Cloud Shell, que accede de forma automática a la CLI de gcloud. Para comprobar la cuenta activa actual, ejecuta gcloud auth list.

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

Explorador de APIs

Copia el cuerpo de la solicitud y abre la página de referencia del método. El panel del Explorador de APIs se abre en la parte derecha de la página. Puedes interactuar con esta herramienta para enviar solicitudes. Pega el cuerpo de la solicitud en esta herramienta, completa cualquier otro campo obligatorio y haz clic en Ejecutar.

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Si configuraste algún campo en el recurso FhirStore, también aparecerá en la respuesta.

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

De forma predeterminada, cuando transmites cambios de los recursos de FHIR a BigQuery, se crea una vista para cada recurso que se transmite. La vista tiene las siguientes propiedades:

Tiene el mismo nombre que el recurso y su tabla en el conjunto de datos de BigQuery. Por ejemplo, cuando transmites un recurso de paciente, se crea una tabla llamada Patient con una vista llamada Patientview.
Solo contiene la versión actual del recurso, en lugar de todas las versiones históricas.

Transmite recursos de FHIR a tablas particionadas

Para exportar recursos de FHIR a tablas particionadas de BigQuery, configura la enumeración TimePartitioning en el campo lastUpdatedPartitionConfig del almacén de FHIR.

Las tablas particionadas funcionan como las tablas particionadas por unidad de tiempo de BigQuery. Las tablas particionadas tienen una columna agregada llamada lastUpdated, que es un duplicado de la columna meta.lastUpdated que se genera a partir del campo meta.lastUpdated en un recurso de FHIR. BigQuery usa la columna lastUpdated para particionar las tablas por hora, día, mes o año.

Consulta Selecciona una partición diaria, por hora, mensual o anual para obtener recomendaciones sobre cómo seleccionar el nivel de detalle de una partición.

No se pueden convertir tablas existentes de BigQuery no particionadas en tablas particionadas. Si exportas cambios de recursos de pacientes a una tabla Patients no particionada y, luego, creas un almacén de FHIR nuevo con partición de tabla que se exporta al mismo conjunto de datos de BigQuery, la API de Cloud Healthcare exporta datos a la tabla Patients no particionada. Para comenzar a usar una tabla particionada, borra la tabla Patients existente o usa un conjunto de datos de BigQuery diferente.

Si agregas una partición a una configuración de almacén de FHIR existente, aún puedes exportar a tablas no particionadas existentes. Sin embargo, la partición solo se aplicará en tablas nuevas.

En los siguientes ejemplos, se muestra cómo habilitar la transmisión de BigQuery a tablas particionadas en un almacén de FHIR existente.

Console

La consola de Google Cloud y la CLI de gcloud no admiten esta acción. En su lugar, usa curl, PowerShell o tu lenguaje preferido.

gcloud

La consola de Google Cloud y la CLI de gcloud no admiten esta acción. En su lugar, usa curl, PowerShell o tu lenguaje preferido.

REST

Si deseas configurar la transmisión de BigQuery a tablas particionadas en un almacén de FHIR existente, usa el método projects.locations.datasets.fhirStores.patch.

Antes de usar cualquiera de los datos de solicitud a continuación, realiza los siguientes reemplazos:

PROJECT_IDEl ID de tu proyecto de Google Cloud.
LOCATION: La ubicación del conjunto de datos
DATASET_ID es el conjunto de datos superior del almacén de FHIR
FHIR_STORE_ID: El ID del almacén de FHIR
BIGQUERY_DATASET_ID: Es el nombre de un conjunto de datos existente de BigQuery en el que transmites cambios de recursos de FHIR.
SCHEMA_TYPE: Un valor para la enumeración SchemaType. Usa uno de los siguientes valores:
- ANALYTICS: Es un esquema basado en el documento SQL en FHIR. Debido a que BigQuery solo permite 10,000 columnas por tabla, no se generan esquemas para los campos Parameters.parameter.resource, Bundle.entry.resource y Bundle.entry.response.outcome.
- ANALYTICS_V2: Es un esquema similar a ANALYTICS, con compatibilidad adicional para lo siguiente:
  - Extensiones con varios valores para el mismo url
  - Recursos de FHIR contenidos
  ANALYTICS_V2 usa más espacio en la tabla de destino que ANALYTICS
  .
TIME_PARTITION_TYPE: Es el nivel de detalle con el que se particionan los recursos de FHIR exportados. Usa uno de los siguientes valores:
- HOUR: Datos de partición por hora
- DAY: particionar datos por día
- MONTH: Datos de partición por mes
- YEAR: Datos de partición por año
WRITE_DISPOSITION: Un valor para la enumeración WriteDisposition. Usa uno de los siguientes valores:
- WRITE_EMPTY. Exporta datos solo si las tablas de destino de BigQuery están vacías.
- WRITE_TRUNCATE. Borra todos los datos existentes en las tablas de BigQuery antes de escribir los recursos de FHIR.
- WRITE_APPEND. Adjuntar datos a las tablas de BigQuery de destino

Cuerpo JSON de la solicitud:

{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Para enviar tu solicitud, elige una de estas opciones:

curl

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

cat > request.json << 'EOF'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
EOF

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

curl -X PATCH \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs"

PowerShell

Guarda el cuerpo de la solicitud en un archivo llamado request.json. Ejecuta el comando siguiente en la terminal para crear o reemplazar este archivo en el directorio actual:

@'
{
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}
'@  | Out-File -FilePath request.json -Encoding utf8

Luego, ejecuta el siguiente comando para enviar tu solicitud de REST:

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method PATCH `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://healthcare.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID?updateMask=streamConfigs" | Select-Object -Expand Content

Explorador de APIs

Deberías recibir una respuesta JSON similar a la que se muestra a continuación:

Respuesta

{
  "name": "projects/PROJECT_ID/locations/LOCATION/datasets/DATASET_ID/fhirStores/FHIR_STORE_ID",
  "version": "FHIR_STORE_VERSION",
  "streamConfigs": [
    {
      "bigqueryDestination": {
        "datasetUri": "bq://PROJECT_ID.BIGQUERY_DATASET_ID",
        "schemaConfig": {
          "schemaType": "SCHEMA_TYPE",
          "lastUpdatedPartitionConfig": {
            "type": "TIME_PARTITION_TYPE"
          }
        },
        "writeDisposition": "WRITE_DISPOSITION"
      }
    }
  ]
}

Consulta una tabla particionada

Si deseas reducir los costos de consulta cuando consultas tablas particionadas, usa la cláusula WHERE para filtrar por unidades de tiempo.

Por ejemplo, supongamos que estableciste la enumeración PartitionType en DAY. Para consultar una tabla Patients de los recursos de paciente que cambiaron en una fecha específica, ejecuta la siguiente consulta:

SELECT * FROM `PROJECT_ID.BIGQUERY_DATASET.Patients`
  WHERE DATE(lastUpdated) = 'YYYY-MM-DD'

Migre de Analytics a Analytics V2

No puedes migrar un conjunto de datos existente de BigQuery del esquema Analytics al esquema Analytics V2 con ningún método, incluido el siguiente:

Cambia el tipo de esquema de la tabla en BigQuery.
Cambiar el tipo de esquema en una configuración de transmisión de FHIR existente.

Esto se debe a que las columnas de la tabla de BigQuery para las extensiones de FHIR en el esquema Analytics tienen su modo establecido en NULLABLE, mientras que las del esquema Analytics V2 las tienen establecido en REPEATED. BigQuery no permite cambiar el modo de una columna de NULLABLE a REPEATED. Por lo tanto, los dos tipos de esquema son incompatibles.

Para migrar el tipo de esquema de los recursos de FHIR exportados de Analytics a Analytics V2, debes exportar los recursos de FHIR a un nuevo conjunto de datos de BigQuery mediante una nueva configuración de transmisión con el tipo de esquema actualizado. Para hacerlo, sigue estos pasos:

Crea un conjunto de datos nuevo de BigQuery.
Configura permisos para el conjunto de datos de BigQuery.
Agrega una configuración de transmisión nueva al almacén de FHIR con el tipo de esquema establecido en Analytics V2.
Para reabastecer los datos existentes, exporta los datos de FHIR existentes con la siguiente configuración. Consulta Exporta recursos de FHIR si quieres obtener instrucciones para establecer esta configuración con la consola de Google Cloud, Google Cloud CLI o la API de REST. La siguiente configuración se aplica a la API de REST:
- Establece WriteDisposition en WRITE_APPEND para adjuntar los datos a la tabla de destino.
- Establece SchemaType en ANALYTICS_V2.

Es posible que las vistas en BigQuery que corresponden a algunos o todos los recursos de FHIR en el conjunto de datos original de BigQuery falten en tu conjunto de datos nuevo. Para solucionar este problema, consulta Creación de vistas de recursos de FHIR faltantes.

Soluciona problemas de transmisión de FHIR

Si se producen errores cuando se envían cambios de recursos a BigQuery, los errores se registran en Cloud Logging. Para obtener más información, consulta Visualiza los registros de errores en Cloud Logging.

No se puede convertir la columna de NULLABLE a REPEATED

Este error se produce por una extensión repetida. Para resolver este error, usa el tipo de esquema ANALYTICS_V2. Si ya usas ANALYTICS_V2, es posible que haya un conflicto entre dos extensiones o un conflicto entre una extensión y otro campo.

Los nombres de columna se generan a partir del texto después del último carácter / en las URLs de extensión. Si una URL de extensión termina con un valor como /resource_field name, puede producirse un conflicto.

Para evitar que se repita este error, no uses extensiones si sus nombres de campo son los mismos que los de los campos de recursos que quieres propagar.

Falta la creación de vistas de recursos de FHIR

Si exportas de forma masiva un recurso de FHIR a BigQuery antes de transmitir ese recurso, BigQuery no creará vistas para ese recurso.

Por ejemplo, es posible que no veas ninguna vista de los recursos de encuentro en la siguiente situación:

Configura la transmisión de BigQuery en un almacén de FHIR y, luego, usa la API de REST para crear un recurso de paciente.

BigQuery crea una tabla y una vista para el recurso de paciente.
Exportas de forma masiva los recursos de Encounter al mismo conjunto de datos de BigQuery que realizaste en el paso anterior.

BigQuery crea una tabla para los recursos de encuentro.
Usa la API de REST para crear un recurso de encuentro.

Después de este paso, no se crean las vistas de BigQuery para el recurso de encuentro.

A fin de resolver este problema, usa la siguiente consulta para crear una vista:

SELECT
    * EXCEPT (_resource_row_id)
FROM (
  SELECT
    ROW_NUMBER() OVER(PARTITION BY id ORDER BY meta.lastUpdated DESC) as _resource_row_id,
    *
    FROM `PROJECT_ID.BIGQUERY_DATASET_ID.RESOURCE_TABLE` AS p
) AS p
WHERE
  p._resource_row_id=1
  AND
  NOT EXISTS (
  SELECT
    *
  FROM
    UNNEST(p.meta.tag)
  WHERE
    code = 'DELETE');

Reemplaza lo siguiente:

PROJECT_IDEl ID de tu proyecto de Google Cloud.
BIGQUERY_DATASET_ID: El ID del conjunto de datos de BigQuery en el que exportaste de forma masiva el recurso de FHIR
RESOURCE_TABLE: Es el nombre de la tabla correspondiente al recurso de FHIR para el que deseas crear vistas.

Después de crear la vista, puedes continuar transmitiendo cambios al recurso de FHIR y la vista se actualiza según corresponda.

¿Qué sigue?

Si deseas obtener un instructivo sobre un caso de uso para transmitir cambios de recursos de FHIR, consulta Transmite y sincroniza recursos de FHIR con BigQuery.