Ruby - 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.

Scripting Ruby dans Logstash

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

Logstash est un pipeline de traitement de données qui ingère des données provenant de sources multiples, les transforme et les envoie vers les destinations de votre choix. Les plugins de filtrage sont essentiels pour ce processus ; ils effectuent des opérations spécifiques sur vos données lorsqu'elles passent par le pipeline.

Logstash comprend plusieurs filtres intégrés pour les tâches courantes telles que l'analyse, l'enrichissement et la modification des données. Mais parfois, vous rencontrerez des scénarios qui nécessiteront une logique personnalisée allant au-delà de ce que ces filtres standard peuvent fournir. C'est là qu'intervient le plugin Ruby filter.

Le plugin Ruby filter vous permet d'exécuter du code Ruby personnalisé directement dans votre pipeline Logstash. Lorsque les filtres standard ne suffisent pas, le filtre Ruby vous permet de gérer des transformations de données complexes, de mettre en œuvre une logique commerciale personnalisée ou d'intégrer des systèmes externes.

Dans ce blog, nous allons explorer comment utiliser les filtres Ruby, de l'utilisation basique à l'utilisation avancée.

Quand utiliser le filtre Ruby ?

En tant qu'architecte consultant d'Elastic, je vois souvent des clients utiliser Logstash pour le pipeline de traitement des données, même s'il ne s'agit pas aujourd'hui d'un moteur de traitement des données à la pointe de la technologie. Ils se heurtent souvent aux limites des filtres standard lorsqu'il s'agit de manipuler des données complexes ou d'appliquer une logique personnalisée. Dans ce cas, le filtre Ruby peut aider à surmonter ces difficultés.

Le filtre Ruby est utile lorsque les filtres standard de Logstash ne peuvent pas répondre à vos besoins spécifiques. Voici quelques cas d'utilisation courants :

Manipulation de données imbriquées en profondeur: Modifier des structures JSON complexes, des tableaux dans des tableaux, ou restructurer dynamiquement des données en fonction de leur contenu.
Traitement avancé des chaînes de caractères: Analyse et extraction de données structurées à partir de textes non structurés
Mise en œuvre d'une logique d'entreprise complexe: Créer des transformations personnalisées qui nécessitent une logique conditionnelle, des boucles ou des calculs complexes.

Utilisation de base

Commençons par un exemple simple pour comprendre le fonctionnement du filtre Ruby.

Configuration du filtre Ruby

Lorsque vous créez un pipeline Logstash, vous devez placer le fichier de configuration dans le répertoire /etc/logstash/conf.d. Alternativement, vous pouvez utiliser l'option -f pour spécifier le chemin vers le fichier de configuration lorsque vous démarrez Logstash manuellement, afin que vous puissiez expérimenter vos pipelines facilement.

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

Le fichier de configuration doit avoir une extension .conf.

Pour utiliser le filtre Ruby, définissez un filtre ruby dans la section filter de votre fichier de configuration du pipeline Logstash (*.conf). Voici un exemple de base :

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

Ce filtre Ruby en ligne définit une instance de filtre Ruby dans votre configuration Logstash. Le paramètre code fournit le script Ruby en ligne que Logstash exécutera pour chaque événement traité par ce filtre. Dans ce script, il existe une variable event qui représente l'événement lui-même. L'objet événement contient les données originales envoyées à Logstash et tous les champs supplémentaires créés lors des étapes de filtrage de Logstash. Vous pouvez accéder à ces champs via l'API Logstash Event telle que event.get() et event.set(). Dans cet exemple de code, event.set('new_field', 'Hello from Ruby!') attribue à un nouveau champ nommé new_field la valeur de chaîne Hello from Ruby!. Vous pouvez ajouter tout autre code dans ce bloc code si nécessaire.

Notez que cet objet event n'est pas un objet de hachage Ruby habituel, bien qu'il agisse comme un conteneur de données de type clé-valeur. Consultez la documentation officielle pour en savoir plus sur l'API des événements.

Externaliser le script Ruby

Pour les transformations simples, le code Ruby en ligne est pratique. Mais pour une logique complexe ou des fonctions réutilisables, il est recommandé de déplacer le code dans un script Ruby externe. Cela permet d'améliorer la maintenabilité et de conserver une configuration propre du pipeline Logstash.

