Ruby - Elasticsearch Labs

Presentamos el ES|Generador de consultas QL para el cliente Ruby de Elasticsearch

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

Recientemente lanzamos elastic-esql, una joya Ruby publicada bajo la licencia Apache 2. Esta gema te permite construir el ES| de ElasticConsultas QL en Ruby idiomático, que luego puedes usar con el ES|API de consulta QL. ES|QL permite a los desarrolladores filtrar, transformar y analizar los datos almacenados en Elasticsearch mediante consultas. Emplea "tuberías" ( | ) para trabajar paso a paso con los datos. La gema emplea funciones Ruby en su lugar, que puedes encadenar al objeto original para crear consultas más complejas:

ESQL:

Rubí:

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

Instalación

La gema puede instalar desde RubyGems con:

gem install elastic-esql

O puede agregar al archivo de gemas de un proyecto:

gem 'elastic-esql'

Uso

Puedes construir una consulta completa de una vez o crear un objeto de consulta con un comando fuente como from o row y luego encadenar ES|QL métodos para construir sobre ella.

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

La gema traduce el código a ES|QL en el método to_s , así que devuelve el ES|Consulta QL cuando se imprime o se convierte en una cadena:

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

Puedes instanciar un objeto de consulta y mutar su estado inicial usando los equivalentes ! de cada función:

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"

La herramienta ofrece formas cómodas de encadenar pasos extra a un ES|Función QL, como enrich y sort. Una vez que llamas enrich a un objeto Elastic::ESQL , puedes encadenar on y with a él:

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

También puedes encadenar desc, asc, nulls_first y nulls_last a tu consulta tras 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'

También soporta cadenas personalizadas, por si quieres escribir el ES|Consulta QL tú mismo, o usa una función que aún no se agregó a la biblioteca. custom se unirán a las cadenas al final de la consulta. Los agregará a medida que se envían a la función, sin agregar ningún carácter de la tubería. Se combinarán con el resto de la consulta mediante un carácter espacio.

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

También puedes encadenar custom funciones:

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

Usando el ES|QL Query Builder con el cliente Ruby

Puedes usar el constructor de consultas directamente con elasticsearch-ruby y la API esql.query enviando el 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 })

También puedes usarlo con el ES|QL Helper del cliente Ruby de Elasticsearch, para saber más:

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

Como herramienta independiente

La gema está diseñada como una herramienta independiente para construir ES|QL consulta de forma idiomática. No tiene dependencias en tiempo de ejecución; puedes usarlo con el cliente oficial de Elasticsearch Ruby, o por separado.

La consulta generada puede usar con la API esql.query de cualquier forma que una aplicación interactúe con la API de Elasticsearch (Ruby o no). Una vez que una consulta se construye con elastic-esql, la cadena generada puede enviar a la API como el parámetro query en el cuerpo de la solicitud.

Anteriormente escribí sobre el uso de Elasticsearch con las herramientas Ruby populares. Esta gema puede usar con cualquiera de las herramientas Ruby populares para consultar Elasticsearch con ES|QL.

Conclusión

Esta biblioteca está en desarrollo activo y la API final aún no se completó. Actualmente está lanzado como un avance técnico. Si tienes algún comentario sobre la API actual o su uso general, no dudes en abrir un nuevo número. Por favor, consulta el README para saber más sobre el Ruby ES|Constructor de consultas QL.

Guion Ruby en Logstash

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

Logstash es una cadena de procesamiento de datos que ingiere datos de múltiples fuentes, los transforma y los envía a los destinos que elijas. Los plugins de filtro son clave para este proceso; Realizan operaciones específicas sobre tus datos a medida que avanzan en la pipeline.

Logstash incluye varios filtros integrados para tareas comunes como análisis sintáctico, enriquecimiento y modificación de datos. Pero a veces te encontrarás con escenarios que requieren una lógica personalizada que va más allá de lo que estos filtros estándar pueden ofrecer. Aquí es donde entra el plugin de filtro Ruby .

El plugin de filtro Ruby te permite ejecutar código Ruby personalizado directamente dentro de tu pipeline de Logstash. Cuando los filtros estándar no son suficientes, el filtro Ruby te permite manejar transformaciones complejas de datos, implementar lógica de negocio personalizada o integrarte con sistemas externos.

