Como carregar dados Parquet do Cloud Storage

Nesta página, apresentamos uma visão geral de como carregar dados Parquet do Cloud Storage no BigQuery.

Parquet é um formato de dados orientado por colunas de código aberto muito usado no ecossistema do Apache Hadoop.

Os dados Parquet podem ser carregados pelo Cloud Storage em uma nova tabela ou partição. Também é possível anexá-los a uma tabela ou partição atual, bem como substituí-las. Quando os dados são carregados no BigQuery, eles são convertidos no formato de colunas do Capacitor, o formato de armazenamento do BigQuery.

Quando você carrega dados do Cloud Storage em uma tabela do BigQuery, o conjunto de dados que a contém precisa estar na mesma região ou multirregião que o intervalo do Cloud Storage.

Para mais informações sobre como carregar dados Parquet de um arquivo local, consulte Como carregar dados de arquivos locais.

Limitações

Você está sujeito às limitações a seguir ao carregar dados de um intervalo do Cloud Storage para o BigQuery:

• Se o local do conjunto de dados estiver definido como um valor diferente da multirregião US, o bucket do Cloud Storage precisará estar na mesma região ou estar contido na mesma multirregião que o conjunto de dados.
• O BigQuery não garante a consistência dos dados para fontes de dados externas. Alterações nos dados subjacentes enquanto uma consulta estiver em execução podem resultar em comportamentos inesperados.

• O BigQuery não é compatível com o controle de versões de objetos do Cloud Storage. Se você incluir um número de geração no URI do Cloud Storage, o job de carregamento falhará.

• O carregamento de dados Parquet segue a convenção de nomenclatura de colunas e não é compatível com nomes de colunas flexíveis por padrão. Para se inscrever nesse pré-lançamento, preencha o formulário de inscrição.

• Não será possível usar um caractere curinga no URI do Cloud Storage se algum dos arquivos a serem carregados tiver esquemas diferentes. Qualquer diferença na posição das colunas se qualifica como um esquema diferente.

Requisitos para arquivos de entrada

Para evitar erros resourcesExceeded ao carregar arquivos Parquet no BigQuery, siga estas diretrizes:

• Mantenha tamanhos de linha de até 50 MB.
• Se os dados de entrada contiverem mais de 100 colunas, considere reduzir o tamanho da página para que seja menor que o tamanho padrão da página (1 * 1024 * 1024 bytes). Isso é útil principalmente se você estiver usando compactação significativa.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedem aos usuários as permissões necessárias para executar cada tarefa neste documento e crie um conjunto de dados para armazenamento.

Permissões necessárias

Para carregar dados no BigQuery, você precisa de permissões do IAM para executar um job de carregamento e carregar dados nas tabelas e partições do BigQuery. Se você estiver carregando dados do Cloud Storage, também precisará de permissões do IAM para acessar o bucket que contém os dados.

Permissões para carregar dados no BigQuery

Para carregar dados em uma nova tabela ou partição do BigQuery ou anexar ou substituir uma tabela ou partição existente, você precisa das seguintes permissões do IAM:

• bigquery.tables.create
• bigquery.tables.updateData
• bigquery.tables.update
• bigquery.jobs.create

Cada um dos seguintes papéis de IAM predefinidos inclui as permissões necessárias para carregar dados em uma tabela ou partição do BigQuery:

• roles/bigquery.dataEditor
• roles/bigquery.dataOwner
• roles/bigquery.admin (inclui a permissão bigquery.jobs.create)
• bigquery.user (inclui a permissão bigquery.jobs.create)
• bigquery.jobUser (inclui a permissão bigquery.jobs.create)

Além disso, se você tiver a permissão bigquery.datasets.create, poderá criar e atualizar tabelas usando um job de carregamento nos conjuntos de dados que criar.

Para mais informações sobre papéis e permissões do IAM no BigQuery, consulte Papéis e permissões predefinidos.

Permissões para carregar dados do Cloud Storage

Para receber as permissões necessárias para carregar dados de um bucket do Cloud Storage, peça ao administrador para conceder a você o o papel IAM doAdministrador de armazenamento (roles/storage.admin) no bucket. Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Esse papel predefinido contém as permissões necessárias para carregar dados de um bucket do Cloud Storage. Para conferir as permissões exatas necessárias, expanda a seção Permissões necessárias:

Permissões necessárias

As permissões a seguir são necessárias para carregar dados de um bucket do Cloud Storage:

• storage.buckets.get
• storage.objects.get
• storage.objects.list (required if you are using a URI wildcard)

Essas permissões também podem ser concedidas com papéis personalizados ou outros papéis predefinidos.

crie um conjunto de dados

Crie um conjunto de dados do BigQuery para armazenar seus dados.

Esquemas Parquet

Quando você carrega arquivos Parquet no BigQuery, o esquema da tabela é recuperado automaticamente pelos dados de origem autodescritivos. Quando o BigQuery recupera o esquema dos dados de origem, o último arquivo em ordem alfabética é usado.

Por exemplo, você tem os seguintes arquivos Parquet no Cloud Storage:

gs://mybucket/00/
  a.parquet
  z.parquet
gs://mybucket/01/
  b.parquet

Executar esse comando na ferramenta de linha de comando bq carrega todos os arquivos (como uma lista separada por vírgulas) e o esquema é derivado de mybucket/01/b.parquet:

bq load \
--source_format=PARQUET \
dataset.table \
"gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

