Exporta los datos de la tabla a Cloud Storage

En esta página, se describe cómo exportar o extraer datos de tablas de BigQuery a Cloud Storage.

Después de cargar tus datos en BigQuery, puedes exportarlos en varios formatos. BigQuery puede exportar hasta 1 GB de datos a un solo archivo. Si necesitas exportar más de 1 GB de datos, debes exportarlos a varios archivos. Cuando exportas tus datos a varios archivos, el tamaño de estos puede variar.

Puedes usar un servicio como Dataflow para leer datos de BigQuery en lugar de exportarlos de forma manual. Si quieres obtener más información sobre cómo usar Dataflow para leer y escribir en BigQuery, consulta E/S de BigQuery en la documentación de Apache Beam.

También puedes exportar los resultados de una consulta mediante la declaración EXPORT DATA. Puedes usar EXPORT DATA OPTIONS para exportar vistas a Cloud Storage.

Exporta limitaciones

Cuando exportes datos desde BigQuery, ten en cuenta esta información:

• No puedes exportar datos de tabla a un archivo local, a las Hojas de cálculo de Google o a Google Drive. La única ubicación de exportación admitida es Cloud Storage. Para obtener información sobre cómo guardar resultados de consultas, consulta Descarga y guarda resultados de consultas.
• Puedes exportar hasta 1 GB de datos de tablas a un solo archivo. Si necesitas exportar más de 1 GB de datos, usa un comodín para exportar los datos a varios archivos. Cuando exportas datos a varios archivos, el tamaño de estos puede variar. Para limitar el tamaño del archivo exportado, puedes particionar los datos y exportar cada partición.
• No se garantiza el tamaño del archivo generado cuando se usa la declaración EXPORT DATA.
• La cantidad de archivos que genera un trabajo de exportación puede variar.
• No puedes exportar datos anidados y repetidos en formato CSV. Las exportaciones Avro, JSON y Parquet admiten datos anidados y repetidos.
• Cuando exportas datos en formato JSON, los tipos de datos INT64 (número entero) se codifican como strings JSON para preservar la precisión de 64 bits cuando otros sistemas leen los datos.
• No puedes exportar datos de varias tablas en un solo trabajo de exportación.
• No puedes elegir un tipo de compresión distinta de GZIP cuando exportas datos mediante la consola de Google Cloud.
• Cuando exportas datos a un bucket de Cloud Storage configurado con una política de retención, es posible que BigQuery no escriba los archivos en el bucket. Configura el período de retención para que sea mayor que la duración de los trabajos de exportación.
• Cuando exportas una tabla en formato JSON, los símbolos <, > y & se convierten mediante la notación Unicode \uNNNN, en la que N es un dígito hexadecimal. Por ejemplo, profit&loss se convierte en profit\u0026loss. Esta conversión Unicode se realiza para evitar vulnerabilidades de seguridad.
• El orden de los datos de tabla exportados no está garantizado, a menos que uses la declaración EXPORT DATA y especifiques una cláusula ORDER BY en query_statement.
• BigQuery no admite rutas de recursos de Cloud Storage que incluyan varias barras consecutivas después de la doble barra inicial. Los nombres de los objetos de Cloud Storage pueden contener varios caracteres de barras consecutivas (“/”). Sin embargo, con BigQuery puedes convertir varias barras consecutivas en una sola barra. Por ejemplo, la ruta de acceso al recurso siguiente, aunque es válida en Cloud Storage, no funciona en BigQuery: gs://bucket/my//object//name.
• Los datos nuevos que se carguen en BigQuery mientras se ejecuta un trabajo de exportación no se incluirán en ese trabajo. Debes crear un trabajo de exportación nuevo para exportar los datos nuevos.

Antes de comenzar

Otorga roles de Identity and Access Management (IAM) que les brindan a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos necesarios

Para realizar las tareas de este documento, necesitas los siguientes permisos.

Permisos para exportar datos desde una tabla de BigQuery

Para exportar datos de una tabla de BigQuery, necesitas el permiso bigquery.tables.export de IAM.

Cada una de las siguientes funciones predefinidas de IAM incluye el permiso bigquery.tables.export:

• roles/bigquery.dataViewer
• roles/bigquery.dataOwner
• roles/bigquery.dataEditor
• roles/bigquery.admin

Permisos para ejecutar un trabajo de exportación

Para ejecutar un trabajo de exportación, necesitas el permiso bigquery.jobs.create de IAM.

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para ejecutar un trabajo de exportación:

• roles/bigquery.user
• roles/bigquery.jobUser
• roles/bigquery.admin

Permisos para escribir los datos en el bucket de Cloud Storage

Para escribir los datos en un bucket de Cloud Storage existente, necesitas los siguientes permisos de IAM:

• storage.objects.create
• storage.objects.delete

Cada una de las siguientes funciones predefinidas de IAM incluye los permisos que necesitas para escribir los datos en un bucket existente de Cloud Storage:

• roles/storage.objectAdmin
• roles/storage.admin

Para obtener más información sobre las funciones y los permisos de IAM en BigQuery, consulta Funciones y permisos predefinidos.

Consideraciones de ubicación

Coloca los buckets de Cloud Storage en la misma ubicación para exportar datos.
• Si tu conjunto de datos de BigQuery está en la multirregión EU, el bucket de Cloud Storage que contiene los datos que exportas debe estar en la misma ubicación o dentro de la multirregión. Por ejemplo, si tu conjunto de datos de BigQuery está en la multirregión EU, el bucket de Cloud Storage puede estar ubicado en la región europe-west1 de Bélgica, que está dentro de EU.

  Si tu conjunto de datos está en la multirregión US, puedes exportar datos a un bucket de Cloud Storage en cualquier ubicación.

• Si tu conjunto de datos está en una región, el bucket de Cloud Storage debe estar en la misma región. Por ejemplo, si tu conjunto de datos está en la región asia-northeast1 de Tokio, tu bucket de Cloud Storage no puede estar en la multirregión ASIA.

Desarrolla un plan de administración de datos:

• Si eliges un recurso de almacenamiento regional, como un conjunto de datos de BigQuery o un depósito de Cloud Storage, debes desarrollar un plan para administrar tus datos geográficamente.

Para obtener más información sobre las ubicaciones de Cloud Storage, consulta Ubicaciones de buckets en la documentación de Cloud Storage.

Traslada los datos de BigQuery entre ubicaciones

No puedes cambiar la ubicación de un conjunto de datos después de crearlo, pero puedes crear una copia del conjunto de datos. No puedes mover un conjunto de datos de una ubicación a otra, pero puedes mover (recrear) un conjunto de datos de forma manual.

Exporta formatos y tipos de compresión

BigQuery es compatible con los formatos de datos y tipos de compresión siguientes para datos exportados.

Formato de los datos	Tipos de compresión compatibles	Detalles
CSV	GZIP	Puedes controlar el delimitador CSV en los datos exportados mediante la marca --field_delimiter de la herramienta de línea de comandos de bq o la propiedad de trabajo de extracción configuration.extract.fieldDelimiter. Los datos anidados y repetidos no son compatibles.
JSON	GZIP	Los datos anidados y repetidos son compatibles.
Avro	DEFLATE, SNAPPY	GZIP no es compatible con las exportaciones de Avro. Los datos anidados y repetidos son compatibles. Consulta Detalles de exportación de Avro.
Parquet	SNAPPY, GZIP, ZSTD	Los datos anidados y repetidos son compatibles. Consulta Detalles de exportación de Parquet.

Exportar datos

Para exportar datos de tablas, puedes hacer lo siguiente:

• Usa la consola de Google Cloud
• Usa el comando bq extract en la herramienta de línea de comandos de bq
• Envía un trabajo extract con la API o las bibliotecas cliente

Exportar datos de tablas

Para exportar datos desde una tabla de BigQuery, sigue estos pasos:

Console

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

   Ir a la página de BigQuery

2. En el panel Explorador, expande el proyecto y conjunto de datos y, luego, selecciona la tabla.

3. En el panel de detalles, haz clic en Exportar y selecciona Exportar a Cloud Storage.

4. Realiza estas acciones en el cuadro de diálogo Exportar tabla a Google Cloud Storage:

   • Para Seleccionar una ubicación de Google Cloud Storage, busca el depósito, la carpeta o el archivo en el que deseas exportar los datos.
   • En Formato de exportación, selecciona el formato de los datos exportados: CSV, JSON (delimitado por saltos de línea), Avro o Parquet.
   • En Compresión, selecciona un formato de compresión o selecciona None para no comprimir.
   • Haz clic en Exportar para exportar la tabla. google3/googledata/devsite/site-cloud/en/bigquery/docs/introduction-sql.md Para verificar el progreso del trabajo, busca en la parte superior de la navegación el Historial de trabajos de un trabajo de Exportación.

Para exportar vistas a Cloud Storage, usa la sentencia EXPORT DATA OPTIONS.

SQL

Usa la sentencia EXPORT DATA. En el siguiente ejemplo, se exportan los campos seleccionados de una tabla llamada mydataset.table1:

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:

   EXPORT DATA
     OPTIONS (
       uri = 'gs://bucket/folder/*.csv',
       format = 'CSV',
       overwrite = true,
       header = true,
       field_delimiter = ';')
   AS (
     SELECT field1, field2
     FROM mydataset.table1
     ORDER BY field1
   );

