Carregar dados Parquet a partir do Cloud Storage

Esta página apresenta uma vista geral do carregamento de dados Parquet do Cloud Storage para o BigQuery.

O Parquet é um formato de dados orientado para colunas de código aberto amplamente usado no ecossistema do Apache Hadoop.

Quando carrega dados Parquet do Cloud Storage, pode carregá-los para uma nova tabela ou partição, ou pode anexá-los ou substituir uma tabela ou uma partição existente. Quando os dados são carregados para o BigQuery, são convertidos para o formato de colunas para o Capacitor (o formato de armazenamento do BigQuery).

Quando carrega dados do Cloud Storage para uma tabela do BigQuery, o conjunto de dados que contém a tabela tem de estar na mesma localização regional ou multirregional que o contentor do Cloud Storage.

Para informações sobre como carregar dados Parquet a partir de um ficheiro local, consulte o artigo Carregar dados a partir de ficheiros locais.

Limitações

Está sujeito às seguintes limitações quando carrega dados para o BigQuery a partir de um contentor do Cloud Storage:

  • O BigQuery não garante a consistência dos dados para origens de dados externas. As alterações aos dados subjacentes durante a execução de uma consulta podem resultar num comportamento inesperado.

  • O BigQuery não suporta o controlo de versões de objetos do Cloud Storage. Se incluir um número de geração no URI do Cloud Storage, a tarefa de carregamento falha.

  • Não pode usar um caráter universal no URI do Cloud Storage se algum dos ficheiros a carregar tiver esquemas diferentes. Qualquer diferença na posição das colunas é considerada um esquema diferente.

Requisitos do ficheiro de entrada

Para evitar erros resourcesExceeded ao carregar ficheiros Parquet para o BigQuery, siga estas diretrizes:

  • Mantenha os tamanhos das linhas iguais ou inferiores a 50 MB.
  • Se os dados de entrada contiverem mais de 100 colunas, considere reduzir o tamanho da página para um valor inferior ao tamanho da página predefinido (1 * 1024 * 1024 bytes). Isto é especialmente útil se estiver a usar uma compressão significativa.
  • Para um desempenho ideal, procure ter tamanhos de grupos de linhas de, pelo menos, 16 MiB. Os tamanhos de grupos de linhas mais pequenos aumentam a E/S e tornam os carregamentos e as consultas mais lentos.

Antes de começar

Conceda funções de gestão de identidade e de acesso (IAM) que dão aos utilizadores as autorizações necessárias para realizar cada tarefa neste documento e crie um conjunto de dados para armazenar os seus dados.

Autorizações necessárias

Para carregar dados para o BigQuery, precisa de autorizações da IAM para executar uma tarefa de carregamento e carregar dados para tabelas e partições do BigQuery. Se estiver a carregar dados do Cloud Storage, também precisa de autorizações de IAM para aceder ao contentor que contém os seus dados.

Autorizações para carregar dados para o BigQuery

Para carregar dados para uma nova tabela ou partição do BigQuery, ou para anexar ou substituir uma tabela ou uma partição existente, precisa das seguintes autorizações de IAM:

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

Cada uma das seguintes funções de IAM predefinidas inclui as autorizações de que precisa para carregar dados para uma tabela ou uma partição do BigQuery:

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

Além disso, se tiver a autorização bigquery.datasets.create, pode criar e atualizar tabelas através de uma tarefa de carregamento nos conjuntos de dados que criar.

Para mais informações sobre as funções e as autorizações do IAM no BigQuery, consulte o artigo Funções e autorizações predefinidas.

Autorizações para carregar dados do Cloud Storage

Para receber as autorizações de que precisa para carregar dados de um contentor do Cloud Storage, peça ao seu administrador para lhe conceder a função de IAM Administrador de armazenamento (roles/storage.admin) no contentor. Para mais informações sobre a atribuição de funções, consulte o artigo Faça a gestão do acesso a projetos, pastas e organizações.

Esta função predefinida contém as autorizações necessárias para carregar dados a partir de um contentor do Cloud Storage. Para ver as autorizações exatas que são necessárias, expanda a secção Autorizações necessárias:

Autorizações necessárias

São necessárias as seguintes autorizações para carregar dados de um contentor do Cloud Storage:

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

Também pode conseguir estas autorizações com funções personalizadas ou outras funções predefinidas.

Crie um conjunto de dados

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

Esquemas Parquet

Quando carrega ficheiros Parquet para o BigQuery, o esquema da tabela é obtido automaticamente dos dados de origem autodescritivos. Quando o BigQuery obtém o esquema dos dados de origem, é usado o ficheiro alfabeticamente último.

Por exemplo, tem os seguintes ficheiros Parquet no Cloud Storage:

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

A execução deste comando na ferramenta de linhas de comando bq carrega todos os ficheiros (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 carrega vários ficheiros Parquet com esquemas diferentes, as colunas idênticas especificadas em vários esquemas têm de ter o mesmo modo em cada definição de esquema.

Quando o BigQuery deteta o esquema, alguns tipos de dados Parquet são convertidos em tipos de dados do BigQuery para os tornar compatíveis com a sintaxe do GoogleSQL. Para mais informações, consulte o artigo Conversões de 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 comandos bq para o URL do ficheiro de referência.

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

Compressão Parquet

O BigQuery suporta os seguintes codecs de compressão para o conteúdo de ficheiros Parquet:

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

Carregar dados Parquet para uma nova tabela

Pode carregar dados Parquet para uma nova tabela através de um dos seguintes métodos:

  • A Google Cloud consola
  • O comando bq load da ferramenta de linhas de comando bq
  • O método da API jobs.insert e a configuração de uma tarefa load
  • As bibliotecas cliente

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

Consola

  1. Na Google Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
  3. Na secção Informações do conjunto de dados, clique em Criar tabela.
  4. No painel Criar tabela, especifique os seguintes detalhes:
    1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
      1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Google Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir. selecione o ficheiro de origem para criar uma tabela do BigQuery
      2. Em Formato de ficheiro, selecione Parquet.
    2. Na secção Destino, especifique os seguintes detalhes:
      1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
      2. No campo Tabela, introduza o nome da tabela que quer criar.
      3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
    3. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros Parquet.
    4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas.
    5. Clique em Opções avançadas e faça o seguinte:
      • Para Preferência de escrita, deixe a opção Escrever se estiver vazio selecionada. Esta opção cria uma nova tabela e carrega os seus dados na mesma.
      • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
      • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google-managed key, o BigQuery encripta os dados em repouso.
    6. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte carrega um ficheiro Parquet para a nova tabela mytable:

  1. Na Google Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaraçã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, consulte o artigo Execute uma consulta interativa.

bq

Use o comando bq load, especifique PARQUET usando a flag --source_format e inclua um URI do Cloud Storage. Pode incluir um único URI, uma lista de URIs separados por vírgulas ou um URI que contenha um caractere universal.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

Outras flags opcionais incluem:

  • --time_partitioning_type: ativa a partição baseada no tempo numa tabela e define o tipo de partição. Os valores possíveis são HOUR, DAY, MONTH e YEAR. Esta flag é opcional quando cria uma tabela particionada numa coluna DATE, DATETIME ou TIMESTAMP. O tipo de partição predefinido para a partição baseada no tempo é DAY. Não pode alterar a especificação de partição numa tabela existente.
  • --time_partitioning_expiration: um número inteiro que especifica (em segundos) quando uma partição baseada no tempo deve ser eliminada. O tempo de expiração é avaliado como a data UTC da partição mais o valor inteiro.
  • --time_partitioning_field: a coluna DATE ou TIMESTAMP usada para criar uma tabela particionada. Se a partição baseada no tempo estiver ativada sem este valor, é criada uma tabela particionada por tempo de ingestão.
  • --require_partition_filter: quando ativada, esta opção exige que os utilizadores incluam uma cláusula WHERE que especifique as partições a consultar. A exigência de um filtro de partição pode reduzir o custo e melhorar o desempenho. Para mais informações, consulte o artigo Exija um filtro de partição nas consultas.
  • --clustering_fields: uma lista separada por vírgulas de até quatro nomes de colunas usados para criar uma tabela agrupada.
  • --destination_kms_key: a chave do Cloud KMS para a encriptação dos dados da tabela.

  • --column_name_character_map: define o âmbito e o processamento de carateres nos nomes das colunas, com a opção de ativar nomes de colunas flexíveis. Para mais informações, consulte load_option_list. Para mais informações sobre carateres suportados e não suportados, consulte os nomes de colunas flexíveis.

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

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

    Para mais informações sobre a encriptação de tabelas, consulte:

Para carregar dados Parquet para o BigQuery, introduza o seguinte comando:

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

Substitua o seguinte:

  • LOCATION: a sua localização. A flag --location é opcional. Por exemplo, se estiver a usar o BigQuery na região de Tóquio, pode definir o valor da flag como asia-northeast1. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
  • FORMAT: PARQUET.
  • DATASET: um conjunto de dados existente.
  • TABLE: o nome da tabela para a qual está a carregar dados.
  • PATH_TO_SOURCE: um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Os carateres universais também são suportados.

Exemplos:

O comando seguinte carrega dados de gs://mybucket/mydata.parquet para uma tabela denominada mytable em mydataset.

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

O comando seguinte carrega dados de gs://mybucket/mydata.parquet para uma tabela particionada por tempo de carregamento com o nome mytable em mydataset.

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

O comando seguinte carrega dados de gs://mybucket/mydata.parquet para uma tabela particionada denominada mytable em mydataset. A tabela está particionada na coluna mytimestamp.

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

O comando seguinte carrega dados de vários ficheiros em gs://mybucket/ para uma tabela denominada mytable em mydataset. O URI do Cloud Storage usa um caráter universal.

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

O comando seguinte carrega dados de vários ficheiros em gs://mybucket/ para uma tabela denominada mytable em mydataset. O comando inclui uma lista de URIs do Cloud Storage separados por vírgulas com carateres universais.

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

API

  1. Crie uma tarefa load que aponte para os dados de origem no Cloud Storage.

  2. (Opcional) Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

  3. A propriedade source URIs tem de estar totalmente qualificada no formato gs://BUCKET/OBJECT. Cada URI pode conter um carater universal "*".

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

  5. Para verificar o estado da tarefa, chame jobs.get(JOB_ID*), substituindo JOB_ID pelo ID da tarefa devolvido pelo pedido inicial.

    • Se status.state = DONE, a tarefa foi concluída com êxito.
    • Se a propriedade status.errorResult estiver presente, o pedido falhou e esse objeto inclui informações que descrevem o que correu mal. Quando um pedido falha, não é criada nenhuma tabela nem são carregados dados.
    • Se status.errorResult estiver ausente, a tarefa foi concluída com êxito; no entanto, podem ter ocorrido alguns erros não fatais, como problemas na importação de algumas linhas. Os erros não fatais são apresentados na propriedade status.errors do objeto de tarefa devolvido.

Notas da API:

  • Os trabalhos de carregamento são atómicos e consistentes: se um trabalho de carregamento falhar, nenhum dos dados está disponível e, se um trabalho de carregamento for bem-sucedido, todos os dados estão disponíveis.

  • Como prática recomendada, gere um ID exclusivo e transmita-o como jobReference.jobId quando chamar jobs.insert para criar uma tarefa de carregamento. Esta abordagem é mais robusta em caso de falha de rede, uma vez que o cliente pode sondar ou tentar novamente com o ID da tarefa conhecido.

  • A chamada jobs.insert num determinado ID da tarefa é idempotente. Pode tentar novamente quantas vezes quiser com o mesmo ID da tarefa e, no máximo, uma dessas operações vai ter êxito.

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Use o método Client.load_table_from_uri() para iniciar uma tarefa de carregamento a partir do Cloud Storage. Para usar o Parquet, defina a propriedade LoadJobConfig.source_format para a string PARQUET e transmita a configuração da tarefa 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))