Quando você carrega vários arquivos Parquet com esquemas diferentes, as colunas idênticas especificadas em vários esquemas precisam ter o mesmo modo em cada definição de esquema.

Quando o BigQuery detecta o esquema, alguns tipos de dados Parquet são convertidos em tipos de dados do BigQuery para que sejam compatíveis com a sintaxe do GoogleSQL. Para mais informações, consulte Conversões Parquet.

Para fornecer um esquema de tabela para criar tabelas externas, defina a propriedade referenceFileSchemaUri na API BigQuery ou o parâmetro
--reference_file_schema_uri na ferramenta de linha de comando bq como o URL do arquivo de referência.

Por exemplo, --reference_file_schema_uri="gs://mybucket/schema.parquet".

Compactação Parquet

O BigQuery é compatível com os seguintes codecs de compactação para conteúdo de arquivos Parquet:

• GZip
• LZO_1C
• LZO_1X
• LZ4_RAW
• Snappy
• ZSTD

Como carregar dados Parquet em uma nova tabela

É possível carregar dados Parquet em uma nova tabela usando uma das seguintes opções:

• Console do Google Cloud
• O comando bq load da ferramenta de linha de comando bq
• O método da API jobs.insert e a configuração de um job load
• As bibliotecas de cliente

Para carregar dados Parquet do Cloud Storage em uma nova tabela do BigQuery:

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato do arquivo, selecione Parquet.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, nenhuma ação é necessária. O esquema é descrito automaticamente nos arquivos Parquet.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, selecione Gravar apenas se a tabela estiver vazia. Usando essa opção, você cria uma nova tabela e carrega seus dados nela.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

Observação: ao carregar dados em uma tabela vazia usando o console do Google Cloud, não será possível adicionar um identificador, uma descrição ou uma validade de tabela ou de partição.

Após a criação da tabela, é possível atualizar a validade, a descrição e os identificadores dela. No entanto, não é possível adicionar uma validade de partição depois de criar uma tabela com o console do Google Cloud. Para mais informações, consulte Como gerenciar tabelas.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir carrega um arquivo Parquet na tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   LOAD DATA OVERWRITE mydataset.mytable
   FROM FILES (
     format = 'PARQUET',
     uris = ['gs://bucket/path/file.parquet']);
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Use o comando bq load, especifique PARQUET usando o sinalizador --source_format e inclua um URI do Cloud Storage É possível incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contém um caractere curinga.

Opcional: forneça a sinalização --location e defina o valor do local.

Estas são outras sinalizações opcionais:

• --time_partitioning_type: ativa o particionamento baseado em tempo na tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Essa sinalização é opcional quando você cria uma tabela particionada em uma coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição padrão para o particionamento baseado em tempo é DAY. Não é possível alterar a especificação de particionamento em uma tabela existente.
• --time_partitioning_expiration: um número inteiro que especifica em segundos quando uma partição baseada em tempo precisa ser excluída. O prazo de validade é a soma da data UTC da partição com o valor do número inteiro.
• --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se o particionamento baseado em tempo for ativado sem esse valor, será criada uma tabela particionada por tempo de processamento.
• --require_partition_filter: quando ativada, essa opção exige que os usuários incluam uma cláusula WHERE que especifica as partições a serem consultadas. A exigência de um filtro de partição pode reduzir custos e melhorar o desempenho. Para mais informações, acesse Como consultar tabelas particionadas.
• --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usadas para criar uma tabela em cluster.
• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

• --column_name_character_map: define o escopo e o processamento de caracteres em nomes de colunas, com a opção de ativar nomes de colunas flexíveis. Veja mais informações em load_option_list.

  Para mais informações sobre tabelas particionadas, consulte:

  • Como criar tabelas particionadas

  Para mais informações sobre tabelas em cluster, consulte:

  • Como criar e usar tabelas em cluster

  Para mais informações sobre a criptografia de tabelas, consulte:

  • Como proteger dados com chaves do Cloud KMS

Para carregar dados Parquet no BigQuery, insira o comando a seguir:

bq --location=LOCATION load \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Substitua:

• LOCATION: seu local. A sinalização --location é opcional. Por exemplo, se estiver usando o BigQuery na região de Tóquio, defina o valor da sinalização como asia-northeast1. Defina um valor padrão para a unidade usando o arquivo .bigqueryr.
• FORMAT: PARQUET.
• DATASET: um conjunto de dados existente
• TABLE: o nome da tabela em que você está carregando dados.
• PATH_TO_SOURCE é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Caracteres curinga também são aceitos

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.parquet em uma tabela chamada mytable em mydataset.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

O comando a seguir carrega dados de gs://mybucket/mydata.parquet em uma nova tabela particionada por tempo de processamento chamada mytable em mydataset.

    bq load \
    --source_format=PARQUET \
    --time_partitioning_type=DAY \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

O comando a seguir carrega dados de gs://mybucket/mydata.parquet em uma tabela particionada chamada mytable em mydataset. A tabela é particionada na coluna mytimestamp.

    bq load \
    --source_format=PARQUET \
    --time_partitioning_field mytimestamp \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

O comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O URI do Cloud Storage usa um caractere curinga.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata*.parquet

O comando a seguir carrega dados de vários arquivos em gs://mybucket/ em uma tabela chamada mytable em mydataset. O comando inclui uma lista separada por vírgulas de URIs do Cloud Storage com caracteres curinga.

    bq load \
    --source_format=PARQUET \
    mydataset.mytable \
    "gs://mybucket/00/*.parquet","gs://mybucket/01/*.parquet"

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

