Fernando Briano - Elasticsearch Labs

Présentation du générateur de requêtes ES|QL pour le client Elasticsearch Ruby

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

Nous avons récemment publié elastic-esql, un outil Ruby publié sous licence Apache 2. Cette gemme vous permet de construire les requêtes ES|QL d'Elastic en Ruby idiomatique, que vous pouvez ensuite utiliser avec l'API de requête ES|QL. ES|QL permet aux développeurs de filtrer, de transformer et d'analyser les données stockées dans Elasticsearch au moyen de requêtes. Il utilise les tuyaux "" ( | ) pour travailler avec les données étape par étape. La gem utilise des fonctions Ruby à la place, que vous pouvez enchaîner à l'objet original pour construire des requêtes plus complexes :

ESQL :

Rubis :

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

Installation

La gemme peut être installée à partir de RubyGems avec :

gem install elastic-esql

Il peut également être ajouté au fichier Gemfile d'un projet :

gem 'elastic-esql'

Utilisation

Vous pouvez soit construire une requête complète en une seule fois, soit créer un objet de requête à l'aide d'une commande source telle que from ou row, puis enchaîner les méthodes ES|QL pour construire à partir de cet objet.

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

La gemme traduit le code en ES|QL dans la méthode to_s, de sorte qu'elle renvoie la requête ES|QL lorsqu'elle est imprimée ou transformée en chaîne :

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

Vous pouvez instancier un objet de requête et modifier son état initial en utilisant les équivalents ! de chaque fonction :

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"

L'outil offre des moyens pratiques d'enchaîner des étapes supplémentaires à une fonction ES|QL, comme enrich et sort. Une fois que vous avez appelé enrich sur un objet Elastic::ESQL, vous pouvez enchaîner on et with:

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

Vous pouvez également enchaîner desc, asc, nulls_first et nulls_last à votre requête après avoir utilisé 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'

Elle prend également en charge les chaînes personnalisées, au cas où vous souhaiteriez écrire vous-même la requête ES|QL ou utiliser une fonctionnalité qui n'a pas encore été ajoutée à la bibliothèque. custom joindra les chaînes à la fin de la requête. Il les ajoutera au fur et à mesure qu'ils sont envoyés à la fonction, sans ajouter de caractères de liaison. Ils seront combinés au reste de la requête par un caractère d'espacement.

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

Vous pouvez également enchaîner les fonctions de custom:

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

Utilisation du générateur de requêtes ES|QL avec le client Ruby

Vous pouvez utiliser le constructeur de requêtes directement avec elasticsearch-ruby et l'API esql.query en envoyant l'objet de requête :

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

Vous pouvez également l'utiliser avec l'ES|QL Helper du client Elasticsearch Ruby, pour en savoir plus :

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

En tant qu'outil autonome

La gemme est conçue comme un outil autonome pour construire des requêtes ES|QL de manière idiomatique. Il n'a aucune dépendance d'exécution ; vous pouvez l'utiliser avec le client Ruby officiel d'Elasticsearch, ou seul.

La requête générée peut être utilisée avec l'API esql.query de toutes les façons dont une application interagit avec l'API Elasticsearch (Ruby ou non). Une fois qu'une requête est construite avec elastic-esql, la chaîne générée peut être envoyée à l'API en tant que paramètre query dans le corps de la requête.

J'ai déjà écrit sur l'utilisation d'Elasticsearch avec des outils Ruby populaires. Cette gemme peut être utilisée avec n'importe quel outil Ruby populaire pour interroger Elasticsearch avec ES|QL.

Conclusion

Cette bibliothèque est en cours de développement et l'API finale n'a pas encore été finalisée. Il s'agit actuellement d'un aperçu technique. Si vous avez des commentaires sur l'API actuelle ou sur son utilisation générale, n'hésitez pas à ouvrir un nouveau dossier. Veuillez vous référer au README pour en savoir plus sur Ruby ES|QL Query Builder.

Comment migrer votre application Ruby d'OpenSearch vers Elasticsearch ?

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

Le client OpenSearch Ruby a été dérivé du client Elasticsearch Ruby dans la version 7.x, les bases de code sont donc relativement similaires. Cela signifie que lors de la migration d'un code Ruby d'OpenSearch vers Elasticsearch, le code des bibliothèques clientes respectives sera très familier. Dans ce billet, je vais montrer un exemple d'application Ruby qui utilise OpenSearch et les étapes pour migrer ce code vers Elasticsearch.

Les deux clients sont publiés sous la célèbre licence Apache 2.0, ce qui en fait des logiciels libres et gratuits. La licence d'Elasticsearch a été récemment mise à jour et le cœur d'Elasticsearch et de Kibana est publié sous la licence Open Source AGPL approuvée par l'OSI depuis la version 8.16.

Prise en compte de la version d'Elasticsearch lors de la migration d'une application Ruby

Lors de la migration, il convient de prendre en compte la version d'Elasticsearch qui sera utilisée. Nous recommandons d'utiliser la dernière version stable, qui, au moment de la rédaction de ce document, est 8.17.0. Les versions mineures du client Elasticsearch Ruby suivent les versions mineures d'Elasticsearch. Ainsi, pour Elasticsearch 8.17.x, vous pouvez utiliser la version 8.17.x de la gem Ruby.

OpenSearch a été dérivé d'Elasticsearch 7.10.2. Les API peuvent donc avoir changé et des fonctionnalités différentes peuvent être utilisées sur l'un ou l'autre. Mais cela n'entre pas dans le cadre de cet article, et je vais seulement examiner les opérations les plus courantes dans un exemple d'application.