Anexar ou substituir uma tabela com dados Parquet

Pode carregar dados adicionais para uma tabela a partir de ficheiros de origem ou acrescentando resultados de consultas.

Na Google Cloud consola, use a opção Preferência de escrita para especificar que ação realizar quando carregar dados de um ficheiro de origem ou de um resultado de consulta.

Tem as seguintes opções quando carrega dados adicionais numa tabela:

Opção da consola Sinalização da ferramenta bq Propriedade da API BigQuery Descrição
Escrever se estiver vazio Não suportado WRITE_EMPTY Escreve os dados apenas se a tabela estiver vazia.
Anexar à tabela --noreplace ou --replace=false; se --[no]replace não estiver especificado, a predefinição é anexar WRITE_APPEND (Predefinição) Anexa os dados ao final da tabela.
Substituir tabela --replace ou --replace=true WRITE_TRUNCATE Apaga todos os dados existentes numa tabela antes de escrever os novos dados. Esta ação também elimina o esquema da tabela, a segurança ao nível da linha e remove qualquer chave do Cloud KMS.

Se carregar dados para uma tabela existente, a tarefa de carregamento pode anexar os dados ou substituir a tabela.

Pode acrescentar ou substituir uma tabela através de um dos seguintes métodos:

  • A Google Cloud consola
  • O comando bq load da ferramenta de linhas de comando bq
  • O método da API jobs.insert e a configuração de uma tarefa load
  • As bibliotecas cliente