2. (Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.

3. É necessário que a propriedade source URIs seja totalmente qualificada no formato gs://BUCKET/OBJECT. Cada URI pode conter um caractere curinga "*".

4. Especifique o formato de dados Parquet definindo a propriedade sourceFormat como PARQUET.

5. Para verificar o status do job, chame jobs.get(JOB_ID*), substituindo JOB_ID pelo ID do job retornado pela solicitação inicial.

   • status.state = DONE indica que o job foi concluído.
   • Se a propriedade status.errorResult estiver presente, a solicitação falhou e esse objeto incluirá informações que descrevem o que deu errado. Quando há falha na solicitação, nenhuma tabela é criada, e os dados não são carregados.
   • A ausência de status.errorResult indica que o job foi concluído com sucesso. No entanto, é possível que tenha havido alguns erros não fatais, como problemas ao importar algumas linhas. Os erros não fatais são listados na propriedade status.errors do objeto do job retornado.

Observações sobre a API:

• Os jobs de carregamento são atômicos e consistentes. Se um deles falhar, nenhum dos dados estará disponível. Se um deles for bem-sucedido, todos os dados estarão disponíveis.

• Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId ao chamar jobs.insert para criar um job de carregamento. Essa abordagem é mais resistente a falhas de rede porque o cliente pode pesquisar ou tentar novamente com o ID do job conhecido.

• Chamar jobs.insert em um determinado ID do job é idempotente. É possível tentar quantas vezes quiser com o mesmo ID e, no máximo, uma das operações será bem-sucedida.

Go

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

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

// importParquet demonstrates loading Apache Parquet data from Cloud Storage into a table.
func importParquet(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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquet {

  public static void runLoadParquet() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquet(datasetName);
  }

  public static void loadParquet(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet loaded successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("GCS Parquet was not loaded. \n" + e.toString());
    }
  }
}

Node.js

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the Parquet file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.parquet
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadTableGCSParquet() {
  // Imports a GCS file into a table with Parquet source format.

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = 'my_dataset';
  // const tableId = 'my_table';

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);

  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId  = 'The Google project ID';
// $datasetId  = 'The BigQuery dataset ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$dataset = $bigQuery->dataset($datasetId);
$table = $dataset->table('us_states');

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET');
$job = $table->runJob($loadConfig);
// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});
// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Use o método Client.load_table_from_uri() para iniciar um job de carregamento no Cloud Storage. Para usar Parquet, defina a propriedade LoadJobConfig.source_format como a string PARQUET e transmita a configuração do job como o argumento job_config para o método load_table_from_uri().

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name"

job_config = bigquery.LoadJobConfig(
    source_format=bigquery.SourceFormat.PARQUET,
)
uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"

load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Como anexar ou substituir uma tabela com dados Parquet

Carregue mais dados em uma tabela de arquivos de origem ou anexando resultados de consultas.

No console do Google Cloud, use a opção Preferência de gravação para especificar qual ação será executada ao carregar dados de um arquivo de origem ou de um resultado de consulta.

Você tem as seguintes opções ao carregar mais dados em uma tabela:

Opção do console	flag da ferramenta bq	Propriedade da API BigQuery	Descrição
Gravar apenas se a tabela estiver vazia	Incompatível	WRITE_EMPTY	Grava dados apenas se a tabela estiver vazia.
Anexar à tabela	--noreplace ou --replace=false; se --[no]replace não for especificado, o padrão será anexado	WRITE_APPEND	(Padrão) Anexa os dados ao final da tabela.
Substituir tabela	--replace ou --replace=true	WRITE_TRUNCATE	Apaga todos os dados da tabela antes de gravar os novos. Essa ação também exclui o esquema da tabela e a segurança no nível da linha, além de remover qualquer chave do Cloud KMS.

Se você carregar dados em uma tabela, o job de carregamento os anexará ou substituirá a tabela.

Você pode anexar ou substituir uma tabela usando uma das seguintes opções:

• Console do Google Cloud
• O comando bq load da ferramenta de linha de comando bq
• O método da API jobs.insert e a configuração de um job load
• As bibliotecas de cliente

Observação: nesta página, não é abordado como anexar ou substituir tabelas particionadas. Para informações sobre esse assunto, consulte: Como anexar e substituir dados de tabelas particionadas.

Para anexar ou substituir uma tabela com dados Parquet:

Console

1. No Console do Google Cloud, acesse a página BigQuery.

   Acessar o BigQuery

2. No painel Explorer, expanda seu projeto e selecione um conjunto de dados.
3. Na seção Informações do conjunto de dados, clique em Criar tabela.
4. No painel Criar tabela, especifique os seguintes detalhes:
1. Na seção Origem, selecione Google Cloud Storage na lista Criar tabela de. Em seguida, faça o seguinte:
   1. Selecione um arquivo do bucket do Cloud Storage ou insira o URI do Cloud Storage. Não é possível incluir vários URIs no console do Google Cloud, mas caracteres curinga são suportados. O bucket do Cloud Storage precisa estar no mesmo local que o conjunto de dados que contém a tabela que você quer criar, anexar ou substituir.
   2. Em Formato do arquivo, selecione Parquet.
Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
2. Na seção Destino, especifique os seguintes campos:
   1. Em Conjunto de dados, selecione o conjunto de dados em que você quer criar a tabela.
   2. No campo Tabela, insira o nome da tabela que você quer criar.
   3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
