Exportar datos de tablas a Cloud Storage

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

Una vez que haya cargado sus datos en BigQuery, podrá exportarlos en varios formatos. BigQuery puede exportar hasta 1 GB de datos lógicos a un solo archivo. Si vas a exportar más de 1 GB de datos, debes hacerlo a varios archivos. Cuando exportas tus datos a varios archivos, el tamaño de los archivos varía.

También puedes exportar los resultados de una consulta mediante la instrucción EXPORT DATA. Puedes usar EXPORT DATA OPTIONS para especificar el formato de los datos exportados.

Por último, puedes usar un servicio como Dataflow para leer datos de BigQuery en lugar de exportarlos de BigLake. Para obtener más información sobre cómo usar Dataflow para leer y escribir en BigQuery, consulta la documentación de E/S de BigQuery.

Limitaciones de exportación

Cuando exporte datos de BigQuery, tenga en cuenta lo siguiente:

Precaución: Si vas a exportar datos a un segmento de Cloud Storage, te recomendamos encarecidamente que inhabilites las políticas de conservación Bloqueo de segmento y Eliminación suave en tu segmento. Cuando exporta datos a un segmento con estas políticas de conservación, BigQuery intenta reescribir los archivos en el segmento, lo que puede fallar si la política de conservación del segmento impide que se sobrescriba un archivo, lo que genera cargos adicionales. Puedes volver a habilitar estas políticas una vez que se haya completado la exportación.

• No puedes exportar datos de tablas a un archivo local, a Hojas de cálculo de Google ni a Google Drive. La única ubicación de exportación admitida es Cloud Storage. Para obtener información sobre cómo guardar los resultados de las consultas, consulta el artículo Descargar y guardar resultados de consultas.
• Puede exportar hasta 1 GB de datos de tamaño de tabla lógica a un solo archivo. Si vas a exportar más de 1 GB de datos, usa un comodín para exportar los datos en varios archivos. Cuando exportas datos a varios archivos, el tamaño de los archivos varía. Para limitar el tamaño del archivo exportado, puedes dividir los datos en particiones y exportar cada partición.
• No se garantiza el tamaño del archivo generado al usar la instrucción EXPORT DATA.
• El número de archivos generados por una tarea de exportación puede variar.
• No puedes exportar datos anidados y repetidos en formato CSV. Se admiten datos anidados y repetidos en las exportaciones de Avro, JSON y Parquet.
• Cuando exportas datos en formato JSON, los tipos de datos INT64 (números enteros) se codifican como cadenas JSON para conservar la precisión de 64 bits cuando otros sistemas leen los datos.
• No puede exportar datos de varias tablas en un solo trabajo de exportación.
• No puedes elegir un tipo de compresión que no sea GZIP cuando exportes datos con la consola Google Cloud .
• Cuando exportas una tabla en formato JSON, los símbolos <, > y & se convierten mediante la notación Unicode \uNNNN, donde 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.
• No se garantiza el orden de los datos de la tabla exportada a menos que uses la instrucció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 barra doble inicial. Los nombres de los objetos de Cloud Storage pueden contener varias barras (/) consecutivas. Sin embargo, BigQuery convierte varias barras consecutivas en una sola barra. Por ejemplo, la siguiente ruta de recurso, 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 esté ejecutando una tarea de exportación no se incluirán en esa tarea. Para exportar los datos nuevos, debes crear un nuevo trabajo de exportación.

Antes de empezar

Concede roles de gestión de identidades y accesos (IAM) que proporcionen a los usuarios los permisos necesarios para realizar cada tarea de este documento.

Permisos obligatorios

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

Permisos para exportar datos de una tabla de BigQuery

Para exportar datos de una tabla de BigQuery, necesitas el permiso de gestión de identidades y accesos bigquery.tables.export.

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos incluye el permiso bigquery.tables.export:

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

Permisos para ejecutar una tarea de exportación

Para ejecutar una tarea de exportación, necesitas el permiso de gestión de identidades y accesos bigquery.jobs.create.

Cada uno de los siguientes roles de gestión de identidades y accesos predefinidos 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 segmento de Cloud Storage

Para escribir los datos en un segmento de Cloud Storage, necesita los siguientes permisos de gestión de identidades y accesos:

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

Cada uno de los siguientes roles predefinidos de gestión de identidades y accesos incluye los permisos que necesitas para escribir los datos en un bucket de Cloud Storage:

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

Para obtener más información sobre los roles y permisos de gestión de identidades y accesos en BigQuery, consulta el artículo sobre roles y permisos predefinidos.

Formatos de exportación y tipos de compresión

