如何将你的 Ruby 应用程序从 OpenSearch 迁移到 Elasticsearch

作者：来自 Elastic Fernando Briano

将 Ruby 代码库从 OpenSearch 客户端迁移到 Elasticsearch 客户端的指南。

OpenSearch Ruby 客户端是从 7.x 版 Elasticsearch Ruby 客户端分叉而来的，因此代码库相对相似。这意味着当将 Ruby 代码库从 OpenSearch 迁移到 Elasticsearch 时，来自相应客户端库的代码看起来会非常熟悉。在这篇博文中，我将展示一个使用 OpenSearch 的示例 Ruby 应用程序以及将此代码迁移到 Elasticsearch 的步骤。

这两个客户端都是根据流行的 Apache 许可证 2.0 发布的，因此它们是开源和免费软件。Elasticsearch 的许可证最近进行了更新，Elasticsearch 和 Kibana 的核心自 8.16 版起根据 OSI 批准的开源许可证 AGPL 发布。

版本

迁移时需要考虑的一个问题是要使用哪个版本的 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}

迁移到 Elasticsearch

第一步是在 Gemfile 中添加 elasticsearch-ruby。运行 bundle install 后，将安装 Elasticsearch Ruby 客户端 gem。如果你想在完全迁移之前测试你的代码，你可以先将 opensearch-ruby gem 保留在那里。

下一个重要步骤是客户端实例化。这将取决于你如何运行 Elasticsearch。为了保持这些示例的类似方法，我按照下载 Elasticsearch 并在本地运行它中的步骤进行操作。

运行 bin/elasticsearch 时，Elasticsearch 将启动并自动配置安全功能。请确保复制 elastic 用户的密码（但你可以通过运行 bin/elasticsearch-reset-password -u elastic 来重置它）。如果你按照此示例操作，请确保在启动 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 的部署以及你决定如何连接和验证它而有所不同。这里与 OpenSearch 中的安全性相同，不验证 SSL 的选项仅用于测试目的，不应在生产中使用。

设置客户端后，我使用以下命令再次运行代码：bundle exec ruby example_code.rb。一切正常！

调试

根据你的应用程序使用的 API，如果 OpenSearch 的 API 不同，则在针对 Elasticsearch 运行代码时可能会收到错误。REST API 文档是有关如何使用 API 的详细信息的重要参考。请务必检查你正在使用的 Elasticsearch 版本的文档。你还可以参考 Elasticsearch::API 参考。

你可能遇到的一些 Elasticsearch 错误可能是：

ArgumentError: Required argument '<ARGUMENT>' missing - 这是一个客户端错误，当请求缺少必需参数时会引发此错误。
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... 此错误来自 Elasticsearch，这意味着客户端代码正在使用 Elasticsearch 无法识别的参数。

Elasticsearch 客户端将通过服务器发送的详细错误消息引发 Elasticsearch 错误。因此，即使对于不支持的参数或端点，错误也应该会告知你有什么不同。

结论

正如我们通过此示例代码所演示的那样，从 Ruby 的角度来看，将 Ruby 应用程序从 OpenSearch 迁移到 Elasticsearch 并不太复杂。你需要了解搜索引擎之间的版本控制和任何潜在的不同 API。但对于最常见的操作，迁移客户端时的主要变化是在实例化中。它们在这方面都很相似，但主机和凭据的定义方式因 Stack 的部署方式而异。设置客户端并验证它是否连接到 Elasticsearch 后，你可以用 Elasticsearch 客户端无缝替换 OpenSearch 客户端。

想要获得 Elastic 认证？了解下一次 Elasticsearch 工程师培训何时开始！

Elasticsearch 包含新功能，可帮助你为你的用例构建最佳搜索解决方案。深入了解我们的示例笔记本以了解更多信息，开始免费云试用，或立即在你的本地机器上试用 Elastic。

原文：https://www.elastic.co/search-labs/blog/ruby-opensearch-elasticsearch-migration