tblsでBigQueryのデータセットのドキュメントを生成する

本エントリでは、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のデータセットのドキュメント生成の紹介でした。