Especificar um esquema

O BigQuery permite-lhe especificar o esquema de uma tabela quando carrega dados para uma tabela e quando cria uma tabela vazia. Em alternativa, pode usar a deteção automática de esquemas para formatos de dados suportados.

Quando carrega ficheiros de exportação Avro, Parquet, ORC, Firestore ou Datastore, o esquema é obtido automaticamente dos dados de origem autodescritivos.

Pode especificar o esquema de uma tabela das seguintes formas:

• Use a Google Cloud consola.
• Use a declaração SQL CREATE TABLE.
• Incorporado através da ferramenta de linhas de comando bq.
• Crie um ficheiro de esquema no formato JSON.
• Chame o método jobs.insert e configure a propriedade schema na configuração da tarefa load.
• Chame o método tables.insert e configure o esquema no recurso de tabela usando a propriedade schema.

Depois de carregar dados ou criar uma tabela vazia, pode modificar a definição do esquema da tabela.

Componentes de esquema

Quando especifica um esquema de tabela, tem de fornecer o nome e o tipo de dados de cada coluna. Também pode fornecer a descrição, o modo e o valor predefinido de uma coluna.

Nomes das colunas

Um nome de coluna pode conter letras (a-z, A-Z), números (0-9) ou sublinhados (_), e tem de começar por uma letra ou um sublinhado. Se usar nomes de colunas flexíveis, o BigQuery suporta o início de um nome de coluna com um número. Tenha cuidado ao iniciar colunas com um número, uma vez que a utilização de nomes de colunas flexíveis com a API BigQuery Storage Read ou a API BigQuery Storage Write requer um processamento especial. Para mais informações sobre o suporte de nomes de colunas flexíveis, consulte o artigo Nomes de colunas flexíveis.

Os nomes das colunas têm um comprimento máximo de 300 carateres. Os nomes das colunas não podem usar nenhum dos seguintes prefixos:

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

Não são permitidos nomes de colunas duplicados, mesmo que a utilização de maiúsculas e minúsculas seja diferente. Por exemplo, uma coluna denominada Column1 é considerada idêntica a uma coluna denominada column1. Para saber mais sobre as regras de nomenclatura de colunas, consulte Nomes das colunas na referência do GoogleSQL.

Se o nome de uma tabela (por exemplo, test) for igual a um dos nomes das respetivas colunas (por exemplo, test), a expressão SELECT interpreta a coluna test como um STRUCT que contém todas as outras colunas da tabela. Para evitar esta colisão, use um dos seguintes métodos:

• Evite usar o mesmo nome para uma tabela e as respetivas colunas.

• Atribua um alias diferente à tabela. Por exemplo, a seguinte consulta atribui um alias de tabela t à tabela project1.dataset.test:

  SELECT test FROM project1.dataset.test AS t;
  

• Inclua o nome da tabela quando fizer referência a uma coluna. Por exemplo:

  SELECT test.test FROM project1.dataset.test;
  

Nomes de colunas flexíveis

