はじめに
Meltanoのプロジェクトのプラグインは、meltano.ymlプロジェクトファイルで定義され、.meltanoディレクトリ内にインストールされます。これらは、さまざまなCLIコマンドやUIを使用して管理することができます。
プラグインの追加
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コマンドを実行します。
.
.
.
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セクションを次のように変更します。
- plugins:
- loaders:
- - name: target-postgres
- variant: datamill-co
- pip_url: singer-target-postgres
+ 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ファイルを次のように修正します。
- config:
- postgres_host: postgres.example.com
- postgres_port: 5432
- postgres_username: my_user
- postgres_database: my_database
+ 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
discovery.ymlファイル
Meltanoはデフォルトでhttps://discovery.meltano.com/discovery.ymlのdiscovery.ymlファイルを参照してプラグインを追加しています。このdiscovery.ymlファイルに存在しないプラグインを作成したい場合は通常、--customオプションを追加してaddコマンドを実行してコンフィグをインタラクティブに入力します。discovery.ymlファイルを自作してexport MELTANO_DISCOVERY_URL=<YOUR discovery.yml PATH>を実行するとインタラクティブなコンフィグ設定を回避することができます。
参考
Ryusei Kakujo
Focusing on data science for mobility
Bench Press 100kg!