Plugin on @johtaniの日記 3rd

Analyze UIとKibanaのプラグインの作成方法（第3回）

Fri, 20 Apr 2018 15:30:01 +0900

第2回から少し間が空いてしまいましたが、templateで作成したプラグインのディレクトリ構成とどういう流れでデータがやり取りされるかについてみていきます。（2018/02月時点で作成したディレクトリ構成にしたがって説明します）ちなみに、JavaScriptの優れた開発者ではないので、誤解している点や、効率の悪い書き方などがあるかもしれません。見つけた場合は、連絡をいただければと思います。

では、まずは作成したディレクトリ構成についてみていきましょう。

ディレクトリ構成

simple-sample-kibana-pluginがプラグインのプロジェクトのトップディレクトリになります。このディレクトリに次のような構成でサブディレクトリが存在します(なお、画像はIntelliJに取り込んだ後のディレクトリになっているので、.imlなど、不要なファイル/ディレクトリが存在しています)。

主要なディレクトリ、ファイルについて簡単に一覧で説明します(順不同)。

ファイル/ディレクトリ名	説明
index.js	プラグインの本体。Kibanaはこのファイルのオブジェクトを読み込みプラグインを起動。設定などの読み込みもこちら。
package.json	npm/yarnのパッケージに関する情報を定義するファイル
README.md	README。プラグインの説明などを記載する。インストール方法なども記載すると便利
public	ブラウザ側に配布されるプログラムや画像一式
public/less/main.less	LESS用のファイル。アプリ固有のスタイルなどを記載
public/app.js	ブラウザ側で読み込まれるプラグインのモジュールなど。
public/template/index.html	HTMLのテンプレート。ブラウザ上での描画に利用
server/routes	Kibanaサーバー側で動作するプラグイン。hapi.jsを利用してREST APIを実装する

重要なファイルについて少しだけ説明します。

package.json

npmやyarnでビルドなどをするときに使用するパッケージ情報を記載するためのファイルです。プラグインの名前、バージョン、説明などを記載します。 Kibanaのバージョンについてもこちらで管理します。この情報をまた、ライブラリなどの依存関係についてもこちらで記載しています。以下、抜粋。

{
  "name": "simple-sample-kibana-plugin",
  "version": "0.0.0",
  "description": "Sample plugin for explaining how to make kibana app",
  "main": "index.js",
  "kibana": {
    "version": "6.2.1",
    "templateVersion": "7.2.4"
  },
  "scripts": {
    "lint": "eslint **/*.js",
...
  },
  "devDependencies": {
    "@elastic/eslint-config-kibana": "^0.14.0",
    "@elastic/eslint-import-resolver-kibana": "^0.9.0",
    "@elastic/plugin-helpers": "^7.1.3",
...
    "expect.js": "^0.3.1"
  }
}

ちなみに私は、versionなどをリリースするたびに変更しています。

index.js

最初にKibanaに読み込まれるオブジェクトになります。 Kibanaのアプリの名前や、必要なモジュールなどを記載します。

また、kibana.ymlから設定など読み込む処理なども書くことができます。

2行目のexampleRouteはサーバー側のAPIとして利用するhapi.js用のファイルのパスになります。

uiExportsはこのアプリの画面に関する設定などの記載になります。 appの部分が実際にアプリの情報で、 mainがあとで説明するこのプラグインのUIのためのJavaScriptファイル(public/app.js)になります。mainですので、最初に読み込まれる処理が記載されているものを指定します。app.jsというファイル名を変更する場合は、こちらのappの部分を変更したファイルに合わせましょう。

config(Joi)の関数が設定ファイルの読み込みなどの処理を記載する場所です。

init(server, options)の関数が初期化処理を記載する場所になります。このサンプルアプリでは、2行目のimportで読み込んだhapi.js用のファイルの関数を呼び出しています。引数で渡しているserverがhapi.jsのserverオブジェクトになります。 routeメソッドを使用して作成しているプラグイン用のREST APIを追加しています。

import { resolve } from 'path';
import exampleRoute from './server/routes/example';

export default function (kibana) {
  return new kibana.Plugin({
    require: ['elasticsearch'],
    name: 'simple-sample-kibana-plugin',
    uiExports: {

      app: {
        title: 'Simple Sample Kibana Plugin',
        description: 'Sample plugin for explaining how to make kibana app',
        main: 'plugins/simple-sample-kibana-plugin/app'
      },

...
    },

    config(Joi) {
      return Joi.object({
        enabled: Joi.boolean().default(true),
      }).default();
    },

    init(server, options) {
      // Add server routes and initialize the plugin here
      exampleRoute(server);
    }
  });
};

public/app.js

画面用のモジュールです。 uiRoutesという機能を使用して、アプリの呼び出しURLを定義します。テンプレートで作成したばかりの場合は、/というURLが追加されるのみです。

実際に画面を表示する際に動くコントローラーの部分はその下の uiModules.controllerに指定してあるfunctionが画面描画の処理を書く部分になります。 templateで作成したプラグインでは、“title"など表示に必要なデータを$scopeというオブジェクトに詰め込んでいます。これはAngularJS(1系)でのモデルオブジェクトになります。

import moment from 'moment';
import { uiModules } from 'ui/modules';
import uiRoutes from 'ui/routes';

import 'ui/autoload/styles';
import './less/main.less';
import template from './templates/index.html';

uiRoutes.enable();
uiRoutes
  .when('/', {
    template,
    resolve: {
...
    }
  });

uiModules
  .get('app/simple-sample-kibana-plugin', [])
  .controller('simpleSampleKibanaPluginHelloWorld', function ($scope, $route, $interval) {
    $scope.title = 'Simple Sample Kibana Plugin';
    $scope.description = 'Sample plugin for explaining how to make kibana app';
...
    $scope.$watch('$destroy', unsubscribe);
  });

server/routes/example.js

hapi.jsというNode.jsのためのサーバーフレームワークです。このフレームワークをKibanaは使っており、Kibanaのサーバーとブラウザとのやり取りに使用するREST APIを記述するために使用しています。例えば、Elasticsearchとのやり取りを実際に行うAPIなどをこのREST API内部で記述します。

export default function (server) {

  server.route({
    path: '/api/simple-sample-kibana-plugin/example',
    method: 'GET',
    handler(req, reply) {
      reply({ time: (new Date()).toISOString() });
    }
  });

}

pathの部分がブラウザ側からアクセスするURLになります。実際にElasticsearchとやり取りする処理の書き方については、次回の記事で説明します。

アーキテクチャ（簡易版）

ざっくりですが、ファイルやディレクトリについて説明しました。簡単なデータのやり取りについての流れを説明します。

Kibana自体はNode.jsで実装されサーバーとして動作していますが、ブラウザでアクセスすることで画面を描画しています。簡単なコンポーネントを並べるとデータのやり取りはこのような形です。

すごく簡易で大雑把な絵ですが。。。

実際のプラグインとしては大きく、2つの処理があります。

ブラウザ上の処理
- クリックなどのイベント処理
- HTMLなどのレンダリング処理
Kibanaサーバー上の処理(Elasticsearchなどとの通信が必要な場合)
- 外部との通信処理
- ブラウザ上では重い処理

絵に記載しましたが、ブラウザ上の処理についてはAngularJSが主なフレームワークで、サーバー上の処理についてはhapi.jsがフレームワークとなっています。

まとめ

ということで、今回はディレクトリ構造とファイルの説明、どういったフレームワークが使われ、データのやり取りがどのように行われているか説明しました。

次回からは、実際に私が作成したAnalyze UIを元にElasticsearchとのデータのやり取りなどについて紹介していきます。

Analyze UIとKibanaのプラグインの作成方法（第2回）

Fri, 09 Feb 2018 18:17:37 +0900

第1回では、Analyze UIというプラグインの紹介をしました、ごく簡単にですが。

第2回では、Kibanaのプラグインの作成方法を順を追って見ていこうと思います。今回は、プラグインのプロジェクトの作り方を説明します。どんなファイルがあるのかなどについては第3回で説明します（2018/02月現在の方法になります。残念ながら、Kibanaのプラグイン作成自体はまだExperimentalな話になっていますので、変更がある可能性があります）。

