Ruby - Elasticsearch Labs

Apresentamos o construtor de consultas ES|QL para o cliente Ruby do Elasticsearch.

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

Recentemente lançamos elastic-esql, uma gem Ruby publicada sob a licença Apache 2. Esta gem permite que você crie consultas ES|QL da Elastic em Ruby idiomático, que você pode então usar com a API de consulta ES|QL. O ES|QL permite que os desenvolvedores filtrem, transformem e analisem dados armazenados no Elasticsearch por meio de consultas. Ele usa "pipes" ( | ) para trabalhar com os dados passo a passo. A gem usa funções Ruby, que você pode encadear ao objeto original para construir consultas mais complexas:

ESQL:

Rubi:

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

Instalação

A gem pode ser instalada a partir do RubyGems com o seguinte comando:

gem install elastic-esql

Ou pode ser adicionado ao Gemfile de um projeto:

gem 'elastic-esql'

Uso

Você pode construir uma consulta completa de uma só vez ou criar um objeto de consulta com um comando de origem como from ou row e, em seguida, encadear métodos ES|QL para construí-lo.

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

A gem traduz o código para ES|QL no método to_s , portanto, retorna a consulta ES|QL quando é impressa ou convertida em uma String:

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

Você pode instanciar um objeto de consulta e modificar seu estado inicial usando os equivalentes ! de cada função:

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"

A ferramenta fornece maneiras convenientes de encadear etapas extras a uma função ES|QL, como enrich e sort. Depois de chamar enrich em um objeto Elastic::ESQL , você pode encadear on e with a ele:

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

Você também pode encadear desc, asc, nulls_first e nulls_last à sua consulta após usar sort:

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'

Também oferece suporte a strings personalizadas, caso você queira escrever a consulta ES|QL por conta própria ou usar um recurso que ainda não foi adicionado à biblioteca. custom irá unir as strings no final da consulta. Isso os adicionará conforme forem enviados para a função, sem adicionar nenhum caractere de barra vertical. Eles serão combinados ao restante da consulta por um caractere de espaço.

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

Você também pode encadear funções custom :

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

Utilizando o Construtor de Consultas ES|QL com o cliente Ruby

Você pode usar o construtor de consultas diretamente com elasticsearch-ruby e a API esql.query enviando o objeto de consulta:

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 })

Você também pode usá-lo com o auxiliar ES|QL do cliente Ruby do Elasticsearch. Saiba mais:

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

Como uma ferramenta independente

A gem foi projetada como uma ferramenta independente para construir consultas ES|QL de forma idiomática. Não possui dependências de tempo de execução; você pode usá-lo com o cliente oficial do Elasticsearch para Ruby ou de forma independente.

A consulta gerada pode ser usada com a API esql.query de qualquer forma que um aplicativo interaja com a API do Elasticsearch (Ruby ou não). Uma vez que uma consulta é construída com elastic-esql, a String gerada pode ser enviada para a API como o parâmetro query no corpo da solicitação.

Anteriormente, escrevi sobre como usar o Elasticsearch com ferramentas populares do Ruby. Esta gem pode ser usada com qualquer uma das ferramentas populares do Ruby para consultar o Elasticsearch com ES|QL.

Conclusão

Esta biblioteca está em desenvolvimento ativo e a API final ainda não foi concluída. Atualmente, está disponível em versão de pré-visualização técnica. Se você tiver algum comentário sobre a API atual ou sobre o uso em geral, não hesite em abrir uma nova solicitação. Consulte o arquivo README para saber mais sobre o construtor de consultas Ruby ES|QL.

Scripting em Ruby no Logstash

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

O Logstash é um pipeline de processamento de dados que ingere dados de múltiplas fontes, os transforma e os envia para os destinos escolhidos. Os plugins de filtro são essenciais para esse processo; eles executam operações específicas nos seus dados à medida que estes percorrem o pipeline.

O Logstash inclui diversos filtros integrados para tarefas comuns, como analisar, enriquecer e modificar dados. Mas, às vezes, você encontrará cenários que exigem lógica personalizada que vai além do que esses filtros padrão podem fornecer. É aí que entra o plugin de filtro Ruby .