3. Haz clic en Ejecutar.

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

bq

Usa el comando bq extract con la marca --destination_format.

Opcional: Proporciona la marca --location y configura el valor en tu ubicación.

Las siguientes son otras marcas opcionales:

• --compression: Es el tipo de compresión que se usará para los archivos exportados.
• --field_delimiter: Es el carácter que indica el límite entre las columnas en el archivo de salida para las exportaciones de formato CSV. \t y tab pueden ser delimitadores de tabulación.
• --print_header: Cuando se especifica, imprime las filas de encabezado de los formatos que tienen encabezados, como CSV.

bq extract --location=location \
--destination_format format \
--compression compression_type \
--field_delimiter delimiter \
--print_header=boolean \
project_id:dataset.table \
gs://bucket/filename.ext

Aquí:

• location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes establecer un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• format es el formato de los datos exportados: CSV, NEWLINE_DELIMITED_JSON, AVRO o PARQUET.
• compression_type es un tipo de compresión compatible para tu formato de datos. Consulta Formatos de exportación y tipos de compresión.
• delimiter es el carácter que indica el límite entre columnas en las exportaciones de CSV. \t y tab son nombres aceptados para la pestaña.
• boolean es true o false. Cuando se establece en true, las filas del encabezado se imprimen en los datos exportados si el formato de datos admite encabezados. El valor predeterminado es true.
• project_id es el ID del proyecto.
• dataset es el nombre del conjunto de datos de origen.
• table es la tabla que exportarás. Si usas un decorador de particiones, debes rodear la ruta de la tabla con comillas simples o escapar el carácter $.
• bucket es el nombre del depósito de Cloud Storage al que exportarás los datos. El conjunto de datos de BigQuery y el depósito de Cloud Storage deben estar en la misma ubicación.
• filename.ext es el nombre y la extensión del archivo de datos exportado. Puedes exportar a varios archivos con un comodín.

Ejemplos:

Por ejemplo, el siguiente comando exporta mydataset.mytable a un archivo comprimido de gzip llamado myfile.csv. myfile.csv se almacena en un depósito de Cloud Storage llamado example-bucket.

bq extract \
--compression GZIP \
'mydataset.mytable' \
gs://example-bucket/myfile.csv

El formato de destino predeterminado es CSV. Para exportar en JSON o Avro, usa la marca destination_format y configúrala como NEWLINE_DELIMITED_JSON o AVRO. Por ejemplo:

bq extract \
--destination_format NEWLINE_DELIMITED_JSON \
'mydataset.mytable' \
gs://example-bucket/myfile.json

El siguiente comando exporta mydataset.mytable a un archivo Avro comprimido con Snappy. El nombre del archivo es myfile.avro. myfile.avro se exporta a un depósito de Cloud Storage llamado example-bucket.

bq extract \
--destination_format AVRO \
--compression SNAPPY \
'mydataset.mytable' \
gs://example-bucket/myfile.avro

Con el siguiente comando, se exporta una sola partición de mydataset.my_partitioned_table a un archivo CSV en Cloud Storage:

bq extract \
--destination_format CSV \
'mydataset.my_partitioned_table$0' \
gs://example-bucket/single_partition.csv

API

Para exportar datos, crea un trabajo extract y propaga la configuración del trabajo.

Nota: Si exportas datos al formato Parquet, es posible que sea más rápido usar la exportación de BigQuery a Parquet (a través de la API de BigQuery Storage) en lugar de escribir una solución personalizada.

Especifica tu ubicación en la propiedad location en la sección jobReference del recurso del trabajo (opcional).

1. Crea un trabajo de extracción que haga referencia a los datos de origen de BigQuery y al destino de Cloud Storage.

2. Especifica la tabla de origen mediante el objeto de configuración sourceTable que contiene el ID del proyecto, el ID del conjunto de datos y el ID de la tabla.

3. La propiedad destination URI(s) debe estar completamente y calificada en el formato gs://bucket/filename.ext. Cada URI puede contener un carácter comodín “*” y debe aparecer después del nombre del depósito.

4. Para especificar el formato de datos, configura la propiedad configuration.extract.destinationFormat. Por ejemplo, para exportar un archivo JSON, configura esta propiedad con el valor NEWLINE_DELIMITED_JSON.

5. Para verificar el estado del trabajo, llama a jobs.get(job_id) con el ID del trabajo que se muestra en la solicitud inicial.

   • Si se muestra status.state = DONE, el trabajo se completó de forma correcta.
   • Si la propiedad status.errorResult está presente, la solicitud falló y ese objeto incluirá información que describa qué salió mal.
   • Si status.errorResult está ausente, el trabajo finalizó de forma correcta, aunque puede que haya habido algunos errores recuperables. Se enumeran los errores recuperables en la propiedad status.errors del objeto de trabajo que se muestra.

