Crea conjuntos de datos externos de Spanner

En este documento, se describe cómo crear un conjunto de datos externo (también conocido como conjunto de datos federado) en BigQuery que esté vinculado a una base de datos existente en Spanner.

Un conjunto de datos externo es una conexión entre BigQuery y una fuente de datos externa a nivel del conjunto de datos. Te permite consultar datos transaccionales en bases de datos de Spanner con GoogleSQL sin necesidad de copiar o importar todos los datos de Spanner al almacenamiento de BigQuery. Estos resultados de la consulta se almacenan en BigQuery.

Las tablas de un conjunto de datos externo se propagan automáticamente a partir de las tablas de la fuente de datos externa correspondiente. Puedes consultar estas tablas directamente en BigQuery, pero no puedes realizar modificaciones, adiciones ni eliminaciones. Sin embargo, cualquier actualización que realices en la fuente de datos externa se reflejará automáticamente en BigQuery.

Cuando consultas Spanner, los resultados de las consultas se guardan de forma predeterminada en tablas temporales. De manera opcional, también se pueden guardar como una tabla de BigQuery nueva, unirse a otras tablas o combinarse con tablas existentes mediante DML.

Permisos necesarios

Para obtener el permiso que necesitas para crear un conjunto de datos externo, pídele a tu administrador que te otorgue el rol de IAM Usuario de BigQuery (roles/bigquery.user). Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

Este rol predefinido contiene el permiso bigquery.datasets.create, que se requiere para crear un conjunto de datos externo.

También puedes obtener este permiso con roles personalizados o con otros roles predefinidos.

Para obtener más información sobre los roles y permisos de IAM en BigQuery, consulta Introducción a IAM.

Usa una conexión CLOUD_RESOURCE

De manera opcional, los conjuntos de datos externos de Spanner pueden usar una conexión CLOUD_RESOURCE para interactuar con tu base de datos de Spanner, de modo que puedas proporcionar acceso de usuario a los datos de Spanner a través de BigQuery, sin darles acceso directo a la base de datos de Spanner. Debido a que la cuenta de servicio de la conexión CLOUD_RESOURCE controla la recuperación de datos de Spanner, solo tienes que otorgar a los usuarios acceso al conjunto de datos externo de Spanner.

Antes de crear conjuntos de datos externos de Spanner con una conexión CLOUD_RESOURCE, haz lo siguiente:

Crear una conexión

Puedes crear o usar una conexión CLOUD_RESOURCE existente para conectarte a Spanner. Para crear la conexión de recursos de Cloud, sigue los pasos que se indican en la página Crea una conexión de recursos de Cloud.

Después de crear la conexión, ábrela y, en el panel Información de conexión, copia el ID de la cuenta de servicio. Necesitarás este ID cuando configures los permisos de la conexión. Cuando creas un recurso de conexión, BigQuery crea una cuenta de servicio del sistema única y la asocia con la conexión.

Configura el acceso

Debes otorgar a la conexión nueva acceso de lectura a tu instancia o base de datos de Spanner. Se recomienda usar el rol de IAM predefinido de Lector de base de datos de Cloud Spanner con DataBoost (roles/spanner.databaseReaderWithDataBoost).

Sigue estos pasos para otorgar acceso a los roles a nivel de la base de datos a la cuenta de servicio que copiaste antes desde la conexión:

  1. Ve a la página Instancias de Spanner.

    Ir a la página Instancias

  2. Haz clic en el nombre de la instancia que contiene tu base de datos para ir a la página Detalles de la instancia.

  3. En la pestaña Descripción general, selecciona la casilla de verificación de tu base de datos.
    Aparecerá el panel de información.

  4. Haz clic en Agregar principal.

  5. En el panel Agregar principales, en Principales nuevas, ingresa el ID de la cuenta de servicio que copiaste antes.

  6. En el campo Selecciona un rol, selecciona Lector de bases de datos de Cloud Spanner con el rol de DataBoost.

  7. Haz clic en Guardar.

Crea un conjunto de datos externo

Para crear un conjunto de datos externo, haz lo siguiente:

Console

  1. Abre la página de BigQuery en la consola de Google Cloud .

    Ir a la página de BigQuery

  2. En el panel Explorador, selecciona el proyecto en el que deseas crear el conjunto de datos.

  3. Expande la opción Acciones y haz clic en Crear conjunto de datos.

  4. En la página Crear conjunto de datos, haz lo siguiente:

    • En ID de conjunto de datos, ingresa un nombre único para el conjunto de datos.
    • En Tipo de ubicación, elige una ubicación para el conjunto de datos, como us-central1 o us multirregional. Después de crear un conjunto de datos, la ubicación no se puede cambiar.

    • En External Dataset, haz lo siguiente:

      • Marca la casilla junto a Vínculo a un conjunto de datos externo.
      • En Tipo de conjunto de datos externo, selecciona Spanner.
      • En Fuente externa, ingresa el identificador completo de tu base de datos de Spanner en el siguiente formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por ejemplo: projects/my_project/instances/my_instance/databases/my_database.
      • De manera opcional, en Rol de la base de datos, ingresa el nombre de un rol de base de datos de Spanner. Para obtener más información, lee sobre los roles de la base de datos que se usan para crear conexiones de Spanner.
      • De manera opcional, marca la casilla junto a Usar una conexión de Cloud Resource para crear el conjunto de datos externo con una conexión.

    • Deja el resto de la configuración predeterminada como está.

  5. Haz clic en Crear conjunto de datos.

SQL

Usa la declaración del lenguaje de definición de datos CREATE EXTERNAL SCHEMA (DDL).

  1. En la consola de Google Cloud , ve a la página BigQuery.

    Ir a BigQuery

  2. En el editor de consultas, escribe la siguiente oración:

    CREATE EXTERNAL SCHEMA DATASET_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');
/*
  Alternatively, create with a connection:
*/
CREATE EXTERNAL SCHEMA DATASET_NAME
  WITH CONNECTION PROJECT_ID.LOCATION.CONNECTION_NAME
  OPTIONS (
    external_source = 'SPANNER_EXTERNAL_SOURCE',
    location = 'LOCATION');

    Reemplaza lo siguiente:

    • DATASET_NAME: el nombre de tu conjunto de datos nuevo en BigQuery.
    • SPANNER_EXTERNAL_SOURCE: El nombre completo y calificado de la base de datos de Spanner, con un prefijo que identifica la fuente, en el siguiente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por ejemplo, google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
    • LOCATION: la ubicación del conjunto de datos nuevo en BigQuery, por ejemplo, us-central1. Después de crear un conjunto de datos, no puedes cambiar su ubicación.
    • CONNECTION_NAME: Es el nombre de tu conexión de recursos de Cloud (opcional).

  3. Haz clic en Ejecutar.

Si deseas obtener información sobre cómo ejecutar consultas, visita Ejecuta una consulta interactiva.

bq

En un entorno de línea de comandos, crea un conjunto de datos externo con el comando bq mk:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    DATASET_NAME

Como alternativa, crea una conexión:

bq --location=LOCATION mk --dataset \
    --external_source SPANNER_EXTERNAL_SOURCE \
    --connection_id PROJECT_ID.LOCATION.CONNECTION_NAME \
    DATASET_NAME

Reemplaza lo siguiente:

  • LOCATION: la ubicación del conjunto de datos nuevo en BigQuery, por ejemplo, us-central1. Después de crear un conjunto de datos, no puedes cambiar su ubicación. Puedes configurar un valor de ubicación predeterminado con el archivo .bigqueryrc.
  • SPANNER_EXTERNAL_SOURCE: Es el nombre completo y calificado de la base de datos de Spanner, con un prefijo que identifica la fuente, en el siguiente formato: google-cloudspanner://[DATABASE_ROLE@]/projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por ejemplo, google-cloudspanner://admin@/projects/my_project/instances/my_instance/databases/my_database o google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database.
  • DATASET_NAME: el nombre de tu conjunto de datos nuevo en BigQuery. Para crear un conjunto de datos en un proyecto que no sea el predeterminado, agrega el ID del proyecto al nombre del conjunto de datos en el siguiente formato: PROJECT_ID:DATASET_NAME.
  • CONNECTION_NAME: Es el nombre de tu conexión de recursos de Cloud (opcional).

