Ruby - Elasticsearch Labs

Elasticsearch Ruby クライアント向け ES|QL クエリビルダーのご紹介

Fernando Briano — Wed, 17 Sep 2025 00:00:00 GMT

最近、Apache 2 ライセンスに基づいて公開された Ruby gem、 elastic-esqlをリリースしました。この gem を使用すると、Elastic のES|QLクエリを慣用的な Ruby で構築し、ES|QL クエリ API で使用できるようになります。ES|QL を使用すると、開発者はクエリを介して Elasticsearch に保存されているデータをフィルタリング、変換、分析できます。「パイプ」（ | ）を使用して、データを段階的に処理します。代わりに gem は Ruby 関数を使用します。これを元のオブジェクトに連鎖して、より複雑なクエリを構築できます。

ESQL:

ルビー：

Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending

インストール

この gem は、RubyGems から次のようにインストールできます。

gem install elastic-esql

または、プロジェクトの Gemfile に追加することもできます。

gem 'elastic-esql'

使用法

完全なクエリを一度に構築することも、 fromやrowなどのソースコマンドを使用してクエリオブジェクトを作成し、それに基づいて ES|QL メソッドを連鎖して構築することもできます。

query = Elastic::ESQL.from('sample_data') query.limit(2).sort('@timestamp')

gem はto_sメソッドでコードを ES|QL に変換するので、印刷されるか文字列としてキャストされるときに ES|QL クエリを返します。

query = Elastic::ESQL.from('sample_data').limit(2).sort('@timestamp').descending query.to_s # => "FROM sample_data | LIMIT 2 | SORT @timestamp DESC"

各関数の!に相当するものを使用して、クエリオブジェクトをインスタンス化し、その初期状態を変更できます。

query = Elastic::ESQL.from('sample_data') query.to_s # => "FROM sample_data" query.limit!(2).sort!('@timestamp') query.to_s # => "FROM sample_data | LIMIT 2 | SORT @timestamp"

このツールは、 enrichやsortなどの追加ステップを ES|QL 関数に連鎖させる便利な方法を提供します。Elastic::ESQLオブジェクトでenrich呼び出すと、それにonとwithを連鎖できます。

esql.enrich!('policy').on('a').with({ name: 'language_name' })

sortを使用した後、クエリにdesc 、 asc 、 nulls_first 、 nulls_lastを連鎖させることもできます。

Elastic::ESQL.from('sample_data').sort('@timestamp').asc.to_s # => 'FROM sample_data | SORT @timestamp ASC' Elastic::ESQL.from('sample_data').sort('@timestamp').desc.nulls_first.to_s # => 'FROM sample_data | SORT @timestamp DESC NULLS FIRST'

また、ES|QL クエリを自分で記述する場合や、ライブラリにまだ追加されていない機能を使用する場合に備えて、カスタム文字列もサポートされています。customクエリの末尾の文字列を結合します。パイプ文字を追加せずに、関数に送信されるとそれらが追加されます。これらはスペース文字によってクエリの残りの部分に結合されます。

esql = Elastic::ESQL.from('sample_data') esql.custom('| MY_VALUE = "test value"').to_s # => 'FROM sample_data | MY_VALUE = "test value"'

custom関数を連鎖させることもできます:

esql.custom('| MY_VALUE = "test value"').custom('| ANOTHER, VALUE') 'FROM sample_data | MY_VALUE = "test value" | ANOTHER, VALUE'

Ruby クライアントで ES|QL クエリビルダーを使用する

クエリオブジェクトを送信することで、 elasticsearch-rubyとesql.query API でクエリビルダーを直接使用できます。

require 'elasticsearch' require 'elastic/esql' client = Elasticsearch::Client.new index = 'sample_data' query = Elastic::ESQL.from(index) .sort('@timestamp') .desc .where('event_duration > 5000000') .limit(3) .eval({ duration_ms: 'ROUND(event_duration/1000000.0, 1)' }) client.esql.query(body: { query: query })

Elasticsearch Ruby クライアントの ES|QL Helper と一緒に使用することもできます。詳細については、以下を参照してください。

require 'elasticsearch/helpers/esql_helper' Elasticsearch::Helpers::ESQLHelper.query(client, query)

スタンドアロンツールとして

この gem は、ES|QL クエリを慣用的な方法で構築するためのスタンドアロンツールとして設計されています。ランタイム依存関係がないため、公式の Elasticsearch Ruby クライアントと一緒に使用することも、単独で使用することもできます。

生成されたクエリは、アプリケーションが Elasticsearch API (Ruby かどうかに関係なく) と対話するあらゆる方法でesql.query API で使用できます。elastic-esqlを使用してクエリを構築すると、生成された文字列をリクエスト本文のqueryパラメータとして API に送信できます。