実はそれほど難しいというわけではありません。Kibanaのプラグインを作成するためのテンプレートが用意されています。template-kiban-pluginです。テンプレートのリポジトリのREADMEに作業手順の記載があります。

KibanaのリポジトリをClone、Checkout
Node.jsの環境を用意する
Kibanaを起動できるようにする
SAOのインストール
テンプレートによるプロジェクトファイルの生成

順を追って説明します。 PLUGIN_DEV_DIRというディレクトリ配下で作業をしている想定になります。

1. KibanaのリポジトリをClone、Checkout

開発環境として、Kibanaが必要です。Kibanaのプラグインを作るので。手順などはKibanaのCONTRIBUTING.mdに記載があります。ということで、まずはKibanaのリポジトリをCloneします。

cd PLUGIN_DEV_DIR
git clone git@github.com:elastic/kibana.git

このままだと、masterブランチなので、開発したい対象のKibanaのバージョンのブランチもしくはタグをcloneします。今回は6.2.1向けということで、次のようになります。

git checkout v6.2.1

これで、ソースが6.2.1向けになりました。

2. Node.jsの環境を用意する

Node.jsをインストールします。 Kibanaのリポジトリに.node-versionというファイルがあります。こちらにNode.jsのバージョンが記載されています。 Kibanaが使用しているNode.jsを利用できるようにします。ローカルではnvm利用してインストールしました。後から、切り替えが可能だからです。 nvm自体のインストールについてはnvmのサイトをご覧ください。 nvmがインストールできたら、次のコマンドで、Kibanaが使用しているバージョンをインストールします。

cd kibana
nvm install "$(cat .node-version)"

すでにnvmを利用している場合などは、Kibana起動時にKibanaのバージョンに合わせたNode.jsに切り替えるようにしてください。

3. Kibanaを起動できるようにする

Kibanaではyarnというjavascript向けのパッケージマネージャーを利用して起動やビルドなどを行います。まずはyarnをインストールします。最近npmからyarnに切り替えたようです。私はMacだったので、brewでインストールしました。インストールできたら、次のコマンドを実行します。

yarn

これにより、package.jsonから必要なライブラリなどをダウンロードして来てくれます。問題なければ「✨ Done in 439.30s.」というような表示がされます（結構時間かかりますね）。では、Kibanaを起動できるか確認してみましょう。さらに、Elasticsearchも起動してみます。 Kibanaのpackage.jsonの中にはElasticsearchを起動するためのスクリプトも用意されています。実際にはgruntを利用してタスクを実行しているようです。Elasticsearchの起動にはJavaが必要になります。今回は6.2.1なので、JDK 8以降がインストールされている必要があります。こちらはインストールされているものとします。

yarn elasticsearch

で起動できます。

>> Started 1 Elasticsearch nodes.

という表示が出てればOKです。次にKibanaです。別のTerminalを起動して、以下のコマンドで起動できます。

yarn start

これだけです。

server    log   [06:58:56.930] [info][listening] Server running at http://localhost:5603

この辺りが出てればKibanaのServerは起動済みです。また、Elasticsearchに接続できていれば、次のログが出ているはずです。

server    log   [07:02:18.010] [info][status][plugin:elasticsearch@6.2.1] Status changed from red to green - Ready

Elasticsearch接続用のKibanaのプラグインの状態になります。これで、Kibanaの環境が整ったことが確認できました。もちろん、Elasticsearchに関しては、yarnで起動せずに、tar.gzなどでダウンロードして来たElasticsearchを起動しておき、アクセスするといったことも可能です。プラグインなどをElasticsearchにもいれてテストしたい場合などはそちらの方が便利かもしれません。

4. SAOのインストール

では、一度、ElasticsearchとKibanaを停止しましょう。フォワグラウンドで起動しているので、それぞれのTerminalでCtrl+Cで停止できます。 Kibanaのプラグイン作成むけに、テンプレートが作られています。sao.jsというGitHubのリポジトリやnpmのパッケージをテンプレートとして使うことができるツールを利用してプラグインのプロジェクト（リポジトリ）を作成します。実際にテンプレートとなるリポジトリはtemplate-kibana-pluginになります。まずはSaoのインストールです。

npm install -g sao

プラグインのテンプレートのページには上記のようにnpmを利用したインストール方法になっていますが、次のようにyarnでも可能です。

yarn global add sao

これで、saoがインストールできました。

5. テンプレートによるプロジェクトファイルの生成

あとは、テンプレートを元にプロジェクトを作成します。 PLUGIN_DEV_DIRディレクトリ配下に、kibanaと同じ階層で作成するプラグイン用のディレクトリを作成します。

mkdir simple-sample-kibana-plugin

以下のような構成になります。

kibana                      simple-sample-kibana-plugin

次にテンプレートを適用していきます。

cd simple-sample-kibana-plugin
sao kibana-plugin@7.2.4

2行目がsaoを利用してプロジェクトを作成しているコマンドになります。すると、次のような質問が出て来ます。これらに答えるとプロジェクトに必要なファイル（package.jsonやREADME.mdなど）に入力した情報を適用したものを作ってくれます。

? Name of your plugin?
? Provide a short description
? What Kibana version are you targeting?
? Should an app component be generated?
? Should translation files be generated?
? Should an hack component be generated?
? Should a server API be generated?

実際に答えた内容はこちら。

? Name of your plugin? simple-sample-kibana-plugin
? Provide a short description Sample plugin for explaining how to make kibana app
? What Kibana version are you targeting? 6.2.1
? Should an app component be generated? Yes
? Should translation files be generated? Yes
? Should an hack component be generated? Yes
? Should a server API be generated? Yes

プラグインの名前などは、ディレクトリ名と同じものを入力補完してくれているので、そのままEnterでもOKです。 Descriptionについてはわかりやすいものを入力しましょう。バージョンは、先ほどのKibanaのリポジトリに合わせて、6.2.1にしてあります。あとは、作るプラグインの種類に応じて、必要なコンポーネントを作るかどうかの質問にYes/Noで答えます。今回はサンプルの説明ということもあるので、全てYesで答えました。ちなみに、私が実際に作成したanalyze-api-ui-pluginでは、appとtranslationとserverの3つを作成しました。ただし、translationについては現在はテンプレートで作成したままのファイルが入っており、実際には利用してないです。

完了したら、プラグインのサンプル入りのプロジェクトが完成です。もう一度、Elasticsearchを立ち上げて、プラグインのプロジェクトからKibanaを起動してアクセスしてみます。まずは、PLUGIN_DEV_DIR/kibanaディレクトリの下で、Elasticsearchを起動します。

yarn elasticsearch

次に、PLUGIN_DEV_DIR/simple-sample-kibana-pluginディレクトリの下で、以下のコマンドを実行し、プラグインが入った状態のKibanaを起動します。

yarn start

問題なく起動すれば、ブラウザでアクセスすると次のような画面が表示されるはずです。

左側にメニューが1つ増えています。クリックすると、上記画像のような画面が表示されるはずです。

これで、カスタムプラグインの開発ができる環境ができました！次回は、プロジェクトのディレクトリ構成や、どんなツールが内部で使用されてデータのやり取りが行われているかについて説明します。お楽しみに。

Analyze UIとKibanaのプラグインの作成方法（第1回）

Fri, 19 Jan 2018 15:36:46 +0900

あけましておめでとうございます。今年はサボりがちだったブログをちょっとずつ復活させようかと。ということで、第1弾として、昨年少し作っていたKibanaのプラグインを何度かに分けて紹介したいと思います。

今回はAnalyze UIというプラグインの紹介です。

今回はインストール方法と簡単な機能紹介です。細かな紹介は個別にやりたいと思います。

Analyze UI pluginとは？

Elasticsearchの_analyzeというAPI(個人的に好きなAPIです)をご存知でしょうか？

Elasticsearchは全文検索エンジンで、データの検索には転置インデックスというものを使用します。 Elasticsearchにデータを登録する際に、text型のデータの場合、この転置インデックスのキーとなる単語を決める処理のことをAnalysisと呼びます（Analysisの詳細については割愛します。後日説明するかも？）。このAnalysisの処理が、入力されたデータの文字列に対してどのように行われて、結果としてどんな単語がキーとして用いられているかを確認できる機能が_analyze APIです。検索で単語がうまくヒットしないな？とか、なんで、こんなので検索結果に出てくるんだ？といった場合、このAPIを利用すると、どのような単語で転置インデックスが作られているかがわかるので、検索にヒットしない/する理由を見つけることができます。

