Esta página se ha traducido con Cloud Translation API.

Usar la detección automática de esquemas

Detección automática de esquemas

La detección automática de esquemas permite a BigQuery inferir el esquema de los datos CSV, JSON o de Hojas de cálculo de Google. La detección automática de esquemas está disponible cuando cargas datos en BigQuery y cuando consultas una fuente de datos externa.

Cuando la detección automática está habilitada, BigQuery infiere el tipo de datos de cada columna. BigQuery selecciona un archivo aleatorio de la fuente de datos y analiza las primeras 500 filas de datos para usarlas como muestra representativa. A continuación, BigQuery examina cada campo e intenta asignarle un tipo de datos en función de los valores de la muestra. Si todas las filas de una columna están vacías, la detección automática asignará el tipo de datos STRING a la columna de forma predeterminada.

Si no habilita la detección automática de esquemas para los datos CSV, JSON o de Hojas de cálculo de Google, deberá proporcionar el esquema manualmente al crear la tabla.

No es necesario habilitar la detección automática de esquemas para los archivos Avro, Parquet, ORC, de exportación de Firestore o de exportación de Datastore. Estos formatos de archivo son autoexplicativos, por lo que BigQuery infiere automáticamente el esquema de la tabla a partir de los datos de origen. En el caso de los archivos Parquet, Avro y Orc, puedes proporcionar un esquema explícito para anular el esquema inferido.

Puedes ver el esquema detectado de una tabla de las siguientes formas:

Usa la consola Google Cloud .
Usa el comando bq show de la herramienta de línea de comandos bq.

Cuando BigQuery detecta esquemas, en raras ocasiones, puede cambiar el nombre de un campo para que sea compatible con la sintaxis de GoogleSQL.

Para obtener información sobre las conversiones de tipos de datos, consulta lo siguiente:

Conversión de tipos de datos al cargar datos de Datastore
Conversión de tipos de datos al cargar datos de Firestore
Conversiones de Avro
Conversiones de Parquet
Conversiones de ORC

Cargar datos mediante la detección automática de esquemas

Para habilitar la detección automática de esquemas al cargar datos, utiliza uno de estos métodos:

En la consola, en la sección Esquema, marca la opción Esquema y parámetros de entrada de Detectar automáticamente. Google Cloud
En la herramienta de línea de comandos bq, usa el comando bq load con el parámetro --autodetect.

Cuando la detección automática de esquemas está habilitada, BigQuery hace todo lo posible para inferir automáticamente el esquema de los archivos CSV y JSON. La lógica de detección automática deduce los tipos de campos de esquema leyendo las primeras 500 filas de datos. Las líneas iniciales se omiten si está presente la marca --skip_leading_rows. Los tipos de campos se basan en las filas que tienen más campos. Por lo tanto, la detección automática debería funcionar correctamente siempre que haya al menos una fila de datos con valores en cada columna o campo.

La detección automática de esquemas no se usa con archivos Avro, Parquet, ORC, de exportación de Firestore ni de exportación de Datastore. Cuando cargues estos archivos en BigQuery, el esquema de la tabla se obtendrá automáticamente de los datos de origen autodescriptivos.

Para usar la detección automática de esquemas al cargar datos JSON o CSV, sigue estos pasos:

Consola

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

Ir a BigQuery
En el panel Explorador, expande tu proyecto y selecciona un conjunto de datos.
Abre la opción Acciones y haz clic en Abrir.
En el panel de detalles, haz clic en Crear tabla .
En la página Crear tabla, ve a la sección Fuente:
- En Crear tabla a partir de, selecciona el tipo de fuente que quieras.
- En el campo de origen, busca el archivo o el segmento de Cloud Storage, o bien introduce el URI de Cloud Storage. Ten en cuenta que no puedes incluir varios URIs en la consola, pero sí se admiten comodines. Google Cloud El segmento de Cloud Storage debe estar en la misma ubicación que el conjunto de datos que contiene la tabla que estás creando.
- En Formato de archivo, selecciona CSV o JSON.
En la página Crear tabla, ve a la sección Destino:
- En Nombre del conjunto de datos, elige el conjunto de datos adecuado.
- En el campo Nombre de la tabla, introduce el nombre de la tabla que vas a crear.
- Verifica que el Tipo de tabla sea Tabla nativa.
Haz clic en Crear tabla.

bq

Ejecute el comando bq load con el parámetro --autodetect.

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

El siguiente comando carga un archivo mediante la detección automática del esquema:

bq --location=LOCATION load \
--autodetect \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Haz los cambios siguientes:

LOCATION: el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, asigna el valor asia-northeast1 a la marca. Puedes definir un valor predeterminado para la ubicación mediante el archivo.bigqueryrc.
FORMAT: NEWLINE_DELIMITED_JSON o CSV.
DATASET: el conjunto de datos que contiene la tabla en la que vas a cargar los datos.
TABLE: el nombre de la tabla en la que vas a cargar los datos.
PATH_TO_SOURCE: es la ubicación del archivo CSV o JSON.

Ejemplos:

Introduce el siguiente comando para cargar myfile.csv desde tu máquina local en una tabla llamada mytable que se almacena en un conjunto de datos llamado mydataset.

bq load --autodetect --source_format=CSV mydataset.mytable ./myfile.csv

Introduce el siguiente comando para cargar myfile.json desde tu máquina local en una tabla llamada mytable que se almacena en un conjunto de datos llamado mydataset.

bq load --autodetect --source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable ./myfile.json

API

Crea un load que apunte a los datos de origen. Para obtener información sobre cómo crear tareas, consulta el artículo Ejecutar tareas de BigQuery mediante programación. Especifica tu ubicación en la propiedad location de la sección jobReference.
Especifica el formato de los datos definiendo la propiedad sourceFormat. Para usar la autodetección de esquemas, este valor debe ser NEWLINE_DELIMITED_JSON o CSV.
Use la propiedad autodetect para definir la autodetección de esquemas como true.

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

// importJSONAutodetectSchema demonstrates loading data from newline-delimited JSON data in Cloud Storage
// and using schema autodetection to identify the available columns.
func importJSONAutodetectSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydataset"
	// tableID := "mytable"
	ctx := context.Background()
	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
	gcsRef.SourceFormat = bigquery.JSON
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteEmpty

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

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.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.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data with autodetect schema from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCSAutodetect {

  public static void runLoadJsonFromGCSAutodetect() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
    loadJsonFromGCSAutodetect(datasetName, tableName, sourceUri);
  }

  public static void loadJsonFromGCSAutodetect(
      String datasetName, String tableName, String sourceUri) {
    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(datasetName, tableName);
      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.json())
              .setAutodetect(true)
              .build();

      // Load data from a GCS JSON file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone()) {
        System.out.println("Json Autodetect from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \n" + e.toString());
    }
  }
}

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.CsvOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;

// Sample to load CSV data with autodetect schema from Cloud Storage into a new BigQuery table
public class LoadCsvFromGcsAutodetect {

  public static void main(String[] args) {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.csv";
    loadCsvFromGcsAutodetect(datasetName, tableName, sourceUri);
  }

