Abfrageoperatoren

Operatoren werden durch ein Dollarzeichenpräfix ($) im Namensfeld gekennzeichnet.

Die Selektorsyntax hat zwei Kerntypen von Operatoren:

  • Kombinationsoperatoren
  • Bedingungsoperatoren

Im Allgemeinen werden Kombinationsoperatoren auf der höchsten Auswahlebene angewendet. Sie werden zum Kombinieren von Bedingungen oder zum Erstellen von Kombinationen von Bedingungen in einem einzelnen Selektor verwendet.

Jeder explizite Operator hat die folgende Form:

{
	"$operator": "argument"
}

Ein Selektor ohne expliziten Operator wird als Selektor mit einem impliziten Operator betrachtet. Der genaue implizite Operator wird durch die Struktur des Selektorausdrucks bestimmt.

Implizite Operatoren

Die folgende Liste zeigt die beiden impliziten Operatoren:

  • Gleichheitsoperator
  • "Und"

In einem Selektor wird jedes Feld, das einen JSON-Wert, jedoch keine Operatoren enthält, als Gleichheitsbedingung betrachtet. Der implizite Gleichheitstest gilt auch für Felder und Unterfelder.

Jedes JSON-Objekt, das kein Argument für einen Bedingungsoperator ist, ist ein impliziter Operator $and für jedes Feld.

Im folgenden Beispiel für einen Selektor wird ein Operator zur Suche aller Dokumente verwendet, in denen das Feld year einen Wert größer als 2010 hat:

{
	"selector": {
		"year": {
			"$gt": 2010
		}
	}
}

Im folgenden Beispiel muss ein übereinstimmendes Dokument ein Feld mit dem Namen director enthalten und das Feld muss genau den Wert Lars von Trier haben.

Beispiel für einen impliziten Gleichheitsoperator:

{
	"director": "Lars von Trier"
}

Sie können den Gleichheitsoperator auch explizit angeben, wie im folgenden Beispiel gezeigt.

Beispiel für einen expliziten Gleichheitsoperator:

{
	"director": {
		"$eq": "Lars von Trier"
	}
}

Im folgenden Beispiel, in dem Unterfelder verwendet werden, imdbmuss* das Feld * in einem übereinstimmenden Dokument auch ein Unterfeld rating enthalten und das Unterfeld muss einen Wert gleich 8 haben.

Beispiel für einen impliziten Operator, der auf einen Unterfeldtest angewendet wird:

{
	"imdb": {
		"rating": 8
	}
}

Sie können den Gleichheitsoperator explizit angeben.

Beispiel für einen expliziten Gleichheitsoperator:

{
	"selector": {
		"imdb": {
			"rating": { "$eq": 8 }
		}
	}
}

Beispiel für einen Operator $eq, der bei einer Volltextindexierung verwendet wird:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"title:string"
	],
	"fields": [
		"title"
	]
}

Beispiel für einen Operator $eq, der mit einer Datenbank verwendet wird, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

Im folgenden Beispiel muss das Feld director vorhanden sein und den Wert Lars von Trier* enthalten und* das Feld year muss vorhanden sein und den Wert 2003 haben.

Beispiel für einen impliziten Operator $and:

{
	"director": "Lars von Trier",
	"year": 2003
}

Sie können beide Operatoren $and und den Gleichheitsoperator explizit angeben.

Beispiel mit expliziten Operatoren $and und $eq:

{
	"$and": [
		{
			"director": {
				"$eq": "Lars von Trier"
			}
		},
		{
			"year": {
				"$eq": 2003
			}
		}
	]
}

Explizite Operatoren

Alle Operatoren mit Ausnahme der Operatoren $eq (Gleichheit) und $and (und) müssen explizit angegeben werden.

Kombinationsoperatoren

Kombinationsoperatoren dienen zum Kombinieren von Selektoren. Zusätzlich zu den gängigen booleschen Operatoren der meisten Programmiersprachen können Sie drei Kombinationsoperatoren ($all, $allMatch und $elemMatch) zur Arbeit mit JSON-Arrays verwenden.