O plugin de filtro Ruby permite executar código Ruby personalizado diretamente no seu pipeline Logstash. Quando os filtros padrão não são suficientes, o filtro Ruby permite lidar com transformações de dados complexas, implementar lógica de negócios personalizada ou integrar-se a sistemas externos.

Neste blog, vamos explorar como usar filtros em Ruby, desde o uso básico até o avançado.

Quando você deve usar o filtro Ruby?

Como arquiteto consultor da Elastic, vejo frequentemente clientes usando o Logstash para o pipeline de processamento de dados, embora atualmente ele não seja um mecanismo de processamento de dados de última geração. Eles frequentemente enfrentam dificuldades com as limitações dos filtros padrão quando se trata de manipulação complexa de dados ou lógica personalizada. Nesses casos, o filtro Ruby pode ajudar a superar esses desafios.

O filtro Ruby é útil quando os filtros padrão do Logstash não atendem às suas necessidades específicas. Aqui estão alguns casos de uso comuns:

Manipulação de dados aninhados em profundidade: Modifique estruturas JSON complexas, arrays dentro de arrays ou reestruture dados dinamicamente com base no conteúdo.
Processamento avançado de strings: Analise e extraia dados estruturados de textos não estruturados.
Implementação de lógica de negócios complexa: Crie transformações personalizadas que exigem lógica condicional, loops ou cálculos complexos.

Uso básico

Vamos começar com um exemplo simples para entender como funciona o filtro Ruby.

Configurando o filtro Ruby

Ao criar um pipeline Logstash, você deve colocar o arquivo de configuração no diretório /etc/logstash/conf.d . Alternativamente, você pode usar a opção -f para especificar o caminho para o arquivo de configuração ao iniciar o Logstash manualmente, para que você possa experimentar seus pipelines facilmente.

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

O arquivo de configuração deve ter a extensão .conf .

Para usar o filtro Ruby, defina um filtro ruby na seção de filtro do seu arquivo de configuração do pipeline Logstash (*.conf). Eis um exemplo básico:

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

Este filtro Ruby embutido define uma instância de filtro Ruby dentro da sua configuração do Logstash. O parâmetro code fornece o script Ruby embutido que o Logstash executará para cada evento processado por este filtro. Dentro desse script, há uma variável event disponível que representa o próprio evento. O objeto de evento contém os dados originais enviados ao Logstash e quaisquer campos adicionais criados durante os estágios de filtragem do Logstash. Você pode acessar esses campos por meio da API de Eventos do Logstash, como event.get() e event.set(). Neste exemplo de código, event.set('new_field', 'Hello from Ruby!') definiu um novo campo chamado new_field com o valor da string Hello from Ruby!. Você pode adicionar qualquer outro código neste bloco code conforme necessário.

Note que este objeto event não é um objeto hash comum do Ruby, embora funcione como um contêiner de dados do tipo chave-valor. Consulte esta documentação oficial para saber mais sobre a API de Eventos.

Externalizar script Ruby

Para transformações simples, o código Ruby embutido é conveniente. Porém, para lógica complexa ou funções reutilizáveis, recomenda-se mover o código para um script Ruby externo. Isso melhora a capacidade de manutenção e mantém a configuração do seu pipeline Logstash organizada.

Primeiro, crie um script Ruby e salve-o como my_ruby_script.rb. O script deve definir um método filter que processa o evento. Ela recebe um objeto de evento como argumento, que representa o evento atual que está sendo processado. O método filter precisa retornar uma matriz de eventos para emitir. Para descartar o evento, retorne um array vazio.

Por exemplo, o seguinte script lê o campo message , calcula seu comprimento e armazena o resultado em um novo campo chamado 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

Em seguida, defina a configuração do filtro Ruby para referenciar o script usando a opção path . Isso instrui o Logstash a carregar e executar o script externo. Ao usar scripts externos, certifique-se de que o arquivo existe e possui as permissões corretas.

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

Agora, cada evento é passado para o método filter em my_ruby_script.rb e é processado por ele.

Essa abordagem ajuda você a gerenciar lógicas complexas com mais eficiência, facilitando o teste, a depuração e a reutilização do seu código Ruby.

Uso avançado

Nesta seção, exploraremos alguns exemplos avançados de uso do filtro Ruby no Logstash. Estes exemplos demonstrarão como realizar transformações de dados, enriquecer eventos e implementar lógica personalizada usando Ruby.

Manipulando estruturas de dados aninhadas