  public static void loadCsvFromGcsAutodetect(
      String datasetName, String tableName, String sourceUri) {
    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(datasetName, tableName);

      // Skip header row in the file.
      CsvOptions csvOptions = CsvOptions.newBuilder().setSkipLeadingRows(1).build();

      LoadJobConfiguration loadConfig =
          LoadJobConfiguration.newBuilder(tableId, sourceUri)
              .setFormatOptions(csvOptions)
              .setAutodetect(true)
              .build();

      // Load data from a GCS CSV file into the table
      Job job = bigquery.create(JobInfo.of(loadConfig));
      // Blocks until this load table job completes its execution, either failing or succeeding.
      job = job.waitFor();
      if (job.isDone() && job.getStatus().getError() == null) {
        System.out.println("CSV Autodetect from GCS successfully loaded in a table");
      } else {
        System.out.println(
            "BigQuery was unable to load into the table due to an error:"
                + job.getStatus().getError());
      }
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Column not added during load append \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.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

/**
 * TODO(developer): Uncomment the following lines before running the sample.
 */
// const datasetId = "my_dataset";
// const tableId = "my_table";

/**
 * This sample loads the JSON file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.json
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.json';

async function loadJSONFromGCSAutodetect() {
  // Imports a GCS file into a table with autodetected schema.

  // Instantiate clients
  const bigquery = new BigQuery();
  const storage = new Storage();

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'NEWLINE_DELIMITED_JSON',
    autodetect: true,
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

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

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.

use Google\Cloud\BigQuery\BigQueryClient;

/**
 * Imports data to the given table from json file present in GCS by auto
 * detecting options and schema.
 *
 * @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.
 */
function import_from_storage_json_autodetect(
    string $projectId,
    string $datasetId,
    string $tableId = 'us_states'
): void {
    // instantiate the bigquery table service
    $bigQuery = new BigQueryClient([
      'projectId' => $projectId,
    ]);
    $dataset = $bigQuery->dataset($datasetId);
    $table = $dataset->table($tableId);

    // create the import job
    $gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.json';
    $loadConfig = $table->loadFromStorage($gcsUri)->autodetect(true)->sourceFormat('NEWLINE_DELIMITED_JSON');
    $job = $table->runJob($loadConfig);

    // check if the job is complete
    $job->reload();
    if (!$job->isComplete()) {
        throw new \Exception('Job has not yet completed', 500);
    }
    // check if the job has errors
    if (isset($job->info()['status']['errorResult'])) {
        $error = $job->info()['status']['errorResult']['message'];
        printf('Error running job: %s' . PHP_EOL, $error);
    } else {
        print('Data imported successfully' . PHP_EOL);
    }
}

Python

Para habilitar la detección automática de esquemas, asigna el valor True a la propiedad LoadJobConfig.autodetect.

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.

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

# Set the encryption key to use for the destination.
# TODO: Replace this key with a key you have created in KMS.
# kms_key_name = "projects/{}/locations/{}/keyRings/{}/cryptoKeys/{}".format(
#     "cloud-samples-tests", "us", "test", "test"
# )
job_config = bigquery.LoadJobConfig(
    autodetect=True, source_format=bigquery.SourceFormat.NEWLINE_DELIMITED_JSON
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.
load_job.result()  # Waits for the job to complete.
destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

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.

require "google/cloud/bigquery"

def load_table_gcs_json_autodetect dataset_id = "your_dataset_id"
  bigquery = Google::Cloud::Bigquery.new
  dataset  = bigquery.dataset dataset_id
  gcs_uri  = "gs://cloud-samples-data/bigquery/us-states/us-states.json"
  table_id = "us_states"

  load_job = dataset.load_job table_id,
                              gcs_uri,
                              format:     "json",
                              autodetect: true
  puts "Starting job #{load_job.job_id}"

  load_job.wait_until_done! # Waits for table load to complete.
  puts "Job finished."

  table = dataset.table table_id
  puts "Loaded #{table.rows_count} rows to table #{table.id}"
end

Detección automática de esquemas para fuentes de datos externas

La detección automática de esquemas se puede usar con fuentes de datos externas de CSV, JSON y Hojas de cálculo de Google. Cuando la detección automática de esquemas está habilitada, BigQuery hace todo lo posible para inferir automáticamente el esquema de los datos de origen. Si no habilitas la detección automática de esquemas para estas fuentes, debes proporcionar un esquema explícito.

No es necesario habilitar la detección automática de esquemas cuando consultas archivos externos Avro, Parquet, ORC, de exportación de Firestore o de exportación de Datastore. Estos formatos de archivo se describen automáticamente, por lo que BigQuery infiere automáticamente el esquema de la tabla a partir de los datos de origen. En el caso de los archivos Parquet, Avro y Orc, puede proporcionar un esquema explícito para anular el esquema inferido.

En la Google Cloud consola, puedes habilitar la detección automática de esquemas marcando la opción Esquema y parámetros de entrada en Detectar automáticamente.

Con la herramienta de línea de comandos bq, puedes habilitar la detección automática de esquemas cuando crees un archivo de definición de tabla para datos CSV, JSON u Hojas de cálculo de Google. Cuando uses la herramienta bq para crear un archivo de definición de tabla, pasa la marca --autodetect al comando mkdef para habilitar la detección automática del esquema o pasa la marca --noautodetect para inhabilitar la detección automática.

Cuando usas la marca --autodetect, el ajuste autodetect se define como true en el archivo de definición de tabla. Si usas la marca --noautodetect, el ajuste autodetect se define como false. Si no proporcionas una definición de esquema para la fuente de datos externa al crear una definición de tabla y no usas las marcas --noautodetect o --autodetect, el valor predeterminado de autodetect será true.

Cuando crees un archivo de definición de tabla mediante la API, asigna el valor true o false a la propiedad autodetect. Si se asigna el valor true a autodetect, se habilita la detección automática. Si se asigna el valor false a autodetect, se inhabilita la detección automática.

Detalles de la detección automática

Además de detectar los detalles del esquema, la detección automática reconoce lo siguiente:

Compresión

BigQuery reconoce la compresión de archivos compatible con gzip al abrir un archivo.

Valores de fecha y hora

BigQuery detecta los valores de fecha y hora en función del formato de los datos de origen.

Los valores de las columnas DATE deben tener el siguiente formato: YYYY-MM-DD.

Los valores de las columnas TIME deben tener el siguiente formato: HH:MM:SS[.SSSSSS] (el componente de los segundos fraccionarios es opcional).

En el caso de las columnas TIMESTAMP, BigQuery detecta una gran variedad de formatos de marca de tiempo, entre los que se incluyen los siguientes:

YYYY-MM-DD HH:MM
YYYY-MM-DD HH:MM:SS
YYYY-MM-DD HH:MM:SS.SSSSSS
YYYY/MM/DD HH:MM

Una marca de tiempo también puede contener un desfase con respecto a UTC o el designador de zona UTC ("Z").

Estos son algunos ejemplos de valores que BigQuery detectará automáticamente como valores de marca de tiempo:

2018-08-19 12:11
2018-08-19 12:11:35.22
2018/08/19 12:11
2018-08-19 07:11:35.220 -05:00

Si la detección automática no está habilitada y el valor tiene un formato que no aparece en los ejemplos anteriores, BigQuery solo puede cargar la columna como un tipo de datos STRING. Puedes habilitar la detección automática para que BigQuery reconozca estas columnas como marcas de tiempo. Por ejemplo, BigQuery solo cargará 2025-06-16T16:55:22Z como marca de tiempo si habilitas la detección automática.

También puede preprocesar los datos de origen antes de cargarlos. Por ejemplo, si exporta datos CSV de una hoja de cálculo, defina el formato de fecha para que coincida con uno de los ejemplos que se muestran aquí. También puedes transformar los datos después de cargarlos en BigQuery.

Detección automática de esquemas para datos CSV

Delimitador de CSV

BigQuery detecta los siguientes delimitadores:

coma ( , )
barra vertical ( | )
tabulador ( \t)

Encabezado del CSV

BigQuery infiere los encabezados comparando la primera fila del archivo con otras filas del mismo archivo. Si la primera línea solo contiene cadenas y las demás líneas contienen otros tipos de datos, BigQuery asume que la primera fila es una fila de encabezado. BigQuery asigna nombres de columna en función de los nombres de campo de la fila de encabezado. Es posible que los nombres se modifiquen para cumplir las reglas de nomenclatura de las columnas de BigQuery. Por ejemplo, los espacios se sustituirán por guiones bajos.

De lo contrario, BigQuery asumirá que la primera fila es una fila de datos y asignará nombres de columna genéricos, como string_field_1. Ten en cuenta que, una vez creada una tabla, los nombres de las columnas no se pueden actualizar en el esquema, aunque puedes cambiar los nombres manualmente después de crear la tabla. Otra opción es proporcionar un esquema explícito en lugar de usar la detección automática.

Puede que tengas un archivo CSV con una fila de encabezado en la que todos los campos de datos sean cadenas. En ese caso, BigQuery no detectará automáticamente que la primera fila es un encabezado. Usa la opción --skip_leading_rows para omitir la fila de encabezado. De lo contrario, el encabezado se importará como datos. También puedes proporcionar un esquema explícito en este caso para asignar nombres de columna.

Saltos de línea entre comillas en archivos CSV

BigQuery detecta los caracteres de nueva línea entre comillas en un campo CSV y no los interpreta como límites de filas.

Detección automática de esquemas para datos JSON

Campos anidados y repetidos de JSON

BigQuery infiere los campos anidados y repetidos de los archivos JSON. Si el valor de un campo es un objeto JSON, BigQuery carga la columna como un tipo RECORD. Si el valor de un campo es una matriz, BigQuery carga la columna como una columna repetida. Para ver un ejemplo de datos JSON con datos anidados y repetidos, consulta Cargar datos JSON anidados y repetidos.

Conversión de cadenas

Si habilitas la detección automática de esquemas, BigQuery convierte las cadenas en tipos booleanos, numéricos o de fecha y hora cuando sea posible. Por ejemplo, con los siguientes datos JSON, la detección automática del esquema convierte el campo id en una columna INTEGER:

{ "name":"Alice","id":"12"}
{ "name":"Bob","id":"34"}
{ "name":"Charles","id":"45"}

Para obtener más información, consulta Cargar datos JSON desde Cloud Storage.

Detección automática de esquemas en Hojas de cálculo de Google

En Hojas de cálculo, BigQuery detecta automáticamente si la primera fila es una fila de encabezado, de forma similar a la detección automática de archivos CSV. Si la primera línea se identifica como encabezado, BigQuery asigna nombres de columna en función de los nombres de campo de la fila de encabezado y omite la fila. Los nombres pueden modificarse para cumplir las reglas de nomenclatura de las columnas de BigQuery. Por ejemplo, los espacios se sustituirán por guiones bajos.

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.