Elasticsearchの便利な点はRESTfulなAPI＋JSONでやりとりができる点なのですが、_analyze APIの結果をJSONで受け取っても、見るのにちょっと苦労します。。。こんな感じ。

リクエスト：

POST _analyze
{
  "analyzer": "kuromoji",
  "text": "今年はブログをいっぱい書きますよ！"
}

レスポンス：

{
  "tokens": [
    {
      "token": "今年",
      "start_offset": 0,
      "end_offset": 2,
      "type": "word",
      "position": 0
    },
    {
      "token": "ブログ",
      "start_offset": 3,
      "end_offset": 6,
      "type": "word",
      "position": 2
    },
    {
      "token": "いっぱい",
      "start_offset": 7,
      "end_offset": 11,
      "type": "word",
      "position": 4
    },
    {
      "token": "書く",
      "start_offset": 11,
      "end_offset": 13,
      "type": "word",
      "position": 5
    }
  ]
}

このくらいの量であればまだなんとかなりますが、文章が長くなると辛いですよね。

ということで、GUIがあると便利だろうなぁと。で、作ってみましたというのが今日紹介するKibana用のAnalyze UIプラグインです。こんな感じで、Kibanaのアプリの一部として動作しブラウザ上で、入力テキストの文字列がどのようにanalyzeされて、単語になるかがわかります。

（先ほどのAPIのサンプルと同じものを画面で入力した結果になります）。

インストール方法

現時点の最新版Kibana（6.1.2）に対応しています。 Kibanaのディレクトリでkibana-pluginコマンドを利用してインストールします。

./bin/kibana-plugin install https://github.com/johtani/analyze-api-ui-plugin/releases/download/6.1.2/analyze-api-ui-plugin-6.1.2.zip

これだけです。で、Kibanaを起動していただくと、左のメニューに「Analyze UI」という項目が増えています。

クリックすると、Analyze UIが表示されます。

初期画面は入力された文字を特定のAnalyzerで処理した場合の結果を見るための画面です。綱目の説明は画像をご覧ください。

先ほどのJSONよりは見やすくなったかと思います。そのほかにもいくつか画面や機能があるのですが、今日はこの辺りで。「_analyze API便利なんだけど、JSONは。。。」とか「検索うまくできないなぁなんでだろう？」と思っている方は、ぜひ試して見ていただければと。問題点などありましたら、GitHubのIssueを登録してください。

Lucene Kuromoji for NEologdで指定した品詞の単語を抜き出すIngest Pluginを書いてみた #elasticsearchjp

Fri, 22 Jul 2016 13:26:56 +0900

久しぶりに、技術的なブログ書いてます。

Ingest Processorのプラグインを作ってみたくなったので、書いてみました。ただ書いてみるんじゃ3番煎じになりそうなので、cookiecutterを使ってみました。

と言っても、同僚のAlexがcookiecutter-elasticsearch-ingest-processorと言うテンプレートを作ってくれているのを使っただけですが。（https://discuss.elastic.co に投稿された記事で、使い方がアニメgifで説明されててわかりやすいです）

cookiecutterとは、コマンドラインで質問に答えると、テンプレートからプロジェクトが生成できるツールです。 Elasticでは、カスタムBeatを作る時に利用する例がいつかの日本語ブログや発表資料で話題になっていました。これのIngest Processorのプラグインバージョンです。

今回は、NEologdも使ってみたかったので、Lucene Kuromoji for NEologdを利用して指定した品詞の単語だけを抽出するProcessorを作ってみました。

GitHubのプロジェクト：https://github.com/johtani/elasticsearch-ingest-kuromoji-pos-extract

Cookiecutterの使い方

Cookiecutterのインストールはサイトをご覧ください。

cookiecutter gh:spinscale/cookiecutter-elasticsearch-ingest-processor

あとは、出てくる以下の項目を指定するだけです。

processor_type : Ingest Processorのタイプ名です。kuromoji_part_of_speech_extractとしました。（Alexのだと_を使うとちょっと問題があるので後述）
description : readme.mdに利用されます。
developer_name : 名前を記載。Javaのファイルのヘッダに利用
elasticsearch_version : デフォルトで5.0.0-alpha4が指定されているので、特に指定せず

以上の質問に答えたら、プロジェクトのディレクトリ構造が出来上がってます。プロジェクトのビルドなどにはGradleを利用します。

プロジェクトのIntelliJ IDEA用のファイルを生成

build.gradleファイルでGradleのideaプラグインがapplyされているので、以下のコマンドを叩けばIntelliJ IDEAのプロジェクトファイル（？）が生成され、IntelliJで開けばすぐに開発ができる状態にできます。

gradle idea

コーディング

あとは、必要処理をコーディングします。実際にコーディングするクラスはorg.elasticsearch.plugin.ingest.kuromoji_part_of_speech_extractのパッケージにある以下の2つです。（パッケージ名にはprocessor_typeの名前が指定されている）

IngestKuromojiPartOfSpeechExtractPlugin
KuromojiPartOfSpeechExtractProcessor

IngestKuromojiPartOfSpeechExtractPlugin

Pluginというクラスは、プラグインをNodeのModuleとして登録する処理を書くクラスとなります。生成してすぐは、次のような形になっています。（※importやクラス定義の部分は省略しています。）

...
    public static final Setting<String> YOUR_SETTING =
            new Setting<>("ingest.kuromoji_part_of_speech_extract.setting", "foo", (value) -> value, Setting.Property.NodeScope);

    @Override
    public List<Setting<?>> getSettings() {
        return Arrays.asList(YOUR_SETTING);
    }

    public void onModule(NodeModule nodeModule) throws IOException {
        nodeModule.registerProcessor(KuromojiPartOfSpeechExtractProcessor.TYPE,
                (registry) -> new KuromojiPartOfSpeechExtractProcessor.Factory());
    }
...

YOUR_SETTINGプロパティとgetSettings()メソッドはelasticsearch.ymlで指定したい設定を記述する場合の例になります。今回は特に必要ないので両方削除しました。最終系はGitHubのコードをご覧ください。

KuromojiPartOfSpeechExtractProcessor

Processorは実際にIngest Nodeで行う処理を書くところです。


    public static final String TYPE = "kuromoji_part_of_speech_extract";

    private final String field;
    private final String targetField;

    public KuromojiPartOfSpeechExtractProcessor(String tag, String field, String targetField) throws IOException {
        super(tag);
        this.field = field;
        this.targetField = targetField;
    }

    @Override
    public void execute(IngestDocument ingestDocument) throws Exception {
        String content = ingestDocument.getFieldValue(field, String.class);
        // TODO implement me!
        ingestDocument.setFieldValue(targetField, content);
    }

    @Override
    public String getType() {
        return TYPE;
    }

    public static final class Factory extends AbstractProcessorFactory<KuromojiPartOfSpeechExtractProcessor> {

        @Override
        public KuromojiPartOfSpeechExtractProcessor doCreate(String processorTag, Map<String, Object> config) throws Exception {
            String field = readStringProperty(TYPE, processorTag, config, "field");
            String targetField = readStringProperty(TYPE, processorTag, config, "target_field", "default_field_name");

            return new KuromojiPartOfSpeechExtractProcessor(processorTag, field, targetField);
        }
    }

TYPEがIngest APIのPipelineでProcessorを指定するときに使う名前になります。ここは、cookiecutterの時にprocessor_typeに入力した文字列になっています。 kuromoji_part_of_speech_extractだと長いので、kuromoji_pos_extractに変えました。

execute()メソッドに// TODO implement me!とあります。この部分に実際の処理を記述していきます。

あとは、FactoryクラスでIngest APIで指定された設定項目を読み込みます。今回作成したelasticsearch-ingest-kuromoji-pos-extractでは品詞を指定する必要があるので、pos_tagsを指定できるように処理を追加しました。

私が実装したものの説明をするとちょっと長くなりそうなので、GitHubのコードをご覧ください。

テストのコーディング

テストのクラスもテンプレートで生成されています。

