Neste documento, você verá como modificar definições de esquema para tabelas atuais do BigQuery. O BigQuery tem compatibilidade nativa com as seguintes modificações de esquema:
- Adicionar colunas a uma definição de esquema.
- Relaxar o modo de uma coluna de
REQUIRED
paraNULLABLE
.
É válido criar uma tabela sem definir um esquema inicial e, depois, adicionar uma definição de esquema a ela.
Todas as outras modificações de esquema são incompatíveis e exigem soluções alternativas manuais, como:
- alterar o nome de uma coluna;
- como alterar o tipo de dados de uma coluna;
- como alterar o modo de uma coluna, além de transformar colunas
REQUIRED
emNULLABLE
; - Excluir uma coluna
Para informações sobre alterações de esquema incompatíveis que exijam soluções alternativas, consulte Como alterar esquemas de tabela manualmente.
Como adicionar colunas à definição de esquema de uma tabela
É possível adicionar colunas à definição de esquema de uma tabela existente:
- manualmente (cria uma coluna vazia);
- quando você usa um job de carregamento ou de consulta para substituir uma tabela;
- quando você anexa dados a uma tabela usando um job de carregamento ou de consulta.
Qualquer coluna que você adicionar precisará aderir às regras do BigQuery para nomes de colunas. Para mais informações sobre como criar componentes de esquema, consulte Como especificar um esquema.
Como adicionar manualmente uma coluna vazia
Use estes métodos para adicionar uma coluna vazia a uma tabela atual:
- Como usar o Console do Cloud
- Use o comando
bq update
da ferramenta de linha de comandobq
. - Chame o
tables.patch
método de API - Como usar a instrução de linguagem de definição de dados (DDL, na sigla em inglês)
ALTER TABLE ADD COLUMN
. - Como usar bibliotecas de cliente
Ao adicionar novas colunas a um esquema de tabela atual, as colunas precisarão ser NULLABLE
ou REPEATED
. Não é possível adicionar uma coluna REQUIRED
a um esquema de tabela atual. Se você tentar adicionar uma coluna REQUIRED
a um esquema de tabela existente na API ou na ferramenta de linha de comando bq
, o seguinte erro será retornado: as colunas BigQuery error in update operation: Provided Schema does not
match Table project_id:dataset.table. Cannot add required columns to
an existing schema.
REQUIRED
poderão ser adicionadas somente quando você criar uma tabela ao carregar dados ou quando você criar uma tabela vazia com uma definição de esquema.
Depois de adicionar uma nova coluna à definição de esquema da tabela, é possível carregar os dados na nova coluna usando:
- uma instrução DML para executar uma atualização em massa em cada linha;
- um job de carregamento que substitua a tabela;
- um resultado de consulta que substitua a tabela.
Para adicionar colunas vazias à definição de esquema de uma tabela:
Console
No painel Explorer, expanda o projeto e o conjunto de dados e selecione a tabela.
No painel de detalhes, clique na guia Visualizar.
Clique em Editar esquema. Talvez seja necessário rolar para ver esse botão.
Na página Esquema atual, em Novos campos, clique em Adicionar campo.
- Em Nome, digite o nome da coluna.
- Em Tipo, escolha o tipo de dados.
- Em Modo, escolha
NULLABLE
ouREPEATED
.
Ao terminar de adicionar colunas, clique em Salvar.
SQL
Para adicionar uma nova coluna a uma tabela atual usando a instrução DDL
ALTER TABLE ADD COLUMN
, siga estas etapas:
No Console do Cloud, clique em Escrever nova consulta.
Digite a instrução DDL no campo Editor de consultas.
ALTER TABLE mydataset.mytable ADD COLUMN A STRING
Clique em Executar.
Para mais informações sobre como usar o SQL padrão, consulte Como alternar dialetos SQL.
bq
Emita o comando bq update
e forneça um arquivo de esquema JSON. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato: project_id:dataset
.
bq update project_id:dataset.table schema
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema é o caminho para o arquivo de esquema JSON na sua máquina local.
Ao especificar o esquema usando a ferramenta de linha de comando bq
, não é possível incluir um tipo RECORD
(STRUCT
) ou uma descrição de coluna, nem especificar o modo da coluna. Todos os modos assumem NULLABLE
como padrão.
Se você tentar adicionar colunas usando uma definição de esquema in-line, será necessário fornecer toda a definição de esquema, incluindo as novas colunas. Como não é possível especificar modos de coluna usando uma definição de esquema in-line, a atualização tentará alterar qualquer coluna REQUIRED
atual para NULLABLE
. Isso resultará na mensagem de erro a seguir: BigQuery error in update
operation: Provided Schema does not match Table
project_id:dataset.table. Field field has changed mode
from REPEATED to NULLABLE.
O método preferido de adicionar colunas a uma tabela existente usando a ferramenta de linha de comando bq
é fornecer um arquivo de esquema JSON.
Para adicionar colunas vazias ao esquema de uma tabela usando um arquivo de esquema JSON, siga estas etapas:
Primeiro, emita o comando
bq show
com a sinalização--schema
e grave o esquema da tabela atual em um arquivo. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:project_id:dataset
.bq show \ --schema \ --format=prettyjson \ project_id:dataset.table > schema_file
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema_file é o arquivo de definição de esquema gravado na máquina local.
Por exemplo, para gravar a definição de esquema de
mydataset.mytable
em um arquivo, digite o comando a seguir.mydataset.mytable
está no projeto padrão.bq show \ --schema \ --format=prettyjson \ mydataset.mytable > /tmp/myschema.json
Abra o arquivo de esquema em um editor de texto. Ele será semelhante a este:
[ { "mode": "REQUIRED", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "mode": "REPEATED", "name": "column3", "type": "STRING" } ]
Adicione as novas colunas ao final da definição de esquema. Caso tente adicionar novas colunas em outro local na matriz, este erro será retornado:
BigQuery error in update operation: Precondition Failed
.Com um arquivo JSON, é possível especificar descrições, modos
NULLABLE
ouREPEATED
e tiposRECORD
para novas colunas. Por exemplo, com a definição de esquema da etapa anterior, a nova matriz JSON será semelhante ao exemplo a seguir. Neste exemplo, é adicionada uma nova colunaNULLABLE
chamadacolumn4
.column4
inclui uma descrição.[ { "mode": "REQUIRED", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "mode": "REPEATED", "name": "column3", "type": "STRING" }, { "description": "my new column", "mode": "NULLABLE", "name": "column4", "type": "STRING" } ]
Para mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.
Depois de atualizar o arquivo de esquema, emita o comando a seguir para atualizar o esquema da tabela. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:
project_id:dataset
.bq update project_id:dataset.table schema
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema é o caminho para o arquivo de esquema JSON na sua máquina local.
Por exemplo, digite o comando a seguir para atualizar a definição de esquema de
mydataset.mytable
no projeto padrão. O caminho para o arquivo de esquema na máquina local é/tmp/myschema.json
.bq update mydataset.mytable /tmp/myschema.json
API
Chame o método tables.patch
e use a propriedade schema
para adicionar colunas vazias à definição de esquema. Como o método tables.update
substitui todo o recurso da tabela, é melhor usar o método tables.patch
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.
Anexe um novo objeto SchemaField a uma cópia de Table.schema e substitua o valor da propriedade Table.schema pelo esquema atualizado.Como adicionar uma coluna aninhada a um RECORD
Além de adicionar novas colunas a um esquema de tabela, também é possível acrescentar novas colunas aninhadas a um RECORD
. O processo de adição de uma nova coluna aninhada é muito parecido com o de adição de uma nova coluna comum.
Console
Ainda não é possível adicionar um novo campo aninhado a uma coluna RECORD
atual no Console do Cloud.
bq
Emita o comando bq update
e forneça um arquivo de esquema JSON que inclua o campo aninhado na definição de esquema da coluna RECORD
atual. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato: project_id:dataset
.
bq update project_id:dataset.table schema
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema é o caminho para o arquivo de esquema JSON na sua máquina local.
Ao especificar o esquema usando a ferramenta de linha de comando bq
, não é possível incluir um tipo RECORD
(STRUCT
) ou uma descrição de coluna, nem especificar o modo da coluna. Todos os modos assumem NULLABLE
como padrão. Sendo assim, se você for adicionar uma nova coluna aninhada a um RECORD
, será necessário fornecer um arquivo de esquema JSON.
Para adicionar uma coluna aninhada a um RECORD
usando um arquivo de esquema JSON, siga estas etapas:
Primeiro, emita o comando
bq show
com a sinalização--schema
e grave o esquema da tabela atual em um arquivo. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:project_id:dataset.table
.bq show \ --schema \ --format=prettyjson \ project_id:dataset.table > schema_file
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema_file é o arquivo de definição de esquema gravado na máquina local.
Por exemplo, para gravar a definição de esquema de
mydataset.mytable
em um arquivo, digite o comando a seguir.mydataset.mytable
está no projeto padrão.bq show \ --schema \ --format=prettyjson \ mydataset.mytable > /tmp/myschema.json
Abra o arquivo de esquema em um editor de texto. O esquema será semelhante ao mostrado abaixo. Neste exemplo,
column3
é uma coluna repetida aninhada. As colunas aninhadas sãonested1
enested2
. A matrizfields
lista os campos aninhados emcolumn3
.[ { "mode": "REQUIRED", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "fields": [ { "mode": "NULLABLE", "name": "nested1", "type": "STRING" }, { "mode": "NULLABLE", "name": "nested2", "type": "STRING" } ], "mode": "REPEATED", "name": "column3", "type": "RECORD" } ]
Adicione a nova coluna aninhada ao final da matriz
fields
. Neste exemplo,nested3
é a nova coluna aninhada.[ { "mode": "REQUIRED", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "fields": [ { "mode": "NULLABLE", "name": "nested1", "type": "STRING" }, { "mode": "NULLABLE", "name": "nested2", "type": "STRING" }, { "mode": "NULLABLE", "name": "nested3", "type": "STRING" } ], "mode": "REPEATED", "name": "column3", "type": "RECORD" } ]
Para mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.
Depois de atualizar o arquivo de esquema, emita o comando a seguir para atualizar o esquema da tabela. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:
project_id:dataset
.bq update project_id:dataset.table schema
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema é o caminho para o arquivo de esquema JSON na sua máquina local.
Por exemplo, digite o comando a seguir para atualizar a definição de esquema de
mydataset.mytable
no projeto padrão. O caminho para o arquivo de esquema na máquina local é/tmp/myschema.json
.bq update mydataset.mytable /tmp/myschema.json
API
Chame o método tables.patch
e use a propriedade schema
para adicionar colunas aninhadas à definição de esquema. Como o método tables.update
substitui todo o recurso da tabela, é melhor usar o método tables.patch
.
Como adicionar uma coluna ao substituir ou anexar dados
É possível adicionar novas colunas a uma tabela atual ao carregar dados nela e optar por substituí-la. Ao substituir uma tabela atual, o esquema dos dados sendo carregados é usado para substituir o esquema dessa tabela. Para informações sobre como substituir uma tabela usando um job de carregamento, consulte estes tópicos:
- Como anexar ou substituir uma tabela com dados Avro
- Como anexar ou substituir uma tabela com dados Parquet
- Como anexar ou substituir uma tabela com dados ORC
- Como anexar ou substituir uma tabela com dados CSV
- Como anexar ou substituir uma tabela com dados JSON
Também é possível adicionar novas colunas a uma tabela existente quando você adiciona dados a ela usando um job de carregamento ou de consulta.
Como adicionar uma coluna a um job de anexação de carregamento
Use estes métodos para adicionar colunas a uma tabela e anexar dados a ela em um job de carregamento:
- Use o comando
bq load
da ferramenta de linha de comandobq
. - Chamada do método
jobs.insert
da API e configuração de um job deload
- Como usar bibliotecas de cliente
O Console do Cloud não é compatível com a inclusão de uma coluna em uma tabela atual durante uma operação de anexação.
Ao adicionar colunas usando uma operação de anexação em um job de carregamento, o esquema atualizado pode ser:
- detectado automaticamente (para arquivos CSV e JSON);
- especificado em um arquivo de esquema JSON (para arquivos CSV e JSON);
- recuperado dos dados de origem autoexplicativos dos arquivos de exportação Avro, ORC, Parquet e Cloud Datastore.
Se você especificar o esquema em um arquivo JSON, as novas colunas precisarão ser definidas nele.
Se não houver novas definições de coluna, o erro a seguir será retornado ao tentar anexar os dados: Error while reading data, error message:
parsing error in row starting at position int: No such field:
field.
.
Ao adicionar novas colunas durante uma operação de anexação, os valores nelas são definidos como NULL
nas linhas atuais.
Para adicionar uma nova coluna ao anexar dados a uma tabela durante um job de carregamento, siga estas etapas:
Console
Não é possível adicionar novas colunas a uma tabela atual ao carregar dados usando o Console do Cloud.
bq
Use o comando bq load
para carregar os dados e especifique a sinalização --noreplace
para indicar que você os está anexando a uma tabela atual.
Se os dados sendo anexados estiverem em CSV ou em formato JSON delimitado por nova linha, especifique a sinalização --autodetect
para usar a detecção automática de esquema ou forneça o esquema em um arquivo de esquema JSON. As colunas adicionadas podem ser inferidas automaticamente dos arquivos de exportação do Avro ou do Cloud Datastore.
Defina a sinalização --schema_update_option
como ALLOW_FIELD_ADDITION
para indicar que o dados sendo anexados contêm novas colunas.
Se a tabela sendo anexada estiver em um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no formato a seguir: project_id:dataset
.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Digite o comando load
a seguir:
bq --location=location load \ --noreplace \ --autodetect \ --schema_update_option=ALLOW_FIELD_ADDITION \ --source_format=format \ project_id:dataset.table \ 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, 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
,CSV
,AVRO
,PARQUET
,ORC
ouDATASTORE_BACKUP
. - project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela.
- table é o nome da tabela que você está anexando.
- path_to_source é um URI do Cloud Storage completo, uma lista de URIs separada por vírgula ou o caminho para um arquivo de dados na máquina local.
- schema é o caminho para um arquivo de esquema JSON local. Um arquivo de esquema é necessário somente para arquivos CSV e JSON quando
--autodetect
não estiver especificado. Os esquemas do Avro e do Cloud Datastore são inferidos com base nos dados de origem.
Por exemplo:
Digite os comandos a seguir para adicionar um arquivo local do Avro, /tmp/mydata.avro
, a mydataset.mytable
usando um job de carregamento. Como os esquemas podem ser inferidos automaticamente a partir dos dados do Avro, não é necessário usar a sinalização --autodetect
. mydataset
está no projeto padrão.
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=AVRO \
mydataset.mytable \
/tmp/mydata.avro
Digite o comando a seguir para anexar um arquivo de dados JSON delimitado por nova linha no Cloud Storage a mydataset.mytable
usando um job de carregamento. A sinalização --autodetect
é usada para detectar as novas colunas. mydataset
está no projeto padrão.
bq load \
--noreplace \
--autodetect \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json
Digite o comando a seguir para anexar um arquivo de dados JSON delimitado por nova linha no Cloud Storage a mydataset.mytable
usando um job de carregamento. O esquema contendo as novas colunas está especificado em um arquivo de esquema JSON local, /tmp/myschema.json
. mydataset
está em myotherproject
, e não no projeto padrão.
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_ADDITION \
--source_format=NEWLINE_DELIMITED_JSON \
myotherproject:mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json
API
Chame o método jobs.insert
. Em seguida, configure um job de load
e defina as propriedades a seguir:
- Faça referência aos dados no Cloud Storage usando a propriedade
sourceUris
. - Especifique o formato de dados definindo a propriedade
sourceFormat
. - Especifique o esquema na propriedade
schema
. - Especifique a opção de atualização de esquema usando a propriedade
schemaUpdateOptions
. - Defina a disposição de gravação da tabela de destino como
WRITE_APPEND
usando a propriedadewriteDisposition
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.
Como adicionar uma coluna em um job de anexação de consulta
Use estes métodos para adicionar colunas a uma tabela e anexar os resultados da consulta a ela:
- Use o comando
bq query
da ferramenta de linha de comandobq
. - Chamada do método
jobs.insert
da API e configuração de um job dequery
- Como usar bibliotecas de cliente
O Console do Cloud não é compatível com a inclusão de uma coluna durante uma operação de anexação.
Ao adicionar colunas usando uma operação de anexação em um job de consulta, o esquema dos resultados dessa consulta é usado para atualizar o esquema da tabela de destino. Não é possível consultar uma tabela em um local e gravar os resultados em uma tabela de outro local.
Para adicionar uma nova coluna ao anexar dados a uma tabela durante um job de consulta:
Console
Não é possível adicionar novas colunas a uma tabela atual ao anexar resultados de consulta usando o Console do Cloud.
bq
Use o comando bq query
para consultar seus dados e especifique a sinalização --destination_table
para indicar qual tabela está sendo anexada.
Para mostrar que você está anexando resultados de consulta a uma tabela de destino atual, especifique a sinalização --append_table
.
Defina a sinalização --schema_update_option
como ALLOW_FIELD_ADDITION
para indicar que os resultados da consulta sendo anexados contêm novas colunas.
Especifique a sinalização use_legacy_sql=false
para usar a sintaxe SQL padrão para a consulta.
Se a tabela sendo anexada estiver em um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no formato a seguir: project_id:dataset
. A tabela sendo consultada e a tabela de destino precisam estar no mesmo local.
Opcional: forneça a sinalização --location
e defina o valor do
local.
bq --location=location query \ --destination_table project_id:dataset.table \ --append_table \ --schema_update_option=ALLOW_FIELD_ADDITION \ --use_legacy_sql=false \ 'query'
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, defina o valor da sinalização comoasia-northeast1
. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. Não é possível anexar resultados de consulta em uma tabela de outro local. - project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está anexando.
- table é o nome da tabela que você está anexando.
- query é uma consulta na sintaxe SQL padrão.
Por exemplo:
Digite o comando a seguir para consultar mydataset.mytable
no projeto padrão e para anexar os resultados da consulta a mydataset.mytable2
, que também está no projeto padrão.
bq query \
--destination_table mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
column1,column2
FROM
mydataset.mytable'
Digite o comando a seguir para consultar mydataset.mytable
no projeto padrão e para anexar os resultados da consulta a mydataset.mytable2
em myotherproject
.
bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_ADDITION \
--use_legacy_sql=false \
'SELECT
column1,column2
FROM
mydataset.mytable'
API
Chame o método jobs.insert
. Em seguida, configure um job de query
e defina as propriedades a seguir:
- Especifique a tabela de destino usando a propriedade
destinationTable
. - Defina a disposição de gravação da tabela de destino como
WRITE_APPEND
usando a propriedadewriteDisposition
. - Especifique a opção de atualização de esquema usando a propriedade
schemaUpdateOptions
. - Especifique a consulta SQL padrão usando a propriedade
query
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.
Como transformar o modo de uma coluna
Atualmente, a única modificação compatível com o modo de uma coluna é alterá-la de REQUIRED
para NULLABLE
. A alteração do modo de uma coluna de REQUIRED
para NULLABLE
também é chamada de relaxamento de coluna. É possível relaxar colunas REQUIRED
:
- manualmente;
- ao substituir uma tabela usando um job de carregamento ou de consulta;
- ao anexar dados a uma tabela usando um job de consulta.
Como alterar manualmente colunas REQUIRED
para NULLABLE
Use estes métodos para alterar manualmente o modo de uma coluna de REQUIRED
para NULLABLE
:
- Como usar o Console do Cloud
- Use o comando
bq update
da ferramenta de linha de comandobq
. - Chame o
tables.patch
método de API - use bibliotecas de cliente.
Para alterar manualmente o modo de uma coluna de REQUIRED
para NULLABLE
:
Console
No painel Explorer, expanda o projeto e o conjunto de dados e selecione a tabela.
No painel de detalhes, clique na guia Visualizar.
Clique em Editar esquema. Talvez seja necessário rolar para ver esse botão.
Na página Esquema atual, localize o campo que você quer alterar.
Na lista suspensa Modo, selecione
NULLABLE
.Clique em Save.
bq
Primeiro, emita o comando
bq show
com a sinalização--schema
e grave o esquema da tabela atual em um arquivo. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:project_id:dataset
.bq show \ --schema \ --format=prettyjson \ project_id:dataset.table > schema_file
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema_file é o arquivo de definição de esquema gravado na máquina local.
Por exemplo, para gravar a definição de esquema de
mydataset.mytable
em um arquivo, digite o comando a seguir.mydataset.mytable
está no projeto padrão.bq show \ --schema \ --format=prettyjson \ mydataset.mytable > /tmp/myschema.json
Abra o arquivo de esquema em um editor de texto. Ele será semelhante a este:
[ { "mode": "REQUIRED", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "mode": "REPEATED", "name": "column3", "type": "STRING" } ]
Altere o modo de uma coluna atual de
REQUIRED
paraNULLABLE
. Neste exemplo, o modo decolumn1
é relaxado.[ { "mode": "NULLABLE", "name": "column1", "type": "STRING" }, { "mode": "REQUIRED", "name": "column2", "type": "FLOAT" }, { "mode": "REPEATED", "name": "column3", "type": "STRING" } ]
Para mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.
Depois de atualizar o arquivo de esquema, emita o comando a seguir para atualizar o esquema da tabela. Se a tabela que você está atualizando estiver em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados neste formato:
project_id:dataset
.bq update project_id:dataset.table schema
Em que:
- project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está atualizando;
- table é o nome da tabela que você está atualizando.
- schema é o caminho para o arquivo de esquema JSON na sua máquina local.
Por exemplo, digite o comando a seguir para atualizar a definição de esquema de
mydataset.mytable
no projeto padrão. O caminho para o arquivo de esquema na máquina local é/tmp/myschema.json
.bq update mydataset.mytable /tmp/myschema.json
API
Chame tables.patch
e use a propriedade schema
para alterar uma coluna REQUIRED
para NULLABLE
na definição do esquema. Como o método tables.update
substitui todo o recurso da tabela, é melhor usar o método tables.patch
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.
Substitua a propriedade Table.schema por uma lista de objetosSchemaField com a propriedade mode definida como'NULLABLE'
Como mudar REQUIRED
para NULLABLE
em um job de carregamento ou de consulta
É possível relaxar colunas REQUIRED
para NULLABLE
no esquema de uma tabela atual ao carregar dados nela e optar por substituí-la. Ao substituir uma tabela atual, o esquema dos dados sendo carregados é usado para substituir o esquema dessa tabela. Para informações sobre como substituir uma tabela usando um job de carregamento, consulte estes tópicos:
- Como anexar ou substituir uma tabela com dados Avro
- Como anexar ou substituir uma tabela com dados Parquet
- Como anexar ou substituir uma tabela com dados ORC
- Como anexar ou substituir uma tabela com dados CSV
- Como anexar ou substituir uma tabela com dados JSON
Também é possível relaxar as colunas REQUIRED
para NULLABLE
no esquema de uma tabela atual ao anexar dados a ela usando um job de consulta.
Como mudar REQUIRED
para NULLABLE
em um job de anexação de carregamento
Use estes métodos para relaxar o modo de uma coluna e anexar dados a uma tabela em um job de carregamento:
- Use o comando
bq load
da ferramenta de linha de comandobq
. - Chamada do método
jobs.insert
da API e configuração de um job de carregamento - Como usar bibliotecas de cliente
O Console do Cloud não é compatível com a alteração do modo de uma coluna durante uma operação de anexação.
Ao relaxar o modo de uma coluna usando uma operação de anexação em um job de carregamento, é possível:
- relaxar o modo de colunas individuais especificando um arquivo de esquema JSON, ao anexar dados de arquivos CSV e JSON;
- relaxar colunas para
null
no esquema do Avro, do ORC ou do Parquet e permitir a inferência de esquema para detectar as colunas relaxadas.
Para relaxar uma coluna de REQUIRED
para NULLABLE
ao anexar dados a uma tabela durante um job de carregamento, siga estas etapas:
Console
Ainda não é possível transformar o modo de coluna usando o Console do Cloud.
bq
Use o comando bq load
para carregar os dados e especifique a sinalização --noreplace
para indicar que você os está anexando a uma tabela atual.
Se os dados que você anexar estiverem em CSV ou em formato JSON delimitado por nova linha, especifique as colunas de relaxamento em um arquivo de esquema JSON local. Se preferir, use a sinalização --autodetect
para utilizar a detecção de esquemas e descobrir colunas de relaxamento nos dados de origem. Para mais informações sobre como relaxar os modos de colunas usando um arquivo de esquema JSON, consulte Como alterar manualmente as colunas REQUIRED
para NULLABLE
.
As colunas de relaxamento podem ser inferidas automaticamente de arquivos Avro, ORC e Parquet. O relaxamento de coluna não se aplica a anexos de exportação do Cloud Datastore. As colunas em tabelas criadas durante o carregamento de arquivos de exportação do Datastore são sempre NULLABLE
.
Defina a sinalização --schema_update_option
como ALLOW_FIELD_RELAXATION
para indicar que os dados sendo anexados contêm colunas relaxadas.
Se a tabela sendo anexada estiver em um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no formato a seguir: project_id:dataset
.
Opcional: forneça a sinalização --location
e defina o valor do
local.
Digite o comando load
a seguir:
bq --location=location load \ --noreplace \ --schema_update_option=ALLOW_FIELD_RELAXATION \ --source_format=format \ project_id:dataset.table \ 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, 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
,CSV
,PARQUET
,ORC
ouAVRO
Os arquivosDATASTORE_BACKUP
não exigem relaxamento da coluna. As colunas em tabelas criadas de arquivos de exportação do Datastore são sempreNULLABLE
. - project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela.
- table é o nome da tabela que você está anexando.
- path_to_source é um URI do Cloud Storage completo, uma lista de URIs separada por vírgula ou o caminho para um arquivo de dados na máquina local.
- schema é o caminho para um arquivo de esquema JSON local. Esta opção é usada apenas para arquivos CSV e JSON. As colunas relaxadas são inferidas automaticamente de arquivos Avro.
Por exemplo:
Digite os comandos a seguir para adicionar um arquivo local do Avro, /tmp/mydata.avro
, a mydataset.mytable
usando um job de carregamento. Como as colunas relaxadas podem ser automaticamente inferidas dos dados do Avro, não é necessário especificar um arquivo de esquema. mydataset
está no projeto padrão.
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=AVRO \
mydataset.mytable \
/tmp/mydata.avro
Digite o comando a seguir para anexar dados de um arquivo JSON delimitado por nova linha no Cloud Storage a mydataset.mytable
usando um job de carregamento. O esquema contendo as colunas relaxadas está em um arquivo de esquema JSON local — /tmp/myschema.json
. mydataset
está no projeto padrão.
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=NEWLINE_DELIMITED_JSON \
mydataset.mytable \
gs://mybucket/mydata.json \
/tmp/myschema.json
Digite o comando a seguir para anexar dados em um arquivo CSV na máquina local a mydataset.mytable
usando um job de carregamento. O comando usa a detecção automática de esquema para descobrir colunas relaxadas nos dados de origem. mydataset
está em myotherproject
, e não no projeto padrão.
bq load \
--noreplace \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--source_format=CSV \
--autodetect \
myotherproject:mydataset.mytable \
mydata.csv
API
Chame o método jobs.insert
. Em seguida, configure um job de load
e defina as propriedades a seguir:
- Faça referência aos dados no Cloud Storage usando a propriedade
sourceUris
. - Especifique o formato de dados definindo a propriedade
sourceFormat
. - Especifique o esquema na propriedade
schema
. - Especifique a opção de atualização de esquema usando a propriedade
schemaUpdateOptions
. - Defina a disposição de gravação da tabela de destino como
WRITE_APPEND
usando a propriedadewriteDisposition
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Node.js
Antes de testar essa amostra, siga as instruções de configuração para Node.js 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 Node.js.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.
Como mudar REQUIRED
para NULLABLE
em um job de anexação de consulta
Use estes métodos para relaxar todas as colunas de uma tabela e anexar os resultados da consulta a ela:
- Use o comando
bq query
da ferramenta de linha de comandobq
. - Chamada do método
jobs.insert
da API e configuração de um job de consulta - Como usar bibliotecas de cliente
O Console do Cloud não é compatível com a transformação de colunas durante uma operação de anexação.
Ao transformar colunas usando uma operação de anexação em um job de consulta, defina a sinalização --schema_update_option
como ALLOW_FIELD_RELAXATION
para transformar todos os campos obrigatórios na tabela de destino. Não é possível relaxar colunas individuais em uma tabela de destino usando um anexo de consulta.
Para relaxar todas as colunas em uma tabela de destino ao anexar dados a ela durante um job de consulta, siga estas etapas:
Console
Ainda não é possível transformar o modo de coluna usando o Console do Cloud.
bq
Use o comando bq query
para consultar seus dados e especifique a sinalização --destination_table
para indicar qual tabela está sendo anexada.
Para mostrar que você está anexando resultados de consulta a uma tabela de destino atual, especifique a sinalização --append_table
.
Defina a sinalização --schema_update_option
como ALLOW_FIELD_RELAXATION
para indicar que todas as colunas REQUIRED
na tabela sendo anexada precisam ser alteradas para NULLABLE
.
Especifique a sinalização use_legacy_sql=false
para usar a sintaxe SQL padrão para a consulta.
Se a tabela sendo anexada estiver em um conjunto de dados em um projeto diferente do padrão, adicione o ID do projeto ao nome do conjunto de dados no formato a seguir: project_id:dataset
.
Opcional: forneça a sinalização --location
e defina o valor do
local.
bq --location=location query \ --destination_table project_id:dataset.table \ --append_table \ --schema_update_option=ALLOW_FIELD_RELAXATION \ --use_legacy_sql=false \ 'query'
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, defina o valor da sinalização comoasia-northeast1
. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc. - project_id é o ID do projeto.
- dataset é o nome do conjunto de dados que contém a tabela que você está anexando.
- table é o nome da tabela que você está anexando.
- query é uma consulta na sintaxe SQL padrão.
Por exemplo:
Digite o comando a seguir para consultar mydataset.mytable
no projeto padrão e para anexar os resultados da consulta a mydataset.mytable2
, que também está no projeto padrão. Esse comando altera todas as colunas REQUIRED
na tabela de destino para NULLABLE
.
bq query \
--destination_table mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'SELECT
column1,column2
FROM
mydataset.mytable'
Digite o comando a seguir para consultar mydataset.mytable
no projeto padrão e para anexar os resultados da consulta a mydataset.mytable2
em myotherproject
. Esse comando altera todas as colunas REQUIRED
na tabela de destino para NULLABLE
.
bq query \
--destination_table myotherproject:mydataset.mytable2 \
--append_table \
--schema_update_option=ALLOW_FIELD_RELAXATION \
--use_legacy_sql=false \
'SELECT
column1,column2
FROM
mydataset.mytable'
API
Chame o método jobs.insert
. Em seguida, configure um job de query
e defina as propriedades a seguir:
- Especifique a tabela de destino usando a propriedade
destinationTable
. - Defina a disposição de gravação da tabela de destino como
WRITE_APPEND
usando a propriedadewriteDisposition
. - Especifique a opção de atualização de esquema usando a propriedade
schemaUpdateOptions
. - Especifique a consulta SQL padrão usando a propriedade
query
.
Go
Java
Antes de testar essa amostra, siga as instruções de configuração para Java 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 em Java.
Python
Antes de testar essa amostra, siga as instruções de configuração para Python 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 em Python.