Como modificar esquemas de tabela

Neste documento, você aprende a modificar definições de esquema para tabelas do BigQuery existentes. 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 adicionar uma definição de esquema à tabela posteriormente.

Todas as outras modificações de esquema são incompatíveis e exigem soluções alternativas manuais, como:

  • alterar o nome de uma coluna;
  • Alterar o tipo de dados de uma coluna
  • 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:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq update da ferramenta de linha de comando.
  • Chame o método de API tables.patch

Se você adicionar novas colunas a um esquema de tabela atual, elas 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 presente na CLI ou na API, será retornado o seguinte erro: BigQuery error in update operation: Provided Schema does not match Table [PROJECT_ID]:[DATASET].[TABLE]. Cannot add required columns to an existing schema. Colunas REQUIRED só podem ser adicionadas quando você cria uma tabela durante o carregamento de dados ou quando você cria 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 própria coluna usando:

Para adicionar colunas vazias à definição de esquema de uma tabela:

Console

  1. No painel Recursos, selecione sua tabela.

  2. Abaixo do editor de consultas, role até a parte inferior da seção Esquema e clique em Editar esquema.

Editar esquema de tabela

  1. Role até a parte inferior do painel aberto e clique em Adicionar campo.

    • Em Nome, digite o nome da coluna.
    • Em Tipo, escolha o tipo de dados.
    • Em Modo, escolha NULLABLE ou REPEATED.
  2. Quando terminar de adicionar colunas, clique em Salvar.

IU clássica

  1. No painel de navegação, selecione a tabela.

  2. Na página Detalhes da tabela, clique em Adicionar novos campos.

  3. Na seção Novos campos:

    • Em Nome, digite o nome da coluna.
    • Em Tipo, escolha o tipo de dados.
    • Em Modo, escolha NULLABLE ou REPEATED.

      Atualizar esquema de tabela

  4. Quando terminar de adicionar colunas, clique em Adicionar à tabela.

CLI

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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

  bq update [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

Em que:

  • [PROJECT_ID] é o código 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 máquina local.

Ao especificar 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 assumem NULLABLE como padrão.

Se você tentar adicionar colunas usando uma definição de esquema in-line, precisará fornecer toda a definição de esquema, inclusive 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 para NULLABLE. Isso resulta no seguinte erro: 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 CLI é fornecer um arquivo de esquema JSON.

Para adicionar colunas vazias ao esquema de uma tabela usando um arquivo de esquema JSON:

  1. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

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

    Em que:

    • [PROJECT_ID] é o código 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. O elemento mydataset.mytable está no projeto padrão.

    bq show --schema --format=prettyjson mydataset.mytable > /tmp/myschema.json
    
  2. Abra o arquivo de esquema em um editor de texto. O esquema será semelhante a este:

    [
      {
        "mode": "REQUIRED",
        "name": "column1",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "column2",
        "type": "FLOAT"
      },
      {
        "mode": "REPEATED",
        "name": "column3",
        "type": "STRING"
      }
    ]
    
  3. Adicione as novas colunas ao final da definição de esquema. Se você tentar adicionar novas colunas em outro ponto da matriz, será retornado o seguinte erro: 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 saber mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.

  4. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

    bq update [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]
    

    Em que:

    • [PROJECT_ID] é o código 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 máquina local.

    Por exemplo, insira 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 tables.update substitui todo o recurso da tabela, o método tables.patch é recomendado.

Go

// 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")
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
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no 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 Python.

Anexe um novo objeto SchemaField a uma cópia de Table.schema. Depois substitua o valor da propriedade Table.schema pelo esquema atualizado.

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

table_ref = client.dataset(dataset_id).table(table_id)
table = client.get_table(table_ref)  # API request

original_schema = table.schema
new_schema = original_schema[:]  # creates a copy of the schema
new_schema.append(bigquery.SchemaField("phone", "STRING"))

table.schema = new_schema
table = client.update_table(table, ["schema"])  # API request

assert len(table.schema) == len(original_schema) + 1 == len(new_schema)

Como adicionar uma coluna aninhada a RECORD

Além de adicionar novas colunas ao esquema de uma tabela, você também pode adicionar novas colunas aninhadas a um RECORD. O processo para adicionar uma nova coluna aninhada é muito semelhante ao processo para adicionar uma nova coluna.

Console

A IU da Web do BigQuery do console ainda não aceita adicionar um novo campo aninhado a uma coluna RECORD existente.

IU clássica

Atualmente, não é possível adicionar um novo campo aninhado a uma coluna RECORD na IU da Web clássica do BigQuery.

CLI

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 existente. Se a tabela que você está atualizando estiver em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

  bq update [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]

Em que:

  • [PROJECT_ID] é o código 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 máquina local.

Ao especificar 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. O padrão de todos os modos é NULLABLE. Como resultado, se você estiver incluindo uma nova coluna aninhada em 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:

  1. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

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

    Em que:

    • [PROJECT_ID] é o código 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. O elemento mydataset.mytable está no projeto padrão.

    bq show --schema --format=prettyjson mydataset.mytable > /tmp/myschema.json
    
  2. 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ão nested1 e nested2. A matriz fields lista os campos aninhados dentro de column3.

    [
      {
        "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"
      }
    ]
    
  3. 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 saber mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.

  4. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

    bq update [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]
    

    Em que:

    • [PROJECT_ID] é o código 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 máquina local.

    Por exemplo, insira 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 incluir as colunas aninhadas na sua definição de esquema. Como tables.update substitui todo o recurso da tabela, o método tables.patch é recomendado.

Como adicionar uma coluna ao substituir ou anexar dados

É possível adicionar novas colunas a uma tabela existente quando você carrega dados nela e opta por substituir a tabela existente. Ao substituir uma tabela existente, o esquema dos dados que você está carregando é usado para substituir o esquema da tabela existente. Para informações sobre como substituir uma tabela usando um job de carregamento, consulte estes tópicos:

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 em 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 comando.
  • Chame o método jobs.insert da API e configure um job de carregamento.

O Console do GCP e a IU da Web clássica do BigQuery ainda não são compatíveis com a inclusão de uma coluna em uma tabela atual durante uma operação de anexação.

Quando você adiciona 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);
  • inferido automaticamente dos dados referentes a arquivos de exportação do Avro e do Cloud Datastore.

