Especifica un esquema

BigQuery te permite especificar el esquema de una tabla cuando cargas datos en una tabla y cuando creas una tabla vacía. Como alternativa, puedes usar la detección automática de esquemas para los formatos de datos compatibles. Cuando se cargan archivos de exportación de Avro, Parquet, ORC, Cloud Firestore o archivos de exportación de Cloud Datastore, el esquema se deduce de los datos.

Se puede especificar el esquema de una tabla de una de las siguientes maneras:

  • Especifica el esquema de forma manual:
    • Usa la IU web de BigQuery.
    • Intercala mediante la CLI.
  • Crea un archivo de esquema en formato JSON.
  • Llama al método jobs.insert y configura la propiedad configuration.load.schema.
  • Llama al método tables.insert y configura el esquema en el recurso de tabla mediante la propiedad schema.

Después de cargar datos o crear una tabla vacía, puedes modificar la definición de esquema de la tabla.

Componentes de esquema

Cuando especificas un esquema de tabla, debes proporcionar el nombre y el tipo de datos de cada columna. De manera opcional, puedes proporcionar la descripción y el modo de una columna.

Nombres de columnas

El nombre de una columna solo debe contener letras (a-z, A-Z), números (0-9) o guiones bajos (_), y debe comenzar con una letra o guion bajo. La longitud máxima del nombre de la columna es de 128 caracteres. El nombre de una columna no puede usar ninguno de los siguientes prefijos:

  • _TABLE_
  • _FILE_
  • _PARTITION

No se permiten nombres de columna duplicados, incluso si el mismo nombre está escrito en mayúscula o minúscula. Por ejemplo, una columna llamada Column1 se considera idéntica a una columna con el nombre column1.

Descripciones de columnas

Cada columna puede incluir una descripción opcional. La descripción es una string con una longitud máxima de 1,024 caracteres.

Tipos de datos de SQL estándar

SQL estándar de BigQuery te permite especificar los siguientes tipos de datos en tu esquema. El tipo de datos es obligatorio.

Tipo de datos Descripción
Número entero Valores numéricos sin componentes fraccionales
Punto flotante Valores numéricos aproximados con componentes fraccionales
Numérico Valores numéricos exactos con componentes fraccionales
Booleano TRUE o FALSE (distinción entre mayúsculas y minúsculas)
String Datos de caracteres de longitud variable (Unicode)
Bytes Datos binarios de longitud variable
Fecha Fecha del calendario lógica
Fecha y hora Año, mes, día, hora, minuto, segundo y tiempo menor que un segundo
Hora Hora, independiente de una fecha específica
Marca de tiempo Momento determinado absoluto con precisión de microsegundos
Estructura (registro) Contenedor de campos ordenados, cada uno con un tipo (obligatorio) y un nombre de campo (opcional)
Datos geográficos Un conjunto de puntos en la superficie de la Tierra (un conjunto de puntos, líneas y polígonos en el esferoide de referencia WGS84 con bordes geodésicos)

Para obtener más información sobre los tipos de datos en SQL estándar, consulta Tipos de datos de SQL estándar.

También puedes declarar un tipo de arreglo cuando consultas datos. Para obtener más información, consulta Cómo trabajar con arreglos.

Modos

BigQuery admite los siguientes modos para tus columnas. El modo es opcional. Si no se especifica el modo, la columna predeterminada es NULLABLE.

Modo Descripción
Acepta valor NULL La columna permite valores NULL (predeterminado)
Obligatorio No se permiten valores NULL
Repetido La columna contiene un arreglo de valores del tipo especificado

Para obtener más información sobre los modos, consulta schema.fields.mode en la referencia de API.

Cómo especificar esquemas de forma manual

