Exportar dados para o Bigtable (ETL reverso)

Neste documento, descrevemos como configurar um ETL reverso (RETL, na sigla em inglês) do BigQuery para o Bigtable. É possível fazer isso usando a instrução EXPORT DATA para exportar dados de uma tabela do BigQuery para uma tabela do Bigtable.

Os usuários do BigQuery podem configurar um fluxo de trabalho RETL no Bigtable que combina os recursos de análise do BigQuery com a baixa latência e a alta capacidade de processamento do Bigtable. Esse fluxo de trabalho permite disponibilizar dados para usuários de aplicativos sem esgotar cotas e limites no BigQuery.

Características das tabelas do Bigtable

As tabelas do Bigtable são diferentes das tabelas do BigQuery de várias maneiras:

  • As tabelas do Bigtable e do BigQuery são feitas de linhas, mas uma linha do Bigtable é composta por chaves de linha e grupos de colunas que têm um número arbitrário de colunas que pertence ao mesmo grupo.
  • Os grupos de colunas de uma determinada tabela são criados no momento da criação dela, mas também podem ser adicionados ou removidos posteriormente. Quando um grupo de colunas é criado, as colunas que pertencem a ele não precisam ser especificadas.
  • As colunas do Bigtable não precisam ser definidas com antecedência e podem ser usadas para armazenar dados no nome delas (também conhecido como qualificador) dentro dos limites de tamanho de dados nas tabelas.
  • As colunas do Bigtable podem ter qualquer valor binário dentro dos limites de tamanho de dados nas tabelas.
  • As colunas do Bigtable sempre têm uma dimensão temporal (também conhecida como versão). Qualquer número de valores pode ser armazenado em qualquer linha para a mesma coluna, desde que o carimbo de data/hora não seja idêntico.
  • Um carimbo de data/hora do Bigtable é medido em microssegundos desde o horário da era Unix. Por exemplo, 0 representa 1970-01-01T00:00:00 UTC. Os carimbos de data/hora precisam ser um número não negativo de microssegundos com granularidade de milissegundos (somente múltiplos de 1.000us são aceitos). O carimbo de data/hora padrão do Bigtable é 0.
  • Os dados no Bigtable são lidos por chave de linha, várias chaves de linha, intervalo de chaves de linha ou usando um filtro. Pelo menos uma chave de linha ou um intervalo de chaves de linha é necessário em todos os tipos de solicitações de leitura, exceto em uma verificação completa da tabela.

Para mais informações sobre como preparar os resultados do BigQuery para exportação para o Bigtable, consulte Preparar os resultados da consulta para exportação.

Antes de começar

Atribua papéis do Identity and Access Management (IAM) que concedam aos usuários as permissões necessárias para realizar cada tarefa deste documento.

Funções exigidas

Para conseguir as permissões necessárias para exportar dados do BigQuery para o Bigtable, peça ao administrador para conceder a você os seguintes papéis do IAM no seu projeto:

Para mais informações sobre como conceder papéis, consulte Gerenciar acesso.

Também é possível conseguir as permissões necessárias com papéis personalizados ou outros papéis predefinidos.

Limitações

Considerações sobre o local

  • Se o conjunto de dados do BigQuery estiver em um local multirregional, o perfil do app Bigtable precisará ser configurado para rotear dados a um cluster do Bigtable dentro dessa multirregião. Por exemplo, se o conjunto de dados do BigQuery estiver na multirregião US, o cluster do Bigtable poderá estar localizado na região us-west1 (Oregon), nos Estados Unidos.
  • Se o conjunto de dados do BigQuery estiver em uma única região, seu perfil do aplicativo Bigtable precisará ser configurado para rotear dados para um cluster do Bigtable na mesma região. Por exemplo, se o conjunto de dados do BigQuery estiver na região asia-northeast1 (Tóquio), seu cluster do Bigtable também precisará estar na região asia-northeast1 (Tóquio).

Para mais informações, consulte Locais do Bigtable.

Tipos compatíveis do BigQuery

Quando são gravados no Bigtable, os seguintes tipos de dados são aceitos:

Tipo do BigQuery Valor do Bigtable gravado
BYTES Exportado no estado em que se encontra.
STRING Convertido para BYTES
INTEGER Se bigtable_options.column_families.encoding for definido como BINARY, o valor será escrito em um formato big-endian de 8 bytes (byte mais significativo primeiro). Se bigtable_options.column_families.encoding for definido como TEXT, o valor será escrito como uma string legível que representa um número.
FLOAT Grava o valor no formato de saída IEEE 754 de 8 bytes.
BOOLEAN Se bigtable_options.column_families.encoding for definido como BINARY, o valor será escrito como um valor de 1 byte (false = 0x00 ou true = 0x01). Se bigtable_options.column_families.encoding for definido como TEXT, o valor será escrito como um texto ("true" ou "false").
JSON
Uma coluna exportada do tipo JSON é interpretada como um grupo de colunas pertencente a um grupo específico de colunas do Bigtable. Os membros do objeto JSON são interpretados como colunas e os valores deles precisam ser gravados no Bigtable. O nome da coluna a ser escrita pode ser ajustado usando a configuração bigtable_options.

Exemplo:
    JSON '{"FIELD1": "VALUE1", "FIELD2": "VALUE2"}' as MY_COLUMN_FAMILY
Em que os valores VALUE1 e VALUE2 são gravados no Bigtable como colunas FIELD1 e FIELD2 no grupo de colunas MY_COLUMN_FAMILY.
STRUCT
Uma coluna exportada do tipo STRUCT é interpretada como um grupo de colunas pertencente a um grupo específico de colunas do Bigtable. Os membros do struct são interpretados como colunas e os valores deles a serem gravados no Bigtable. O nome da coluna a ser escrita pode ser ajustado usando a configuração bigtable_options.

Exemplo:
    STRUCT<FIELD1  STRING, FIELD2 INTEGER> as MY_COLUMN_FAMILY
Em que os valores FIELD1 e FIELD2 são gravados no Bigtable como colunas FIELD1 e FIELD2 no grupo de colunas MY_COLUMN_FAMILY.

Esses tipos de dados compatíveis são semelhantes à leitura de tabelas externas do Bigtable para o BigQuery.

Valores NULL no Bigtable

Os valores NULL no Bigtable têm as seguintes restrições:

  • O Bigtable não é análogo para valores NULL. A exportação de um valor NULL para um determinado grupo de colunas e coluna no Bigtable exclui os valores atuais de uma linha do Bigtable.

  • Se um valor do Bigtable com uma determinada chave de linha, grupo de colunas, qualificador de coluna e carimbo de data/hora não existir antes da exportação, os valores NULL exportados não terão efeito na linha do Bigtable.

  • Ao exportar um valor NULL do tipo STRUCT ou JSON, todos os valores de coluna pertencentes ao grupo de colunas correspondente da linha afetada são excluídos. Transmita o valor NULL ao tipo STRUCT ou JSON para que o mecanismo SQL conecte um tipo correto a ele. A consulta a seguir exclui todos os dados do grupo de colunas column_family1 com um conjunto de chaves de linha determinadas:

    EXPORT DATA OPTIONS (...) AS
SELECT
  rowkey,
CAST(NULL as STRUCT) AS column_family1 FROM T

  • As linhas com chaves de linha NULL são ignoradas durante a exportação. O número de linhas ignoradas é retornado nas estatísticas de exportação para o autor da chamada.

Configurar exportações com bigtable_options

Use a configuração bigtable_options durante uma exportação para resolver as diferenças entre os modelos de armazenamento do BigQuery e do Bigtable. A configuração é expressa na forma de uma string JSON, conforme mostrado neste exemplo:

EXPORT DATA OPTIONS(
   uri="https://bigtable.googleapis.com/projects/PROJECT_ID/instances/INSTANCE_ID/appProfiles/APP_PROFILE_ID/tables/TABLE",
   bigtable_options = """{
     "columnFamilies": [{
       "familyId": "COLUMN_FAMILY_NAME",
       "encoding": "ENCODING_VALUE",
       "columns": [
         {
           "qualifierString": "BIGTABLE_COLUMN_QUALIFIER",
           ["qualifierEncoded": "BASE_64_ENCODED_VALUE",]
           "fieldName": "BIGQUERY_RESULT_FIELD_NAME"
         }
       ]
    }]
   }"""
)