Se você especificar o esquema em um arquivo JSON, as novas colunas precisarão ser definidas nele. Caso não haja novas definições de coluna, será retornado o seguinte erro quando você tentar anexar os dados: Error while reading data, error message: parsing error in row starting at position [INT]: No such field: [FIELD].

Quando você adiciona novas colunas durante uma operação de anexação, os valores nas novas colunas são definidos como NULL para as linhas existentes.

Para adicionar uma nova coluna ao anexar dados a uma tabela durante um job de carregamento:

Console

Não é possível adicionar novas colunas a uma tabela atual ao carregar dados usando a IU da Web do BigQuery do console.

IU clássica

Não é possível adicionar novas colunas a uma tabela atual ao carregar dados usando a IU da Web clássica do BigQuery.

CLI

Use o comando bq load para carregar os dados e especifique a sinalização --noreplace para indicar que você está anexando os dados a uma tabela existente.

Se os dados que você anexar 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 os dados que você está anexando contêm novas colunas.

Se a tabela anexada estiver em um conjunto de dados em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

Digite o comando load desta maneira:

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 seu local. A sinalização --location será opcional se os dados estiverem no local multirregional US ou EU. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina 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, CSV, AVRO ou DATASTORE_BACKUP;
  • [PROJECT_ID] é o código 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, totalmente qualificado, uma lista de URIs separada por vírgulas 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 a partir dos dados de origem.

Exemplos:

Digite o comando a seguir para anexar a /tmp/mydata.avro um arquivo de dados Avro local (mydataset.mytable) usando um job de carregamento. Como as colunas adicionadas podem ser inferidas automaticamente de dados Avro, você não precisa usar a sinalização --autodetect. mydataset está no projeto padrão e foi criado no local multirregional US.

bq --location=US load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=AVRO mydataset.mytable /tmp/mydata.avro

Digite o comando a seguir para anexar a mydataset.mytable um arquivo de dados JSON delimitado pela nova linha no Cloud Storage usando um job de carregamento. A sinalização --autodetect é usada para detectar as novas colunas. mydataset está no projeto padrão e foi criado no local multirregional US.

