Crea tablas de BigLake de Amazon S3

En este documento, se describe cómo crear una tabla de BigLake de Amazon Simple Storage Service (Amazon S3). Una tabla de BigLake te permite usar la delegación de acceso para consultar datos en Amazon S3. La delegación de acceso separa el acceso a la tabla de BigLake del acceso al almacén de datos subyacente.

Para obtener información sobre cómo fluyen los datos entre BigQuery y Amazon S3, consulta Flujo de datos cuando se consultan datos.

Antes de comenzar

Asegúrate de tener una conexión para acceder a los datos de Amazon S3.

Roles obligatorios

Para obtener los permisos que necesitas para crear una tabla externa, pídele a tu administrador que te otorgue el rol de IAM Administrador de BigQuery (roles/bigquery.admin) en tu conjunto de datos. Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso.

Este rol predefinido contiene los permisos necesarios para crear una tabla externa. Para ver los permisos exactos que son necesarios, expande la sección Permisos requeridos:

Permisos necesarios

Se requieren los siguientes permisos para crear una tabla externa:

• bigquery.tables.create
• bigquery.connections.delegate

También puedes obtener estos permisos con roles personalizados o con otros roles predefinidos.

Crea un conjunto de datos

Antes de crear una tabla externa, debes crear un conjunto de datos en la región compatible. Selecciona una de las opciones siguientes:

Consola

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, selecciona el proyecto en el que deseas crear el conjunto de datos.
3. Expande la opción Ver acciones y haz clic en Crear conjunto de datos.
4. En la página Crear conjuntos de datos, especifica los siguientes detalles:
1. En ID de conjunto de datos, ingresa un nombre único para el conjunto de datos.
2. En Ubicación de los datos, elige una región compatible.
3. Opcional: para borrar tablas automáticamente, selecciona la casilla de verificación Habilitar vencimiento de la tabla y establece la Antigüedad máxima de la tabla predeterminada en días. Los datos en Amazon S3 no se borran cuando vence la tabla.
4. Si deseas usar la intercalación predeterminada, expande la sección Opciones avanzadas y selecciona la opción Habilitar intercalación predeterminada.
5. Haz clic en Crear conjunto de datos.

SQL

Usa la declaración DDL CREATE SCHEMA. En el siguiente ejemplo, se crea un conjunto de datos en la región aws-us-east-1:

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

   CREATE SCHEMA mydataset
   OPTIONS (
     location = 'aws-us-east-1');

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 con el comando bq mk:

bq --location=LOCATION mk \
    --dataset \
PROJECT_ID:DATASET_NAME

El parámetro --project_id anula el proyecto predeterminado.

Reemplaza lo siguiente:

• LOCATION: Es la ubicación de tu conjunto de datos.

  Para obtener información sobre las regiones compatibles, consulta Ubicaciones. Después de crear un conjunto de datos, no puedes cambiar su ubicación. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.

• PROJECT_ID: Es el ID de tu proyecto.

• DATASET_NAME: Es el nombre de la imagen que deseas crear.

  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.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Dataset;
import com.google.cloud.bigquery.DatasetInfo;

// Sample to create a aws dataset
public class CreateDatasetAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    // Note: As of now location only supports aws-us-east-1
    String location = "aws-us-east-1";
    createDatasetAws(projectId, datasetName, location);
  }

  public static void createDatasetAws(String projectId, String datasetName, String location) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      DatasetInfo datasetInfo =
          DatasetInfo.newBuilder(projectId, datasetName).setLocation(location).build();

      Dataset dataset = bigquery.create(datasetInfo);
      System.out.println(
          "Aws dataset created successfully :" + dataset.getDatasetId().getDataset());
    } catch (BigQueryException e) {
      System.out.println("Aws dataset was not created. \n" + e.toString());
    }
  }
}

Crea tablas de BigLake en datos sin particiones

Selecciona una de las opciones siguientes:

Console

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y, luego, elige un conjunto de datos.

3. En la sección Información del conjunto de datos, haz clic en Crear tabla.

4. En la sección Fuente de la página Crear tabla, haz lo siguiente:

   1. En Crear tabla desde, selecciona Amazon S3.
   2. En Selecciona la ruta de acceso de S3, ingresa un URI que apunte a los datos de Amazon S3 en el formato s3://BUCKET_NAME/PATH. Reemplaza BUCKET_NAME por el nombre del bucket de Amazon S3. La región del bucket debe ser la misma que la región del conjunto de datos. Reemplaza PATH por la ruta de acceso en la que deseas escribir el archivo exportado; puede contener un comodín *.
   3. En Formato del archivo, selecciona el formato de datos en Amazon S3. Los formatos admitidos son los siguientes:AVRO, PARQUET, ORC, CSV y JSONL (JSON delimitado por saltos de línea).