A tabela a seguir descreve os possíveis campos usados em uma configuração bigtable_options:

Nome do campo Descrição
columnFamilies Uma matriz de descritores de grupos de colunas.
columnFamilies.familyId Identificador do grupo de colunas do Bigtable.
columnFamilies.encoding O valor pode ser definido como BINARY ou TEXT. Para informações sobre como os tipos são codificados, consulte Tipos compatíveis do BigQuery.
columnFamilies.columns Uma matriz de mapeamentos de colunas do Bigtable.
columnFamilies.columns.qualifierString Opcional: um qualificador de coluna do Bigtable. Especifique esse valor se o qualificador de coluna não tiver códigos não UTF-8. Os campos qualifierString e qualifierEncoding são mutuamente exclusivos. Se qualifierString e qualifierEncoded não forem especificados, fieldName será usado como qualificador de coluna.
columnFamilies.columns.qualifierEncoded Opcional: qualificador de coluna codificado em Base64. Semelhante a qualifierString, caso o qualificador de coluna precise ter códigos não UTF-8.
columnFamilies.columns.fieldName Obrigatório: nome do campo do conjunto de resultados do BigQuery. Pode ser uma string vazia em determinados casos. Para conferir um exemplo de como um valor fieldName vazio é usado com campos de tipos simples, consulte Preparar os resultados da consulta para exportação.

Preparar os resultados da consulta para exportação

Para exportar resultados de consulta para o Bigtable, eles precisam atender aos seguintes requisitos:

  • O conjunto de resultados precisa conter uma coluna rowkey do tipo STRING ou BYTES.
  • As chaves de linha, os qualificadores de coluna, os valores e os carimbos de data/hora não podem exceder os limites de tamanho de dados nas tabelas do Bigtable.
  • Pelo menos uma coluna diferente de rowkey precisa estar presente no conjunto de resultados.
  • Cada coluna do conjunto de resultados precisa ser de um dos tipos compatíveis do BigQuery. Os tipos de coluna incompatíveis precisam ser convertidos em um dos tipos compatíveis antes de exportar para o Bigtable.

O Bigtable não exige qualificadores de coluna para serem nomes de colunas válidos do BigQuery, e o Bigtable é compatível com o uso de bytes. Para saber mais sobre como substituir qualificadores de coluna de destino para uma exportação, consulte Configurar exportações com bigtable_options.

Se você usar valores exportados com as APIs do Bigtable, como ReadModifyWriteRow, todos os valores numéricos precisarão usar a codificação binária correta.

Por padrão, as colunas de resultados independentes de tipos diferentes de STRUCT ou JSON são interpretadas como valores para grupos de colunas de destino iguais ao nome da coluna de resultado e o qualificador de coluna igual a uma string vazia.

Para demonstrar como esses tipos de dados são gravados, considere o exemplo de SQL a seguir, em que column e column2 são colunas de resultados independentes:

SELECT
  x as column1, y as column2
FROM table

Nesta consulta de exemplo, SELECT x as column1 grava valores no Bigtable no grupo de colunas column1 e no qualificador de coluna '' (string vazia) ao processar tipos diferentes de JSON ou STRUCT

É possível alterar como esses tipos são gravados em uma exportação usando a configuração bigtable_options, conforme mostrado no exemplo a seguir:

EXPORT DATA OPTIONS (
  …
  bigtable_options="""{
   "columnFamilies" : [
      {
        "familyId": "ordered_at",
        "columns": [
           {"qualifierString": "order_time", "fieldName": ""}
        ]
      }
   ]
}"""
) AS
SELECT
  order_id as rowkey,
  STRUCT(product, amount) AS sales_info,
  EXTRACT (MILLISECOND FROM order_timestamp AT TIME ZONE "UTC") AS ordered_at
FROM T

Neste exemplo, a tabela T do BigQuery contém a seguinte linha:

order_id order_timestamp product amount
101 2023-03-28T10:40:54Z Joystick 2