En este blog, exploraremos cómo usar los filtros Ruby, desde el uso básico hasta el avanzado.

¿Cuándo deberías usar el filtro Ruby?

Como arquitecto consultor de Elastic, a menudo veo a clientes que emplean Logstash para la cadena de procesamiento de datos, aunque hoy en día no es un motor de procesamiento de datos de última generación. A menudo tienen dificultades con las limitaciones de los filtros estándar cuando se trata de manipulación compleja de datos o lógica personalizada. En estos casos, el filtro Ruby puede ayudar a superar esos desafíos.

El filtro Ruby es útil cuando los filtros Logstash estándar no pueden cumplir tus requisitos específicos. Aquí tienes algunos casos de uso comunes:

Manipulación profunda de datos anidados: Modificar estructuras JSON complejas, arrays dentro de arrays o reestructurar dinámicamente los datos en función del contenido
Procesamiento avanzado de cadenas: Analizar y extraer datos estructurados de texto no estructurado
Implementación de lógica de negocio compleja: Crear transformaciones personalizadas que requieran lógica condicional, bucles o cálculos complejos

Uso básico

Empecemos con un ejemplo sencillo para entender cómo funciona el filtro Ruby.

Configuración del filtro Ruby

Cuando crees una pipeline de Logstash, deberías colocar el archivo de configuración en el directorio /etc/logstash/conf.d . Alternativamente, puedes usar -f opción para especificar la ruta al archivo de configuración cuando arranques Logstash manualmente, para que puedas experimentar fácilmente con tus pipelines.

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

El archivo de configuración debería tener una extensión .conf .

Para usar el filtro Ruby, define un filtro ruby en la sección de filtros de tu archivo de configuración de la tubería Logstash (*.conf). Aquí tienes un ejemplo básico:

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

Este filtro Ruby en línea define una instancia de filtro Ruby dentro de tu configuración de Logstash. El parámetro code proporciona el script Ruby en línea que Logstash ejecutará para cada evento procesado por este filtro. Dentro de ese script, hay una variable event disponible que representa el propio evento. El objeto evento contiene los datos originales enviados a Logstash y cualquier campo adicional creado durante las etapas de filtro de Logstash. Puedes acceder a esos campos a través de la API de eventos de Logstash como event.get() y event.set(). En este código de ejemplo, event.set('new_field', 'Hello from Ruby!') establecer un nuevo campo llamado new_field al valor de cadena Hello from Ruby!. Puedes agregar cualquier otro código en este bloque de code según lo necesites.

Ten en cuenta que este objeto event no es un objeto hash de Ruby habitual, aunque actúa como un contenedor de datos clave-valor. Consulta esta documentación oficial para saber más sobre la API de eventos.

Externalizar la escritura Ruby

Para transformaciones simples, el código Ruby en línea es cómodo. Pero, para lógica compleja o funciones reutilizables, se recomienda mover el código a un script Ruby externo. Esto mejora la mantenibilidad y mantiene limpia la configuración de tu pipeline de Logstash.

Primero, crea un script Ruby y almacénalo como my_ruby_script.rb. El script debe definir un método filter que procese el evento. Toma un objeto evento como argumento, que representa el evento actual que se está procesando. El método filter necesita devolver un serial de eventos para emitir. Para eliminar el evento, devuelvo un array vacío.

Por ejemplo, el siguiente script lee el campo message , calcula su longitud y almacena el resultado en un nuevo campo llamado 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

A continuación, configura la configuración del filtro Ruby para que haga referencia al script usando la opción path . Esto indica a Logstash que cargue y ejecute el script externo. Al usar scripts externos, cerciórate de que el archivo existe y tiene las licencias correctas.

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

Ahora, cada evento se pasa al método filter en my_ruby_script.rb y es procesado por él.

Este enfoque te ayuda a gestionar la lógica compleja de forma más eficaz, facilitando probar, depurar y reutilizar tu código Ruby.

Uso avanzado

En esta sección, exploraremos algunos ejemplos avanzados de cómo usar el filtro Ruby en Logstash. Estos ejemplos demostrarán cómo realizar transformaciones de datos, enriquecer eventos e implementar lógica personalizada usando Ruby.