Terraform

Usa el recurso google_bigquery_dataset.

.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

En el siguiente ejemplo, se crea un conjunto de datos externo de Spanner:

resource "google_bigquery_dataset" "default" {
  dataset_id    = "my_external_dataset"
  friendly_name = "My external dataset"
  description   = "This is a test description."
  location      = "US"
  external_dataset_reference {
    # The full identifier of your Spanner database.
    external_source = "google-cloudspanner:/projects/my_project/instances/my_instance/databases/my_database"
    # Must be empty for a Spanner external dataset.
    connection = ""
  }
}

Para aplicar tu configuración de Terraform en un proyecto de Google Cloud , completa los pasos de las siguientes secciones.

Prepara Cloud Shell

  1. Inicia Cloud Shell

  2. Establece el proyecto Google Cloud predeterminado en el que deseas aplicar tus configuraciones de Terraform.

    Solo necesitas ejecutar este comando una vez por proyecto y puedes ejecutarlo en cualquier directorio.

    export GOOGLE_CLOUD_PROJECT=PROJECT_ID

    Las variables de entorno se anulan si configuras valores explícitos en el archivo de configuración de Terraform.

Prepara el directorio

Cada archivo de configuración de Terraform debe tener su propio directorio (también llamado módulo raíz).

  1. En Cloud Shell, crea un directorio y un archivo nuevo dentro de ese directorio. El nombre del archivo debe tener la extensión .tf, por ejemplo, main.tf. En este instructivo, el archivo se denomina main.tf. 
    mkdir DIRECTORY && cd DIRECTORY && touch main.tf

  2. Si sigues un instructivo, puedes copiar el código de muestra en cada sección o paso.

    Copia el código de muestra en el main.tf recién creado.

    De manera opcional, copia el código de GitHub. Esto se recomienda cuando el fragmento de Terraform es parte de una solución de extremo a extremo.

  3. Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
  4. Guarda los cambios.
  5. Inicializa Terraform. Solo debes hacerlo una vez por directorio. 
    terraform init

    De manera opcional, incluye la opción -upgrade para usar la última versión del proveedor de Google: 

    terraform init -upgrade

Aplica los cambios

  1. Revisa la configuración y verifica que los recursos que creará o actualizará Terraform coincidan con tus expectativas: 
    terraform plan

    Corrige la configuración según sea necesario.

  2. Para aplicar la configuración de Terraform, ejecuta el siguiente comando y, luego, escribe yes cuando se te solicite: 
    terraform apply

    Espera hasta que Terraform muestre el mensaje “¡Aplicación completa!”.

  3. Abre tu Google Cloud proyecto para ver los resultados. En la consola de Google Cloud , navega a tus recursos en la IU para asegurarte de que Terraform los haya creado o actualizado.

API

Llama al método datasets.insert con un recurso de conjunto de datos y un campo externalDatasetReference definidos para tu base de datos de Spanner.

Ten en cuenta que los nombres de las tablas en los conjuntos de datos externos no distinguen mayúsculas de minúsculas.

Cuando creas los conjuntos de datos externos con una conexión CLOUD_RESOURCE, debes tener el permiso bigquery.connections.delegate (disponible a través del rol de administrador de conexiones de BigQuery) en la conexión que usan los conjuntos de datos externos.

Controla el acceso a las tablas

Los conjuntos de datos externos de Spanner admiten credenciales de usuario final (EUC). Esto significa que Spanner controla el acceso a las tablas de Spanner desde conjuntos de datos externos. Los usuarios solo pueden consultar estas tablas si tienen acceso otorgado en Spanner.

