本エントリでは、tblsでBigQueryのデータセットのドキュメントを生成するところまでを紹介します。
"既にGCPでプロジェクトとデータセットは作成済み" というところから説明したいと思います。
ただ、今回はGCPが公開しているプロジェクト bigquery-public-data と、そのデータセットの1つ census_bureau_international を利用しますので、必ずしもデータセットを用意する必要はありません。
1. サービスアカウントの作成とキーファイルのダウンロード
tblsでBigQueryのデータセットにアクセスするときは、設定ファイル tbls.yml で、以下のようにDSNを指定します。
# tbls.yml
dsn: bq://bigquery-public-data/census_bureau_international?creds=/path/to/google_application_credentials.json
まず上記の ?creds=/path/to/google_application_credentials.json のクレデンシャルファイル google_application_credentials.json を作成します。
まず、コンソールの「IAMと管理 > サービスアカウント」で「サービスアカウントを作成」をクリックします
サービスアカウントの詳細を入力します
サービスアカウントの権限は「BigQueryメタデータ閲覧者」で良いです。
（ちなみに、詳しい人用に必要なPermissionを挙げると bigquery.datasets.get bigquery.tables.get bigquery.tables.list の3つです）
「キーを作成」をクリックします。
キーのタイプは「JSON」です。
で、ダウンロードされたJSONを、今回は
「 google_application_credentials.json にファイル名を変更して /path/to/google_application_credentials.json に置いた」
ということにしましょう。
2. tblsのインストール
MacユーザはHomebrewでインストールするのがいいでしょう。
$ brew install k1LoW/tap/tbls
その他のOSを使っている方は、tblsのREADME#installを見て適切なインストール方法を選択してください。
3. tbls.yml の作成
任意のディレクトリでtbls.ymlファイルを作成します。
# tbls.yml
dsn: bq://bigquery-public-data/census_bureau_international?creds=/path/to/google_application_credentials.json
4. ドキュメントの作成
ドキュメントを作成します。tbls.ymlがあるディレクトリで以下のコマンドを実行してください。
$ tbls doc -f
dbdoc ディレクトリが作成されて、その中にMarkdown形式でドキュメントが生成されていると思います。
GitHubのリポジトリにコミットしてみると、ちょうどこんな感じです。
おまけ. Excelのテーブル定義書の出力
tbls.ymlがあるディレクトリで以下のコマンドを実行してください。
$ tbls out -t xlsx -o tbls.xlsx
出力されますね。
Columns や Name を日本語にしたい場合はtbls.ymlのdict: の設定を追加してみてください。
以上、tblsでのBigQueryのデータセットのドキュメント生成の紹介でした。