3. Na seção Esquema, nenhuma ação é necessária. O esquema é descrito automaticamente nos arquivos Parquet.
Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carregamento, consulte Como modificar esquemas de tabelas.
4. Opcional: especifique configurações de partição e cluster. Para mais informações, consulte Como criar tabelas particionadas e Como criar e usar tabelas em cluster. Não é possível anexar ou substituir uma tabela para convertê-la em uma particionada ou em cluster. O console do Cloud não é compatível com anexação ou substituição de tabelas particionadas ou em cluster em um job de carregamento.
5. Clique em Opções avançadas e faça o seguinte:
   • Em Preferência de gravação, escolha Anexar à tabela ou Substituir tabela.
   • Se você quiser ignorar valores em uma linha ausentes no esquema da tabela, selecione Valores desconhecidos.
   • Em Criptografia, clique em Chave gerenciada pelo cliente para usar uma chave do Cloud Key Management Service. Se você optar pela configuração Chave gerenciada pelo Google, o BigQuery criptografará os dados em repouso.
6. Selecione Criar tabela.

SQL

Use a instrução DDL LOAD DATA. O exemplo a seguir anexa um arquivo Parquet à tabela mytable:

1. No Console do Google Cloud, acesse a página BigQuery.

   Ir para o BigQuery

2. No editor de consultas, digite a seguinte instrução:

   LOAD DATA INTO mydataset.mytable
   FROM FILES (
     format = 'PARQUET',
     uris = ['gs://bucket/path/file.parquet']);
   

3. Clique em Executar.

Para mais informações sobre como executar consultas, acesse Executar uma consulta interativa.

bq

Digite o comando bq load com a sinalização --replace para substituir a tabela. Use a sinalização --noreplace para anexar dados à tabela. Se nenhuma sinalização for especificada, o padrão será anexar os dados. Forneça a sinalização --source_format e defina-a como PARQUET. Como os esquemas Parquet são recuperados automaticamente dos dados de origem autodescritivos, não é necessário fornecer uma definição de esquema.

Observação: é possível modificar o esquema da tabela ao anexá-la ou substituí-la. Para mais informações sobre alterações de esquema compatíveis durante uma operação de carga, consulte Como modificar esquemas de tabela.

Opcional: forneça a sinalização --location e defina o valor do local.

Estas são outras sinalizações opcionais:

• --destination_kms_key: a chave do Cloud KMS para criptografia dos dados da tabela.

bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Substitua:

• location: seu local. A sinalização --location é opcional. É possível definir um valor padrão para o local usando o arquivo .bigqueryrc;
• format: PARQUET.
• dataset: um conjunto de dados existente
• table: o nome da tabela em que você está carregando dados.
• path_to_source é um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Caracteres curinga também são aceitos

Exemplos:

O comando a seguir carrega dados de gs://mybucket/mydata.parquet e substitui uma tabela chamada mytable em mydataset.

    bq load \
    --replace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

O comando a seguir carrega dados de gs://mybucket/mydata.parquet e anexa dados a uma tabela chamada mytable em mydataset.

    bq load \
    --noreplace \
    --source_format=PARQUET \
    mydataset.mytable \
    gs://mybucket/mydata.parquet

Para mais informações sobre como anexar e substituir tabelas particionadas usando a ferramenta de linha de comando bq , consulte Como anexar e substituir dados de tabelas particionadas.

API

1. Crie um job load que aponte para os dados de origem no Cloud Storage.

2. (Opcional) Especifique o local na propriedade location da seção jobReference do recurso do job.

3. A propriedade source URIs precisa ser totalmente qualificada no formato gs://BUCKET/OBJECT. É possível incluir vários URIs como uma lista separada por vírgulas. Os caracteres curinga também são compatíveis.

4. Especifique o formato de dados definindo a propriedade configuration.load.sourceFormat como PARQUET.

5. Especifique a preferência de gravação definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