以前、 Elasticsearch を一般的な Ruby ツールと併用する方法について書きました。この gem は、一般的な Ruby ツールと組み合わせて使用し、ES|QL を使用して Elasticsearch をクエリできます。

まとめ

このライブラリは現在開発中であり、最終的な API はまだ完成していません。現在はテクニカルプレビューとしてリリースされています。現在の API または一般的な使用方法に関してフィードバックがある場合は、遠慮なく新しい問題を開いてください。Ruby ES|QL クエリビルダーの詳細については、 READMEを参照してください。

LogstashでのRubyスクリプト

Dai Sugimori — Tue, 24 Jun 2025 00:00:00 GMT

Logstash は、複数のソースからデータを取り込み、変換して、選択した宛先に送信するデータ処理パイプラインです。フィルタープラグインはこのプロセスの鍵であり、データがパイプラインを通過するときにデータに対して特定の操作を実行します。

Logstash には、データの解析、拡充、変更などの一般的なタスク用のフィルターがいくつか組み込まれています。しかし、場合によっては、これらの標準フィルターが提供できる範囲を超えたカスタムロジックが必要なシナリオに遭遇することがあります。ここでRuby フィルタープラグインが役立ちます。

Ruby フィルタープラグインを使用すると、Logstash パイプライン内でカスタム Ruby コードを直接実行できます。標準フィルターでは不十分な場合は、Ruby フィルターを使用すると、複雑なデータ変換を処理したり、カスタムビジネスロジックを実装したり、外部システムと統合したりできます。

このブログでは、Ruby フィルターの使い方を、基本的な使い方から高度な使い方まで解説します。

Ruby フィルターはいつ使用すればよいですか?

Elastic のコンサルティングアーキテクトとして、Logstash は現在最先端のデータ処理エンジンではないにもかかわらず、データ処理パイプラインに Logstash を使用している顧客をよく見かけます。複雑なデータ操作やカスタムロジックに関しては、標準フィルターの制限に悩まされることがよくあります。このような場合、Ruby フィルターはこれらの課題を克服するのに役立ちます。

Ruby フィルターは、標準の Logstash フィルターが特定の要件を満たせない場合に役立ちます。一般的な使用例をいくつか紹介します。

深くネストされたデータ操作: 複雑な JSON 構造、配列内の配列を変更したり、コンテンツに基づいてデータを動的に再構築したりできます。
高度な文字列処理: 非構造化テキストから構造化データを解析して抽出します
複雑なビジネスロジックの実装: 条件付きロジック、ループ、または複雑な計算を必要とするカスタム変換を作成します。

基本的な使い方

Ruby フィルターがどのように機能するかを理解するために、簡単な例から始めましょう。

Rubyフィルターの設定

Logstash パイプラインを作成するときは、構成ファイルを/etc/logstash/conf.dディレクトリに配置する必要があります。あるいは、Logstash を手動で起動するときに-fオプションを使用して構成ファイルへのパスを指定し、パイプラインを簡単に試すことができます。

$ ./bin/logstash -f /path/to/your_pipeline.conf

構成ファイルには.conf拡張子が必要です。

Ruby フィルターを使用するには、Logstash パイプライン構成 (*.conf) ファイルのフィルターセクションでrubyフィルターを定義します。基本的な例は次のとおりです。

filter { ruby { code => " event.set('new_field', 'Hello from Ruby!') " } }

このインライン Ruby フィルターは、Logstash 構成内で Ruby フィルターインスタンスを定義します。codeパラメータは、このフィルタによって処理される各イベントに対して Logstash が実行するインライン Ruby スクリプトを提供します。そのスクリプト内には、イベント自体を表すevent変数があります。イベントオブジェクトには、Logstash に送信された元のデータと、Logstash のフィルターステージ中に作成された追加フィールドが含まれます。これらのフィールドには、 event.get()やevent.set()などの Logstash イベント API を介してアクセスできます。このサンプルコードでは、 event.set('new_field', 'Hello from Ruby!') new_fieldという名前の新しいフィールドを文字列値Hello from Ruby!に設定します。必要に応じて、このcodeブロックに他のコードを追加できます。

このeventオブジェクトはキーバリュー型のデータコンテナとして機能しますが、通常の Ruby のハッシュオブジェクトではないことに注意してください。イベント API の詳細については、この公式ドキュメントをご覧ください。

Rubyスクリプトを外部化する

単純な変換には、インライン Ruby コードが便利です。ただし、複雑なロジックや再利用可能な関数の場合は、コードを外部の Ruby スクリプトに移動することをお勧めします。これにより保守性が向上し、Logstash パイプラインの構成がクリーンな状態に保たれます。