Ein Kombinationsoperator akzeptiert ein einzelnes Argument. Das Argument ist entweder ein anderer Selektor oder ein Array von Selektoren.

Kombinationsoperatoren
Operator Argument Zweck
$all Array Erkennt einen Array-Wert als Übereinstimmung, wenn er alle Elemente des Argumentarrays enthält.
$allMatch Selektor Erkennt alle Dokumente, die ein Array-Feld enthalten, in dem alle Elemente allen angegebenen Abfragekriterien entsprechen, als Übereinstimmung und gibt die Dokumente zurück.
$and Array Liefert eine Überstimmung, wenn alle Selektoren im Array übereinstimmen.
$elemMatch Selektor Erkennt alle Dokumente, die ein Array-Feld mit mindestens einem Element enthalten, das allen angegebenen Abfragekriterien entspricht, als Übereinstimmung und gibt die Dokumente zurück.
$nor Array Liefert eine Überstimmung, wenn keine der Selektoren im Array übereinstimmen.
$not Selektor Liefert eine Übereinstimmung, wenn der Selektor nicht übereinstimmt.
$or Array Liefert eine Überstimmung, wenn beliebige der Selektoren im Array übereinstimmen. Alle Selektoren müssen denselben Index verwenden.

$all

Der Operator $all erkennt einen Array-Wert als Übereinstimmung, wenn dieser alle Elemente des Argumentarrays enthält.

Beispiel mit dem Operator $all:

{
	"selector": {
		"genre": {
			"$all": ["Comedy","Short"]
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 10
}

$allMatch

Der Operator $allMatch erkennt alle Dokumente als Übereinstimmung, die ein Array-Feld enthalten, in dem alle Elemente mit den angegebenen Abfragekriterien übereinstimmen.

Beispiel mit dem Operator $allMatch:

{
    "genre": {
        "$allMatch": {
          "$eq": "Horror"
        }
    }
}

$and

Der Operator $and liefert eine Übereinstimmung, wenn alle Selektoren im Array übereinstimmen.

Beispiel mit dem Operator $and:

{
    "selector": {
        "$and": [
            {
                "year": {
                    "$in": [2014, 2015]
                }
            },
            {
                "genre": {
                     "$all": ["Comedy","Short"]
                 }
            }
        ]
    },
    "fields": [
        "year",
        "_id",
        "title"
    ],
    "limit": 10
}

$elemMatch

Der Operator $elemMatch erkennt alle Dokumente, die ein Array-Feld mit mindestens einem Element enthalten, das den angegebenen Abfragekriterien entspricht, als Übereinstimmung und gibt die Dokumente zurück.

Beispiel mit dem Operator $elemMatch:

{
	"selector": {
		"genre": {
			"$elemMatch": {
				"$eq": "Horror"
			}
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 10
}

$nor

Der Operator $nor liefert eine Übereinstimmung, wenn der Selektor nicht übereinstimmt.

Beispiel mit dem Operator $nor:

{
	"selector": {
		"year": {
			"$gte": 1900,
			"$lte": 1910
		},
		"$nor": [
			{ "year": 1901 },
			{ "year": 1905 },
			{ "year": 1907 }
		]
	},
	"fields": [
		"title",
		"year"
	]
}

$not

Der Operator $not liefert eine Übereinstimmung, wenn der Selektor nicht in den Wert true aufgelöst wird.

Beispiel mit dem Operator $not:

{
	"selector": {
		"year": {
			"$gte": 1900,
			"$lte": 1903
		},
		"$not": {
			"year": 1901
		}
	},
	"fields": [
		"title",
		"year"
	]
}

$or

Der Operator $or liefert eine Übereinstimmung, wenn beliebige der Selektoren im Array übereinstimmen.

Beispiel mit dem Operator $or:

{
	"selector": {
		"year": 1977,
		"$or": [
			{ "director": "George Lucas" },
			{ "director": "Steven Spielberg" }
		]
	},
	"fields": [
		"title",
		"director",
		"year"
	]
}

Bedingungsoperatoren

Bedingungsoperatoren sind für ein Feld spezifisch und dienen zur Auswertung des Werts, der in diesem Feld enthalten ist. Der Operator $eq liefert zum Beispiel eine Übereinstimmung, wenn das angegebene Feld einen Wert enthält, der gleich dem angegebenen Argument ist.

Die Basisoperatoren für Gleichheit und Ungleichheit, die für die meisten Programmiersprachen gängig sind, werden unterstützt. Darüber hinaus sind auch einige "Meta"-Bedingungsoperatoren verfügbar.

Einige Bedingungsoperatoren akzeptieren beliebigen gültigen JSON-Inhalt als Argument. Für andere Bedingungsoperatoren muss das Argument ein bestimmtes JSON-Format haben.

Argumentanforderungen für Bedingungsoperatoren
Operatortyp Operator Argument Zweck
(Un-) Gleichheit $lt Beliebiges JSON Der Feldwert ist kleiner als der Argumentwert.
$lte Beliebiges JSON Der Feldwert ist kleiner als oder gleich dem Argumentwert.
$eq Beliebiges JSON Der Feldwert ist gleich dem Argumentwert.
$ne Beliebiges JSON Der Feldwert ist nicht gleich dem Argumentwert.
$gte Beliebiges JSON Der Feldwert ist größer als oder gleich dem Argumentwert.
$gt Beliebiges JSON Der Feldwert ist größer als der Argumentwert.
Object $exists Boolescher Wert Prüft unabhängig vom Wert, ob das Feld vorhanden ist oder nicht.
$type Zeichenfolge Prüft den Typ des Dokumentfelds. Gültige Werte: null, boolean, number, string, array, und object.
Array $in Array von JSON-Werten Das Dokumentfeld muss in der angegebenen Liste vorhanden sein.
$nin Array von JSON-Werten Das Dokumentfeld darf nicht in der angegebenen Liste vorhanden sein.
$size Integer Sonderbedingung zum Vergleich der Länge eines Array-Felds in einem Dokument. Nicht-Array-Felder können mit dieser Bedingung nicht verglichen werden.
Verschiedene $mod [Divisor, Rest] Divisor und Rest sind beide positive oder negative Ganzzahlen. Nicht-ganzzahlige Werte führen zu einem 404-Status. Sucht Dokumente, für die der Ausdruck (field % Divisor == Remainder) wahr ist, und dies nur, wenn das Dokumentfeld den Typ 'Ganzzahl' hat.
$regex Zeichenfolge Ein Muster für einen regulären Ausdruck zum Abgleich mit dem Dokumentfeld. Erkennt nur dann eine Übereinstimmung, wenn das Feld einen Zeichenfolgewert enthält, der dem angegebenen regulären Ausdruck entspricht.

Reguläre Ausdrücke funktionieren nicht mit Indizes. Daher dürfen sie nicht zum Filtern großer Datasets verwendet werden. Sie können jedoch dazu verwendet werden, einen partial index <find/partial_indexes> einzugrenzen.

$lt

Der Operator $lt liefert eine Übereinstimmung, wenn der angegebene Feldinhalt kleiner als der Argumentwert ist.

Beispiel mit dem Operator $lt bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$lt": 1900
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Beispiel für den Operator $lt mit einer Datenbank, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$lt": 1900
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

$lte

Der Operator $lte liefert eine Übereinstimmung, wenn der angegebene Feldinhalt kleiner als oder gleich dem Argumentwert ist.

Beispiel mit dem Operator $lte bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$lte": 1900
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Beispiel für den Operator $lte mit einer Datenbank, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$lte": 1900
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

$eq

Der Operator $eq liefert eine Übereinstimmung, wenn der angegebene Feldinhalt gleich dem Argumentwert ist.

Beispiel mit dem Operator $eq bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"title:string"
	],
	"fields": [
		"title"
	]
}

Beispiel für den Operator $eq mit einer Datenbank, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$eq": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

$ne

Der Operator $ne liefert eine Übereinstimmung, wenn der angegebene Feldinhalt nicht gleich dem Argumentwert ist.

Der Operator $ne kann nicht das Basiselement (auf unterster Ebene) in einem Selektor sein, wenn Sie einen Index vom Typ json verwenden.

Beispiel mit dem Operator $ne bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$ne": 1892
		}
	},
	"fields": [
		"year"
	],
	"sort": [
		"year:number"
	]
}

