PHP 8.4.1 Released!

MongoDB\Driver\Query::__construct

(mongodb >=1.0.0)

MongoDB\Driver\Query::__constructCréer une nouvelle requête

Description

final public MongoDB\Driver\Query::__construct(array|object $filter, ?array $queryOptions = null)

Construit un nouvel objet MongoDB\Driver\Query, qui est un objet de valeur immuable qui représente une requête de base de données. La requête peut ensuite être exécutée avec MongoDB\Driver\Manager::executeQuery().

Liste de paramètres

filter (array|object)

L'» attribut de la requête. Un attribut vide va faire correspondre tous les documents de la collection.

Note: Lors de l'évaluation des critères de requête, MongoDB compare les type et les valeurs en fonction de leur propre » règles de comparaison pour les types BSON, qui diffère des règles de comparaison et de manipulation des type de PHP. Lors de la correspondance d'un type BSON spcécial, les critères de requête doivent utiliser la classe BSON (ex. : utiliser MongoDB\BSON\ObjectId pour correspondre à un » ObjectId).

queryOptions

queryOptions
Option Type Description
allowDiskUse bool

Autorise MongoDB à utiliser des fichiers temporaires sur le disque pour stocker des données dépassant la limite de mémoire système de 100 mégaoctets lors du traitement d'une opération de tri bloquante.

allowPartialResults bool

Pour les requêtes sur une collection fragmentée, retourne des résultats partiels du mongos si certains fragments ne sont pas disponibles au lieu de générer une erreur.

Retombe sur l'option dépréciée "partial" si non spécifiée.

awaitData bool Utiliser en conjonction avec l'option "tailable" pour bloquer temporairement une opération getMore sur le curseur si à la fin des données plutôt que de ne pas retourner de données. Après une période d'attente, la requête se termine normalement.
batchSize int

Le nombre de documents à retourner dans le premier lot. Par défaut à 101. Une taille de lot de 0 signifie que le curseur sera établi, mais aucun document ne sera retourné dans le premier lot.

Dans les versions de MongoDB antérieures à 3.2, où les requêtes utilisent le protocole de filaire hérité OP_QUERY, une taille de lot de 1 fermera le curseur indépendamment du nombre de documents.

collation array|object

» Collation permet aux utilisateurs de spécifier des règles spécifiques au langage pour la comparaison des chaînes, par exemple, des règles pour les majuscules ou les accents. Lors de la spécification d'une collation, le champ "locale" est obligatoire ; tous les autres champs de la collation sont optionnels. Pour la description de ces champs, reportez-vous au » document Collation.

Si la collation n'est pas spécifiée mais que la collection a une collation par défaut, l'opération utilisera la collation spécifiée pour la collection. Si aucune collation n'est spécifiée pour la collection ou pour l'opération, MongoDB utilisera le binaire simple de comparaison utilisé dans les versions précédentes pour les comparaisons des chaînes.

Cette option est disponible en MongoDB 3.4+ et une exception sera émise au moment de l'exécution si elle est spécifiée dans une version antérieure.

comment mixed

Un commentaire arbitraire pour aider à tracer l'opération à travers le profil de la base de données, la sortie currentOp et les journaux.

Le commentaire peut être n'importe quel type BSON valide pour MongoDB 4.4+. Les versions de serveur antérieures ne prennent en charge que les valeurs de chaîne.

Retombe sur l'option dépréciée "$comment" si non spécifiée.

exhaust bool

Le flux de données en aval à pleine puissance dans plusieurs paquets "more", en supposant que le client lira entièrement toutes les données interrogées. Plus rapide lorsque vous tirez beaucoup de données et savez que vous voulez tout tirer. Remarque : le client n'est pas autorisé à ne pas lire toutes les données sauf s'il ferme la connexion.

Cette option n'est pas prise en charge par la commande find dans MongoDB 3.2+ et forcera le pilote à utiliser la version du protocole de filaire hérité (c'est-à-dire OP_QUERY).

explain bool

Si true le curseur MongoDB\Driver\Cursor retourné contiendra un seul document qui décrit le processus et les index utilisés pour retourner la requête.

Retombe sur l'option dépréciée "$explain" si non spécifiée.