まず、Ruby スクリプトを作成し、 my_ruby_script.rbとして保存します。スクリプトはイベントを処理するfilterメソッドを定義する必要があります。処理中の現在のイベントを表すイベントオブジェクトを引数として受け取ります。filterメソッドは、発行するイベントの配列を返す必要があります。イベントを削除するには、空の配列を返します。

たとえば、次のスクリプトはmessageフィールドを読み取り、その長さを計算し、結果をmessage_lengthという新しいフィールドに格納します。

def register(params) # This method is called when the plugin is loaded. # You can use it to initialize any instance variables or perform setup tasks. end def filter(event) message = event.get('message') if message event.set('message_length', message.length) end return [event] end

次に、 pathオプションを使用してスクリプトを参照するように Ruby フィルター構成を設定します。これにより、Logstash は外部スクリプトを読み込んで実行します。外部スクリプトを使用する場合は、ファイルが存在し、適切な権限があることを確認してください。

filter { ruby { path => "/path/to/my_ruby_script.rb" } }

これで、各イベントはmy_ruby_script.rbのfilterメソッドに渡され、処理されるようになります。

このアプローチにより、複雑なロジックをより効率的に管理できるようになり、Ruby コードのテスト、デバッグ、再利用が容易になります。

高度な使用法

このセクションでは、Logstash で Ruby フィルターを使用する高度な例をいくつか紹介します。これらの例では、Ruby を使用してデータ変換を実行し、イベントを強化し、カスタムロジックを実装する方法を示します。

ネストされたデータ構造の操作

Logstash イベントは、Logstash が処理するコアデータ構造です。配列やハッシュなどのネストされたデータ構造を含むさまざまなフィールドを含めることができます。Ruby フィルターを使用すると、これらのネストされた構造を簡単に操作できます。

Ruby フィルターはハッシュや配列などのネストされたデータ構造を処理できるため、これらの構造内のフィールドを変更したり追加したりできます。これは、JSON のような複雑なデータ形式を扱うときに便利です。

input { generator { lines => [ '{"nested": {"key1": "value1", "key2": "value2"}}' ] count => 1 codec => "json" ecs_compatibility => "disabled" } } filter { ruby { code => " nested_data = event.get('nested') if nested_data.is_a?(Hash) nested_data['key3'] = 'value3' event.set('nested', nested_data) end " } } output { stdout { codec => rubydebug } }

この例では、入力データにネストされた JSON オブジェクトが含まれています。Ruby フィルターは、新しいキーと値のペアを追加してネストされたデータを変更します。ネストされたデータに対するこの種の操作は標準の Logstash フィルターでは不可能であるため、Ruby フィルターは複雑なデータ構造に便利なオプションになります。

1つのイベントを複数のイベントに分割する

Ruby フィルターを使用して、単一のイベントを複数のイベントに分割することもできます。これは、アイテムの配列を含む単一のイベントがあり、アイテムごとに個別のイベントを作成する場合に便利です。

Elasticsearch の取り込みパイプラインも Beats/Elastic Agent のプロセッサもイベントの分割をサポートしていないことに注意してください。これは Logstash の最も強力な使用例の 1 つです。

分割フィルター付き

splitフィルターを使用すると、指定されたフィールドに基づいてイベントを複数のイベントに分割できます。ただし、分割中に追加の変換やロジックを実行する必要がある場合は、分割フィルターと組み合わせて Ruby フィルターを使用できます。

次の例では、RSS フィードが 1 行の XML テキストとして存在します。複数の要素が含まれています。Ruby フィルターは、XML から要素を抽出し、 itemsという新しいフィールドに保存するために使用されます。次に、分割フィルターを使用して、 itemsフィールドに基づいてイベントを複数のイベントに分割します。

input { generator { lines => [ 'Sample RSSArticle 1http://example.com/1Desc 1Article 2http://example.com/2Desc 2' ] count => 1 codec => "plain" ecs_compatibility => "disabled" } } filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { code => "event.set('items', event.get('[rss][channel][item]')) if event.get('[rss][channel][item]')" } split { field => "items" } ruby { code => " item = event.get('items') event.set('title', item['title']) if item['title'] event.set('link', item['link']) if item['link'] event.set('description', item['description']) if item['description'] " } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } } output { stdout { codec => rubydebug } }

出力は次のようになります:

{ "title" => "Article 1", "link" => "http://example.com/1", "description" => "Desc 1" } { "title" => "Article 2", "link" => "http://example.com/2", "description" => "Desc 2" }

お気づきかもしれませんが、この場合、 rubyフィルターは必須ではありません。splitフィルターを使用すると、 itemsフィールドに基づいてイベントを複数のイベントに分割できます。また、 mutateフィルターを使用すると、不要なフィールドを削除できます。ただし、分割中に追加の変換やロジックを実行する必要がある場合は、Ruby フィルターを使用できます。

インラインRubyスクリプトを使用する