bq --location=US 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 a mydataset.mytable um arquivo de dados JSON delimitado pela nova linha no Cloud Storage usando um job de carregamento. O esquema contendo as novas colunas é especificado em um arquivo de esquema JSON local (/tmp/myschema.json). mydataset está em myotherproject, e não no projeto padrão. mydataset foi criado no local multirregional US.

bq --location=US load --noreplace --schema_update_option=ALLOW_FIELD_ADDITION --source_format=NEWLINE_DELIMITED_JSON myotherproject:mydataset.mytable gs://mybucket/mydata.json /tmp/myschema.json

Digite o comando a seguir para anexar a mydataset.mytable um arquivo de dados JSON delimitado pela nova linha no Cloud Storage usando um job de carregamento. A sinalização --autodetect é usada para detectar as novas colunas. mydataset está no projeto padrão e foi criado no local multirregional asia-northeast1.

bq --location=asia-northeast1 load --noreplace --autodetect --schema_update_option=ALLOW_FIELD_ADDITION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json

API

Chame o método jobs.insert. Especifique sua região na propriedade location da seção jobReference do recurso do job.

Depois, configure um job de carregamento e defina as seguintes propriedades:

Go

// 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},
}
meta := &bigquery.TableMetadata{
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, meta); err != nil {
	return err
}
// Now, import data from a local file, but specify field additions are allowed.
// Because the data has a second column (age), the schema is amended as part of
// the load.
f, err := os.Open(filename)
if err != nil {
	return err
}
source := bigquery.NewReaderSource(f)
source.AutoDetect = true   // Allow BigQuery to determine schema.
source.SkipLeadingRows = 1 // CSV has a single header line.

loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the length of the schema
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
print("Table {} contains {} columns.".format(table_id, len(table.schema)))

# Configures the load job to append the data to the destination table,
# allowing field addition
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
]
# In this example, the existing table contains only the 'full_name' column.
# 'REQUIRED' fields cannot be added to an existing schema, so the
# additional column must be 'NULLABLE'.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="NULLABLE"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated length of the schema
table = client.get_table(table)
print("Table {} now contains {} columns.".format(table_id, len(table.schema)))

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 comando
  • Chame o método jobs.insert da API e configure um job de consulta

O Console do GCP e a IU da Web clássica do BigQuery ainda não são compatíveis com a inclusão de uma coluna durante uma operação de anexação.

Quando você adiciona colunas usando uma operação de anexação em um job de consulta, o esquema dos resultados da consulta é usado para atualizar o esquema da tabela de destino.

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 quando você anexa resultados da consulta usando a IU da Web do BigQuery do console.

IU clássica

Não é possível adicionar novas colunas a uma tabela atual quando você anexa resultados da consulta usando a IU da Web clássica do BigQuery.

CLI

Use o comando bq query para consultar os dados e especifique a sinalização --destination_table para indicar qual tabela você está anexando.

Para mostrar que você está anexando resultados da consulta a uma tabela de destino existente, especifique a sinalização --append_table.

Defina a sinalização --schema_update_option como ALLOW_FIELD_ADDITION para indicar que os resultados da consulta que você está anexando contêm novas colunas.

Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão da consulta.

Se a tabela anexada estiver em um conjunto de dados em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --append_table --schema_update_option  --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do seu local. A sinalização --location será opcional se os dados estiverem no local multirregional US ou EU. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o código 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.

Exemplos:

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 (também no projeto padrão). mydataset foi criado no local multirregional US.

bq --location=US query --destination_table mydataset.mytable2 --append_table --schema_update_option=ALLOW_FIELD_ADDITION --use_legacy_sql=false 'SELECT column1,column2 FROM mydataset.mytable'

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 em myotherproject. mydataset foi criado no local multirregional US.

bq --location=US query --destination_table myotherproject:mydataset.mytable2 --append_table --schema_update_option=ALLOW_FIELD_ADDITION --use_legacy_sql=false 'SELECT column1,column2 FROM mydataset.mytable'

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 (também no projeto padrão). mydataset foi criado na região asia-northeast1.

bq --location=asia-northeast1 query --destination_table 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. Especifique sua região na propriedade location da seção jobReference do recurso do job.

Configure um job de consulta e defina as seguintes propriedades:

Go