Para acrescentar ou substituir uma tabela com dados Parquet:

Consola

  1. Na Google Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No painel Explorador, expanda o seu projeto e, de seguida, selecione um conjunto de dados.
  3. Na secção Informações do conjunto de dados, clique em Criar tabela.
  4. No painel Criar tabela, especifique os seguintes detalhes:
    1. Na secção Origem, selecione Google Cloud Storage na lista Criar tabela a partir de. Em seguida, faça o seguinte:
      1. Selecione um ficheiro do contentor do Cloud Storage ou introduza o URI do Cloud Storage. Não pode incluir vários URIs na Google Cloud consola, mas os carateres universais são suportados. O contentor do Cloud Storage tem de estar na mesma localização que o conjunto de dados que contém a tabela que quer criar, acrescentar ou substituir. selecione o ficheiro de origem para criar uma tabela do BigQuery
      2. Em Formato de ficheiro, selecione Parquet.
    2. Na secção Destino, especifique os seguintes detalhes:
      1. Para Conjunto de dados, selecione o conjunto de dados no qual quer criar a tabela.
      2. No campo Tabela, introduza o nome da tabela que quer criar.
      3. Verifique se o campo Tipo de tabela está definido como Tabela nativa.
    3. Na secção Esquema, não é necessária nenhuma ação. O esquema é autodescrito em ficheiros Parquet.
    4. Opcional: especifique as definições de partição e cluster. Para mais informações, consulte os artigos Criar tabelas particionadas e Criar e usar tabelas agrupadas. Não pode converter uma tabela numa tabela particionada ou agrupada anexando-a ou substituindo-a. A Google Cloud consola não suporta a anexação nem a substituição de tabelas particionadas ou agrupadas num trabalho de carregamento.
    5. Clique em Opções avançadas e faça o seguinte:
      • Para Preferência de escrita, escolha Anexar à tabela ou Substituir tabela.
      • Se quiser ignorar valores numa linha que não estejam presentes no esquema da tabela, selecione Valores desconhecidos.
      • Para Encriptação, clique em Chave gerida pelo cliente para usar uma chave do Cloud Key Management Service. Se deixar a definição Google-managed key, o BigQuery encripta os dados em repouso.
    6. Clique em Criar tabela.

SQL

Use a LOAD DATA declaração DDL. O exemplo seguinte anexa um ficheiro Parquet à tabela mytable:

  1. Na Google Cloud consola, aceda à página BigQuery.

    Aceda ao BigQuery

  2. No editor de consultas, introduza a seguinte declaraçã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, consulte o artigo Execute uma consulta interativa.

bq

Introduza o comando bq load com a flag --replace para substituir a tabela. Use a flag --noreplace para anexar dados à tabela. Se não for especificada nenhuma flag, a predefinição é anexar dados. Forneça a flag --source_format e defina-a como PARQUET. Uma vez que os esquemas Parquet são obtidos automaticamente dos dados de origem autodescritivos, não tem de fornecer uma definição de esquema.