インライン Ruby スクリプトを使用して、 event.cloneメソッドとnew_event_block variable ( new_event_block.call(new_event)など) を使用することで、単一のイベントを複数のイベントに分割することもできます。これにより、元のイベントのデータを保持しながら、元のイベントに基づいて新しいイベントを作成できます。

Ruby フィルターを使用して 1 つのイベントを複数のイベントに分割する方法の例を次に示します。入力と出力は前の例と同じです。

filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { code => " items = event.get('[rss][channel][item]') if items.is_a?(Array) items.each do |item| new_event = event.clone new_event.set('title', item['title']) new_event.set('link', item['link']) new_event.set('description', item['description']) new_event_block.call new_event end event.cancel elsif items.is_a?(Hash) event.set('title', items['title']) event.set('link', items['link']) event.set('description', items['description']) end " } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } }

外部Rubyスクリプトを使用する

外部の Ruby スクリプトを使用して、単一のイベントを複数のイベントに分割することもできます。

設定ファイル:

filter { xml { source => "message" target => "rss" store_xml => true force_array => false } ruby { path => "path/to/ruby/split_event.rb" } mutate { remove_field => ["@timestamp", "@version", "sequence", "host", "event", "message", "rss", "items"] } }

Ruby スクリプトはsplit_event.rbとして外部化する必要があります:

def filter(event) items = event.get('[rss][channel][item]') events = [] if items.is_a?(Array) items.each do |item| new_event = event.clone new_event.set('title', item['title']) new_event.set('link', item['link']) new_event.set('description', item['description']) events << new_event end return events elsif items.is_a?(Hash) event.set('title', items['title']) event.set('link', items['link']) event.set('description', items['description']) return [event] else return [] end end

filterメソッドはイベントの配列を返す必要があることに注意してください。受信したイベントオブジェクトを複製して配列に追加することで複数のイベントを返すことも、1 つの要素を持つ配列として 1 つのイベントを返すこともできます。

return events # or # return [event]

これにより、単一のイベントを複数のイベントに分割できます。

外部コマンドを実行し、その出力を解析する

Logstash exec 入力プラグインを使用すると、外部コマンドを実行でき、その出力は Logstash のイベントになります。コマンドの出力はイベントのmessageフィールドに保存されます。

通常、システムコマンドの出力は人間が判読できますが、Logstash が簡単に解析できる JSON やその他の形式として構造化されていません。これを処理するには、Ruby フィルターを使用して出力を解析し、そこから情報を抽出します。

以下は、 exec入力プラグインを使用して、Unix 系システムで実行中のすべてのプロセスを一覧表示するps -efコマンドを実行する例です。出力は Ruby フィルターによって解析され、各プロセスに関する関連情報が抽出されます。

input { exec { command => "ps -ef" interval => 60 } } filter { ruby { code => ' processes = [] lines = event.get("message").split("\n") lines.each_with_index do |line, index| # Skip header line and empty lines next if index == 0 || line.strip.empty? entry = nil # Use regex to match the ps -ef output format more flexibly # This pattern accounts for variable spacing and different time formats if line =~ /^\s*(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(\S+)\s+(\S+)\s+([\d:]+\.?\d*)\s+(.+)$/ uid, pid, ppid, c, stime, tty, time, cmd = $1, $2, $3, $4, $5, $6, $7, $8 entry = { "UID" => uid, "PID" => pid, "PPID" => ppid, "C" => c, "STIME" => stime, "TTY" => tty, "TIME" => time, "CMD" => cmd.strip } elsif line =~ /^\s*(\S+)\s+(\d+)\s+(\d+)\s+(\d+)\s+(.+)$/ # Fallback pattern for lines that might not match the exact format # Split the remaining part more carefully uid, pid, ppid, c, remainder = $1, $2, $3, $4, $5 # Split remainder into STIME, TTY, TIME, CMD parts = remainder.strip.split(/\s+/, 4) if parts.length >= 4 stime, tty, time, cmd = parts[0], parts[1], parts[2], parts[3] entry = { "UID" => uid, "PID" => pid, "PPID" => ppid, "C" => c, "STIME" => stime, "TTY" => tty, "TIME" => time, "CMD" => cmd } end end if entry && entry["UID"] == "0" original_line = line.strip entry["original_line"] = original_line if original_line.length > 0 processes.push(entry) end end event.set("processes", processes) event.remove("message") event.remove("event") ' } } output { stdout { codec => rubydebug } }

この例では、 exec入力プラグインを使用して、60 秒ごとにps -efコマンドを実行します。Ruby フィルターは出力を処理し、UID、PID、PPID、CPU 使用率 (C)、開始時刻 (STIME)、TTY、合計 CPU 時間 (TIME)、実行されたコマンド (CMD) などの関連フィールドを抽出します。私の macOS 環境では問題なく動作しますが、システムのps -efコマンドの出力形式に合わせて正規表現パターンを調整する必要がある場合があります。