KuromojiPartOfSpeechExtractProcessorTests
KuromojiPartOfSpeechExtractRestIT

KuromojiPartOfSpeechExtractProcessorTests

Processorクラスのテストになります。生成直後は次のような感じです。

public void testThatProcessorWorks() throws Exception {
    Map<String, Object> document = new HashMap<>();
    document.put("source_field", "fancy source field content");
    IngestDocument ingestDocument = RandomDocumentPicks.randomIngestDocument(random(), document);

    KuromojiPartOfSpeechExtractProcessor processor = new KuromojiPartOfSpeechExtractProcessor(randomAsciiOfLength(10), "source_field", "target_field");
    processor.execute(ingestDocument);
    Map<String, Object> data = ingestDocument.getSourceAndMetadata();

    assertThat(data, hasKey("target_field"));
    assertThat(data.get("target_field"), is("fancy source field content"));
    // TODO add fancy assertions here
}

テストメソッドも実装されていますが、パラメータの追加の設定処理やアサーションが書かれてません。実装に合わせて、アサーションや設定処理を追加しましょう。

KuromojiPartOfSpeechExtractRestIT

こちらはIntegration Testになります。実際にElasticsearchに対して外部からAPIを叩くような感じです。 APIを叩くときに利用するJSONの設定やアサーションはsrc/test/resourcesにyamlファイルがあります。

10_basic.yaml
20_kuromoji_part_of_speech_extract_processor.yaml

10_basic.yamlはプラグインがインストールされているかの確認のテストです。特に変更する必要はないです。

20_kuromoji_part_of_speech_extract_processor.yamlは実際にコーディングしたProcessorが動くかどうかのテストです。

テストの内容については、GitHubのコードをご覧ください。

テストの実行とZipの生成

テストの実行とZipの生成は次のコマンドを実行すればOKです。

gradle check

テストに問題があった場合は、コケますし、問題なければSUCCESSと表示が出ます。成功した場合はbuild/distributions/というディレクトリにzipファイルができています。これをElasticsearchのpluginコマンドでインストールすれば動きます。

bin/plugin install file:///path/to/elasticsearch-ingest-kuromoji-pos-extract/build/distribution/ingest-kuromoji_part_of_speech_extract-0.0.1-SNAPSHOT.zip

kuromoji_pos_extractの利用方法

Ingest APIには便利なSimulate Pipeline APIがあります。

ということで、mecab-ipadic-NEologdにあったサンプルの文章を使って、使い方の説明です。

POST _ingest/pipeline/_simulate
{
  "pipeline" : {
    "description" : "kuromoji neologd extract test",
    "processors" : [
      {
        "kuromoji_pos_extract" : {
        "field" : "body",
        "target_field" : "noun_field",
        "pos_tags" : [
          "名詞-固有名詞-組織",
          "名詞-固有名詞-一般",
          "名詞-固有名詞-人名-一般",
          "名詞-固有名詞-地域-一般",
          "名詞-固有名詞-地域-国"
          ]
        }
      }
      ]
  },
  "docs" : [
    {
      "_index": "index",
      "_type": "type",
      "_id": "id",
      "_source": {
        "body" : "10日放送の「中居正広のミになる図書館」（テレビ朝日系）で、SMAPの中居正広が、篠原信一の過去の勘違いを明かす一幕があった。"
      }
    }
    ]
}

結果はこちら。

{
  "docs": [
    {
      "doc": {
        "_index": "index",
        "_id": "id",
        "_type": "type",
        "_source": {
          "noun_field": [
            "10日",
            "中居正広のミになる図書館",
            "テレビ朝日",
            "SMAP",
            "中居正広",
            "篠原信一"
          ],
          "body": "10日放送の「中居正広のミになる図書館」（テレビ朝日系）で、SMAPの中居正広が、篠原信一の過去の勘違いを明かす一幕があった。"
        },
        "_ingest": {
          "timestamp": "2016-07-22T06:18:49.007+0000"
        }
      }
    }
  ]
}

noun_fieldに固有名詞の単語が抜き出せているのがわかるかと思います。

Alexのテンプレートで困った点

テンプレートは便利だったのですが、processor_typeに_を使用したタイプ名を指定すると次のような問題（？）が発生しました。

クラス名がKuromoji_part_of_speech_extractProcessorとなってしまう

深刻な問題ではないのですが、JavaだとCamel Caseが普通なのでちょっと気になって。ということで、プルリク作って出してみました。まだ取り込まれてないかな。

取り込み前に使いたい方は以下のコマンドを実行してください。 processor_class_nameという項目が増えています。デフォルトだとprocessor_typeの_の部分を取り除きつつCamel Caseにしたものが入ります。

cookiecutter gh:johtani/cookiecutter-elasticsearch-ingest-processor

まとめ

ということで、とりあえず作ってみましたというものになります。特徴的な単語（固有名詞だけ）を抜き出して、別のフィールドにできるので、タグみたいなものをこれを使って前処理で作れるようになるかなぁと。

参考ブログ（元ネタ？）

インスパイア元となったブログです。

Sonatypeのバージョン番号で困ったので

Wed, 15 Oct 2014 15:26:08 +0900

Elasticsearch 1.4.0.Beta1がリリースされました。

個人でelasticsearch-extended-analyzeというプラグインを開発してます。こちらも1.4.0.Beta1に対応するべく作業をしてて、少し戸惑ったことがあったので、メモをば。

ここ最近はプラグインのバージョン番号をElasticsearchのバージョン番号と同じものを利用していました。（プラグインの機能追加をサボってる？？）その時に、1.4.0.Beta1という番号を指定したのですが、意味不明なエラーに悩まされてしまいまして。

プラグインのリリースでは、以下のコマンドを実行します。

$ mvn release:prepare
$ mvn release:perform

最初のコマンド（prepare）で、パッケージングを実施し、Githubにリリースタグを打ったバージョンがpushされます。次のコマンド（perform）で、パッケージングされたzipファイルがsonatypeのサイトに公開するためにアップロードされます。

1.4.0.Beta1というバージョン文字列を利用した場合、prepareは問題なく実行できたのですが、 performで以下の様なエラーが返ってきました。

Return code is: 401, ReasonPhrase: Unauthorized.

バージョン番号が1.3.0では特に問題はなかったのですが、、、結局、バージョン番号を1.4.0-beta1に変更すると問題なくリリースが完了しました。

mike_neckさんと話をしていて、Semantic Versioningに関係しているのかなぁという話にはなったのですが、詳しく調べていません。。。

そのうち調べようかなぁ。。。。

プロキシ環境でのpluginコマンドの実行

Fri, 01 Aug 2014 15:24:00 +0900

Proxy環境で働いている方も結構いると思います。 Twitter上で、Elasticsearchのpluginコマンドでプラグインがインストールできなくて困っている方がいたので、調べてみたのでメモしておきます。

プラグインコマンド

Elasticsearchでは、プラグインという形でいくつかの便利な機能が公開されています。形態素解析ライブラリのKuromojiを使うためのプラグインや、クラスタの管理がGUIで可能なkopfプラグインなどがあります。公式、サードパーティいろいろです。

これらのプラグインをElasticsearchにインストールする場合、以下のコマンドを実行すれば自動的にダウンロードしてpluginsディレクトリにインストールしてくれます。

./bin/plugin -i elasticsearch/elasticsearch-analysis-kuromoji/2.3.0

ここで、elasticsearch/elasticsearch-analysis-kuromoji/2.3.0がプラグインのパスになります（例では、提供元/プラグイン名/プラグインバージョンとなっています。）。

このpluginコマンドがダウンロード元にアクセスに行くのですが、プロキシ環境だとプロキシの設定が必要になります。

プロキシの指定（Mac/LinuxとWindowsでの違い）

Mac/Linux(shコマンド)

以前の記事でプロキシのポート番号などの指定方法を以下のように説明していました。（※昔の記事のため、kuromojiプラグインのバージョンが古いです）

ElasticsearchのpluginコマンドはJavaで実装されています。（org.elasticsearch.common.http.client.HttpDownloadHelper）プラグインのダウンロードには、java.net.URL.openConnection()から取得URLConnectionを使用しています。

ですので、pluginのインストールを行う際に、Proxy環境にある場合は以下のようにコマンドを実行します。

