Exporte dados para o Bigtable (ETL inverso)

Este documento descreve como pode configurar o ETL inverso (RETL) do BigQuery para o Bigtable. Pode fazê-lo através da declaração EXPORT DATA para exportar dados de uma tabela do BigQuery para uma tabela do Bigtable.

Pode usar um fluxo de trabalho RETL para o Bigtable para combinar as capacidades de estatísticas do BigQuery com a baixa latência e o elevado débito do Bigtable. Este fluxo de trabalho permite-lhe publicar dados para utilizadores da aplicação sem esgotar as quotas e os limites no BigQuery.

Caraterísticas das tabelas do Bigtable

As tabelas do Bigtable diferem das tabelas do BigQuery de várias formas:

  • As tabelas do Bigtable e do BigQuery são compostas por linhas, mas uma linha do Bigtable é composta por uma chave de linha e famílias de colunas que têm um número arbitrário de colunas pertencentes à mesma família de colunas.
  • As famílias de colunas de uma determinada tabela são criadas no momento da criação da tabela, mas também podem ser adicionadas ou removidas posteriormente. Quando é criada uma família de colunas, não é necessário especificar as colunas que lhe pertencem.
  • Não é necessário definir as colunas do Bigtable antecipadamente, e estas podem ser usadas para armazenar dados no respetivo nome (também conhecido como qualificador) dentro dos limites de tamanho dos dados nas tabelas.
  • As colunas do Bigtable podem ter qualquer valor binário dentro dos limites de tamanho dos dados nas tabelas.
  • As colunas do Bigtable têm sempre uma dimensão temporal (também conhecida como versão). Pode armazenar qualquer número de valores em qualquer linha para a mesma coluna, desde que a data/hora não seja idêntica.
  • Uma data/hora do Bigtable é medida em microssegundos desde a hora de época Unix. Por exemplo, 0 representa 1970-01-01T00:00:00 UTC. As indicações de tempo têm de ser um número não negativo de microssegundos com granularidade de milissegundos (apenas são aceites múltiplos de 1000 us). A data/hora predefinida 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 através de um filtro. É necessária, pelo menos, uma chave de linha ou um intervalo de chaves de linhas em todos os tipos de pedidos de leitura, exceto numa análise completa da tabela.

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

Antes de começar

Tem de criar uma instância do Bigtable e uma tabela do Bigtable para receber os dados exportados.

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.

Funções necessárias

Para receber as autorizações de que precisa para exportar dados do BigQuery para o Bigtable, peça ao seu administrador que lhe conceda as seguintes funções do IAM no seu projeto:

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.

Também pode conseguir as autorizações necessárias através de funções personalizadas ou outras funções predefinidas.

Limitações

Considerações sobre a localização

  • Se o seu conjunto de dados do BigQuery estiver numa região múltipla, o perfil da app do Bigtable tem de ser configurado para encaminhar dados para um cluster do Bigtable nessa região múltipla. Por exemplo, se o seu conjunto de dados do BigQuery estiver na USmultirregião, o cluster do Bigtable pode estar localizado na região us-west1 (Oregão), que se encontra nos Estados Unidos.
  • Se o seu conjunto de dados do BigQuery estiver numa única região, o perfil da app do Bigtable tem de ser configurado para encaminhar dados para um cluster do Bigtable na mesma região. Por exemplo, se o seu conjunto de dados do BigQuery estiver na região asia-northeast1 (Tóquio), o cluster do Bigtable também tem de estar na região asia-northeast1 (Tóquio).

Para mais informações, consulte o artigo Localizações do Bigtable.

Tipos do BigQuery suportados

Os seguintes tipos de dados são suportados quando são escritos no Bigtable:

Tipo do BigQuery Valor do Bigtable escrito
BYTES Exportado tal como está.
STRING Convertido em BYTES.
INTEGER Se bigtable_options.column_families.encoding estiver definido como BINARY, o valor é escrito num formato de 8 bytes, big-endian (byte mais significativo primeiro). Se bigtable_options.column_families.encoding estiver definido como TEXT, o valor é escrito como uma string legível que representa um número.
FLOAT Escreve o valor no formato de saída de 8 bytes IEEE 754.
BOOLEAN Se bigtable_options.column_families.encoding estiver definido como BINARY, o valor é escrito como um valor de 1 byte (false = 0x00 ou true = 0x01). Se bigtable_options.column_families.encoding estiver definido como TEXT, o valor é escrito como texto ("true" ou "false").
JSON
Uma coluna exportada do tipo JSON é interpretada como um grupo de colunas pertencentes a uma família de colunas do Bigtable específica. Os membros do objeto JSON são interpretados como colunas e os respetivos valores são escritos no Bigtable. O nome da coluna a escrever pode ser ajustado através da configuração bigtable_options.

