Esta página se ha traducido con Cloud Translation API.

Crear 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 de Spanner.

Un conjunto de datos externo es una conexión entre BigQuery y una fuente de datos externa a nivel de conjunto de datos. Te permite consultar datos transaccionales en bases de datos de Spanner con GoogleSQL sin tener que copiar ni importar todos los datos de Spanner al almacenamiento de BigQuery. Los resultados de estas consultas se almacenan en BigQuery.

Las tablas de un conjunto de datos externo se rellenan automáticamente a partir de las tablas de la fuente de datos externa correspondiente. Puedes consultar estas tablas directamente en BigQuery, pero no puedes modificarlas, añadirles datos ni eliminarlas. Sin embargo, los cambios que hagas en la fuente de datos externa se reflejarán automáticamente en BigQuery.

Cuando consultas Spanner, los resultados de las consultas se guardan de forma predeterminada en tablas temporales. También se pueden guardar como una tabla de BigQuery, combinar con otras tablas o fusionar con tablas ya creadas mediante DML.

Permisos obligatorios

Para obtener el permiso que necesitas para crear un conjunto de datos externo, pide a tu administrador que te asigne el rol de gestión de identidades y accesos Usuario de BigQuery (roles/bigquery.user). Para obtener más información sobre cómo conceder roles, consulta el artículo Gestionar el acceso a proyectos, carpetas y organizaciones.

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

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

Para obtener más información sobre los roles y permisos de gestión de identidades y accesos en BigQuery, consulta la introducción a la gestión de identidades y accesos.

Usar una conexión `CLOUD_RESOURCE`

De forma opcional, los conjuntos de datos externos de Spanner pueden usar una CLOUD_RESOURCE para interactuar con tu base de datos de Spanner, de forma que puedas dar acceso a los datos de Spanner a un usuario a través de BigQuery sin darle acceso directo a la base de datos de Spanner. Como la cuenta de servicio de la conexión CLOUD_RESOURCE se encarga de obtener los datos de Spanner, solo tienes que conceder acceso a los usuarios 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 para conectarte a Spanner. Para crear la conexión de recursos de Cloud, sigue los pasos que se indican en la página Crear una conexión de recursos de Cloud.

Después de crear la conexión, ábrela y, en el panel Información de la 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 a la conexión.

Configurar el acceso

Debe dar a la nueva conexión acceso de lectura a su instancia o base de datos de Spanner. Se recomienda usar el rol de gestión de identidades y accesos predefinido Lector de las bases de datos de Cloud Spanner con Data Boost (roles/spanner.databaseReaderWithDataBoost).

Sigue estos pasos para conceder acceso a los roles a nivel de base de datos a la cuenta de servicio que has copiado anteriormente de la conexión:

Ve a la página Instancias de Spanner.

Ir a la página de instancias
Haga clic en el nombre de la instancia que contiene su base de datos para ir a la página Detalles de la instancia.
En la pestaña Resumen, marca la casilla de tu base de datos.
Aparecerá el panel Información.
Haz clic en Añadir principal.
En el panel Añadir principales, en Principales nuevos, introduce el ID de la cuenta de servicio que has copiado anteriormente.
En el campo Seleccionar un rol, selecciona Lector de bases de datos de Cloud Spanner con rol DataBoost.
Haz clic en Guardar.

Crear un conjunto de datos externo

Para crear un conjunto de datos externo, sigue estos pasos:

Consola

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

