cbt CLI からの出力形式

このドキュメントでは、cbt CLI で表示されるときに Bigtable 行に格納された、特定のデータ型をフォーマットする方法について説明します。

フォーマットの例

バージョン 0.12.0 以降では、cbt CLI を使用して、テーブル行に格納されたデータの特定の複合型をフォーマットできます。cbt read コマンドまたは cbt lookup コマンドを使用すると、cbt CLI は行に格納されている値を「プリティプリント」できます。

次の例は、フォーマットしていない cbt CLI からのデータ出力を示しています。

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

次の例は、フォーマットした cbt CLI からのデータ出力を示しています。

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"

フォーマットされた行を出力する

列または列ファミリーをフォーマットするには、その列の形式を指定する YAML ファイルを指定する必要があります。cbt lookup または cbt read を呼び出すときに、YAML ファイルのパスを format-file 引数で渡します。次のスニペットは、format-file 引数を指定して cbt lookup を呼び出しています。

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

YAML で列データ形式を定義する

フォーマット YAML ファイルでは、列名または列ファミリー名をそこに格納されているデータ型に関連付ける必要があります。次のスニペットは、YAML フォーマットファイルの例を示しています。

protocol_buffer_definitions:
  - cat.proto
protocol_buffer_paths:
  - testdata/

columns:
  col1:
    encoding: ProtocolBuffer
    type: Cat

  col2:
    encoding: json

次のスニペットは、「cat.proto」の内容を示しています。

syntax = "proto3";
package cats;

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

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

例を見てみましょう。

protocol_buffer_definitions フィールドには、protobuf データのデコードに使用するプロトコルバッファメッセージタイプが含まれる .proto ファイルのリストを指定します。
protocol_buffer_paths フィールドには、プロトコルバッファタイプをデコードするための .proto ファイルが含まれるローカルパスのリストを指定します。標準プロトコルバッファのインポート先（google/protobuf パッケージ内のメッセージなど）を指定する必要はありません。
columns フィールドには、列のリストと各列の対応するデータ型が指定します。
- protobuf 列の encoding が「ProtocolBuffer」に、type が「Cat」に設定されています。cbt CLI は、この列に格納されているすべての値を Cat proto メッセージ型として解釈し、フォーマットします。型は、protocol_buffer_definition フィールドに指定された .proto ファイルのいずれかで定義されたメッセージ型に対応している必要があります。
- json 列の encoding フィールドが「json」に設定されています。cbt は、この列に格納されているすべての値を JSON 構造として解釈し、フォーマットします。

他に指定できるフィールドは次のとおりです。

default_encoding: このフィールドには、テーブル内のすべての列または列ファミリー内のすべての列にデフォルトの書式を定義します。
default_type: このフィールドには、プロトコルバッファ、ビッグエンディアン、リトルエンディアンでエンコードされた列のデフォルトのデータ型を定義します。
families: このフィールドには、列ファミリー内のすべての列のエンコードと型を定義します。列ファミリーには default_encoding と default_type を指定できます。次のスニペットに示すように、名前で列をリストする columns フィールドに適切なエンコードとデータ型を指定して、これらのエンコードを列レベルでオーバーライドすることもできます。
```
families:
  family1:
    default_encoding: BigEndian
    default_type: INT64
    columns:
      address:
        encoding: PROTO
        type: tutorial.Person
```

サポートされるデータ型

cbt CLI は、いくつかの複合データ型の形式をサポートしています。次の表に、各リスト型の YAML ファイルに指定できる、サポートされているデータ型と文字列を示します。文字列値の大文字と小文字は区別されません。

データ型	YAML のフォーマット値
16 進数	`Hex`、`H`
ビッグエンディアン	`BigEndian`、`B`
リトルエンディアン	`LittleEndian`、`L`
プロトコルバッファ	`ProtocolBuffer`、`P`、`PROTO`
JSON	`JSON`、`J`

表 1.cbt 出力のフォーマットでサポートされているデータ型。

16 進数エンコードは型に依存しません。データは、格納されたデータの未加工の 16 進数表現として表示されます。
ビッグエンディアンとリトルエンディアンのエンコードで使用可能な型は、int8、int16、int32、int64、uint8、uint16、uint32、uint64、float32、float64 です。格納されたデータの長さはバイト単位で、サイズが設定された型の倍数でなければなりません。格納されている長さが型のサイズと一致する場合はデータがスカラーとして、それ以外の場合は配列として表示されます。型名では大文字と小文字が区別されません。
protocol-buffer エンコードに指定された型は、提供されたプロトコルバッファ定義ファイルで定義されたメッセージ型と一致している必要があります。大文字と小文字は区別されません。型が指定されていない場合、表示される列データの列名がデフォルトの値になります。
YAML のフォーマット値では大文字と小文字は区別されません。