Pour Ruby on Rails, vous pouvez utiliser le client Elasticsearch officiel ou les bibliothèques d'intégration Rails. Nous recommandons de migrer vers la dernière version stable d'Elasticsearch et du client respectivement. La version de la gem elasticsearch-rails 8.0.0 supporte Rails 6.1, 7.0 et 7.1 et Elasticsearch 8.x.

Le code

Pour cet exemple, j'ai suivi les étapes d'installation d'OpenSearch à partir d'une archive. Après avoir téléchargé et extrait l'archive, j'ai dû définir un mot de passe administrateur initial que j'utiliserai plus tard pour instancier le client.

J'ai créé un répertoire avec un Gemfile qui ressemble à ceci :

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

Après avoir lancé bundle install, la gem est installée pour mon projet. Ceci a installé la version 3.4.0 de opensearch-ruby et la version d'OpenSearch que j'utilise est 2.18.0. J'ai écrit le code dans un fichier example_code.rb dans le même répertoire. Le code initial de ce fichier est l'instanciation d'un client OpenSearch :

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

Le paramètre de l'option de transport ssl: { verify: false} est transmis conformément au guide de l'utilisateur afin de faciliter les tests. En production, cela doit être configuré en fonction du déploiement d'OpenSearch.

Depuis la version 2.12.0 d'OpenSearch, la variable d'environnement OPENSEARCH_INITIAL_ADMIN_PASSWORD doit être définie avec un mot de passe fort lors de l'exécution du script d'installation. En suivant les étapes d'installation d'OpenSearch à partir d'une archive, j'ai exporté la variable dans ma console et elle est maintenant disponible pour mon script Ruby.

Une API simple pour s'assurer que le client se connecte à OpenSearch consiste à utiliser l'API cluster.health:

puts 'HEALTH:' pp client.cluster.health

Et en effet, cela fonctionne :

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

J'ai testé certains des exemples courants que nous avons dans la documentation du client Elasticsearch Ruby, et ils fonctionnent comme prévu :

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}

Migration d'une application Ruby vers Elasticsearch

La première étape consiste à ajouter elasticsearch-ruby dans le fichier Gemfile. Après l'exécution de bundle install, le client Elasticsearch Ruby gem sera installé. Si vous souhaitez tester votre code avant de migrer complètement, vous pouvez initialement laisser la gem opensearch-ruby en place.

La prochaine étape importante sera l'instanciation du client. Cela va dépendre de la manière dont vous utilisez Elasticsearch. Afin de conserver une approche similaire pour ces exemples, je suivrai les étapes de la section Télécharger Elasticsearch et l'exécuter localement.

Lors de l'exécution de bin/elasticsearch, Elasticsearch démarre avec des fonctions de sécurité automatiquement configurées. Veillez à copier le mot de passe de l'utilisateur élastique (mais vous pouvez le réinitialiser en lançant bin/elasticsearch-reset-password -u elastic). Si vous suivez cet exemple, assurez-vous d'arrêter OpenSearch avant de démarrer Elasticsearch, car ils fonctionnent sur le même port.

Au début de example_code.rb, j'ai commenté l'instanciation du client OpenSearch et j'ai ajouté l'instanciation d'un client 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 } } )

Comme vous pouvez le constater, le code est presque identique dans ce scénario de test. Elle diffère en fonction du déploiement d'Elasticsearch et de la manière dont vous décidez de vous connecter et de vous authentifier. Il en va de même pour OpenSearch en ce qui concerne la sécurité, l'option de ne pas vérifier ssl ne sert qu'à des fins de test et ne doit pas être utilisée en production.

Une fois le client configuré, j'exécute à nouveau le code avec : bundle exec ruby example_code.rb. Et tout fonctionne !

Déboguer les problèmes de migration

En fonction des API que votre application utilise, il est possible que vous receviez une erreur lorsque vous exécutez votre code contre Elasticsearch si les API d'OpenSearch divergent. La documentation sur les API REST est une référence essentielle pour obtenir des informations détaillées sur l'utilisation des API. Veillez à consulter la documentation relative à la version d'Elasticsearch que vous utilisez. Vous pouvez également consulter la référence Elasticsearch::API.

Voici quelques exemples d'erreurs que vous pouvez rencontrer avec Elasticsearch :

ArgumentError: Required argument '' missing - Il s'agit d'une erreur du client qui se produit lorsqu'il manque un paramètre requis dans une demande.
Elastic::Transport::Transport::Errors::BadRequest: [400] {"error":{"root_cause":[{"type":"illegal_argument_exception","reason":"request [/example/_doc] contains unrecognized parameter: [test]"}]... Cette erreur provient d'Elasticsearch et signifie que le code client utilise un paramètre qu'Elasticsearch ne reconnaît pas pour l'API utilisée.

Le client Elasticsearch lèvera les erreurs d'Elasticsearch avec le message d'erreur détaillé envoyé par le serveur. Ainsi, pour les paramètres ou les points de terminaison non pris en charge, l'erreur devrait vous informer de ce qui est différent.

Conclusion

Comme nous l'avons démontré avec cet exemple de code, la migration d'une application Ruby d'OpenSearch vers Elasticsearch n'est pas trop complexe du côté de Ruby. Vous devez être conscient des versions et des éventuelles divergences entre les API des moteurs de recherche. Mais pour les actions les plus courantes, le principal changement lors de la migration des clients se situe au niveau de l'instanciation. Ils sont tous deux similaires à cet égard, mais la façon dont l'hôte et les informations d'identification sont définis varie en fonction de la manière dont la pile est déployée. Une fois que le client est configuré et que vous avez vérifié qu'il se connecte à Elasticsearch, vous pouvez remplacer le client OpenSearch par le client Elasticsearch.