<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> <html xmlns="http://www.w3.org/1999/xhtml"> <head> <meta http-equiv="X-UA-Compatible" content="IE=Edge" /> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <title>client_session – Logical sessions for sequential operations — PyMongo 3.7.2 documentation</title> <link rel="stylesheet" href="../../_static/pydoctheme.css" type="text/css" /> <link rel="stylesheet" href="../../_static/pygments.css" type="text/css" /> <script type="text/javascript" id="documentation_options" data-url_root="../../" src="../../_static/documentation_options.js"></script> <script type="text/javascript" src="../../_static/jquery.js"></script> <script type="text/javascript" src="../../_static/underscore.js"></script> <script type="text/javascript" src="../../_static/doctools.js"></script> <script type="text/javascript" src="../../_static/language_data.js"></script> <script type="text/javascript" src="../../_static/sidebar.js"></script> <link rel="index" title="Index" href="../../genindex.html" /> <link rel="search" title="Search" href="../../search.html" /> <link rel="next" title="collation – Tools for working with collations." href="collation.html" /> <link rel="prev" title="change_stream – Watch changes on a collection" href="change_stream.html" /> </head><body> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../../genindex.html" title="General Index" accesskey="I">index</a></li> <li class="right" > <a href="../../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="collation.html" title="collation – Tools for working with collations." accesskey="N">next</a> |</li> <li class="right" > <a href="change_stream.html" title="change_stream – Watch changes on a collection" accesskey="P">previous</a> |</li> <li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li> <li class="nav-item nav-item-2"><a href="index.html" accesskey="U"><code class="docutils literal notranslate"><span class="pre">pymongo</span></code> – Python driver for MongoDB</a> »</li> </ul> </div> <div class="document"> <div class="documentwrapper"> <div class="bodywrapper"> <div class="body" role="main"> <div class="section" id="module-pymongo.client_session"> <span id="client-session-logical-sessions-for-sequential-operations"></span><h1><code class="xref py py-mod docutils literal notranslate"><span class="pre">client_session</span></code> – Logical sessions for sequential operations<a class="headerlink" href="#module-pymongo.client_session" title="Permalink to this headline">¶</a></h1> <p>Logical sessions for ordering sequential operations.</p> <p>Requires MongoDB 3.6.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.6.</span></p> </div> <div class="section" id="causally-consistent-reads"> <h2>Causally Consistent Reads<a class="headerlink" href="#causally-consistent-reads" title="Permalink to this headline">¶</a></h2> <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="k">with</span> <span class="n">client</span><span class="o">.</span><span class="n">start_session</span><span class="p">(</span><span class="n">causal_consistency</span><span class="o">=</span><span class="bp">True</span><span class="p">)</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span> <span class="n">collection</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">collection</span> <span class="n">collection</span><span class="o">.</span><span class="n">update_one</span><span class="p">({</span><span class="s1">'_id'</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="p">{</span><span class="s1">'$set'</span><span class="p">:</span> <span class="p">{</span><span class="s1">'x'</span><span class="p">:</span> <span class="mi">10</span><span class="p">}},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span> <span class="n">secondary_c</span> <span class="o">=</span> <span class="n">collection</span><span class="o">.</span><span class="n">with_options</span><span class="p">(</span> <span class="n">read_preference</span><span class="o">=</span><span class="n">ReadPreference</span><span class="o">.</span><span class="n">SECONDARY</span><span class="p">)</span> <span class="c1"># A secondary read waits for replication of the write.</span> <span class="n">secondary_c</span><span class="o">.</span><span class="n">find_one</span><span class="p">({</span><span class="s1">'_id'</span><span class="p">:</span> <span class="mi">1</span><span class="p">},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span> </pre></div> </div> <p>If <cite>causal_consistency</cite> is True (the default), read operations that use the session are causally after previous read and write operations. Using a causally consistent session, an application can read its own writes and is guaranteed monotonic reads, even when reading from replica set secondaries.</p> <div class="admonition seealso"> <p class="first admonition-title">See also</p> <p class="admonition-title">The MongoDB documentation on</p> <p class="last"><a class="reference external" href="http://dochub.mongodb.org/core/causal-consistency" name="pymongo.client_session.ClientSession"><em>causal-consistency</em></a></p> </div> </div> <div class="section" id="transactions"> <span id="transactions-ref"></span><h2>Transactions<a class="headerlink" href="#transactions" title="Permalink to this headline">¶</a></h2> <p>MongoDB 4.0 adds support for transactions on replica set primaries. A transaction is associated with a <a class="reference internal" href="#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>. To start a transaction on a session, use <a class="reference internal" href="#pymongo.client_session.ClientSession.start_transaction" title="pymongo.client_session.ClientSession.start_transaction"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ClientSession.start_transaction()</span></code></a> in a with-statement. Then, execute an operation within the transaction by passing the session to the operation:</p> <div class="highlight-python notranslate"><div class="highlight"><pre><span></span><span class="n">orders</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">orders</span> <span class="n">inventory</span> <span class="o">=</span> <span class="n">client</span><span class="o">.</span><span class="n">db</span><span class="o">.</span><span class="n">inventory</span> <span class="k">with</span> <span class="n">client</span><span class="o">.</span><span class="n">start_session</span><span class="p">()</span> <span class="k">as</span> <span class="n">session</span><span class="p">:</span> <span class="k">with</span> <span class="n">session</span><span class="o">.</span><span class="n">start_transaction</span><span class="p">():</span> <span class="n">orders</span><span class="o">.</span><span class="n">insert_one</span><span class="p">({</span><span class="s2">"sku"</span><span class="p">:</span> <span class="s2">"abc123"</span><span class="p">,</span> <span class="s2">"qty"</span><span class="p">:</span> <span class="mi">100</span><span class="p">},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span> <span class="n">inventory</span><span class="o">.</span><span class="n">update_one</span><span class="p">({</span><span class="s2">"sku"</span><span class="p">:</span> <span class="s2">"abc123"</span><span class="p">,</span> <span class="s2">"qty"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"$gte"</span><span class="p">:</span> <span class="mi">100</span><span class="p">}},</span> <span class="p">{</span><span class="s2">"$inc"</span><span class="p">:</span> <span class="p">{</span><span class="s2">"qty"</span><span class="p">:</span> <span class="o">-</span><span class="mi">100</span><span class="p">}},</span> <span class="n">session</span><span class="o">=</span><span class="n">session</span><span class="p">)</span> </pre></div> </div> <p>Upon normal completion of <code class="docutils literal notranslate"><span class="pre">with</span> <span class="pre">session.start_transaction()</span></code> block, the transaction automatically calls <a class="reference internal" href="#pymongo.client_session.ClientSession.commit_transaction" title="pymongo.client_session.ClientSession.commit_transaction"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ClientSession.commit_transaction()</span></code></a>. If the block exits with an exception, the transaction automatically calls <a class="reference internal" href="#pymongo.client_session.ClientSession.abort_transaction" title="pymongo.client_session.ClientSession.abort_transaction"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ClientSession.abort_transaction()</span></code></a>.</p> <p>For multi-document transactions, you can only specify read/write (CRUD) operations on existing collections. For example, a multi-document transaction cannot include a create or drop collection/index operations, including an insert operation that would result in the creation of a new collection.</p> <p>A session may only have a single active transaction at a time, multiple transactions on the same session can be executed in sequence.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> <div class="admonition seealso"> <p class="first admonition-title">See also</p> <p class="admonition-title">The MongoDB documentation on</p> <p class="last"><a class="reference external" href="http://dochub.mongodb.org/core/transactions" name="pymongo.client_session.ClientSession"><em>transactions</em></a></p> </div> </div> <div class="section" id="classes"> <h2>Classes<a class="headerlink" href="#classes" title="Permalink to this headline">¶</a></h2> <dl class="class"> <dt id="pymongo.client_session.ClientSession"> <em class="property">class </em><code class="descclassname">pymongo.client_session.</code><code class="descname">ClientSession</code><span class="sig-paren">(</span><em>client</em>, <em>server_session</em>, <em>options</em>, <em>authset</em>, <em>implicit</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession" title="Permalink to this definition">¶</a></dt> <dd><p>A session for ordering sequential operations.</p> <dl class="method"> <dt id="pymongo.client_session.ClientSession.abort_transaction"> <code class="descname">abort_transaction</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.abort_transaction" title="Permalink to this definition">¶</a></dt> <dd><p>Abort a multi-statement transaction.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> </dd></dl> <dl class="method"> <dt id="pymongo.client_session.ClientSession.advance_cluster_time"> <code class="descname">advance_cluster_time</code><span class="sig-paren">(</span><em>cluster_time</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.advance_cluster_time" title="Permalink to this definition">¶</a></dt> <dd><p>Update the cluster time for this session.</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li><cite>cluster_time</cite>: The <a class="reference internal" href="#pymongo.client_session.ClientSession.cluster_time" title="pymongo.client_session.ClientSession.cluster_time"><code class="xref py py-data docutils literal notranslate"><span class="pre">cluster_time</span></code></a> from another <cite>ClientSession</cite> instance.</li> </ul> </td> </tr> </tbody> </table> </dd></dl> <dl class="method"> <dt id="pymongo.client_session.ClientSession.advance_operation_time"> <code class="descname">advance_operation_time</code><span class="sig-paren">(</span><em>operation_time</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.advance_operation_time" title="Permalink to this definition">¶</a></dt> <dd><p>Update the operation time for this session.</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li><cite>operation_time</cite>: The <a class="reference internal" href="#pymongo.client_session.ClientSession.operation_time" title="pymongo.client_session.ClientSession.operation_time"><code class="xref py py-data docutils literal notranslate"><span class="pre">operation_time</span></code></a> from another <cite>ClientSession</cite> instance.</li> </ul> </td> </tr> </tbody> </table> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.client"> <code class="descname">client</code><a class="headerlink" href="#pymongo.client_session.ClientSession.client" title="Permalink to this definition">¶</a></dt> <dd><p>The <a class="reference internal" href="mongo_client.html#pymongo.mongo_client.MongoClient" title="pymongo.mongo_client.MongoClient"><code class="xref py py-class docutils literal notranslate"><span class="pre">MongoClient</span></code></a> this session was created from.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.cluster_time"> <code class="descname">cluster_time</code><a class="headerlink" href="#pymongo.client_session.ClientSession.cluster_time" title="Permalink to this definition">¶</a></dt> <dd><p>The cluster time returned by the last operation executed in this session.</p> </dd></dl> <dl class="method"> <dt id="pymongo.client_session.ClientSession.commit_transaction"> <code class="descname">commit_transaction</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.commit_transaction" title="Permalink to this definition">¶</a></dt> <dd><p>Commit a multi-statement transaction.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> </dd></dl> <dl class="method"> <dt id="pymongo.client_session.ClientSession.end_session"> <code class="descname">end_session</code><span class="sig-paren">(</span><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.end_session" title="Permalink to this definition">¶</a></dt> <dd><p>Finish this session. If a transaction has started, abort it.</p> <p>It is an error to use the session after the session has ended.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.has_ended"> <code class="descname">has_ended</code><a class="headerlink" href="#pymongo.client_session.ClientSession.has_ended" title="Permalink to this definition">¶</a></dt> <dd><p>True if this session is finished.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.operation_time"> <code class="descname">operation_time</code><a class="headerlink" href="#pymongo.client_session.ClientSession.operation_time" title="Permalink to this definition">¶</a></dt> <dd><p>The operation time returned by the last operation executed in this session.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.options"> <code class="descname">options</code><a class="headerlink" href="#pymongo.client_session.ClientSession.options" title="Permalink to this definition">¶</a></dt> <dd><p>The <a class="reference internal" href="#pymongo.client_session.SessionOptions" title="pymongo.client_session.SessionOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">SessionOptions</span></code></a> this session was created with.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.ClientSession.session_id"> <code class="descname">session_id</code><a class="headerlink" href="#pymongo.client_session.ClientSession.session_id" title="Permalink to this definition">¶</a></dt> <dd><p>A BSON document, the opaque server session identifier.</p> </dd></dl> <dl class="method"> <dt id="pymongo.client_session.ClientSession.start_transaction"> <code class="descname">start_transaction</code><span class="sig-paren">(</span><em>read_concern=None</em>, <em>write_concern=None</em>, <em>read_preference=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.ClientSession.start_transaction" title="Permalink to this definition">¶</a></dt> <dd><p>Start a multi-statement transaction.</p> <p>Takes the same arguments as <a class="reference internal" href="#pymongo.client_session.TransactionOptions" title="pymongo.client_session.TransactionOptions"><code class="xref py py-class docutils literal notranslate"><span class="pre">TransactionOptions</span></code></a>.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> </dd></dl> </dd></dl> <dl class="class"> <dt id="pymongo.client_session.SessionOptions"> <em class="property">class </em><code class="descclassname">pymongo.client_session.</code><code class="descname">SessionOptions</code><span class="sig-paren">(</span><em>causal_consistency=True</em>, <em>default_transaction_options=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.SessionOptions" title="Permalink to this definition">¶</a></dt> <dd><p>Options for a new <a class="reference internal" href="#pymongo.client_session.ClientSession" title="pymongo.client_session.ClientSession"><code class="xref py py-class docutils literal notranslate"><span class="pre">ClientSession</span></code></a>.</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li><cite>causal_consistency</cite> (optional): If True (the default), read operations are causally ordered within the session.</li> <li><cite>default_transaction_options</cite> (optional): The default TransactionOptions to use for transactions started on this session.</li> </ul> </td> </tr> </tbody> </table> <dl class="attribute"> <dt id="pymongo.client_session.SessionOptions.causal_consistency"> <code class="descname">causal_consistency</code><a class="headerlink" href="#pymongo.client_session.SessionOptions.causal_consistency" title="Permalink to this definition">¶</a></dt> <dd><p>Whether causal consistency is configured.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.SessionOptions.default_transaction_options"> <code class="descname">default_transaction_options</code><a class="headerlink" href="#pymongo.client_session.SessionOptions.default_transaction_options" title="Permalink to this definition">¶</a></dt> <dd><p>The default TransactionOptions to use for transactions started on this session.</p> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> </dd></dl> </dd></dl> <dl class="class"> <dt id="pymongo.client_session.TransactionOptions"> <em class="property">class </em><code class="descclassname">pymongo.client_session.</code><code class="descname">TransactionOptions</code><span class="sig-paren">(</span><em>read_concern=None</em>, <em>write_concern=None</em>, <em>read_preference=None</em><span class="sig-paren">)</span><a class="headerlink" href="#pymongo.client_session.TransactionOptions" title="Permalink to this definition">¶</a></dt> <dd><p>Options for <a class="reference internal" href="#pymongo.client_session.ClientSession.start_transaction" title="pymongo.client_session.ClientSession.start_transaction"><code class="xref py py-meth docutils literal notranslate"><span class="pre">ClientSession.start_transaction()</span></code></a>.</p> <table class="docutils field-list" frame="void" rules="none"> <col class="field-name" /> <col class="field-body" /> <tbody valign="top"> <tr class="field-odd field"><th class="field-name">Parameters:</th><td class="field-body"><ul class="first last simple"> <li><cite>read_concern</cite>: The <a class="reference internal" href="read_concern.html#pymongo.read_concern.ReadConcern" title="pymongo.read_concern.ReadConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadConcern</span></code></a> to use for this transaction.</li> <li><cite>write_concern</cite>: The <a class="reference internal" href="write_concern.html#pymongo.write_concern.WriteConcern" title="pymongo.write_concern.WriteConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteConcern</span></code></a> to use for this transaction.</li> </ul> </td> </tr> </tbody> </table> <div class="versionadded"> <p><span class="versionmodified">New in version 3.7.</span></p> </div> <dl class="attribute"> <dt id="pymongo.client_session.TransactionOptions.read_concern"> <code class="descname">read_concern</code><a class="headerlink" href="#pymongo.client_session.TransactionOptions.read_concern" title="Permalink to this definition">¶</a></dt> <dd><p>This transaction’s <a class="reference internal" href="read_concern.html#pymongo.read_concern.ReadConcern" title="pymongo.read_concern.ReadConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadConcern</span></code></a>.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.TransactionOptions.read_preference"> <code class="descname">read_preference</code><a class="headerlink" href="#pymongo.client_session.TransactionOptions.read_preference" title="Permalink to this definition">¶</a></dt> <dd><p>This transaction’s <a class="reference internal" href="read_preferences.html#pymongo.read_preferences.ReadPreference" title="pymongo.read_preferences.ReadPreference"><code class="xref py py-class docutils literal notranslate"><span class="pre">ReadPreference</span></code></a>.</p> </dd></dl> <dl class="attribute"> <dt id="pymongo.client_session.TransactionOptions.write_concern"> <code class="descname">write_concern</code><a class="headerlink" href="#pymongo.client_session.TransactionOptions.write_concern" title="Permalink to this definition">¶</a></dt> <dd><p>This transaction’s <a class="reference internal" href="write_concern.html#pymongo.write_concern.WriteConcern" title="pymongo.write_concern.WriteConcern"><code class="xref py py-class docutils literal notranslate"><span class="pre">WriteConcern</span></code></a>.</p> </dd></dl> </dd></dl> </div> </div> </div> </div> </div> <div class="sphinxsidebar" role="navigation" aria-label="main navigation"> <div class="sphinxsidebarwrapper"> <h3><a href="../../index.html">Table of Contents</a></h3> <ul> <li><a class="reference internal" href="#"><code class="docutils literal notranslate"><span class="pre">client_session</span></code> – Logical sessions for sequential operations</a><ul> <li><a class="reference internal" href="#causally-consistent-reads">Causally Consistent Reads</a></li> <li><a class="reference internal" href="#transactions">Transactions</a></li> <li><a class="reference internal" href="#classes">Classes</a></li> </ul> </li> </ul> <h4>Previous topic</h4> <p class="topless"><a href="change_stream.html" title="previous chapter"><code class="docutils literal notranslate"><span class="pre">change_stream</span></code> – Watch changes on a collection</a></p> <h4>Next topic</h4> <p class="topless"><a href="collation.html" title="next chapter"><code class="docutils literal notranslate"><span class="pre">collation</span></code> – Tools for working with collations.</a></p> <div role="note" aria-label="source link"> <h3>This Page</h3> <ul class="this-page-menu"> <li><a href="../../_sources/api/pymongo/client_session.rst.txt" rel="nofollow">Show Source</a></li> </ul> </div> <div id="searchbox" style="display: none" role="search"> <h3>Quick search</h3> <div class="searchformwrapper"> <form class="search" action="../../search.html" method="get"> <input type="text" name="q" /> <input type="submit" value="Go" /> <input type="hidden" name="check_keywords" value="yes" /> <input type="hidden" name="area" value="default" /> </form> </div> </div> <script type="text/javascript">$('#searchbox').show(0);</script> </div> </div> <div class="clearer"></div> </div> <div class="related" role="navigation" aria-label="related navigation"> <h3>Navigation</h3> <ul> <li class="right" style="margin-right: 10px"> <a href="../../genindex.html" title="General Index" >index</a></li> <li class="right" > <a href="../../py-modindex.html" title="Python Module Index" >modules</a> |</li> <li class="right" > <a href="collation.html" title="collation – Tools for working with collations." >next</a> |</li> <li class="right" > <a href="change_stream.html" title="change_stream – Watch changes on a collection" >previous</a> |</li> <li class="nav-item nav-item-0"><a href="../../index.html">PyMongo 3.7.2 documentation</a> »</li> <li class="nav-item nav-item-1"><a href="../index.html" >API Documentation</a> »</li> <li class="nav-item nav-item-2"><a href="index.html" ><code class="docutils literal notranslate"><span class="pre">pymongo</span></code> – Python driver for MongoDB</a> »</li> </ul> </div> <div class="footer" role="contentinfo"> © Copyright MongoDB, Inc. 2008-present. MongoDB, Mongo, and the leaf logo are registered trademarks of MongoDB, Inc. </div> </body> </html>