Ir a la página de BigQuery
En el panel Explorador, selecciona el proyecto en el que quieras crear el conjunto de datos.
Abre la opción Acciones y haz clic en Crear conjunto de datos.
En la página Crear conjunto de datos, haz lo siguiente:
- En ID del conjunto de datos, introduce 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 multirregión us. Una vez que hayas creado un conjunto de datos, no podrás cambiar su ubicación.
- En External Dataset (Conjunto de datos externo), haga lo siguiente:
  - Marca la casilla situada junto a Enlazar a un conjunto de datos externo.
  - En Tipo de conjunto de datos externo, selecciona Spanner.
  - En External source (Fuente externa), introduce el identificador completo de tu base de datos de Spanner con el siguiente formato: projects/PROJECT_ID/instances/INSTANCE/databases/DATABASE. Por ejemplo: projects/my_project/instances/my_instance/databases/my_database.
  - Opcionalmente, en Rol de base de datos, introduce el nombre de un rol de base de datos de Spanner. Para obtener más información, consulta los roles de base de datos que se usan para crear conexiones de Spanner.
  - Opcionalmente, marca la casilla situada junto a Usar una conexión de recurso de Cloud para crear el conjunto de datos externo con una conexión.
- Deja el resto de los ajustes predeterminados como están.
Haz clic en Crear conjunto de datos.

SQL

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

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

