1. Accueil
  2. Docs
  3. API Doc
  4. Queries

Queries

Les API d’Olifid sont basées sur un moteur Elasticsearch, lui-même basé sur Lucene, la librairie de recherche d’Apache. Elles utilisent donc la syntaxe de requête de Lucene.

Connaître la syntaxe et les opérateurs de Lucene vous aidera grandement à créer des requêtes.

Fonctionnement général: comment faire la requête ?

C’est tout simple, les appels aux API d’Olifid se décomposent ainsi:

GET (seule la méthode GET est disponible) https://api.olifid.com/ (URL de base) + endpoint (nom du endpoint) + ?apikey=votreclefdAPI (clef d’API) + &q=query (votre requête)

Liste des variables retournées dans le JSON qui sont autant de paramètres sur lesquels faire varier la query

versioncreated: c’est la date de parution du communiqué au format universel

organisation: c’est le nom de la société

source: c’est le diffuseur de niveau 1 du communiqué (un Newswire, une agence de presse…)

headline: c’est le titre du communiqué

subheadline: c’est le sous-titre ou le chapeau du communiqué

dateline

body_xhtml

contact

copyrightnotice

language

isin

css

publicidentifier

Exemple:

GET "https://api.olifid.com/news?apikey=XXXXXXXX&q=*
vous retournera les 100 derniers communiqués publiés.

{
   "count": 100, (nombre de communiqués retournés)
   "nbqueries": 4, (nombre de requêtes réalisées dans les dernières 24h)
   "maxqueries": 100000, (maximum de requêtes possible en 24h)
   "query": "",   (rappel de la requête effectuée)
   "hits": [     
            {       
               versioncreated: date du communiqué 1
               organisation: nom de l'entreprise ou organisation qui émet le communiqué 1
               source: source de diffusion du communiqué 1 (wire, agence de presse...)
               headline: titre du communiqué 1 (HTML)
               subheadline: sous-titre du communiqué 1 (HTML)
               dateline: dateline 1 (Ville / pays / + heure) (HTML)
               body_xhtml: corps du communiqué 1 (HTML)
               contact: contact lié au communiqué 1 (HTML) 
               copyrightnotice: ligne de copyright a toujours citer lors de la reprise du communiqué 1
               language: langage utilisé pour le communiqué 1
               isin: code ISIN de la société emmetrice du communiqué 1
               css: code CSS qui doit être repris pour la mise en forme du communiqué 1 (CSS)
               publicidentifier: numéro unique du communiqué 1
            },
                versioncreated: date du communiqué 2
               organisation: nom de l'entreprise ou organisation qui émet le communiqué 2
               source: source de diffusion du communiqué 2 (wire, agence de presse...)
               headline: titre du communiqué 2 (HTML)
               subheadline: sous-titre du communiqué 2  (HTML) 
               dateline: dateline 2 (Ville / pays / + heure)  (HTML) 
               body_xhtml: corps du communiqué 2 (HTML)
               contact: contact lié au communiqué 2 (HTML) 
               copyrightnotice: ligne de copyright a toujours citer lors de la reprise du communiqué 2
               language: langage utilisé pour le communiqué 2
               isin: code ISIN de la société emmetrice du communiqué 2
               css: code CSS qui doit être repris pour la mise en forme du communiqué 2 (CSS)
               publicidentifier: numéro unique du communiqué 2
            }, 

            {... jusqu'au 100ème communiqué
            }
          ]
}

Accélerez le temps de réponse avec un header de compression suivant

Accept-Encoding: gzip, deflate, br

Opérateurs booléens

Comme avec la plupart des langages informatiques, Elasticsearch prend en charge les opérateurs AND, OR et NOT:

  • jack AND jill – Renverra les événements contenant à la fois Jack et Jill
  • ahab NOT moby – Retourne les événements contenant ahab mais pas moby
  • tom OR jerry – renverra les événements contenant tom ou jerry, ou les deux

Des champs

Vous recherchez peut-être des événements pour lesquels un champ spécifique contient certains termes. Vous spécifiez cela comme suit:

  • nom: « Ned Stark »

Soyez prudent avec les valeurs avec des espaces tels que «Ned Stark». Vous devrez le mettre entre guillemets pour garantir que la valeur entière est utilisée.

Gammes

