construct.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- EN-Revision: 4639881688d3faaf0073ad71fe0a4b730aea15a0 Maintainer: Fan2Shrek Status: ready -->
<!-- Reviewed: yes -->
<refentry xml:id="mongodb-driver-query.construct" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink">
 <refnamediv>
  <refname>MongoDB\Driver\Query::__construct</refname>
  <refpurpose>Créer une nouvelle requête</refpurpose>
 </refnamediv>

 <refsect1 role="description">
  &reftitle.description;
  <methodsynopsis>
   <modifier>final</modifier> <modifier>public</modifier> <methodname>MongoDB\Driver\Query::__construct</methodname>
   <methodparam><type class="union"><type>array</type><type>object</type></type><parameter>filter</parameter></methodparam>
   <methodparam choice="opt"><type class="union"><type>array</type><type>null</type></type><parameter>queryOptions</parameter><initializer>&null;</initializer></methodparam>
  </methodsynopsis>
  <para>
   Construit un nouvel objet <classname>MongoDB\Driver\Query</classname>, 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
   <methodname>MongoDB\Driver\Manager::executeQuery</methodname>.
  </para>
 </refsect1>

 <refsect1 role="parameters">
  &reftitle.parameters;
  <variablelist>
   &mongodb.parameter.filter;
   <varlistentry>
    <term><parameter>queryOptions</parameter></term>
    <listitem>
     <para>
      <table xml:id="mongodb-driver-query.construct-queryOptions">
       <title>queryOptions</title>
       <tgroup cols="3">
        <thead>
         <row>
          <entry>Option</entry>
          <entry>Type</entry>
          <entry>Description</entry>
         </row>
        </thead>
        <tbody>
         <row>
          <entry>allowDiskUse</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            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.
           </para>
          </entry>
         </row>
         <row>
          <entry>allowPartialResults</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            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.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"partial"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>awaitData</entry>
          <entry><type>bool</type></entry>
          <entry>
           Utiliser en conjonction avec l'option <literal>"tailable"</literal> 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.
          </entry>
         </row>
         <row>
          <entry>batchSize</entry>
          <entry><type>int</type></entry>
          <entry>
           <para>
            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.
           </para>
           <para>
            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.
           </para>
          </entry>
         </row>
         &mongodb.option.collation;
         <row>
          <entry>comment</entry>
          <entry><type>mixed</type></entry>
          <entry>
           <para>
            Un commentaire arbitraire pour aider à tracer l'opération à travers
            le profil de la base de données, la sortie currentOp et les journaux.
           </para>
           <para>
            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.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$comment"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>exhaust</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            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.
           </para>
           <para>
            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).
           </para>
          </entry>
         </row>
         <row>
          <entry>explain</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            Si &true; le curseur <classname>MongoDB\Driver\Cursor</classname> retourné
            contiendra un seul document qui décrit le processus et les index utilisés
            pour retourner la requête.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$explain"</literal> si non
            spécifiée.
           </para>
           <para>
            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
            <link xlink:href="&url.mongodb.docs;reference/command/explain/">explain</link>
            doit être utilisée sur MongoDB 3.0+.
           </para>
          </entry>
         </row>
         <row>
          <entry>hint</entry>
          <entry><type class="union"><type>string</type><type>array</type><type>object</type></type></entry>
          <entry>
           <para>
            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é.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"hint"</literal> si non spécifiée.
           </para>
          </entry>
         </row>
         &mongodb.option.let;
         <row>
          <entry>limit</entry>
          <entry><type>int</type></entry>
          <entry>
           <para>
            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.
           </para>
          </entry>
         </row>
         <row>
          <entry>max</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <para>
            La limite supérieure <emphasis>exclusive</emphasis> pour un index spécifique.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$max"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>maxAwaitTimeMS</entry>
          <entry><type>int</type></entry>
          <entry>
           <para>
            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 <literal>"tailable"</literal> et
            <literal>"awaitData"</literal>.
           </para>
          </entry>
         </row>
         <row>
          <entry>maxTimeMS</entry>
          <entry><type>int</type></entry>
          <entry>
           <para>
            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.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$maxTimeMS"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>min</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <para>
            La limite inférieure <emphasis>inclusive</emphasis> pour un index spécifique.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$min"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>noCursorTimeout</entry>
          <entry><type>bool</type></entry>
          <entry>
           Empêche le serveur de mettre fin aux curseurs inactifs après une période
           d'inactivité (10 minutes).
          </entry>
         </row>
         <row>
          <entry>projection</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <para>
            Les <link xlink:href="&url.mongodb.docs;tutorial/project-fields-from-query-results/">spécifications de projection</link>
            pour déterminer quels champs inclure dans les documents retournés.
           </para>
           <para>
            Si vous utilisez la
            <link linkend="mongodb.persistence.deserialization">fonctionnalité ODM</link>
            pour désérialiser les documents en tant que leur classe PHP d'origine,
            assurez-vous d'inclure le champ <property>__pclass</property> 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
            <classname>stdClass</classname> à la place.
           </para>
          </entry>
         </row>
         <row>
          <entry>readConcern</entry>
          <entry><classname>MongoDB\Driver\ReadConcern</classname></entry>
          <entry>
           <para>
            Un read concern à appliquer à l'opération. Par défaut, le read concern
            de l'<link linkend="mongodb-driver-manager.construct-uri">URI
            de connexion MongoDB</link>
            sera utilisé.
           </para>
           <para>
            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.
           </para>
          </entry>
         </row>
         <row>
          <entry>returnKey</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            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.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$returnKey"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>showRecordId</entry>
          <entry><type>bool</type></entry>
          <entry>
           <para>
            Détermine si l'identifiant d'enregistrement doit être retourné pour
            chaque document. Si &true;, ajoute un champ <literal>"$recordId"</literal>
            de premier niveau aux documents retournés.
           </para>
           <para>
            Retombe sur l'option dépréciée <literal>"$showDiskLoc"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>singleBatch</entry>
          <entry><type>bool</type></entry>
          <entry>
           Détermine si le curseur doit être fermé après le premier lot.
           Par défaut à &false;.
          </entry>
         </row>
         <row>
          <entry>skip</entry>
          <entry><type>int</type></entry>
          <entry>Nombre de documents à sauter. Par défaut à 0.</entry>
         </row>
         <row>
          <entry>sort</entry>
          <entry><type class="union"><type>array</type><type>object</type></type></entry>
          <entry>
           <para>La spécification de tri pour l'ordonnancement des résultats.</para>
           <para>
            Retombe sur l'option dépréciée <literal>"$orderby"</literal> si non
            spécifiée.
           </para>
          </entry>
         </row>
         <row>
          <entry>tailable</entry>
          <entry><type>bool</type></entry>
          <entry>Renvoie un curseur tailable pour une collection capée.</entry>
         </row>
        </tbody>
       </tgroup>
      </table>
     </para>
    </listitem>
   </varlistentry>
  </variablelist>
 </refsect1>

 <refsect1 role="errors">
  &reftitle.errors;
  <simplelist>
   &mongodb.throws.argumentparsing;
  </simplelist>
 </refsect1>

 <refsect1 role="changelog">
  &reftitle.changelog;
  <para>
   <informaltable>
    <tgroup cols="2">
     <thead>
      <row>
       <entry>&Version;</entry>
       <entry>&Description;</entry>
      </row>
     </thead>
     <tbody>
      <row>
       <entry>PECL mongodb 2.0.0</entry>
       <entry>
        <para>
         L'option <literal>"partial"</literal> a été supprimée. Utilisez
         <literal>"allowPartialResults"</literal> à la place.
        </para>
        <para>
         L'option <literal>"maxScan"</literal> a été supprimée. Le Support
         pour cette option a été supprimé dans MongoDB 4.2.
        </para>
        <para>
         L'option <literal>"modifiers"</literal> a été supprimée. Cette options était
         utilisée pour les modificateurs d'ancienne requête, qui sont tous dépréciés.
        </para>
        <para>
         L'option <literal>"oplogReplay"</literal> a été supprimée. Cela est ignoré
         dans MongoDB 4.4 et plus récent.
        </para>
        <para>
         L'option <literal>"snapshot"</literal> a été supprimée. Son support a été
         supprimé dans MongoDB 4.0.
        </para>
        <para>
         Une valuer négative pour l'option <literal>"limit"</literal> n'implique plus
         &true; pour l'option <literal>"singleBatch"</literal>. Pour ne recevoir
         qu'un seul lot de résultats, combinez une valeur positive
         <literal>"limit"</literal> avec l'option
         <literal>"singleBatch"</literal>.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.14.0</entry>
       <entry>
        <para>
         Ajout de l'option <literal>"let"</literal>. L'option
         <literal>"comment"</literal> accepte désormais n'importe quel type.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.8.0</entry>
       <entry>
        <para>
         Ajout de l'option <literal>"allowDiskUse"</literal>.
        </para>
        <para>
         L'option <literal>"oplogReplay"</literal> est dépréciée.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.5.0</entry>
       <entry>
        <para>
         Les options <literal>"maxScan"</literal> et <literal>"snapshot"</literal>
         sont dépréciées.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.3.0</entry>
       <entry>
        <para>
         Ajout de l'option <literal>"maxAwaitTimeMS"</literal>
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.2.0</entry>
       <entry>
        <para>
         Ajout des options <literal>"allowPartialResults"</literal>,
         <literal>"collation"</literal>, <literal>"comment"</literal>,
         <literal>"hint"</literal>, <literal>"max"</literal>,
         <literal>"maxScan"</literal>, <literal>"maxTimeMS"</literal>,
         <literal>"min"</literal>, <literal>"returnKey"</literal>,
         <literal>"showRecordId"</literal>, et <literal>"snapshot"</literal>.
        </para>
        <para>
         Renommer l'option <literal>"partial"</literal> en
         <literal>"allowPartialResults"</literal>. Pour la compatibilité ascendante,
         <literal>"partial"</literal> sera toujours lu si
         <literal>"allowPartialResults"</literal> n'est pas spécifié.
        </para>
        <para>
         Supprime l'option <literal>"secondaryOk"</literal> obsolète. Pour les
         requêtes utilisant le protocole de filaire hérité OP_QUERY, le pilote
         définira le bit <literal>secondaryOk</literal> selon les besoins
         conformément à la
         <link xlink:href="&url.mongodb.serverselection;">Spécification de sélection du serveur</link>.
        </para>
       </entry>
      </row>
      <row>
       <entry>PECL mongodb 1.1.0</entry>
       <entry>Ajout de l'option <literal>"readConcern"</literal>.</entry>
      </row>
     </tbody>
    </tgroup>
   </informaltable>
  </para>
 </refsect1>

 <refsect1 role="examples">
  &reftitle.examples;
  <example>
   <title>Exemple de <function>MongoDB\Driver\Query::__construct</function></title>
   <programlisting role="php">
<![CDATA[
<?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' => $readPreference]);

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

?>
]]>
   </programlisting>
  </example>
 </refsect1>

 <refsect1 role="seealso">
  &reftitle.seealso;
  <simplelist>
   <member><methodname>MongoDB\Driver\Manager::executeQuery</methodname></member>
   <member><classname>MongoDB\Driver\Cursor</classname></member>
  </simplelist>
 </refsect1>

</refentry>

<!-- Keep this comment at the end of the file
Local variables:
mode: sgml
sgml-omittag:t
sgml-shorttag:t
sgml-minimize-attributes:nil
sgml-always-quote-attributes:t
sgml-indent-step:1
sgml-indent-data:t
indent-tabs-mode:nil
sgml-parent-document:nil
sgml-default-dtd-file:"~/.phpdoc/manual.ced"
sgml-exposed-tags:nil
sgml-local-catalogs:nil
sgml-local-ecat-files:nil
End:
vim600: syn=xml fen fdm=syntax fdl=2 si
vim: et tw=78 syn=sgml
vi: ts=1 sw=1
-->