Opérateurs de requête
Les opérateurs sont signalés par le préfixe dollar ($) dans la zone de nom.
La syntaxe de sélecteur possède deux types principaux d'opérateurs :
- Opérateurs de combinaison
- Opérateurs de condition
En général, les opérateurs de combinaison sont appliqués au niveau de sélection le plus élevé. Ils sont utilisés pour combiner des conditions ou pour créer des combinaisons de conditions dans un sélecteur unique.
Le format de chaque opérateur explicite est le suivant :
{
"$operator": "argument"
}
Un sélecteur sans opérateur explicite est supposé posséder un opérateur implicite. L'opérateur implicite exact est déterminé par la structure de l'expression de sélecteur.
Opérateurs implicites
Les deux opérateurs implicites sont les suivants :
- "Equality"
- "Et"
Dans un sélecteur, toute zone contenant une valeur JSON qui ne comporte pas d'opérateur est considérée comme une condition d'égalité. Le test d'égalité implicite s'applique également aux zones et aux sous-zones.
Tout objet JSON qui ne constitue pas un argument d'un opérateur de condition est un opérateur $and implicite pour chaque zone.
Voici un exemple de sélecteur qui utilise un opérateur pour mettre en correspondance des documents, où la zone year possède une valeur supérieure à 2010 :
{
"selector": {
"year": {
"$gt": 2010
}
}
}
Dans l'exemple ci-dessous, les documents correspondants doivent posséder une zone nommée director et la zone doit avoir une valeur exactement égale à Lars von Trier.
Voici un exemple d'opérateur d'égalité implicite :
{
"director": "Lars von Trier"
}
Vous pouvez également rendre l'opérateur d'égalité explicite, conformément à l'exemple ci-dessous.
Voici un exemple d'opérateur d'égalité explicite :
{
"director": {
"$eq": "Lars von Trier"
}
}
Dans l'exemple ci-dessous qui utilise des sous-zones, la zone imdb dans un document correspondant doit également posséder une sous-zone rating
et la sous-zone doit avoir une valeur égale à 8.
Voici un exemple d'opérateur implicite appliqué à un test de sous-zone :
{
"imdb": {
"rating": 8
}
}
Vous pouvez rendre l'opérateur d'égalité explicite.
Voici un exemple d'opérateur d'égalité explicite :
{
"selector": {
"imdb": {
"rating": { "$eq": 8 }
}
}
}
Voici un exemple d'opérateur $eq qui est utilisé avec une indexation en texte intégral :
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"title:string"
],
"fields": [
"title"
]
}
Voici un exemple d'opérateur $eq qui est utilisé avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
Dans l'exemple suivant, la zone director doit être présente et contenir la valeur Lars von TrierEt la zone year doit exister et avoir la valeur 2003.
Voici un exemple d'opérateur $and implicite :
{
"director": "Lars von Trier",
"year": 2003
}
Vous pouvez rendre l'opérateur $and et l'opérateur d'égalité explicites.
Voici un exemple qui utilise des opérateurs $and et $eq explicites :
{
"$and": [
{
"director": {
"$eq": "Lars von Trier"
}
},
{
"year": {
"$eq": 2003
}
}
]
}
Opérateurs explicites
Tous les opérateurs, sauf les opérateurs $eq (égalité) et $and (et), doivent être mentionnés explicitement.
Opérateurs de combinaison
Les opérateurs de combinaison sont utilisés pour combiner des sélecteurs. Trois opérateurs de combinaison ($all, $allMatch et $elemMatch) permettent de traiter les tableaux JSON, en plus des opérateurs
booléens communs qui existent dans la plupart des langages de programmation.
Un opérateur de combinaison admet un argument unique. L'argument est un autre sélecteur ou un tableau de sélecteurs.
| Opérateur | Argument | Objectif |
|---|---|---|
$all |
Tableau | Mise en correspondance d'une valeur de tableau si elle contient tous les éléments du tableau d'arguments. |
$allMatch |
Sélecteur | Mise en correspondance et renvoi de tous les documents contenant une zone de tableau, où tous les éléments correspondent à tous les critères de requête spécifiés. |
$and |
Tableau | Correspondance si tous les sélecteurs du tableau correspondent. |
$elemMatch |
Sélecteur | Mise en correspondance et renvoi de tous les documents contenant une zone de tableau avec au moins un élément correspondant à tous les critères de requête spécifiés. |
$nor |
Tableau | Correspondance si aucun des sélecteurs du tableau ne correspond. |
$not |
Sélecteur | Correspondance si le sélecteur ne correspond pas. |
$or |
Tableau | Correspondance si l'un des sélecteurs du tableau correspond. Tous les sélecteurs doivent utiliser le même index. |
$all
L'opérateur $all met en correspondance une valeur de tableau si elle contient tous les éléments du tableau d'arguments.
Voici un exemple qui utilise l'opérateur $all :
{
"selector": {
"genre": {
"$all": ["Comedy","Short"]
}
},
"fields": [
"title",
"genre"
],
"limit": 10
}
$allMatch
L'opérateur $allMatch identifie des correspondances et renvoie tous les documents contenant une zone de tableau, où les éléments dans la zone de tableau correspondent aux critères de requête fournis.
Voici un exemple qui utilise l'opérateur $allMatch :
{
"genre": {
"$allMatch": {
"$eq": "Horror"
}
}
}
$and
L'opérateur $and identifie des correspondances si tous les sélecteurs du tableau correspondent.
Voici un exemple qui utilise l'opérateur $and :
{
"selector": {
"$and": [
{
"year": {
"$in": [2014, 2015]
}
},
{
"genre": {
"$all": ["Comedy","Short"]
}
}
]
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$elemMatch
L'opérateur $elemMatch identifie des correspondances et renvoie tous les documents contenant une zone de tableau avec au moins un élément correspondant aux critères de recherche fournis.
Voici un exemple qui utilise l'opérateur $elemMatch :
{
"selector": {
"genre": {
"$elemMatch": {
"$eq": "Horror"
}
}
},
"fields": [
"title",
"genre"
],
"limit": 10
}
$nor
L'opérateur $nor identifie des correspondances si le sélecteur ne correspond pas.
Voici un exemple qui utilise l'opérateur $nor :
{
"selector": {
"year": {
"$gte": 1900,
"$lte": 1910
},
"$nor": [
{ "year": 1901 },
{ "year": 1905 },
{ "year": 1907 }
]
},
"fields": [
"title",
"year"
]
}
$not
L'opérateur $not identifie des correspondances si le sélecteur n'est pas résolu en valeur true.
Voici un exemple qui utilise l'opérateur $not :
{
"selector": {
"year": {
"$gte": 1900,
"$lte": 1903
},
"$not": {
"year": 1901
}
},
"fields": [
"title",
"year"
]
}
$or
L'opérateur $or identifie des correspondances si l'un des sélecteurs du tableau correspond.
Voici un exemple qui utilise l'opérateur $or :
{
"selector": {
"year": 1977,
"$or": [
{ "director": "George Lucas" },
{ "director": "Steven Spielberg" }
]
},
"fields": [
"title",
"director",
"year"
]
}
Opérateurs de condition
Les opérateurs de condition sont propres à une zone et sont utilisés pour évaluer la valeur stockée dans cette zone. Par exemple, l'opérateur $eq correspond lorsque la zone spécifiée contient une valeur qui est égale à l'argument
fourni.
Les opérateurs d'égalité et d'inégalité de base communs à la plupart des langages de programmation sont pris en charge. Certains opérateurs de condition "méta" sont également disponibles.
Certains opérateurs de condition acceptent tous les contenus JSON valides comme argument. D'autres opérateurs de condition exigent un format JSON spécifique pour l'argument.
| Type d'opérateur | Opérateur | Argument | Objectif |
|---|---|---|---|
| (In)égalité | $lt |
Tout JSON | La zone est inférieure à l'argument. |
$lte |
Tout JSON | La zone est inférieure ou égale à l'argument. | |
$eq |
Tout JSON | La zone est égale à l'argument. | |
$ne |
Tout JSON | La zone n'est pas égale à l'argument. | |
$gte |
Tout JSON | La zone est supérieure ou égale à l'argument. | |
$gt |
Tout JSON | La zone est supérieure à l'argument. | |
| Objet | $exists |
Booléen | Vérifier si la zone existe ou non, quelle que soit sa valeur. |
$type |
Chaîne | Vérifier le type de la zone de document. Les valeurs admises sont null, boolean, number, string, array et object. |
|
| Tableau | $in |
Tableau de valeurs JSON | La zone de document doit figurer dans la liste fournie. |
$nin |
Tableau de valeurs JSON | La zone de document ne doit pas figurer dans la liste fournie. | |
$size |
Entier | Condition spéciale pour la mise en correspondance de la longueur d'une zone de tableau dans un document. Les zones autres que les zones de tableau ne peuvent pas correspondre à cette condition. | |
| Divers | $mod |
[Diviseur, reste] | Divisor et Remainder (le diviseur et le reste) sont des entiers positifs ou négatifs. Les valeurs non entières entraînent un statut 404. Mise
en correspondance des documents où l'expression (field % Divisor == Remainder) est vérifiée et uniquement lorsque la zone de document est un entier. |
$regex |
Chaîne | Modèle d'expression régulière à mettre en correspondance avec la zone de document. Mise en correspondance uniquement lorsque la zone est une valeur de chaîne et correspond à l'expression régulière fournie. |
Les expressions régulières ne fonctionnent pas avec les index ; par conséquent, elles ne doivent pas être utilisées pour filtrer des ensembles de données volumineux. Toutefois, elles peuvent être utilisées pour restreindre un partial index <find/partial_indexes>.
$lt
L'opérateur $lt identifie des correspondances si le contenu de zone spécifié est inférieur à l'argument.
Voici un exemple qui utilise l'opérateur $lt avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$lt": 1900
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Voici un exemple qui utilise l'opérateur $lt avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$lt": 1900
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$lte
L'opérateur $lte identifie des correspondances si le contenu de zone spécifié est inférieur ou égal à l'argument.
Voici un exemple qui utilise l'opérateur $lte avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$lte": 1900
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Voici un exemple qui utilise l'opérateur $lte avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$lte": 1900
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$eq
L'opérateur $eq identifie des correspondances si le contenu de zone spécifié est égal à l'argument fourni.
Voici un exemple qui utilise l'opérateur $eq avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"title:string"
],
"fields": [
"title"
]
}
Voici un exemple qui utilise l'opérateur $eq avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$ne
L'opérateur $ne identifie des correspondances si le contenu de zone spécifié n'est pas égal à l'argument fourni.
L'opérateur $ne ne peut pas être l'élément (de niveau inférieur) de base dans un sélecteur lorsque vous utilisez un index de type json.
Voici un exemple qui utilise l'opérateur $ne avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$ne": 1892
}
},
"fields": [
"year"
],
"sort": [
"year:number"
]
}
Voici un exemple qui utilise l'opérateur $ne avec un index primaire :
{
"selector": {
"year": {
"$ne": 1892
}
},
"fields": [
"year"
],
"limit": 10
}
$gte
L'opérateur $gte identifie des correspondances si le contenu de zone spécifié est supérieur ou égal à l'argument.
Voici un exemple qui utilise l'opérateur $gte avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$gte": 2001
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Voici un exemple qui utilise l'opérateur $gte avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$gte": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$gt
L'opérateur $gt identifie des correspondances si le contenu de zone spécifié est supérieur à l'argument.
Voici un exemple qui utilise l'opérateur $gt avec l'indexation en texte intégral :
{
"selector": {
"year": {
"$gt": 2001
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Voici un exemple qui utilise l'opérateur $gt avec une base de données indexée sur la zone year :
{
"selector": {
"year": {
"$gt": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$exists
L'opérateur $exists identifie des correspondances si la zone existe, quelle que soit sa valeur.
Voici un exemple qui utilise l'opérateur $exists :
{
"selector": {
"year": 2015,
"title": {
"$exists": true
}
},
"fields": [
"year",
"_id",
"title"
]
}
$type
L'opérateur $type requiert que la zone de document spécifiée soit du type approprié.
Voici un exemple qui utilise l'opérateur $type :
{
"selector": {
"year": {
"$type": "number"
}
},
"fields": [
"year",
"_id",
"title"
]
}
$in
L'opérateur $in requiert que la zone de document figure dans la liste fournie.
Voici un exemple qui utilise l'opérateur $in :
{
"selector": {
"year": {
"$in": [2010, 2015]
}
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$nin
L'opérateur $nin requiert que la zone de document ne figure pas dans la liste fournie.
Voici un exemple qui utilise l'opérateur $nin :
{
"selector": {
"year": {
"$nin": [2010, 2015]
}
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$size
L'opérateur $size met en correspondance la longueur d'une zone de tableau dans un document.
Voici un exemple qui utilise l'opérateur $size :
{
"selector": {
"genre": {
"$size": 4
}
},
"fields": [
"title",
"genre"
],
"limit": 25
}
$mod
L'opérateur $mod met en correspondance les documents où l'expression (field % Divisor == Remainder) est vérifiée et uniquement lorsque la zone de document est un entier. Le diviseur et le reste doivent être des entiers.
Il peut s'agir d'entiers positifs ou négatifs. Une requête dans laquelle le diviseur ou le reste n'est pas un nombre entier renvoie un code d'état 404.
Lorsque vous utilisez des valeurs entières négatives pour le diviseur ou le reste, l'opérateur IBM® Cloudant® for IBM Cloud® $mod utilise la division tronquée.
Les sites Opérateur « modulo » dans l' rem e Erlang et % opérateur en C fonctionnent de manière similaire
Voici un exemple qui utilise l'opérateur $mod :
{
"selector": {
"year": {
"$mod": [100,0]
}
},
"fields": [
"title",
"year"
],
"limit": 50
}
$regex
L'opérateur $regex identifie des correspondances lorsque la zone est une valeur de chaîne et qu'elle correspond à l'expression régulière fournie.
Voici un exemple qui utilise l'opérateur $regex :
{
"selector": {
"cast": {
"$elemMatch": {
"$regex": "^Robert"
}
}
},
"fields": [
"title",
"cast"
],
"limit": 10
}