5. En la sección Destino, especifica los siguientes detalles:

   1. En Conjunto de datos, elige el conjunto de datos apropiado.
   2. En el campo Tabla, ingresa el nombre de la tabla.
   3. Verifica que el Table type (Tipo de tabla) esté configurado como Tabla externa.
   4. En ID de conexión, selecciona el ID de conexión que corresponda en el menú desplegable. Para obtener más información sobre las conexiones, consulta Conéctate a Amazon S3.

6. En la sección Esquema, puedes habilitar la detección automática de esquemas o especificar un esquema de forma manual si tienes un archivo de origen. Si no tienes un archivo de origen, debes especificar un esquema de forma manual.

   • Para habilitar la detección automática de esquemas, elige la opción Detección automática.

   • Para especificar un esquema de forma manual, deja sin marcar la opción Detección automática. Habilita Editar como texto e ingresa el esquema de la tabla como un array JSON.

7. Haga clic en Crear tabla.

SQL

Para crear una tabla de BigLake, usa la sentencia CREATE EXTERNAL TABLE con la cláusula WITH CONNECTION:

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

   Ir a BigQuery

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

   CREATE EXTERNAL TABLE DATASET_NAME.TABLE_NAME
     WITH CONNECTION `AWS_LOCATION.CONNECTION_NAME`
     OPTIONS (
       format = "DATA_FORMAT",
       uris = ["S3_URI"],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE');

   Reemplaza lo siguiente:

   • DATASET_NAME: Es el nombre del conjunto de datos que creaste.
   • TABLE_NAME: Es el nombre que deseas asignar a esta tabla.
   • AWS_LOCATION: Es una ubicación de AWS en Google Cloud (por ejemplo, “aws-us-east-1”)
   • CONNECTION_NAME: Es el nombre de la conexión que creaste.
   • DATA_FORMAT: Es cualquiera de los formatos federados de BigQuery compatibles, como AVRO, CSV o DELTA_LAKE (vista previa).
   • S3_URI: es un URI que apunta a los datos de Amazon S3 (por ejemplo, s3://bucket/path)
   • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de BigLake usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

     Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Amazon S3.

   • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

     Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

     Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

3. Haz clic en Ejecutar.

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

Ejemplo:

CREATE EXTERNAL TABLE awsdataset.awstable
  WITH CONNECTION `aws-us-east-1.s3-read-connection`
  OPTIONS (
    format="CSV",
    uris=["s3://s3-bucket/path/file.csv"],
    max_staleness = INTERVAL 1 DAY,
    metadata_cache_mode = 'AUTOMATIC'
);

bq

Crea un archivo de definición de tabla

bq mkdef  \
--source_format=DATA_FORMAT \
--connection_id=AWS_LOCATION.CONNECTION_NAME \
--metadata_cache_mode=CACHE_MODE \
S3_URI > table_def

Reemplaza lo siguiente:

• DATA_FORMAT: Es cualquiera de los formatos federados de BigQuery compatibles (como AVRO o CSV).
• S3_URI: es un URI que apunta a los datos de Amazon S3 (por ejemplo, s3://bucket/path).
• AWS_LOCATION: Es una ubicación de AWS en Google Cloud (por ejemplo, aws-us-east-1).

• CONNECTION_NAME: Es el nombre de la conexión que creaste.

• CACHE_MODE: Especifica si la caché de metadatos se actualiza de forma automática o manual. Solo debes incluir esta marca si también planeas usar la marca --max_staleness en el comando bq mk posterior para habilitar el almacenamiento en caché de metadatos. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

  Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché. Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

Nota: Para anular el proyecto predeterminado, usa el parámetro --project_id=PROJECT_ID. Reemplaza PROJECT_ID por el ID del proyecto de Google Cloud.

A continuación, crea la tabla de BigLake:

bq mk --max_staleness=STALENESS_INTERVAL --external_table_definition=table_def DATASET_NAME.TABLE_NAME

Reemplaza lo siguiente:

• STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de BigLake y los metadatos almacenados en caché deben usarse para que la operación los use en caché. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

  Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos que eso, la operación recupera metadatos de Amazon S3 en su lugar.

• DATASET_NAME: Es el nombre del conjunto de datos que creaste.

• TABLE_NAME: Es el nombre que deseas asignar a esta tabla.

Por ejemplo, con el siguiente comando, se crea una tabla nueva de BigLake, awsdataset.awstable, que puede consultar los datos de Amazon S3 que se almacenan en la ruta de acceso s3://s3-bucket/path/file.csv y tiene una conexión de lectura en la ubicación aws-us-east-1:

bq mkdef  \
--autodetect \
--source_format=CSV \
--connection_id=aws-us-east-1.s3-read-connection \
--metadata_cache_mode=AUTOMATIC \
s3://s3-bucket/path/file.csv > table_def

bq mk --max_staleness=INTERVAL "1" HOUR \
--external_table_definition=table_def awsdataset.awstable

API

Llama al método tables.insert de la API y crea un ExternalDataConfiguration en el recurso Table que pasas.

Especifica la propiedad schema o establece la propiedad autodetect en true a fin de habilitar la detección automática de esquemas para las fuentes de datos compatibles.

Especifica la propiedad connectionId a fin de identificar la conexión que se usará para conectarse a Amazon S3.

Java

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.ExternalTableDefinition;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

// Sample to create an external aws table
public class CreateExternalTableAws {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "MY_PROJECT_ID";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String connectionId = "MY_CONNECTION_ID";
    String sourceUri = "s3://your-bucket-name/";
    CsvOptions options = CsvOptions.newBuilder().setSkipLeadingRows(1).build();
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    ExternalTableDefinition externalTableDefinition =
        ExternalTableDefinition.newBuilder(sourceUri, options)
            .setConnectionId(connectionId)
            .setSchema(schema)
            .build();
    createExternalTableAws(projectId, datasetName, tableName, externalTableDefinition);
  }

  public static void createExternalTableAws(
      String projectId,
      String datasetName,
      String tableName,
      ExternalTableDefinition externalTableDefinition) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      TableId tableId = TableId.of(projectId, datasetName, tableName);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, externalTableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Aws external table created successfully");

      // Clean up
      bigquery.delete(TableId.of(projectId, datasetName, tableName));
    } catch (BigQueryException e) {
      System.out.println("Aws external was not created." + e.toString());
    }
  }
}

