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.

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

  • Especifica el esquema de forma manual:
    • Usa Cloud Console
    • Usa la IU web clásica de BigQuery
    • Intercala mediante la CLI
  • 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 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

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

    • _TABLE_
    • _FILE_
    • _PARTITION

    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.

    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
    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 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
    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.

    Especifica esquemas de forma manual

    Cuando cargas datos o creas una tabla vacía, puedes especificar de forma manual el esquema de la tabla con Cloud Console, la IU web clásica de BigQuery o la herramienta de línea de comandos. Puedes especificar un esquema de forma manual si cargas 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 de forma manual un esquema de tabla:

    Console

    En Cloud Console, puedes especificar un esquema mediante la opción Agregar campo o la opción Editar como texto.

  • Abre la IU web de BigQuery en Cloud Console.
    Ir a Cloud Console

  • Selecciona un conjunto de datos de la sección Recursos del panel de navegación.

  • Haz clic en Crear tabla (Create table) en el lado derecho de la ventana.

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

  • En la página Crear tabla, en la sección Destino (Destination), realiza lo siguiente:

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

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

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

  • En la sección Esquema, ingresa la definición del esquema.

  • Opción 1: usa Agregar campo y especifica el Nombre, Tipo y Modo de cada campo. En Cloud Console, 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.
  • Opción 2: haz clic en Editar como texto y pega el esquema con el formato 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.
  • Haz clic en Crear tabla.

  • IU clásica

    En la IU web clásica 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.

    3. En la página Crear tabla, sigue estos pasos:

      • En Datos de origen, haz clic en Crear desde el origen si cargas datos o haz clic en Crear tabla vacía.
      • En 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.
      • En Esquema (Schema), selecciona una de las siguientes opciones a fin de especificar un esquema de forma manual:

      • Opción 1: usa Agregar campo (Add field) y especifica el Nombre (Name), Tipo (Type) y Modo (Mode) 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 con agregar campos

      • Opción 2: haz clic en Editar como texto y pega el esquema con el formato 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.

    4. Haz clic en Crear tabla.

    CLI

    Proporciona de forma manual el intercalado de esquema en el formato field:data_type,field:data_type con los comandos siguientes:

  • 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 RECORD (STRUCT) o una descripción de columna. Tampoco puedes especificar el modo de la columna. Todos los modos están establecidos como NULLABLE de forma predeterminada. Para incluir descripciones, modos y tipos RECORD, 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.

    Proporciona la marca --location y establece el valor según tu ubicación (opcional).

    bq --location=location load \
    --source_format=format \
    project_id:dataset.table_name \
    path_to_source \
    schema
    

    Esta es una explicación de los parámetros del ejemplo anterior:

  • location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • format es NEWLINE_DELIMITED_JSON o CSV.
  • project_id:dataset.table_name es el ID del proyecto.
  • project_id:dataset.table_name es el conjunto de datos que contiene la tabla en la que se cargan los datos.
  • project_id:dataset.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:

    Ingresa el comando siguiente para cargar datos de un archivo CSV local llamado myfile.csv en mydataset.mytable en tu proyecto predeterminado. El esquema se especifica intercalado de forma manual.

    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.

    Ingresa el comando 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
    

    Esta es una explicación de los parámetros del ejemplo anterior:

  • project_id es el ID del proyecto.
  • dataset es un conjunto de datos en tu proyecto.
  • table es el nombre de la tabla que quieres crear.
  • schema es una definición de esquema intercalado.
  • Por ejemplo, con el comando siguiente se crea una tabla vacía llamada 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#

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

    
    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, ejecuta el comando siguiente:

    
    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

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

    // 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, ejecuta el comando siguiente:

    // 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

    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
    
    schema = [
        bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
        bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
    ]
    
    # TODO(developer): 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"
    
    table = bigquery.Table(table_id, schema=schema)
    table = client.create_table(table)  # API request
    print(
        "Created table {}.{}.{}".format(table.project, table.dataset_id, table.table_id)
    )

    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:

    • La descripción de la columna (opcional)
    • 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)

    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 una 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"
      }
    ]
    

    Usa 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 Cloud Console, la IU web clásica 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 se pueda leer de manera local. 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
    

    Esta es una explicación de los parámetros del ejemplo anterior:

  • location es el nombre de tu ubicación. La marca --location es opcional. Por ejemplo, si usas BigQuery en la región de Tokio, puedes configurar el valor de la marca como asia-northeast1. Puedes configurar un valor predeterminado para la ubicación con el archivo .bigqueryrc.
  • format es NEWLINE_DELIMITED_JSON o CSV.
  • project_id es el ID del proyecto.
  • dataset es el conjunto de datos que contiene la tabla en la que cargas los datos.
  • table es el nombre de la tabla en la que cargas 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 JSON en tu máquina local.
  • Ejemplo:

    Ingresa 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.

    bq 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
    

    Esta es una explicación de los parámetros del ejemplo anterior:

  • project_id es el ID del proyecto.
  • dataset es un conjunto de datos en tu proyecto.
  • table es el nombre de la tabla que quieres crear.
  • path_to_schema_file es la ruta de acceso al archivo de esquema JSON en tu máquina local.
  • Por ejemplo, el comando siguiente crea una tabla llamada mytable en mydataset en tu proyecto predeterminado. Se especifica el esquema en myschema.json:

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

    Especifica un esquema en la API

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

  • Para especificar un esquema cuando cargas datos, realiza una llamada al método jobs.insert y configura la propiedad schema en la configuración del trabajo load.
  • Para especificar un esquema cuando creas una tabla, realiza una llamada al método tables.insert y configura la propiedad schema en el recurso de tabla.
  • 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.