// 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, Required: true},
	{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
}
original := &bigquery.TableMetadata{
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, original); err != nil {
	return err
}
// Our table has two columns.  We'll introduce a new favorite_color column via
// a subsequent query that appends to the table.
q := client.Query("SELECT \"Timmy\" as full_name, 85 as age, \"Blue\" as favorite_color")
q.SchemaUpdateOptions = []string{"ALLOW_FIELD_ADDITION"}
q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
q.WriteDisposition = bigquery.WriteAppend
q.Location = "US"
job, err := q.Run(ctx)
if err != nil {
	return err
}
_, err = job.Wait(ctx)
if err != nil {
	return err
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

# Retrieves the destination table and checks the length of the schema
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
print("Table {} contains {} columns.".format(table_id, len(table.schema)))

# Configures the query to append the results to a destination table,
# allowing field addition
job_config = bigquery.QueryJobConfig()
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_ADDITION
]
job_config.destination = table_ref
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND

query_job = client.query(
    # In this example, the existing table contains only the 'full_name' and
    # 'age' columns, while the results of this query will contain an
    # additional 'favorite_color' column.
    'SELECT "Timmy" as full_name, 85 as age, "Blue" as favorite_color;',
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location="US",
    job_config=job_config,
)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print("Query job {} complete.".format(query_job.job_id))

# Checks the updated length of the schema
table = client.get_table(table)
print("Table {} now contains {} columns.".format(table_id, len(table.schema)))

Como relaxar o modo de uma coluna

Atualmente, a única alteração aceita que você pode fazer no modo de uma coluna é de REQUIRED para NULLABLE. Alterar o modo de uma coluna de REQUIRED para NULLABLE também é chamado de relaxamento de coluna. E 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:

  • Use o Console do GCP ou a IU da Web clássica do BigQuery.
  • Use o comando bq update da ferramenta de linha de comando.
  • Chame o método de API tables.patch.

Para alterar manualmente o modo de uma coluna de REQUIRED para NULLABLE:

Console

Atualmente, não é possível relaxar o modo de uma coluna usando a IU da Web do BigQuery do console.

IU clássica

  1. Expanda o conjunto de dados e selecione a tabela.

  2. Na página Detalhes da tabela, clique na guia Esquema.

  3. Clique na seta para baixo à direita da coluna REQUIRED e escolha entre:

    • Definir como NULLABLE: relaxa o modo da coluna individual.
    • Todas as REQUIRED como NULLABLE: altera todas as colunas REQUIRED na definição de esquema para NULLABLE

      Relaxar modo de coluna

  4. Na caixa de diálogo Confirmar alteração do modo, clique em OK para alterar o modo para NULLABLE. Observe que essa alteração não pode ser desfeita.

CLI

  1. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

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

    Em que:

    • [PROJECT_ID] é o código 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. O elemento mydataset.mytable está no projeto padrão.

    bq show --schema --format=prettyjson mydataset.mytable > /tmp/myschema.json
    
  2. Abra o arquivo de esquema em um editor de texto. O esquema será semelhante a este:

    [
      {
        "mode": "REQUIRED",
        "name": "column1",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "column2",
        "type": "FLOAT"
      },
      {
        "mode": "REPEATED",
        "name": "column3",
        "type": "STRING"
      }
    ]
    
  3. Altere o modo de uma coluna atual de REQUIRED para NULLABLE. Neste exemplo, o modo da column1 é relaxado.

    [
      {
        "mode": "NULLABLE",
        "name": "column1",
        "type": "STRING"
      },
      {
        "mode": "REQUIRED",
        "name": "column2",
        "type": "FLOAT"
      },
      {
        "mode": "REPEATED",
        "name": "column3",
        "type": "STRING"
      }
    ]
    

    Para saber mais informações sobre como trabalhar com arquivos de esquema JSON, consulte Como especificar um arquivo de esquema JSON.

  4. 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 projeto padrão, adicione o código do projeto ao nome do conjunto de dados, no seguinte formato: [PROJECT_ID]:[DATASET].

    bq update [PROJECT_ID]:[DATASET].[TABLE] [SCHEMA]
    

    Em que:

    • [PROJECT_ID] é o código 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 máquina local.

    Por exemplo, insira 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 de esquema. Como tables.update substitui todo o recurso da tabela, o método tables.patch é recomendado.

Go