Se você usar a configuração bigtable_options anterior com a tabela T, os dados a seguir serão gravados no Bigtable:

rowkey sales_info (grupo de colunas) ordered_at (grupo de colunas)
101 product amount order_time
1970-01-01T00:00:00Z Joystick 1970-01-01T00:00:00Z 2 1680000054000

1680000054000 representa 2023-03-28T10:40:54Z em milissegundos desde o horário Unix no fuso horário UTC.

Definir o carimbo de data/hora para todas as células em uma linha usando _CHANGE_TIMESTAMP

É possível adicionar uma coluna _CHANGE_TIMESTAMP do tipo TIMESTAMP ao resultado para exportação. Todas as células gravadas no Bigtable usam o valor do carimbo de data/hora do _CHANGE_TIMESTAMP da linha do resultado exportado.

O Bigtable não aceita carimbos de data/hora anteriores à época do Unix (1970-01-01T00:00:00Z). Se o valor de _CHANGE_TIMESTAMP for NULL, o horário da época Unix de 0 será usado como o valor de carimbo de data/hora padrão.

A consulta a seguir grava células para as colunas product e amount com o carimbo de data/hora especificado na coluna order_timestamp da tabela T.

EXPORT DATA OPTIONS (...) AS
SELECT
  rowkey,
  STRUCT(product, amount) AS sales_info,
  order_timestamp as _CHANGE_TIMESTAMP
FROM T

Exportar vários resultados com o mesmo valor rowkey

Quando você exporta um resultado que contém várias linhas com o mesmo valor rowkey, os valores gravados no Bigtable acabam na mesma linha do Bigtable.

Use esse método para gerar várias versões de valores de coluna na mesma linha. Neste exemplo, a tabela orders no BigQuery contém os seguintes dados:

id customer order_timestamp amount_spent
100 Bob 2023-01-01T10:10:54Z 10.99
101 Alice 2023-01-02T12:10:50Z 102.7
102 Bob 2023-01-04T15:17:01Z 11.1

Em seguida, o usuário executa a seguinte instrução EXPORT DATA:

EXPORT DATA OPTIONS (
uri="https://bigtable.googleapis.com/projects/PROJECT-ID/instances/INSTANCE-ID/appProfiles/APP_PROFILE_ID/tables/TABLE",
format="CLOUD_BIGTABLE"
) AS


SELECT customer as rowkey, STRUCT(amount_spent) as orders_column_family, order_timestamp as _CHANGE_TIMESTAMP
FROM orders

O uso dessa instrução com a tabela orders do BigQuery resulta nos seguintes dados gravados no Bigtable:

orders_column_family
Chave de linha amount_spent
Alice 2023-01-02T12:10:50Z 102.7
Bob 2023-01-01T10:10:54Z 10.99
2023-01-04T15:17:01Z 11.1

A exportação para o Bigtable mescla novos valores na tabela em vez de substituir linhas inteiras. Se os valores já estiverem presentes no Bigtable de uma chave de linha, os novos valores poderão substituir parcial ou totalmente os valores anteriores, dependendo do grupo de colunas, dos nomes das colunas e dos carimbos de data/hora das células que estão sendo gravadas.

Exportar várias colunas como valores de buffer de protocolo (Protobuf)

Os buffers de protocolo oferecem um mecanismo flexível e eficiente para serializar dados estruturados. A exportação como Protobuf pode ser benéfica considerando como diferentes tipos são tratados entre o BigQuery e o Bigtable. Use funções definidas pelo usuário (UDFs, na sigla em inglês) do BigQuery para exportar dados como valores binários Protobuf para o Bigtable. Para mais informações, consulte Exportar dados como colunas Protobuf.

Otimização da exportação

Há várias maneiras de aumentar a capacidade de exportação de registros do BigQuery para o Bigtable. É possível otimizar o desempenho de exportação das seguintes formas:

Preços

Para saber mais sobre os preços de exportação de dados, consulte a página de preços do BigQuery.

Depois que os dados são exportados, você é cobrado pelo armazenamento dos dados no Bigtable. Para mais informações, consulte Preços do Bigtable.