readconcern.xml

<?xml version="1.0" encoding="utf-8"?>
<!-- $Revision$ -->

<reference xml:id="class.mongodb-driver-readconcern" role="class" xmlns="http://docbook.org/ns/docbook" xmlns:xlink="http://www.w3.org/1999/xlink" xmlns:xi="http://www.w3.org/2001/XInclude">

 <title>The MongoDB\Driver\ReadConcern class</title>
 <titleabbrev>MongoDB\Driver\ReadConcern</titleabbrev>

 <partintro>

<!-- {{{ MongoDB\Driver\ReadConcern intro -->
  <section xml:id="mongodb-driver-readconcern.intro">
   &reftitle.intro;
   <para>
    <classname>MongoDB\Driver\ReadConcern</classname> controls the level of
    isolation for read operations for replica sets and replica set shards. This
    option requires MongoDB 3.2 or later.
   </para>
  </section>
<!-- }}} -->

  <section xml:id="mongodb-driver-readconcern.synopsis">
   &reftitle.classsynopsis;

<!-- {{{ Synopsis -->
   <classsynopsis>
    <ooclass><classname>MongoDB\Driver\ReadConcern</classname></ooclass>

<!-- {{{ Class synopsis -->
    <classsynopsisinfo>
     <modifier>final</modifier>
     <ooclass>
      <classname>MongoDB\Driver\ReadConcern</classname>
     </ooclass>

     <oointerface>
      <interfacename>MongoDB\BSON\Serializable</interfacename>
     </oointerface>

     <oointerface>
      <interfacename>Serializable</interfacename>
     </oointerface>
    </classsynopsisinfo>
<!-- }}} -->
    <classsynopsisinfo role="comment">&Constants;</classsynopsisinfo>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>string</type>
     <varname linkend="mongodb-driver-readconcern.constants.linearizable">MongoDB\Driver\ReadConcern::AVAILABLE</varname>
     <initializer>"available"</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>string</type>
     <varname linkend="mongodb-driver-readconcern.constants.linearizable">MongoDB\Driver\ReadConcern::LINEARIZABLE</varname>
     <initializer>"linearizable"</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>string</type>
     <varname linkend="mongodb-driver-readconcern.constants.local">MongoDB\Driver\ReadConcern::LOCAL</varname>
     <initializer>"local"</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>string</type>
     <varname linkend="mongodb-driver-readconcern.constants.majority">MongoDB\Driver\ReadConcern::MAJORITY</varname>
     <initializer>"majority"</initializer>
    </fieldsynopsis>
    <fieldsynopsis>
     <modifier>const</modifier>
     <type>string</type>
     <varname linkend="mongodb-driver-readconcern.constants.snapshot">MongoDB\Driver\ReadConcern::SNAPSHOT</varname>
     <initializer>"snapshot"</initializer>
    </fieldsynopsis>

    <classsynopsisinfo role="comment">&Methods;</classsynopsisinfo>
    <xi:include xpointer="xmlns(db=http://docbook.org/ns/docbook) xpointer(id('class.mongodb-driver-readconcern')/db:refentry/db:refsect1[@role='description']/descendant::db:methodsynopsis[not(@role='procedural')])" />
   </classsynopsis>
<!-- }}} -->

  </section>