./bin/plugin -DproxyPort=ポート番号 -DproxyHost=ホスト名 -i elasticsearch/elasticsearch-analysis-kuromoji/1.5.0

LinuxやMacの環境であれば、こちらのコマンドでプロキシの指定が可能です。ただし、Windows環境ではうまくいきません。

Elasticsearchは、環境の違いにより、ダウンロードするファイルが異なります。 Windows環境の方は、zipファイルをダウンロードしてもらうようになっています。 elasticsearchコマンドおよびpluginコマンドがbat形式で提供されているのがzipファイルとなるからです。

Windows(batコマンド)

Windows環境では次のように指定します。

set JAVA_OPTS="-DproxyHost=ホスト名 -DproxyPort=ポート番号"
bin\plugin -i elasticsearch/elasticsearch-analysis-kuromoji/2.3.0

コマンドの実装方法が少し異なるために、このようになっています。

まとめ

プロキシ環境で利用される場合は、プラグインコマンドは上記のように実行していただければと。

公式ガイドには、これらの情報を追記するPRを送る予定です。また、WindowsのコマンドでもMac/Linuxと同様にできたほうがいい気がするので、Issueをあげようと思います。

不明点などあれば、コメントいただければと。

elasticsearch-kopfの紹介（aliases画面）

Sun, 04 May 2014 01:01:00 +0900

今日はelasticsearch-kopfのAnalysis画面の紹介です。

（簡単なところから。。。その３）

ちょっとあいだが開いてしまいましたが、再開です。メニューのaliasesを選択すると、次のような画面が表示されます。

Aliases画面

Elasticsearchのaliasを画面で確認できます。

エイリアスは、インデックスに別名をつけることができるElasticsearchの機能です。１エイリアス＝１インデックスでも良いですが、１エイリアスに対して複数のエイリアスを付与することもできます。この機能を利用することで、次のようなことが可能となります。

インデックスの切り替えをアプリ側に意識させずに実施（アプリはエイリアス名に対して検索すればOKなので）
直近１週間のログを検索するためのエイリアスの作成（複数のインデックスを１つのエイリアスに割り当て可能）
特定のルーティングによる検索（特定のデータに対する検索だけに絞るためにfilterを指定する）

エイリアスについて詳しく知りたい方は公式ガイドをご覧いただくのが良いかと。

画面は非常にわかりやすい作りになっているので、特に説明必要ないんですよね。。。

elasticsearch-kopfの紹介（analysis画面）

Wed, 09 Apr 2014 11:41:00 +0900

今日はelasticsearch-kopfのAnalysis画面の紹介です。

（簡単なところから。。。その２）

メニューのanalysisを選択すると、次のような画面が表示されます。

Analysis画面

Elasticsearchの_analyze APIを画面で確認できます。画面で動作の確認ができるのは嬉しいですよね。

入力文字列：入力となるドキュメントに含まれる文字列や検索キーワードを入力
フィールドの指定：対象とするインデックス名、タイプ名、フィールド名を選択
analyze：ボタンを押す
トークナイズされた結果：入力文字列がどのようなトークンに分割されるか
- start、end：入力文字列中の文字列の位置
- pos：トークンの位置

という形でElasticsearchが指定されたフィールドで入力文字をどのようにトークナイズしたかを確認することができます。

Elasticsearchは内部でこのトークナイズされた単語を元に転置インデックスを作成し、検索に利用します。ですので、特定のデータが検索に上手くヒットしないときに、この画面でデータの文字列をトークナイズしてみるといった用途に使えます。

フィールドの設定がどのようにして入力文字列をトークンにしているかといった点については、今度のElasticsearch勉強会で話す予定です。

フィールドの設定を利用する以外に、アナライザを指定してどのようにトークナイズされるかを見ることもできます。「ANALYZE BYANALYZER」をクリックすると利用できます。

ANALYZE BY ANALYZER

トークナイズしたい文字列を入力し、インデックス名と、インデックスに設定されているアナライザ名を選択してanalyzeボタンを押すと結果が表示されます。（例では、kuromojiアナライザを利用して出力になっています。また、出力結果のposの表示位置がFIELD TYPEの時と違うのが少し気になりました。）

ただ、残念ながら、インデックスのマッピングで指定したアナライザしか利用できないみたいなので、どのアナライザがどんな挙動かを調べたい場合は、以前紹介したelasticsearch-inquisitorを利用したほうが良さそうです。

ということで、今日はanalysis画面の説明でした。

elasticsearch-kopfの紹介（rest画面）

Mon, 07 Apr 2014 11:24:00 +0900

今日はelasticsearch-kopfのREST画面の紹介です。

（簡単なところから。。。）

メニューのrestを選択すると、次のような画面が表示されます。

Elasticsearch自体が、さまざまな操作をRESTでできる仕組みになっています。検索にも利用しますが、それ以外の設定などにつてもリクエストを送ればOKです。

ですので、リクエストや設定を自分で組み立てて送ることができる画面が用意されているととても便利です。（もちろん、curlコマンドでもいいのですが、画面があると便利ですよね）

REST画面

History

履歴表示画面です。これまで、kopfのrest画面を利用して送信したリクエストが一覧で表示されます。

Historyという文字をクリックすることで、表示/非表示の切り替えが可能です。（最初は非表示）マウスオーバーすると、リクエストボディがポップアップで表示されます。

History

履歴にあるURLはクリック可能で、クリックすると実行されます。履歴はlocalStorageに保存されるみたいです。（ブラウザの仕様？あんまり詳しくないので。。。）たぶん、30件が上限かと（ソースで確認しただけ）

URL

rest画面でリクエストを送信する先のURLを指定します。メソッドは右側のSELECTで選択可能です。

リクエストパラメータも指定が可能です。

リクエストボディ

検索や設定のJSONを記述するところです。一応、JSON的にエラーがある場合は行数の左側にバツ印が出てきておかしなところもわかるようになっています。

インデントなどは行ってくれますが、senseみたいな補完などはないので、少し辛いところです。

レスポンス

送信したリクエストに対するレスポンスが返ってきます。インデントされた状態で表示されるので読みやすいかと。また、入れ子になっているJSONについては、閉じたり開いたりすることも可能です。（開始のカッコの右側に-が表示されていて、クリックすると閉じることができます。閉じると+に変わります）

簡単ですが、rest画面の説明でした。 KOPFを使っていて、ちょっとしたクエリを送ったりするのには便利だと思います。

複雑な検索クエリなどについては、やはりsenseを使うのが良いかと思いますが。。。

elasticsearch-kopfの紹介（概要）

Sat, 05 Apr 2014 23:18:00 +0900

なんだか、ドタバタしてて久しぶりの更新です。ベルリンの旅行記みたいなのも書きたいのですが、まずはこちらかと。

elasticsearch-kopfプラグインの紹介です。

今回は概要の説明だけになります。機能が結構多いので。

elasticsearch-kopfとは？

_siteプラグインの一つで、クラスタ管理用のプラグインになります。 headプラグインやHQプラグインと同様です。

プラグインの画面

このようにシンプルな画面で、スッキリとしています。緑を基調にした画面構成はElasticsearchの緑色を意識してるんでしょうか？

上記の画像に簡単なコメントを入れてあります。

メニュー

KOPF：KOPF自体の設定（接続先とリフレッシュインターバルの変更）
cluster：クラスタ管理、情報（デフォルト表示画面）
rest：RESTリクエスト送信、結果表示画面
aliases：エイリアス管理
analysis：analysis API
percolator：パーコレータ管理
warmup：ウォームアップクエリ管理

上記のようなメニューです。各メニューについては、今後のブログで少しずつ紹介しようかと。このメニューの色が、クラスタの状態も表しています。ステータスがYELLOWなら黄色、REDなら赤色に変わります。

インデックス

インデックスは列として表示されます。先ほどの画像では、2つのインデックスが表示されている状態です。インデックス毎に、シャードも表示されます。これは、各ノードがどのシャードを保持しているかという情報です。色の濃いシャードがプライマリでしょう。インデックス名やシャードの箱はクリックできるようになっていて、それぞれの情報がJSONで表示されます。その他にもドキュメント数、サイズなども表示されます。インデックスの各種操作（closeやdeleteなど）もここからメニューが表示されます。（これも次回詳しく）

