Meltanoのプラグインの使い方

Meltano のプラグインの使い方

この記事では、Meltano のプラグインの使い方について紹介します。

プラグインの追加

meltano addコマンドを実行するか、meltano.ymlファイルを直接編集してmeltano installコマンドを実行することにより、プラグインを追加することができます。

Discoverable plugins

meltano がサポートしている（meltano addで見つけることができる）extractor や loader は公式ドキュメントでは「Discoverable plugins」と表現されています。Discoverable plugins では、meltano addコマンドでプラグインを追加することができます。

$ meltano add extractor tap-gitlab
$ meltano add loader target-postgres
$ meltano add transformer dbt
$ meltano add orchestrator airflow

上記のコマンドを実行するとmeltano.ymlファイルのpluginセクションが以下のようになります。

plugins:
  extractors:
  - name: tap-gitlab
    variant: meltano
    pip_url: git+https://gitlab.com/meltano/tap-gitlab.git
  loaders:
  - name: target-postgres
    variant: datamill-co
    pip_url: singer-target-postgres
  transformer:
  - name: dbt
    pip_url: dbt
  orchestrators:
  - name: airflow
    pip_url: apache-airflow

同じ extractor や loader でもいくつか種類がある場合があり、その種類を公式ドキュメントでは「variant」と表現されています。variant を指定せずにmeltano addを実行すると meltano が推奨する variant が自動的に選択されます。

variant を指定する場合は以下のようにコマンドを実行します。

$ meltano add loader target-postgres --variant=transferwise

複数の variant をインストールしたい場合は、以下のようなコマンドを実行します。

$ meltano add loader target-snowflake --variant=transferwise --as target-snowflake--transferwise
$ meltano add loader target-snowflake --variant=meltano --as target-snowflake--meltano

カスタムプラグイン

Discoverable plugins に所望のプラグインが存在しない場合は、meltano addコマンドに--customオプションを追加することで任意の Singer tap や Singer target を追加することができます。公式ドキュメントに従い、Discoverable plugins に存在しない extractor を追加します。

$ meltano add --custom extractor tap-covid-19

上記コマンドを実行するとインタラクティブな質問に回答していきます。

Adding new custom extractor with name 'tap-covid-19'...

Specify the plugin's namespace, which will serve as the:
- identifier to find related/compatible plugins
- default database schema (`load_schema` extra),
  for use by loaders that support a target schema

Hit Return to accept the default: plugin name with underscores instead of dashes

(namespace) [tap_covid_19]: tap_covid_19

Specify the plugin's `pip install` argument, for example:
- PyPI package name:
	tap-covid-19
- Git repository URL:
	git+https://gitlab.com/meltano/tap-covid-19.git
- local directory, in editable/development mode:
	-e extract/tap-covid-19
- 'n' if using a local executable (nothing to install)

Default: plugin name as PyPI package name

(pip_url) [tap-covid-19]: -e extract/tap-covid-19

Specify the plugin's executable name

Default: name derived from `pip_url`

(executable) [tap-covid-19]: tap-covid-19

Specify the tap's supported Singer features (executable flags), for example:
	`catalog`: supports the `--catalog` flag
	`discover`: supports the `--discover` flag
	`properties`: supports the `--properties` flag
	`state`: supports the `--state` flag