組み込みライブラリを使用する

Ruby フィルタープラグインを使用すると、さまざまなタスクに非常に役立つ組み込みの Ruby ライブラリを使用できます。たとえば、 jsonライブラリを使用して JSON 文字列を解析したり、 dateライブラリを使用して日付を操作したりできます。

以下は、 jsonライブラリを使用して、フィールドに格納されている JSON 文字列を解析する例です。

require 'json' def filter(event) json_string = event.get('message') parsed_json = JSON.parse(json_string) event.set('parsed_json', parsed_json) return [event] end

毎回ライブラリを要求するのを避けるには、Ruby フィルタースクリプトの先頭でrequireステートメントを使用できるように Ruby コードを外部化する必要があります。これにより、ライブラリが一度読み込まれ、スクリプトで使用できるようになります。

環境で使用できるライブラリを確認するには、Ruby フィルターで次のコードを実行して、組み込みライブラリを一覧表示できます。

Gem.loaded_specs.sort_by { |name, _| name }.each do |name, spec| puts "#{name}: #{spec.version}" end

注意:組み込みライブラリは Logstash では正式にサポートされていないため、その動作は変更される可能性があり、将来のバージョンでは利用できなくなる可能性があります。自己責任でご使用ください。

まとめ

Logstash Ruby フィルターを使用すると、Logstash パイプラインの機能をカスタマイズおよび拡張できます。この記事では、Ruby フィルターの基本的な使用方法を説明し、高度な使用例を示しました。

Ruby フィルターを活用することで、カスタムロジックや高度な操作を必要とする複雑なデータ処理タスクを処理できます。ネストされたデータ構造を操作したり、イベントを分割したり、複雑または非構造化テキストを解析して構造化 JSON に変換したりする場合でも、Ruby フィルターは特定の要件を満たす柔軟性を提供します。

このガイドが、Logstash Ruby フィルターの可能性を最大限に引き出すための知識とインスピレーションを提供できたことを願っています。スクリプト作成を楽しんでください!

RubyアプリをOpenSearchからElasticsearchに移行する方法

Fernando Briano — Fri, 13 Dec 2024 00:00:00 GMT

OpenSearch Ruby クライアントは、バージョン7.xの Elasticsearch Ruby クライアントからフォークされたため、コードベースは比較的似ています。つまり、Ruby コードベースを OpenSearch から Elasticsearch に移行すると、それぞれのクライアントライブラリのコードは非常に馴染みのあるものになります。このブログ記事では、OpenSearch を使用する Ruby アプリの例と、このコードを Elasticsearch に移行する手順を紹介します。

どちらのクライアントも、一般的な Apache License 2.0 に基づいてリリースされているため、オープンソースかつフリーソフトウェアです。Elasticsearch のライセンスは最近更新され、Elasticsearch と Kibana のコアはバージョン 8.16 以降、OSI 承認のオープンソースライセンス AGPL に基づいて公開されています。

Rubyアプリの移行時にElasticsearchのバージョンを考慮する