Cuando cargas datos o creas una tabla vacía, puedes especificar el esquema de la tabla de forma manual mediante la IU web de BigQuery o la herramienta de línea de comandos. La especificación manual de un esquema se admite cuando se cargan archivos CSV y JSON (delimitados por saltos de línea). Cuando se cargan datos de exportación de Avro, Parquet, ORC, Cloud Firestore o datos de exportación de Cloud Datastore, BigQuery deduce el esquema desde los datos de origen.

Sigue estos pasos para especificar de forma manual un esquema de tabla:

IU web

En la IU web de BigQuery, puedes especificar un esquema mediante las opciones Agregar campo o Editar como texto.

  1. Ve a la IU web de BigQuery.

    Ir a la IU web de BigQuery

  2. Haz clic en el ícono de flecha hacia abajo ícono de flecha hacia abajo junto al nombre de tu conjunto de datos en el menú de navegación y haz clic en Crear tabla nueva. El proceso de carga de datos es el mismo que el proceso para crear una tabla vacía.

  3. En la página Crear tabla, haz lo siguiente:

    • Para los Datos de origen, haz clic en Crear desde el origen si cargas datos o haz clic en Crear tabla vacía.
    • Para la Tabla de destino, selecciona tu conjunto de datos y luego ingresa el nombre de la tabla en el campo Nombre de la tabla de destino.
    • Para el Esquema, selecciona una de las siguientes opciones a fin de especificar un esquema de forma manual:

      • Opción 1: Usa Agregar campo y especifica el Nombre, Tipo y Modo de cada campo. En la IU web de BigQuery, no puedes agregar la descripción de un campo cuando usas la opción Agregar campo, pero puedes agregar descripciones de campo de forma manual en la IU después de cargar tus datos.

        Agregar esquema mediante agregar campos

      • Opción 2: Haz clic en Editar como texto y pega el esquema en el formulario de un arreglo JSON. Cuando usas un arreglo JSON, generas el esquema mediante el mismo proceso que se usa para crear un archivo de esquema JSON.

        Agregar un esquema como arreglo JSON

    • Haz clic en Crear tabla.

Línea de comandos

Proporciona de forma manual el esquema intercalado en el formato [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] mediante los siguientes comandos:

  • Comando load si cargas datos.
  • Comando mk si creas una tabla vacía.

Cuando especificas el esquema en la línea de comandos, no puedes incluir un tipo de RECORD (STRUCT), incluir una descripción de campo ni especificar el modo de campo. Todos los modos predeterminados son NULLABLE. Si quieres incluir descripciones, modos y RECORD tipos, proporciona un archivo de esquema JSON.

Para cargar datos en una tabla mediante la definición de un esquema intercalado, ingresa el comando load y especifica el formato de datos con la marca --source_format. Si cargas datos en una tabla en un proyecto que no sea el predeterminado, incluye el ID del proyecto en el siguiente formato: [PROJECT_ID]:[DATASET].[TABLE_NAME].

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

bq --location=[LOCATION] load --source_format=[FORMAT] [PROJECT_ID]:[DATASET].[TABLE_NAME] [PATH_TO_SOURCE] [SCHEMA]

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 configurar el valor de las marcas en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • [FORMAT] es NEWLINE_DELIMITED_JSON o CSV.
  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es el conjunto de datos que contiene la tabla en la que cargas datos.
  • [TABLE] es el nombre de la tabla en la que cargas datos.
  • [PATH_TO_SOURCE] es la ubicación del archivo de datos CSV o JSON en tu máquina local o en Google Cloud Storage.
  • [SCHEMA] es la definición de esquema intercalado.

Ejemplos:

Ingresa el siguiente comando para cargar datos desde un archivo CSV local con el nombre myfile.csv en mydataset.mytable en tu proyecto predeterminado. El esquema se especifica intercalado de forma manual. mydataset se creó en la ubicación multirregión US.

bq --location=US load --source_format=CSV mydataset.mytable ./myfile.csv qtr:STRING,sales:FLOAT,year:STRING