ノード

ノードの情報が行として表示されます。ノードが増えると下に追加されていきます。 node1というのが、ノード名です。（ヒーローの名前とかが出てくるやつです。）

その他に、IPアドレス、ポート番号、負荷、ヒープサイズなども表示されています。電源ボタンはノードのシャットダウンを行うためのボタンです。（確認用のダイアログが表示される）

その他

その他に、クラスタの概要として、ノード数、インデックス数、シャード数、ドキュメント数なども表示されます。インデックスの作成などは、アイコンから操作が可能です。大規模なクラスタを管理している場合、検索ボックスを利用することで、インデックス名やノード名による絞込もできるようになっています。

感想

シンプルな構成の画面で、個人的にはheadよりも好きな画面です。 HQよりもシャードの分散具合がわかりやすいので、今後はこのプラグインを利用していこうと考えています。

まずは、簡単な紹介です。今後、各画面についてもう少し説明をブログに書いていこうかと考えています。待てない方は、触ってみてもらうのが良いかと。もちろん、続きを書いてもらってもいいですよ！！

いつも入れているElasticsearchのプラグイン

Tue, 11 Mar 2014 14:23:00 +0900

elasticsearchに、このへん入れるときっと幸せになれるはず・たぶん。 elasticsearch/elasticsearch-analysis-kuromoji/1.6.0 oyrusso/elasticsearch-HQ mobz/elasticsearch-head
— toshi_miura (@toshi_miura) 2014, 3月 5

こんなツイートを見かけたので、普段入れてるプラグインを簡単に紹介してみようかと。

ローカルの環境に普段入れているプラグインの紹介です。ちゃんとクラスタを管理しているというよりは、最新版の動作などを確認するための環境になります。なので、ちょっと視点が異なるかもしれませんが参考になればと。

elasticsearch-analysis-kuromoji

URL : elasticsearch-analysis-kuromoji

Kuromojiという日本語形態素解析のTokenizerなどを使えるようにするためのプラグインです。今度、発売される「ElasticSearch Server」日本語版には付録として、利用方法を執筆しました。参考にしていただければと。 READMEにもサンプルは掲載されてるので、こちらを参考にするのもありですが。

elasticsearch-extended-analyze

URL : elasticsearch-extended-analyze

私が開発しているプラグインです。 ElasticsearchにはanalyzeというAPIが用意されています。文章を渡すと指定したanalyzerなどでどのような単語に区切られるかがわかるAPIです。

ただ、analyzerの内部ではchar filter、tokenizer、token filterという個別のパーツがそれぞれ入力された文字列に対して処理を実施します。この過程がanalyze APIではわかりません。それをわかるようにしてみたのがelasticsearch-extended-analyzeプラグインになります。

詳細については過去の記事を見ていただければと。画面があると便利だよなぁと思いつつ、作ってない。。。

polyfractal/elasticsearch-inquisitor

URL : elasticsearch-inquisitor

クエリのデバッグとかに便利なプラグイン。

こちらも詳細は過去の記事を見ていただければと。

mobz/elasticsearch-head

URL : elasticsearch-head

クラスタ管理に便利なプラグインです。クラスタに存在するノードに対してインデックスのデータ（シャード）がどこに配置されているかなどが一目瞭然になる便利なプラグインです。プライマリシャードやレプリカなどもわかります。インデックスの削除もできるし、クエリを投げることもできるし、全部入りな感じのプラグインです。

私個人は、シャードの配置を見るのに主に利用しています。クエリを投げたりインデックスを消したりするのには殆ど使っていません。

royrusso/elasticsearch-HQ

URL : elasticsearch-HQ

これも管理系のプラグインです。こっちのほうが個人的にスッキリしていて好きなプラグインです。インデックスの管理やノードの停止などはこちらを主に使用しています。あくまでもローカルの簡易クラスタを管理する目的というのもあります。

polyfractal/elasticsearch-segmentspy

URL : elasticsearch-segmentspy

こちらはモニタリングでしょうか。 ElasticSearch Serverで紹介されていたのが主な理由で、入れてますがあんまり見てないかも。インデックスのSegment単位の情報が見ることが可能です。あと、ちょっと更新されてない感じがしますね。

elasticsearch/marvel

Elasticsearch社から提供されている、モニタリングなどに使えるプラグインです。開発環境では無償提供という感じです。渡しの場合、モニタリング目的ではなく、senseと呼ばれるクエリの補完をしてくれるツールの目的のために使用しています。モニタリング部分を停止する方法とかないかなぁ。

詳細については過去の記事を参考にしていただければと。

まとめ？

ということで、簡単にローカルに入っているプラグインの紹介でした。他にもいっぱいあるので、おすすめがあれば、教えてもらえると助かります。

elasticsearch-extended-analyzeを公開？

Thu, 14 Nov 2013 17:55:00 +0900

どーも。以前の記事で開発中としていたプラグインですが、とりあえず、pluginコマンドでインストール出来る形にしてみました。

インストールなどについては、READMEに記載したのでそちらを参照してもらうことにして、試行錯誤した話をメモとして残しておきます。

プラグインの開発はしいてたのですが、やっぱりpluginコマンドでインストール出来ないと使ってもらえないよなということで、勉強会も終わったのでちょっと調べてました。

プラグインコマンド

コマンドが用意されてますが、実態はJavaで実装されてて、通常はこんなかんじでプラグインをインストールします。

./bin/plugin -i elasticsearch/elasticsearch-analysis-kuromoji/1.6.0

この「elasticsearch/elasticsearch-analysis-kuromoji/1.6.0」という文字列ですが、「ユーザ名/リポジトリ名/バージョン」という意味になります。

で、ダウンロードするURLは以下のものの中から選ばれます。

elasticsearch.orgのダウンロード用サイト
search.maven.org
oss.sonatype.org
Githubのarchive

これらのサイトに先ほどのユーザ名、リポジトリ名、バージョンを利用したURLを組み立てて、ダウンロードしてくれるという仕組みになっています。

elasticsearch.orgについては、本家の人しかアップロードできないと思うので、なし。
maven、sonatypeについては、Mavenのリポジトリにリリースする必要があるんじゃないかなと。で、昔~~調べて~~ググって途中で挫折したんですが、挫折してます。手順が結構手間で。。。（参考記事：【最新版】Maven Central Repository へのライブラリ登録方法 #maven）

ということで、Githubにアップしたらなんとかなるんじゃん？ということで色々と調査して試してみました。（結果はイマイチなんですが。。。）

その１：mvn release:prepare

せっかくGithubだし、せっかくMavenなんだしなんか、pom.xmlに便利な設定したらコマンド一発でリリースできるんじゃない？という甘い気持ちで~~調査した~~ググったらそれっぽい記事が見つかりました。「MavenとGitHubの連携」って記事です。
で、pom.xmlの設定にも他のプラグインを真似してコピペしたものに<scm>ってタグがあったなぁと。このコマンドでついでにGithubにアップロードできるんじゃないの？ということで、試してみました。

mvn release:prepare

このコマンドを叩くと、記事にあるとおりにいくつか質問をされます。タグについては、プロジェクト名-バージョン番号という文字列がデフォルトだと指定されているので、v0.5と変更して実施してみると、Githubのreleaseにv0.5ってのができてるじゃないですか。
※pluginコマンドはGithubを見に行く時に次のファイルをダウンロードしに行きます。

https://github.com/ユーザ名/リポジトリ名/archive/vバージョン名.zip

やった！と思い、早速pluginコマンドを実行してみましたが、エラーが出ました。。。

Trying https://github.com/johtani/elasticsearch-extended-analyze/archive/v0.5.zip...
Downloading ...DONE
Installed johtani/elasticsearch-extended-analyze/0.5 into /Users/johtani/projects/tmp/ess_env/second_node/elasticsearch-0.90.7/plugins/extended-analyze
Usage:
    -u, --url     [plugin location]   : Set exact URL to download the plugin from
...省略...

Message:
   Error while installing plugin, reason: IllegalArgumentException: Plugin installation assumed to be site plugin, but contains source code, aborting installation.