Beispiel mit dem Operator $ne und einem Primärindex:

{
	"selector": {
	"year": {
			"$ne": 1892
		}
	},
	"fields": [
		"year"
	],
	"limit": 10
}

$gte

Der Operator $gte liefert eine Übereinstimmung, wenn der angegebene Feldinhalt größer als oder gleich dem Argumentwert ist.

Beispiel mit dem Operator $gte bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$gte": 2001
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Beispiel für den Operator $gte mit einer Datenbank, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$gte": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

$gt

Der Operator $gt liefert eine Übereinstimmung, wenn der angegebene Feldinhalt größer als der Argumentwert ist.

Beispiel mit dem Operator $gt bei Volltextindexierung:

{
	"selector": {
		"year": {
			"$gt": 2001
		}
	},
	"sort": [
		"year:number",
		"title:string"
	],
	"fields": [
		"year",
		"title"
	]
}

Beispiel für den Operator $gt mit einer Datenbank, die über das Feld year indexiert ist:

{
	"selector": {
		"year": {
			"$gt": 2001
		}
	},
	"sort": [
		"year"
	],
	"fields": [
		"year"
	]
}

$exists

Der Operator $exists liefert eine Übereinstimmung, wenn das Feld vorhanden ist, und zwar unabhängig von dem Wert des Felds.

Beispiel mit dem Operator $exists:

{
	"selector": {
		"year": 2015,
		"title": {
			"$exists": true
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	]
}

$type

Der Operator $type erfordert, dass das angegebene Dokumentfeld den richtigen Typ hat.

Beispiel mit dem Operator $type:

{
	"selector": {
		  "year": {
			"$type": "number"
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	]
}

$in

Der Operator $in erfordert, dass das Dokumentfeld in der angegebenen Liste vorhanden sein muss.

Beispiel mit dem Operator $in:

{
	"selector": {
		  "year": {
			"$in": [2010, 2015]
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	],
	"limit": 10
}

$nin

Der Operator $nin erfordert, dass das Dokumentfeld in der angegebenen Liste nicht vorhanden sein darf.

Beispiel mit dem Operator $nin:

{
	"selector": {
		  "year": {
			"$nin": [2010, 2015]
		}
	},
	"fields": [
		"year",
		"_id",
		"title"
	],
	"limit": 10
}

$size

Der Operator $size gleicht die Länge eines Array-Felds in einem Dokument ab.

Beispiel mit dem Operator $size:

{
	"selector": {
		  "genre": {
			"$size": 4
		}
	},
	"fields": [
		"title",
		"genre"
	],
	"limit": 25
}

$mod

Der Operator $mod sucht Dokumente, für die der Ausdruck (field % Divisor == Remainder) wahr ist, und dies nur, wenn das Dokumentfeld den Typ 'Ganzzahl' hat. Der Divisor und der Rest müssen Ganzzahlen sein. Sie können positive oder negative Ganzzahlen sein. Eine Abfrage, bei der der Divisor oder der Rest kein ganzer Zahl ist, führt zu einem 404-Status.

Wenn Sie negative ganzzahlige Werte für den Divisor oder den Rest verwenden, wendet der Operator „ IBM® Cloudant® for IBM Cloud® “ $mod die abgeschnittene Division an. Sowohl der Modulo-Operator „ rem “ in Erlang als auch der Operator „ % “ in C verhalten sich auf ähnliche Weise.

Beispiel mit dem Operator $mod:

{
	"selector": {
          "year": {
			"$mod": [100,0]
		}
	},
	"fields": [
		"title",
		"year"
	],
	"limit": 50
}

$regex

Der Operator $regex liefert eine Übereinstimmung, wenn das Feld einen Zeichenfolgewert enthält und dem angegebenen regulären Ausdruck entspricht.

Beispiel mit dem Operator $regex:

{
	"selector": {
		   "cast": {
			"$elemMatch": {
				"$regex": "^Robert"
			}
		}
	},
	"fields": [
		"title",
		"cast"
	],
	"limit": 10
}