Crea tablas de BigLake en datos particionados

Puedes crear una tabla de BigLake para datos particionados en Hive en Amazon S3. Después de crear una tabla particionada de forma externa, no podrás cambiar la clave de partición. Debes volver a crear la tabla para cambiar la clave de partición.

Para crear una tabla de BigLake basada en datos particionados de Hive, selecciona una de las siguientes opciones:

Consola

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.

3. Haz clic en Ver acciones y, luego, en Crear tabla. Se abrirá el panel Crear tabla.

4. En la sección Fuente, especifica los siguientes detalles:

   1. En Crear tabla desde, selecciona Amazon S3.

   2. Proporciona la ruta de acceso a la carpeta mediante comodines. Por ejemplo, s3://mybucket/*.

      La carpeta debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que deseas crear, agregar o reemplazar.

   3. En la lista Formato de archivo, selecciona el tipo de archivo.

   4. Selecciona la casilla de verificación Partición de datos de origen y, luego, especifica los siguientes detalles:

      1. En Seleccionar prefijo de URI de origen, ingresa el prefijo de URI. Por ejemplo, s3://mybucket/my_files
      2. Opcional: A fin de solicitar un filtro de partición en todas las consultas de esta tabla, selecciona la casilla de verificación Exigir filtro de partición. Exigir un filtro de partición puede reducir los costos y mejorar el rendimiento. Para obtener más información, consulta Filtros de predicado obligatorios en claves de partición de consultas.

      3. En la sección Modo de inferencia de la partición, selecciona una de las siguientes opciones:

         • Inferir tipos automáticamente: configura el modo de detección de esquemas de partición como AUTO.
         • Todas las columnas son strings: configura el modo de detección de esquemas de partición como STRINGS.
         • Proporcionar uno propio: configura el modo de detección de esquemas de partición como CUSTOM e ingresa de forma manual la información del esquema para las claves de partición. Para obtener más información, consulta Proporciona un esquema de clave de partición personalizado.

5. En la sección Destino, especifica los siguientes detalles:

   1. En Proyecto, selecciona el proyecto en el que deseas crear la tabla.
   2. En Conjunto de datos, selecciona el conjunto de datos en el que deseas crear la tabla.
   3. En Tabla, ingresa el nombre de la tabla que deseas crear
   4. En Tipo de tabla, verifica que la opción Tabla externa esté seleccionada.
   5. En ID de conexión, selecciona la conexión que creaste antes.