Um evento do Logstash é a estrutura de dados principal que o Logstash processa. Pode conter diversos campos, incluindo estruturas de dados aninhadas, como arrays e hashes. O filtro Ruby permite manipular essas estruturas aninhadas com facilidade.

O filtro Ruby consegue lidar com estruturas de dados aninhadas, como hashes e arrays, permitindo que você modifique ou adicione campos dentro dessas estruturas. Isso é útil ao lidar com formatos de dados complexos como 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 } }

Este exemplo inclui um objeto JSON aninhado nos dados de entrada. O filtro Ruby modifica os dados aninhados adicionando um novo par chave-valor. Esse tipo de manipulação de dados aninhados não é possível com os filtros padrão do Logstash, o que torna o filtro Ruby uma opção prática para estruturas de dados complexas.

Dividir um único evento em vários eventos.

Os filtros Ruby também podem ser usados para dividir um único evento em vários eventos. Isso é útil quando você tem um único evento contendo uma matriz de itens e deseja criar eventos separados para cada item.

Note que nem o pipeline de ingestão do Elasticsearch nem os processadores do Beats/Elastic Agent suportam a divisão de eventos. Este é um dos casos de uso mais fortes para o Logstash.

Com filtro dividido

Você pode usar o filtro split para dividir um evento em vários eventos com base em um campo especificado. No entanto, se precisar realizar transformações ou lógicas adicionais durante a divisão, você pode usar o filtro Ruby em combinação com o filtro de divisão.

No exemplo a seguir, temos um feed RSS como uma única linha de texto XML. Contém múltiplos elementos . O filtro Ruby é usado para extrair os elementos do XML e armazená-los em um novo campo chamado items. O filtro de divisão é então usado para dividir o evento em vários eventos com base no campo 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 } }

Isso resultará no seguinte:

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

Como você deve ter percebido, o filtro ruby não é essencial neste caso. O filtro split pode ser usado para dividir o evento em vários eventos com base no campo items e o filtro mutate pode ser usado para remover campos desnecessários. No entanto, se você precisar realizar transformações ou lógicas adicionais durante a divisão, poderá usar o filtro Ruby.

Use script Ruby embutido

Você também pode usar um script Ruby embutido para dividir um único evento em vários eventos usando o método event.clone e o new_event_block variable, como new_event_block.call(new_event). Isso permite criar novos eventos com base no evento original, preservando seus dados.

Aqui está um exemplo de como usar o filtro Ruby para dividir um único evento em vários eventos. A entrada e a saída são as mesmas do exemplo anterior.

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"] } }

Utilizar script Ruby externo

Você também pode usar um script Ruby externo para dividir um único evento em vários eventos.

Arquivo de configuração:

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"] } }

O script Ruby precisa ser externalizado como 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

Lembre-se, o método filter deve retornar uma matriz de eventos. Você pode retornar vários eventos clonando um objeto de evento recebido e adicionando-os à matriz, ou pode retornar um único evento como uma matriz com um único elemento.

return events # or # return [event]

Isso permite dividir um único evento em vários eventos.

Executar comandos externos e analisar seus resultados.

O plugin Logstash exec input permite executar comandos externos, e a saída desses comandos será um evento do Logstash. O resultado do comando será armazenado no campo message do evento.

Normalmente, a saída dos comandos do sistema é legível para humanos, mas não está estruturada em JSON ou outros formatos que o Logstash possa analisar facilmente. Para lidar com isso, você pode usar o filtro Ruby para analisar a saída e extrair as informações dela.

Aqui está um exemplo de uso do plugin de entrada exec para executar o comando ps -ef , que lista todos os processos em execução em um sistema do tipo Unix. A saída será analisada pelo filtro Ruby para extrair informações relevantes sobre cada processo.

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 } }

Este exemplo usa o plugin de entrada exec para executar o comando ps -ef a cada 60 segundos. O filtro Ruby processa a saída, extraindo campos relevantes como UID, PID, PPID, uso da CPU (C), hora de início (STIME), TTY, tempo total da CPU (TIME) e o comando (CMD) executado. Funciona bem no meu ambiente macOS, mas você pode precisar ajustar os padrões regex para corresponder ao formato de saída do comando ps -ef no seu sistema.

Utilize bibliotecas integradas

