Crea tablas de BigLake de Cloud Storage

Console

1. Ve a la página de BigQuery.

   Ir a BigQuery

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

3. Expande la opción more_vert Acciones y haz clic en Crear table.

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

   1. En Crear tabla desde, elige Google Cloud Storage.

   2. En Elegir un archivo del bucket de GCS o usa un patrón de URI, elige un bucket y un archivo para usar o escribe la ruta con el formato gs://bucket_name/[folder_name/]file_name.

      No puedes especificar varios URI en la consola de Google Cloud, pero puedes elegir varios archivos si especificas un carácter comodín de asterisco (*). Por ejemplo, gs://mybucket/file_name* Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

      El bucket de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que quieres crear.

   3. En Formato de archivo, elige el formato que coincida con tu archivo.

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

   1. En Proyecto, elige el proyecto en el que deseas crear la tabla.

   2. En Conjunto de datos, elige el conjunto de datos en el que deseas crear la tabla.

   3. En Tabla, escribe el nombre de la tabla que crearás.

   4. En Tipo de tabla, selecciona Tabla externa.

   5. Selecciona Crear una tabla de BigLake mediante una conexión de Cloud Resource.

   6. 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 Cambiar como texto e escribe 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 elige Valores desconocidos.

8. Haga clic en Crear tabla.

Después de crear la tabla permanente, puedes ejecutar una consulta en ella como si fuera una tabla de BigQuery nativa. Cuando se completa tu consulta, puedes exportar los resultados como archivos CSV o JSON, guardarlos como una tabla o en Hojas de cálculo de Google.

SQL

