Format output from the cbt CLI

This document describes how to format specific types of data stored inBigtable rows when displayed by thecbt CLI.

Examples of formatting

Starting with version 0.12.0, thecbt CLI can formatcertain complex types of data stored in table rows.When you use thecbt read orcbt lookup command, thecbt CLI can"pretty print" values stored in the rows.

The following example shows data output from thecbt CLI withoutformatting.

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

The following example shows data output from thecbt CLI withformatting.

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"

Print rows with formatting

To format a column or column family, you must provide a YAML file thatspecifies the formatting for that column. When you callcbt lookup orcbt read, you pass in the path to the YAML file with theformat-fileargument. The following snippet shows an example of callingcbt lookup withtheformat-file argument supplied.

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

Define column data formats in YAML

The formatting YAML file must connect the column names or column family nameswith the data types stored within them. The following snippet shows an exampleof a YAML formatting file.

protocol_buffer_definitions:-cat.protoprotocol_buffer_paths:-testdata/columns:col1:encoding:ProtocolBuffertype:Catcol2:encoding:json

The following snippet shows the contents of 'cat.proto'.

syntax="proto3";packagecats;optiongo_package="github.com/protocolbuffers/protobuf/examples/go/tutorialpb";messageCat{stringname=1;int32age=2;}

Looking at the example:

• Theprotocol_buffer_definitions field provides a listof .proto files that can contain protocol buffer message types to use fordecoding protobuf data.
• Theprotocol_buffer_paths field provides a list of local paths thatcan contain .proto files for decoding protocol buffer types.You do not need to specify the locations of standard protocol bufferimports, such as messages in thegoogle/protobuf package.

• Thecolumns field contains a list of column names with the correspondingdata types for each column:

  • Theprotobuf column has itsencoding set to "ProtocolBuffer" and itstype is set to 'Cat'. Thecbt CLI interprets and formats all values storedin this column as aCat proto message type. The type must correspond toa message type defined in one of the .proto files provided for theprotocol_buffer_definition field.
  • Thejson column has itsencoding field set to "json". Thecbtinterprets and formats all values stored in this column as a JSONstructure.

Other fields that you can provide:

• default_encoding: This field defines a default formatting for allall columns in a table or all columns in a column family.
• default_type: This field defines a default data type for protocol buffer,big-endian, and little-endian encoded columns.

• families: This field defines encodings and types for all columns withina column family. You can provide adefault_encoding anddefault_typefor a column family. You can also override these encodings at the columnlevel by providing acolumns field that lists columns by name with theappropriate encoding and data types, as shown in the following snippet:

  families:family1:default_encoding:BigEndiandefault_type:INT64columns:address:encoding:PROTOtype:tutorial.Person

Supported data types

Thecbt CLI supports formatting for several complex data types. The followingtable lists the supported data types and strings to provide in the YAML filefor each of the list types. String values are not case-sensitive.

Table 1. Data types supported for formatting incbt output.

• The hexadecimal encoding is type agnostic. Data are displayed as a rawhexadecimal representation of the stored data.
• The available types for the big-endian and little-endian encodings areint8,int16,int32,int64,uint8,uint16,uint32,uint64,float32, andfloat64. Stored data length must be a multiple of the type sized, in bytes. Data are displayed as scalars if the storedlength matches the type size, or as arrays otherwise. Types names are notcase-sensitive.
• The types given for theprotocol-buffer encodingmust match message types defined in providedprotocol-buffer definition files. The types are not case-sensitive.If no type is specified, itdefaults to the column name for the column data being displayed.
• The formatting values for YAML are not case-sensitive.