あらら、なんで？と。
で、実際にgithubにアップされてたzipファイルをダウンロードしてみたら、githubのリポジトリにあるディレクトリ構成がそのまま入ってるじゃないですか。。。そうですか、そうですよね。prepareだし、タグ打ってzipにかためてくれるだけなんですねと。。。

おそらく、siteプラグインだけの場合はこの方法でpluginコマンド叩けばOKなんでしょうが、私がダウンロードしてもらいたいのは.jarファイルが入ったzipファイルなんです。

ということで、断念しました。（タグ消したりをgitコマンドで叩いて綺麗にし直すとか虚しい作業をしてました）

その２：github.comのWebでリリース

おとなしく、Sonatypeのサイトにアップロードする方向でがんばればいいんですが、とりあえず使えるようにするのが先だと思い、 github.comのページでアップロードしてしまおうと。

「release」というタブをクリックすると、画面からアップロードできるようになります。
zipファイルを作ってアップロードしました。（zipファイル自体はmvn packageコマンドを実行したらtarget/releaseというディレクトリに作成されてる）

これで行けるだろということで、またpluginコマンドを実行すると

Trying https://github.com/johtani/elasticsearch-extended-analyze/archive/v0.5.zip...
Downloading ...DONE
Installed johtani/elasticsearch-extended-analyze/0.5 into /Users/johtani/projects/tmp/ess_env/second_node/elasticsearch-0.90.7/plugins/extended-analyze
Usage:
    -u, --url     [plugin location]   : Set exact URL to download the plugin from
...省略...

Message:
   Error while installing plugin, reason: IllegalArgumentException: Plugin installation assumed to be site plugin, but contains source code, aborting installation.

あれ？同じエラー？なんで？jar入りのzipファイルアップロードしたのに？？？

と。で、https://github.com/johtani/elasticsearch-extended-analyze/releasesにreleaseのページができてたので見てみると、あら。アップロードしたファイルについては次のようなURLになってるじゃないですか。

https://github.com/johtani/elasticsearch-extended-analyze/releases/download/v0.5/v0.5.zip

で、よく見ると「Source code(zip)」というボタンもあるぞ？このリンクは？

https://github.com/johtani/elasticsearch-extended-analyze/archive/v0.5.zip

。。。あぁ。そうですか。そういうことですか。理解してない私が悪いんですねと。

結論？

ということで、とりあえず、releaseにjar入りファイルはアップロードできた（手動で）ので -uオプションで直接URL指定すればインストールできるだろ！と諦めました。いい勉強になりました。。。

README見ていただくとインストール方法が分かりますが、長いです。。。

時間をとって本腰入れてSonatypeにMavenコマンドでアップロードできるようにしようかな。。。

elasticsearch-extended-analyzeの改良

Mon, 04 Nov 2013 22:12:00 +0900

開発中ですと書きました、elasticsearch-extended-analyzeですが、改良しました。

改良と変更は以下のとおりです。

ソースのパッケージをorg.elasticsearchからinfo.johtaniに。MLで気になったので質問したら、変えたほうがいいよとのこと。ダウンロード化については、もう少々お待ちを。
出力形式を変更。可能な限りCharFilter、Tokenizer、TokenFilterそれぞれが出力する内容を返すようにしました。
- ただし、既存のAnalyzer（JapaneseAnalyzerクラスとか）に関しては、現時点では出力しません。CharFilterなどを取得するI/Fが見えないためです。（改良できるかの調査は未着手）

現時点でできてないのは以下の項目

pluginコマンドでインストール
出力したいAttributeの指定
TokenizeChainで変更されたTokenの追跡（現状はどのTokenがStopFilterで消されたかなどが不明）
画面の用意（簡単に確認できる画面）

ということで、README.mdに出力サンプルは貼り付けてるので、興味のある方は試してみてください。不明点などあれば、コメントかIssueかツイートでも。

elasticsearch-extended-analyzeプラグインを開発中

Fri, 25 Oct 2013 19:06:00 +0900

お久しぶりです。気づいたらまた、結構ブログを書いてなかったです。。。

今回は、今開発しているElasticsearchのプラグインに関するお話です。

いやぁ、名前決めるの難しいですね。これで英語的に合ってるか不安ですが、elasticsearch-extended-analyzeというプラグインを作っています。

どんなもの？

Solrの管理画面のanalysisに相当する機能が欲しくて作り始めました。

Elasticsearchにはanalyze APIというAPI（名前あってるのかなぁ?）が存在します。
これは、文字列を投げると、指定したアナライザやトークナイザでどのようなトークンに分割されるかを調べることができるAPIです。

例えば、elasticsearch-analysis-kuromojiをインストールしたElasticsearchに対して、以下のcurlコマンドを実行します。

curl -XPOST 'localhost:9200/_analyze?tokenizer=kuromoji_tokenizer&filters=kuromoji_baseform&pretty' -d '寿司が美味しい'

すると、トークナイズされた結果が次のようなJSONで返ってきます。

{
  "tokens" : [ {
    "token" : "寿司",
    "start_offset" : 0,
    "end_offset" : 2,
    "type" : "word",
    "position" : 1
  }, {
    "token" : "が",
    "start_offset" : 2,
    "end_offset" : 3,
    "type" : "word",
    "position" : 2
  }, {
    "token" : "美味しい",
    "start_offset" : 3,
    "end_offset" : 7,
    "type" : "word",
    "position" : 3
  } ]
}

トークナイズの結果がわかるのは嬉しいのですが、どんな品詞なのかといったKuromoji固有のTokenの属性情報がなくなってしまいます。

Solrでは、こんな画面が用意されていて、品詞情報とかが出力されます。あとは、各TokenFilterでどのトークンがなくなっているかなどもわかるようになっています。

これって結構役立つと思うんですよ。ということで、Pluginも作ってみたかったので、いい機会だから作ってみようかと。

出力サンプル

まずは、その他のAttribute（品詞とか）を表示するところを実装してみました。

curl -XPOST 'localhost:9200/_extended_analyze?tokenizer=kuromoji_tokenizer&filters=kuromoji_baseform&pretty' -d '寿司が美味しい'

先ほどとほぼ一緒のcurlコマンドを実行します。違う点は**「_analyze」が「_extended_analyze」**となっている点です。
で、実行結果はこんな感じです。（長いですがそのまま載せてます。続きの文章がしたにあります。）

{
  "tokens" : [ {
    "token" : "寿司",
    "start_offset" : 0,
    "end_offset" : 2,
    "type" : "word",
    "position" : 1,
    "extended_attributes" : [ {
      "org.apache.lucene.analysis.tokenattributes.TermToBytesRefAttribute#bytes" : "[e5 af bf e5 8f b8]"
    }, {
      "org.apache.lucene.analysis.tokenattributes.PositionLengthAttribute#positionLength" : 1
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.BaseFormAttribute#baseForm" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech" : "名詞-一般"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech (en)" : "noun-common"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading" : "スシ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading (en)" : "sushi"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation" : "スシ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation (en)" : "sushi"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType (en)" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm (en)" : null
    }, {
      "org.apache.lucene.analysis.tokenattributes.KeywordAttribute#keyword" : false
    } ]
  }, {
    "token" : "が",
    "start_offset" : 2,
    "end_offset" : 3,
    "type" : "word",
    "position" : 2,
    "extended_attributes" : [ {
      "org.apache.lucene.analysis.tokenattributes.TermToBytesRefAttribute#bytes" : "[e3 81 8c]"
    }, {
      "org.apache.lucene.analysis.tokenattributes.PositionLengthAttribute#positionLength" : 1
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.BaseFormAttribute#baseForm" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech" : "助詞-格助詞-一般"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech (en)" : "particle-case-misc"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading" : "ガ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading (en)" : "ga"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation" : "ガ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation (en)" : "ga"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType (en)" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm (en)" : null
    }, {
      "org.apache.lucene.analysis.tokenattributes.KeywordAttribute#keyword" : false
    } ]
  }, {
    "token" : "美味しい",
    "start_offset" : 3,
    "end_offset" : 7,
    "type" : "word",
    "position" : 3,
    "extended_attributes" : [ {
      "org.apache.lucene.analysis.tokenattributes.TermToBytesRefAttribute#bytes" : "[e7 be 8e e5 91 b3 e3 81 97 e3 81 84]"
    }, {
      "org.apache.lucene.analysis.tokenattributes.PositionLengthAttribute#positionLength" : 1
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.BaseFormAttribute#baseForm" : null
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech" : "形容詞-自立"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.PartOfSpeechAttribute#partOfSpeech (en)" : "adjective-main"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading" : "オイシイ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#reading (en)" : "oishii"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation" : "オイシイ"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.ReadingAttribute#pronunciation (en)" : "oishii"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType" : "形容詞・イ段"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionType (en)" : "adj-group-i"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm" : "基本形"
    }, {
      "org.apache.lucene.analysis.ja.tokenattributes.InflectionAttribute#inflectionForm (en)" : "base"
    }, {
      "org.apache.lucene.analysis.tokenattributes.KeywordAttribute#keyword" : false
    } ]
  } ]
}