Usa la declaración DDL CREATE EXTERNAL TABLE. Puedes especificar el esquema de forma explícita o usar la detección automática de esquemas para inferir el esquema a partir de los datos externos.

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 CONNECTION `PROJECT_ID.REGION.CONNECTION_ID`
     OPTIONS (
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'[,...]],
       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.
   • REGION: la región que contiene la conexión, por ejemplo, us
   • CONNECTION_ID: el ID de conexión, por ejemplo, myconnection

     Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo projects/myproject/locations/connection_location/connections/myconnection.

   • TABLE_FORMAT: el formato de la tabla que deseas crear, por ejemplo, PARQUET

     Para obtener más información sobre los formatos compatibles, consulta Limitaciones.

   • BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formato ['gs://bucket_name/[folder_name/]file_name'].

     Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso. Un ejemplo es ['gs://mybucket/file_name*']. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

     Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

     En los siguientes ejemplos, se muestran valores uris válidos:

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

     Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

   • 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 Cloud Storage.

   • CACHE_MODE: especifica si la caché de metadatos se actualiza de forma automática o manual. Si quieres 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 play_circle Ejecutar.

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

bq

Opción 1: Archivo de definición de tablas

Usa el comando bq mkdef para crear un archivo de definición de tablas y, luego, pasa la ruta de acceso del archivo al comando bq mk de la siguiente manera:

bq mkdef \
    --connection_id=CONNECTION_ID \
    --source_format=SOURCE_FORMAT \
  BUCKET_PATH > DEFINITION_FILE

bq mk --table \
    --external_table_definition=DEFINITION_FILE \
    --max_staleness=STALENESS_INTERVAL \
    PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME \
    SCHEMA

Reemplaza lo siguiente:

• CONNECTION_ID: el ID de conexión, por ejemplo, myconnection

  Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo projects/myproject/locations/connection_location/connections/myconnection.

• SOURCE_FORMAT: El formato de la fuente de datos externos. Por ejemplo, PARQUET

• BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formato gs://bucket_name/[folder_name/]file_pattern.

  Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso file_pattern. Un ejemplo es gs://mybucket/file00*.parquet. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

  Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

  En los siguientes ejemplos, se muestran valores uris válidos:

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

  Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

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

• 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 intervalo entre 30 minutos y 7 días, mediante el siguiente comando:Y-M D H:M:S formato que se describe en elINTERVAL tipo de datos. Por ejemplo, especifica 0-0 0 4:0:0 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 Cloud Storage.

• 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.

• SCHEMA: es el esquema de la tabla de BigLake

Ejemplo:

bq mkdef
    --connection_id=myconnection
    --metadata_cache_mode=CACHE_MODE
    --source_format=CSV 'gs://mybucket/*.csv' > mytable_def

bq mk
    --table
    --external_table_definition=mytable_def='gs://mybucket/*.csv'
    --max_staleness=0-0 0 4:0:0
    myproject:mydataset.mybiglaketable
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

Para usar la detección automática de esquemas, configura la marca --autodetect=true en el comando mkdef y omite el esquema:

bq mkdef \
    --connection_id=myconnection \
    --metadata_cache_mode=CACHE_MODE \
    --source_format=CSV --autodetect=true \
    gs://mybucket/*.csv > mytable_def

bq mk \
    --table \
    --external_table_definition=mytable_def=gs://mybucket/*.csv \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable

Opción 2: Definición de tabla intercalada

En lugar de crear un archivo de definición de tablas, puedes pasar la definición de tabla directamente al comando bq mk: Usa el decorador @connection para especificar la conexión que se usará al final de la marca --external_table_definition.

bq mk --table \
  --external_table_definition=@SOURCE_FORMAT=BUCKET_PATH@projects/PROJECT_ID/locations/REGION/connections/CONNECTION_ID \
  DATASET_NAME.TABLE_NAME \
  SCHEMA

Reemplaza lo siguiente:

• SOURCE_FORMAT: El formato de la fuente de datos externos.

  Por ejemplo, CSV.

• BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla, en el formato gs://bucket_name/[folder_name/]file_pattern.

  Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso file_pattern. Un ejemplo es gs://mybucket/file00*.parquet. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

  Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

  En los siguientes ejemplos, se muestran valores uris válidos:

  • gs://bucket/path1/myfile.csv
  • gs://bucket/path1/*.parquet
  • gs://bucket/path1/file1*, gs://bucket1/path1/*

  Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

  Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

• PROJECT_ID: el nombre del proyecto en el que deseas crear la tabla, por ejemplo, myproject.

• REGION: la región que contiene la conexión, us

• CONNECTION_ID: el ID de conexión, por ejemplo, myconnection

  Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo projects/myproject/locations/connection_location/connections/myconnection.

• DATASET_NAME: es el nombre del conjunto de datos en el que deseas crear la tabla de BigLake

• TABLE_NAME: es el nombre de la tabla BigLake

• SCHEMA: es el esquema de la tabla de BigLake

Ejemplo:

bq mk --table \
    --external_table_definition=@CSV=gs://mybucket/*.parquet@projects/myproject/locations/us/connections/myconnection \
    --max_staleness=0-0 0 4:0:0 \
    myproject:mydataset.myexternaltable \
    Region:STRING,Quarter:STRING,Total_sales:INTEGER

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 Cloud Storage.

Terraform

En este ejemplo, se crea una tabla de BigLake sobre datos no particionados.

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.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

# This queries the provider for project information.
data "google_project" "project" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.project.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding.
# This lets IAM permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with
# default expiration times for partitions and tables, a
# description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}


# This creates a BigQuery Table with automatic metadata caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema = jsonencode([
    { "name" : "country", "type" : "STRING" },
    { "name" : "product", "type" : "STRING" },
    { "name" : "price", "type" : "INT64" }
  ])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/data/*"]
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }

  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [time_sleep.default]
}

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 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).

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 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.

Console

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 more_vert 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 Create table from (Crear tabla desde), selecciona Google Cloud Storage.

   2. Proporciona la ruta de acceso a la carpeta mediante comodines. Por ejemplo, my_bucket/my_files*. 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, gs://my_bucket/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, selecciona Tabla externa.
   5. Selecciona la casilla de verificación Crear una tabla de BigLake con una conexión de Cloud Resource.
   6. 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 Cambiar como texto e escribe 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 elige 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'],
     max_staleness = STALENESS_INTERVAL,
     metadata_cache_mode = 'CACHE_MODE',
     format ="TABLE_FORMAT"
   );

   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 ID de conexión, por ejemplo, myconnection

     Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo projects/myproject/locations/connection_location/connections/myconnection.

   • HIVE_PARTITION_URI_PREFIX: prefijo de URI de partición de Hive, por ejemplo, gs://mybucket/
   • FILE_PATH: ruta de acceso a la fuente de datos para la tabla externa que deseas crear, por ejemplo, gs://mybucket/*.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 Cloud Storage.

   • 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.

   • TABLE_FORMAT: el formato de la tabla que deseas crear, por ejemplo, PARQUET

3. Haz clic en play_circle 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 sobre datos particionados en la que ocurre lo siguiente:

• El esquema se detecta de forma automática.
• El intervalo de inactividad de la caché de metadatos de la tabla es de 1 día.
• La caché de metadatos se actualiza 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 = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 1 DAY,
  metadata_cache_mode = 'AUTOMATIC'
);

En el siguiente ejemplo, se crea una tabla de BigLake sobre datos particionados en la que ocurre lo siguiente:

• Se especifica el esquema.
• El intervalo de inactividad de la caché de metadatos de la tabla es de 8 horas.
• La caché de metadatos se debe actualizar de forma manual.

CREATE EXTERNAL TABLE `my_dataset.my_table`
(
  ProductId INTEGER,
  ProductName STRING,
  ProductType STRING
)
WITH PARTITION COLUMNS
(
  sku STRING,
)
WITH CONNECTION `us.my-connection`
OPTIONS(
  hive_partition_uri_prefix = "gs://mybucket/products",
  uris = ['gs://mybucket/products/*'],
  max_staleness = INTERVAL 8 HOUR,
  metadata_cache_mode = 'MANUAL'
);

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=GCS_URI_SHARED_PREFIX \
--require_hive_partition_filter=BOOLEAN \
--metadata_cache_mode=CACHE_MODE \
 GCS_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 ID de conexión, por ejemplo, myconnection.

  Cuando ves los detalles de conexión en la consola de Google Cloud, el ID de conexión es el valor en la última sección del ID de conexión completamente calificado que se muestra en ID de conexión, por ejemplo projects/myproject/locations/connection_location/connections/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.

• GCS_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 en caché de metadatos para 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.

• GCS_URIS: Es la ruta a la carpeta de Cloud Storage, en el formato de 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=GCS_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 --external_table_definition=DEFINITION_FILE \
--max_staleness=STALENESS_INTERVAL \
DATASET_NAME.TABLE_NAME \
SCHEMA

Reemplaza lo siguiente:

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

• 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 incluyes esta marca, también debes haber especificado un valor para la marca --metadata_cache_mode en el comando anterior bq mkdef. Si deseas obtener más información sobre las consideraciones de almacenamiento en caché de metadatos, consulta Almacenamiento en caché de metadatos para 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 intervalo entre 30 minutos y 7 días, mediante Y-M D H:M:S formato que se describe en el tipo de datos INTERVAL. Por ejemplo, especifica 0-0 0 4:0:0 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 Cloud Storage.

• 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 y, también, se configura la caché de metadatos para que tenga un intervalo de inactividad de 12 horas y se actualice de forma automática:

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

bq mk --external_table_definition=mytable_def \
  --max_staleness=0-0 0 12:0:0 \
  mydataset.mytable \
  Region:STRING,Quarter:STRING,Total_sales:INTEGER

En el siguiente ejemplo, se usa el modo de partición de subárbol STRING:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=STRING \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable \
  gs://myBucket/myTable/* > mytable_def

bq mk --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 de subárbol CUSTOM:

bq mkdef --source_format=CSV \
  --connection_id=us.my-connection \
  --hive_partitioning_mode=CUSTOM \
  --hive_partitioning_source_uri_prefix=gs://myBucket/myTable/{dt:DATE}/{val:STRING} \
  gs://myBucket/myTable/* > mytable_def

bq mk --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: gs://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.

Terraform

En este ejemplo, se crea una tabla de BigLake sobre datos particionados.

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.

# This creates a bucket in the US region named "my-bucket" with a pseudorandom
# suffix.
resource "random_id" "default" {
  byte_length = 8
}
resource "google_storage_bucket" "default" {
  name                        = "my-bucket-${random_id.default.hex}"
  location                    = "US"
  force_destroy               = true
  uniform_bucket_level_access = true
}

resource "google_storage_bucket_object" "default" {
  # This creates a fake message to create partition locations on the table.
  # Otherwise, the table deployment fails.
  name    = "publish/dt=2000-01-01/hr=00/min=00/fake_message.json"
  content = "{\"column1\": \"XXX\"}"
  bucket  = google_storage_bucket.default.name
}

# This queries the provider for project information.
data "google_project" "default" {}

# This creates a connection in the US region named "my-connection".
# This connection is used to access the bucket.
resource "google_bigquery_connection" "default" {
  connection_id = "my-connection"
  location      = "US"
  cloud_resource {}
}

# This grants the previous connection IAM role access to the bucket.
resource "google_project_iam_member" "default" {
  role    = "roles/storage.objectViewer"
  project = data.google_project.default.id
  member  = "serviceAccount:${google_bigquery_connection.default.cloud_resource[0].service_account_id}"
}

# This makes the script wait for seven minutes before proceeding. This lets IAM
# permissions propagate.
resource "time_sleep" "default" {
  create_duration = "7m"

  depends_on = [google_project_iam_member.default]
}

# This defines a Google BigQuery dataset with default expiration times for
# partitions and tables, a description, a location, and a maximum time travel.
resource "google_bigquery_dataset" "default" {
  dataset_id                      = "my_dataset"
  default_partition_expiration_ms = 2592000000  # 30 days
  default_table_expiration_ms     = 31536000000 # 365 days
  description                     = "My dataset description"
  location                        = "US"
  max_time_travel_hours           = 96 # 4 days

  # This defines a map of labels for the bucket resource,
  # including the labels "billing_group" and "pii".
  labels = {
    billing_group = "accounting",
    pii           = "sensitive"
  }
}

# This creates a BigQuery table with partitioning and automatic metadata
# caching.
resource "google_bigquery_table" "default" {
  dataset_id = google_bigquery_dataset.default.dataset_id
  table_id   = "my_table"
  schema     = jsonencode([{ "name" : "column1", "type" : "STRING", "mode" : "NULLABLE" }])
  external_data_configuration {
    # This defines an external data configuration for the BigQuery table
    # that reads Parquet data from the publish directory of the default
    # Google Cloud Storage bucket.
    autodetect    = false
    source_format = "PARQUET"
    connection_id = google_bigquery_connection.default.name
    source_uris   = ["gs://${google_storage_bucket.default.name}/publish/*"]
    # This configures Hive partitioning for the BigQuery table,
    # partitioning the data by date and time.
    hive_partitioning_options {
      mode                     = "CUSTOM"
      source_uri_prefix        = "gs://${google_storage_bucket.default.name}/publish/{dt:STRING}/{hr:STRING}/{min:STRING}"
      require_partition_filter = false
    }
    # This enables automatic metadata refresh.
    metadata_cache_mode = "AUTOMATIC"
  }


  # This sets the maximum staleness of the metadata cache to 10 hours.
  max_staleness = "0-0 0 10:0:0"

  deletion_protection = false

  depends_on = [
    time_sleep.default,
    google_storage_bucket_object.default
  ]
}

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 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).

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 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.

SQL

Usa la declaración DDL CREATE OR REPLACE EXTERNAL TABLE para actualizar una tabla:

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 OR REPLACE EXTERNAL TABLE
     `PROJECT_ID.DATASET.EXTERNAL_TABLE_NAME`
     WITH CONNECTION `REGION.CONNECTION_ID`
     OPTIONS(
       format ="TABLE_FORMAT",
       uris = ['BUCKET_PATH'],
       max_staleness = STALENESS_INTERVAL,
       metadata_cache_mode = 'CACHE_MODE'
       );

   Reemplaza lo siguiente:

   • PROJECT_ID: el nombre del proyecto que contiene la tabla
   • DATASET: el nombre del conjunto de datos que contiene la tabla
   • EXTERNAL_TABLE_NAME: el nombre de la tabla
   • REGION: la región que contiene la conexión
   • CONNECTION_ID: el nombre de la conexión que se usará
   • TABLE_FORMAT: el formato que usa la tabla

     No puedes cambiar esto cuando actualizas la tabla.

   • BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formato ['gs://bucket_name/[folder_name/]file_name'].

     Puedes elegir varios archivos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso. Un ejemplo es ['gs://mybucket/file_name*']. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

     Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

     En los siguientes ejemplos, se muestran valores uris válidos:

     • ['gs://bucket/path1/myfile.csv']
     • ['gs://bucket/path1/*.csv']
     • ['gs://bucket/path1/*', 'gs://bucket/path2/file00*']

     Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

     Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

   • STALENESS_INTERVAL: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché 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 Cloud Storage.

   • 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 play_circle Ejecutar.

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

bq

Usa los comandos bq mkdef y bq update para actualizar una tabla:

1. Genera una definición de tabla externa, que describa los aspectos de la tabla que se debe cambiar:

   bq mkdef --connection_id=PROJECT_ID.REGION.CONNECTION_ID \
   --source_format=TABLE_FORMAT \
   --metadata_cache_mode=CACHE_MODE \
   "BUCKET_PATH" > /tmp/DEFINITION_FILE

   Reemplaza lo siguiente:

   • PROJECT_ID: el nombre del proyecto que contiene la conexión
   • REGION: la región que contiene la conexión
   • CONNECTION_ID: el nombre de la conexión que se usará
   • TABLE_FORMAT: el formato que usa la tabla No puedes cambiar esto cuando actualizas la tabla.

   • 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.

   • BUCKET_PATH: la ruta al bucket de Cloud Storage que contiene los datos de la tabla externa, en el formato gs://bucket_name/[folder_name/]file_name.

     Puedes limitar los archivos elegidos del bucket si especificas un carácter comodín de asterisco (*) en la ruta de acceso. Un ejemplo es gs://mybucket/file_name*. Si deseas obtener más información, consulta Compatibilidad de comodines para los URI de Cloud Storage.

     Puedes especificar varios buckets para la opción uris si proporcionas varias rutas de acceso.

     En los siguientes ejemplos, se muestran valores uris válidos:

     • gs://bucket/path1/myfile.csv
     • gs://bucket/path1/*.csv
     • gs://bucket/path1/*,gs://bucket/path2/file00*

     Cuando especificas valores uris que se orientan a varios archivos, todos esos archivos deben compartir un esquema compatible.

     Para obtener más información sobre cómo usar los URI de Cloud Storage en BigQuery, consulta Ruta de acceso al recurso de Cloud Storage.

   • DEFINITION_FILE: el nombre del archivo de definición de tablas que crearás.

2. Actualiza la tabla con la definición de tabla externa nueva:

   bq update --max_staleness=STALENESS_INTERVAL \
   --external_table_definition=/tmp/DEFINITION_FILE \
   PROJECT_ID:DATASET.EXTERNAL_TABLE_NAME

   Reemplaza lo siguiente:

   • STALENESS_INTERVAL: especifica si las operaciones en la tabla usan los metadatos almacenados en caché y qué tan recientes deben ser los metadatos almacenados en caché 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 intervalo entre 30 minutos y 7 días, mediante el siguiente comando:Y-M D H:M:S formato que se describe en elINTERVAL tipo de datos. Por ejemplo, especifica 0-0 0 4:0:0 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 Cloud Storage.

   • DEFINITION_FILE: el nombre del archivo de definición de tablas que creaste o actualizaste.

   • PROJECT_ID: el nombre del proyecto que contiene la tabla

   • DATASET: el nombre del conjunto de datos que contiene la tabla

   • EXTERNAL_TABLE_NAME: El nombre de la tabla.

Ejemplo

En el siguiente ejemplo, se actualiza mytable para usar metadatos almacenados en caché, siempre que se hayan actualizado en las últimas 4.5 horas, y también actualizar metadatos en caché de forma automática:

bq update --project_id=myproject --max_staleness='0-0 0 4:30:0' \
--external_table_definition=enable_metadata.json mydataset.mytable

En el ejemplo anterior, enable_metadata.json tiene el siguiente contenido: { "metadataCacheMode": "AUTOMATIC" }