Tout d'abord, créez un script Ruby et enregistrez-le sous my_ruby_script.rb. Le script doit définir une méthode filter qui traite l'événement. Elle prend en argument un objet événement qui représente l'événement en cours de traitement. La méthode filter doit renvoyer un tableau d'événements à émettre. Pour supprimer l'événement, renvoyer un tableau vide.

Par exemple, le script suivant lit la rubrique message, calcule sa longueur et stocke le résultat dans une nouvelle rubrique appelée 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

Ensuite, définissez la configuration du filtre Ruby pour qu'il fasse référence au script à l'aide de l'option path. Cela indique à Logstash de charger et d'exécuter le script externe. Lors de l'utilisation de scripts externes, assurez-vous que le fichier existe et que les autorisations sont correctes.

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

Maintenant, chaque événement est transmis à la méthode filter dans my_ruby_script.rb et est traité par elle.

Cette approche vous permet de gérer plus efficacement une logique complexe, ce qui facilite les tests, le débogage et la réutilisation de votre code Ruby.

Utilisation avancée

Dans cette section, nous allons explorer quelques exemples avancés d'utilisation du filtre Ruby dans Logstash. Ces exemples montrent comment effectuer des transformations de données, enrichir des événements et mettre en œuvre une logique personnalisée à l'aide de Ruby.

Manipulation de structures de données imbriquées

Un événement Logstash est la structure de données centrale que Logstash traite. Il peut contenir différents champs, y compris des structures de données imbriquées telles que des tableaux et des hachages. Le filtre Ruby permet de manipuler facilement ces structures imbriquées.

Le filtre Ruby peut gérer des structures de données imbriquées, telles que des hachages et des tableaux, ce qui permet de modifier ou d'ajouter des champs dans ces structures. Cette fonction est utile lorsqu'il s'agit de traiter des formats de données complexes tels que 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 } }

Cet exemple inclut un objet JSON imbriqué dans les données d'entrée. Le filtre Ruby modifie les données imbriquées en ajoutant une nouvelle paire clé-valeur. Ce type de manipulation des données imbriquées n'est pas possible avec les filtres Logstash standard, ce qui fait du filtre Ruby une option pratique pour les structures de données complexes.

Diviser un événement unique en plusieurs événements

Les filtres Ruby peuvent également être utilisés pour diviser un événement unique en plusieurs événements. Ceci est utile lorsque vous avez un événement unique contenant un tableau d'éléments et que vous souhaitez créer des événements distincts pour chaque élément.

Notez que ni le pipeline d'acquisition d'Elasticsearch ni les processeurs de Beats/Elastic Agent ne prennent en charge le fractionnement des événements. C'est l'un des cas d'utilisation les plus importants pour Logstash.

Avec filtre divisé

Vous pouvez utiliser le filtre split pour diviser un événement en plusieurs événements sur la base d'un champ spécifié. Toutefois, si vous devez effectuer des transformations ou des opérations logiques supplémentaires pendant le fractionnement, vous pouvez utiliser le filtre Ruby en combinaison avec le filtre de fractionnement.

Dans l'exemple suivant, nous avons un flux RSS sous la forme d'une seule ligne de texte XML. Il contient plusieurs éléments . Le filtre Ruby est utilisé pour extraire les éléments du XML et les stocker dans un nouveau champ appelé items. Le filtre de division est ensuite utilisé pour diviser l'événement en plusieurs événements sur la base du champ 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 } }

Le résultat sera le suivant :

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

Comme vous l'avez peut-être remarqué, le filtre ruby n'est pas indispensable dans ce cas. Le filtre split peut être utilisé pour diviser l'événement en plusieurs événements sur la base du champ items, et le filtre mutate peut être utilisé pour supprimer les champs inutiles. Toutefois, si vous devez effectuer des transformations ou des opérations logiques supplémentaires pendant le fractionnement, vous pouvez utiliser le filtre Ruby.

Utiliser un script Ruby en ligne

Vous pouvez également utiliser un script Ruby en ligne pour diviser un événement unique en plusieurs événements en utilisant la méthode event.clone et la méthode new_event_block variable, telle que new_event_block.call(new_event). Cela vous permet de créer de nouveaux événements basés sur l'événement original tout en préservant ses données.