(Opcional) Forneça a flag --location e defina o valor para a sua localização.

Outras flags opcionais incluem:

  • --destination_kms_key: a chave do Cloud KMS para a encriptação dos dados da tabela.
bq --location=LOCATION load \
--[no]replace \
--source_format=FORMAT \
DATASET.TABLE \
PATH_TO_SOURCE

Substitua o seguinte:

  • location: a sua localização. A flag --location é opcional. Pode predefinir um valor para a localização através do ficheiro.bigqueryrc.
  • format: PARQUET.
  • dataset: um conjunto de dados existente.
  • table: o nome da tabela para a qual está a carregar dados.
  • path_to_source: um URI do Cloud Storage totalmente qualificado ou uma lista de URIs separados por vírgulas. Os carateres universais também são suportados.

Exemplos:

O comando seguinte carrega dados de gs://mybucket/mydata.parquet e substitui uma tabela denominada mytable em mydataset.

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

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

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

Para ver informações sobre como anexar e substituir tabelas particionadas através da ferramenta de linha de comandos bq, consulte o artigo Anexar e substituir dados de tabelas particionadas.

API

  1. Crie uma tarefa load que aponte para os dados de origem no Cloud Storage.

  2. (Opcional) Especifique a sua localização na propriedade location na secção jobReference do recurso de emprego.

  3. A propriedade source URIs tem de ser totalmente qualificada no formato gs://BUCKET/OBJECT. Pode incluir vários URIs como uma lista separada por vírgulas. Tenha em atenção que os carateres universais também são suportados.

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

  5. Especifique a preferência de escrita definindo a propriedade configuration.load.writeDisposition como WRITE_TRUNCATE ou WRITE_APPEND.

Go

Antes de experimentar este exemplo, siga as Goinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Go BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Javainstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Java BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Node.jsinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Node.js BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as PHPinstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API PHP BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure 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 experimentar este exemplo, siga as Pythoninstruções de configuração no início rápido do BigQuery com bibliotecas cliente. Para mais informações, consulte a API Python BigQuery documentação de referência.

Para se autenticar no BigQuery, configure as Credenciais padrão da aplicação. Para mais informações, consulte o artigo Configure a autenticação para bibliotecas de cliente.

Para anexar as linhas a uma tabela existente, defina a propriedade LoadJobConfig.write_disposition como WRITE_APPEND.

Para substituir as linhas numa tabela existente, defina a propriedade LoadJobConfig.write_disposition comoWRITE_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))

Carregar dados Parquet particionados por Hive

O BigQuery suporta o carregamento de dados Parquet particionados por Hive armazenados no Cloud Storage e preenche as colunas de particionamento por Hive como colunas na tabela gerida do BigQuery de destino. Para mais informações, consulte o artigo Carregar dados particionados externamente.

Conversões de parquet

Esta secção descreve 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 converte corretamente os tipos de dados Parquet, especifique o tipo de dados adequado no ficheiro Parquet.

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

optional int32 date_col (DATE);

O BigQuery converte os tipos de dados Parquet nos tipos de dados do BigQuery descritos nas secções seguintes.

Conversões de tipo

Tipo de parquet Tipos lógicos do Parquet Tipo de dados do BigQuery
BOOLEAN Nenhum BOOLEAN
INT32 Nenhum, INTEGER (UINT_8, UINT_16, UINT_32, INT_8, INT_16, INT_32) INT64
INT32 DECIMAL NUMERIC, BIGNUMERIC ou STRING
INT32 DATE DATA
INT64 Nenhuma, 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 tipos convertidos não são suportadas.

Tipos lógicos não assinados

Os tipos Parquet UINT_8, UINT_16, UINT_32 e UINT_64 não têm sinal. O BigQuery trata os valores com estes tipos como não assinados quando os carrega numa coluna INTEGER assinada do BigQuery. No caso de UINT_64, é devolvido um erro se o valor não assinado exceder o valor máximo de INTEGER 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 escala do tipo lógico decimal e dos tipos de destino decimal especificados. Especifique o tipo de destino decimal da seguinte forma:

Tipo lógico de enumeração

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

Tipo lógico da lista

Pode ativar a inferência de esquemas para tipos lógicos LIST Parquet. O BigQuery verifica se o nó LIST está na forma padrão ou numa das formas descritas pelas regras de compatibilidade com versões anteriores:

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

Se sim, o campo correspondente do nó LIST no esquema convertido é tratado como se o nó tivesse o seguinte esquema:

repeated <element-type> <name>

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

Dados geoespaciais

Pode carregar ficheiros Parquet que contenham WKT, WKB codificado em hexadecimal ou GeoJSON numa coluna STRING ou WKB numa coluna BYTE_ARRAY especificando um esquema do BigQuery com o tipo GEOGRAPHY. Para mais informações, consulte o artigo Carregar dados geoespaciais.

Também pode carregar ficheiros GeoParquet. Neste caso, as colunas descritas pelos metadados GeoParquet são interpretadas como do tipo GEOGRAPHY por predefinição. Também pode carregar os dados WKB não processados numa coluna BYTES fornecendo um esquema explícito. Para mais informações, consulte o artigo Carregar ficheiros GeoParquet.

Conversões de nomes de colunas

Um nome de coluna pode conter letras (a-z, A-Z), números (0-9) ou sublinhados (_), e tem de começar por uma letra ou um sublinhado. Se usar nomes de colunas flexíveis, o BigQuery suporta o início de um nome de coluna com um número. Tenha cuidado ao iniciar colunas com um número, uma vez que a utilização de nomes de colunas flexíveis com a API BigQuery Storage Read ou a API BigQuery Storage Write requer um processamento especial. Para mais informações sobre o suporte de nomes de colunas flexíveis, consulte o artigo Nomes de colunas flexíveis.

Os nomes das colunas têm um comprimento máximo de 300 carateres. Os nomes das colunas não podem usar nenhum dos seguintes prefixos:

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

Não são permitidos nomes de colunas duplicados, mesmo que a utilização de maiúsculas e minúsculas seja diferente. Por exemplo, uma coluna denominada Column1 é considerada idêntica a uma coluna denominada column1. Para saber mais sobre as regras de nomenclatura de colunas, consulte Nomes das colunas na referência do GoogleSQL.