// 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")
tableRef := client.Dataset(datasetID).Table(tableID)
meta, err := tableRef.Metadata(ctx)
if err != nil {
	return err
}
// Iterate through the schema to set all Required fields to false (nullable).
var relaxed bigquery.Schema
for _, v := range meta.Schema {
	v.Required = false
	relaxed = append(relaxed, v)
}
newMeta := bigquery.TableMetadataToUpdate{
	Schema: relaxed,
}
if _, err := tableRef.Update(ctx, newMeta, meta.ETag); err != nil {
	return err
}

Python

Antes de testar esta amostra, siga as instruções de configuração do Python no 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 Python.

Substitua a propriedade Table.schema por uma lista de objetos SchemaField com a propriedade de modo definida como 'NULLABLE'

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_id = 'my_dataset'
# table_id = 'my_table'

original_schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]
table_ref = client.dataset(dataset_id).table(table_id)
table = bigquery.Table(table_ref, schema=original_schema)
table = client.create_table(table)
assert all(field.mode == "REQUIRED" for field in table.schema)

# SchemaField properties cannot be edited after initialization.
# To make changes, construct new SchemaField objects.
relaxed_schema = [
    bigquery.SchemaField("full_name", "STRING", mode="NULLABLE"),
    bigquery.SchemaField("age", "INTEGER", mode="NULLABLE"),
]
table.schema = relaxed_schema
table = client.update_table(table, ["schema"])

assert all(field.mode == "NULLABLE" for field in table.schema)

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

É possível relaxar colunas REQUIRED para NULLABLE no esquema de uma tabela existente quando você carrega dados nela e opta por substituir a tabela existente. Ao substituir uma tabela existente, o esquema dos dados que você está carregando é usado para substituir o esquema da tabela existente. Para informações sobre como substituir uma tabela usando um job de carregamento, consulte estes tópicos:

Você também pode relaxar as colunas REQUIRED para NULLABLE no esquema de uma tabela existente ao anexar dados a ela usando um job de consulta.

Como alterar 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 comando.
  • Chame o método jobs.insert da API e configure um job de carregamento.

O Console do GCP e a IU da Web clássica do BigQuery ainda não são compatíveis 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 e permitir a inferência do 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:

Console

Atualmente, não é possível relaxar o modo de uma coluna usando a IU da Web do BigQuery do console.

IU clássica

Não é possível relaxar o modo de uma coluna atual quando você anexa dados a uma tabela em um job de carregamento usando a IU da Web clássica do BigQuery.

CLI

Use o comando bq load para carregar os dados e especifique a sinalização --noreplace para indicar que você está anexando os dados a uma tabela existente.

Se os dados que você está anexando estiverem no formato CSV ou JSON delimitado por nova linha, especifique as colunas relaxadas em um arquivo de esquema JSON local. Outra opção é escolher a sinalização --autodetect para usar a detecção de esquema e descobrir colunas relaxadas nos dados de origem. Para informações sobre como relaxar os modos de colunas usando um arquivo de esquema JSON, consulte Como alterar manualmente colunas REQUIRED para NULLABLE.

As colunas relaxadas podem ser inferidas automaticamente de arquivos Avro. 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 Cloud Datastore são sempre NULLABLE.

Defina a sinalização --schema_update_option como ALLOW_FIELD_RELAXATION para indicar que os dados que você está anexando contêm colunas relaxadas.

Se a tabela anexada estiver em um conjunto de dados em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

Digite o comando load desta maneira:

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

Em que:

  • [LOCATION] é o nome do seu local. A sinalização --location será opcional se os dados estiverem no local multirregional US ou EU. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina 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, CSV ou AVRO. Arquivos DATASTORE_BACKUP não exigem relaxamento de coluna. As colunas em tabelas criadas a partir de arquivos de exportação do Cloud Datastore são sempre NULLABLE;
  • [PROJECT_ID] é o código 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, totalmente qualificado, uma lista de URIs separada por vírgulas 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 a partir de arquivos Avro.

Exemplos:

Digite o comando a seguir para anexar a /tmp/mydata.avro um arquivo de dados Avro local (mydataset.mytable) usando um job de carregamento. Como as colunas adicionadas podem ser inferidas automaticamente de dados Avro, você não precisa especificar um arquivo de esquema. mydataset está no projeto padrão e foi criado no local multirregional US.