Voici un exemple d'utilisation du filtre Ruby pour diviser un événement unique en plusieurs événements. L'entrée et la sortie sont les mêmes que dans l'exemple précédent.

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

Utiliser un script Ruby externe

Vous pouvez également utiliser un script Ruby externe pour diviser un événement unique en plusieurs événements.

Fichier de configuration :

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

Le script Ruby doit être externalisé en tant que 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

N'oubliez pas que la méthode filter doit renvoyer un tableau d'événements. Vous pouvez renvoyer plusieurs événements en clonant un objet événement entrant et en l'ajoutant au tableau, ou vous pouvez renvoyer un seul événement sous la forme d'un tableau à un seul élément.

return events # or # return [event]

Cela vous permet de diviser un événement unique en plusieurs événements.

Exécuter des commandes externes et analyser leurs résultats

Le plugin Logstash exec input vous permet d'exécuter des commandes externes et leur sortie sera un événement de Logstash. La sortie de la commande sera stockée dans le champ message de l'événement.

Habituellement, la sortie des commandes système est lisible par l'homme, mais n'est pas structurée en JSON ou dans d'autres formats que Logstash peut facilement analyser. Pour ce faire, vous pouvez utiliser le filtre Ruby pour analyser la sortie et en extraire les informations.

Voici un exemple d'utilisation du plugin d'entrée exec pour exécuter la commande ps -ef, qui répertorie tous les processus en cours d'exécution sur un système de type Unix. La sortie sera analysée par le filtre Ruby afin d'extraire les informations pertinentes sur chaque processus.

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

Cet exemple utilise le plugin d'entrée exec pour exécuter la commande ps -ef toutes les 60 secondes. Le filtre Ruby traite la sortie, en extrayant les champs pertinents tels que UID, PID, PPID, l'utilisation du CPU (C), l'heure de démarrage (STIME), TTY, le temps total du CPU (TIME), et la commande (CMD) exécutée. Cela fonctionne bien dans mon environnement macOS, mais il se peut que vous deviez ajuster les motifs des expressions rationnelles pour qu'ils correspondent au format de sortie de la commande ps -ef sur votre système.

Utiliser les bibliothèques intégrées

Le plugin de filtrage Ruby vous permet d'utiliser des bibliothèques Ruby intégrées, qui peuvent s'avérer très utiles pour diverses tâches. Par exemple, vous pouvez utiliser la bibliothèque json pour analyser les chaînes JSON ou la bibliothèque date pour manipuler les dates.

Voici un exemple d'utilisation de la bibliothèque json pour analyser une chaîne JSON stockée dans un champ :

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

Pour éviter d'avoir besoin de la bibliothèque à chaque fois, vous devriez externaliser votre code Ruby afin d'utiliser l'instruction require au début de votre script de filtrage Ruby. Cela chargera la bibliothèque une fois et la rendra disponible pour une utilisation dans votre script.

Pour vérifier quelles sont les bibliothèques disponibles dans votre environnement, vous pouvez dresser la liste des bibliothèques intégrées en exécutant le code suivant dans le filtre Ruby :

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

Note : Les bibliothèques intégrées ne sont pas officiellement supportées par Logstash, et leur comportement peut changer ou elles peuvent ne pas être disponibles dans les versions futures. Utilisez-les à vos risques et périls.

Conclusion

Le filtre Logstash Ruby vous permet de personnaliser et d'étendre les capacités de vos pipelines Logstash. Dans ce billet, nous avons couvert les bases de l'utilisation du filtre Ruby et fourni des exemples d'utilisation avancée.

En tirant parti du filtre Ruby, vous pouvez effectuer des tâches de traitement de données complexes qui nécessitent une logique personnalisée ou des manipulations avancées. Que vous travailliez avec des structures de données imbriquées, que vous fractionniez des événements ou que vous analysiez et convertissiez du texte complexe/non structuré en JSON structuré, le filtre Ruby offre la flexibilité nécessaire pour répondre à vos besoins spécifiques.

Nous espérons que ce guide vous a apporté les connaissances et l'inspiration nécessaires pour explorer tout le potentiel du filtre Logstash Ruby. Bonne lecture !

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.