Ingresa el siguiente comando para cargar datos desde un archivo CSV local con el nombre myfile.csv en mydataset.mytable en tu proyecto predeterminado. mydataset se creó en la región asia-northeast1. El esquema se especifica intercalado de forma manual:

bq --location=asia-northeast1 load --source_format=CSV mydataset.mytable ./myfile.csv qtr:STRING,sales:FLOAT,year:STRING

A fin de obtener más información sobre cómo cargar datos en BigQuery, consulta Introducción para cargar datos.

Ingresa el comando mk con la marca --table o -t para especificar la definición de un esquema intercalado cuando crees una tabla vacía. Si creas una tabla en otro proyecto que no sea el predeterminado, agrega el ID del proyecto al comando en el siguiente formato: [PROJECT_ID]:[DATASET].[TABLE].

bq mk --table [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

Donde:

  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es un conjunto de datos en tu proyecto.
  • [TABLE] es el nombre de la tabla que creas.
  • [SCHEMA] es una definición de esquema intercalado.

Por ejemplo, con el siguiente comando se crea una tabla vacía con el nombre mytable en tu proyecto predeterminado. El esquema se especifica intercalado de forma manual.

bq mk --table mydataset.mytable qtr:STRING,sales:FLOAT,year:STRING

Para obtener más información sobre cómo crear una tabla vacía, consulta Cómo crear una tabla vacía con una definición de esquema.

C#

Antes de probar esta muestra, sigue las instrucciones de configuración para C# de la Guía de inicio rápido de BigQuery: Usa bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para C#.

Para especificar el esquema de una tabla cuando cargas datos en una tabla:
using Google.Apis.Bigquery.v2.Data;
using Google.Cloud.BigQuery.V2;
using System;

public class BigQueryLoadTableGcsJson
{
    public void LoadTableGcsJson(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var gcsURI = "gs://cloud-samples-data/bigquery/us-states/us-states.json";
        var dataset = client.GetDataset(datasetId);
        var schema = new TableSchemaBuilder {
            { "name", BigQueryDbType.String },
            { "post_abbr", BigQueryDbType.String }
        }.Build();
        TableReference destinationTableRef = dataset.GetTableReference(
            tableId: "us_states");
        // Create job configuration
        var jobOptions = new CreateLoadJobOptions()
        {
            SourceFormat = FileFormat.NewlineDelimitedJson
        };
        // Create and run job
        BigQueryJob loadJob = client.CreateLoadJob(
            sourceUri: gcsURI, destination: destinationTableRef,
            schema: schema, options: jobOptions);
        loadJob.PollUntilCompleted();  // Waits for the job to complete.
        // Display the number of rows uploaded
        BigQueryTable table = client.GetTable(destinationTableRef);
        Console.WriteLine(
            $"Loaded {table.Resource.NumRows} rows to {table.FullyQualifiedId}");
    }
}

Para especificar un esquema cuando creas una tabla vacía:

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

public class BigQueryCreateTable
{
    public BigQueryTable CreateTable(
        string projectId = "your-project-id",
        string datasetId = "your_dataset_id"
    )
    {
        BigQueryClient client = BigQueryClient.Create(projectId);
        var dataset = client.GetDataset(datasetId);
        // Create schema for new table.
        var schema = new TableSchemaBuilder
        {
            { "full_name", BigQueryDbType.String },
            { "age", BigQueryDbType.Int64 }
        }.Build();
        // Create the table
        return dataset.CreateTable(tableId: "your_table_id", schema: schema);
    }
}

Go

Antes de probar esta muestra, sigue las instrucciones de configuración para Go que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Go de BigQuery.

Para especificar el esquema de una tabla cuando cargas datos en una tabla:
// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.json")
gcsRef.SourceFormat = bigquery.JSON
gcsRef.Schema = bigquery.Schema{
	{Name: "name", Type: bigquery.StringFieldType},
	{Name: "post_abbr", Type: bigquery.StringFieldType},
}
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())
}

