Como especificar um esquema

Com o BigQuery, você especifica o esquema de uma tabela ao carregar dados nela e ao criar uma tabela vazia. Também é possível usar a detecção automática de esquema em formatos de dados compatíveis. Quando você carrega arquivos Avro, Parquet, ORC, de exportação do Cloud Firestore ou de exportação do Cloud Datastore, o esquema é recuperado automaticamente dos dados de origem autodescritos.

Especifique o esquema da tabela de uma das seguintes maneiras:

Depois de carregar os dados ou criar uma tabela vazia, é possível modificar a definição do esquema da tabela.

Componentes do esquema

Quando você especifica um esquema de tabela, é necessário fornecer o nome e o tipo de dados de cada coluna. Opcionalmente, você também pode fornecer a descrição e o modo.

Nomes de coluna

O nome da coluna precisa conter apenas letras (a-z, A-Z), números (0-9) ou sublinhados (_) e começar com uma letra ou sublinhado. O comprimento máximo é de 128 caracteres. Não é possível usar estes prefixos nos nomes da coluna:

  • _TABLE_
  • _FILE_
  • _PARTITION

Os nomes de coluna duplicados não são permitidos, mesmo em caso de diferença de maiúsculas e minúsculas. Por exemplo, uma coluna chamada Column1 é considerada idêntica a uma coluna chamada column1.

Descrições de coluna

Cada coluna pode incluir uma descrição opcional. Ela é uma string com comprimento máximo de 1.024 caracteres.

Tipos de dados do SQL padrão

Com o SQL padrão do BigQuery, você especifica os tipos de dados a seguir no esquema. O tipo de dados é obrigatório.

Tipo de dado Descrição
Integer Valores numéricos sem componentes fracionários.
Floating point Valores numéricos aproximados com componentes fracionários.
Numeric Valores numéricos exatos com componentes fracionários.
Boolean "TRUE" ou "FALSE", indiferente a maiúsculas.
String Dados em caracteres de comprimento variável (Unicode).
Bytes Dados binários de comprimento variável.
Data Uma data de calendário lógico.
Datetime Ano, mês, dia, hora, minuto, segundo e subsegundo.
Time Um horário, sem depender de uma data específica.
Timestamp Ponto absoluto no tempo, com precisão de microssegundo.
Struct (Record) Contêiner de campos ordenados, cada um com um tipo (obrigatório) e um nome de campo (opcional).
Geography Um conjunto na superfície da Terra composto por pontos, linhas e polígonos com bordas geodésicas no esferoide de referência WGS84.

Para saber mais sobre os tipos de dados no SQL padrão, consulte Tipos de dados do SQL padrão.

Também é possível declarar um tipo de matriz quando você consulta dados. Para saber mais, consulte Como trabalhar com matrizes.

Modos

O BigQuery é compatível com os modos para colunas a seguir. O modo é opcional. Se ele não for especificado, o padrão da coluna é NULLABLE.

Modo Descrição
Nullable A coluna permite valores NULL (padrão).
Required Os valores NULL não são permitidos.
Repeated A coluna contém uma matriz de valores do tipo especificado.

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

Como especificar os esquemas manualmente

Ao carregar dados ou criar uma tabela vazia, é possível especificar manualmente o esquema da tabela usando o Console do GCP, a IU da Web clássica do BigQuery ou a ferramenta de linha de comando. A especificação manual de esquema é compatível quando você carrega arquivos CSV e JSON (delimitado por nova linha). Quando você carrega dados de Avro, Parquet, ORC, de exportação do Cloud Firestore ou de exportação do Cloud Datastore, o esquema é recuperado automaticamente dos dados de origem autodescritos.

Para especificar manualmente um esquema de tabela:

Console

Na IU da Web do BigQuery, é possível especificar um esquema usando a opção Adicionar campo ou Editar como texto.

  1. Abra a IU da Web do BigQuery no Console do GCP.
    Acessar a IU da Web do BigQuery

  2. Selecione um conjunto de dados na seção Recursos do painel de navegação. Clique em Criar tabela do lado direito da janela.

    Criar tabela

  3. Na página Criar tabela, na seção Origem, selecione Criar tabela vazia.

    Criar origem da tabela

  4. Na página Criar tabela, na seção Destino:

    • Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.

      Escolher conjunto de dados

    • No campo Nome da tabela, insira o nome da tabela que você está criando no BigQuery.

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

  5. Na seção Esquema, insira a definição do esquema.

    • Opção 1: use Adicionar campo e especifique o nome, o tipo e o modo de cada campo. Na IU da Web do BigQuery, não é possível adicionar uma descrição de campo quando você usa a opção Adicionar campo. No entanto, é possível adicionar descrições manualmente na IU depois de carregar os dados.
    • Opção 2: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON.

  6. Clique em Criar tabela.

