Como modificar esquemas de tabelas

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

É 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 em NULLABLE;
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 comando bq.
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.

Observação: a experiência padrão é a versão de visualização do Console do Cloud. Se você clicou em Ocultar recursos da versão de visualização para acessar a versão de disponibilidade geral do Console do Cloud, faça o seguinte: na seção Recursos do painel de navegação, selecione um projeto e um banco de dados e clique no nome da 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 ou REPEATED.
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.

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 ou REPEATED e tipos RECORD 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 coluna NULLABLE chamada column4. 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

Ver no GitHub

import (
	"context"
	"fmt"

	"cloud.google.com/go/bigquery"
)

// updateTableAddColumn demonstrates modifying the schema of a table to append an additional column.
func updateTableAddColumn(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()

	tableRef := client.Dataset(datasetID).Table(tableID)
	meta, err := tableRef.Metadata(ctx)
	if err != nil {
		return err
	}
	newSchema := append(meta.Schema,
		&bigquery.FieldSchema{Name: "phone", Type: bigquery.StringFieldType},
	)
	update := bigquery.TableMetadataToUpdate{
		Schema: newSchema,
	}
	if _, err := tableRef.Update(ctx, update, meta.ETag); err != nil {
		return err
	}
	return nil
}

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.

Como modificar esquemas de tabelas

Como adicionar colunas à definição de esquema de uma tabela

Como adicionar manualmente uma coluna vazia

Console

SQL

bq

API

Go

Java

Node.js

Python

Como adicionar uma coluna aninhada a um RECORD

Console

bq

API

Como adicionar uma coluna ao substituir ou anexar dados

Como adicionar uma coluna a um job de anexação de carregamento

Console

bq

API

Go

Java

Node.js

Python

Como adicionar uma coluna em um job de anexação de consulta

Console

bq

API

Go

Java

Node.js

Python

Como transformar o modo de uma coluna

Como alterar manualmente colunas REQUIRED para NULLABLE

Console

bq

API

Go

Java

Node.js

Python

Como mudar REQUIRED para NULLABLE em um job de carregamento ou de consulta

Como mudar REQUIRED para NULLABLE em um job de anexação de carregamento

Console

bq

API

Go

Java

Node.js

Python

Como mudar REQUIRED para NULLABLE em um job de anexação de consulta

Console

bq

API

Go

Java

Python

Como adicionar uma coluna aninhada a um `RECORD`

Como alterar manualmente colunas `REQUIRED` para `NULLABLE`

Como mudar `REQUIRED` para `NULLABLE` em um job de carregamento ou de consulta

Como mudar `REQUIRED` para `NULLABLE` em um job de anexação de carregamento

Como mudar `REQUIRED` para `NULLABLE` em um job de anexação de consulta