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 cargas archivos de exportación de Avro, Parquet, ORC, Firestore o archivos de exportación de Datastore, el esquema se recupera de manera automática a partir de los datos de origen autodescriptivos.

Puedes especificar el esquema de una tabla de las siguientes maneras:

• Uso de consola de Google Cloud.
• Usa la instrucción de SQL CREATE TABLE
• Intercala con la herramienta de línea de comandos de bq.
• Crea un archivo de esquema en formato JSON.
• Realiza una llamada al método jobs.insert y configura la propiedad schema en la configuración de trabajo load.
• Realiza una llamada al método tables.insert y configura el esquema en el recurso de tabla con la propiedad schema.

Después de cargar datos o crear una tabla vacía, puedes cambiar 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. También puedes proporcionar la descripción, el modo y el valor predeterminado de una columna.

Nombres de columnas

El nombre de una columna puede contener letras (a-z, A-Z), números (0-9) o guiones bajos (_) y debe empezar con una letra o guion bajo. Si usas nombres de columna flexibles, BigQuery admite que se inicie un nombre de columna con un número. Ten cuidado cuando inicies columnas con un número, ya que el uso de nombres de columna flexibles con la API de lectura de almacenamiento de BigQuery o la API de escritura de BigQuery Storage requiere un control especial. Para obtener más información sobre la compatibilidad con los nombres de columnas flexibles, consulta Nombres de columnas flexibles.

Los nombres de las columnas tienen una longitud máxima de 300 caracteres. No se puede usar ninguno de los siguientes prefijos para los nombres de columna:

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

No se permiten nombres de columna duplicados, incluso si difieren las mayúsculas y minúsculas. Por ejemplo, una columna llamada Column1 se considera idéntica a una columna con el nombre column1. Si deseas obtener más información sobre las reglas de nombres de columnas, consulta Nombres de columnas en la referencia de Google SQL.

Si un nombre de tabla (por ejemplo, test) es el mismo que uno de los nombres de sus columnas (por ejemplo, test), la expresión SELECT interpreta la columna test como un STRUCT que contiene todas las demás columnas de la tabla. Para evitar esta colisión, usa uno de los siguientes métodos:

• Evita usar el mismo nombre para una tabla y sus columnas.

• Asigna un alias diferente a la tabla. Por ejemplo, la siguiente consulta asigna un alias de tabla t a la tabla project1.dataset.test:

  SELECT test FROM project1.dataset.test AS t;
  

• Incluye el nombre de la tabla cuando hagas referencia a una columna. Por ejemplo:

  SELECT test.test FROM project1.dataset.test;
  

Nombres flexibles de columnas

Vista previa

Este producto o función está sujeto a las "Condiciones de las Ofertas de Fase Previa a la DG" de la sección Condiciones Generales del Servicio de las Condiciones específicas del Servicio. Los productos y las funciones que se encuentran en la fase previa a la DG están disponibles “tal cual” y podrían tener asistencia limitada. Para obtener más información, consulta las descripciones de la etapa de lanzamiento.

Ahora tiene más flexibilidad en los nombres de las columnas, incluido el acceso expandido a caracteres en otros idiomas además del inglés, así como símbolos adicionales.

Los nombres flexibles de las columnas admiten los siguientes caracteres:

• Cualquier letra en cualquier lenguaje, como lo representa la expresión regular Unicode \p{L}.
• Cualquier carácter numérico en cualquier lenguaje representado por la expresión regular Unicode \p{N}.
• Cualquier carácter de puntuación de conector, incluidos los guiones bajos, como lo representa la expresión regular Unicode \p{Pc}.
• Un guion o una raya representada por la expresión regular Unicode \p{Pd}.
• Cualquier marca destinada a acompañar otro carácter, como lo representa la expresión regular Unicode \p{M}. Por ejemplo, los acentos, las diéresis o los cuadros de cierre.
• Los siguientes caracteres especiales:
  • Un signo et (&) representado por la expresión regular Unicode \u0026.
  • Un signo de porcentaje (%) representado por la expresión regular Unicode \u0025.
  • Un signo igual (=) representado por la expresión regular Unicode \u003D.
  • Un signo más (+) representado por la expresión regular Unicode \u002B.
  • Los dos puntos (:) que representa la expresión regular Unicode \u003A.
  • Un apóstrofo (') representado por la expresión regular Unicode \u0027.
  • Un signo menor que (<) representado por la expresión regular Unicode \u003C.
  • Un signo mayor que (>) representado por la expresión regular Unicode \u003E.
  • Un signo de número (#) representado por la expresión regular Unicode \u0023.
  • Una línea vertical (|) representada por la expresión regular Unicode \u007c.
  • Espacio en blanco.

Los nombres de columnas flexibles no son compatibles con los siguientes caracteres especiales:

• Un signo de exclamación (!) representado por la expresión regular Unicode \u0021.
• Una comilla (") representada por la expresión regular Unicode \u0022.
• Un signo de dólar ($) representado por la expresión regular Unicode \u0024.
• Un paréntesis de apertura (() representado por la expresión regular Unicode \u0028.
• Un paréntesis de cierre ()) representado por la expresión regular Unicode \u0029.
• Un asterisco (*) representado por la expresión regular Unicode \u002A.
• Una coma (,) representada por la expresión regular Unicode \u002C.
• Un punto (.) representado por la expresión regular Unicode \u002E.
• Una barra (/) representada por la expresión regular Unicode \u002F.
• Un punto y coma (;) representado por la expresión regular Unicode \u003B.
• Un signo de interrogación (?) representado por la expresión regular Unicode \u003F.
• Una arroba (@) representada por la expresión regular Unicode \u0040.
• Un corchete de apertura ([) representado por la expresión regular Unicode \u005B.
• Una barra inversa (\) representada por la expresión regular Unicode \u005C.
• Un corchete de cierre (]) representado por la expresión regular Unicode \u005D.
• Un acento circunflejo (^) representado por la expresión regular Unicode \u005E.
• Un acento grave (`) representado por la expresión regular Unicode \u0060.
• Una llave de apertura {{) representada por la expresión regular Unicode \u007B.
• Una llave de cierre (}) representada por la expresión regular Unicode \u007D.
• Una virgulilla (~) representada por la expresión regular Unicode \u007E.

Para obtener lineamientos adicionales, consulta Nombres de columnas.

Los caracteres expandidos de columna son compatibles con la API de BigQuery Storage Read y la API de BigQuery Storage Write. Para usar la lista expandida de caracteres Unicode con la API de BigQuery Storage Read, debes establecer una marca. Puedes usar el atributo displayName para recuperar el nombre de la columna. En el siguiente ejemplo, se muestra cómo configurar una marca con el cliente de Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Para usar la lista expandida de caracteres Unicode con la API de BigQuery Storage Write, debes proporcionar el esquema con la notación column_name, a menos que uses el objeto de escritor JsonStreamWriter. En el siguiente ejemplo, se muestra cómo proporcionar el esquema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

En este ejemplo, item_name_column y item_description_column son nombres de marcadores de posición que deben cumplir con la convención de nombres del búfer de protocolo. Ten en cuenta que las anotaciones column_name siempre tienen prioridad sobre los nombres de los marcadores de posición.

• La carga de datos de Parquet no admite nombres flexibles de columnas de forma predeterminada. Para inscribirte en esta vista previa, completa el formulario de inscripción. Ten en cuenta que después de inscribirte en la vista previa, cualquier nombre de columna no válido (por ejemplo, intercalaciones de nombres de columna) devuelve un error. Para los proyectos no inscritos, la solicitud de carga reemplaza los caracteres no válidos por guiones bajos en lugar de devolver un error.
• La carga de datos CSV con la detección automática de esquemas no es compatible con los nombres flexibles de columnas de forma predeterminada. Para inscribirte en esta vista previa, completa el formulario de inscripción. Ten en cuenta que después de inscribirte en la vista previa, cualquier nombre de columna no válido (por ejemplo, intercalaciones de nombres de columna) devuelve un error. Para los proyectos no inscritos, la solicitud de carga reemplaza los caracteres no válidos por guiones bajos en lugar de devolver un error.

Limitaciones

Los nombres de columnas flexibles no son compatibles con las tablas externas.

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.

Valores predeterminados

El valor predeterminado para una columna debe ser un literal o una de las siguientes funciones:

• CURRENT_DATE
• CURRENT_DATETIME
• CURRENT_TIME
• CURRENT_TIMESTAMP
• GENERATE_UUID
• RAND
• SESSION_USER
• ST_GEOGPOINT

Tipos de datos de GoogleSQL

GoogleSQL te permite especificar los siguientes tipos de datos en tu esquema. El tipo de datos es obligatorio.

Nombre	Tipo de datos	Descripción
Número entero	INT64	Valores numéricos sin componentes fraccionales
Punto flotante	FLOAT64	Valores numéricos aproximados con componentes fraccionales
Numérico	NUMERIC	Valores numéricos exactos con componentes fraccionales
BigNumeric	BIGNUMERIC	Valores numéricos exactos con componentes fraccionales
Booleano	BOOL	TRUE o FALSE (distinción entre mayúsculas y minúsculas)
String	STRING	Datos de caracteres de longitud variable (Unicode)
Bytes	BYTES	Datos binarios de longitud variable
Fecha	DATE	Fecha del calendario lógica
fecha/hora	DATETIME	Año, mes, día, hora, minuto, segundo y tiempo menor que un segundo
Hora	TIME	Hora, independiente de una fecha específica
Marca de tiempo	TIMESTAMP	Momento determinado absoluto con precisión de microsegundos
Estructura (registro)	STRUCT	Contenedor de campos ordenados, cada uno con un tipo (obligatorio) y un nombre de campo (opcional)
Datos geográficos	GEOGRAPHY	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)
JSON	JSON	Representa JSON, un formato ligero de intercambio de datos
RANGE (vista previa)	RANGE	Un rango de valores DATE, DATETIME o TIMESTAMP

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

También puedes declarar un tipo de arreglo cuando consultas datos. Para obtener más información, consulta Trabaja con arrays.

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
Anulable	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 mode en TableFieldSchema.

Modo de redondeo

Cuando una columna es un tipo NUMERIC o BIGNUMERIC, puedes configurar la opción de columna rounding_mode, que determina cómo se redondean los valores de esa columna cuando se escriben en la tabla. Puedes configurar la opción rounding_mode en una columna de nivel superior o en un campo STRUCT. Se admiten los siguientes modos de redondeo:

• "ROUND_HALF_AWAY_FROM_ZERO": este modo (predeterminado) redondea los casos de punto medio en dirección opuesta al cero.
• "ROUND_HALF_EVEN": Este modo redondea casos de punto medio hacia el dígito par más cercano.

No puedes configurar la opción rounding_mode para una columna que no sea de tipo NUMERIC ni BIGNUMERIC. Para obtener más información sobre estos tipos, consulta los tipos decimales.

En el siguiente ejemplo, se crea una tabla y se insertan valores que se redondean según el modo de redondeo de la columna:

CREATE TABLE mydataset.mytable (
  x NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_EVEN'),
  y NUMERIC(5,2) OPTIONS (rounding_mode='ROUND_HALF_AWAY_FROM_ZERO')
);
INSERT mydataset.mytable (x, y)
VALUES (NUMERIC "1.025", NUMERIC "1.025"),
       (NUMERIC "1.0251", NUMERIC "1.0251"),
       (NUMERIC "1.035", NUMERIC "1.035"),
       (NUMERIC "-1.025", NUMERIC "-1.025");

La tabla mytable se ve de la siguiente manera:

+-------+-------+
| x     | y     |
+-------+-------+
| 1.02  | 1.03  |
| 1.03  | 1.03  |
| 1.04  | 1.04  |
| -1.02 | -1.03 |
+-------+-------+

Para obtener más información, consulta roundingMode en TableFieldSchema.

Especifica esquemas

Cuando cargas datos o creas una tabla vacía, puedes especificar el esquema de la tabla con la consola de Google Cloud o la herramienta de línea de comandos de bq. La especificación de un esquema se admite cuando se cargan archivos CSV y JSON (delimitados por saltos de línea). Cuando cargas datos de exportación de Avro, Parquet, ORC, Firestore o datos de exportación de Datastore, el esquema se recupera de forma automática partir de los datos de origen autodescriptivos.

Sigue estos pasos para especificar un esquema de tabla:

Console

En la consola de Google Cloud, puedes especificar un esquema mediante las opciones Agregar campo o Editar como texto.

1. En la consola de Google Cloud, abre la página de BigQuery.

   Ir a BigQuery

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

3. Expande la opción Acciones y haz clic en Abrir.

4. En el panel de detalles, haz clic en Crear tabla  (Create table).

5. En la página Crear tabla, en la sección Origen, elige Tabla vacía.

6. En la página Crear tabla, en la sección Destino (Destination), haz lo siguiente:

   • En Dataset name (Nombre del conjunto de datos), elige el conjunto de datos correspondiente.

     

   • En el campo Nombre de tabla, escribe el nombre de la tabla que quieres crear.

   • Verifica que Tipo de tabla (Table type) esté configurado como Tabla nativa (Native table).

7. En la sección Esquema, escribe la definición del esquema.

   • Opción 1: usa Agregar campo y especifica el nombre, el tipo y el modo de cada campo.
   • Opción 2: Haz clic en Editar como texto y pega el esquema en forma de array de JSON. Cuando usas un arreglo JSON, generas el esquema mediante el mismo proceso que se usa para crear un archivo de esquema JSON.

8. Haz clic en Crear tabla.

SQL

Usa la sentencia CREATE TABLE. Especifica el esquema con la opción de columna. En el siguiente ejemplo, se crea una tabla nueva llamada newtable con las columnas x, y, z, cuyos tipos son número entero, string y booleano:

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

   Ir a BigQuery

2. En el editor de consultas, escribe la siguiente sentencia:

   CREATE TABLE IF NOT EXISTS mydataset.newtable (x INT64, y STRING, z BOOL)
     OPTIONS(
       description = 'My example table');
   

3. Haz clic en Ejecutar.

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

bq

Proporciona el esquema intercalado en el formato field:data_type,field:data_type mediante uno de los siguientes comandos:

• Si cargas datos, usa el comando bq load.
• Si quieres crear una tabla vacía, usa el comando bq mk.

Cuando especificas el esquema en la línea de comandos, no puedes incluir tipos RECORD (STRUCT) ni RANGE, no puedes incluir una descripción de la columna y no puedes especificar el modo de la columna. Todos los modos predeterminados están establecidos en NULLABLE. Para incluir descripciones, modos y tipos RECORD y RANGE, proporciona un archivo de esquema JSON en su lugar.

Para cargar datos en una tabla mediante la definición de un esquema intercalado, debes ingresar el comando load y especificar el formato de datos con la marca --source_format. Si cargas datos en una tabla en otro proyecto que no sea el predeterminado, debes incluir el ID del proyecto en el formato siguiente: project_id:dataset.table_name.

Opcional: 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

Reemplaza lo siguiente:

• location: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• format: NEWLINE_DELIMITED_JSON o CSV.
• project_id: es el ID de tu proyecto.
• dataset: es el conjunto de datos que contiene la tabla en la que cargas datos.
• table_name: Es el nombre de la tabla en la que se cargan los datos.
• path_to_source: es la ubicación del archivo de datos CSV o JSON en tu máquina local o en Cloud Storage.
• schema: es la definición de esquema intercalado.

Ejemplo:

Escribe el comando siguiente para cargar datos de un archivo CSV local llamado myfile.csv en mydataset.mytable en tu proyecto predeterminado. El esquema está especificado de forma intercalada.

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

Para obtener más información sobre la carga de datos en BigQuery, consulta Introducción a la carga de datos.

Escribe el comando bq mk con la marca --table o -t para especificar una definición de 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 formato siguiente: project_id:dataset.table.

bq mk --table project_id:dataset.table schema

Reemplaza lo siguiente:

• project_id: es el ID de tu proyecto.
• dataset: Un conjunto de datos en tu proyecto.
• table: es el nombre de la tabla que crearás.
• schema: es una definición de esquema intercalado.

Por ejemplo, con el comando siguiente se crea una tabla vacía llamada mytable en el proyecto predeterminado. El esquema está especificado de forma intercalada.

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

Si deseas obtener más información para crear una tabla vacía, consulta Crea una tabla vacía con una definición de esquema.

C#

Para especificar el esquema de una tabla cuando cargas datos en una tabla, ejecuta el siguiente comando:

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

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

using Google.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 = loadJob.PollUntilCompleted().ThrowOnAnyError();  // 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, ejecuta el siguiente comando:

using Google.Cloud.BigQuery.V2;

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

Para especificar el esquema de una tabla cuando cargas datos en una tabla, ejecuta el siguiente comando:

Antes de probar este ejemplo, sigue las instrucciones de configuración para Go incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Go.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import (
	"context"
	"fmt"

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

// importJSONExplicitSchema demonstrates loading newline-delimited JSON data from Cloud Storage
// into a BigQuery table and providing an explicit schema for the data.
func importJSONExplicitSchema(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.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())
	}
	return nil
}

Para especificar un esquema cuando creas una tabla vacía, ejecuta el siguiente comando:

import (
	"context"
	"fmt"
	"time"

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

// createTableExplicitSchema demonstrates creating a new BigQuery table and specifying a schema.
func createTableExplicitSchema(projectID, datasetID, tableID string) error {
	// projectID := "my-project-id"
	// datasetID := "mydatasetid"
	// tableID := "mytableid"
	ctx := context.Background()

	client, err := bigquery.NewClient(ctx, projectID)
	if err != nil {
		return fmt.Errorf("bigquery.NewClient: %v", err)
	}
	defer client.Close()

	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
	}
	return nil
}

Java

Para especificar el esquema de una tabla cuando cargas datos en una tabla, ejecuta el siguiente comando:

Antes de probar este ejemplo, sigue las instrucciones de configuración para Java incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Java.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
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.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.TableId;

// Sample to load JSON data from Cloud Storage into a new BigQuery table
public class LoadJsonFromGCS {

  public static void runLoadJsonFromGCS() {
    // 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";
    Schema schema =
        Schema.of(
            Field.of("name", StandardSQLTypeName.STRING),
            Field.of("post_abbr", StandardSQLTypeName.STRING));
    loadJsonFromGCS(datasetName, tableName, sourceUri, schema);
  }

  public static void loadJsonFromGCS(
      String datasetName, String tableName, String sourceUri, Schema schema) {
    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())
              .setSchema(schema)
              .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 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());
    }
  }
}

Para especificar un esquema cuando creas una tabla vacía, ejecuta el siguiente comando:

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.Field;
import com.google.cloud.bigquery.Schema;
import com.google.cloud.bigquery.StandardSQLTypeName;
import com.google.cloud.bigquery.StandardTableDefinition;
import com.google.cloud.bigquery.TableDefinition;
import com.google.cloud.bigquery.TableId;
import com.google.cloud.bigquery.TableInfo;

public class CreateTable {

  public static void runCreateTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    String tableName = "MY_TABLE_NAME";
    Schema schema =
        Schema.of(
            Field.of("stringField", StandardSQLTypeName.STRING),
            Field.of("booleanField", StandardSQLTypeName.BOOL));
    createTable(datasetName, tableName, schema);
  }

  public static void createTable(String datasetName, String tableName, Schema schema) {
    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);
      TableDefinition tableDefinition = StandardTableDefinition.of(schema);
      TableInfo tableInfo = TableInfo.newBuilder(tableId, tableDefinition).build();

      bigquery.create(tableInfo);
      System.out.println("Table created successfully");
    } catch (BigQueryException e) {
      System.out.println("Table was not created. \n" + e.toString());
    }
  }
}

Python

Para especificar el esquema de una tabla cuando cargas datos en una tabla, configura la propiedad LoadJobConfig.schema.

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

from google.cloud import bigquery

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

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
    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,
    location="US",  # Must match the destination dataset location.
    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))

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

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"

schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # Make an API request.
print(
    "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
)

Especifica un archivo de esquema JSON

Si lo prefieres, puedes especificar el esquema con un archivo de esquema JSON en lugar de usar una definición de esquema intercalado. Un archivo de esquema JSON consta de un array JSON con la siguiente información:

• El nombre de la columna
• El tipo de datos de la columna
• El modo de la columna (opcional; si no se especifica, el modo predeterminado es NULLABLE)
• Opcional: Los campos de la columna si son un tipo STRUCT
• La descripción de la columna (opcional)
• Las etiquetas de política de la columna, que se usan para el control de acceso a nivel del campo (opcional)
• La longitud máxima de los valores de la columna para los tipos STRING o BYTES (opcional)
• La precisión de la columna para los tipos NUMERIC o BIGNUMERIC (opcional)
• La escala de la columna para los tipos NUMERIC o BIGNUMERIC (opcional)
• La intercalación de la columna para tipos STRING (opcional)
• El valor predeterminado de la columna (opcional)
• El modo de redondeo de la columna, si la columna es de tipo NUMERIC o BIGNUMERIC (opcional)

Nota: También puedes especificar el array de JSON que creas en el archivo de esquema mediante la opción Editar como texto en la consola de Google Cloud. También se puede usar como punto de partida para configurar la propiedad schema en la API.

Crea un archivo de esquema JSON

Para crear un archivo de esquema JSON, escribe un TableFieldSchema en cada columna. Los campos name y type son obligatorios. Todos los demás campos son opcionales.

[
  {
    "name": string,
    "type": string,
    "mode": string,
    "fields": [
      {
        object (TableFieldSchema)
      }
    ],
    "description": string,
    "policyTags": {
      "names": [
        string
      ]
    },
    "maxLength": string,
    "precision": string,
    "scale": string,
    "collation": string,
    "defaultValueExpression": string,
    "roundingMode": string
  },
  {
    "name": string,
    "type": string,
    ...
  }
]

Si la columna es un tipo RANGE<T>, usa el campo rangeElementType para describir T, donde T debe ser uno de DATE, DATETIME o TIMESTAMP.

[
  {
    "name": "duration",
    "type": "RANGE",
    "mode": "NULLABLE",
    "rangeElementType": {
      "type": "DATE"
    }
  }
]

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

Para escribir un esquema de tabla existente en un archivo local, haz lo siguiente:

bq

bq show \
--schema \
--format=prettyjson \
project_id:dataset.table > path_to_file

Reemplaza lo siguiente:

• project_id: es el ID de tu proyecto.
• dataset: Un conjunto de datos en tu proyecto.
• table: Es el nombre de un esquema de tabla existente.
• path_to_file: Es la ubicación del archivo local en el que escribes el esquema de la tabla.

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Para escribir un archivo JSON de esquema desde una tabla mediante la biblioteca cliente de Python, llama al método Client.schema_to_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change the table_id variable to the full name of the
# table you want to get schema from.
table_id = "your-project.your_dataset.your_table_name"

# TODO(dev): Change schema_path variable to the path
# of your schema file.
schema_path = "path/to/schema.json"
table = client.get_table(table_id)  # Make an API request.

# Write a schema file to schema_path with the schema_to_json method.
client.schema_to_json(table.schema, schema_path)

with open(schema_path, "r", encoding="utf-8") as schema_file:
    schema_contents = schema_file.read()

# View table properties
print(f"Got table '{table.project}.{table.dataset_id}.{table.table_id}'.")
print(f"Table schema: {schema_contents}")

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 tres columnas: qtr (REQUIRED STRING), rep (NULLABLE STRING) y sales (NULLABLE FLOAT).

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

Usa un archivo de esquema JSON

Después de crear el archivo de esquema JSON, puedes especificarlo con la herramienta de línea de comandos de bq. No puedes usar un archivo de esquema con la consola de Google Cloud o la API.

Proporciona el archivo de esquema:

• Si cargas datos, usa el comando bq load.
• Si quieres crear una tabla vacía, usa el comando bq mk.

Cuando proporciones un archivo de esquema JSON, este debe almacenarse en una ubicación que se 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

Para cargar datos en una tabla mediante la definición de esquema JSON, haz lo siguiente:

bq

bq --location=location load \
--source_format=format \
project_id:dataset.table \
path_to_data_file \
path_to_schema_file

Reemplaza lo siguiente:

• location: El nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
• format: NEWLINE_DELIMITED_JSON o CSV.
• project_id: es el ID de tu 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 se están cargando los datos.
• path_to_data_file: es la ubicación del archivo de datos CSV o JSON en tu máquina local o en Cloud Storage.
• path_to_schema_file: es la ruta de acceso al archivo de esquema en tu máquina local.

Ejemplo:

Escribe el comando siguiente para cargar datos de un archivo CSV local llamado myfile.csv en mydataset.mytable en tu proyecto predeterminado. Se especifica el esquema en myschema.json en el directorio actual.

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Para cargar un esquema de tabla desde un archivo JSON con la biblioteca cliente de Python, llama al método schema_from_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change uri variable to the path of your data file.
uri = "gs://your-bucket/path/to/your-file.csv"
# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

job_config = bigquery.LoadJobConfig(
    # To use the schema you loaded pass it into the
    # LoadJobConfig constructor.
    schema=schema,
    skip_leading_rows=1,
)

# Pass the job_config object to the load_table_from_file,
# load_table_from_json, or load_table_from_uri method
# to use the schema on a new table.
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)  # Make an API request.
print(f"Loaded {destination_table.num_rows} rows to {table_id}.")

Especifica un archivo de esquema cuando crees una tabla

Para crear una tabla vacía en un conjunto de datos existente con un archivo de esquema JSON, haz lo siguiente:

bq

bq mk --table project_id:dataset.table path_to_schema_file

Reemplaza lo siguiente:

• project_id: es el ID de tu proyecto.
• dataset: Un conjunto de datos en tu proyecto.
• table: es el nombre de la tabla que crearás.
• path_to_schema_file: es la ruta de acceso al archivo de esquema en tu máquina local.

Por ejemplo, el siguiente comando crea una tabla llamada mytable en mydataset en el proyecto predeterminado. Se especifica el esquema en myschema.json en el directorio actual:

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

Python

Antes de probar este ejemplo, sigue las instrucciones de configuración para Python incluidas en la guía de inicio rápido de BigQuery sobre cómo usar bibliotecas cliente. Para obtener más información, consulta la documentación de referencia de la API de BigQuery para Python.

Para autenticarte en BigQuery, configura las credenciales predeterminadas de la aplicación. Si deseas obtener más información, consulta Configura la autenticación para bibliotecas cliente.

Para cargar un esquema de tabla desde un archivo JSON con la biblioteca cliente de Python, llama al método schema_from_json.

from google.cloud import bigquery

client = bigquery.Client()

# TODO(dev): Change table_id to the full name of the table you want to create.
table_id = "your-project.your_dataset.your_table_name"
# TODO(dev): Change schema_path variable to the path of your schema file.
schema_path = "path/to/schema.json"
# To load a schema file use the schema_from_json method.
schema = client.schema_from_json(schema_path)

table = bigquery.Table(table_id, schema=schema)
table = client.create_table(table)  # API request
print(f"Created table {table_id}.")

Especifica un esquema en la API

Si deseas 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 schema, en el recurso JobConfigurationLoad.

• Para especificar un esquema cuando creas una tabla, llama al método tables.insert y configura la propiedad schema, en el recurso Table.

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

Seguridad de las tablas

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

¿Qué sigue?

• Obtén más información sobre cómo especificar columnas anidadas y repetidas en una definición de esquema.
• Obtén más información sobre la detección automática de esquema.
• Obtén más información sobre cargar datos en BigQuery.
• Obtén más información sobre cómo crear y usar tablas.