BigQuery admite los siguientes formatos de datos y tipos de compresión para los datos exportados.

Formato de datos	Tipos de compresión admitidos	Detalles
CSV	GZIP	Puedes controlar el delimitador CSV de los datos exportados con la marca --field_delimiter de la herramienta de línea de comandos bq o con la propiedad configuration.extract.fieldDelimiter de la tarea de extracción. No se admiten datos anidados ni repetidos.
JSON	GZIP	Se admiten datos anidados y repetidos.
Avro	DEFLATE, SNAPPY	GZIP no se admite en las exportaciones de Avro. Se admiten datos anidados y repetidos. Consulta los detalles de la exportación a Avro.
Parquet	SNAPPY, GZIP y ZSTD	Se admiten datos anidados y repetidos. Consulta los detalles de la exportación de Parquet.

Exportar datos

En las siguientes secciones se explica cómo exportar los datos de una tabla, los metadatos de una tabla y los resultados de una consulta a Cloud Storage.

Exportar datos de una tabla

Para exportar los datos de una tabla, puedes hacer lo siguiente:

• Usar la Google Cloud consola
• Usar el comando bq extract en la herramienta de línea de comandos bq
• Enviar un trabajo extract mediante la API o las bibliotecas de cliente

Selecciona una de las opciones siguientes:

Consola

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

   Ir a la página de BigQuery

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

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

4. En el cuadro de diálogo Exportar a Google Cloud Storage, haz lo siguiente:

   • En Ubicación de GCS, busque el bucket, la carpeta o el archivo al que quiera exportar los datos.
   • En Formato de exportación, elige 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 None para no aplicar compresión.

5. Haz clic en Guardar para exportar la tabla.

Para comprobar el progreso del trabajo, despliega el panel Historial de trabajos y busca el trabajo de tipo EXTRACT.

Para exportar vistas a Cloud Storage, usa la instrucción EXPORT DATA OPTIONS.

SQL

Usa la instrucción EXPORT DATA. En el siguiente ejemplo se exportan campos seleccionados de una tabla llamada mydataset.table1:

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

   Ir a BigQuery

2. En el editor de consultas, introduce la siguiente instrucción:

   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.

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

bq

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

(Opcional) Proporcione la marca --location y asigne el valor a su ubicación.

Otras marcas opcionales son:

• --compression: el tipo de compresión que se usará en los archivos exportados.
• --field_delimiter: el carácter que indica el límite entre las columnas del archivo de salida de las exportaciones CSV. Se permiten tanto \t como tab para los 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

Donde:

• 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 asignar el valor asia-northeast1 a la marca. Puedes definir un valor predeterminado para la ubicación mediante 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 con el formato de tus datos. Consulta Formatos de exportación y tipos de compresión.
• delimiter es el carácter que indica el límite entre las columnas de las exportaciones de CSV. \t y tab son nombres aceptados para la pestaña.
• boolean es true o false. Si se define como true, las filas de 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 vas a exportar. Si usas un decorador de partición, debes incluir la ruta de la tabla entre comillas simples o usar el carácter de escape $.
• bucket es el nombre del segmento de Cloud Storage al que vas a exportar los datos. El conjunto de datos de BigQuery y el segmento 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 mediante un carácter comodín.

Ejemplos:

Por ejemplo, el siguiente comando exporta mydataset.mytable a un archivo comprimido con gzip llamado myfile.csv. myfile.csv se almacena en un segmento 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 a JSON o Avro, usa la marca destination_format y asigna el valor 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 archivo se llama myfile.avro. myfile.avro se exporta a un segmento de Cloud Storage llamado example-bucket.

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

El siguiente comando 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 extract y rellena su configuración.

Nota: Si va a exportar datos al formato Parquet, puede que sea más rápido usar la plantilla de exportación de BigQuery a Parquet (mediante la API Storage de BigQuery) que escribir una solución personalizada.

(Opcional) Especifica tu ubicación en la propiedad location de la sección jobReference del recurso Job.

1. Crea una tarea de extracción que apunte 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 completa y tener el formato gs://bucket/filename.ext. Cada URI puede contener un comodín "*" y debe ir después del nombre del contenedor.

4. Especifica el formato de los datos definiendo la propiedad configuration.extract.destinationFormat. Por ejemplo, para exportar un archivo JSON, asigna a esta propiedad el valor NEWLINE_DELIMITED_JSON.