Para especificar un esquema cuando creas una tabla vacía:

// To run this sample, you will need to create (or reuse) a context and
// an instance of the bigquery client.  For example:
// import "cloud.google.com/go/bigquery"
// ctx := context.Background()
// client, err := bigquery.NewClient(ctx, "your-project-id")
sampleSchema := bigquery.Schema{
	{Name: "full_name", Type: bigquery.StringFieldType},
	{Name: "age", Type: bigquery.IntegerFieldType},
}

metaData := &bigquery.TableMetadata{
	Schema:         sampleSchema,
	ExpirationTime: time.Now().AddDate(1, 0, 0), // Table will be automatically deleted in 1 year.
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, metaData); err != nil {
	return err
}

Python

Antes de probar esta muestra, sigue las instrucciones de configuración para Python que se encuentran en la Guía de inicio rápido de BigQuery con bibliotecas cliente. Para obtener más información, consulta la Documentación de referencia de la API de Python de BigQuery.

Para especificar el esquema de una tabla cuando cargas datos en una tabla, configura la propiedad LoadJobConfig.schema.
# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'

dataset_ref = client.dataset(dataset_id)
job_config = bigquery.LoadJobConfig()
job_config.schema = [
    bigquery.SchemaField('name', 'STRING'),
    bigquery.SchemaField('post_abbr', 'STRING')
]
job_config.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,
    dataset_ref.table('us_states'),
    location='US',  # Location must match that of the destination dataset.
    job_config=job_config)  # API request
print('Starting job {}'.format(load_job.job_id))

load_job.result()  # Waits for table load to complete.
print('Job finished.')

destination_table = client.get_table(dataset_ref.table('us_states'))
print('Loaded {} rows.'.format(destination_table.num_rows))

Para especificar un esquema cuando creas una tabla vacía, configura la propiedad Table.schema.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

schema = [
    bigquery.SchemaField('full_name', 'STRING', mode='REQUIRED'),
    bigquery.SchemaField('age', 'INTEGER', mode='REQUIRED'),
]
table_ref = dataset_ref.table('my_table')
table = bigquery.Table(table_ref, schema=schema)
table = client.create_table(table)  # API request

assert table.table_id == 'my_table'

Especifica un archivo de esquema JSON

Si prefieres no especificar tu esquema de forma manual, puedes crear un archivo de esquema JSON para usarlo con la CLI. Un archivo de esquema JSON consta de un arreglo JSON que contiene lo siguiente:

  • (Opcional) La descripción de la columna
  • El nombre de la columna
  • El tipo de datos de la columna
  • (Opcional) El modo de la columna (si no se especifica, el modo predeterminado es NULLABLE)

Crea un archivo de esquema JSON

Para crear un archivo de esquema JSON, ingresa lo siguiente mediante un editor de texto adecuado:

[
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 },
 {
   "description": "[DESCRIPTION]",
   "name": "[NAME]",
   "type": "[TYPE]",
   "mode": "[MODE]"
 }
]

El arreglo JSON se indica mediante los corchetes inicial y final []. Cada entrada de columna debe estar separada por coma: },.

Puedes escribir un esquema de tabla existente en un archivo local si ingresas el siguiente comando:

bq show --schema --format=prettyjson [PROJECT_ID]:[DATASET].[TABLE] > [PATH_TO_FILE]

Puedes usar el archivo de salida como punto de partida para tu propio archivo de esquema JSON. Si usas este enfoque, asegúrate de que el archivo contenga solo el arreglo JSON que representa el esquema de la tabla.

Por ejemplo, el siguiente arreglo JSON representa un esquema de tabla básico. Este esquema tiene 3 columnas: qtr (REQUIRED STRING), rep (NULLABLE STRING) y sales (NULLABLE FLOAT).