O plugin de filtro Ruby permite usar bibliotecas Ruby integradas, o que pode ser muito útil para diversas tarefas. Por exemplo, você pode usar a biblioteca json para analisar strings JSON ou a biblioteca date para manipular datas.

Aqui está um exemplo de como usar a biblioteca json para analisar uma string JSON armazenada em um campo:

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

Para evitar exigir a biblioteca sempre, você deve externalizar seu código Ruby para que possa usar a instrução require no início do seu script de filtro Ruby. Isso carregará a biblioteca uma única vez e a tornará disponível para uso em seu script.

Para verificar quais bibliotecas estão disponíveis em seu ambiente, você pode listar as bibliotecas integradas executando o seguinte código no filtro Ruby:

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

Observação: as bibliotecas integradas não são oficialmente suportadas pelo Logstash e seu comportamento pode mudar ou elas podem não estar disponíveis em versões futuras. Use-os por sua conta e risco.

Conclusão

O filtro Logstash Ruby permite personalizar e ampliar as funcionalidades dos seus pipelines Logstash. Neste post, abordamos os conceitos básicos do uso do filtro Ruby e fornecemos exemplos de uso avançado.

Ao utilizar o filtro Ruby, você pode lidar com tarefas complexas de processamento de dados que exigem lógica personalizada ou manipulação avançada. Seja trabalhando com estruturas de dados aninhadas, dividindo eventos ou analisando e convertendo texto complexo/não estruturado em JSON estruturado, o filtro Ruby oferece a flexibilidade necessária para atender às suas necessidades específicas.

Esperamos que este guia tenha lhe fornecido o conhecimento e a inspiração necessários para explorar todo o potencial do filtro Logstash Ruby. Boa programação!

Como migrar seu aplicativo Ruby do OpenSearch para o Elasticsearch

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

O cliente Ruby do OpenSearch foi derivado do cliente Ruby do Elasticsearch na versão 7.x, portanto, as bases de código são relativamente semelhantes. Isso significa que, ao migrar um código-fonte Ruby do OpenSearch para o Elasticsearch, o código das respectivas bibliotecas de cliente parecerá muito familiar. Neste post do blog, vou mostrar um exemplo de aplicativo Ruby que usa o OpenSearch e os passos para migrar esse código para o Elasticsearch.

Ambos os clientes são distribuídos sob a popular Licença Apache 2.0, sendo, portanto, software livre e de código aberto. A licença do Elasticsearch foi atualizada recentemente e o núcleo do Elasticsearch e do Kibana são publicados sob a licença de código aberto AGPL, aprovada pela OSI, desde a versão 8.16.

Considerando a versão do Elasticsearch ao migrar um aplicativo Ruby.

Um aspecto a considerar na migração é qual versão do Elasticsearch será utilizada. Recomendamos usar a versão estável mais recente, que no momento em que este texto foi escrito é 8.17.0. As versões secundárias do cliente Ruby do Elasticsearch seguem as versões secundárias do Elasticsearch. Então, para o Elasticsearch 8.17.x, você pode usar a versão 8.17.x da gem Ruby.

O OpenSearch foi derivado do Elasticsearch 7.10.2. Assim, as APIs podem ter mudado e recursos diferentes podem ser usados em qualquer uma delas. Mas isso está fora do escopo desta postagem, e vou analisar apenas as operações mais comuns em um aplicativo de exemplo.

Para Ruby on Rails, você pode usar o cliente oficial do Elasticsearch ou as bibliotecas de integração do Rails. Recomendamos a migração para a versão estável mais recente do Elasticsearch e do cliente, respectivamente. A versão elasticsearch-rails da gem 8.0.0 suporta Rails 6.1, 7.0 e 7.1 e Elasticsearch 8.x.

O código

Neste exemplo, segui os passos para instalar o OpenSearch a partir de um arquivo tar. Após baixar e extrair o arquivo tar, precisei definir uma senha de administrador inicial, que usarei posteriormente para instanciar o cliente.

Criei um diretório com um Gemfile que se parece com isto:

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

Após executar bundle install, a gem é instalada para o meu projeto. Esta versão do opensearch-ruby instalada é 3.4.0 e a versão do OpenSearch que estou executando é 2.18.0. Eu escrevi o código em um arquivo example_code.rb no mesmo diretório. O código inicial neste arquivo é a instanciação de um cliente OpenSearch:

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