Vous pouvez rechercher des champs dans une plage spécifique, en utilisant les crochets pour les recherches de plages inclusives et les accolades pour les recherches de plages exclusives:

  • age: [3 TO 10] – Rendra les événements avec un âge compris entre 3 et 10
  • price: {100 TO 400} – Retourne les événements avec des prix compris entre 101 et 399
  • name: [Adam TO Ziggy] – Renverra les noms compris entre Adam et Ziggy

Comme vous pouvez le constater dans les exemples ci-dessus, vous pouvez également utiliser des plages dans des champs non numériques tels que des chaînes et des dates.

Wildcards, Regexes et Fuzzy Searching

La recherche ne serait pas une recherche sans caractères génériques. Vous pouvez utiliser le caractère * pour les caractères génériques à plusieurs caractères ou le symbole? caractère pour les caractères génériques à caractère unique:

  • Ma? S – Correspondra à Mars, à la messe et à des cartes
  • Ma * s – Correspondra à Mars, Matches et Massachusetts

Les regex vous donnent encore plus de pouvoir. Placez simplement votre regex entre les barres obliques (/):

  • / p [ea] n / – Correspondra à la fois au stylo et au pan
  • /<.+>/ – Correspondra au texte ressemblant à une balise HTML

La recherche floue utilise la distance de Damerau-Levenshtein pour faire correspondre des termes similaires en orthographe. C’est formidable lorsque votre ensemble de données contient des mots mal orthographiés. Utilisez le tilde (~) avec un nombre pour spécifier l’importance de la distance entre les mots:

  • john ~ 2 – Correspondra, entre autres, à jean, johns, jhon et horn

Recherche URI

Le moyen le plus simple de rechercher votre cluster Elasticsearch consiste à effectuer une recherche d’URI. Vous pouvez transmettre une requête simple à Elasticsearch à l’aide du paramètre de requête q. La requête suivante recherchera dans tout votre cluster des documents avec un champ de nom égal à «travis»:

  • curl “localhost: 9200 / _search? q = name: travis”

Avec la syntaxe Lucene, vous pouvez construire des recherches assez impressionnantes. Habituellement, vous devez encoder des URL tels que des espaces (pour des raisons de clarté, ces exemples ont été omis):

  • curl « localhost: 9200 / _search? q = nom: john ~ 1 ET (age: [30 A 40}} OU nom: K *) ET -cité »

Un certain nombre d’options sont disponibles pour vous permettre de personnaliser la recherche d’URI, notamment en ce qui concerne l’analyseur à utiliser (analyseur), si la requête doit être tolérante aux pannes (indulgence) et si une explication de l’évaluation doit être fournie ( Explique).

Bien que la recherche d’URI soit un moyen simple et efficace d’interroger votre cluster, vous constaterez rapidement qu’elle ne prend pas en charge toutes les fonctionnalités offertes par Elasticsearch. Toute la puissance d’Elasticsearch est exposée via Request Body Search. L’utilisation de la requête Recherche dans le corps vous permet de créer une requête de recherche complexe en utilisant divers éléments et clauses de requête qui vont correspondre, filtrer et classer, ainsi que manipuler des documents en fonction de plusieurs critères.

La requête de recherche de corps

La requête de recherche de corps utilise un document JSON contenant divers éléments pour créer une recherche sur votre cluster Elasticsearch. Vous pouvez non seulement spécifier des critères de recherche, mais également définir la plage et le nombre de documents attendus, les champs souhaités et diverses autres options.

Le premier élément d’une recherche est l’élément de requête qui utilise Query DSL. L’utilisation de la requête DSL peut parfois être source de confusion car elle peut être utilisée pour combiner et construire des clauses de requête en une requête pouvant être imbriquée en profondeur. Étant donné que la plupart des documents Elasticsearch ne font référence qu’à des clauses isolées, il est facile de perdre de vue où les clauses doivent être placées.

Pour utiliser le DSL de requête, vous devez inclure un élément «requête» dans votre corps de recherche et le renseigner avec une requête créée à l’aide du DSL:

{"Requête": {"correspondance": {"_all": "signification"}}}

Copie

Dans ce cas, l’élément « query » contient une clause de requête « match » qui recherche le terme « signification » dans tous les champs de tous les documents de votre cluster.

L’élément de requête est utilisé avec d’autres éléments dans le corps de recherche:

{
"requete": {
“Match”: {“_all”: “signification”}
},
“Champs”: [“nom”, “nom”, “age”],
“À partir de”: 100, “taille”: 20
}