bq --location=US load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=AVRO mydataset.mytable /tmp/mydata.avro

Digite o comando a seguir para anexar a mydataset.mytable um arquivo de dados JSON delimitado pela nova linha no Cloud Storage 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 e foi criado no local multirregional US.

bq --location=US 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 a mydataset.mytable em um arquivo CSV na máquina local 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. mydataset foi criado no local multirregional US.

bq --location=US load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=CSV --autodetect myotherproject:mydataset.mytable mydata.csv

Digite o comando a seguir para anexar a mydataset.mytable um arquivo de dados JSON delimitado pela nova linha no Cloud Storage 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 e foi criado na região asia-northeast1.

bq --location=asia-northeast1 load --noreplace --schema_update_option=ALLOW_FIELD_RELAXATION --source_format=NEWLINE_DELIMITED_JSON mydataset.mytable gs://mybucket/mydata.json /tmp/myschema.json

API

Chame o método jobs.insert. Especifique sua região na propriedade location da seção jobReference do recurso do job. Depois, configure um job de carregamento e defina as seguintes propriedades:

Go

// 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, Required: true},
	{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
}
meta := &bigquery.TableMetadata{
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, meta); err != nil {
	return err
}
// Now, import data from a local file, but specify relaxation of required
// fields as a side effect while the data is appended.
f, err := os.Open(filename)
if err != nil {
	return err
}
source := bigquery.NewReaderSource(f)
source.AutoDetect = true   // Allow BigQuery to determine schema.
source.SkipLeadingRows = 1 // CSV has a single header line.

loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(source)
loader.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
job, err := loader.Run(ctx)
if err != nil {
	return err
}
status, err := job.Wait(ctx)
if err != nil {
	return err
}
if err := status.Err(); err != nil {
	return err
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')
# filepath = 'path/to/your_file.csv'

# Retrieves the destination table and checks the number of required fields
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
# In this example, the existing table has 3 required fields.
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the load job to append the data to a destination table,
# allowing field relaxation
job_config = bigquery.LoadJobConfig()
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION
]
# In this example, the existing table contains three required fields
# ('full_name', 'age', and 'favorite_color'), while the data to load
# contains only the first two fields.
job_config.schema = [
    bigquery.SchemaField("full_name", "STRING", mode="REQUIRED"),
    bigquery.SchemaField("age", "INTEGER", mode="REQUIRED"),
]
job_config.source_format = bigquery.SourceFormat.CSV
job_config.skip_leading_rows = 1

with open(filepath, "rb") as source_file:
    job = client.load_table_from_file(
        source_file,
        table_ref,
        location="US",  # Must match the destination dataset location.
        job_config=job_config,
    )  # API request

job.result()  # Waits for table load to complete.
print(
    "Loaded {} rows into {}:{}.".format(
        job.output_rows, dataset_id, table_ref.table_id
    )
)

# Checks the updated number of required fields
table = client.get_table(table)
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))

Como alterar 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 comando
  • Chame o método jobs.insert da API e configure um job de consulta

O Console do GCP e a IU da Web clássica do BigQuery ainda não são compatíveis com o relaxamento de colunas durante uma operação de anexação.

Quando você relaxa colunas usando uma operação de anexação em um job de consulta, pode relaxar todos os campos obrigatórios na tabela de destino definindo a sinalização --schema_update_option como ALLOW_FIELD_RELAXATION. Não é possível relaxar colunas individuais em uma tabela de destino usando uma anexação de consulta.

Para relaxar todas as colunas em uma tabela de destino ao anexar dados a ela durante um job de consulta:

Console

Atualmente, não é possível relaxar o modo de uma coluna usando a IU da Web do BigQuery do console.

IU clássica

Não é possível relaxar colunas em uma tabela de destino quando você anexa resultados da consulta usando a IU da Web do BigQuery.

CLI

Use o comando bq query para consultar os dados e especifique a sinalização --destination_table para indicar qual tabela você está anexando.

Para mostrar que você está anexando resultados da consulta a uma tabela de destino existente, especifique a sinalização --append_table.

Defina a sinalização --schema_update_option como ALLOW_FIELD_RELAXATION para indicar a necessidade de que todas as colunas REQUIRED na tabela anexada sejam alteradas para NULLABLE.

Especifique a sinalização use_legacy_sql=false para usar a sintaxe SQL padrão da consulta.