移行時に考慮すべき点の 1 つは、どのバージョンの Elasticsearch を使用するかということです。最新の安定リリース (この記事の執筆時点では8.17.0を使用することをお勧めします。Elasticsearch Ruby クライアントのマイナーバージョンは、Elasticsearch のマイナーバージョンに従います。したがって、Elasticsearch 8.17.xでは、Ruby gem のバージョン8.17.xを使用できます。

OpenSearch は Elasticsearch 7.10.2 からフォークされました。そのため、API が変更され、どちらでも異なる機能が使用される可能性があります。しかし、それはこの記事の範囲外なので、サンプルアプリで最も一般的な操作についてのみ説明します。

Ruby on Rails の場合、公式の Elasticsearch クライアント、またはRails 統合ライブラリを使用できます。Elasticsearch とクライアントの最新の安定バージョンに移行することをお勧めします。elasticsearch-rails gem バージョン8.0.0 Rails 6.1 、 7.0 、 7.1 、および Elasticsearch 8.xをサポートします。

コード

この例では、 tarball から OpenSearch をインストールする手順に従いました。tarball をダウンロードして解凍した後、後でクライアントをインスタンス化するために使用する初期管理者パスワードを設定する必要がありました。

次のようなGemfileを持つディレクトリを作成しました:

source 'https://rubygems.org' gem 'opensearch-ruby'

bundle installを実行すると、プロジェクトに gem がインストールされます。インストールされた opensearch-ruby バージョン3.4.0と、実行している OpenSearch のバージョンは2.18.0です。同じディレクトリ内のexample_code.rbファイルにコードを記述しました。このファイルの初期コードは、OpenSearch クライアントのインスタンス化です。

require 'opensearch' client = OpenSearch::Client.new( host: 'https://localhost:9200', user: 'admin', password: ENV['OPENSEARCH_INITIAL_ADMIN_PASSWORD'], transport_options: { ssl: { verify: false } } )

テストを容易にするために、ユーザーガイドに従ってトランスポートオプションssl: { verify: false}パラメータが渡されます。本番環境では、OpenSearch の展開に応じてこれを設定する必要があります。

OpenSearch バージョン 2.12.0 以降では、インストールスクリプトを実行するときに、 OPENSEARCH_INITIAL_ADMIN_PASSWORD環境変数を強力なパスワードに設定する必要があります。tarball から OpenSearch をインストールする手順に従って、コンソールで変数をエクスポートし、Ruby スクリプトで使用できるようになりました。

クライアントが OpenSearch に接続していることを確認するための簡単な API は、 cluster.health API を使用しています。

puts 'HEALTH:' pp client.cluster.health

そして実際にそれは機能します:

$ be ruby example_code.rb HEALTH: {"cluster_name"=>"opensearch", "status"=>"yellow", "timed_out"=>false, "number_of_nodes"=>1, "number_of_data_nodes"=>1,

Elasticsearch Ruby クライアントのドキュメントにある一般的な例をいくつかテストしたところ、期待どおりに動作しました。

index = 'books' puts 'Creating index' response = client.indices.create(index: index) puts response # Creating index # {"acknowledged"=>true, "shards_acknowledged"=>true, "index"=>"books"} puts 'Indexing a document' document = { title: 'The Time Machine', author: 'H. G. Wells', year: 1895 } response = client.index(index: index, body: document, refresh: true) puts response # Indexing document # {"_index"=>"books", "_id"=>"esalT5MB4vnuJz5TtqOc", "_version"=>1, "result"=>"created", "forced_refresh"=>true, "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>0, "_primary_term"=>1} id = response['_id'] puts 'Getting document' response = client.get(index: index, id: id) puts response # Getting document # {"_index"=>"books", "_id"=>"esalT5MB4vnuJz5TtqOc", "_version"=>1, "_seq_no"=>0, "_primary_term"=>1, "found"=>true, "_source"=>{"title"= >"The Time Machine", "author"=>"H. G. Wells", "year"=>1895}} puts "Does an index exist?" puts client.indices.exists(index: 'imaginary_index') # Does an index exist? # false puts 'Processing Bulk request' body = [ { index: { _index: 'books', data: { name: 'Leviathan Wakes', author: 'James S.A. Corey', release_date: '2011-06-02', page_count: 561 } } }, { index: { _index: 'books', data: { name: 'Hyperion', author: 'Dan Simmons', release_date: '1989-05-26', page_count: 482 } } }, { index: { _index: 'books', data: { name: 'Dune', author: 'Frank Herbert', release_date: '1965-06-01', page_count: 604 } } }, { index: { _index: 'books', data: { name: 'Dune Messiah', author: 'Frank Herbert', release_date: '1969-10-15', page_count: 331 } } }, { index: { _index: 'books', data: { name: 'Children of Dune', author: 'Frank Herbert', release_date: '1976-04-21', page_count: 408 } } }, { index: { _index: 'books', data: { name: 'God Emperor of Dune', author: 'Frank Herbert', release_date: '1981-05-28', page_count: 454 } } }, { index: { _index: 'books', data: { name: 'Consider Phlebas', author: 'Iain M. Banks', release_date: '1987-04-23', page_count: 471 } } }, { index: { _index: 'books', data: { name: 'Pandora\'s Star', author: 'Peter F. Hamilton', release_date: '2004-03-02', page_count: 768 } } }, { index: { _index: 'books', data: { name: 'Revelation Space', author: 'Alastair Reynolds', release_date: '2000-03-15', page_count: 585 } } }, { index: { _index: 'books', data: { name: 'A Fire Upon the Deep', author: 'Vernor Vinge', release_date: '1992-06-01', page_count: 613 } } }, { index: { _index: 'books', data: { name: 'Ender\'s Game', author: 'Orson Scott Card', release_date: '1985-06-01', page_count: 324 } } }, { index: { _index: 'books', data: { name: '1984', author: 'George Orwell', release_date: '1985-06-01', page_count: 328 } } }, { index: { _index: 'books', data: { name: 'Fahrenheit 451', author: 'Ray Bradbury', release_date: '1953-10-15', page_count: 227 } } }, { index: { _index: 'books', data: { name: 'Brave New World', author: 'Aldous Huxley', release_date: '1932-06-01', page_count: 268 } } }, { index: { _index: 'books', data: { name: 'Foundation', author: 'Isaac Asimov', release_date: '1951-06-01', page_count: 224 } } }, { index: { _index: 'books', data: { name: 'The Giver', author: 'Lois Lowry', release_date: '1993-04-26', page_count: 208 } } }, { index: { _index: 'books', data: { name: 'Slaughterhouse-Five', author: 'Kurt Vonnegut', release_date: '1969-06-01', page_count: 275 } } }, { index: { _index: 'books', data: { name: 'The Hitchhiker\'s Guide to the Galaxy', author: 'Douglas Adams', release_date: '1979-10-12', page_count: 180 } } }, { index: { _index: 'books', data: { name: 'Snow Crash', author: 'Neal Stephenson', release_date: '1992-06-01', page_count: 470 } } }, { index: { _index: 'books', data: { name: 'Neuromancer', author: 'William Gibson', release_date: '1984-07-01', page_count: 271 } } }, { index: { _index: 'books', data: { name: 'The Handmaid\'s Tale', author: 'Margaret Atwood', release_date: '1985-06-01', page_count: 311 } } }, { index: { _index: 'books', data: { name: 'Starship Troopers', author: 'Robert A. Heinlein', release_date: '1959-12-01', page_count: 335 } } }, { index: { _index: 'books', data: { name: 'The Left Hand of Darkness', author: 'Ursula K. Le Guin', release_date: '1969-06-01', page_count: 304 } } }, { index: { _index: 'books', data: { name: 'The Moon is a Harsh Mistress', author: 'Robert A. Heinlein', release_date: '1966-04-01', page_count: 288 } } } ] puts client.bulk(body: body, refresh: true) # Processing Bulk request # {"took"=>38, "errors"=>false, "items"=>[{"index"=>{"_index"=>"books", "_id"=>" ... query = { query: { multi_match: { query: 'dune', fields: ['name'] } } } puts 'Search results' response = client.search(index: index, body: query) puts response # Search results # {"_index"=>"books", "_id"=>"oEawT5MBOXHuGXdEu5Wu", "_score"=>2.2886353, "_source"=>{"name"=>"Dune", "author"=>"Frank Herbert", "release_date"=>"1965-06-01", "page_count"=>604}} # {"_index"=>"books", "_id"=>"oUawT5MBOXHuGXdEu5Wu", "_score"=>1.8893257, "_source"=>{"name"=>"Dune Messiah", "author"=>"Frank Herbert", "release_date"=>"1969-10-15", "page_count"=>331}} # {"_index"=>"books", "_id"=>"okawT5MBOXHuGXdEu5Wu", "_score"=>1.6086557, "_source"=>{"name"=>"Children of Dune", "author"=>"Frank Herbert", "release_date"=>"1976-04-21", "page_count"=>408}} # {"_index"=>"books", "_id"=>"o0awT5MBOXHuGXdEu5Wu", "_score"=>1.40059, "_source"=>{"name"=>"God Emperor of Dune", "author"=>"Frank Herbert", "release_date"=>"1981-05-28", "page_count"=>454}} puts 'Updating document' document = { title: 'Walkaway', author: 'Cory Doctorow', release_date: '2017' } response = client.index(index: index, body: document, refresh: true) id = response['_id'] response = client.update(index: index, id: id, body: { doc: { release_date: '2017-04-26' } }) puts response # Updating document # {"_index"=>"books", "_id"=>"degnZJMBIGr4X0Yim55L", "_version"=>2, "result"=>"updated", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>26, "_primary_term"=>1} puts 'Retrieveing multiple documents' response = client.search(index: index, body: { query: { match_all: {} }, size: 3, stored_fields: '_id' }) ids = response['hits']['hits'] ids.map { |a| a.delete('_score') } response = client.mget(body: { docs: [{ _index: index, _id: ids }] }) puts response # Retrieveing multiple documents # {"docs"=>[{"_index"=>"books", "_id"=>"qeg2ZJMBIGr4X0YiiqD2", "_version"=>1, "_seq_no"=>0, "_primary_term"=>1, "found"=>true, "_source"=>{"title"=>"The Time Machine", "author"=>"H. G. Wells", "year"=>1895}}, {"_index"=>"books", "_id"=>"q-g2ZJMBIGr4X0Yii6Ah", "_version"=>1, "_seq_no"=>1, "_primary_term"=>1, "found"=>true, "_source"=>{"name"=>"Leviathan Wakes", "author"=>"James S.A. Corey", "release_date"=>"2011-06-02", "page_count"=>561}}, {"_index"=>"books", "_id"=>"rOg2ZJMBIGr4X0Yii6Ah", "_version"=>1, "_seq_no"=>2, "_primary_term"=>1, "found"=>true, "_source"=>{"name"=>"Hyperion", "author"=>"Dan Simmons", "release_date"=>"1989-05-26", "page_count"=>482}}]} puts "Count #{client.count(index: index)['count']}" puts 'Deleting by query' response = client.delete_by_query(index: index, body: { query: { match: { author: 'Robert A. Heinlein' } } }, refresh: true) puts response puts "Count #{client.count(index: index)['count']}" # Count 26 # Deleting by query # {"took"=>16, "timed_out"=>false, "total"=>2, "deleted"=>2, "batches"=>1, "version_conflicts"=>0, "noops"=>0, "retries"=>{"bulk"=>0, "search"=>0}, "throttled_millis"=>0, "requests_per_second"=>-1.0, "throttled_until_millis"=>0, "failures"=>[]} # Count 24 puts 'Deleting document' response = client.delete(index: index, id: id) puts response # Deleting document # {"_index"=>"books", "_id"=>"nEawT5MBOXHuGXdEu5WA", "_version"=>2, "result"=>"deleted", "_shards"=>{"total"=>2, "successful"=>1, "failed"=>0}, "_seq_no"=>25, "_primary_term"=>1} puts 'Deleting index' response = client.indices.delete(index: index) puts response # Deleting index # {"acknowledged"=>true}

RubyアプリをElasticsearchに移行する

最初のステップは、Gemfile にelasticsearch-rubyを追加することです。bundle installを実行すると、Elasticsearch Ruby クライアント gem がインストールされます。完全に移行する前にコードをテストしたい場合は、最初はopensearch-ruby gem をそこに残しておくことができます。

次の重要なステップは、クライアントのインスタンス化です。これは、Elasticsearch をどのように実行しているかによって異なります。これらの例に対して同様のアプローチを維持するために、「Elasticsearch をダウンロードしてローカルで実行する」の手順に従います。

bin/elasticsearchを実行すると、Elasticsearch は自動的に構成されたセキュリティ機能で起動します。必ず elastic ユーザーのパスワードをコピーしてください (ただし、 bin/elasticsearch-reset-password -u elasticを実行してリセットできます)。この例に従う場合は、OpenSearch と Elasticsearch は同じポートで実行されるため、Elasticsearch を起動する前に必ず OpenSearch を停止してください。

example_code.rbの始めで、OpenSearch クライアントのインスタンス化をコメントアウトし、Elasticsearch クライアントのインスタンス化を追加しました。

# require 'opensearch' # client = OpenSearch::Client.new( # host: 'https://localhost:9200', # user: 'admin', # password: ENV['OPENSEARCH_INITIAL_ADMIN_PASSWORD'] # transport_options: { ssl: { verify: false } } # ) require 'elasticsearch' client = Elasticsearch::Client.new( host: 'https://localhost:9200', user: ENV['ELASTICSEARCH_USER'], password: ENV['ELASTICSEARCH_PASSWORD'], transport_options: { ssl: { verify: false } } )

ご覧のとおり、このテストシナリオではコードはほぼ同じです。これは、Elasticsearch のデプロイメントと、Elasticsearch との接続および認証の方法によって異なります。セキュリティに関しては OpenSearch と同じことが当てはまります。SSL を検証しないオプションはテスト目的のみであり、本番環境では使用しないでください。

クライアントがセットアップされたら、 bundle exec ruby example_code.rbを使用してコードを再度実行します。そして、すべてがうまく機能します!

移行問題のデバッグ

アプリケーションが使用している API によっては、OpenSearch の API が異なる場合、Elasticsearch に対してコードを実行するとエラーが発生する可能性があります。REST API ドキュメントは、API の使用方法に関する詳細な情報を得るための重要なリファレンスです。使用している Elasticsearch のバージョンのドキュメントを必ず確認してください。Elasticsearch::API参照も参照できます。

Elasticsearch で発生する可能性のあるエラーには次のようなものがあります:

ArgumentError: Required argument '' missing - これはクライアントエラーであり、リクエストに必要なパラメータがない場合に発生します。
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... このエラーは Elasticsearch から発生し、クライアントコードが、使用されている API に対して Elasticsearch が認識しないパラメータを使用していることを意味します。

Elasticsearch クライアントは、サーバーから送信された詳細なエラーメッセージとともに、Elasticsearch からのエラーを発生させます。したがって、サポートされていないパラメータやエンドポイントの場合でも、エラーによって何が異なっているかが通知されるはずです。

まとめ

このサンプルコードで示したように、Ruby アプリを OpenSearch から Elasticsearch に移行することは、Ruby 側から見るとそれほど複雑ではありません。バージョン管理と、検索エンジン間で異なる可能性のある API に注意する必要があります。しかし、最も一般的なアクションでは、クライアントを移行する際の主な変更はインスタンス化にあります。その点ではどちらも似ていますが、ホストと資格情報の定義方法は、スタックの展開方法によって異なります。クライアントがセットアップされ、Elasticsearch に接続していることを確認したら、OpenSearch クライアントを Elasticsearch クライアントにシームレスに置き換えることができます。