Tem mais flexibilidade na forma como denomina as colunas, incluindo acesso expandido a carateres em idiomas que não o inglês, bem como símbolos adicionais. Certifique-se de que usa carateres de acento grave (`) para incluir nomes de colunas flexíveis se forem Identificadores entre aspas.

Os nomes de colunas flexíveis suportam os seguintes carateres:

• Qualquer letra em qualquer idioma, conforme representado pela expressão regular Unicode \p{L}.
• Qualquer caráter numérico em qualquer idioma, representado pela expressão regular Unicode \p{N}.
• Qualquer caráter de pontuação de conetor, incluindo sublinhados, conforme representado pela expressão regular Unicode \p{Pc}.
• Um hífen ou um travessão representado pela expressão regular Unicode \p{Pd}.
• Qualquer marca destinada a acompanhar outro caráter, conforme representado pela expressão regular Unicode \p{M}. Por exemplo, acentos, trema ou caixas delimitadoras.
• Os seguintes carateres especiais:
  • Um E comercial (&), representado pela expressão regular Unicode \u0026.
  • Um sinal de percentagem (%) representado pela expressão regular Unicode \u0025.
  • Um sinal de igual (=) representado pela expressão regular Unicode \u003D.
  • Um sinal de mais (+) representado pela expressão regular Unicode \u002B.
  • Um dois pontos (:) representado pela expressão regular Unicode \u003A.
  • Um apóstrofo (') representado pela expressão regular Unicode \u0027.
  • Um sinal de menor do que (<), representado pela expressão regular Unicode \u003C.
  • Um sinal de maior do que (>) representado pela expressão regular Unicode \u003E.
  • Um sinal de número (#), representado pela expressão regular Unicode \u0023.
  • Uma linha vertical (|) representada pela expressão regular Unicode \u007c.
  • Espaço em branco.

Os nomes de colunas flexíveis não suportam os seguintes carateres especiais:

• Um ponto de exclamação (!) representado pela expressão regular Unicode \u0021.
• Uma marca de aspas ("), representada pela expressão regular Unicode \u0022.
• Um cifrão ($) representado pela expressão regular Unicode \u0024.
• Um parêntese esquerdo (() representado pela expressão regular Unicode \u0028.
• Um parêntese direito ()), representado pela expressão regular Unicode \u0029.
• Um asterisco (*), representado pela expressão regular Unicode \u002A.
• Uma vírgula (,) representada pela expressão regular Unicode \u002C.
• Um ponto (.), representado pela expressão regular Unicode \u002E. Os pontos não são substituídos por sublinhados nos nomes das colunas do ficheiro Parquet quando é usado um mapa de carateres do nome da coluna. Para mais informações, consulte as limitações das colunas flexíveis.
• Uma barra (/) representada pela expressão regular Unicode \u002F.
• Um ponto e vírgula (;) representado pela expressão regular Unicode \u003B.
• Um ponto de interrogação (?), representado pela expressão regular Unicode \u003F.
• Um sinal de arroba (@) representado pela expressão regular Unicode \u0040.
• Um parêntesis reto esquerdo ([) representado pela expressão regular Unicode \u005B.
• Uma barra invertida (\), representada pela expressão regular Unicode \u005C.
• Um parêntesis reto direito (]), representado pela expressão regular Unicode \u005D.
• Um acento circunflexo (^), representado pela expressão regular Unicode \u005E.
• Um acento grave (`) representado pela expressão regular Unicode \u0060.
• Uma chaveta esquerda {{) representada pela expressão regular Unicode \u007B.
• Uma chaveta direita (}) representada pela expressão regular Unicode \u007D.
• Um til (~) representado pela expressão regular Unicode \u007E.

Para ver diretrizes adicionais, consulte o artigo Nomes das colunas.

Os carateres de coluna expandidos são suportados pela API BigQuery Storage Read e pela API BigQuery Storage Write. Para usar a lista expandida de carateres Unicode com a API BigQuery Storage Read, tem de definir uma flag. Pode usar o atributo displayName para obter o nome da coluna. O exemplo seguinte mostra como definir uma flag com o cliente 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 a lista expandida de carateres Unicode com a API Storage Write do BigQuery, tem de fornecer o esquema com a notação column_name, a menos que esteja a usar o objeto de gravação JsonStreamWriter. O exemplo seguinte mostra como fornecer o 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-列"];
}

Neste exemplo, item_name_column e item_description_column são nomes de marcadores de posição que têm de estar em conformidade com a convenção de nomenclatura do protocol buffer. Tenha em atenção que as anotações column_name têm sempre precedência sobre os nomes dos marcadores de posição.

Limitações

• Os nomes de colunas flexíveis não são suportados com tabelas externas.

Descrições das colunas

Cada coluna pode incluir uma descrição opcional. A descrição é uma string com um comprimento máximo de 1024 carateres.

Valores predefinidos

O valor predefinido de uma coluna tem de ser um literal ou uma das seguintes funções:

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

Tipos de dados do GoogleSQL

O GoogleSQL permite-lhe especificar os seguintes tipos de dados no seu esquema. O tipo de dados é obrigatório.

Nome	Tipo de dados	Descrição
Inteiro	INT64	Valores numéricos sem componentes fracionários
Vírgula flutuante	FLOAT64	Aproximar valores numéricos com componentes fracionários
Numérico	NUMERIC	Valores numéricos exatos com componentes fracionários
BigNumeric	BIGNUMERIC	Valores numéricos exatos com componentes fracionários
Booleano	BOOL	VERDADEIRO ou FALSO (não é sensível a maiúsculas e minúsculas)
String	STRING	Dados de carateres de comprimento variável (Unicode)
Bytes	BYTES	Dados binários de comprimento variável
Data	DATE	Uma data do calendário lógica
Data/hora	DATETIME	Um ano, um mês, um dia, uma hora, um minuto, um segundo e uma fração de segundo
Hora	TIME	Uma hora, independentemente de uma data específica
Data/hora	TIMESTAMP	Um ponto absoluto no tempo, com precisão de microssegundos
Struct (Record)	STRUCT	Contentor de campos ordenados, cada um com um tipo (obrigatório) e um nome do campo (opcional)
Geografia	GEOGRAPHY	Um conjunto de pontos na superfície da Terra (um conjunto de pontos, linhas e polígonos no esferoide de referência WGS84 com arestas geodésicas)
JSON	JSON	Representa JSON, um formato básico de intercâmbio de dados
RANGE	RANGE	Um intervalo de valores de DATE, DATETIME ou TIMESTAMP

