Se usó la API de Cloud Translation para traducir esta página.

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 mover datos de Spanner al almacenamiento de 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.

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.

Crea un conjunto de datos externo

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

Console

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

Ir a la página de BigQuery
En el panel Explorador, selecciona el proyecto en el que deseas crear el conjunto de datos.
Expande 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 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.
- Deja el resto de la configuración predeterminada como está.
Haz clic en Crear conjunto de datos.

SQL

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

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

Ir a BigQuery
En el editor de consultas, escribe la siguiente oración:
```
CREATE EXTERNAL SCHEMA DATASET_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 de tu conjunto de datos nuevo en BigQuery, por ejemplo, us-central1. Después de crear un conjunto de datos, no puedes cambiar su ubicación.
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

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.

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

Inicia Cloud Shell
Establece el proyecto de 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).

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
```
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.
Revisa y modifica los parámetros de muestra que se aplicarán a tu entorno.
Guarda los cambios.
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

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.
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!”.
Abre tu proyecto de Google Cloud 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.

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.

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.

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.
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. 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.
Puedes crear una vista autorizada que haga referencia al conjunto de datos externo de Spanner. Sin embargo, cuando se consulte esta vista, se enviará a Spanner la EUC de una persona que ejecute una consulta.

¿Qué sigue?

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