Operatori di query
Gli operatori sono identificati dall'uso del prefisso del segno del dollaro ($) nel campo del nome.
La sintassi dei selettori prevede due tipi principali di operatori:
- Operatori combinati
- Operatori delle condizioni
In generale, gli operatori di combinazione vengono applicati all'ultimo livello di selezione. Si usano per combinare le condizioni, o per creare combinazioni di condizioni, in un unico selettore.
Ogni operatore esplicito ha la forma:
{
"$operator": "argument"
}
Un selettore senza un operatore esplicito è considerato un operatore implicito. L'operatore implicito esatto è determinato dalla struttura dell'espressione del selettore.
Operatori impliciti
I due operatori impliciti sono illustrati nel seguente elenco:
- "Uguaglianza"
- "E"
In un selettore, qualsiasi campo che contenga un valore JSON, ma che non contenga operatori, è considerato una condizione di uguaglianza. Il test di uguaglianza implicita si applica anche ai campi e ai sottocampi.
Qualsiasi oggetto JSON che non sia l'argomento di un operatore di condizione è un operatore $and implicito su ogni campo.
Si veda il seguente esempio di selettore che utilizza un operatore per abbinare qualsiasi documento in cui il campo year ha un valore superiore a 2010:
{
"selector": {
"year": {
"$gt": 2010
}
}
}
Nell'esempio seguente, un documento corrispondente deve avere un campo chiamato director,
e il campo deve avere un valore esattamente uguale a Lars von Trier.
Si veda il seguente esempio dell'operatore di uguaglianza implicita:
{
"director": "Lars von Trier"
}
È anche possibile rendere esplicito l'operatore di uguaglianza, come mostrato nell'esempio seguente.
Si veda il seguente esempio di operatore di uguaglianza esplicito:
{
"director": {
"$eq": "Lars von Trier"
}
}
Nel seguente esempio che utilizza i sottocampi, il campo imdb in un documento corrispondente deve avere anche un sottocampo rating,
e il sottocampo deve avere un valore pari a 8.
Si veda il seguente esempio di operatore implicito applicato a un test di sottocampo:
{
"imdb": {
"rating": 8
}
}
È possibile rendere esplicito l'operatore di uguaglianza.
Si veda il seguente esempio di operatore di uguaglianza esplicito:
{
"selector": {
"imdb": {
"rating": { "$eq": 8 }
}
}
}
Si veda il seguente esempio di operatore $eq utilizzato con l'indicizzazione full text:
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"title:string"
],
"fields": [
"title"
]
}
Si veda il seguente esempio di operatore $eq utilizzato con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
Nell'esempio seguente, il campo director deve essere presente e contenere il valore Lars von Trier
e il campo year deve esistere e avere il valore 2003.
Si veda il seguente esempio di operatore implicito $and:
{
"director": "Lars von Trier",
"year": 2003
}
È possibile rendere espliciti sia l'operatore $and che l'operatore di uguaglianza.
Si veda il seguente esempio che utilizza gli operatori espliciti $and e $eq:
{
"$and": [
{
"director": {
"$eq": "Lars von Trier"
}
},
{
"year": {
"$eq": 2003
}
}
]
}
Operatori espliciti
Tutti gli operatori, ad eccezione degli operatori $eq (uguaglianza) e $and (e), devono essere dichiarati esplicitamente.
Operatori combinati
Gli operatori di combinazione sono usati per combinare i selettori. Tre operatori combinati ($all, $allMatch e $elemMatch) aiutano a lavorare con gli array JSON, oltre ai comuni operatori booleani presenti
nella maggior parte dei linguaggi di programmazione.
Un operatore di combinazione accetta un singolo argomento. L'argomento è un altro selettore o un array di selettori.
| Operatore | Argomento | Scopo |
|---|---|---|
$all |
Array | Corrisponde al valore di una matrice se contiene tutti gli elementi della matrice di argomenti. |
$allMatch |
Selettore | Corrisponde e restituisce tutti i documenti che contengono un campo array, in cui tutti gli elementi corrispondono a tutti i criteri di interrogazione specificati. |
$and |
Array | Corrisponde se tutti i selettori dell'array corrispondono. |
$elemMatch |
Selettore | Corrisponde e restituisce tutti i documenti che contengono un campo array con almeno un elemento che corrisponde a tutti i criteri di interrogazione specificati. |
$nor |
Array | Corrisponde se nessuno dei selettori dell'array corrisponde. |
$not |
Selettore | Corrisponde se il selettore non corrisponde. |
$or |
Array | Corrisponde se uno qualsiasi dei selettori dell'array corrisponde. Tutti i selettori devono utilizzare lo stesso indice. |
$all
L'operatore $all corrisponde a un valore di matrice se contiene tutti gli elementi della matrice di argomento.
Si veda il seguente esempio che utilizza l'operatore $all:
{
"selector": {
"genre": {
"$all": ["Comedy","Short"]
}
},
"fields": [
"title",
"genre"
],
"limit": 10
}
$allMatch
L'operatore $allMatch corrisponde e restituisce tutti i documenti che contengono un campo array, in cui tutti gli elementi della matrice corrispondono ai criteri di interrogazione forniti.
Si veda il seguente esempio che utilizza l'operatore $allMatch:
{
"genre": {
"$allMatch": {
"$eq": "Horror"
}
}
}
$and
L'operatore $and corrisponde se tutti i selettori dell'array corrispondono.
Si veda il seguente esempio che utilizza l'operatore $and:
{
"selector": {
"$and": [
{
"year": {
"$in": [2014, 2015]
}
},
{
"genre": {
"$all": ["Comedy","Short"]
}
}
]
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$elemMatch
L'operatore $elemMatch corrisponde e restituisce tutti i documenti che contengono un campo dell'array con almeno un elemento che corrisponde ai criteri di ricerca forniti.
Si veda il seguente esempio che utilizza l'operatore $elemMatch:
{
"selector": {
"genre": {
"$elemMatch": {
"$eq": "Horror"
}
}
},
"fields": [
"title",
"genre"
],
"limit": 10
}
$nor
L'operatore $nor corrisponde se il selettore non corrisponde.
Si veda il seguente esempio che utilizza l'operatore $nor:
{
"selector": {
"year": {
"$gte": 1900,
"$lte": 1910
},
"$nor": [
{ "year": 1901 },
{ "year": 1905 },
{ "year": 1907 }
]
},
"fields": [
"title",
"year"
]
}
$not
L'operatore $not corrisponde se il selettore non si risolve in un valore di true.
Si veda il seguente esempio che utilizza l'operatore $not:
{
"selector": {
"year": {
"$gte": 1900,
"$lte": 1903
},
"$not": {
"year": 1901
}
},
"fields": [
"title",
"year"
]
}
$or
L'operatore $or corrisponde se uno qualsiasi dei selettori dell'array corrisponde.
Si veda il seguente esempio che utilizza l'operatore $or:
{
"selector": {
"year": 1977,
"$or": [
{ "director": "George Lucas" },
{ "director": "Steven Spielberg" }
]
},
"fields": [
"title",
"director",
"year"
]
}
Operatori delle condizioni
Gli operatori di condizione sono specifici per un campo, e vengono usati per valutare il valore memorizzato in quel campo. Ad esempio, l'operatore $eq corrisponde quando il campo specificato contiene un valore uguale all'argomento
fornito.
Sono supportati gli operatori di uguaglianza e disuguaglianza comuni alla maggior parte dei linguaggi di programmazione. Sono disponibili anche alcuni "meta" operatori di condizione.
Alcuni operatori di condizione accettano come argomento qualsiasi contenuto JSON valido. Altri operatori di condizione richiedono che l'argomento sia in un formato JSON specifico.
| Tipo di operatore | Operatore | Argomento | Scopo |
|---|---|---|---|
| uguaglianza (in) | $lt |
Qualsiasi JSON | Il campo è inferiore all'argomento. |
$lte |
Qualsiasi JSON | Il campo è minore o uguale all'argomento. | |
$eq |
Qualsiasi JSON | Il campo è uguale all'argomento. | |
$ne |
Qualsiasi JSON | Il campo non è uguale all'argomento. | |
$gte |
Qualsiasi JSON | Il campo è maggiore o uguale all'argomento. | |
$gt |
Qualsiasi JSON | Il campo è maggiore dell'argomento. | |
| Oggetto | $exists |
Booleano | Controlla se il campo esiste o meno, indipendentemente dal suo valore. |
$type |
Stringa | Controllare il tipo di campo del documento. I valori accettati sono null, boolean, number, string, array e object. |
|
| Array | $in |
Array di valori JSON | Il campo del documento deve essere presente nell'elenco fornito. |
$nin |
Array di valori JSON | Il campo del documento non deve esistere nell'elenco fornito. | |
$size |
Numero intero | Condizione speciale per la corrispondenza con la lunghezza di un campo array in un documento. I campi non a matrice non possono soddisfare questa condizione. | |
| Miscellaneous | $mod |
[Divisore, resto] | Divisore e resto sono entrambi numeri interi positivi o negativi. I valori non interi comportano lo stato 404. Corrisponde ai documenti in
cui l'espressione (field % Divisor == Remainder) è vera e solo quando il campo del documento è un numero intero. |
$regex |
Stringa | Un modello di espressione regolare da confrontare con il campo del documento. Corrisponde solo se il campo è un valore stringa e corrisponde all'espressione regolare fornita. |
Le espressioni regolari non funzionano con gli indici, quindi non devono essere usate per filtrare grandi insiemi di dati. Tuttavia, possono essere utilizzati per limitare un partial index <find/partial_indexes>.
$lt
L'operatore $lt corrisponde se il contenuto del campo specificato è inferiore all'argomento.
Si veda il seguente esempio che utilizza l'operatore $lt con l'indicizzazione full-text:
{
"selector": {
"year": {
"$lt": 1900
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Si veda il seguente esempio che utilizza l'operatore $lt con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$lt": 1900
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$lte
L'operatore $lte corrisponde se il contenuto del campo specificato è minore o uguale all'argomento.
Si veda il seguente esempio che utilizza l'operatore $lte con l'indicizzazione full-text:
{
"selector": {
"year": {
"$lte": 1900
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Si veda il seguente esempio che utilizza l'operatore $lte con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$lte": 1900
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$eq
L'operatore $eq corrisponde se il contenuto del campo specificato è uguale all'argomento fornito.
Si veda il seguente esempio che utilizza l'operatore $eq con l'indicizzazione full-text:
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"title:string"
],
"fields": [
"title"
]
}
Si veda il seguente esempio che utilizza l'operatore $eq con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$eq": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$ne
L'operatore $ne corrisponde se il contenuto del campo specificato non è uguale all'argomento fornito.
L'operatore $ne non può essere l'elemento di base (di livello più basso) in un selettore quando si usa un indice di tipo json.
Si veda il seguente esempio che utilizza l'operatore $ne con l'indicizzazione full-text:
{
"selector": {
"year": {
"$ne": 1892
}
},
"fields": [
"year"
],
"sort": [
"year:number"
]
}
Si veda il seguente esempio che utilizza l'operatore $ne con un indice primario:
{
"selector": {
"year": {
"$ne": 1892
}
},
"fields": [
"year"
],
"limit": 10
}
$gte
L'operatore $gte corrisponde se il contenuto del campo specificato è maggiore o uguale all'argomento.
Si veda il seguente esempio che utilizza l'operatore $gte con l'indicizzazione full-text:
{
"selector": {
"year": {
"$gte": 2001
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Si veda il seguente esempio che utilizza l'operatore $gte con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$gte": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$gt
L'operatore $gt corrisponde se il contenuto del campo specificato è maggiore dell'argomento.
Si veda il seguente esempio che utilizza l'operatore $gt con l'indicizzazione full-text:
{
"selector": {
"year": {
"$gt": 2001
}
},
"sort": [
"year:number",
"title:string"
],
"fields": [
"year",
"title"
]
}
Si veda il seguente esempio che utilizza l'operatore $gt con un database indicizzato sul campo year:
{
"selector": {
"year": {
"$gt": 2001
}
},
"sort": [
"year"
],
"fields": [
"year"
]
}
$exists
L'operatore $exists corrisponde se il campo esiste, indipendentemente dal suo valore.
Si veda il seguente esempio che utilizza l'operatore $exists:
{
"selector": {
"year": 2015,
"title": {
"$exists": true
}
},
"fields": [
"year",
"_id",
"title"
]
}
$type
L'operatore $type richiede che il campo del documento specificato sia del tipo corretto.
Si veda il seguente esempio che utilizza l'operatore $type:
{
"selector": {
"year": {
"$type": "number"
}
},
"fields": [
"year",
"_id",
"title"
]
}
$in
L'operatore $in richiede che il campo del documento esista nell'elenco fornito.
Si veda il seguente esempio che utilizza l'operatore $in:
{
"selector": {
"year": {
"$in": [2010, 2015]
}
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$nin
L'operatore $nin richiede che il campo del documento non es ista nell'elenco fornito.
Si veda il seguente esempio che utilizza l'operatore $nin:
{
"selector": {
"year": {
"$nin": [2010, 2015]
}
},
"fields": [
"year",
"_id",
"title"
],
"limit": 10
}
$size
L'operatore $size corrisponde alla lunghezza di un campo array in un documento.
Si veda il seguente esempio che utilizza l'operatore $size:
{
"selector": {
"genre": {
"$size": 4
}
},
"fields": [
"title",
"genre"
],
"limit": 25
}
$mod
L'operatore $mod corrisponde ai documenti in cui l'espressione (field % Divisor == Remainder) è vera, e solo quando il campo del documento è un intero. Il divisore e il resto devono essere numeri interi. Possono essere
numeri interi positivi o negativi. Una query in cui il divisore o il resto è un numero non intero restituisce uno stato 404.
Quando si utilizzano valori interi negativi per il divisore o il resto, l'operatore IBM® Cloudant® for IBM Cloud® $mod utilizza la divisione tronca.
Sia l'operatore modulo di Erlang rem sia l'operatore % in C, si comportano in modo simile.
Si veda il seguente esempio che utilizza l'operatore $mod:
{
"selector": {
"year": {
"$mod": [100,0]
}
},
"fields": [
"title",
"year"
],
"limit": 50
}
$regex
L'operatore $regex corrisponde quando il campo è un valore stringa e corrisponde all'espressione regolare fornita.
Si veda il seguente esempio che utilizza l'operatore $regex:
{
"selector": {
"cast": {
"$elemMatch": {
"$regex": "^Robert"
}
}
},
"fields": [
"title",
"cast"
],
"limit": 10
}