Por exemplo:
    JSON '{"FIELD1": "VALUE1", "FIELD2": "VALUE2"}' as MY_COLUMN_FAMILY
Em que os valores VALUE1 e VALUE2 são escritos no Bigtable como colunas FIELD1 e FIELD2 para a família de colunas MY_COLUMN_FAMILY.
STRUCT
Uma coluna exportada do tipo STRUCT é interpretada como um grupo de colunas pertencentes a uma família de colunas do Bigtable específica. Os membros da struct são interpretados como colunas e os respetivos valores a serem escritos no Bigtable. O nome da coluna a escrever pode ser ajustado através da configuração bigtable_options.

Por exemplo:
    STRUCT<FIELD1  STRING, FIELD2 INTEGER> as MY_COLUMN_FAMILY
Em que os valores FIELD1 e FIELD2 são escritos no Bigtable como colunas FIELD1 e FIELD2 para a família de colunas MY_COLUMN_FAMILY.

Estes tipos de dados suportados 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 tem nenhum análogo para os valores NULL. A exportação de um NULL valor para uma determinada família de colunas e coluna no Bigtable elimina os valores presentes de uma linha do Bigtable.

  • Se um valor do Bigtable com uma determinada chave de linha, família de colunas, qualificador de coluna e data/hora não existir antes da exportação, os valores NULL exportados não têm efeito na linha do Bigtable.

  • Quando exporta um valor NULL do tipo STRUCT ou JSON, todos os valores das colunas pertencentes à família de colunas correspondente da linha afetada são eliminados. Deve converter o valor NULL para o tipo STRUCT ou JSON para que o motor SQL anexe um tipo correto ao mesmo. A consulta seguinte elimina todos os dados da família de colunas column_family1 com um conjunto de chaves de linhas fornecidas:

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

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

Configure as exportações com o bigtable_options

Pode usar a configuração bigtable_options durante uma exportação para colmatar as diferenças entre os modelos de armazenamento do BigQuery e do Bigtable. A configuração é expressa sob a forma de uma string JSON, como se vê no exemplo seguinte:

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 seguinte descreve os campos possíveis usados numa bigtable_options configuração:

Nome do campo Descrição
columnFamilies Uma matriz de descritores de famílias de colunas.
columnFamilies.familyId Identificador da família de colunas do Bigtable.
columnFamilies.encoding O valor pode ser definido como BINARY ou TEXT. Para obter informações sobre como os tipos são codificados, consulte o artigo Tipos do BigQuery suportados.
columnFamilies.columns Uma matriz de mapeamentos de colunas do Bigtable.
columnFamilies.columns.qualifierString Opcional: um qualificador de coluna do Bigtable. Especifique este 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 não especificar qualifierString nem qualifierEncoded, é usado fieldName como qualificador de coluna.
columnFamilies.columns.qualifierEncoded Opcional: qualificador de coluna codificado em Base64. Semelhante a qualifierString, caso o qualificador de coluna tenha de 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 ver um exemplo de como um valor fieldName vazio é usado com campos de tipos simples, consulte o artigo Prepare os resultados da consulta para exportação.

Prepare os resultados da consulta para exportação

Para exportar os resultados da consulta para o Bigtable, os resultados têm de cumprir os seguintes requisitos:

  • O conjunto de resultados tem de conter uma coluna rowkey do tipo STRING ou BYTES.
  • As chaves de linhas, os qualificadores de colunas, os valores e as datas/horas não podem exceder os limites de tamanho dos dados do Bigtable nas tabelas.
  • Tem de estar presente, pelo menos, uma coluna que não seja rowkey no conjunto de resultados.
  • Cada coluna do conjunto de resultados tem de ser de um dos tipos do BigQuery suportados. Todos os tipos de colunas não suportados têm de ser convertidos num dos tipos suportados antes da exportação para o Bigtable.

O Bigtable não exige que os qualificadores de colunas sejam nomes de colunas do BigQuery válidos e suporta a utilização de quaisquer bytes. Para obter informações sobre a substituição dos qualificadores de colunas de destino para uma exportação, consulte o artigo Configure exportações com bigtable_options.

Se usar valores exportados com APIs Bigtable, como ReadModifyWriteRow, todos os valores numéricos têm de usar a codificação binária correta.

Por predefinição, as colunas de resultados autónomas de tipos diferentes de STRUCT ou JSON são interpretadas como valores para famílias de colunas de destino iguais ao nome da coluna de resultados e o qualificador de coluna igual a uma string vazia.