6. En la sección Esquema, puedes habilitar la detección automática de esquemas o especificar un esquema de forma manual si tienes un archivo de origen. Si no tienes un archivo de origen, debes especificar un esquema de forma manual.

   • Para habilitar la detección automática de esquemas, elige la opción Detección automática.

   • Para especificar un esquema de forma manual, deja sin marcar la opción Detección automática. Habilita Editar como texto e ingresa el esquema de la tabla como un array JSON.

7. Para omitir las filas con valores de columna adicionales que no coinciden con el esquema, expande la sección Opciones avanzadas y selecciona Valores desconocidos.

8. Haga clic en Crear tabla.

SQL

Usa la declaración DDL CREATE EXTERNAL TABLE:

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

   Ir a BigQuery

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

   CREATE EXTERNAL TABLE `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
   WITH PARTITION COLUMNS
   (
     PARTITION_COLUMN PARTITION_COLUMN_TYPE,
   )
   WITH CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
   OPTIONS (
     hive_partition_uri_prefix = "HIVE_PARTITION_URI_PREFIX",
     uris=['FILE_PATH'],
     format ="TABLE_FORMAT"
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE'
   );

   Reemplaza lo siguiente:

   • PROJECT_ID: el nombre del proyecto en el que deseas crear la tabla, por ejemplo, myproject
   • DATASET: el nombre del conjunto de datos de BigQuery en el que deseas crear una tabla, por ejemplo, mydataset
   • EXTERNAL_TABLE_NAME: el nombre de la tabla que deseas crear, por ejemplo, mytable
   • PARTITION_COLUMN: el nombre de la columna de partición
   • PARTITION_COLUMN_TYPE: el tipo de columna de partición
   • REGION: la región que contiene la conexión, por ejemplo, us
   • CONNECTION_ID: el nombre de la conexión, por ejemplo, myconnection
   • HIVE_PARTITION_URI_PREFIX: prefijo de URI de partición de Hive, por ejemplo, s3://mybucket/
   • FILE_PATH: ruta de acceso a la fuente de datos para la tabla externa que deseas crear, por ejemplo, s3://mybucket/*.parquet
   • TABLE_FORMAT: el formato de la tabla que deseas crear, por ejemplo, PARQUET
   • STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de BigLake usan los metadatos almacenados en caché, y qué tan actuales deben ser los metadatos para que la operación los use. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

     Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos, la operación recupera metadatos de Amazon S3.

   • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

     Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

     Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché.

     Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

3. Haz clic en Ejecutar.

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

Ejemplos

En el siguiente ejemplo, se crea una tabla de BigLake a partir de datos particionados en Amazon S3. El esquema se detecta de forma automática.

CREATE EXTERNAL TABLE `my_dataset.my_table`
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "s3://mybucket/products",
  uris = ['s3://mybucket/products/*']
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

bq

Primero, usa el comando bq mkdef para crear un archivo de definición de tablas:

bq mkdef \
--source_format=SOURCE_FORMAT \
--connection_id=REGION.CONNECTION_ID \
--hive_partitioning_mode=PARTITIONING_MODE \
--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 URIS > DEFINITION_FILE

Reemplaza lo siguiente:

• SOURCE_FORMAT: El formato de la fuente de datos externos. Por ejemplo, CSV
• REGION: la región que contiene la conexión, por ejemplo, us.
• CONNECTION_ID: el nombre de la conexión, por ejemplo, myconnection
• PARTITIONING_MODE: El modo de partición de subárbol. Usa uno de los siguientes valores:
  • AUTO: Detecta de forma automática los nombres y tipos de claves.
  • STRINGS: Convierte de forma de automática los nombres de las claves en strings.
  • CUSTOM: Codifica el esquema de clave en el prefijo de URI de origen.
• URI_SHARED_PREFIX: Es el prefijo del URI de origen.

• BOOLEAN especifica si se requiere un filtro de predicado en el momento de la consulta. Esta marca es opcional. El valor predeterminado es false.

• CACHE_MODE: Especifica si la caché de metadatos se actualiza de forma automática o manual. Solo debes incluir esta marca si también planeas usar la marca --max_staleness en el comando bq mk posterior para habilitar el almacenamiento en caché de metadatos. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Configúralo como AUTOMATIC para que la caché de metadatos se actualice a un intervalo definido por el sistema, por lo general, entre 30 y 60 minutos.

  Configúralo como MANUAL si deseas actualizar la caché de metadatos en un programa que determines. En este caso, puedes llamar al procedimiento del sistema BQ.REFRESH_EXTERNAL_METADATA_CACHE para actualizar la caché. Debes configurar CACHE_MODE si STALENESS_INTERVAL está configurado en un valor mayor que 0.

• URIS: La ruta a la carpeta de Amazon S3, en formato comodín.

• DEFINITION_FILE: Es la ruta de acceso al archivo de definición de tabla en tu máquina local.

Si PARTITIONING_MODE es CUSTOM, incluye el esquema de la clave de partición en el prefijo de URI de origen mediante el siguiente formato:

--hive_partitioning_source_uri_prefix=URI_SHARED_PREFIX/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Después de crear el archivo de definición de tablas, usa el comando bq mk para crear la tabla de BigLake:

bq mk --max_staleness=STALENESS_INTERVAL \
--external_table_definition=DEFINITION_FILE \
DATASET_NAME.TABLE_NAME \
SCHEMA

Reemplaza lo siguiente:

• STALENESS_INTERVAL: especifica si las operaciones que se usan en la tabla de BigLake y los metadatos almacenados en caché deben usarse para que la operación los use en caché. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento de metadatos en caché para mejorar el rendimiento.

  Para inhabilitar el almacenamiento en caché de metadatos, especifica 0. Esta es la opción predeterminada.

  Para habilitar el almacenamiento en caché de metadatos, especifica un valor de literal de intervalo entre 30 minutos y 7 días. Por ejemplo, especifica INTERVAL 4 HOUR para un intervalo de inactividad de 4 horas. Con este valor, las operaciones en la tabla usan metadatos almacenados en caché si se actualizaron en las últimas 4 horas. Si los metadatos almacenados en caché son más antiguos que eso, la operación recupera metadatos de Amazon S3 en su lugar.

• DEFINITION_FILE es la ruta de acceso al archivo de definición de tablas.

• DATASET_NAME: es el nombre del conjunto de datos que contiene la tabla.

• TABLE_NAME: es el nombre de la tabla que crearás.

• SCHEMA: especifica una ruta a un archivo de esquema JSON o especifica el esquema en el formato field:data_type,field:data_type,.... Para usar la detección automática de esquemas, omite este argumento.

Ejemplos

En el siguiente ejemplo, se usa el modo de partición AUTO de Hive para datos de Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=AUTO \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

En el siguiente ejemplo, se usa el modo de partición STRING de Hive para datos de Amazon S3:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=s3://mybucket/myTable \
  --metadata_cache_mode=AUTOMATIC \
  s3://mybucket/myTable/* > mytable_def

bq mk --max_staleness=INTERVAL "1" HOUR \
  --external_table_definition=mytable_def \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

API

Para configurar la partición de Hive mediante la API de BigQuery, incluye el objeto hivePartitioningOptions en el objeto ExternalDataConfiguration cuando crees el Archivo de definición de tabla. Si deseas crear una tabla de BigLake, también debes especificar un valor para el campo connectionId.

Si configuras el campo hivePartitioningOptions.mode como CUSTOM, debes codificar el esquema de clave de partición en el campo hivePartitioningOptions.sourceUriPrefix de la siguiente manera: s3://BUCKET/PATH_TO_TABLE/{KEY1:TYPE1}/{KEY2:TYPE2}/...

Para implementar el uso de un filtro de predicado en el momento de la consulta, establece el campo hivePartitioningOptions.requirePartitionFilter en true.

Tablas de Delta Lake

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Para inscribirte en esta vista previa, completa el siguiente formulario.

Para solicitar comentarios o asistencia sobre esta función, envía un correo electrónico a [e-mail].

Delta Lake es un formato de tabla de código abierto que admite tablas de datos a escala de petabytes. Las tablas de Delta Lake se pueden consultar como tablas temporales y permanentes, y se admiten como tabla de BigLake.

Sincronización de esquemas

Delta Lake mantiene un esquema canónico como parte de sus metadatos. No puedes actualizar un esquema con un archivo de metadatos JSON. Para actualizar el esquema, haz lo siguiente:

1. Usa el comando bq update con la marca --autodetect_schema:

   bq update --autodetect_schema
   PROJECT_ID:DATASET.TABLE
   

   Reemplaza lo siguiente:

   • PROJECT_ID: el ID del proyecto que contiene la tabla que deseas actualizar

   • DATASET: el conjunto de datos que contiene la tabla que deseas actualizar

   • TABLE: la tabla que deseas actualizar

Conversión de tipos

BigQuery convierte los tipos de datos de Delta Lake en los siguientes tipos de datos de BigQuery:

Tipo de Delta Lake	Tipo de BigQuery
boolean	BOOL
byte	INT64
int	INT64
long	INT64
float	FLOAT64
double	FLOAT64
Decimal(P/S)	NUMERIC o BIG_NUMERIC, según la precisión
date	DATE
time	TIME
timestamp (not partition column)	TIMESTAMP
timestamp (partition column)	DATETIME
string	STRING
binary	BYTES
array<Type>	ARRAY<Type>
struct	STRUCT
map<KeyType, ValueType>	ARRAY<Struct<key KeyType, value ValueType>>

Limitaciones

Las siguientes limitaciones se aplican a las tablas de Delta Lake:

• Las limitaciones de las tablas externas se aplican a las tablas del Delta Lake.

• Las tablas de Delta Lake solo son compatibles con BigQuery Omni y tienen las limitaciones asociadas.

• No puedes actualizar una tabla con un archivo de metadatos JSON nuevo. Debes usar una operación de actualización de tabla de esquema de detección automática. Consulta Sincronización de esquemas para obtener más información.

• Las características de seguridad de BigLake solo protegen las tablas del Delta Lake cuando se accede a ellas a través de los servicios de BigQuery.

Crea una tabla de Delta Lake

En el siguiente ejemplo, se crea una tabla externa mediante la declaración CREATE EXTERNAL TABLE con el formato de Delta Lake:

CREATE [OR REPLACE] EXTERNAL TABLE table_name
WITH CONNECTION connection_name
OPTIONS (
         format = 'DELTA_LAKE',
         uris = ["parent_directory"]
       );

Reemplaza lo siguiente:

• table_name: el nombre de la tabla.

• connection_name: Es el nombre de la conexión. La conexión debe identificar una fuente de Amazon S3 o una fuente de Blob Storage.

• parent_directory: Es el URI del directorio principal.

Transferencia entre nubes con Delta Lake

En el siguiente ejemplo, se usa la declaración LOAD DATA para cargar datos en la tabla adecuada:

LOAD DATA [INTO | OVERWRITE] table_name
FROM FILES (
        format = 'DELTA_LAKE',
        uris = ["parent_directory"]
)
WITH CONNECTION connection_name;

Para obtener más ejemplos de transferencias de datos entre nubes, consulta Carga datos con operaciones entre nubes.

Consulta tablas de BigLake

Para obtener más información, visita Consulta datos de Amazon S3.

Visualiza los metadatos de recursos

Vista previa

Esta función está sujeta a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones Específicas del Servicio. Las funciones de fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Puedes ver los metadatos de los recursos con las vistas INFORMATION_SCHEMA. Cuando consultes las vistas JOBS_BY_* ,JOBS_TIMELINE_BY_* yRESERVATION*, debes especificar la ubicación de procesamiento de la consulta que se encuentra junto a la región de la tabla. Para obtener información sobre las ubicaciones de BigQuery Omni, consulta Ubicaciones. Para todas las demás tablas del sistema, la especificación de la ubicación del trabajo de consulta es opcional.

Para obtener más información sobre las tablas del sistema compatibles con BigQuery Omni, consulta Limitaciones.

Para consultar las tablas del sistema JOBS_* y RESERVATION*, selecciona uno de los siguientes métodos para especificar la ubicación de procesamiento:

Consola

1. Ve a la página de BigQuery.

   Ir a BigQuery

2. Si la pestaña Editor no está visible, haga clic en Redactar consulta nueva.

3. Haz clic en Más > Configuración de consulta. Se abrirá el cuadro de diálogo Configuración de consulta.

4. En el cuadro de diálogo Configuración de consulta, en Configuración adicional > Ubicación de los datos, selecciona la región BigQuery que se encuentra ubicada en la región de BigQuery Omni. Por ejemplo, si tu región de BigQuery Omni es aws-us-east-1, especifica us-east4.

5. Selecciona los campos restantes y haz clic en Guardar.

bq

Usa la marca --location para configurar la ubicación de procesamiento del trabajo en la región de BigQuery que se encuentra ubicada en la región de BigQuery Omni. Por ejemplo, si tu región de BigQuery Omni es aws-us-east-1, especifica us-east4.

Ejemplo

bq query --use_legacy_sql=false --location=us-east4 \
"SELECT * FROM region-aws-us-east-1.INFORMATION_SCHEMA.JOBS limit 10;"

bq query --use_legacy_sql=false --location=asia-northeast3 \
"SELECT * FROM region-aws-ap-northeast-2.INFORMATION_SCHEMA.JOBS limit 10;"

API

Si ejecutas trabajos de manera programática, configura el argumento de ubicación como la región de BigQuery que encuentra ubicada en la región de BigQuery Omni. Por ejemplo, si tu región de BigQuery Omni es aws-us-east-1, especifica us-east4.

En el siguiente ejemplo, se enumeran los trabajos de actualización de metadatos:

SELECT
 *
FROM
 `region-aws-us-east-1.INFORMATION_SCHEMA.JOBS_BY_PROJECT`
WHERE
 job_id LIKE '%metadata_cache_refresh%'
 AND creation_time > TIMESTAMP_SUB(CURRENT_TIMESTAMP(), INTERVAL 6 HOUR)
ORDER BY start_time desc
LIMIT 10;

Controles del servicio de VPC

Puedes usar los perímetros de los Controles del servicio de VPC para restringir el acceso de BigQuery Omni a un servicio de nube externo como una capa adicional de defensa. Por ejemplo, los perímetros de los Controles del servicio de VPC pueden limitar las exportaciones de tus tablas de BigQuery Omni a un bucket específico de Amazon S3 o a un contenedor de almacenamiento de BLOB.

Consulta Descripción general de los Controles del servicio de VPC para obtener más información sobre estos.

Permiso necesario

Asegúrate de tener los permisos necesarios para configurar los perímetros de servicio. Si deseas ver una lista de las funciones de IAM necesarias para configurar los Controles del servicio de VPC, consulta Control de acceso con IAM en la documentación de los Controles del servicio de VPC.

Configura los Controles del servicio de VPC mediante la consola de Google Cloud

1. En el menú de navegación de la consola de Google Cloud, haz clic en Seguridad y, luego, en Controles del servicio de VPC.

   Ir a los Controles del servicio de VPC

2. A fin de configurar los Controles del servicio de VPC para BigQuery Omni, sigue los pasos de la guía Crea un perímetro de servicio y cuando estés en las reglas de salida, sigue estos pasos:

   1. En el panel Reglas de salida, haz clic en Agregar regla.

   2. En la sección Desde los atributos del cliente de la API, selecciona una opción de la lista Identidad.

   3. Selecciona A atributos de recursos externos.

   4. Para agregar un recurso externo, haz clic en Agregar recursos externos.

   5. En el cuadro de diálogo Agregar recurso externo, en Nombre del recurso externo, ingresa un nombre de recurso válido. Por ejemplo:

      • Para Amazon Simple Storage Service (Amazon S3): s3://BUCKET_NAME

        Reemplaza BUCKET_NAME por el nombre de tu bucket de Amazon S3.

      • Para Azure Blob Storage: azure://myaccount.blob.core.windows.net/CONTAINER_NAME

        Reemplaza CONTAINER NAME por el nombre del contenedor de Blob Storage.

      Para obtener una lista de los atributos de reglas de salida, consulta Referencia de reglas de salida.

   6. Selecciona los métodos que desees permitir en tus recursos externos:

      1. Si deseas permitir todos los métodos, selecciona Todos los métodos en la lista de Métodos.
      2. Si deseas permitir métodos específicos, selecciona Método seleccionado, haz clic en Seleccionar métodos y, luego, selecciona los métodos que deseas permitir en tus recursos externos.

   7. Haz clic en Crear perímetro.

Configura los Controles del servicio de VPC mediante la CLI de gcloud

Para configurar los Controles del servicio de VPC mediante la CLI de gcloud, sigue estos pasos:

1. Configura la política de acceso predeterminada.
2. Crea el archivo de entrada de la política de salida.
3. Agrega la política de salida.

Configura la política de acceso predeterminada

Una política de acceso es un contenedor en toda la organización para los niveles de acceso y los perímetros de servicio. Para obtener información sobre cómo configurar una política de acceso predeterminada o cómo obtener un nombre de política de acceso, consulta Administra una política de acceso.

Crea el archivo de entrada de la política de salida

Un bloque de reglas de salida define el acceso permitido desde un perímetro a recursos fuera de ese perímetro. En el caso de los recursos externos, la propiedad externalResources define las rutas de acceso a los recursos externos desde el perímetro de los Controles del servicio de VPC.

Las reglas de salida se pueden configurar mediante un archivo JSON o YAML. En el siguiente ejemplo, se usa el formato .yaml:

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
      *OR*
      - permission: "externalResource.read"
    externalResources:
      - EXTERNAL_RESOURCE_PATH
  egressFrom:
    identityType: IDENTITY_TYPE
    *OR*
    identities:
    - serviceAccount:SERVICE_ACCOUNT

• egressTo: Enumera las operaciones de servicio permitidas en los recursos de Google Cloud en proyectos especificados fuera del perímetro.

• operations: Marca el comienzo de la lista de servicios y las acciones o los métodos accesibles a los que el cliente satisface las condiciones del bloque from a los que puede acceder.

• serviceName: configura bigquery.googleapis.com para BigQuery Omni.

• methodSelectors: enumera los métodos a los que un cliente que cumple con las condiciones from puede acceder. Para conocer los métodos y permisos restringidos para los servicios, consulta las restricciones de los métodos de servicio compatibles.

• method: Es un método de servicio válido o \"*\" para permitir todos los métodos serviceName.

• permission: Es un permiso de servicio válido, como \"*\", externalResource.read o externalResource.write. El acceso a los recursos fuera del perímetro se permite para las operaciones que requieren este permiso.

• externalResources: Enumera los recursos externos a los que pueden acceder los clientes dentro de un perímetro. Reemplaza EXTERNAL_RESOURCE_PATH por un bucket de Amazon S3 válido, como s3://bucket_name, o por una ruta del contenedor de Blob Storage, como azure://myaccount.blob.core.windows.net/container_name.

• egressFrom: Enumera las operaciones de servicio permitidas en los recursos de Google Cloud en proyectos especificados dentro del perímetro.

• identityType o identities: Define los tipos de identidad que pueden acceder a los recursos especificados fuera del perímetro. Reemplaza IDENTITY_TYPE por uno de los siguientes valores válidos:

  • ANY_IDENTITY: para permitir todas las identidades.
  • ANY_USER_ACCOUNT: para permitir a todos los usuarios.
  • ANY_SERVICE_ACCOUNT: para permitir todas las cuentas de servicio.

• identities: Enumera las cuentas de servicio que pueden acceder a los recursos especificados fuera del perímetro.

• serviceAccount (opcional): Reemplaza SERVICE_ACCOUNT por la cuenta de servicio que puede acceder a los recursos especificados fuera del perímetro.

Ejemplos

En el siguiente ejemplo, se muestra una política que permite operaciones de salida desde el interior del perímetro hasta la ubicación del Amazon S3 s3://mybucket en AWS.

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - s3://mybucket
      - s3://mybucket2
  egressFrom:
    identityType: ANY_IDENTITY

En el siguiente ejemplo, se permiten operaciones de salida a un contenedor de Blob Storage.

- egressTo:
    operations:
    - serviceName: bigquery.googleapis.com
      methodSelectors:
      - method: "*"
    externalResources:
      - azure://myaccount.blob.core.windows.net/mycontainer
  egressFrom:
    identityType: ANY_IDENTITY

Para obtener más información sobre las políticas de salida, consulta la referencia de las reglas de salida.

Agrega la política de salida

Para agregar la política de salida cuando creas un perímetro de servicio nuevo, usa el comando gcloud access-context-manager perimeters create. Por ejemplo, con el siguiente comando, se crea un perímetro nuevo llamado omniPerimeter que incluye el proyecto con el número de proyecto 12345, restringe la API de BigQuery y agrega una política de salida definida en el archivo egress.yaml:

gcloud access-context-manager perimeters create omniPerimeter \
    --title="Omni Perimeter" \
    --resources=projects/12345 \
    --restricted-services=bigquery.googleapis.com \
    --egress-policies=egress.yaml

Para agregar la política de salida a un perímetro de servicio existente, usa el comando gcloud access-context-manager perimeters update. Por ejemplo, el siguiente comando agrega una política de salida definida en el archivo egress.yaml a un perímetro de servicio existente llamado omniPerimeter:

gcloud access-context-manager perimeters update omniPerimeter
    --set-egress-policies=egress.yaml

Verifica tu perímetro

Para verificar el perímetro, usa el comando gcloud access-context-manager perimeters describe:

gcloud access-context-manager perimeters describe PERIMETER_NAME

Reemplaza PERIMETER_NAME por el nombre del perímetro.

Por ejemplo, con el siguiente comando, se describe el perímetro omniPerimeter:

gcloud access-context-manager perimeters describe omniPerimeter

Para obtener más información, consulta Administra perímetros de servicio.

Limitaciones

Para obtener una lista completa de las limitaciones que se aplican a las tablas de BigLake basadas en Amazon S3 y Blob Storage, consulta Limitaciones.

¿Qué sigue?

• Obtén información sobre BigQuery Omni.
• Usa el lab de BigQuery Omni con AWS.
• Obtén más información sobre tablas de BigLake.
• Aprende a exportar resultados de consultas a Amazon S3.
• Aprende a crear vistas materializadas a través de las tablas habilitadas para caché de metadatos de Amazon Simple Storage Service (Amazon S3).
• Obtén información sobre cómo hacer que los datos de Amazon S3 en una vista materializada estén disponibles de forma local para uniones mediante la creación de una réplica de la vista materializada.