Go

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import (
	"context"
	"fmt"

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

// importParquetTruncate demonstrates loading Apache Parquet data from Cloud Storage into a table
// and overwriting/truncating existing data in the table.
func importParquetTruncate(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()

	gcsRef := bigquery.NewGCSReference("gs://cloud-samples-data/bigquery/us-states/us-states.parquet")
	gcsRef.SourceFormat = bigquery.Parquet
	gcsRef.AutoDetect = true
	loader := client.Dataset(datasetID).Table(tableID).LoaderFrom(gcsRef)
	loader.WriteDisposition = bigquery.WriteTruncate

	job, err := loader.Run(ctx)
	if err != nil {
		return err
	}
	status, err := job.Wait(ctx)
	if err != nil {
		return err
	}

	if status.Err() != nil {
		return fmt.Errorf("job completed with error: %v", status.Err())
	}
	return nil
}

Java

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

import com.google.cloud.bigquery.BigQuery;
import com.google.cloud.bigquery.BigQueryException;
import com.google.cloud.bigquery.BigQueryOptions;
import com.google.cloud.bigquery.FormatOptions;
import com.google.cloud.bigquery.Job;
import com.google.cloud.bigquery.JobInfo;
import com.google.cloud.bigquery.JobInfo.WriteDisposition;
import com.google.cloud.bigquery.LoadJobConfiguration;
import com.google.cloud.bigquery.TableId;
import java.math.BigInteger;

public class LoadParquetReplaceTable {

  public static void runLoadParquetReplaceTable() {
    // TODO(developer): Replace these variables before running the sample.
    String datasetName = "MY_DATASET_NAME";
    loadParquetReplaceTable(datasetName);
  }

  public static void loadParquetReplaceTable(String datasetName) {
    try {
      // Initialize client that will be used to send requests. This client only needs to be created
      // once, and can be reused for multiple requests.
      BigQuery bigquery = BigQueryOptions.getDefaultInstance().getService();

      // Imports a GCS file into a table and overwrites table data if table already exists.
      // This sample loads CSV file at:
      // https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
      String sourceUri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet";
      TableId tableId = TableId.of(datasetName, "us_states");

      // For more information on LoadJobConfiguration see:
      // https://googleapis.dev/java/google-cloud-clients/latest/com/google/cloud/bigquery/LoadJobConfiguration.Builder.html
      LoadJobConfiguration configuration =
          LoadJobConfiguration.builder(tableId, sourceUri)
              .setFormatOptions(FormatOptions.parquet())
              // Set the write disposition to overwrite existing table data.
              .setWriteDisposition(WriteDisposition.WRITE_TRUNCATE)
              .build();

      // For more information on Job see:
      // https://googleapis.dev/java/google-cloud-clients/latest/index.html?com/google/cloud/bigquery/package-summary.html
      // Load the table
      Job job = bigquery.create(JobInfo.of(configuration));

      // Load data from a GCS parquet file into the table
      // Blocks until this load table job completes its execution, either failing or succeeding.
      Job completedJob = job.waitFor();
      if (completedJob == null) {
        System.out.println("Job not executed since it no longer exists.");
        return;
      } else if (completedJob.getStatus().getError() != null) {
        System.out.println(
            "BigQuery was unable to load into the table due to an error: \n"
                + job.getStatus().getError());
        return;
      }

      // Check number of rows loaded into the table
      BigInteger numRows = bigquery.getTable(tableId).getNumRows();
      System.out.printf("Loaded %d rows. \n", numRows);

      System.out.println("GCS parquet overwrote existing table successfully.");
    } catch (BigQueryException | InterruptedException e) {
      System.out.println("Table extraction job was interrupted. \n" + e.toString());
    }
  }
}

Node.js

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

// Import the Google Cloud client libraries
const {BigQuery} = require('@google-cloud/bigquery');
const {Storage} = require('@google-cloud/storage');

// Instantiate clients
const bigquery = new BigQuery();
const storage = new Storage();

/**
 * This sample loads the CSV file at
 * https://storage.googleapis.com/cloud-samples-data/bigquery/us-states/us-states.csv
 *
 * TODO(developer): Replace the following lines with the path to your file.
 */
const bucketName = 'cloud-samples-data';
const filename = 'bigquery/us-states/us-states.parquet';

async function loadParquetFromGCSTruncate() {
  /**
   * Imports a GCS file into a table and overwrites
   * table data if table already exists.
   */

  /**
   * TODO(developer): Uncomment the following lines before running the sample.
   */
  // const datasetId = "my_dataset";
  // const tableId = "my_table";

  // Configure the load job. For full list of options, see:
  // https://cloud.google.com/bigquery/docs/reference/rest/v2/Job#JobConfigurationLoad
  const metadata = {
    sourceFormat: 'PARQUET',
    // Set the write disposition to overwrite existing table data.
    writeDisposition: 'WRITE_TRUNCATE',
    location: 'US',
  };

  // Load data from a Google Cloud Storage file into the table
  const [job] = await bigquery
    .dataset(datasetId)
    .table(tableId)
    .load(storage.bucket(bucketName).file(filename), metadata);
  // load() waits for the job to finish
  console.log(`Job ${job.id} completed.`);

  // Check the job's status for errors
  const errors = job.status.errors;
  if (errors && errors.length > 0) {
    throw errors;
  }
}

PHP

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

use Google\Cloud\BigQuery\BigQueryClient;
use Google\Cloud\Core\ExponentialBackoff;

/** Uncomment and populate these variables in your code */
// $projectId = 'The Google project ID';
// $datasetId = 'The BigQuery dataset ID';
// $tableID = 'The BigQuery table ID';

// instantiate the bigquery table service
$bigQuery = new BigQueryClient([
    'projectId' => $projectId,
]);
$table = $bigQuery->dataset($datasetId)->table($tableId);

// create the import job
$gcsUri = 'gs://cloud-samples-data/bigquery/us-states/us-states.parquet';
$loadConfig = $table->loadFromStorage($gcsUri)->sourceFormat('PARQUET')->writeDisposition('WRITE_TRUNCATE');
$job = $table->runJob($loadConfig);

// poll the job until it is complete
$backoff = new ExponentialBackoff(10);
$backoff->execute(function () use ($job) {
    print('Waiting for job to complete' . PHP_EOL);
    $job->reload();
    if (!$job->isComplete()) {
        throw new Exception('Job has not yet completed', 500);
    }
});

// check if the job has errors
if (isset($job->info()['status']['errorResult'])) {
    $error = $job->info()['status']['errorResult']['message'];
    printf('Error running job: %s' . PHP_EOL, $error);
} else {
    print('Data imported successfully' . PHP_EOL);
}

Python

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

Para autenticar no BigQuery, configure o Application Default Credentials. Para mais informações, acesse Configurar a autenticação para bibliotecas de cliente.

Para substituir as linhas em uma tabela existente, defina a propriedade LoadJobConfig.write_disposition como WRITE_TRUNCATE.

import io

from google.cloud import bigquery

# Construct a BigQuery client object.
client = bigquery.Client()

# TODO(developer): Set table_id to the ID of the table to create.
# table_id = "your-project.your_dataset.your_table_name

job_config = bigquery.LoadJobConfig(
    schema=[
        bigquery.SchemaField("name", "STRING"),
        bigquery.SchemaField("post_abbr", "STRING"),
    ],
)

body = io.BytesIO(b"Washington,WA")
client.load_table_from_file(body, table_id, job_config=job_config).result()
previous_rows = client.get_table(table_id).num_rows
assert previous_rows > 0

job_config = bigquery.LoadJobConfig(
    write_disposition=bigquery.WriteDisposition.WRITE_TRUNCATE,
    source_format=bigquery.SourceFormat.PARQUET,
)

uri = "gs://cloud-samples-data/bigquery/us-states/us-states.parquet"
load_job = client.load_table_from_uri(
    uri, table_id, job_config=job_config
)  # Make an API request.

load_job.result()  # Waits for the job to complete.

destination_table = client.get_table(table_id)
print("Loaded {} rows.".format(destination_table.num_rows))

Como carregar dados Parquet particionados do Hive

O BigQuery é compatível com o carregamento de dados Parquet particionados do Hive armazenados no Cloud Storage e preenche as colunas de particionamento do Hive como colunas na tabela gerenciada de destino do BigQuery. Para mais informações, consulte Como carregar dados particionados externamente.

Conversões Parquet

Nesta seção, descrevemos como o BigQuery analisa vários tipos de dados ao carregar dados Parquet.

Alguns tipos de dados Parquet, como INT32, INT64, BYTE_ARRAY e FIXED_LEN_BYTE_ARRAY, podem ser convertidos em vários tipos de dados do BigQuery. Para garantir que o BigQuery converta os tipos de dados Parquet corretamente, especifique o tipo apropriado no arquivo Parquet.

Por exemplo, para converter o tipo de dados Parquet INT32 para o tipo de dados DATE do BigQuery, especifique o seguinte:

optional int32 date_col (DATE);

O BigQuery converte tipos de dados Parquet nos tipos de dados do BigQuery descritos nas seções a seguir.

Conversões de tipos

Tipo Parquet	Tipos lógicos do Parquet	Tipo de dados BigQuery
BOOLEAN	Nenhum	BOOLEANO
INT32	Nenhum, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32)	INT64
INT32	DECIMAL	NUMERIC, BIGNUMERIC ou STRING
INT32	DATE	DATE
INT64	Nenhum, INTEGER (UINT_64, INT_64)	INT64
INT64	DECIMAL	NUMERIC, BIGNUMERIC ou STRING
INT64	TIMESTAMP, precision=MILLIS (TIMESTAMP_MILLIS)	TIMESTAMP
INT64	TIMESTAMP, precision=MICROS (TIMESTAMP_MICROS)	TIMESTAMP
INT96	Nenhum	TIMESTAMP
FLOAT	Nenhum	FLOAT64
DOUBLE	Nenhum	FLOAT64
BYTE_ARRAY	Nenhum	BYTES
BYTE_ARRAY	STRING (UTF8)	STRING
FIXED_LEN_BYTE_ARRAY	DECIMAL	NUMERIC, BIGNUMERIC ou STRING
FIXED_LEN_BYTE_ARRAY	Nenhum	BYTES

