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

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 :

FROM sample_data | LIMIT 2 | SORT @timestamp DESC

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.