O parâmetro de opção de transporte ssl: { verify: false} está sendo passado conforme o guia do usuário para facilitar os testes. Em produção, isso deve ser configurado dependendo da implantação do OpenSearch.

A partir da versão 2.12.0 do OpenSearch, a variável de ambiente OPENSEARCH_INITIAL_ADMIN_PASSWORD deve ser definida com uma senha forte ao executar o script de instalação. Seguindo os passos para instalar o OpenSearch a partir de um arquivo tar.gz, exportei a variável no meu console e agora ela está disponível para o meu script Ruby.

Uma API simples para garantir que o cliente esteja se conectando ao OpenSearch é usar a API cluster.health :

puts 'HEALTH:' pp client.cluster.health

E de fato funciona:

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

Testei alguns dos exemplos comuns que temos na documentação do cliente Ruby do Elasticsearch e eles funcionaram conforme o esperado:

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}

Migrando um aplicativo Ruby para o Elasticsearch

O primeiro passo é adicionar elasticsearch-ruby no Gemfile. Após executar bundle install, a gem do cliente Ruby do Elasticsearch será instalada. Se você quiser testar seu código antes de migrar completamente, você pode inicialmente deixar a gem opensearch-ruby lá.

O próximo passo importante será a instanciação do cliente. Isso vai depender de como você está executando o Elasticsearch. Para manter uma abordagem semelhante nestes exemplos, estou seguindo os passos descritos em "Baixar o Elasticsearch e executá-lo localmente".

Ao executar bin/elasticsearch, o Elasticsearch será iniciado com recursos de segurança configurados automaticamente. Certifique-se de copiar a senha do usuário elastic (mas você pode redefini-la executando bin/elasticsearch-reset-password -u elastic). Se você estiver seguindo este exemplo, certifique-se de parar o OpenSearch antes de iniciar o Elasticsearch, pois ambos são executados na mesma porta.

No início de example_code.rb, comentei a instanciação do cliente OpenSearch e adicionei a instanciação para um cliente 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 } } )

Como você pode ver, o código é quase idêntico neste cenário de teste. Isso varia de acordo com a implementação do Elasticsearch e a forma como você decide se conectar e autenticar com ele. O mesmo se aplica aqui ao OpenSearch em relação à segurança: a opção de não verificar o SSL destina-se apenas a fins de teste e não deve ser usada em produção.

Depois que o cliente estiver configurado, eu executo o código novamente com: bundle exec ruby example_code.rb. E tudo simplesmente funciona!

Depurando problemas de migração

Dependendo das APIs que seu aplicativo utiliza, existe a possibilidade de você receber um erro ao executar seu código no Elasticsearch se as APIs do OpenSearch divergirem. A documentação das APIs REST é uma referência essencial para informações detalhadas sobre como usar as APIs. Certifique-se de consultar a documentação da versão do Elasticsearch que você está usando. Você também pode consultar a referência Elasticsearch::API .

Alguns erros que você pode encontrar no Elasticsearch podem ser:

ArgumentError: Required argument '' missing - Este é um erro do cliente e será gerado quando uma solicitação não contiver um parâmetro obrigatório.
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Esse erro vem do Elasticsearch e significa que o código do cliente está usando um parâmetro que o Elasticsearch não reconhece para a API que está sendo usada.

O cliente Elasticsearch irá gerar erros do Elasticsearch com a mensagem de erro detalhada enviada pelo servidor. Assim, mesmo para parâmetros ou endpoints não suportados, o erro deve informar qual é a diferença.

Conclusão

Como demonstramos com este exemplo de código, a migração de um aplicativo Ruby do OpenSearch para o Elasticsearch não é muito complexa do ponto de vista do Ruby. É preciso estar ciente das diferenças de versão e de quaisquer APIs potencialmente divergentes entre os mecanismos de busca. Mas, para as ações mais comuns, a principal mudança na migração de clientes está na instanciação. Nesse aspecto, ambos são semelhantes, mas a forma como o host e as credenciais são definidos varia de acordo com a maneira como o Stack está sendo implantado. Após configurar o cliente e verificar se ele está se conectando ao Elasticsearch, você pode substituir o cliente OpenSearch pelo cliente Elasticsearch sem problemas.