Para mais informações sobre os tipos de dados no GoogleSQL, consulte o artigo Tipos de dados GoogleSQL.

Também pode declarar um tipo de matriz quando consulta dados. Para mais informações, consulte o artigo Trabalhe com matrizes.

Meios

O BigQuery suporta os seguintes modos para as suas colunas. O modo é opcional. Se o modo não for especificado, a coluna é predefinida para NULLABLE.

Modo	Descrição
Permitido valor nulo	A coluna permite valores NULL (predefinição)
Obrigatória	Os valores NULL não são permitidos
Repetido	A coluna contém uma matriz de valores do tipo especificado

Para mais informações sobre os modos, consulte mode no TableFieldSchema.

Modo de arredondamento

Quando uma coluna é do tipo NUMERIC ou BIGNUMERIC, pode definir a opção de coluna rounding_mode, que determina como os valores nessa coluna são arredondados quando escritos na tabela. Pode definir a opção rounding_mode numa coluna de nível superior ou num STRUCTcampo. São suportados os seguintes modos de arredondamento:

• "ROUND_HALF_AWAY_FROM_ZERO": este modo (predefinição) arredonda os casos a meio caminho para longe de zero.
• "ROUND_HALF_EVEN": este modo arredonda os casos intermédios para o dígito par mais próximo.

Não pode definir a opção rounding_mode para uma coluna que não seja do tipo NUMERIC ou BIGNUMERIC. Para saber mais sobre estes tipos, consulte os tipos decimais.

O exemplo seguinte cria uma tabela e insere valores arredondados com base no modo de arredondamento da coluna:

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

A tabela mytable tem o seguinte aspeto:

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

Para mais informações, consulte roundingMode no TableFieldSchema.

Especifique esquemas

Quando carrega dados ou cria uma tabela vazia, pode especificar o esquema da tabela através da consola ou da ferramenta de linha de comandos bq. Google Cloud A especificação de um esquema é suportada quando carrega ficheiros CSV e JSON (delimitados por nova linha). Quando carrega dados de exportação do Avro, Parquet, ORC, Firestore ou Datastore, o esquema é obtido automaticamente dos dados de origem autodescritivos.

Para especificar um esquema de tabela:

Consola

Na Google Cloud consola, pode especificar um esquema através da opção Adicionar campo ou da opção Editar como texto.

1. Na Google Cloud consola, abra a página do BigQuery.

   Aceda ao BigQuery

2. No painel Explorador, expanda o projeto e selecione um conjunto de dados.

3. Expanda a opção Ações e clique em Abrir.

4. No painel de detalhes, clique em Criar tabela .

5. Na página Criar tabela, na secção Origem, selecione Tabela vazia.

6. Na página Criar tabela, na secção Destino:

   • Em Nome do conjunto de dados, escolha o conjunto de dados adequado

     

   • No campo Nome da tabela, introduza o nome da tabela que está a criar.

   • Verifique se o Tipo de tabela está definido como Tabela nativa.

7. Na secção Esquema, introduza a definição do esquema.

   • Opção 1: use Adicionar campo e especifique o nome, tipo> e modo de cada campo.
   • Opção 2: clique em Editar como texto e cole o esquema sob a forma de uma matriz JSON. Quando usa uma matriz JSON, gera o esquema através do mesmo processo que criar um ficheiro de esquema JSON.

8. Clique em Criar tabela.

SQL

Use a declaração CREATE TABLE. Especifique o esquema através da opção coluna. O exemplo seguinte cria uma nova tabela denominada newtable com colunas x, y e z dos tipos integer, string e boolean:

1. Na Google Cloud consola, aceda à página BigQuery.

   Aceda ao BigQuery

2. No editor de consultas, introduza a seguinte declaração:

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

3. Clique em Executar.

Para mais informações sobre como executar consultas, consulte o artigo Execute uma consulta interativa.

bq

Forneça o esquema inline no formato field:data_type,field:data_type usando um dos seguintes comandos:

• Se estiver a carregar dados, use o comando bq load.
• Se estiver a criar uma tabela vazia, use o comando bq mk.

Quando especifica o esquema na linha de comandos, não pode incluir os tipos RECORD (STRUCT) ou RANGE. Além disso, não pode incluir uma descrição da coluna nem especificar o modo da coluna. Todos os modos têm NULLABLE como predefinição. Para incluir descrições, modos, tipos RECORD e tipos RANGE, forneça um ficheiro de esquema JSON.

Para carregar dados para uma tabela usando uma definição de esquema inline, introduza o comando load e especifique o formato dos dados usando a flag --source_format. Se estiver a carregar dados para uma tabela num projeto que não seja o projeto predefinido, inclua o ID do projeto no seguinte formato: project_id:dataset.table_name.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

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

Substitua o seguinte:

• location: o nome da sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
• format: NEWLINE_DELIMITED_JSON ou CSV.
• project_id: o ID do seu projeto.
• dataset: o conjunto de dados que contém a tabela para a qual está a carregar dados.
• table_name: o nome da tabela para a qual está a carregar dados.
• path_to_source: a localização do ficheiro de dados CSV ou JSON no seu computador local ou no Cloud Storage.
• schema: a definição do esquema inline.

Exemplo:

Introduza o seguinte comando para carregar dados de um ficheiro CSV local denominado myfile.csv para mydataset.mytable no seu projeto predefinido. O esquema é especificado inline.

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

Para mais informações sobre o carregamento de dados no BigQuery, consulte o artigo Introdução ao carregamento de dados.

Para especificar uma definição de esquema inline quando cria uma tabela vazia, introduza o comando bq mk com a flag --table ou -t. Se estiver a criar uma tabela num projeto que não seja o projeto predefinido, adicione o ID do projeto ao comando no seguinte formato: project_id:dataset.table.

bq mk --table project_id:dataset.table schema

Substitua o seguinte:

• project_id: o ID do seu projeto.
• dataset: um conjunto de dados no seu projeto.
• table: o nome da tabela que está a criar.
• schema: uma definição de esquema inline.

Por exemplo, o comando seguinte cria uma tabela vazia denominada mytable no seu projeto predefinido. O esquema é especificado inline.

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

Para mais informações sobre como criar uma tabela vazia, consulte o artigo Criar uma tabela vazia com uma definição de esquema.

C#

Para especificar o esquema de uma tabela quando carrega dados para uma tabela:

Antes de experimentar este exemplo, siga as C#instruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API C# BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 um esquema quando cria uma tabela vazia:

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 o esquema de uma tabela quando carrega dados para uma tabela:

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 um esquema quando cria uma tabela vazia:

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 o esquema de uma tabela quando carrega dados para uma tabela:

Antes de experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.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 um esquema quando cria uma tabela vazia:

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 o esquema de uma tabela quando carrega dados para uma tabela, configure a propriedade LoadJobConfig.schema.

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de 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 um esquema quando cria uma tabela vazia, configure a propriedade 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)
)

Especificar um ficheiro de esquema JSON

Se preferir, pode especificar o esquema através de um ficheiro de esquema JSON em vez de usar uma definição de esquema inline. Um ficheiro de esquema JSON consiste numa matriz JSON que contém o seguinte:

• O nome da coluna
• O tipo de dados da coluna
• Opcional: o modo da coluna (se não for especificado, o modo é predefinido como NULLABLE)
• Opcional: os campos da coluna, se for do tipo STRUCT
• Opcional: a descrição da coluna
• Opcional: as etiquetas de política da coluna, usadas para o controlo de acesso ao nível do campo
• Opcional: o comprimento máximo dos valores da coluna para os tipos STRING ou BYTES
• Opcional: a precisão da coluna para os tipos NUMERIC ou BIGNUMERIC
• Opcional: a escala da coluna para os tipos NUMERIC ou BIGNUMERIC
• Opcional: a colação da coluna para tipos STRING
• Opcional: o valor predefinido da coluna
• Opcional: o modo de arredondamento da coluna, se a coluna for do tipo NUMERIC ou BIGNUMERIC

Nota: também pode especificar a matriz JSON que cria no ficheiro de esquema usando a opção Editar como texto da Google Cloud consola. Também pode ser usado como ponto de partida para configurar a propriedade schema na API.

Criar um ficheiro de esquema JSON

Para criar um ficheiro de esquema JSON, introduza um TableFieldSchema para cada coluna. Os campos name e type são obrigatórios. Todos os outros campos são opcionais.

[
  {
    "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,
    ...
  }
]