[
  {
    "description": "quarter",
    "mode": "REQUIRED",
    "name": "qtr",
    "type": "STRING"
  },
  {
    "description": "sales representative",
    "mode": "NULLABLE",
    "name": "rep",
    "type": "STRING"
  },
  {
    "description": "total sales",
    "mode": "NULLABLE",
    "name": "sales",
    "type": "FLOAT"
  }
]

Cómo usar un archivo de esquema JSON

Puedes especificar tu archivo de esquema JSON en la línea de comandos después de crearlo. No puedes usar un archivo de esquema con la IU web de BigQuery o la API.

Proporciona de forma manual el archivo de esquema mediante los siguientes comandos:

  • Comando load si cargas datos.
  • Comando mk si creas una tabla vacía.

Cuando proporciones un archivo de esquema JSON, este debe almacenarse en una ubicación que sea pueda leer localmente. No puedes especificar un archivo de esquema JSON almacenado en Cloud Storage o Google Drive.

Especifica un archivo de esquema cuando cargues datos

El siguiente comando carga datos en una tabla mediante la definición de esquema en un archivo JSON:

bq --location=[LOCATION] load --source_format=[FORMAT] [PROJECT_ID]:[DATASET].[TABLE] [PATH_TO_DATA_FILE] [PATH_TO_SCHEMA_FILE]

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 configurar el valor de las marcas en asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • [FORMAT] es NEWLINE_DELIMITED_JSON o CSV.
  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es el conjunto de datos que contiene la tabla en la que cargas datos.
  • [TABLE] es el nombre de la tabla en la que cargas datos.
  • [PATH_TO_DATA_FILE] es la ubicación del archivo de datos CSV o JSON en tu máquina local o en Google Cloud Storage.
  • [SCHEMA_FILE] es la ruta al archivo de esquema en tu máquina local.

Ejemplos:

Ingresa el siguiente comando para cargar datos desde un archivo CSV local con el nombre myfile.csv en mydataset.mytable en tu proyecto predeterminado. mydataset se creó en la ubicación multirregión US. El esquema se especifica en myschema.json.

bq --location=US load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

Ingresa el siguiente comando para cargar datos desde un archivo CSV local con el nombre myfile.csv en mydataset.mytable en tu proyecto predeterminado. mydataset se creó en la región asia-northeast1. El esquema se especifica en myschema.json.

bq --location=asia-northeast1 load --source_format=CSV mydataset.mytable ./myfile.csv ./myschema.json

Especifica un archivo de esquema cuando crees una tabla

Con el siguiente comando se puede crear una tabla vacía en un conjunto de datos existente mediante la definición de esquema en un archivo JSON:

bq mk --table [PROJECT_ID]:[DATASET].[TABLE] [PATH_TO_SCHEMA_FILE]

Donde:

  • [PROJECT_ID] es tu ID del proyecto.
  • [DATASET] es un conjunto de datos en tu proyecto.
  • [TABLE] es el nombre de la tabla que creas.
  • [PATH_TO_SCHEMA_FILE] es la ruta al archivo de esquema en tu máquina local.

Por ejemplo, con el siguiente comando se puede crear una tabla con el nombre mytable en mydataset en tu proyecto predeterminado. El esquema se especifica en myschema.json:

bq mk --table mydataset.mytable ./myschema.json

Cómo especificar un esquema en la API

Para especificar el esquema de una tabla mediante la API, haz lo siguiente:

  • Para especificar un esquema cuando cargas datos, llama al método jobs.insert y configura la propiedad configuration.load.schema. Especifica tu región en la propiedad location de la sección jobReference.
  • Para especificar un esquema cuando creas una tabla, llama al método tables.insert y configura el esquema en el recurso de tabla mediante la propiedad schema.

Especificar un esquema mediante la API es similar al proceso para crear un archivo de esquema JSON.

Próximos pasos

¿Te ha resultado útil esta página? Enviar comentarios:

Enviar comentarios sobre...

Si necesitas ayuda, visita nuestra página de asistencia.