Os grupos aninhados são convertidos em tipos STRUCT. Outras combinações de tipos Parquet e convertidos não são compatíveis.

Tipos lógicos não assinados

Os tipos Parquet UINT_8, UINT_16, UINT_32 e UINT_64 não estão assinados. O BigQuery trata os valores com esses tipos como não assinados ao carregar em uma coluna INTEGER assinada do BigQuery. No caso deUINT_64 um erro será retornado se o valor não sinalizado exceder o máximoINTEGER de 9.223.372.036.854.775.807.

Tipo lógico decimal

Os tipos lógicos Decimal podem ser convertidos em tipos NUMERIC, BIGNUMERIC ou STRING. O tipo convertido depende dos parâmetros de precisão e escalonamento do tipo lógico decimal e dos tipos decimais de destino especificados. Especifique o tipo decimal de destino da seguinte forma:

• Para um job de carregamento usando a API jobs.insert, use o campo JobConfigurationLoad.decimalTargetTypes.
• Para um job de carregamento usando o comando bq load na ferramenta de linha de comando bq, use a sinalização --decimal_target_types.
• Para uma consulta em uma tabela com fontes externas, use o campo ExternalDataConfiguration.decimalTargetTypes.
• Para uma tabela externa permanente criada com DDL, use a opção decimal_target_types.

Tipo lógico enum

Os tipos lógicos Enum podem ser convertidos em STRING ou BYTES. Especifique o tipo decimal de destino da seguinte forma:

• Para um job de carregamento usando a API jobs.insert, use o campo JobConfigurationLoad.parquetOptions.
• Para um job de carregamento usando o comando bq load na ferramenta de linha de comando bq, use a sinalização --parquet_enum_as_string.
• Para uma tabela externa permanente criada com bq mk: use a sinalização --parquet_enum_as_string.

Listar tipo lógico

É possível ativar a inferência de esquema para os tipos lógicos LIST Parquet. O BigQuery verifica se o nó LIST está no formato padrão ou em um dos formulários descritos pelas regras de compatibilidade com versões anteriores:

// standard form
<optional | required> group <name> (LIST) {
  repeated group list {
    <optional | required> <element-type> element;
  }
}