Se a coluna for do tipo RANGE<T>, use o campo rangeElementType para descrever T, em que T tem de ser um de DATE, DATETIME ou TIMESTAMP.

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

A matriz JSON é indicada pelos parênteses de abertura e fecho []. Cada entrada de coluna tem de estar separada por uma vírgula: },.

Para escrever um esquema de tabela existente num ficheiro local, faça o seguinte:

bq

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

Substitua o seguinte:

• project_id: o ID do seu projeto.
• dataset: um conjunto de dados no seu projeto.
• table: o nome de um esquema de tabela existente.
• path_to_file: a localização do ficheiro local no qual está a escrever o esquema da tabela.

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para escrever um ficheiro JSON de esquema a partir de uma tabela através da biblioteca cliente Python, chame o 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}")

Pode usar o ficheiro de saída como ponto de partida para o seu próprio ficheiro de esquema JSON. Se usar esta abordagem, certifique-se de que o ficheiro contém apenas a matriz JSON que representa o esquema da tabela.

Por exemplo, a matriz JSON seguinte representa um esquema de tabela básico. Este esquema tem três colunas: qtr (REQUIRED STRING), rep (NULLABLE STRING) e 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"
  }
]

Usar um ficheiro de esquema JSON

Depois de criar o ficheiro de esquema JSON, pode especificá-lo através da ferramenta de linha de comandos bq. Não pode usar um ficheiro de esquema com a Google Cloud consola nem com a API.

Forneça o ficheiro de esquema:

• Se estiver a carregar dados, use o comando bq load.
• Se estiver a criar uma tabela vazia, use o comando bq mk.

Quando fornece um ficheiro de esquema JSON, este tem de ser armazenado numa localização legível localmente. Não pode especificar um ficheiro de esquema JSON armazenado no Cloud Storage ou no Google Drive.

Especificar um ficheiro de esquema quando carrega dados

Para carregar dados para uma tabela através de uma definição de esquema JSON, faça o seguinte:

bq

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

Substitua o seguinte:

• location: o nome da sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode definir um valor predefinido para a localização através do ficheiro.bigqueryrc.
• format: NEWLINE_DELIMITED_JSON ou CSV.
• project_id: o ID do seu projeto.
• dataset: o conjunto de dados que contém a tabela para a qual está a carregar dados.
• table: o nome da tabela para a qual está a carregar dados.
• path_to_data_file: a localização do ficheiro de dados CSV ou JSON no seu computador local ou no Cloud Storage.
• path_to_schema_file: o caminho para o ficheiro de esquema no seu computador local.

Exemplo:

Introduza o seguinte comando para carregar dados de um ficheiro CSV local denominado myfile.csv para mydataset.mytable no seu projeto predefinido. O esquema é especificado em myschema.json no diretório atual.

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

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para carregar um esquema de tabela a partir de um ficheiro JSON através da biblioteca cliente Python, chame o 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}.")

Especificar um ficheiro de esquema quando cria uma tabela

Para criar uma tabela vazia num conjunto de dados existente através de um ficheiro de esquema JSON, faça o seguinte:

bq

bq mk --table project_id:dataset.table path_to_schema_file

Substitua o seguinte:

• project_id: o ID do seu projeto.
• dataset: um conjunto de dados no seu projeto.
• table: o nome da tabela que está a criar.
• path_to_schema_file: o caminho para o ficheiro de esquema no seu computador local.

Por exemplo, o comando seguinte cria uma tabela denominada mytable em mydataset no seu projeto predefinido. O esquema é especificado em myschema.json no diretório atual:

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

Python

Antes de experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para carregar um esquema de tabela a partir de um ficheiro JSON através da biblioteca cliente Python, chame o 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}.")

Especificar um esquema na API

Especifique um esquema de tabela através da API:

• Para especificar um esquema quando carrega dados, chame o método jobs.insert e configure a propriedade schema no recurso JobConfigurationLoad.

• Para especificar um esquema quando cria uma tabela, chame o método tables.insert e configure a propriedade schema no recurso Table.

A especificação de um esquema através da API é semelhante ao processo de criação de um ficheiro de esquema JSON.

Segurança da mesa

Para controlar o acesso a tabelas no BigQuery, consulte o artigo Controle o acesso a recursos com a IAM.

O que se segue?

• Saiba como especificar colunas aninhadas e repetidas numa definição de esquema.
• Saiba mais sobre a deteção automática de esquemas.
• Saiba como carregar dados para o BigQuery.
• Saiba como criar e usar tabelas.