Manipulación de estructuras de datos anidadas

Un evento Logstash es la estructura de datos central que procesa Logstash. Puede contener varios campos, incluyendo estructuras de datos anidadas como arrays y hashes. El filtro Ruby te permite manipular fácilmente estas estructuras anidadas.

El filtro Ruby puede manejar estructuras de datos anidadas, como hashes y arrays, permitiéndote modificar o agregar campos dentro de estas estructuras. Esto es útil cuando se trata de formatos de datos complejos 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 ejemplo incluye un objeto JSON anidado en los datos de entrada. El filtro Ruby modifica los datos anidados agregando un nuevo par clave-valor. Este tipo de manipulación para datos anidados no es posible con los filtros Logstash estándar, lo que convierte al filtro Ruby en una opción útil para estructuras de datos complejas.

Dividir un solo evento en varios eventos

Los filtros Ruby también pueden usar para dividir un solo evento en varios eventos. Esto es útil cuando tienes un solo evento que contiene un array de objetos y quieres crear eventos separados para cada uno.

Ten en cuenta que ni la tubería de ingesta de Elasticsearch ni los procesadores de Beats/Elastic Agent soportan eventos de división. Este es uno de los casos de uso más estables de Logstash.

Con filtro dividido

Puedes usar el filtro split para dividir un evento en varios eventos según un campo especificado. Sin embargo, si necesitas realizar transformaciones adicionales o lógica durante la división, puedes usar el filtro Ruby en combinación con el filtro dividido.

En el siguiente ejemplo, tenemos un feed RSS como una sola línea de texto XML. Contiene múltiples elementos . El filtro Ruby se emplea para extraer los elementos del XML y almacenarlos en un nuevo campo llamado items. El filtro dividido se emplea entonces para dividir el evento en varios eventos según el 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 } }

Esto dará la siguiente manera:

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

Como notaste, el filtro ruby no es esencial en este caso. El filtro split puede usar para dividir el evento en varios eventos basados en el campo items , y el filtro mutate puede usar para eliminar campos innecesarios. Sin embargo, si necesitas realizar transformaciones o lógica adicional durante la división, puedes usar el filtro Ruby.

Emplea escritura Ruby en línea

También puedes usar un script Ruby en línea para dividir un solo evento en varios eventos usando el método event.clone y el new_event_block variable, como new_event_block.call(new_event). Esto te permite crear nuevos eventos basados en el evento original mientras se conservan sus datos.

Aquí tienes un ejemplo de cómo usar el filtro Ruby para dividir un solo evento en varios eventos. La entrada y salida son las mismas que en el ejemplo 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"] } }

Usa un script Ruby externo

También puedes usar un script externo de Ruby para dividir un solo evento en varios eventos.

Archivo de configuración:

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

El sistema Ruby debe externalizar 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

Recuerda, el método filter debe devolver un serial de eventos. Puedes devolver varios eventos clonando un objeto de evento entrante y agregándolos al array, o puedes devolver un solo evento como un array con un solo elemento.

return events # or # return [event]

Esto te permite dividir un solo evento en varios eventos.

Ejecuta comandos externos y analiza su salida

El plugin de entrada ejecutiva de Logstash permite ejecutar comandos externos y su salida será un evento de Logstash. La salida del comando se almacenará en el campo message del evento.

Normalmente, la salida de los comandos del sistema es legible por humanos, pero no está estructurada como JSON u otros formatos que Logstash pueda analizar fácilmente. Para gestionarlo, puedes usar el filtro Ruby para analizar la salida y extraer la información de ella.

Aquí tienes un ejemplo de cómo se emplea el plugin de entrada exec para ejecutar el comando ps -ef , que lista todos los procesos en ejecución en un sistema tipo Unix. La salida será analizada por el filtro Ruby para extraer información relevante sobre cada proceso.

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 ejemplo emplea el plugin de entrada exec para ejecutar el comando ps -ef cada 60 segundos. El filtro Ruby procesa la salida, extrayendo campos relevantes como UID, PID, PPID, uso de la CPU (C), hora de inicio (STIME), TTY, tiempo total de CPU (TIME) y el comando (CMD) ejecutado. Funciona bien en mi entorno macOS, pero puede que tengas que ajustar los patrones regex para que coincidan con el formato de salida del comando ps -ef en tu sistema.

