Formate a saída da CLI cbt

Este documento descreve como formatar tipos específicos de dados armazenados em linhas do Bigtable quando apresentados pela CLI cbt.

Exemplos de formatação

A partir da versão 0.12.0, a cbt CLI pode formatar determinados tipos complexos de dados armazenados em linhas de tabelas. Quando usa o comando cbt read ou cbt lookup, a cbtCLIcbt pode "imprimir de forma organizada" os valores armazenados nas linhas.

O exemplo seguinte mostra a saída de dados da CLI cbt sem formatação.

----------------------------------------
r1
  fam1:col1                                 @ 2022/03/09-11:19:45.966000
    "\n\x05Brave\x10\x02"
  fam1:col2                                 @ 2022/03/14-11:17:20.014000
    "{\"name\": \"Brave\", \"age\": 2}"

O exemplo seguinte mostra a saída de dados da CLI cbt com formatação.

r1
  fam1:col1                                 @ 2022/03/09-11:19:45.966000
    name: "Brave"
    age: 2
  fam1:col2                                 @ 2022/03/14-11:17:20.014000
    age:     2.00
    name:   "Brave"

Para formatar uma coluna ou uma família de colunas, tem de fornecer um ficheiro YAML que especifique a formatação dessa coluna. Quando chama cbt lookup ou cbt read, transmite o caminho para o ficheiro YAML com o argumento format-file. O fragmento seguinte mostra um exemplo de chamada de cbt lookup com o argumento format-file fornecido.

cbt lookup my-table r1 format-file=/path/to/formatting.yml

Defina formatos de dados de colunas em YAML

O ficheiro YAML de formatação tem de associar os nomes das colunas ou os nomes das famílias de colunas aos tipos de dados armazenados nos mesmos. O fragmento seguinte mostra um exemplo de um ficheiro de formatação YAML.

protocol_buffer_definitions:
  - cat.proto
protocol_buffer_paths:
  - testdata/


columns:
  col1:
    encoding: ProtocolBuffer
    type: Cat

  col2:
    encoding: json

O fragmento seguinte mostra o conteúdo de "cat.proto".

syntax = "proto3";
package cats;

option go_package = "github.com/protocolbuffers/protobuf/examples/go/tutorialpb";

message Cat {
  string name = 1;
  int32 age = 2;
}

Analisando o exemplo:

  • O campo protocol_buffer_definitions fornece uma lista de ficheiros .proto que podem conter tipos de mensagens de buffer de protocolo a usar para descodificar dados protobuf.
  • O campo protocol_buffer_paths fornece uma lista de caminhos locais que podem conter ficheiros .proto para descodificar tipos de buffer de protocolo. Não precisa de especificar as localizações das importações de buffers de protocolo padrão, como mensagens no pacote google/protobuf.

  • O campo columns contém uma lista de nomes de colunas com os tipos de dados correspondentes para cada coluna:

    • A coluna protobuf tem o encoding definido como "ProtocolBuffer" e o type está definido como "Cat". A CLI cbt interpreta e formata todos os valores armazenados nesta coluna como um tipo de mensagem Catproto. O tipo tem de corresponder a um tipo de mensagem definido num dos ficheiros .proto fornecidos para o campo protocol_buffer_definition.
    • A coluna json tem o campo encoding definido como "json". A função cbt interpreta e formata todos os valores armazenados nesta coluna como uma estrutura JSON.

Outros campos que pode indicar:

  • default_encoding: este campo define uma formatação predefinida para todas as colunas numa tabela ou todas as colunas numa família de colunas.
  • default_type: este campo define um tipo de dados predefinido para colunas codificadas em buffer de protocolo, big-endian e little-endian.

  • families: este campo define as codificações e os tipos de todas as colunas numa família de colunas. Pode fornecer um default_encoding e um default_type para uma família de colunas. Também pode substituir estas codificações ao nível da coluna fornecendo um campo columns que liste as colunas por nome com a codificação e os tipos de dados adequados, conforme mostrado no seguinte fragmento:

    families:
  family1:
    default_encoding: BigEndian
    default_type: INT64
    columns:
      address:
        encoding: PROTO
        type: tutorial.Person

Tipos de dados suportados

A cbt CLI suporta a formatação de vários tipos de dados complexos. A tabela seguinte apresenta os tipos de dados e as strings suportados a indicar no ficheiro YAML para cada um dos tipos de listas. Os valores das strings não são sensíveis a maiúsculas e minúsculas.

Tipo de dados Formatar o valor para YAML
Hexadecimal Hex, H
Big-endian BigEndian, B
Little-endian LittleEndian, L
Buffer de protocolo ProtocolBuffer, P, PROTO
JSON JSON, J

Tabela 1. Tipos de dados suportados para formatação na saída cbt.

  • A codificação hexadecimal é independente do tipo. Os dados são apresentados como uma representação hexadecimal não processada dos dados armazenados.
  • Os tipos disponíveis para as codificações big-endian e little-endian são int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32 e float64. O comprimento dos dados armazenados tem de ser um múltiplo do tamanho do tipo, em bytes. Os dados são apresentados como escalares se o comprimento armazenado corresponder ao tamanho do tipo ou como matrizes caso contrário. Os nomes dos tipos não são sensíveis a maiúsculas e minúsculas.
  • Os tipos indicados para a codificação protocol-buffer têm de corresponder aos tipos de mensagens definidos nos ficheiros de definição de protocol-buffer fornecidos. Os tipos não são sensíveis a maiúsculas e minúsculas. Se não for especificado nenhum tipo, a predefinição é o nome da coluna para os dados da coluna que estão a ser apresentados.
  • Os valores de formatação para YAML não são sensíveis a maiúsculas e minúsculas.