Se a tabela anexada estiver em um conjunto de dados em um projeto diferente do projeto padrão, adicione o código do projeto ao nome do conjunto de dados no seguinte formato: [PROJECT_ID]:[DATASET].

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

bq --location=[LOCATION] query --destination_table [PROJECT_ID]:[DATASET].[TABLE] --append_table --schema_update_option --use_legacy_sql=false '[QUERY]'

Em que:

  • [LOCATION] é o nome do seu local. A sinalização --location será opcional se os dados estiverem no local multirregional US ou EU. Por exemplo, se você estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
  • [PROJECT_ID] é o código 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.

Exemplos:

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 (também no projeto padrão). O comando altera todas as colunas REQUIRED na tabela de destino para NULLABLE. mydataset foi criado no local multirregional US.

bq --location=US query --destination_table mydataset.mytable2 --append_table --schema_update_option=ALLOW_FIELD_RELAXATION --use_legacy_sql=false 'SELECT column1,column2 FROM mydataset.mytable'

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 em myotherproject. O comando altera todas as colunas REQUIRED na tabela de destino para NULLABLE. mydataset foi criado no local multirregional US.

bq --location=US query --destination_table myotherproject:mydataset.mytable2 --append_table --schema_update_option=ALLOW_FIELD_RELAXATION --use_legacy_sql=false 'SELECT column1,column2 FROM mydataset.mytable'

Digite a consulta de comando mydataset.mytable a seguir no projeto padrão para anexar os resultados da consulta a mydataset.mytable2 (também no projeto padrão). O comando altera todas as colunas REQUIRED na tabela de destino para NULLABLE. mydataset foi criado na região asia-northeast1.

bq --location=asia-northeast1 query --destination_table 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. Especifique sua região na propriedade location da seção jobReference do recurso do job.

Configure um job de consulta e defina as seguintes propriedades:

Go

// 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, Required: true},
	{Name: "age", Type: bigquery.IntegerFieldType, Required: true},
}
meta := &bigquery.TableMetadata{
	Schema: sampleSchema,
}
tableRef := client.Dataset(datasetID).Table(tableID)
if err := tableRef.Create(ctx, meta); err != nil {
	return err
}
// Now, append a query result that includes nulls, but allow the job to relax
// all required columns.
q := client.Query("SELECT \"Beyonce\" as full_name")
q.QueryConfig.Dst = client.Dataset(datasetID).Table(tableID)
q.SchemaUpdateOptions = []string{"ALLOW_FIELD_RELAXATION"}
q.WriteDisposition = bigquery.WriteAppend
q.Location = "US"
job, err := q.Run(ctx)
if err != nil {
	return err
}
_, err = job.Wait(ctx)
if err != nil {
	return err
}

Python

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

# from google.cloud import bigquery
# client = bigquery.Client()
# dataset_ref = client.dataset('my_dataset')

# Retrieves the destination table and checks the number of required fields
table_id = "my_table"
table_ref = dataset_ref.table(table_id)
table = client.get_table(table_ref)
original_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
# In this example, the existing table has 2 required fields
print("{} fields in the schema are required.".format(original_required_fields))

# Configures the query to append the results to a destination table,
# allowing field relaxation
job_config = bigquery.QueryJobConfig()
job_config.schema_update_options = [
    bigquery.SchemaUpdateOption.ALLOW_FIELD_RELAXATION
]
job_config.destination = table_ref
job_config.write_disposition = bigquery.WriteDisposition.WRITE_APPEND

query_job = client.query(
    # In this example, the existing table contains 'full_name' and 'age' as
    # required columns, but the query results will omit the second column.
    'SELECT "Beyonce" as full_name;',
    # Location must match that of the dataset(s) referenced in the query
    # and of the destination table.
    location="US",
    job_config=job_config,
)  # API request - starts the query

query_job.result()  # Waits for the query to finish
print("Query job {} complete.".format(query_job.job_id))

# Checks the updated number of required fields
table = client.get_table(table)
current_required_fields = sum(field.mode == "REQUIRED" for field in table.schema)
print("{} fields in the schema are now required.".format(current_required_fields))
Esta página foi útil? Conte sua opinião sobre:

Enviar comentários sobre…

Precisa de ajuda? Acesse nossa página de suporte.