O BigQuery permite especificar 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.
Ao carregar arquivos de exportação Avro, Parquet, ORC, Firestore ou Datastore, o esquema é recuperado automaticamente dos dados de origem autodescritivos.
É possível especificar o esquema de uma tabela das seguintes maneiras:
- Especifique manualmente:
- usando o Console do Cloud;
- Inline usando a ferramenta de linha de comando
bq
.
- Crie um arquivo de esquema no formato JSON.
- Chame o método
jobs.insert
e configure a propriedadeschema
na configuração de jobload
. - Chame o método
tables.insert
e configure o esquema no recurso de tabela usando a propriedadeschema
.
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. Também é possível fornecer a descrição e o modo da coluna.
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.
Nome | Tipo de dado | Descrição |
---|---|---|
Número inteiro | INT64 |
Valores numéricos sem componentes fracionários. |
Ponto flutuante | FLOAT64 |
Valores numéricos aproximados com componentes fracionários. |
Numérico | NUMERIC |
Valores numéricos exatos com componentes fracionários. |
Booleano | BOOL |
"TRUE" ou "FALSE", indiferente a maiúsculas. |
String | STRING |
Dados em caracteres de comprimento variável (Unicode). |
Bytes | BYTES |
Dados binários de comprimento variável. |
Data | DATE |
Uma data de calendário lógico |
Data/hora | DATETIME |
Ano, mês, dia, hora, minuto, segundo e subsegundo |
Hora | TIME |
Um horário, sem depender de uma data específica. |
Carimbo de data/hora | TIMESTAMP |
Ponto absoluto no tempo, com precisão de microssegundo. |
Struct (Record) | STRUCT |
Contêiner de campos ordenados, cada um com um tipo (obrigatório) e um nome de campo (opcional). |
Geografia | GEOGRAPHY |
Um conjunto de pontos na superfície da Terra formado por pontos, linhas e polígonos com bordas geodésicas no esferóide 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 ao consultar 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 |
---|---|
Anulável | A coluna permite valores NULL (padrão). |
Obrigatório | Os valores NULL não são permitidos. |
Repetida | 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 Cloud ou a ferramenta de linha de comando bq
. A especificação manual de esquema é compatível quando você carrega arquivos CSV e JSON (delimitado por nova linha). Ao carregar dados de exportação Avro, Parquet, ORC, Firestore ou Datastore, o esquema é recuperado automaticamente dos dados de origem autodescritivos.
Para especificar manualmente um esquema de tabela:
Console
No Console do Cloud, especifique um esquema usando as opções Adicionar campo ou Editar como texto.
Abra a página do BigQuery no Console do Cloud.
Selecione um conjunto de dados na seção Recursos do painel de navegação.
Clique em Criar tabela no lado direito da janela.
Na página Criar tabela, localizada na seção Origem, selecione Tabela vazia.
Siga estas etapas na página Criar tabela, localizada na seção Destino:
Em Nome do conjunto de dados, escolha o conjunto de dados apropriado.
No campo Nome da tabela, insira o nome da tabela que você está criando.
Verifique se o Tipo de tabela está definido como Tabela nativa.
Na seção Esquema, insira a definição do esquema.
- Opção 1: use Adicionar campo e especifique o Nome, Tipo e Modo de cada campo. No Console do Cloud, não é possível adicionar uma descrição de campo ao usar a opção Adicionar campo. No entanto, é possível adicionar descrições manualmente 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.
Clique em Criar tabela.
bq
Forneça manualmente o esquema in-line no formato field:data_type,field:data_type
usando um dos comandos a seguir:
- Se estiver carregando dados, use o comando
bq load
. - Se você estiver criando uma tabela vazia, use o comando
bq mk
.
Quando você especifica o esquema na linha de comando, não é possível especificar o modo da coluna ou incluir um tipo RECORD
(STRUCT
) e uma descrição de coluna. Todos os modos assumem NULLABLE
como 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 usando a sinalização --source_format
.
Se estiver carregando dados em uma tabela em um projeto diferente do seu projeto padrão, inclua o ID do projeto no seguinte formato: project_id:dataset.table_name
.
Opcional: forneça a sinalização --location
e defina o valor do
local.
bq --location=location load \ --source_format=format \ project_id:dataset.table_name \ path_to_source \ schema
Substitua:
location
: o nome do seu local. A sinalização--location
é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização comoasia-northeast1
. É possível definir um valor padrão para a unidade usando o arquivo .bigqueryrc.format
:NEWLINE_DELIMITED_JSON
ouCSV
.project_id
: o ID do projeto;dataset
: o conjunto de dados que contém a tabela em que você está carregando dados;table_name
: o nome da tabela em que você está carregando 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 do esquema in-line.
Exemplo:
Digite o comando abaixo para carregar dados de um arquivo CSV local chamado myfile.csv
em mydataset.mytable
no seu projeto padrão. O esquema é especificado manualmente e in-line.
bq load \
--source_format=CSV \
mydataset.mytable \
./myfile.csv \
qtr:STRING,sales:FLOAT,year:STRING
Para mais informações sobre como carregar 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 bq mk
com a sinalização --table
ou -t
. Se estiver criando uma tabela em um projeto diferente do seu projeto padrão, adicione o ID do projeto ao comando no seguinte formato: project_id:dataset.table
.
bq mk --table project_id:dataset.table schema
Substitua:
project_id
: o ID 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.
O comando a seguir, por exemplo, cria uma tabela vazia chamada mytable
no seu 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#
Para especificar o esquema de uma tabela ao carregar dados nela:
Para especificar um esquema ao criar uma tabela vazia:
Go
Para especificar o esquema de uma tabela ao carregar dados nela:
Para especificar um esquema ao criar uma tabela vazia:
Java
Para especificar o esquema de uma tabela ao carregar dados nela:
Para especificar um esquema ao criar uma tabela vazia:
Python
Para especificar o esquema de uma tabela ao carregar dados, configure a propriedade LoadJobConfig.schema.
Para especificar um esquema ao criar uma tabela vazia, configure a propriedade Table.schema.
Como especificar um arquivo de esquema JSON
Se você preferir não especificar o esquema manualmente, crie um arquivo de esquema JSON
para usar com a ferramenta de linha de comando bq
. Um arquivo de esquema JSON consiste em uma matriz JSON que contém o seguinte:
- (Opcional) descrição
- nome
- Tipo de dado
- (Opcional) Modo (se não for especificado, o modo padrão é
NULLABLE
)
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 por colchetes de início e fim []
. É preciso 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. Este esquema tem três 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 seu arquivo de esquema JSON, é possível especificá-lo usando a ferramenta de linha de comando bq
.
Não é possível usar um arquivo de esquema com o Console do Cloud ou a API.
Forneça manualmente o arquivo de esquema:
- Se estiver carregando dados, use o comando
bq load
. - Se você estiver criando uma tabela vazia, use o comando
bq mk
.
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 arquivo de esquema JSON armazenado no Cloud Storage ou no 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
Substitua:
location
: o nome do seu local. A sinalização--location
é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização comoasia-northeast1
. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;format
:NEWLINE_DELIMITED_JSON
ouCSV
.project_id
: o ID do projeto;dataset
: o conjunto de dados que contém a tabela em que você está carregando dados;table
: o nome da tabela em que você está carregando dados;path_to_data_file
: o local do arquivo de dados CSV ou JSON na sua máquina local ou no Cloud Storage;path_to_schema_file
: o caminho para o arquivo de esquema na máquina local.
Exemplo:
Digite o comando abaixo para carregar dados de um arquivo CSV local chamado myfile.csv
em mydataset.mytable
no seu projeto padrão. O esquema é especificado em myschema.json
.
bq 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
Substitua:
project_id
: o ID 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.
O comando a seguir, por exemplo, cria uma tabela chamada mytable
em mydataset
no seu projeto padrão. O esquema é especificado em myschema.json
:
bq mk --table mydataset.mytable ./myschema.json
Como especificar um esquema na API
Especificar um esquema de tabela usando a API, siga estas etapas:
Para especificar um esquema ao carregar dados, chame o método
jobs.insert
e configure a propriedadeschema
no recursoJobConfigurationLoad
.Para especificar um esquema ao criar uma tabela, chame o método
tables.insert
e configure a propriedadeschema
no recursoTable
.
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
- Saiba como especificar colunas aninhadas e repetidas em uma definição de esquema.
- Saiba mais sobre a detecção automática de esquema.
- Saiba mais sobre o carregamento de dados no BigQuery.
- Saiba mais sobre Como criar e usar tabelas.