Se o nome de uma tabela (por exemplo, test) for igual a um dos nomes das respetivas colunas (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 esta colisão, use um dos seguintes métodos:

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

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

    SELECT test FROM project1.dataset.test AS t;

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

    SELECT test.test FROM project1.dataset.test;

Nomes de colunas flexíveis

Tem mais flexibilidade na forma como denomina as colunas, incluindo acesso expandido a carateres em idiomas que não o inglês, bem como símbolos adicionais. Certifique-se de que usa carateres de acento grave (`) para incluir nomes de colunas flexíveis se forem Identificadores entre aspas.

Os nomes de colunas flexíveis suportam os seguintes carateres:

  • Qualquer letra em qualquer idioma, conforme representado pela expressão regular Unicode \p{L}.
  • Qualquer caráter numérico em qualquer idioma, representado pela expressão regular Unicode \p{N}.
  • Qualquer caráter de pontuação de conetor, incluindo sublinhados, conforme representado pela expressão regular Unicode \p{Pc}.
  • Um hífen ou um travessão representado pela expressão regular Unicode \p{Pd}.
  • Qualquer marca destinada a acompanhar outro caráter, conforme representado pela expressão regular Unicode \p{M}. Por exemplo, acentos, trema ou caixas delimitadoras.
  • Os seguintes carateres especiais:
    • Um E comercial (&), representado pela expressão regular Unicode \u0026.
    • Um sinal de percentagem (%) representado pela expressão regular Unicode \u0025.
    • Um sinal de igual (=) representado pela expressão regular Unicode \u003D.
    • Um sinal de mais (+) representado pela expressão regular Unicode \u002B.
    • Um dois pontos (:) representado pela expressão regular Unicode \u003A.
    • Um apóstrofo (') representado pela expressão regular Unicode \u0027.
    • Um sinal de menor do que (<), representado pela expressão regular Unicode \u003C.
    • Um sinal de maior do que (>) representado pela expressão regular Unicode \u003E.
    • Um sinal de número (#), representado pela expressão regular Unicode \u0023.
    • Uma linha vertical (|) representada pela expressão regular Unicode \u007c.
    • Espaço em branco.

Os nomes de colunas flexíveis não suportam os seguintes carateres especiais:

  • Um ponto de exclamação (!) representado pela expressão regular Unicode \u0021.
  • Uma marca de aspas ("), representada pela expressão regular Unicode \u0022.
  • Um cifrão ($) representado pela expressão regular Unicode \u0024.
  • Um parêntese esquerdo (() representado pela expressão regular Unicode \u0028.
  • Um parêntese direito ()), representado pela expressão regular Unicode \u0029.
  • Um asterisco (*), representado pela expressão regular Unicode \u002A.
  • Uma vírgula (,) representada pela expressão regular Unicode \u002C.
  • Um ponto (.), representado pela expressão regular Unicode \u002E. Os pontos não são substituídos por sublinhados nos nomes das colunas do ficheiro Parquet quando é usado um mapa de carateres do nome da coluna. Para mais informações, consulte as limitações das colunas flexíveis.
  • Uma barra (/) representada pela expressão regular Unicode \u002F.
  • Um ponto e vírgula (;) representado pela expressão regular Unicode \u003B.
  • Um ponto de interrogação (?), representado pela expressão regular Unicode \u003F.
  • Um sinal de arroba (@) representado pela expressão regular Unicode \u0040.
  • Um parêntesis reto esquerdo ([) representado pela expressão regular Unicode \u005B.
  • Uma barra invertida (\), representada pela expressão regular Unicode \u005C.
  • Um parêntesis reto direito (]), representado pela expressão regular Unicode \u005D.
  • Um acento circunflexo (^), representado pela expressão regular Unicode \u005E.
  • Um acento grave (`) representado pela expressão regular Unicode \u0060.
  • Uma chaveta esquerda {{) representada pela expressão regular Unicode \u007B.
  • Uma chaveta direita (}) representada pela expressão regular Unicode \u007D.
  • Um til (~) representado pela expressão regular Unicode \u007E.

Para ver diretrizes adicionais, consulte o artigo Nomes das colunas.

Os carateres de coluna expandidos são suportados pela API BigQuery Storage Read e pela API BigQuery Storage Write. Para usar a lista expandida de carateres Unicode com a API BigQuery Storage Read, tem de definir uma flag. Pode usar o atributo displayName para obter o nome da coluna. O exemplo seguinte 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 carateres Unicode com a API Storage Write do BigQuery, tem de fornecer o esquema com a notação column_name, a menos que esteja a usar o objeto de gravação JsonStreamWriter. O exemplo seguinte 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 de posição que têm de estar em conformidade com a convenção de nomenclatura do protocol buffer. Tenha em atenção que as anotações column_name têm sempre precedência sobre os nomes dos marcadores de posição.

Limitações

  • Os nomes de colunas flexíveis não são suportados com tabelas externas.

  • Não pode carregar ficheiros Parquet que contenham colunas com um ponto final (.) no nome da coluna.

  • Os nomes das colunas dos ficheiros Parquet são tratados como não sensíveis a maiúsculas e minúsculas quando são carregados no BigQuery. Os nomes idênticos que não são sensíveis a maiúsculas e minúsculas causam conflitos. Para evitar esta situação, acrescente um caráter de sublinhado a um dos nomes de colunas duplicados ou mude o nome das colunas antes do carregamento.

Depurar o ficheiro Parquet

Se as tarefas de carregamento falharem com erros de dados, pode usar o PyArrow para verificar se os seus ficheiros de dados Parquet estão danificados. Se o PyArrow não conseguir ler os ficheiros, é provável que os ficheiros sejam rejeitados pela tarefa de carregamento do BigQuery. O exemplo seguinte mostra como ler o conteúdo de um ficheiro Parquet através do 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 a documentação do PyArrow.