Em caso afirmativo, o campo correspondente ao nó LIST no esquema convertido será tratado como se o nó tivesse o seguinte esquema:

repeated <element-type> <name>

Os nós "list" e "element" são omitidos.

• Para um job de carregamento usando a API jobs.insert, use o campo JobConfigurationLoad.parquetOptions.
• Para um job de carregamento usando o comando bq load na ferramenta de linha de comando bq, use a flag --parquet_enable_list_inference.
• Para uma tabela externa permanente criada com bq mk, use a flag --parquet_enable_list_inference.
• Para uma tabela externa persistente criada com a instrução CREATE EXTERNAL TABLE, use a opção enable_list_inference.

Dados geoespaciais

É possível carregar arquivos em parquet que contêm WKT, WKB codificado em hexadecimal ou GeoJSON em uma coluna STRING ou WKB em uma coluna BYTE_ARRAY especificando um esquema do BigQuery com o tipo GEOGRAPHY. Consulte Como carregar dados geoespaciais.

Observação: tenha cuidado ao usar essa abordagem para dados do GeoParquet. O BigQuery não lê metadados sobre o sistema de coordenadas e a orientação do polígono.

Conversões de nome de coluna

O nome da coluna pode conter letras (a-z, A-Z), números (0-9) ou sublinhados (_) e precisa começar com uma letra ou sublinhado. Se você usa nomes de coluna flexíveis, o BigQuery aceita iniciar um nome de coluna com um número. Tenha cuidado ao iniciar colunas com um número, já que o uso de nomes de colunas flexíveis com a API BigQuery Storage Read ou a API BigQuery Storage Write requer tratamento especial. Para mais informações sobre o suporte a nomes de colunas flexíveis, consulte nomes de colunas flexíveis.

Os nomes das colunas podem ter no máximo 300 caracteres. Os nomes de colunas não podem usar nenhum dos seguintes prefixos:

• _TABLE_
• _FILE_
• _PARTITION
• _ROW_TIMESTAMP
• __ROOT__
• _COLIDENTIFIER

Não é permitido haver nomes de coluna duplicados, mesmo com diferença de maiúsculas e minúsculas. Por exemplo, uma coluna chamada Column1 é considerada idêntica a uma coluna chamada column1. Para saber mais sobre regras de nomenclatura de coluna, consulte Nomes de coluna na referência do GoogleSQL.

Se um nome de tabela (por exemplo, test) é igual a um de seus nomes de coluna (por exemplo, test), a expressão SELECT interpreta a coluna test como um STRUCT, que contém todas as outras colunas da tabela. Para evitar essa colisão, use um dos seguintes métodos:

• Evite usar o mesmo nome para uma tabela e suas colunas.

• Atribua um alias diferente à tabela. Por exemplo, a consulta a seguir atribui um alias de tabela t à tabela project1.dataset.test:

  SELECT test FROM project1.dataset.test AS t;
  

• Inclua o nome da tabela ao fazer referência a uma coluna. Por exemplo:

  SELECT test.test FROM project1.dataset.test;
  

Nomes de colunas flexíveis

Visualização

Este produto ou recurso está sujeito aos "Termos das ofertas pré-GA" na seção "Termos de Serviço gerais" dos Termos específicos do serviço. Os produtos e recursos pré-GA estão disponíveis "no estado em que se encontram" e podem ter suporte limitado. Para mais informações, consulte as descrições da fase de lançamento.

Agora você tem mais flexibilidade para nomear as colunas, incluindo mais acesso a caracteres em outros idiomas além de inglês, bem como outros símbolos.

Os nomes de colunas flexíveis são compatíveis com os seguintes caracteres:

• Qualquer letra em qualquer idioma, conforme representado pela expressão regular Unicode \p{L}.
• Qualquer caractere numérico em qualquer idioma, conforme representado pela expressão regular Unicode \p{N}.
• Qualquer caractere de pontuação do conector, incluindo sublinhados, conforme representado pela expressão regular Unicode \p{Pc}.
• Hífen ou traço, conforme representado pela expressão regular Unicode \p{Pd}.
• Qualquer marca destinada a acompanhar outro caractere, conforme representado pela expressão regular Unicode \p{M}. Por exemplo, acentos, trema ou caixas de delimitação.
• Estes caracteres especiais:
  • Um "e" comercial (&), conforme representado pela expressão regular Unicode \u0026.
  • Um sinal de porcentagem (%), conforme representado pela expressão regular Unicode \u0025.
  • Um sinal de igual (=), conforme representado pela expressão regular Unicode \u003D.
  • Um sinal de adição (+), conforme representado pela expressão regular Unicode \u002B.
  • Dois-pontos (:), conforme representado pela expressão regular Unicode \u003A.
  • Um apóstrofo ('), conforme representado pela expressão regular Unicode \u0027.
  • Um sinal de menor que (<), conforme representado pela expressão regular Unicode \u003C.
  • Um sinal de maior que (>), conforme representado pela expressão regular Unicode \u003E.
  • Um sinal numérico (#), conforme representado pela expressão regular Unicode \u0023.
  • Uma linha vertical (|), conforme representado pela expressão regular Unicode \u007c.
  • Espaço em branco.

Os nomes de colunas flexíveis não são compatíveis com os seguintes caracteres especiais:

• Um ponto de exclamação (!), conforme representado pela expressão regular Unicode \u0021.
• Aspas ("), conforme representadas pela expressão regular Unicode \u0022.
• Um cifrão ($), conforme representado pela expressão regular Unicode \u0024.
• Um parêntese esquerdo ((), conforme representado pela expressão regular Unicode \u0028.
• Um parêntese direito ()), conforme representado pela expressão regular Unicode \u0029.
• Um asterisco (*), conforme representado pela expressão regular Unicode \u002A.
• Uma vírgula (,), conforme representado pela expressão regular Unicode \u002C.
• Um ponto (.), conforme representado pela expressão regular Unicode \u002E.
• Uma barra (/), conforme representada pela expressão regular Unicode \u002F.
• Ponto e vírgula (;), conforme representado pela expressão regular Unicode \u003B.
• Um ponto de interrogação (?), conforme representado pela expressão regular Unicode \u003F.
• Um sinal de arroba (@), conforme representado pela expressão regular Unicode \u0040.
• Um colchete esquerdo ([), conforme representado pela expressão regular Unicode \u005B.
• Uma barra invertida (\), conforme representado pela expressão regular Unicode \u005C.
• Um colchete direito (]), conforme representado pela expressão regular Unicode \u005D.
• Um acento circunflexo (^), conforme representado pela expressão regular Unicode \u005E.
• Um acento grave (`), conforme representado pela expressão regular Unicode \u0060.
• Uma chave à esquerda ({), conforme representado pela expressão regular Unicode \u007B.
• Uma chave à direita (}), conforme representado pela expressão regular Unicode \u007D.
• Um til (~) conforme representado pela expressão regular Unicode \u007E.

Para acessar outras diretrizes, consulte Nomes de colunas.

Os caracteres da coluna expandida são compatíveis com a API BigQuery Storage Read e a API BigQuery Storage Write. Para usar a lista expandida de caracteres Unicode com a API BigQuery Storage Read, é necessário definir uma flag. É possível usar o atributo displayName para recuperar o nome da coluna. O exemplo a seguir mostra como definir uma flag com o cliente Python:

from google.cloud.bigquery_storage import types
requested_session = types.ReadSession()

#set avro serialization options for flexible column.
options = types.AvroSerializationOptions()
options.enable_display_name_attribute = True
requested_session.read_options.avro_serialization_options = options

Para usar a lista expandida de caracteres Unicode com a API BigQuery Storage Write, forneça o esquema com a notação column_name, a menos que você esteja usando o objeto gravador JsonStreamWriter. O exemplo a seguir mostra como fornecer o esquema:

syntax = "proto2";
package mypackage;
// Source protos located in github.com/googleapis/googleapis
import "google/cloud/bigquery/storage/v1/annotations.proto";

message FlexibleSchema {
  optional string item_name_column = 1
  [(.google.cloud.bigquery.storage.v1.column_name) = "name-列"];
  optional string item_description_column = 2
  [(.google.cloud.bigquery.storage.v1.column_name) = "description-列"];
}

Neste exemplo, item_name_column e item_description_column são nomes de marcadores que precisam estar em conformidade com a convenção de nomenclatura do buffer de protocolo. Observe que as anotações column_name sempre têm precedência sobre nomes de marcadores.

• Por padrão, o carregamento de dados do Parquet não é compatível com nomes de colunas flexíveis. Para se inscrever nesse pré-lançamento, preencha o formulário de inscrição. Depois de se registrar na visualização, todos os nomes de coluna inválidos (por exemplo, ordenação de nomes de colunas) retornam um erro. Para projetos não registrados, a solicitação de carregamento substitui os caracteres inválidos por sublinhados em vez de retornar um erro.
• Por padrão, o carregamento de dados CSV usando detecção automática de esquema não é compatível com nomes de colunas flexíveis. Para se inscrever nesse pré-lançamento, preencha o formulário de inscrição. Depois de se registrar na visualização, todos os nomes de coluna inválidos (por exemplo, ordenação de nomes de colunas) retornam um erro. Para projetos não registrados, a solicitação de carregamento substitui os caracteres inválidos por sublinhados em vez de retornar um erro.

Limitações

Nomes de colunas flexíveis não são compatíveis com tabelas externas.

não é possível carregar arquivos Parquet que contenham colunas com um ponto final (.) no nome da coluna.

Se o nome de uma coluna Parquet contiver outros caracteres (além de um ponto final), os caracteres serão substituídos por sublinhados. Para evitar colisões, você pode adicionar sublinhados à direita nos nomes das colunas. Por exemplo, se um arquivo Parquet tiver duas colunas Column1 e column1, elas serão carregadas como Column1 e column1_, respectivamente.

Como depurar o arquivo Parquet

Se os jobs de carregamento falharem com erros de dados, use o PyArrow para verificar se os arquivos de dados Parquet estão corrompidos. Se o PyArrow não conseguir ler os arquivos, eles provavelmente serão rejeitados pelo job de carregamento do BigQuery. O exemplo a seguir mostra como ler o conteúdo de um arquivo Parquet usando o PyArrow:

from pyarrow import parquet as pq

# Read the entire file
pq.read_table('your_sample_file.parquet')
# Read specific columns
pq.read_table('your_sample_file.parquet',columns=['some_column', 'another_column'])
# Read the metadata of specific columns
file_metadata=pq.read_metadata('your_sample_file.parquet')
for col in file_metadata.row_group(0).to_dict()['columns']:
    print col['column_path_in_schema']
    print col['num_values']

Para mais informações, consulte os documentos do PyArrow.