Exportar dados para o Bigtable (ETL reverso)

Este documento descreve como configurar o ETL reverso (RETL) 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.

Use um fluxo de trabalho RETL no Bigtable para combinar 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

É necessário criar uma instância do Bigtable e uma tabela do Bigtable para receber os dados exportados.

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:

Exporte dados de uma tabela do BigQuery: Leitor de dados do BigQuery (roles/bigquery.dataViewer)
Execute um job de exportação: Usuário do BigQuery (roles/bigquery.user)
Gravar dados em uma tabela do Bigtable: Usuário do Bigtable (roles/bigtable.user)

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

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

Limitações

A codificação é limitada a BINARY e TEXT.
O perfil do aplicativo Bigtable de destino precisa ser configurado com o roteamento de cluster único e um nível de prioridade de solicitação baixo.
O perfil do aplicativo Bigtable precisa ser configurado para rotear dados para um cluster do Bigtable colocalizado com o conjunto de dados do BigQuery. Para mais informações, consulte Considerações de localização.
As exportações para o Bigtable só são compatíveis com as edições do BigQuery Enterprise ou Enterprise Plus. A edição padrão do BigQuery e a computação sob demanda não são compatíveis.

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`. Observação: um documento JSON aninhado em outro tipo `JSON` ou `STRUCT` é gravado no Bigtable como uma string. A exportação de um valor `STRUCT` aninhado em outro struct está sujeita às limitações explicadas na seção Configurar exportações com `bigtable_options`.
`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<`FIELD`1 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<INT64>) 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	produto		valor		order_time
101	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 continuamente

Se você quiser processar continuamente uma consulta de exportação, configure-a como uma consulta contínua.

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
Bob	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

É possível mudar a capacidade de processamento de exportação de registros do BigQuery para o Bigtable modificando o número de nós no cluster de destino do Bigtable. A capacidade de processamento (linhas gravadas por segundo) é dimensionada linearmente de acordo com o número de nós no cluster de destino. Por exemplo, se você dobrar o número de nós no cluster de destino, a capacidade de processamento de exportação vai aumentar aproximadamente o dobro.

Preços

Quando você exporta dados em uma consulta padrão, a cobrança é feita usando os preços de extração de dados. Quando você exporta dados em uma consulta contínua, a cobrança é feita usando os preços de computação da capacidade do BigQuery. Para executar consultas contínuas, é preciso ter uma reserva que use a edição Enterprise ou Enterprise Plus e uma atribuição de reserva que usa o tipo de job CONTINUOUS.

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