Une chaîne de requête contient des caractères Unicode. La longueur maximale d'une chaîne de requête est de 2 000 caractères. Toutes les chaînes de requête contiennent au moins une valeur de champ. Il est recommandé d'écrire les valeurs de champ en minuscules car, d'une part, les recherches sur les champs Atom, texte et HTML ne sont pas sensibles à la casse, et d'autre part, une chaîne de requête peut aussi contenir les opérateurs booléens AND, OR et NOT, lesquels se reconnaissent par leur écriture en majuscules.
Une virgule ne peut apparaître dans une chaîne de requête que si elle sert à séparer les arguments d'une fonction : distance(home, geopoint(35.2, 40.5)) > 100 ou si elle fait partie d'une chaîne entre guillemets.
Une chaîne de requête peut prendre plusieurs formes. Il existe deux façons principales de construire une requête : avec noms de champ et sans noms de champ. Une recherche globale utilise une chaîne de requête ne contenant que des valeurs de champ :
query = "blue"
query = "NOT white"
query = "blue OR red"
query = "blue guitar"
Une recherche de champ utilise une chaîne de requête qui contient une ou plusieurs expressions spécifiant les noms et les valeurs de champ :
query = "model:gibson date < 1965-01-01"
query = "title:\"Harry Potter\" AND pages<500"
query = "beverage:wine color:(red OR white) NOT country:france"
Ce document explique comment construire des chaînes de requête pour les recherches globales et de champ, ainsi que la logique de recherche appliquée à chaque cas.
Nous vous recommandons de consigner les chaînes de requête dans votre application si vous souhaitez conserver un enregistrement des requêtes exécutées.
Recherche globale
La recherche globale permet de rechercher des documents en spécifiant des valeurs susceptibles d'apparaître dans n'importe quel champ de document. Une recherche globale s'effectue en écrivant une chaîne de requête qui contient une ou plusieurs valeurs de champ. L'algorithme de recherche reconnaît le type de chaque valeur et effectue la recherche dans tous les champs de document pouvant contenir cette valeur.
Requêtes à une seule valeur
Les recherches à partir d'une chaîne de requête ne contenant qu'une seule valeur sont gérées selon les règles suivantes :
Si la chaîne de requête est un mot (red) ou une chaîne entre guillemets ("red rose"), la recherche extrait tous les documents d'un index contenant :
- un champ de texte ou HTML contenant ce mot ou cette chaîne entre guillemets (la correspondance n'est pas sensible à la casse) ;
- un champ Atom avec une valeur qui correspond au mot ou à la chaîne entre guillemets (la correspondance n'est pas sensible à la casse).
Si la chaîne de requête est un nombre ("3.14159"), la recherche récupère tous les documents contenant :
- un champ de texte ou HTML contenant un jeton correspondant au nombre tel qu'il apparaît dans la requête (le champ de texte "il a mis 5 minutes" correspond à la requête "5", mais pas à "5.0") ;
- un champ Atom qui correspond littéralement au nombre tel qu'il apparaît dans la requête.
Si la chaîne de requête est une date au format aaaa-mm-jj, la recherche récupère tous les documents contenant :
- un champ de date dont la valeur est égale à cette date (les zéros situés au début de la chaîne de requête sont facultatifs : "2012-07-04" et "2012-7-4" représentent la même date) ;
- un champ de texte ou HTML contenant un jeton qui correspond littéralement à la date telle qu'elle apparaît dans la requête ;
- un champ Atom qui correspond littéralement à la date telle qu'elle apparaît dans la requête.
Vous pouvez ajouter l'opérateur booléen NOT (en majuscules) au début d'une requête contenant un seul mot. Le résultat est une liste de documents pour lesquels aucun champ ne correspond à la valeur de la requête, selon les mêmes règles. Ainsi la requête NOT red récupère tous les documents ne comportant aucun champ de texte ou HTML contenant "red", ni aucun champ Atom avec la valeur red.
Vous avez peut-être remarqué que les champs de point géographique n'ont pas été mentionnés. Pour le moment, il n'est pas possible de spécifier une valeur de point géographique brute en tant que chaîne. Par conséquent, les points géographiques ne peuvent pas apparaître dans les recherches globales.
Requêtes à valeurs multiples
Vous pouvez spécifier plusieurs valeurs (séparées par un espace) dans une chaîne de recherche globale. Les caractères d'espacement entre les mots, les chaînes entre guillemets, les nombres et les dates sont traités comme un opérateur AND implicite. Les deux chaînes de recherche suivantes sont presque identiques. La différence réside dans la façon dont la recherche globale traite les champs Atom, comme expliqué ci-dessous :
query = "small red"
query = "small AND red"
Lorsque vous effectuez une recherche globale avec des valeurs multiples, la correspondance de champ est établie indépendamment pour chaque valeur de la chaîne et la correspondance de champ Atom est gérée différemment, en particulier :
- Les valeurs de requête peuvent apparaître dans n'importe quel ordre dans un champ de texte ou un champ HTML.
- Différentes valeurs peuvent apparaître dans différents champs.
- La recherche n'est effectuée dans les champs Atom que lorsque la chaîne de requête ne contient aucun opérateur booléen (
AND,OR,NOT). Toute la chaîne de requête doit correspondre à un champ Atom.
Notez la troisième règle concernant les champs Atom. La chaîne de requête "red small" ne contient pas l'opérateur booléen AND (même s'il est implicite). La recherche va donc tenter de trouver les champs Atom correspondants. La chaîne "red AND small" contient un opérateur booléen. Par conséquent, la recherche n'essaiera pas de faire correspondre la chaîne de requête aux champs Atom.
L'exemple suivant montre quatre documents qui ont été récupérés à partir de la chaîne de requête "rose bud". Chaque document comporte deux champs de texte et un champ Atom. La colonne Commentaire explique en quoi chaque document est conforme à la requête.
| ID du document | Champ de texte 1 | Champ de texte 2 | Champ Atom | Commentaire |
|---|---|---|---|---|
| 1 | mighty like a rose | one bud to bind them all | thorn bush | Les valeurs correspondantes peuvent apparaître dans différents champs. |
| 2 | wide like a river | like a bud on a rose | tumble weed | Les valeurs correspondantes peuvent apparaître dans n'importe quel ordre dans le même champ de texte ou HTML, avec du texte intermédiaire. |
| 3 | deep like the ocean | the rose bud boys | blue bonnet | Les valeurs correspondantes peuvent apparaître dans n'importe quel ordre dans le même champ de texte ou HTML. |
| 4 | tall like a mountain | the beautiful garden | rose bud | Le champ Atom correspond, car sa valeur est identique à celle de la chaîne de requête entière. |
Notez que si vous inversez les valeurs de la requête et recherchez "bud rose", les documents 1, 2 et 3 seront toujours renvoyés, mais pas le document 4. Pour rechercher une chaîne de caractères exacte dans des champs Atom, de texte et HTML, placez-la entre guillemets dans la chaîne de requête. Une recherche portant sur "rose bud" renvoie uniquement les documents 3 et 4 dans l'exemple.
Opérateurs booléens
Vous pouvez effectuer une recherche globale plus complexe en utilisant l'opérateur booléen NOT avant une valeur, et les opérateurs AND et OR entre les valeurs. Notez que ces opérateurs doivent être écrits en majuscules. S'ils apparaissent dans une chaîne entre guillemets, ils sont traités comme faisant partie de la valeur du champ et non comme des opérateurs. Pour clarifier la logique, vous pouvez utiliser des parenthèses dans une chaîne de requête.
L'ordre de priorité des opérateurs booléens (de la plus élevée à la moins élevée) est NOT, OR, AND :
NOT cat AND dogs OR horses --> (NOT cat) AND (dogs OR horses)
NOT cat OR dogs AND horses --> ((NOT cat) OR dogs) AND horses
Recherche de radical
Pour rechercher des variantes communes d'un mot, telles que les formes plurielles et les terminaisons de verbe, utilisez l'opérateur "radical" ~ (le caractère tilde). Il s'agit d'un opérateur préfixe qui doit précéder une valeur sans espace intermédiaire. La valeur ~cat correspond à "cat" ou "cats", et ~dog à "dog" ou "dogs". L'algorithme de recherche de radical n'est pas infaillible. La valeur ~care correspond à "care" et "caring", mais pas "cares" ni "cared". La recherche de radical n'est utilisée que pour les champs de texte et HTML.
Tokenisation
Lorsqu'un document est indexé, ses champs sont tokenisés. De même, les valeurs d'une chaîne de requête sont également tokenisées. Cela signifie qu'une requête qui peut sembler être à une seule valeur est en réalité traitée comme une requête à valeurs multiples. Exemple :
"real-time" --> "real time"
"2001-12-15" --> "2001 12 15"
"1.5" --> "1 5"
Recherche de champ
Une recherche de champ recherche des valeurs dans des champs de document spécifiques, par nom de champ. Une chaîne de requête de recherche de champ est composée d'une ou plusieurs expressions spécifiant un nom de champ, un opérateur relationnel et une valeur de champ. Les opérateurs relationnels disponibles dépendent du type du champ. L'opérateur d'égalité, représenté par le signe deux-points ou le signe égal, peut être utilisé pour tous les types de champs. Voici quelques chaînes de requête de champ pour différents types de champs :
query = "pet = dog"
query = "author = \"Ray Bradbury\""
query = "color:red"
query = "NOT color:red"
query = "price < 500"
query = "birthday>=2011-05-10"
Notez que l'utilisation des caractères d'espacement de part et d'autre de l'opérateur relationnel est facultative. Comme pour les chaînes de requête de recherche globale, la valeur d'un champ de texte, HTML ou Atom peut être placée entre guillemets pour spécifier une chaîne. De la même façon, une expression pour une valeur de champ peut être inversée en ajoutant NOT en majuscules au début de l'expression.
Requêtes sur les champs Atom
La valeur d'un champ Atom est une chaîne de caractères. Les requêtes sur les champs Atom ne sont pas sensibles à la casse. Si votre requête spécifie une valeur de champ avec des caractères d'espacement ou des signes de ponctuation, veillez à bien mettre la valeur entre guillemets dans la chaîne de requête. L'opérateur d'égalité est le seul opérateur relationnel valide pour les champs Atom. Le contenu complet d'un champ Atom doit correspondre à la valeur de la requête. Cela inclut tout caractère combiné ou caractère accentué Unicode compris dans le champ. La recherche de radical n'est pas disponible pour les champs Atom.
| Chaîne de requête | Commentaires |
|---|---|
"weather=stormy"
|
Les deux formes de l'opérateur d'égalité sont valides. Récupère les documents dont le champ "weather" correspond à "stormy". |
"Title: \"Tom&Jerry\""
|
Si vous recherchez un champ Atom contenant des caractères d'espacement ou des caractères spéciaux, mettez la valeur entre guillemets. |
"Color = (red OR blue)"
|
Vous pouvez utiliser des parenthèses et l'opérateur logique OR pour spécifier une liste de valeurs de champ alternatives. |
Requêtes sur les champs de texte et HTML
L'égalité est le seul opérateur relationnel valide pour les champs de texte et HTML. Dans ce cas, l'opérateur signifie "le champ inclut la valeur" et non "le champ est égal à la valeur". Vous pouvez utiliser l'opérateur de recherche de radical pour rechercher des variantes d'un mot. Vous pouvez également utiliser les opérateurs OR et AND pour spécifier des expressions booléennes complexes pour la valeur de champ. Si un opérateur booléen apparaît dans une chaîne indiquée entre guillemets, il ne fait pas l'objet d'un traitement particulier. Il s'agit simplement d'une partie de la chaîne de caractères à rechercher. N'oubliez pas que lors de la recherche de champs HTML, le texte situé à l'intérieur des balises HTML est ignoré. Les requêtes sur les champs de texte et HTML ne sont pas sensibles à la casse. Lorsque ces champs sont indexés, tous les caractères de non-espacement et les caractères accentués Unicode sont "normalisés" selon leur équivalent non accentué. Les caractères de non-espacement et les accents sont également normalisés dans les chaînes de requête de ces champs. Une requête peut ainsi inclure ou non les formes accentuées et correspondre aux champs dans les deux cas.
| Chaîne de requête | Commentaires |
|---|---|
"Comment = great" |
Les deux formes de l'opérateur d'égalité sont valides. Récupère les documents dont le champ "Comment" contient au moins une occurrence du mot "great". |
"Comment = (great big ball)"
|
Pour rechercher deux mots ou plus dans un champ, dans n'importe quel ordre, placez les mots entre parenthèses. Cette chaîne de requête récupère les documents dont le champ "Comment" inclut les trois mots dans n'importe quel ordre, peu importe le nombre de mots entre eux. Le caractère d'espacement entre les mots implique un AND logique ; la seconde forme le rend explicite. |
"Comment = \"insanely great\""
|
Pour rechercher une chaîne de texte spécifique, placez-la entre guillemets. Cette requête récupère les documents dont le champ "Comment" contient l'expression "insanely great" (ainsi que "insanely-great", qui correspond à la même forme tokenisée). |
"pet = ~dog"
|
L'opérateur de recherche de radical fait correspondre les variantes du mot "dog" dans le champ "pet". |
"Color = (red OR blue)" |
Pour rechercher une correspondance dans une liste d'alternatives, placez la liste entre parenthèses avec le mot clé OR entre les alternatives. Cette requête récupère les documents dont le champ "Color" comprend "red" ou "blue", ou les deux. |
"weather = ((rain OR snow) AND cold)" |
Vous pouvez utiliser les opérateurs logiques OR et AND, ainsi que des parenthèses, pour spécifier une valeur de champ plus complexe. |
"weather = \"rain OR shine\"" |
Étant donné que l'opérateur logique OR est inclus dans une chaîne entre guillemets, il n'est pas traité comme un opérateur relationnel. Cette chaîne de requête récupère les documents dont le champ "weather" contient la chaîne "rain or shine". |
Requêtes sur les champs numériques
Une valeur de champ numérique peut être écrite sous la forme d'un nombre entier, d'un nombre décimal ou d'une valeur exponentielle.
Les opérateurs relationnels valides pour les champs numériques sont les opérateurs d'égalité, ainsi que les opérateurs inférieur à/supérieur à (<, <=, >, >=). Notez qu'il n'existe aucun opérateur (!=) d'inégalité. Voici quelques exemples de chaînes de requête pour les champs numériques :
"quantity = 10000"
"size: 4"
"price < 9.99"
"theta > 1.5E-2"
Requêtes sur les champs de date
Une valeur de champ de date doit être écrite au format yyyy-mm-dd form. Les zéros situés au début des mois et des jours à un chiffre sont facultatifs. Les opérateurs relationnels valides pour les champs de date sont les opérateurs d'égalité, ainsi que les opérateurs inférieur à/supérieur à (<, <=, >, >=). Notez qu'il n'existe aucun opérateur d'inégalité. Vous pouvez ajouter l'opérateur NOT au début d'une expression pour l'inverser. Voici des exemples de chaînes de requête pour les champs de date :
"start_date: 2012-05-20"
"end_date: 2013-5-1"
"birthday >= 2000-12-31"
"NOT birthday = 2000-12-25"
Requêtes sur les champs de point géographique
Aucun opérateur relationnel ne fonctionne avec les champs de point géographique. Par conséquent, ceux-ci ne peuvent pas être nommés directement dans une chaîne de requête. L'API Search fournit deux fonctions spéciales pouvant être utilisées pour les requêtes qui impliquent des champs de point géographique :
geopoint(lat,long)- Définit un point géographique à partir d'une latitude et d'une longitude.
distance(point1, point2)- Calcule la distance en mètres entre deux points géographiques. Chaque point peut être spécifié en utilisant le nom d'un champ de point géographique ou un appel de la fonction de point géographique. Notez que vous ne pouvez pas fournir deux noms de champs en tant qu'arguments pour cette fonction. Au moins un argument doit être une constante.
Ces fonctions peuvent être utilisées pour créer des requêtes qui récupèrent des emplacements par rapport à une position constante. Les exemples suivants supposent que l'index contient des documents avec des champs de points géographiques nommés "survey_marker" et "home".
| Chaîne de requête | Commentaires |
|---|---|
"distance(survey_marker, geopoint(35.2, 40.5)) < 100" |
Recherche des champs "survey_marker" dont la valeur est située à moins de 100 mètres d'un point géographique donné. |
"distance(home, geopoint(35.2, 40.5)) > 100" |
Recherche des champs "home" dont la valeur est située à plus de 100 mètres d'un point géographique donné. |
Les applications qui utilisent la géolocalisation reçoivent généralement des informations du navigateur. Si l'utilisateur le permet, son emplacement peut être déduit à partir de son adresse IP. L'utilisateur peut aussi entrer un code postal. L'emplacement peut également provenir d'autres API telles que l'API Google Maps Geolocation.
Requêtes sur plusieurs champs
Il est possible de combiner plusieurs expressions de requête de champ dans une seule requête en les répertoriant dans l'ordre et en les séparant par un caractère d'espacement. Un opérateur AND implicite est ainsi placé entre chaque expression, de sorte que toutes les expressions doivent être satisfaites pour récupérer un document. Vous pouvez ajouter des opérateurs AND et OR explicites entre des expressions, et utiliser des parenthèses pour clarifier la logique.
| Chaîne de requête | Commentaires |
|---|---|
"product=piano manufacturer=steinway""product=piano AND manufacturer=steinway"
|
Ces requêtes récupèrent tous les pianos de marque Steinway. Le caractère d'espacement entre les termes implique un AND logique ; la seconde forme le rend explicite. |
"product=piano AND NOT manufacturer=steinway"
|
Récupère tous les pianos de marque autre que Steinway. |
"product=piano AND price<2000" |
Cette requête récupère des pianos d'entrée de gamme. |
Combiner recherche globale et recherche de champ
Une chaîne de requête peut contenir un nombre indéfini d'expressions de recherche globale et d'expressions de recherche de champ. Les espaces entre les expressions sont considérés comme AND. Vous pouvez également utiliser OR et AND explicitement, avec des parenthèses. Chaque expression est traitée selon les règles associées à ce type de terme.
| Chaîne de requête | Commentaires |
|---|---|
"keyboard great price<5000"
|
Récupère les documents pour lesquels les mots "great" et "keyboard" apparaissent dans n'importe quel champ de texte, HTML ou Atom, et dont la valeur du champ "price" est inférieure à 5 000.
L'opérateur AND est implicite et la seconde forme est équivalente.
|
"keyboard OR product=piano" |
Récupère les documents dont le champ "product" contient le terme "piano", ou les documents qui comportent un champ de texte, HTML ou Atom contenant le terme "keyboard". |