IU clássica

Na IU da Web do BigQuery, é possível especificar um esquema usando a opção Adicionar campo ou Editar como texto.

  1. Acesse a IU da Web do BigQuery.

    Acessar a IU da Web do BigQuery

  2. Clique no ícone de seta para baixo ícone de seta para baixo ao lado do nome do conjunto de dados na navegação e em Criar nova tabela. O processo de carregamento de dados é igual ao de criação de uma tabela vazia.

  3. Na página Criar tabela:

    • Em Dados de origem, clique em Criar a partir da fonte se você estiver carregando dados ou selecione Criar tabela vazia.
    • Em Tabela de destino, escolha o conjunto de dados e insira o nome da tabela no campo Nome da tabela de destino.

    • Em Esquema, escolha uma das seguintes opções para fazer a especificação manual:

      • Opção 1: use Adicionar campo e especifique o nome, o tipo e o modo de cada campo. Na IU da Web do BigQuery, não é possível adicionar uma descrição de campo quando você usa a opção Adicionar campo. No entanto, é possível adicionar descrições manualmente na IU depois de carregar os dados.

        Adicionar esquema usando "Adicionar campos"

      • Opção 2: clique em Editar como texto e cole o esquema na forma de uma matriz JSON. Com ela, você gera o esquema usando um processo igual ao de criação de um arquivo de esquema JSON.

        Adicionar esquema como matriz JSON

    • Clique em Criar tabela.

Linha de comando

Forneça in-line e manualmente o esquema no formato [FIELD]:[DATA_TYPE],[FIELD]:[DATA_TYPE] por meio do:

  • comando load se você estiver carregando dados;
  • comando mk se você estiver criando uma tabela vazia.

Quando você especifica o esquema na linha de comando, não é possível incluir um tipo RECORD (STRUCT) nem uma descrição de coluna. Também não é possível especificar o modo da coluna. Todos os modos são definidos como NULLABLE por padrão. Para incluir descrições, modos e tipos RECORD, forneça um arquivo de esquema JSON.

Para carregar dados em uma tabela usando uma definição de esquema in-line, insira o comando load e especifique o formato de dados por meio da sinalização --source_format. Se você estiver carregando dados para uma tabela em um projeto diferente do padrão, inclua o código do projeto no seguinte formato: [PROJECT_ID]:[DATASET].[TABLE_NAME].

Insira a sinalização --location e defina o valor como seu local.

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

Em que:

  • [LOCATION] é o nome do local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [FORMAT] é NEWLINE_DELIMITED_JSON ou CSV;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que contém a tabela em que você carregará dados;
  • [TABLE] é o nome da tabela em que você carregará dados;
  • [PATH_TO_SOURCE] é o local do arquivo de dados CSV ou JSON na sua máquina local ou no Cloud Storage;
  • [SCHEMA] é a definição de esquema in-line.

Exemplos:

Digite o seguinte comando para carregar dados de um arquivo CSV local chamado myfile.csv em mydataset.mytable no seu projeto padrão. O esquema é especificado manualmente in-line. mydataset foi criado na multirregião US.

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

Digite o seguinte comando para carregar dados de um arquivo CSV local chamado myfile.csv em mydataset.mytable no seu projeto padrão. mydataset foi criado na região asia-northeast1. O esquema é especificado manualmente e in-line.

bq --location=asia-northeast1 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 Introdução ao carregamento de dados.

Para especificar uma definição de esquema in-line ao criar uma tabela vazia, insira o comando mk com a sinalização --table ou -t. Se você estiver criando uma tabela em um projeto diferente do padrão, adicione o código do projeto ao comando no seguinte formato: [PROJECT_ID]:[DATASET].[TABLE].

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

Em que:

  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é um conjunto de dados no projeto;
  • [TABLE] é o nome da tabela que você está criando;
  • [SCHEMA] é uma definição de esquema in-line.

Por exemplo, o comando a seguir cria uma tabela vazia chamada mytable no projeto padrão. O esquema é especificado manualmente e in-line.

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

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

C#

