Fernando Briano - 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.

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.