<!-- {{{ MongoDB\Driver\ReadConcern constants -->
  <section xml:id="mongodb-driver-readconcern.constants">
   &reftitle.constants;
   <variablelist>

    <varlistentry xml:id="mongodb-driver-readconcern.constants.available">
     <term><constant>MongoDB\Driver\ReadConcern::AVAILABLE</constant></term>
     <listitem>
      <para>
       Default for reads against secondaries when
       <literal>afterClusterTime</literal>and <literal>level</literal> are
       unspecified.
      </para>
      <para>
       The query returns the instance&apos;s most recent data. Provides no
       guarantee that the data has been written to a majority of the replica set
       members (i.e. may be rolled back).
      </para>
      <para>
       For unsharded collections (including collections in a standalone
       deployment or a replica set deployment), <literal>"local"</literal> and
       <literal>"available"</literal> read concerns behave identically.
      </para>
      <para>
       For a sharded cluster, <literal>"available"</literal> read concern
       provides greater tolerance for partitions since it does not wait to
       ensure consistency guarantees. However, a query with
       <literal>"available"</literal> read concern may return orphan documents
       if the shard is undergoing chunk migrations since the
       <literal>"available"</literal> read concern, unlike
       <literal>"local"</literal> read concern, does not contact the
       shard&apos;s primary nor the config servers for updated metadata.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry xml:id="mongodb-driver-readconcern.constants.linearizable">
     <term><constant>MongoDB\Driver\ReadConcern::LINEARIZABLE</constant></term>
     <listitem>
      <para>
       The query returns data that reflects all successful writes issued with a
       write concern of <literal>"majority"</literal> <emphasis>and</emphasis>
       acknowledged prior to the start of the read operation. For replica sets
       that run with <literal>writeConcernMajorityJournalDefault</literal> set
       to &true;, linearizable read concern returns data that will never be
       rolled back.
      </para>
      <para>
       With <literal>writeConcernMajorityJournalDefault</literal> set to
       &false;, MongoDB will not wait for <literal>w: "majority"</literal>
       writes to be durable before acknowledging the writes. As such,
       <literal>"majority"</literal> write operations could possibly roll back
       in the event of a loss of a replica set member.
      </para>
      <para>
       You can specify linearizable read concern for read operations on the
       primary only.
      </para>
      <para>
       Linearizable read concern guarantees only apply if read
       operations specify a query filter that uniquely identifies a single
       document.
      </para>
      <tip>
       <simpara>
        Always use <literal>maxTimeMS</literal> with linearizable read concern
        in case a majority of data bearing members are unavailable.
        <literal>maxTimeMS</literal> ensures that the operation does not block
        indefinitely and instead ensures that the operation returns an error if
        the read concern cannot be fulfilled.
       </simpara>
      </tip>
      <para>
       Linearizable read concern requires MongoDB 3.4.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry xml:id="mongodb-driver-readconcern.constants.local">
     <term><constant>MongoDB\Driver\ReadConcern::LOCAL</constant></term>
     <listitem>
      <para>
       Default for reads against primary if <literal>level</literal> is
       unspecified and for reads against secondaries if <literal>level</literal>
       is unspecified but <literal>afterClusterTime</literal> is specified.
      </para>
      <para>
       The query returns the instance&apos;s most recent data. Provides no
       guarantee that the data has been written to a majority of the replica set
       members (i.e. may be rolled back).
      </para>
     </listitem>
    </varlistentry>

    <varlistentry xml:id="mongodb-driver-readconcern.constants.majority">
     <term><constant>MongoDB\Driver\ReadConcern::MAJORITY</constant></term>
     <listitem>
      <para>
       The query returns the instance&apos;s most recent data acknowledged as
       having been written to a majority of members in the replica set.
      </para>
      <para>
       To use read concern level of <literal>"majority"</literal>, replica sets
       must use WiredTiger storage engine and election protocol version 1.
      </para>
     </listitem>
    </varlistentry>

    <varlistentry xml:id="mongodb-driver-readconcern.constants.snapshot">
     <term><constant>MongoDB\Driver\ReadConcern::SNAPSHOT</constant></term>
     <listitem>
      <para>
       Read concern <literal>"snapshot"</literal> is available for
       multi-document transactions, and starting in MongoDB 5.0, certain read
       operations outside of multi-document transactions.
      </para>
      <para>
       If the transaction is not part of a causally consistent session, upon
       transaction commit with write concern <literal>"majority"</literal>, the
       transaction operations are guaranteed to have read from a snapshot of
       majority-committed data.
      </para>
      <para>
       If the transaction is part of a causally consistent session, upon
       transaction commit with write concern <literal>"majority"</literal>, the
       transaction operations are guaranteed to have read from a snapshot of
       majority-committed data that provides causal consistency with the
       operation immediately preceding the transaction start.
      </para>
      <para>
       Outside of multi-document transactions, read concern
       <literal>"snapshot"</literal> is available on primaries and secondaries
       for the following read operations: <literal>find</literal>,
       <literal>aggregate</literal>, and <literal>distinct</literal> (on
       unsharded collections). All other read commands prohibit
       <literal>"snapshot"</literal>.
      </para>
     </listitem>
    </varlistentry>

   </variablelist>
  </section>
<!-- }}} -->

  <section role="changelog">
   &reftitle.changelog;
   <para>
    <informaltable>
     <tgroup cols="2">
      <thead>
       <row>
        <entry>&Version;</entry>
        <entry>&Description;</entry>
       </row>
      </thead>
      <tbody>
       <row>
        <entry>PECL mongodb 1.11.0</entry>
        <entry>
         <para>
          Added the <constant>MongoDB\Driver\ReadConcern::SNAPSHOT</constant>
          constant.
         </para>
        </entry>
       </row>
       <row>
        <entry>PECL mongodb 1.7.0</entry>
        <entry>
         Implements <interfacename>Serializable</interfacename>.
        </entry>
       </row>
       <row>
        <entry>PECL mongodb 1.4.0</entry>
        <entry>
         <para>
          Added the <constant>MongoDB\Driver\ReadConcern::AVAILABLE</constant>
          constant.
         </para>
        </entry>
       </row>
       <row>
        <entry>PECL mongodb 1.2.0</entry>
        <entry>
         <para>
          Added the
          <constant>MongoDB\Driver\ReadConcern::LINEARIZABLE</constant>
          constant.
         </para>
         <para>
          Implements <interfacename>MongoDB\BSON\Serializable</interfacename>.
         </para>
        </entry>
       </row>
      </tbody>
     </tgroup>
    </informaltable>
   </para>
  </section>

  <section xml:id="mongodb-driver-readconcern.seealso">
   &reftitle.seealso;
  <simplelist>
   <member><link xlink:href="&url.mongodb.docs.readconcern;">Read Concern reference</link></member>
  </simplelist>
  </section>

 </partintro>

 &reference.mongodb.mongodb.driver.entities.readconcern;

</reference>

<!-- 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
-->