5. Para comprobar el estado de la tarea, llama a jobs.get(job_id) con el ID de la tarea devuelto por la solicitud inicial.

   • Si status.state = DONE, el trabajo se ha completado correctamente.
   • Si la propiedad status.errorResult está presente, significa que se ha producido un error en la solicitud y que el objeto incluirá información que describe lo que ha fallado.
   • Si no aparece status.errorResult, significa que el trabajo se ha completado correctamente, aunque puede que se hayan producido algunos errores no fatales. Los errores no fatales se indican en la propiedad status.errors del objeto de trabajo devuelto.

Notas sobre la API:

• Como práctica recomendada, genera un ID único y pásalo como jobReference.jobId al llamar a jobs.insert para crear un trabajo. Este enfoque es más sólido ante fallos de red, ya que el cliente puede sondear o volver a intentar la operación con el ID de trabajo conocido.

• Llamar a jobs.insert en un ID de tarea determinado es idempotente. En otras palabras, puedes volver a intentarlo tantas veces como quieras en el mismo ID de tarea y, como mucho, una de esas operaciones se completará correctamente.

C#

Antes de probar este ejemplo, sigue las C#instrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API C# de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 PHPinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API PHP de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Rubyinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Ruby de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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

Exportar metadatos de una tabla

Para exportar metadatos de tablas Iceberg, usa la siguiente instrucción SQL:

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

Haz los cambios siguientes:

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

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

Exportar resultados de consultas

Puedes exportar los resultados de tus consultas a Cloud Storage en la Google Cloud consola siguiendo estos pasos:

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

   Ir a la página de BigQuery

2. Haz clic en Consulta de SQL.

3. Introduce una consulta de GoogleSQL válida en el área de texto Editor de consultas.

4. Haz clic en Ejecutar.

5. Cuando se devuelvan los resultados, haz clic en Guardar resultados > Cloud Storage.

6. En el cuadro de diálogo Exportar a Google Cloud Storage, haz lo siguiente:

   • En Ubicación de GCS, busque el bucket, la carpeta o el archivo al que quiera exportar los datos.
   • En Formato de exportación, elige 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 None para no aplicar compresión.

7. Haz clic en Guardar para exportar los resultados de la consulta.

Para comprobar el progreso del trabajo, despliega el panel Historial de trabajos y busca el trabajo de tipo EXTRACT.

Detalles de la exportación a Avro

BigQuery expresa los datos con formato Avro de las siguientes formas:

• 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 mediante objetos de registro anidados.
• Los campos REQUIRED se representan como los tipos Avro correspondientes. Por ejemplo, un tipo INTEGER de BigQuery se asigna a un tipo LONG de Avro.
• Los campos NULLABLE se representan como una unión de Avro del tipo correspondiente y "null".
• Los campos REPEATED se representan como matrices Avro.
• Los tipos de datos TIMESTAMP se representan como tipos lógicos timestamp-micros (anota un tipo LONG de Avro) de forma predeterminada tanto en las tareas de extracción como en el SQL de exportación de datos. Precaución: puedes añadir use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico y que se use el tipo string en su lugar en la columna de marca de tiempo, pero en los trabajos de extracción siempre se usa el tipo lógico Avro.
• Los tipos de datos DATE se representan como el tipo lógico date (anota los tipos de INT de Avro) de forma predeterminada en Export Data SQL, pero se representan como el tipo string de forma predeterminada en los trabajos Extract. Nota: Puedes añadir use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True para habilitar el tipo lógico en los trabajos Extract.
• Los tipos de datos TIME se representan como tipo lógico timestamp-micro (anota tipos LONG de Avro) de forma predeterminada en Export Data SQL, pero se representan como tipo string de forma predeterminada en los trabajos de extracción. Nota: Puedes añadir use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True para habilitar el tipo lógico en los trabajos de extracción.
• Los tipos de datos DATETIME se representan como tipos STRING de Avro (un tipo de cadena con el tipo lógico personalizado datetime) de forma predeterminada en Export Data SQL, pero se representan como tipo string de forma predeterminada en las tareas de extracción. Nota: Puedes añadir use_avro_logical_types=False a Export Data Options para inhabilitar el tipo lógico o usar la marca --use_avro_logical_types=True para habilitar el tipo lógico en los trabajos de extracción.
• Los tipos RANGE no se admiten en la exportación de Avro.

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

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

Precaución:

• Si exportas un tipo DATETIME a Avro, no podrás volver a cargar el archivo Avro directamente en el mismo esquema de tabla, ya que el tipo STRING convertido no coincidirá con el esquema. Como solución alternativa, carga el archivo en una tabla de almacenamiento temporal. A continuación, usa una consulta de SQL para convertir el campo al tipo DATETIME y guarda el resultado en una tabla nueva. Para obtener más información, consulta Cambiar el tipo de datos de una columna .
• La opción Exportar datos use_avro_logical_types y la marca de tarea de extracción --use_avro_logical_types se aplican a todos los tipos lógicos al mismo tiempo una vez especificados.

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 bq o la API y especifica uno de los tipos de compresión admitidos para datos Avro: DEFLATE o SNAPPY.