Notas de API:

• Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId cuando llames a jobs.insert para crear un trabajo. Este enfoque es más resistente al fallo de la red porque el cliente puede sondear o reintentar con el ID de trabajo conocido.

• Llamar a jobs.insert con un ID de trabajo dado es idempotente. En otras palabras, puedes volver a intentarlo tantas veces como desees con el mismo ID de trabajo y al menos una de las operaciones será correcta.

C#

Antes de probar este ejemplo, sigue las instrucciones de configuración para C# 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 C#.

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.

using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryExtractTable
{
    public void ExtractTable(
        string projectId = "your-project-id",
        string bucketName = "your-bucket-name")
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        // Define a destination URI. Use a single wildcard URI if you think
        // your exported data will be larger than the 1 GB maximum value.
        string destinationUri = $"gs://{bucketName}/shakespeare-*.csv";
        BigQueryJob job = client.CreateExtractJob(
            projectId: "bigquery-public-data",
            datasetId: "samples",
            tableId: "shakespeare",
            destinationUri: destinationUri
        );
        job = job.PollUntilCompleted().ThrowOnAnyError();  // Waits for the job to complete.
        Console.Write($"Exported table to {destinationUri}.");
    }
}

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go 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 Go.

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 (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as CSV.
func exportTableAsCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsUri := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.FieldDelimiter = ","

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

	job, err := extractor.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

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.RetryOption;
import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.Table;
import com.google.cloud.bigquery.TableId;
import org.threeten.bp.Duration;

public class ExtractTableToCsv {

  public static void runExtractTableToCsv() {
    // TODO(developer): Replace these variables before running the sample.
    String projectId = "bigquery-public-data";
    String datasetName = "samples";
    String tableName = "shakespeare";
    String bucketName = "my-bucket";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html

    String dataFormat = "CSV";
    extractTableToCsv(projectId, datasetName, tableName, destinationUri, dataFormat);
  }

  // Exports datasetName:tableName to destinationUri as raw CSV
  public static void extractTableToCsv(
      String projectId,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat) {
    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);
      Table table = bigquery.getTable(tableId);

      Job job = table.extract(dataFormat, destinationUri);

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob =
          job.waitFor(
              RetryOption.initialRetryDelay(Duration.ofSeconds(1)),
              RetryOption.totalTimeout(Duration.ofMinutes(3)));
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println(
          "Table export successful. Check in GCS bucket for the " + dataFormat + " file.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js 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 Node.js.

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 the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableToGCS() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as raw CSV.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
  };

  // Export data from the table into a Google Cloud Storage file
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .extract(storage.bucket(bucketName).file(filename), options);

  console.log(`Job ${job.id} created.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

Antes de probar este ejemplo, sigue las instrucciones de configuración para PHP 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 PHP.

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.

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Extracts the given table as json to given GCS bucket.
 *
 * @param string $projectId The project Id of your Google Cloud Project.
 * @param string $datasetId The BigQuery dataset ID.
 * @param string $tableId The BigQuery table ID.
 * @param string $bucketName Bucket name in Google Cloud Storage
 */
function extract_table(
    string $projectId,
    string $datasetId,
    string $tableId,
    string $bucketName
): void {
    $bigQuery = new BigQueryClient([
      'projectId' => $projectId,
    ]);
    $dataset = $bigQuery->dataset($datasetId);
    $table = $dataset->table($tableId);
    $destinationUri = "gs://{$bucketName}/{$tableId}.json";
    // Define the format to use. If the format is not specified, 'CSV' will be used.
    $format = 'NEWLINE_DELIMITED_JSON';
    // Create the extract job
    $extractConfig = $table->extract($destinationUri)->destinationFormat($format);
    // Run the job
    $job = $table->runJob($extractConfig);  // Waits for the job to complete
    printf('Exported %s to %s' . PHP_EOL, $table->id(), $destinationUri);
}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python 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 Python.

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.

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'
project = "bigquery-public-data"
dataset_id = "samples"
table_id = "shakespeare"

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table(table_id)

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
)  # API request
extract_job.result()  # Waits for job to complete.

print(
    "Exported {}:{}.{} to {}".format(project, dataset_id, table_id, destination_uri)
)

Ruby

Antes de probar este ejemplo, sigue las instrucciones de configuración para Ruby 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 Ruby.

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.

require "google/cloud/bigquery"

def extract_table bucket_name = "my-bucket",
                  dataset_id  = "my_dataset_id",
                  table_id    = "my_table_id"

  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  table    = dataset.table    table_id

  # Define a destination URI. Use a single wildcard URI if you think
  # your exported data will be larger than the 1 GB maximum value.
  destination_uri = "gs://#{bucket_name}/output-*.csv"

  extract_job = table.extract_job destination_uri do |config|
    # Location must match that of the source table.
    config.location = "US"
  end
  extract_job.wait_until_done! # Waits for the job to complete

  puts "Exported #{table.id} to #{destination_uri}"
end

Detalles de exportación de Avro

BigQuery expresa datos en formato Avro de las maneras siguientes:

• Los archivos de exportación resultantes son archivos de contenedor Avro.
• Cada fila de BigQuery se representa como un registro Avro. Los datos anidados se representan con objetos de registro anidados.
• Los campos REQUIRED se representan como los tipos Avro correspondientes. Por ejemplo, un tipo INTEGER de BigQuery asigna a un tipo LONG de Avro.
• Los campos NULLABLE se representan como una unión Avro del tipo correspondiente y “nulo”.
• Los campos REPEATED se representan como arreglos de Avro.
• Los tipos de datos TIMESTAMP se representan como un tipo lógico timestamp-micros (anota un tipo LONG de Avro) de forma predeterminada en los trabajos de extracción y en la exportación de datos de SQL. (Precaución: Puedes agregar use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico y usarlostring en su lugar en la columna de marca de tiempo, pero en Trabajos de extracción, siempre usa el tipo lógico de Avro).
• Los tipos de datos DATE se representan como un tipo lógico de date (anota un tipo INT de Avro) de forma predeterminada en la exportación de datos de SQL, pero se representan como un tipo string de forma predeterminada. en Trabajos de extracción. (Nota: Puedes agregar use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True a fin de habilitar el tipo lógico en trabajos de extracción).
• Los tipos de datos TIME se representan como un tipo lógico timestamp-micro (anota un tipo LONG de Avro) de forma predeterminada en la exportación de datos de SQL, pero como un tipo string de forma predeterminada en Trabajos de extracción. (Nota: Puedes agregar use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True a fin de habilitar el tipo lógico en trabajos de extracción).
• Los tipos de datos DATETIME se representan como tipos STRING de Avro (un tipo de string con tipo lógico personalizado con el nombre datetime) de forma predeterminada en SQL de exportación de datos, pero se representan como string de forma predeterminada en Trabajos de extracción. (Nota: Puedes agregar use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True a fin de habilitar el tipo lógico en trabajos de extracción).

Nota: La codificación del tipo de string sigue la especificación RFC 3339 de Internet Engineering Task Force.

Los tipos de datos NUMERIC(P[, S]) y BIGNUMERIC(P[, S]) parametrizados transfieren sus parámetros de precisión y tipo de escala al tipo lógico decimal Avro.

Precaución:

• Si exportas un tipo DATETIME a Avro, no puedes cargar el archivo de Avro directamente en el mismo esquema de tabla, ya que la STRING convertida no coincidirá con el esquema. Como solución alternativa, carga el archivo en una tabla de etapa de pruebas. Luego, usa una consulta en SQL para convertir el campo en un tipo DATETIME y guarda el resultado en una tabla nueva. Para obtener más información, consulta Cambia el tipo de datos de una columna.
• La opción de exportar datos use_avro_logical_types y extraer la marca de trabajo --use_avro_logical_types se aplica a todos los tipos lógicos al mismo tiempo una vez que se especifica.

El formato Avro no se puede usar junto con la compresión GZIP. Para comprimir datos Avro, usa la herramienta de línea de comandos de bq o la API y especifica uno de los tipos de compresión compatibles con los datos Avro: DEFLATE o SNAPPY.

Detalles de exportación de Parquet

BigQuery convierte los tipos de datos de GoogleSQL en los siguientes tipos de datos de Parquet:

Tipo de datos de BigQuery	Tipo básico de Parquet	Tipo lógico de Parquet
Entero	INT64	NONE
Numérico	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 38, scale = 9)
Numeric(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
BigNumeric	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = 76, scale = 38)
BigNumeric(P[, S])	FIXED_LEN_BYTE_ARRAY	DECIMAL (precision = P, scale = S)
Punto flotante	FLOAT	NONE
Booleano	BOOLEAN	NONE
String	BYTE_ARRAY	STRING (UTF8)
Bytes	BYTE_ARRAY	NONE
Fecha	INT32	DATE
Fecha y hora	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Tiempo	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
Marca de tiempo	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)

El esquema de Parquet representa los datos anidados como un grupo y los registros repetidos como grupos repetidos. Si deseas obtener más información sobre datos anidados y repetidos en BigQuery, consulta Especifica columnas anidadas y repetidas.

Precaución: Si exportas un tipo DATETIME a Parquet, no puedes cargar el archivo de Parquet directamente en el mismo esquema de tabla, ya que el valor convertido no coincidirá con el esquema.

Puedes usar las siguientes soluciones para los tipos DATETIME:

• Carga el archivo en una tabla de etapa de pruebas. Luego, usa una consulta de SQL para convertir el campo en DATETIME y guarda el resultado en una tabla nueva. Para obtener más información, consulta Cambia el tipo de datos de una columna.
• Proporciona un esquema para la tabla mediante la marca --schema en el trabajo de carga. Define la columna de fecha y hora como col:DATETIME.

Exporta datos a uno o más archivos

La propiedad destinationUris indica una o más ubicaciones y nombres de archivo en los que BigQuery debería exportar los archivos.

BigQuery admite un solo operador de comodín (*) en cada URI. El comodín puede aparecer en cualquier lugar del URI, excepto como parte del nombre del depósito. El uso del operador de comodín le indica a BigQuery que cree varios archivos fragmentados según el patrón suministrado. El operador de comodín se reemplaza con un número (que comienza en 0) y se rellena a la izquierda con 12 dígitos. Por ejemplo, un URI con un comodín al final del nombre del archivo crearía archivos con 000000000000 adjuntado al primer archivo y 000000000001 adjuntado al segundo archivo, y continuaría con ese patrón.

En la siguiente tabla, se describen varias opciones posibles para la propiedad destinationUris:

Opciones de destinationUris
Un solo URI	Usa un solo URI si exportas una cantidad de datos de tabla igual o inferior a 1 GB. Esta opción es el caso de uso más común, ya que los datos exportados suelen ser inferiores al valor máximo de 1 GB. Esta opción no es compatible con la instrucción EXPORT DATA; debes usar un URI de un solo comodín. Definición de la propiedad: ['gs://my-bucket/file-name.json'] Crea: gs://my-bucket/file-name.json
URI de un solo comodín	Usa un URI de un solo comodín si piensas que tus datos exportados serán superiores al valor máximo de 1 GB. BigQuery fragmenta tus datos en varios archivos según el patrón proporcionado. El tamaño de los archivos exportados variará. Si usas un comodín en un componente del URI que no sea el nombre del archivo, asegúrate de que la ruta de acceso del componente no exista antes de exportar tus datos. Definición de la propiedad: ['gs://my-bucket/file-name-*.json'] Crea: gs://my-bucket/file-name-000000000000.json gs://my-bucket/file-name-000000000001.json gs://my-bucket/file-name-000000000002.json ...

Limita el tamaño del archivo exportado

Cuando exportas más de 1 GB de datos en un solo movimiento, debes usar un comodín para exportar esos datos a varios archivos; además, el tamaño de los archivos varía. Si necesitas limitar el tamaño máximo de cada archivo exportado, una opción es particionar los datos de forma aleatoria y, luego, exportar cada partición a un archivo:

1. Determina la cantidad de particiones que necesitas, que es igual al tamaño total de los datos dividido entre el tamaño del archivo exportado elegido. Por ejemplo, si tienes 8,000 MB de datos y quieres que cada archivo exportado sea de alrededor de 20 MB, necesitas 400 particiones.

2. Crea una tabla nueva particionada y agrupada en clústeres mediante una columna nueva generada de forma aleatoria y llamada export_id. En el siguiente ejemplo, se muestra cómo crear una processed_table nueva a partir de una tabla existente llamada source_table, que requiere n particiones para lograr el tamaño de archivo elegido:

   CREATE TABLE my_dataset.processed_table
   PARTITION BY RANGE_BUCKET(export_id, GENERATE_ARRAY(0, n, 1))
   CLUSTER BY export_id
   AS (
     SELECT *, CAST(FLOOR(n*RAND()) AS INT64) AS export_id
     FROM my_dataset.source_table
   );

3. Para cada número entero i entre 0 y n-1, ejecuta una declaración EXPORT DATA en la siguiente consulta:

   SELECT * EXCEPT(export_id)
   FROM my_dataset.processed_table
   WHERE export_id = i;

Extrae la tabla comprimida

Go

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go 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 Go.

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 (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// exportTableAsCompressedCSV demonstrates using an export job to
// write the contents of a table into Cloud Storage as compressed CSV.
func exportTableAsCompressedCSV(projectID, gcsURI string) error {
	// projectID := "my-project-id"
	// gcsURI := "gs://mybucket/shakespeare.csv"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %w", err)
	}
	defer client.Close()

	srcProject := "bigquery-public-data"
	srcDataset := "samples"
	srcTable := "shakespeare"

	gcsRef := bigquery.NewGCSReference(gcsURI)
	gcsRef.Compression = bigquery.Gzip

	extractor := client.DatasetInProject(srcProject, srcDataset).Table(srcTable).ExtractorTo(gcsRef)
	extractor.DisableHeader = true
	// You can choose to run the job in a specific location for more complex data locality scenarios.
	// Ex: In this example, source dataset and GCS bucket are in the US.
	extractor.Location = "US"

	job, err := extractor.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}
	if err := status.Err(); err != nil {
		return err
	}
	return nil
}

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.ExtractJobConfiguration;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.TableId;

// Sample to extract a compressed table
public class ExtractTableCompressed {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String projectName = "MY_PROJECT_NAME";
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String bucketName = "MY-BUCKET-NAME";
    String destinationUri = "gs://" + bucketName + "/path/to/file";
    // For more information on export formats available see:
    // https://cloud.google.com/bigquery/docs/exporting-data#export_formats_and_compression_types
    String compressed = "gzip";
    // For more information on Job see:
    // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
    String dataFormat = "CSV";

    extractTableCompressed(
        projectName, datasetName, tableName, destinationUri, dataFormat, compressed);
  }

  public static void extractTableCompressed(
      String projectName,
      String datasetName,
      String tableName,
      String destinationUri,
      String dataFormat,
      String compressed) {
    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(projectName, datasetName, tableName);

      ExtractJobConfiguration extractConfig =
          ExtractJobConfiguration.newBuilder(tableId, destinationUri)
              .setCompression(compressed)
              .setFormat(dataFormat)
              .build();

      Job job = bigquery.create(JobInfo.of(extractConfig));

      // Blocks until this job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to extract due to an error: \n" + job.getStatus().getError());
        return;
      }
      System.out.println("Table extract compressed successful");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

Antes de probar este ejemplo, sigue las instrucciones de configuración para Node.js 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 Node.js.

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 the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

const bigquery = new BigQuery();
const storage = new Storage();

async function extractTableCompressed() {
  // Exports my_dataset:my_table to gcs://my-bucket/my-file as a compressed file.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";
  // const bucketName = "my-bucket";
  // const filename = "file.csv";

  // Location must match that of the source table.
  const options = {
    location: 'US',
    gzip: true,
  };

  // Export data from the table into a Google Cloud Storage file
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .extract(storage.bucket(bucketName).file(filename), options);

  console.log(`Job ${job.id} created.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python 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 Python.

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.

# from google.cloud import bigquery
# client = bigquery.Client()
# bucket_name = 'my-bucket'

destination_uri = "gs://{}/{}".format(bucket_name, "shakespeare.csv.gz")
dataset_ref = bigquery.DatasetReference(project, dataset_id)
table_ref = dataset_ref.table("shakespeare")
job_config = bigquery.job.ExtractJobConfig()
job_config.compression = bigquery.Compression.GZIP

extract_job = client.extract_table(
    table_ref,
    destination_uri,
    # Location must match that of the source table.
    location="US",
    job_config=job_config,
)  # API request
extract_job.result()  # Waits for job to complete.

Exporta metadatos de tablas

Para exportar metadatos de una tabla administrada de BigLake, usa la siguiente instrucción de SQL:

EXPORT TABLE METADATA FROM `[[PROJECT_NAME.]DATASET_NAME.]TABLE_NAME`;

Reemplaza lo siguiente:

• PROJECT_NAME es el nombre del proyecto para la tabla. El valor predeterminado es el proyecto que ejecuta esta consulta de DDL.
• DATASET_NAME es el nombre del conjunto de datos de la tabla.
• TABLE_NAME: Es el nombre de la tabla.

Los metadatos exportados se encuentran en la carpeta STORAGE_URI/metadata, en la que STORAGE_URI es la ubicación de almacenamiento de la tabla establecida en las opciones.

Ejemplo de caso de uso

En este ejemplo, se muestra cómo puedes exportar datos a Cloud Storage.

Supongamos que transmites datos a Cloud Storage desde registros de extremos de forma continua. Se exporta una instantánea diaria a Cloud Storage para crear copias de seguridad y archivar datos. La mejor opción es un trabajo de extracción sujeto a ciertas cuotas y limitaciones.

Envía un trabajo de extracción con la API o las bibliotecas cliente y pasa un ID único como jobReference.jobId. Los trabajos de extracción son asíncronos. Verifica el estado del trabajo con el ID de trabajo único que se usó para crear el trabajo. El trabajo se completó de forma correcta si status.status es DONE. Si status.errorResult está presente, el trabajo falló y se debe reintentar.

Procesamiento de datos por lotes

Supongamos que se usa un trabajo nocturno por lotes para cargar datos con un plazo fijo. Después de que se completa este trabajo de carga, se crea una tabla con estadísticas a partir de una consulta, como se describe en la sección anterior. Los datos de esta tabla se recuperan y compilan en un informe en formato PDF y se envían a un regulador.

Dado que la cantidad de datos que se deben leer es pequeña, usa la API de tabledata.list para recuperar todas las filas de la tabla en formato de diccionario JSON. Si hay más de una página de datos, los resultados tendrán la propiedad pageToken establecida. Para recuperar la página siguiente de resultados, haz otra llamada a tabledata.list e incluye el valor del token como el parámetro pageToken. Si la llamada a la API falla con un error 5xx , vuelve a intentarlo con retirada exponencial. La mayoría de los errores 4xx no se pueden reintentar. Para separar mejor la exportación de BigQuery y la generación de informes, los resultados se deben conservar en el disco.

Política de cuotas

Para obtener información sobre las cuotas de un trabajo de exportación, consulta Trabajos de exportación en la página Cuotas y límites.

El uso de los trabajos de exportación está disponible en INFORMATION_SCHEMA. La entrada de trabajo en las tablas del sistema JOBS_BY_* para el trabajo de exportación contendrá un valor total_processed_bytes que se puede usar para supervisar el uso total a fin de garantizar que se mantenga por debajo de los 50 TiB por día. Si deseas aprender a consultar la vista INFORMATION_SCHEMA.JOBS para obtener el valor total_processed_bytes, consulta Obtén bytes procesados por trabajos de exportación.

Visualiza el uso actual de la cuota

Puedes ver el uso actual de los trabajos de consulta, carga, extracción o copia mediante la ejecución de una consulta INFORMATION_SCHEMA para ver los metadatos sobre los trabajos que se ejecutaron durante un período específico. Puedes comparar el uso actual con el límite de cuota a fin de determinar el uso de la cuota para un tipo de trabajo en particular. La siguiente consulta de ejemplo usa la vista INFORMATION_SCHEMA.JOBS para enumerar la cantidad de trabajos de consulta, carga, extracción y copia por proyecto:

SELECT
  sum(case  when job_type="QUERY" then 1 else 0 end) as QRY_CNT,
  sum(case  when job_type="LOAD" then 1 else 0 end) as LOAD_CNT,
  sum(case  when job_type="EXTRACT" then 1 else 0 end) as EXT_CNT,
  sum(case  when job_type="COPY" then 1 else 0 end) as CPY_CNT
FROM `region-eu`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Puedes configurar una política de alertas de Cloud Monitoring que proporcione una notificación de la cantidad de bytes exportados.

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

   Ir a Monitoring

2. En el panel de navegación, selecciona Explorador de métricas.

3. En el editor de consultas MQL, configura una alerta para supervisar los bytes exportados por día, como se ve en el siguiente ejemplo:

   fetch consumer_quota
     | filter resource.service == 'bigquery.googleapis.com'
     | { metric serviceruntime.googleapis.com/quota/rate/net_usage
         | align delta_gauge(1m)
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sum(value.net_usage)
       ; metric serviceruntime.googleapis.com/quota/limit
         | filter metric.limit_name == 'ExtractBytesPerDay'
         | group_by [resource.project_id, metric.quota_metric, resource.location],
             sliding(1m), max(val()) }
     | ratio
     | every 1m
     | condition gt(val(), 0.01 '1')
   

4. Para configurar tu alerta, haz clic en Ejecutar consulta.

Para obtener más información, consulta Políticas de alertas con MQL.

Soluciona problemas

Para diagnosticar problemas con los trabajos de extracción, puedes usar el Explorador de registros para revisar los registros de un trabajo de extracción específico y, luego, identificar posibles errores. El siguiente filtro del Explorador de registros muestra información sobre tus trabajos de extracción:

resource.type="bigquery_resource"
protoPayload.methodName="jobservice.insert"
(protoPayload.serviceData.jobInsertRequest.resource.jobConfiguration.query.query=~"EXPORT" OR
protoPayload.serviceData.jobCompletedEvent.eventName="extract_job_completed" OR
protoPayload.serviceData.jobCompletedEvent.job.jobConfiguration.query.query=~"EXPORT")

Precios

Para obtener información sobre los precios de la exportación de datos, consulta la página Precios de BigQuery.

Una vez que se exportan los datos, se te cobra por almacenarlos en Cloud Storage. Para obtener más información, consulta los Precios de Cloud Storage.

Seguridad de las tablas

Para controlar el acceso a las tablas en BigQuery, consulta Introducción a los controles de acceso a tablas.

¿Qué sigue?

• Para obtener más información sobre la consola de Google Cloud, consulta Usa la consola de Google Cloud.
• Para obtener más información sobre la herramienta de línea de comandos de bq, consulta Usa la herramienta de línea de comandos de bq.
• Para obtener información sobre cómo crear una aplicación con las bibliotecas cliente de la API de BigQuery, consulta Guía de inicio rápido: usa bibliotecas cliente.