Antes de testar esta amostra, siga as instruções de configuração do C# no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery C#.

Para especificar o esquema de uma tabela ao carregar dados nela: 
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 um esquema ao criar uma tabela vazia: 

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

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

Go

Antes de testar esta amostra, siga as instruções de configuração do Go no Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para mais informações, consulte a documentação de referência da API BigQuery Go.

Para especificar o esquema de uma tabela ao carregar dados nela: 
// 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 um esquema ao criar uma tabela vazia: 

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

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

Python

Antes de testar esta amostra, siga as instruções de configuração do Python em Guia de início rápido do BigQuery: como usar bibliotecas de cliente. Para ver mais informações, consulte a documentação de referência da API BigQuery para Python.

Para especificar o esquema de uma tabela ao carregar dados, configure a propriedade 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 um esquema ao criar uma tabela vazia, configure a propriedade 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)
)

Como especificar um arquivo de esquema JSON

Se você prefere não especificar o esquema manualmente, crie um arquivo de esquema JSON para usar com a CLI. Ele consiste em uma matriz JSON, que contém as propriedades de coluna a seguir:

Como criar um arquivo de esquema JSON

Basta inserir o comando a seguir usando um editor de texto apropriado:

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

A matriz JSON é indicada pelos colchetes de início e fim []. Você precisa separar todas as entradas de coluna com uma vírgula: },.

Para gravar um esquema de tabela existente em um arquivo local, insira o comando a seguir:

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

É possível usar o arquivo de saída como ponto de partida do seu próprio arquivo de esquema JSON. Ao usar essa abordagem, verifique se o arquivo contém apenas a matriz JSON que representa o esquema da tabela.

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

Como usar um arquivo de esquema JSON

Depois de criar o arquivo de esquema JSON, é possível especificá-lo na linha de comando. Não é possível usar um arquivo de esquema com o Console do GCP, a IU da Web clássica do BigQuery ou a API.

Forneça manualmente o arquivo de esquema por meio do:

  • comando load se você estiver carregando dados;
  • comando mk se você estiver criando uma tabela vazia.

Quando você fornece um arquivo de esquema JSON, ele precisa estar armazenado em uma localização legível localmente. Não é possível especificar um que esteja armazenado no Cloud Storage ou no Google Drive.

Como especificar um arquivo de esquema ao carregar dados

O comando a seguir carrega dados em uma tabela usando a definição de esquema em um arquivo JSON:

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

Em que:

  • [LOCATION] é o nome do local. A sinalização --location é opcional. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, poderá definir o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [FORMAT] é NEWLINE_DELIMITED_JSON ou CSV;
  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é o conjunto de dados que contém a tabela em que você carregará dados;
  • [TABLE] é o nome da tabela em que você carregará dados;
  • [PATH_TO_DATA_FILE] é a localização do arquivo de dados CSV ou JSON na máquina local ou no Google Cloud Storage;
  • [SCHEMA_FILE] é o caminho para o arquivo de esquema na máquina local.

Exemplos:

Digite o comando a seguir para carregar dados de um arquivo CSV local chamado myfile.csv em mydataset.mytable em seu projeto padrão. mydataset foi criado na multirregião US. O esquema é especificado em myschema.json:

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

Digite o comando a seguir para carregar dados de um arquivo CSV local chamado myfile.csv em mydataset.mytable no seu projeto padrão. mydataset foi criado na região asia-northeast1. O esquema é especificado em myschema.json:

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

Como especificar um arquivo de esquema ao criar uma tabela

O comando a seguir cria uma tabela vazia em um conjunto de dados existente usando a definição do esquema em um arquivo JSON:

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

Em que:

  • [PROJECT_ID] é o código do projeto;
  • [DATASET] é um conjunto de dados no projeto;
  • [TABLE] é o nome da tabela que você está criando;
  • [PATH_TO_SCHEMA_FILE] é o caminho para o arquivo de esquema na máquina local.

Por exemplo, o comando a seguir cria uma tabela chamada mytable em mydataset no projeto padrão. O esquema é especificado em myschema.json:

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

Como especificar um esquema na API

Para especificar um esquema de tabela usando a API, siga estas etapas:

O processo de especificação de esquema por meio da API é semelhante ao de criação de um arquivo de esquema JSON.

Próximas etapas

Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Esta página
Comentários sobre a documentação
BigQuery
Comentários sobre o produto
Precisa de ajuda? Acesse nossa página de suporte.