Detalles de la 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 primitivo 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)
Coma flotante	FLOAT	NONE
Booleano	BOOLEAN	NONE
Cadena	BYTE_ARRAY	STRING (UTF8)
Bytes	BYTE_ARRAY	NONE
Fecha	INT32	DATE
Fecha y hora	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Hora	INT64	TIME (isAdjustedToUTC = true, unit = MICROS)
Marca de tiempo	INT64	TIMESTAMP (isAdjustedToUTC = false, unit = MICROS)
Geografía	BYTE_ARRAY	GEOGRAPHY (edges = spherical)

El esquema de Parquet representa los datos anidados como un grupo y los registros repetidos como grupos repetidos. Para obtener más información sobre cómo usar datos anidados y repetidos en BigQuery, consulta el artículo sobre cómo especificar columnas anidadas y repetidas.

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

Puedes usar las siguientes soluciones alternativas para los tipos de DATETIME:

• Carga el archivo en una tabla de almacenamiento temporal. A continuación, usa una consulta de SQL para convertir el campo a DATETIME y guarda el resultado en una tabla nueva. Para obtener más información, consulta Cambiar el tipo de datos de una columna.
• Proporciona un esquema para la tabla mediante la marca --schema en la tarea de carga. Define la columna de fecha y hora como col:DATETIME.

El tipo lógico GEOGRAPHY se representa con metadatos GeoParquet añadidos a los archivos exportados.

Exportar datos a uno o varios archivos

La propiedad destinationUris indica una o varias ubicaciones y nombres de archivo en los que BigQuery debe exportar los archivos.

BigQuery admite un único operador comodín (*) en cada URI. El comodín puede aparecer en cualquier parte del componente del nombre de archivo. Al usar el operador comodín, se indica a BigQuery que cree varios archivos fragmentados basados en el patrón proporcionado. El operador comodín se sustituye por un número (empezando por 0) que se rellena con ceros a la izquierda hasta tener 12 dígitos. Por ejemplo, un URI con un comodín al final del nombre de archivo crearía archivos con 000000000000 añadido al primer archivo y 000000000001 añadido al segundo, y así sucesivamente.

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 datos de tabla de 1 GB o menos. Esta opción es la más habitual, ya que los datos exportados suelen ser inferiores al valor máximo de 1 GB. Esta opción no se admite en la declaración EXPORT DATA. Debes usar un único URI con comodín. Definición de la propiedad: ['gs://my-bucket/file-name.json'] Crea: gs://my-bucket/file-name.json
URI comodín único	Solo se puede usar un comodín en el componente de nombre de archivo del URI. Utilice un único URI con comodín si cree que los datos exportados superarán el valor máximo de 1 GB. BigQuery fragmenta los datos en varios archivos en función del patrón proporcionado. El tamaño de los archivos exportados variará. 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 ... ['gs://my-bucket/*'] Crea: gs://my-bucket/000000000000 gs://my-bucket/000000000001 gs://my-bucket/000000000002 ...

Limitar el tamaño del archivo exportado

Si exportas más de 1 GB de datos en una sola exportación, debes usar un comodín para exportar los datos en varios archivos. El tamaño de los archivos variará. Si necesitas limitar el tamaño máximo de cada archivo exportado, una opción es particionar tus datos de forma aleatoria y, a continuación, exportar cada partición a un archivo:

1. Determina el número de particiones que necesitas, que es igual al tamaño total de tus datos dividido por el tamaño de archivo exportado que hayas elegido. Por ejemplo, si tienes 8000 MB de datos y quieres que cada archivo exportado tenga aproximadamente 20 MB, necesitarás 400 particiones.

2. Crea una tabla con particiones y agrupada en clústeres por una nueva columna generada aleatoriamente llamada export_id. En el siguiente ejemplo se muestra cómo crear un processed_table a partir de una tabla llamada source_table, que requiere n particiones para alcanzar 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 instrucción EXPORT DATA en la siguiente consulta:

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

Extraer tabla comprimida

Go

Antes de probar este ejemplo, sigue las Goinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Go de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Javainstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Java de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Node.jsinstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Node.js de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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 Pythoninstrucciones de configuración de la guía de inicio rápido de BigQuery con bibliotecas de cliente. Para obtener más información, consulta la documentación de referencia de la API Python de BigQuery.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Para obtener más información, consulta el artículo Configurar la autenticación para bibliotecas de 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.