Para demonstrar como estes tipos de dados são escritos, considere o seguinte exemplo de SQL, em que column e column2 são colunas de resultados autónomas:

SELECT
  x as column1, y as column2
FROM table

Nesta consulta de exemplo, SELECT x as column1 escreve valores no Bigtable na família de colunas column1 e no qualificador de coluna '' (string vazia) quando processa tipos diferentes de JSON ou STRUCT.

Pode alterar a forma como estes tipos são escritos numa exportação através da configuração bigtable_options, como mostrado no exemplo seguinte:

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 do BigQuery T contém a seguinte linha:

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

Se usar a configuração bigtable_options anterior com a tabela T, os seguintes dados são escritos no Bigtable:

rowkey sales_info (família de colunas) ordered_at (família de colunas)
101 produto valor 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 a hora de época Unix no fuso horário UTC.

Crie automaticamente novas famílias de colunas

Para criar automaticamente novas famílias de colunas numa tabela do Bigtable, defina a opção auto_create_column_families na declaração EXPORT DATA como true. Esta opção requer a autorização bigtable.tables.update, que está incluída em funções como a de administrador do Bigtable (roles/bigtable.admin).

EXPORT DATA OPTIONS (
uri="https://bigtable.googleapis.com/projects/PROJECT-ID/instances/INSTANCE-ID/appProfiles/APP_PROFILE_ID/tables/TABLE",
format="CLOUD_BIGTABLE",
auto_create_column_families = true
) AS
SELECT
  order_id as rowkey,
  STRUCT(product, amount) AS sales_info
FROM T

Defina a indicação de tempo para todas as células numa linha através de _CHANGE_TIMESTAMP

Pode adicionar uma coluna _CHANGE_TIMESTAMP do tipo TIMESTAMP ao resultado para exportação. Cada célula escrita no Bigtable usa o valor do carimbo de data/hora da _CHANGE_TIMESTAMP da linha de resultado exportada.

O Bigtable não suporta datas/horas anteriores à época Unix (1970-01-01T00:00:00Z). Se o valor de _CHANGE_TIMESTAMP for NULL, a hora epoch Unix de 0 é usada como o valor de data/hora predefinido.

A consulta seguinte escreve células para as colunas product e amount com a data/hora especificada 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

Exporte continuamente

Se quiser processar continuamente uma consulta de exportação, pode configurá-la como uma consulta contínua.

Exporte vários resultados com o mesmo valor de rowkey

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

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

id customer order_timestamp amount_spent
100 João 2023-01-01T10:10:54Z 10,99
101 Alice 2023-01-02T12:10:50Z 102,7
102 João 2023-01-04T15:17:01Z 11.1

Em seguida, o utilizador executa a seguinte declaraçã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

A utilização desta declaração com a tabela orders do BigQuery resulta nos seguintes dados escritos no Bigtable:

orders_column_family
Chave da linha amount_spent
Alice 2023-01-02T12:10:50Z 102,7
João 2023-01-01T10:10:54Z 10,99
2023-01-04T15:17:01Z 11.1

A exportação para o Bigtable une os novos valores à tabela, em vez de substituir linhas inteiras. Se já existirem valores no Bigtable para uma chave de linha, os novos valores podem substituir parcial ou totalmente os valores anteriores, consoante a família de colunas, os nomes das colunas e as datas/horas das células que estão a ser escritas.

Exporte várias colunas como valores de Protocol Buffer (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 tendo em conta a forma como os diferentes tipos são processados entre o BigQuery e o Bigtable. Pode usar funções definidas pelo utilizador (UDFs) do BigQuery para exportar dados como valores binários Protobuf para o Bigtable. Para mais informações, consulte o artigo Exporte dados como colunas Protobuf.

Otimização da exportação

Pode alterar a taxa de transferência à qual os registos são exportados do BigQuery para o Bigtable modificando o número de nós no cluster de destino do Bigtable. O débito (linhas escritas por segundo) é ajustado linearmente com o número de nós no cluster de destino. Por exemplo, se duplicar o número de nós no cluster de destino, o débito de exportação duplica aproximadamente.

Preços

Quando exporta dados numa consulta padrão, a faturação é feita com base nos preços de extração de dados. Quando exporta dados numa consulta contínua, a faturação é feita através dos preços de computação de capacidade do BigQuery. Para executar consultas contínuas, tem de ter uma reserva que use a edição Enterprise ou Enterprise Plus e uma atribuição de reserva que use o tipo de tarefa CONTINUOUS.

Após a exportação dos dados, é-lhe cobrado o armazenamento dos dados no Bigtable. Para mais informações, consulte os preços do Bigtable.