先ほどの結果に**「extended_attributes」**という配列のオブジェクトが追加された形になっています。ちょっと長くなってしまいましたが。。。

Solrの処理を真似して作ったので大したことはやってないんですが、少しは便利になるかもなぁと。

現時点では、最終的な結果しか取得できないですが、今後は次のような機能を作っていこうかと思っています。できるかどうかは、やってみてって感じですが。

pluginコマンドでインストール
- pom.xmlはありますが、まだMavenとかに登録はされていません。ですので、mvn packageしてからjarファイルをpluginsフォルダに配置しないといけません。pluginコマンドでインストールできるともっと使ってもらえるはず？
出力したいAttributeの指定
- リクエストパラメータで、出力したいAttribute名を指定するとか。
出力形式の変更
- 今は、Solrの真似をしていますが、せっかくJSONだったりするので、もう少し検討しようかと（同じAttributeの異なる値も1オブジェクトとして出力されてる）
TokenizeChainの出力
- Solr同様、CharFilter、Tokenizer、TokenFilterが動作して、最終的なTokenがインデックスに登録されます。ですので、各処理の直後のTokenがどうなっているかもわかったほうが嬉しいと思うので、それらも取得できるようにしたいなぁと
画面の用意
- せっかくプラグインなんだし、画面で見れると嬉しいかなと。これは当分先になっちゃうと思いますが、Webページで確認できるような画面を作ると確認しやすくなるかなぁと。上記対応が終わってから取替かかると思いますが。

とりあえず、思いつくのはこんなかんじです。

Elasticsearchの_analyze APIを真似しただけのコードだし、テストも実装もまだまだですが、とりあえず公開してみました。

要望などあれば、コメント、Issue、ツイート（もちろん、テストコードなども！）なんでも受け付けてますので、お気軽に。

elasticsearch-inquisitorプラグインの紹介

Mon, 23 Sep 2013 12:27:00 +0900

今日は、ElasticSearchのMLで見つけたelasticsearch-inquisitorプラグインの紹介です。

ElasticSearchはREST API形式で簡単にコマンドラインからいろいろな処理を実行できて便利ですが、 GUIがあったほうが楽なこともまた事実です。今回紹介する、inquisitorプラグインもSiteプラグイン（Webブラウザでアクセスできるプラグイン）の1つです。（ただし、ローカルにインストールしてローカルのElasticSearchにしか接続できませんが。。。）

インストール

プラグインですので、以下のコマンドでインストールが出来ます。インストール後はElasticSearchの再起動が必要です。

bin/plugin -install polyfractal/elasticsearch-inquisitor

ElasticSearch再起動後に、以下のURLにアクセスすればOKです。 ※ローカルでのみ動作可能なプラグインです。（内部で呼び出しているJSにlocalhostと記載があるため）

http://localhost:9200/_plugin/inquisitor/#/

何ができるの？

自分の書いたQueryが正しく動作するかや、Analyzerによって文章がどのように、Term（Token）に分割されるかといった挙動をWebブラウザ上で確認することができます。用意されている画面は「Queries」「Analyzers」「Tokenizers」の3種類です。

Queries

クエリの確認、実行が可能な画面です。

「Index」「Type」はプルダウンになっており、現在ElasticSearchに存在しているものが選択可能です。その下のテキストエリアがクエリを入力する画面です。

クエリを入力していると、入力しているクエリがValidかどうかをクエリのコンソール部分（右側上部）に表示してくれます。

少し残念なことに、Tabを押すと、フォームのフォーカスが切り替わってしまうので、クエリを入力するのがちょっと面倒です。。。（私は通常の検索には、ChromeプラグインのSenseというものを利用してます。）

クエリに問題がない場合は、「Query」ボタンを押すことで実際の検索が実行されます。この時、画面真ん中のブルーのテーブル（内部で実行されるクエリ）の部分に、QueryがElasticSearch内部で解釈されたあとの、Luceneで実行されるレベルのクエリに変換されたクエリが表示されます。

これが便利です。JSONで記述したり、色々なタイプのクエリがElasticSearchでは実行できますが、望んだ形に単語が区切られているかなどを確認することができるため、非常に便利です。

ElasticSearchのQuery DSLではexplainをtrueにすることで、ヒットしたドキュメントのスコア計算に用いられた単語などがわかるのですが、そもそもヒットしないクエリの場合は、explainでは単語の区切られ方などがわかりません。

その場合に、このプラグインで確認すると、想定と違う単語の区切られ方やクエリの造られ方がわかるかと思います。

Analyzers

Analyzerによる文章のアナライズ結果の確認が出来る画面です。 ElasticSearchやSolrにあまり詳しくない場合、どんなAnalyzerが文章をどのように単語に区切って、転置インデックスのキーワードとして利用しているかがわからないと思います。

このAnalyzerが文章をどのように単語に区切っているかを確認することができるのがAnalyzers画面です。こんなかんじの画面になります。

一番上のテキストエリアが文章を入力する場所です。文章を入力していくと、その下のテーブルの「Analyzed Text」の部分が変化していくのが分かります。このグレーの単語が転置インデックスのキーワードとなります。

予め用意されているAnalyzer以外に、用意されているTokenzier＋Filterの組み合わせも簡単ですが確認可能です。（Tokenizer、Filtersとあるテーブル）ただし、ここまでのどちらも細かな設定は画面上ではできません（Filterの細かな引数の指定など）

一番下の部分が、ElasticSearchに存在しているインデックスごとに定義されたAnalyzerやフィールドを元にした解析結果を表示することができる領域です。

自分でマッピングを記述してフィールド定義したものの動作確認や、インデックスを適当に作ったけど、うまくヒットしない場合など、ここで、単語の区切れ方を確認することで、検索になぜヒットしないのかといった問題のヒントを得ることができると思います。

Analyzerによっては、インデックス対象の文字として扱わない文字があったりしますので。先ほどのQueries画面のLuceneに投げられる直前のクエリと、Analyzersでの単語の区切られ方を確認することで、検索がうまくヒットしていないことが判明すると思います。

Tokenizers

最後はTokenizers画面です。Analyzersとほぼ同様ですが、ちがいは、デフォルトで用意されているTokenizerの挙動の確認ができるというだけになります。

簡単な確認ならここで可能かと。

注意点は？

まだ開発途中のようで、つぎの部分が課題かと。

ローカルでのみ実行可能
Queries画面の結果の「Explain Result」リンクが未実装
Queries画面のクエリ入力が使いにくい（タブが打てないので）
カスタム登録のAnalyzersはインデックスを用意しないと確認できない。（Kuromojiのプラグインを登録しただけでは確認できなかった）
細かな設定のフィールドも用意しないと、Analyzers画面では利用できない

まとめ

ということで、Inquisitor（読みがわからない）プラグインの簡単な説明でした。検索にうまくヒットしないという理由は大体の場合、クエリに入力した文字列が単語に区切られたものと、登録したデータが単語に区切られたものが異なるために検索にヒットしないというものです。

そのクエリ、データの単語の区切られ方を確認するのに役に立つプラグインじゃないでしょうか。

ちなみに、このプラグイン自体はHTML＋JSで作成されており、実際にはElasticSearchが持っているREST APIをキックしているだけになります。ですので、Web画面なんか要らないという方は、このプラグインが実際に送信しているリクエストを参考にするとcurlコマンドでどういったリクエストを投げればいいかというのがわかると思います。

私は軟弱者なので画面があったほうがいいですが。