Caso práctico de ejemplo

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

Supongamos que estás transmitiendo datos a Cloud Storage de forma continua desde los registros de endpoints. Se debe exportar una instantánea diaria a Cloud Storage para crear copias de seguridad y archivarla. La mejor opción es una tarea de extracción, que está sujeta a determinadas cuotas y limitaciones.

Envía un trabajo de extracción con la API o las bibliotecas de cliente y transfiere un ID único como jobReference.jobId. Los trabajos de extracción son asíncronos. Consulta el estado del trabajo con el ID de trabajo único que se ha usado para crearlo. El trabajo se ha completado correctamente si status.status es DONE. Si status.errorResult está presente, el trabajo ha fallado y debe volver a intentarse.

Procesamiento de datos por lotes

Supongamos que se usa una tarea por lotes nocturna para cargar datos antes de una fecha límite fija. Una vez que se haya completado este trabajo de carga, se materializará una tabla con estadísticas a partir de una consulta, tal como se describe en la sección anterior. Los datos de esta tabla se recuperan y se compilan en un informe en PDF que se envía a un organismo regulador.

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

Política de cuotas

Para obtener información sobre las cuotas de los trabajos de exportación, consulta la sección Trabajos de exportación de la página Cuotas y límites.

El uso de las tareas de exportación está disponible en la INFORMATION_SCHEMA. La entrada de la tarea en las tablas de sistema JOBS_BY_* de la tarea de exportación contiene un valor total_bytes_processed que se puede usar para monitorizar el uso agregado y asegurarse de que no supere los 50 TiB al día. Para saber cómo consultar la vista INFORMATION_SCHEMA.JOBS para obtener el valor de total_bytes_processed, consulta el esquema de INFORMATION_SCHEMA.JOBS.

Ver la cuota de uso actual

Para ver el uso actual de las tareas de consulta, carga, extracción o copia, puedes ejecutar una INFORMATION_SCHEMA consulta para ver los metadatos de las tareas que se han ejecutado durante un periodo específico. Puedes comparar tu uso actual con el límite de cuota para determinar el uso de la cuota de un tipo de trabajo concreto. La siguiente consulta de ejemplo usa la vista INFORMATION_SCHEMA.JOBS para enumerar el número de tareas 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-REGION_NAME`.INFORMATION_SCHEMA.JOBS_BY_PROJECT
WHERE date(creation_time)= CURRENT_DATE()

Puedes configurar una política de alertas de Cloud Monitoring que monitorice el número de bytes exportados.

1. En la Google Cloud consola, ve a la página  Alertas:

   Ve a Alertas.

   Si usas la barra de búsqueda para encontrar esta página, selecciona el resultado cuya sección sea Monitorización.

2. En la página Alertas, haz clic en Crear política.

3. En Modo de configuración de la política, selecciona Editor de código (MQL o PromQL).

4. En el editor de consultas PromQL, introduce la siguiente consulta:

   (
     sum by (project_id, quota_metric, location) (increase({"serviceruntime.googleapis.com/quota/rate/net_usage", monitored_resource="consumer_quota", service="bigquery.googleapis.com"}[1m]))
     /
     max by (project_id, quota_metric, location) ({"serviceruntime.googleapis.com/quota/limit", monitored_resource="consumer_quota", service="bigquery.googleapis.com", limit_name="ExtractBytesPerDay"})
   ) > 0.01
   

   Si la opción Ejecución automática no está habilitada, haz clic en Ejecutar consulta.

5. Configura el resto de la alerta y haz clic en Crear política.

Para obtener información detallada sobre cómo crear políticas de alertas basadas en PromQL, consulta el artículo Crear políticas de alertas basadas en PromQL (consola).

Solución de problemas

Para diagnosticar problemas con los trabajos de extracción, puede usar el Explorador de registros para revisar los registros de un trabajo de extracción específico e identificar posibles errores. El siguiente filtro de Explorador de registros devuelve información sobre tus tareas 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 de 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 la página Precios de Cloud Storage.

Seguridad de las tablas

Para controlar el acceso a las tablas de BigQuery, consulta el artículo sobre cómo controlar el acceso a los recursos con la gestión de identidades y accesos.

Siguientes pasos

• Para obtener más información sobre la consola Google Cloud , consulta Usar la consola Google Cloud .
• Para obtener más información sobre la herramienta de línea de comandos bq, consulta el artículo Usar la herramienta de línea de comandos bq.
• Para saber cómo crear una aplicación con las bibliotecas de cliente de la API de BigQuery, consulta la guía de inicio rápido de la biblioteca de cliente.