Cette option n'est pas prise en charge par la commande find dans MongoDB 3.2+ et ne sera respectée que lors de l'utilisation de la version du protocole de filaire hérité (c'est-à-dire OP_QUERY). La commande » explain doit être utilisée sur MongoDB 3.0+.

hint string|array|object

Spécification de l'index. Spécifiez soit le nom de l'index en tant que chaîne, soit le modèle de clé d'index. Si spécifié, le système de requête ne considérera que les plans utilisant l'index suggéré.

Retombe sur l'option dépréciée "hint" si non spécifiée.

let array|object

Dictionnaire des noms et des valeurs des paramètres. Les valeurs doivent être des constantes ou des expressions fermées qui ne font pas référence aux champs du document. Les paramètres peuvent ensuite être accédés en tant que variables dans un contexte d'expression agrégée (par exemple $$var).

Cette option est disponible dans MongoDB 5.0+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version antérieure du serveur.

limit int

Le nombre maximum de documents à retourner. Si non spécifié, alors par défaut à aucune limite. Une limite de 0 est équivalente à ne pas définir de limite.

Une limite négative sera interprétée comme une limite positive avec l'option "singleBatch" définie sur true. Ce comportement est pris en charge pour la compatibilité ascendante, mais doit être considéré comme déprécié.

max array|object

La limite supérieure exclusive pour un index spécifique.

Retombe sur l'option dépréciée "$max" si non spécifiée.

maxAwaitTimeMS int

Entier positif indiquant la limite de temps en millisecondes pour le serveur pour bloquer une opération getMore si aucune donnée n'est disponible. Cette option ne doit être utilisée qu'en conjonction avec les options "tailable" et "awaitData".

maxScan int
Avertissement

Cette option est dépréciée et ne doit pas être utilisée.

Entier positif indiquant le nombre maximum de documents ou de clés d'index à analyser lors de l'exécution de la requête.

Retombe sur l'option dépréciée "$maxScan" si non spécifiée.

maxTimeMS int

La limite de temps cumulative en millisecondes pour le traitement des opérations sur le curseur. MongoDB arrête l'opération au premier point d'interruption le plus proche.

Retombe sur l'option dépréciée "$maxTimeMS" si non spécifiée.

min array|object

La limite inférieure inclusive pour un index spécifique.

Retopmbe sur l'option dépréciée "$min" si non spécifiée.

modifiers array » Opérateurs méta modifiant la sortie ou le comportement d'une requête. L'utilisation de ces opérateurs est dépréciée en faveur des options nommées.
noCursorTimeout bool Empêche le serveur de mettre fin aux curseurs inactifs après une période d'inactivité (10 minutes).
oplogReplay bool

Utilisation interne pour les ensembles de réplicas. Pour utiliser oplogReplay, vous devez inclure la condition suivante dans le filtre :

[ 'ts' => [ '$gte' => <timestamp> ] ]

Note: Cette option est dépréciée à partir de la version 1.8.0.

projection array|object

Les » spécifications de projection pour déterminer quels champs inclure dans les documents retournés.

Si vous utilisez la fonctionnalité ODM pour désérialiser les documents en tant que leur classe PHP d'origine, assurez-vous d'inclure le champ __pclass dans la projection. Cela est nécessaire pour que la désérialisation fonctionne et sans cela, l'extension renverra (par défaut) un objet stdClass à la place.

readConcern MongoDB\Driver\ReadConcern

Un read concern à appliquer à l'opération. Par défaut, le read concern de l'URI de connexion MongoDB sera utilisé.

Cette option est disponible dans MongoDB 3.2+ et entraînera une exception au moment de l'exécution si elle est spécifiée pour une version de serveur plus ancienne.

returnKey bool

Si true, ne retourne que les clés d'index dans les documents résultants. La valeur par défaut est false. Si true et que la commande find n'utilise pas d'index, les documents retournés seront vides.

Retombe sur l'option dépréciée "$returnKey" si non spécifiée.

showRecordId bool

Détermine si l'identifiant d'enregistrement doit être retourné pour chaque document. Si true, ajoute un champ "$recordId" de premier niveau aux documents retournés.

Retombe sur l'option dépréciée "$showDiskLoc" si non spécifiée.

singleBatch bool Détermine si le curseur doit être fermé après le premier lot. Par défaut à false.
skip int Nombre de documents à sauter. Par défaut à 0.
snapshot bool
Avertissement

Cette option est dépréciée et ne doit pas être utilisée.

Empêche le curseur de retourner un document plus d'une fois en raison d'une opération d'écriture intermédiaire.

Retombe sur l'option dépréciée "$snapshot" si non spécifiée.

sort array|object

La spécification de tri pour l'ordonnancement des résultats.

Retombe sur l'option dépréciée "$orderby" si non spécifiée.

tailable bool Renvoie un curseur tailable pour une collection capée.

Erreurs / Exceptions

  • Lance une exception MongoDB\Driver\InvalidArgumentException lors d'une erreur survenue pendant l'analyse d'un argument.

Historique

Version Description
PECL mongodb 1.14.0

Ajout de l'option "let". L'option "comment" accepte désormais n'importe quel type.

PECL mongodb 1.8.0

Ajout de l'option "allowDiskUse".

L'option "oplogReplay" est dépréciée.

PECL mongodb 1.5.0

Les options "maxScan" et "snapshot" sont dépréciées.

PECL mongodb 1.3.0

Ajout de l'option "maxAwaitTimeMS"

PECL mongodb 1.2.0

Ajout des options "allowPartialResults", "collation", "comment", "hint", "max", "maxScan", "maxTimeMS", "min", "returnKey", "showRecordId", et "snapshot".

Renommer l'option "partial" en "allowPartialResults". Pour la compatibilité ascendante, "partial" sera toujours lu si "allowPartialResults" n'est pas spécifié.

Supprime l'option "secondaryOk" obsolète. Pour les requêtes utilisant le protocole de filaire hérité OP_QUERY, le pilote définira le bit secondaryOk selon les besoins conformément à la » Spécification de sélection du serveur.

PECL mongodb 1.1.0 Ajout de l'option "readConcern".

Exemples

Exemple #1 Exemple de MongoDB\Driver\Query::__construct()

<?php
/* Selectionne uniquement les documents écrits par "bjori" avec au moins 100 vues */
$filter = [
'author' => 'bjori',
'views' => [
'$gte' => 100,
],
];

$options = [
/* Retourne uniquement les champs suivants dans les documents correspondants */
'projection' => [
'title' => 1,
'article' => 1,
],
/* Retourne les documents dans l'ordre décroissant des vues */
'sort' => [
'views' => -1
],
];

$query = new MongoDB\Driver\Query($filter, $options);

$manager = new MongoDB\Driver\Manager('mongodb://localhost:27017');
$readPreference = new MongoDB\Driver\ReadPreference(MongoDB\Driver\ReadPreference::PRIMARY);
$cursor = $manager->executeQuery('databaseName.collectionName', $query, $readPreference);

foreach(
$cursor as $document) {
var_dump($document);
}

?>

Voir aussi

add a note

User Contributed Notes

There are no user contributed notes for this page.
To Top