Da formato a los resultados desde la CLI de cbt

En este documento, se describe cómo dar formato a tipos específicos de datos almacenados en filas de Bigtable cuando los muestra la CLI de cbt.

Ejemplos de formato

A partir de la versión 0.12.0, la CLI de cbt puede dar formato a ciertos tipos complejos de datos almacenados en filas de tablas. Cuando usas el comando cbt read o cbt lookup, la CLI de cbt puede “imprimir con precisión” los valores almacenados en las filas.

En el siguiente ejemplo, se muestra la salida de datos de la CLI de cbt sin formato.

----------------------------------------
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}"

En el siguiente ejemplo, se muestra la salida de datos de la CLI de cbt con formato.

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"

Imprime filas con formato

Para dar formato a una columna o familia de columnas, debes proporcionar un archivo YAML que especifique el formato de esa columna. Cuando llamas a cbt lookup o a cbt read, pasas la ruta al archivo YAML con el argumento format-file. En el siguiente fragmento, se muestra un ejemplo de llamada a cbt lookup con el argumento format-file proporcionado.

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

Define los formatos de datos de columna en YAML

El archivo YAML de formato debe conectar los nombres de las columnas o la familia de columnas con los tipos de datos almacenados en ellas. En el siguiente fragmento, se muestra un ejemplo de un archivo de formato YAML.

protocol_buffer_definitions:
  - cat.proto
protocol_buffer_paths:
  - testdata/

columns:
  col1:
    encoding: ProtocolBuffer
    type: Cat

  col2:
    encoding: json

En el siguiente fragmento, se muestra el contenido 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;
}

Lo siguiente se observa en el ejemplo:

• El campo protocol_buffer_definitions proporciona una lista de archivos .proto que pueden contener tipos de mensajes de búfer de protocolo para usar en la decodificación de datos protobuf.
• El campo protocol_buffer_paths proporciona una lista de rutas de acceso locales que pueden contener archivos .proto para decodificar tipos de búferes de protocolo. No es necesario que especifiques las ubicaciones de las importaciones estándar de búferes de protocolo, como los mensajes en el paquete google/protobuf.

• El campo columns contiene una lista de nombres de columnas con los tipos de datos correspondientes para cada columna:

  • La columna protobuf tiene encoding configurado como “ProtocolBuffer” y su type como “Cat”. La CLI de cbt interpreta y formatea todos los valores almacenados en esta columna como un tipo de mensaje proto Cat. El tipo debe corresponder a un tipo de mensaje definido en uno de los archivos .proto proporcionados para el campo protocol_buffer_definition.
  • La columna json tiene su campo encoding configurado como “json”. cbt interpreta y formatea todos los valores almacenados en esta columna como una estructura JSON.

Otros campos que puedes proporcionar:

• default_encoding: Este campo define un formato predeterminado para todas las columnas de una tabla o todas las columnas de una familia de columnas.
• default_type: Este campo define un tipo de datos predeterminado para las columnas con codificación big-endian, little-endian y búfer de protocolo.

• families: Este campo define las codificaciones y los tipos para todas las columnas dentro de una familia de columnas. Puedes proporcionar un default_encoding y un default_type para una familia de columnas. También puedes anular estas codificaciones a nivel de columna mediante un campo columns que enumere las columnas por nombre con los tipos de datos y de codificación adecuados, como se muestra en el siguiente fragmento:

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

Tipos de datos admitidos

La CLI de cbt admite el formato para varios tipos de datos complejos. En la siguiente tabla, se enumeran los tipos de datos admitidos y las strings que deben proporcionarse en el archivo YAML para cada uno de los tipos de listas. Los valores de string no distinguen mayúsculas de minúsculas.

Data type	Valor de formato para YAML
Hexadecimal	Hex, H
Big-endian	BigEndian, B
Little-endian	LittleEndian, L
Búfer de protocolo	ProtocolBuffer, P, PROTO
JSON	JSON, J

Tabla 1. Tipos de datos compatibles con el formato en resultados de cbt.

• La codificación hexadecimal es independiente del tipo. Los datos se muestran como una representación hexadecimal sin procesar de los datos almacenados.
• Los tipos de codificaciones big-endian y little-endian disponibles son los siguientes: int8, int16, int32, int64, uint8, uint16, uint32, uint64, float32 y float64. La longitud de los datos almacenados debe ser un múltiplo del tamaño del tipo, en bytes. Los datos se muestran como escalares si la longitud almacenada coincide con el tamaño del tipo o, de lo contrario, como arrays. Los nombres de tipos no distinguen mayúsculas de minúsculas.
• Los tipos proporcionados para la codificación protocol-buffer deben coincidir con los tipos de mensajes definidos en los archivos de definición de protocol-buffer proporcionados. Los tipos no distinguen mayúsculas de minúsculas. Si no se especifica ningún tipo, el valor predeterminado de los datos de las columnas que se muestran es el nombre predeterminado de la columna.
• Los valores de formato de YAML no distinguen mayúsculas de minúsculas.