To find out what features a tap supports, reference its documentation or try one
of the tricks under [how to test a tap](/contribute/plugins#how-to-test-a-tap).

Multiple capabilities can be separated using commas.

Default: no capabilities

(capabilities) [[]]: catalog,discover,state

Specify the tap's supported settings (`config.json` keys)

Multiple setting names (keys) can be separated using commas.

A setting kind can be specified alongside the name (key) by using the `:` delimiter,
e.g. `port:integer` to set the kind `integer` for the name `port`

Supported setting kinds:
string | integer | boolean | date_iso8601 | email | password | oauth | options | file | array | object | hidden

- Credentials and other sensitive setting types should use the password kind.
- If not specified, setting kind defaults to string.
- Nested properties can be represented using the `.` separator, e.g. `auth.username` for `{ "auth": { "username": value } }`.
- To find out what settings a tap supports, reference its documentation.

Default: no settings

(settings) [[]]: api_token:password,user_agent:string,start_date:date_iso8601
Added extractor 'tap-covid-19' to your Meltano project

Installing extractor 'tap-covid-19'...
Installed extractor 'tap-covid-19'

meltano.ymlファイルのpluginsセクションに tap-covid-19 extractor が追加されています。

plugins:
  extractors:
  - name: tap-covid-19
    namespace: tap_covid_19
    pip_url: tap-covid-19
    executable: tap-covid-19
    capabilities:
    - catalog
    - discover
    - state
    settings:
    - name: api_token
    - name: user_agent
    - name: start_date

プラグインの継承

Discoverable plugin を継承して、別名でインストールしたい場合はオプションに--inherit-fromもしくは--asを追加します。

$ meltano add extractor tap-postgres--billing --inherit-from tap-postgres

もしくは

$ meltano add extractor tap-postgres --as tap-postgres--billing

meltano.ymlファイルのpluginsセクションは以下のようになります。

plugins:
  extractors:
  - name: tap-postgres--billing
    inherit_from: tap-postgres
    variant: transferwise
    pip_url: pipelinewise-tap-postgres

特定のプラグインのバージョンを指定

特定のプラグインバージョンを利用したい場合は、以下のようにmeltano.ymlファイルのpip_urlを記述します。

# Before:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git
pip_url: git+https://github.com/adswerve/target-bigquery.git

# After:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git@v0.9.11
pip_url: git+https://github.com/adswerve/target-bigquery.git@v0.10.2

# Alternatively:
pip_url: git+https://gitlab.com/meltano/tap-gitlab.git@2657b89e8896face4ce320a03b8413bbc196cec9
pip_url: git+https://github.com/adswerve/target-bigquery.git@3df97b951b7eebdfa331a1ff570f1fe3487d632f

プラグインの削除

meltano removeコマンドにより、プラグインを削除することが可能です。

例

$ meltano remove extractor tap-github
$ meltano remove loader target-csv target-bigquery

カスタムフォークしたプラグインの利用

フォークしたプラグインのレポジトリを資料したい場合は、以下のようにmeltano.ymlファイルのpluginsセクションにあるpip_urlの値を修正し、meltano installコマンドを実行します。

meltano.yml

.
.
.
plugins:
   extractors:
   - name: tap-gitlab
     variant: meltano
     pip_url: git+https://github.com/meltano/tap-gitlab.git@ref-name #この行を修正する

$ meltano install extractor tap-github

プラグインのレポジトリがプライベートである場合は、以下の２通りの手段で対応します。

.netrcファイルをホームディレクトリに配置する

machine <hostname> # e.g. gitlab.com or github.com
  login <username>
  password <personal-access-token-or-password>

SSH で認証する

pip_url: git+ssh://git@gitlab.com/meltano/tap-gitlab.git

variant の変更

既存の variant が存在し、別の variant に切り替えたい場合は、新しい variant を追加するか、既存の variant を上書きします。

ここでは、既存の variant を上書きする方法を行います。meltano.ymlファイルのpluginsセクションを以下のように変更します。

# Before
plugins:
  loaders:
  - name: target-postgres
    variant: datamill-co
    pip_url: singer-target-postgres

# After
plugins:
  loaders:
  - name: target-postgres
    variant: meltano
    pip_url: git+https://github.com/meltano/target-postgres.git # Optional

次に、meltano installコマンドを実行します。

$ meltano install loader target-postgres

variant が異なるとコンフィグの値も異なることが多いです。meltano.ymlファイルを以下のように修正します。

# Before
config:
  postgres_host: postgres.example.com
  postgres_port: 5432
  postgres_username: my_user
  postgres_database: my_database

# After
config:
  host: postgres.example.com
  port: 5432
  user: my_user
  dbname: my_database

古いコンフィグ値がある場合は以下のコマンドで新しい値をセットすることができます。

meltano config target-postgres unset postgres_password
meltano config target-postgres set password my_password

参考

Meltano 公式ドキュメント

備考

Hakky ではエンジニアを募集中です！まずは話してみたいなどでも構いませんので、ぜひお気軽に採用ページからお問い合わせくださいませ。