Los conjuntos de datos externos de Spanner también admiten la delegación de acceso. La delegación de acceso separa el acceso a las tablas de Spanner de los conjuntos de datos externos y el acceso directo a las tablas de Spanner subyacentes. Se usa una conexión de recursos de Cloud asociada con una cuenta de servicio para conectarse a Spanner. Los usuarios pueden consultar estas tablas de Spanner desde conjuntos de datos externos, incluso si no tienen acceso otorgado en Spanner.

Enumera tablas en un conjunto de datos externo

Para enumerar las tablas que están disponibles para las consultas en tu conjunto de datos externo, consulta Enumera los conjuntos de datos.

Obtén información de tablas

Para obtener información sobre las tablas de tu conjunto de datos externo, como los detalles del esquema, consulta Obtén información de la tabla.

Consulta datos de Spanner

Consultar tablas en conjuntos de datos externos es lo mismo que consultar tablas en cualquier otro conjunto de datos de BigQuery. Sin embargo, no se admiten las operaciones de modificación de datos (DML).

Las consultas a tablas en conjuntos de datos externos de Spanner usan Data Boost de forma predeterminada y no se puede cambiar. Por lo tanto, necesitas permisos adicionales para ejecutar esas consultas.

Crea una vista en un conjunto de datos externo

No puedes crear una vista en un conjunto de datos externo. Sin embargo, puedes crear una vista en un conjunto de datos estándar que se base en una tabla en un conjunto de datos externo. Para obtener más información, consulta Crea vistas.

Borra un conjunto de datos externo

Borrar un conjunto de datos externo es lo mismo que borrar cualquier otro conjunto de datos de BigQuery. Borrar conjuntos de datos externos no afecta las tablas de la base de datos de Spanner. Para obtener más información, consulta Borra conjuntos de datos.

Limitaciones

  • Se aplican las limitaciones de las consultas federadas de BigQuery.
  • En BigQuery, solo se puede acceder a las tablas de un esquema de Spanner predeterminado. No se admiten las tablas de los esquemas de nombres.
  • Las claves primarias y externas definidas en la base de datos de Spanner no son visibles en BigQuery.
  • Si una tabla de la base de datos de Spanner contiene una columna de un tipo que BigQuery no admite, no se podrá acceder a esta columna desde BigQuery.
  • No puedes agregar, borrar ni actualizar datos o metadatos en las tablas de un conjunto de datos externo de Spanner.
  • No puedes crear tablas, vistas ni vistas materializadas nuevas en un conjunto de datos externo de Spanner.
  • Las vistas INFORMATION_SCHEMA no son compatibles.
  • No se admite el almacenamiento en caché de metadatos.
  • La configuración a nivel del conjunto de datos relacionada con los valores predeterminados de creación de tablas no afecta a los conjuntos de datos externos porque no puedes crear tablas de forma manual.
  • Las bases de datos de Spanner que usan el dialecto de PostgreSQL no son compatibles.
  • No se admiten las APIs de Write y Read.
  • No se admiten la seguridad a nivel de la fila, la seguridad a nivel de la columna ni el enmascaramiento de datos.
  • No se admiten las vistas materializadas basadas en tablas de conjuntos de datos externos de Spanner.
  • No se admite la integración con Dataplex Universal Catalog. Por ejemplo, no se admiten los perfiles de datos ni los análisis de la calidad de los datos.
  • No se admiten etiquetas a nivel de la tabla.
  • La finalización automática de SQL no funciona con las tablas externas de Spanner cuando escribes consultas.
  • Analizar con la protección de datos sensibles no es compatible con los conjuntos de datos externos.
  • El uso compartido con BigQuery sharing (anteriormente Analytics Hub) no es compatible con los conjuntos de datos externos.
  • Si el conjunto de datos externo de Spanner usa credenciales de usuario final (EUC), puedes crear una vista autorizada que haga referencia al conjunto de datos externo. Sin embargo, cuando se consulte esta vista, se enviará a Spanner la EUC de una persona que ejecute una consulta.
  • Si el conjunto de datos externo de Spanner usa una conexión de recursos de Cloud para la delegación de acceso, puedes crear una vista o una rutina autorizada que haga referencia al conjunto de datos externo.

¿Qué sigue?