Ir a BigQuery
En el editor de consultas, introduce la siguiente instrucció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');
```
Haz los cambios siguientes:
- DATASET_NAME: el nombre del nuevo conjunto de datos en BigQuery.
- SPANNER_EXTERNAL_SOURCE: el nombre completo y cualificado 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 nuevo conjunto de datos en BigQuery. Por ejemplo, us-central1. Una vez que hayas creado un conjunto de datos, no podrás cambiar su ubicación.
- (Opcional)CONNECTION_NAME: el nombre de tu conexión de recursos de Cloud.
Haz clic en Ejecutar.

Para obtener más información sobre cómo ejecutar consultas, consulta Ejecutar una consulta interactiva.

bq

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

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

También puedes crear una conexión:

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

Haz los cambios siguientes:

LOCATION: la ubicación del nuevo conjunto de datos en BigQuery. Por ejemplo, us-central1. Una vez que hayas creado un conjunto de datos, no podrás cambiar su ubicación. Puedes definir un valor de ubicación predeterminado mediante el archivo .bigqueryrc.
SPANNER_EXTERNAL_SOURCE: el nombre completo y cualificado 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 del nuevo conjunto de datos en BigQuery. Para crear un conjunto de datos en un proyecto que no sea el predeterminado, añade el ID del proyecto al nombre del conjunto de datos con el siguiente formato: PROJECT_ID:DATASET_NAME.
(Opcional)CONNECTION_NAME: el nombre de tu conexión de recursos de Cloud.

Terraform

Usa el recurso google_bigquery_dataset.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta Configurar la autenticación para bibliotecas de 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 la configuración de Terraform en un proyecto, sigue los pasos que se indican en las siguientes secciones. Google Cloud

Preparar Cloud Shell

Abre Cloud Shell.
Define el Google Cloud proyecto Google Cloud predeterminado en el que quieras aplicar tus configuraciones de Terraform.

Solo tiene que ejecutar este comando una vez por proyecto y puede hacerlo en cualquier directorio.
```
export GOOGLE_CLOUD_PROJECT=PROJECT_ID
```
Las variables de entorno se anulan si defines valores explícitos en el archivo de configuración de Terraform.

Preparar el directorio

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

En Cloud Shell, crea un directorio y un archivo nuevo en ese directorio. El nombre del archivo debe tener la extensión .tf. Por ejemplo, main.tf. En este tutorial, nos referiremos al archivo como main.tf.
```
mkdir DIRECTORY && cd DIRECTORY && touch main.tf
```
Si estás siguiendo un tutorial, puedes copiar el código de ejemplo de cada sección o paso.

Copia el código de ejemplo en el archivo main.tf que acabas de crear.

También puedes copiar el código de GitHub. Se recomienda cuando el fragmento de Terraform forma parte de una solución integral.
Revisa y modifica los parámetros de ejemplo para aplicarlos a tu entorno.
Guarda los cambios.
Inicializa Terraform. Solo tienes que hacerlo una vez por directorio.
```
terraform init
```
Si quieres usar la versión más reciente del proveedor de Google, incluye la opción -upgrade:
```
terraform init -upgrade
```

Aplica los cambios

Revisa la configuración y comprueba que los recursos que va a crear o actualizar Terraform se ajustan a tus expectativas:
```
terraform plan
```
Haga las correcciones necesarias en la configuración.
Aplica la configuración de Terraform ejecutando el siguiente comando e introduciendo yes en la petición:
```
terraform apply
```
Espera hasta que Terraform muestre el mensaje "Apply complete!".
Abre tu Google Cloud proyecto para ver los resultados. En la Google Cloud consola, ve a tus recursos en la interfaz de usuario para asegurarte de que Terraform los ha creado o actualizado.

API

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

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

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

Controlar 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 concedido en Spanner.

Los conjuntos de datos externos de Spanner también admiten la delegación de acceso. La delegación de acceso desacopla el acceso a las tablas de Spanner de los conjuntos de datos externos y del acceso directo a las tablas de Spanner subyacentes. Se usa una conexión de recursos de Cloud asociada a una cuenta de servicio para conectarse a Spanner. Los usuarios pueden consultar estas tablas de Spanner desde conjuntos de datos externos aunque no tengan acceso concedido en Spanner.

Mostrar las tablas de un conjunto de datos externo

Para ver una lista de las tablas que se pueden consultar en tu conjunto de datos externo, consulta Listar conjuntos de datos.

Obtener información de una tabla

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

Consultar datos de Spanner

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

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

Crear 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 de un conjunto de datos externo. Para obtener más información, consulta el artículo Crear vistas.

Eliminar un conjunto de datos externo

Eliminar un conjunto de datos externo es igual que eliminar cualquier otro conjunto de datos de BigQuery. Eliminar conjuntos de datos externos no afecta a las tablas de la base de datos de Spanner. Para obtener más información, consulta Eliminar conjuntos de datos.

Limitaciones

Se aplican las limitaciones de las consultas federadas de BigQuery.
Solo se puede acceder a las tablas de un esquema predeterminado de Spanner en BigQuery. No se admiten tablas de esquemas con nombre.
Las claves principales y externas definidas en la base de datos de Spanner no se ven en BigQuery.
Si una tabla de una base de datos de Spanner contiene una columna de un tipo que no es compatible con BigQuery, no se podrá acceder a ella en BigQuery.
No puedes añadir, eliminar ni actualizar datos ni metadatos en las tablas de un conjunto de datos externo de Spanner.
No puedes crear tablas, vistas ni vistas materializadas en un conjunto de datos externo de Spanner.
Las INFORMATION_SCHEMA visualizaciones no se admiten.
No se admite el almacenamiento en caché de metadatos.
Los ajustes a nivel de conjunto de datos relacionados con los valores predeterminados de creación de tablas no afectan a los conjuntos de datos externos porque no se pueden crear tablas manualmente.
No se admiten las bases de datos de Spanner que usan el dialecto PostgreSQL.
No se admiten las APIs de lectura y escritura.
No se admiten la seguridad a nivel de fila, la seguridad a nivel de columna ni el enmascaramiento de datos.
No se admiten 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 calidad de los datos.
No se admiten etiquetas a nivel de tabla.
La función de autocompletado de SQL no funciona con tablas externas de Spanner al escribir consultas.
La opción Analizar con Protección de Datos Sensibles no está disponible para conjuntos de datos externos.
No se puede compartir con la función de compartir de BigQuery (antes Analytics Hub) conjuntos de datos externos.
Si el conjunto de datos externo de Spanner usa credenciales de usuario final (EUC), puede crear una vista autorizada que haga referencia al conjunto de datos externo. Sin embargo, cuando se consulta esta vista, la información de usuario final de la persona que ejecuta la consulta se envía a Spanner.
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 autorizada o una rutina autorizada que haga referencia al conjunto de datos externo.

Siguientes pasos

Consulta más información sobre las consultas federadas de Spanner.