Copie

Ici, nous utilisons l’élément «fields» pour limiter les champs à renvoyer, ainsi que les éléments «from» et «size» pour indiquer à Elasticsearch que nous recherchons les documents 100 à 119 (commençant à 100 et comptant 20 documents).

La requête DSL

Query DSL peut être appelé à l’aide de la plupart des API de recherche d’Elasticsearch. Par souci de simplicité, nous ne regarderons que l’API de recherche qui utilise le noeud final _search. Lorsque vous appelez l’API de recherche, vous pouvez spécifier l’index et / ou le type sur lequel vous souhaitez effectuer une recherche. Vous pouvez même effectuer des recherches sur plusieurs index et types en séparant leurs noms par des virgules ou en utilisant des caractères génériques pour faire correspondre plusieurs index et types:

Rechercher sur tous les index Logstash:

  • curl localhost: 9200 / logstash – * / _ recherche

Rechercher dans les index actuels et anciens, dans le type de document:

  • curl localhost: 9200 / actuel, hérité / documents / _search

Rechercher dans les indices clients, dans les types bigcorp et smallco:

  • curl localhost: 9200 / clients / bigcorp, smallco / _search

Nous allons utiliser les recherches dans le corps de la requête, les recherches doivent donc être appelées comme suit:

  • curl localhost: 9200 / _search -d ‘{« query »: {« match »: {« _all »: « signification »}}}’

Requêtes composées

Bien qu’il existe plusieurs types de clause de requête, celui que vous utiliserez le plus est les requêtes composées, car il est utilisé pour combiner plusieurs clauses afin de créer des requêtes complexes.

La requête booléenne est probablement la plus utilisée car elle peut combiner les fonctionnalités de certaines autres clauses de requête composées telles que les clauses And, Or, Filter et Not. Il est tellement utilisé que ces quatre clauses ont été déconseillées dans diverses versions en faveur de l’utilisation de la requête Bool. Son utilisation s’explique mieux par un exemple:

curl localhost: 9200 / _search -d '{
"requete":{
"bool": {
"doit": {
"flou": {
"nom": "john",
"flou": 2
}
},
"ne doit pas": {
"rencontre": {
"_all": "ville"
}
},
"devrait": [
{
"intervalle": {
"age": {"de": 30, "à": 40}
}
},
{
"joker": {"nom": "K *"}
}
]
}
}
} '

Copie

Dans l’élément de requête, nous avons ajouté la clause bool qui indique qu’il s’agira d’une requête booléenne. Il y a pas mal de choses à faire, alors couvrons-les article par article, en commençant par le haut:

doit

Toutes les requêtes de cette clause doivent correspondre à un document pour qu’il soit renvoyé par Elasticsearch. Pensez à cela comme à vos requêtes AND. La requête que nous avons utilisée ici est la requête floue. Elle correspond à tous les documents dont le champ de nom correspond à «john» de manière floue. Le paramètre supplémentaire «flou» indique à Elasticsearch qu’il devrait utiliser une distance de Damerau-Levenshtein de deux pour déterminer le flou.

ne doit pas

Tous les documents correspondant à la requête dans cette clause seront exclus du jeu de résultats. C’est l’opérateur NOT ou moins (-) de la requête DSL. Dans ce cas, nous effectuons une requête de correspondance simple, recherchant des documents contenant le terme «ville». L’utilisation de _all comme nom de champ indique que le terme peut apparaître dans l’un des champs du document. Ceci est la clause must_not , ainsi les documents correspondants seront exclus.

devrait

Jusqu’à présent, nous avons eu affaire à des absolus: must and must_not . Should n’est pas absolu et est équivalent à l’opérateur OR. Elasticsearch renverra tous les documents correspondant à une ou plusieurs des requêtes de la clause should. La première requête que nous avons fournie recherche des documents dont le champ d’âge est compris entre 30 et 40 ans. La deuxième requête effectue une recherche avec un caractère générique sur le champ du nom de famille, en recherchant les valeurs commençant par «K.».

La requête contenant trois clauses différentes, Elasticsearch ne renverra donc que les documents correspondant aux critères. Ces requêtes peuvent être imbriquées, vous pouvez donc créer des requêtes très complexes en spécifiant une requête booléenne comme must , must_not , devrait ou filtrer la requête.

filtre

Un type de clause dont nous n’avons pas discuté pour une requête composée est la clause filter . Voici un exemple d’utilisation:

curl localhost: 9200 / _search -d '{
"requete":{
“Bool”: {
"doit": {
{"Match_all": {}}
},
“Filtre”: {
«Terme»: {
“Email”: “joe@bloggs.com”
}
}
}
}
} `

Copie

La requête match_all de la clause must indique à Elasticsearch qu’il doit renvoyer tous les documents. Cela peut sembler une recherche peu utile, mais elle s’avère pratique si vous l’utilisez en conjonction avec un filtre, comme nous l’avons fait ici. Le filtre que nous avons spécifié est une requête de terme, demandant tous les documents contenant un champ de courrier électronique avec la valeur «joe@bloggs.com». Nous avons utilisé un filtre pour spécifier les documents que nous souhaitons. Ils seront donc tous renvoyés avec un score de 1. Les filtres n’étant pas utilisés dans le calcul des scores, la requête match_all attribue à tous les documents un score de 1.Plus sur le sujet:

Une chose à noter est que cette requête ne fonctionnera pas comme prévu si le champ de courrier électronique est analysé, ce qui est la valeur par défaut pour les champs dans Elasticsearch. La raison en est un sujet qui pourrait être mieux traité dans un autre article de blog, mais cela revient au fait qu’Elasticsearch analyse les champs et les requêtes lorsqu’ils arrivent. Dans ce cas, le champ de courrier électronique sera divisé en trois parties: joe, blogs et com. Cela signifie que les recherches et les documents seront mis en correspondance pour trois de ces termes.

Filtres et requêtes

Les personnes ayant utilisé Elasticsearch avant la version 2 seront familiarisées avec les filtres et les requêtes. Vous aviez l’habitude de construire un corps de requête à l’aide de filtres et de requêtes. La différence entre les deux était que les filtres étaient généralement plus rapides, car ils vérifiaient uniquement si un document correspondait et non si il correspondait bien. En d’autres termes, les filtres donnent une réponse booléenne tandis que les requêtes renvoient un score calculé indiquant si un document correspond à une requête. Diverses améliorations des performances ont été associées aux filtres en raison de leur nature simplifiée.

Depuis la version 2 de Elasticsearch, les filtres et les requêtes ont été fusionnés et toute clause de requête peut être utilisée comme filtre ou comme requête (selon le contexte). Comme avec la version 1, les filtres sont mis en cache et doivent être utilisés si le score n’a pas d’importance.

Notation

Nous avons mentionné le fait qu’Elasticsearch renvoie une partition avec tous les documents correspondants d’une requête:

> curl “localhost: 9200 / _search? q = application”
{
"_shards": {
"total": 5,
"réussi": 5,
"échoué": 0
},
"les coups":{
"total": 1,
"max_score": 2.3,
"les coups" : [
{
"_index": "logstash-2016.04.04",
"_type": "logs",
"_id": "1",
"_score": 2.3,
"_la source" : {
"message": "Enregistrer le message de mon application"
}
}
]
}
}

Copie

Ce score est calculé par rapport aux documents dans Elasticsearch en fonction des requêtes fournies. Des facteurs tels que la longueur d’un champ, la fréquence à laquelle le terme spécifié apparaît dans le champ et (dans le cas de recherches génériques et floues) le degré de correspondance entre le terme et la valeur spécifiée ont tous une influence sur le score. Le score calculé est ensuite utilisé pour commander des documents, généralement du score le plus élevé au plus bas, et les documents présentant les scores les plus élevés sont ensuite renvoyés au client. Il existe différentes manières d’influencer les résultats de différentes requêtes, telles que le paramètre Boost. Cela est particulièrement utile si vous souhaitez que certaines requêtes d’une requête complexe aient plus de poids que d’autres et que vous recherchiez les documents les plus significatifs.

Lors de l’utilisation d’une requête dans un contexte de filtre (comme expliqué précédemment), aucun score n’est calculé. Ceci fournit les performances améliorées généralement associées à l’utilisation de filtres, mais ne fournit pas les fonctionnalités de classement et d’importance fournies avec l’évaluation.

Conclusion

La chose la plus difficile à propos d’Elasticsearch est la profondeur et la largeur des fonctionnalités disponibles. Nous avons essayé de couvrir les éléments essentiels avec autant de détails que possible sans vous noyer dans les informations. Posez toutes les questions que vous pourriez avoir dans les commentaires et recherchez