Emplea librerías integradas

El plugin de filtro Ruby permite usar librerías Ruby integradas, que pueden ser muy útiles para diversas tareas. Por ejemplo, puedes usar la librería json para analizar cadenas JSON o la librería date para manipular fechas.

Aquí tienes un ejemplo de cómo usar la librería json para analizar una cadena JSON almacenada en un 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 tener que usar la librería cada vez, deberías externalizar tu código Ruby para poder usar la sentencia require al principio de tu script de filtro Ruby. Esto cargará la biblioteca una vez y la pondrá disponible para tu script.

Para comprobar qué librerías están disponibles en tu entorno, puedes listar las bibliotecas integradas ejecutando el siguiente código en el filtro Ruby:

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

Nota: Las bibliotecas integradas no son soportadas oficialmente por Logstash, y su comportamiento puede cambiar o puede que no estén disponibles en versiones futuras. Úsalos bajo tu propia responsabilidad.

Conclusión

El filtro Ruby de Logstash te permite personalizar y ampliar las capacidades de tus pipelines de Logstash. En esta publicación, cubrimos lo básico del uso del filtro Ruby y proporcionado ejemplos avanzados de uso.

Aprovechando el filtro Ruby, puedes manejar tareas complejas de procesamiento de datos que requieren lógica personalizada o manipulación avanzada. Ya sea que trabajes con estructuras de datos anidadas, divisiones de eventos o analizes y conviertas textos complejos/no estructurados en JSON estructurado, el filtro Ruby ofrece flexibilidad para satisfacer tus necesidades específicas.

Esperamos que esta guía te proporcionó el conocimiento e inspiración para explorar todo el potencial del filtro Ruby de Logstash. ¡Feliz guion!

Cómo migrar tu aplicación Ruby de OpenSearch a Elasticsearch

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

El cliente Ruby de OpenSearch fue bifurcado desde el cliente Ruby de Elasticsearch en la versión 7.x, por lo que las bases de código son relativamente similares. Esto significa que, al migrar una base de código Ruby de OpenSearch a Elasticsearch, el código de las respectivas bibliotecas cliente resultará muy familiar. En esta entrada del blog, voy a mostrar un ejemplo de aplicación Ruby que emplea OpenSearch y los pasos para migrar este código a Elasticsearch.

Ambos clientes están lanzados bajo la popular Apache License 2.0, por lo que son software de código abierto y libre. La licencia de Elasticsearch se actualizó recientemente y el núcleo de Elasticsearch y Kibana se publica bajo la licencia de código abierto aprobada por la OSI AGPL desde la versión 8.16.

Considerando la versión de Elasticsearch al migrar la aplicación Ruby

Una consideración al migrar es qué versión de Elasticsearch se va a emplear. Recomendamos usar la última versión estable, que en el momento de escribir esto es 8.17.0. Las versiones menores del cliente Rubí de Elasticsearch siguen a las versiones menores de Elasticsearch. Así que para Elasticsearch 8.17.x, puedes usar la versión 8.17.x de la gema Rubí.

OpenSearch se bifurcó a partir de Elasticsearch 7.10.2. Así que las APIs pueden cambiar y se podrían usar diferentes funciones en cualquiera de las dos. Pero eso está fuera del alcance de esta publicación, y solo voy a analizar las operaciones más comunes en una aplicación de ejemplo.

Para Ruby on Rails, puedes usar el cliente oficial de Elasticsearch o las bibliotecas de integración de Rails. Recomendamos migrar a la última versión estable de Elasticsearch y del cliente, respectivamente. La versión elasticsearch-rails gema 8.0.0 soportar Rails 6.1, 7.0 y 7.1 y Elasticsearch 8.x.

El código

Para este ejemplo, seguí los pasos para instalar OpenSearch desde un tarball. Luego de descargar y extraer el tarball, necesitaba establecer una contraseña inicial de administrador que usaré más adelante para instanciar el cliente.

Creé un directorio con una Gemfile que se ve así:

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

Luego de ejecutar bundle install, se instala la gema para mi proyecto. Esta versión de opensearch-ruby instalada 3.4.0 y la versión de OpenSearch que estoy usando es 2.18.0. Escribí el código en un archivo example_code.rb en el mismo directorio. El código inicial en este archivo es la instancia de un 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 } } )

La opción de transporte ssl: { verify: false} el parámetro se está pasando según la guía de usuario para facilitar las pruebas. En producción, esto debería configurar dependiendo del despliegue de OpenSearch.

Desde la versión 2.12.0 de OpenSearch, la variable de entorno OPENSEARCH_INITIAL_ADMIN_PASSWORD debe establecer con una contraseña fuerte al ejecutar el script de instalación. Siguiendo los pasos para instalar OpenSearch desde un tarball, exporté la variable en mi consola y ahora está disponible para mi script Ruby.

Una API sencilla para cerciorar de que el cliente se conecta a OpenSearch es usar la API cluster.health :

puts 'HEALTH:' pp client.cluster.health

Y efectivamente funciona:

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

Probé algunos de los ejemplos comunes que tenemos en la documentación del cliente Ruby de Elasticsearch, y funcionan como se espera:

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}

Migración de la aplicación Ruby a Elasticsearch

El primer paso es agregar elasticsearch-ruby en el archivo gema. Tras ejecutar bundle install, se instalará la gema cliente Ruby de Elasticsearch. Si quieres probar tu código antes de migrar completamente, puedes dejar la gema opensearch-ruby ahí inicialmente.

El siguiente paso importante será la instanciación del cliente. Esto va a depender de cómo ejecutes Elasticsearch. Para mantener un enfoque similar en estos ejemplos, sigo los pasos de Download Elasticsearch y lo ejecuto localmente.

Al ejecutar bin/elasticsearch, Elasticsearch se iniciará con las funciones de seguridad configuradas automáticamente. Cerciórate de copiar la contraseña del usuario elástico (pero puedes restablecerla ejecutando bin/elasticsearch-reset-password -u elastic). Si sigues este ejemplo, cerciórate de detener OpenSearch antes de iniciar Elasticsearch, ya que se ejecutan en el mismo puerto.

Al principio de example_code.rb, comenté la instancia del cliente OpenSearch y agregué la instancia para un 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 puedes ver, el código es casi idéntico en este escenario de pruebas. Variará según el despliegue de Elasticsearch y cómo decidas conectarte y autenticarte con él. Lo mismo aplica aquí que en OpenSearch en cuanto a seguridad, la opción de no verificar SSL es solo para fines de prueba y no debe usar en producción.

Una vez configurado el cliente, vuelvo a ejecutar el código con: bundle exec ruby example_code.rb. ¡Y todo simplemente funciona!

Problemas de depuración de migración

Dependiendo de las APIs que use tu aplicación, existe la posibilidad de que recibas un error al ejecutar tu código contra Elasticsearch si las APIs de OpenSearch divergen. La documentación de las APIs REST es una referencia esencial para obtener información detallada sobre cómo emplear las APIs. Cerciórate de consultar la documentación de la versión de Elasticsearch que estás usando. También puedes consultar la Elasticsearch::API referencia.

Algunos errores que puedes encontrar en Elasticsearch podrían ser:

ArgumentError: Required argument '' missing - Esto es un error de cliente y se generará cuando una solicitud tenga un parámetro requerido.
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Este error proviene de Elasticsearch y significa que el código del cliente está usando un parámetro que Elasticsearch no reconoce para la API que se está empleando.

El cliente de Elasticsearch generará errores de Elasticsearch con el mensaje de error detallado enviado por el servidor. Así que, para parámetros o endpoints no soportados, el error debería informarte qué es diferente.

Conclusión

Como demostramos con este código de ejemplo, la migración de una aplicación Ruby de OpenSearch a Elasticsearch no es demasiado compleja desde el punto de vista de Ruby. Debes estar atento al versionado y a cualquier posible divergencia de APIs entre los motores de búsqueda. Pero para las acciones más comunes, el principal cambio al migrar clientes está en la instancia. Ambos son similares en ese aspecto, pero la forma en que se definen el host y las credenciales varía en función de cómo se despliega la pila. Una vez que el cliente está configurado y verifica que se conecta a Elasticsearch, puedes reemplazar el cliente OpenSearch sin problemas por el cliente Elasticsearch.