3.6.txt

=================================================
Release Notes for MongoDB 3.6 (Release Candidate)
=================================================

.. default-domain:: mongodb

.. contents:: On this page
   :local:
   :backlinks: none
   :depth: 1
   :class: twocols

.. include:: /includes/in-dev.rst

Security
--------

.. _3.6-bind-to-localhost:

Default Bind to Localhost
~~~~~~~~~~~~~~~~~~~~~~~~~~

.. include:: /includes/fact-default-bind-ip-change.rst

Additional Security Enhancements
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- Added :parameter:`opensslCipherConfig` parameter to control the
  OpenSSL ciphers when using TLS/SSL encryption.

- If authentication is turned on, you can only issue a :dbcommand:`getMore`
  against cursors you created.

- Added ``authenticationRestrictions`` parameter to the
  :method:`db.createUser()` and :method:`db.updateUser()` methods to
  restrict database user connections to specified IP addresses.

- Added :authaction:`convertToCapped` action to :authrole:`restore`
  role.

  .. seealso:: :ref:`3.6-compatibility-enabled`

.. _3.6-rel-notes-aggregation:

Aggregation
-----------

The following features are available starting in MongoDB 3.6.

More Expressive ``$lookup``
~~~~~~~~~~~~~~~~~~~~~~~~~~~

:pipeline:`$lookup` adds support for specifying multiple join
conditions as well as uncorrelated sub-queries by allowing variable
specification and pipeline execution on the joined collection.

For details, see the :pipeline:`$lookup` syntax for
:ref:`lookup-syntax-let-pipeline`.

New Aggregation Stages
~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 adds the following new aggregation pipeline stages:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Operator
     - Description

   * - :pipeline:`$listSessions`

     - Lists sessions in the ``system.sessions`` collection in the
       ``config`` database.

   * - :pipeline:`$listLocalSessions`

     - Lists sessions cached in memory by the server.

   * - :pipeline:`$currentOp`

     - Returns a stream of documents containing information
       on active and/or dormant operations on a :program:`mongod`
       instance.

New Aggregation Operators
~~~~~~~~~~~~~~~~~~~~~~~~~

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Operator
     - Description

   * - :expression:`$arrayToObject`

     - Converts an array of key value pairs to a document.

   * - :expression:`$objectToArray`

     - Converts a document to an array of documents representing
       key-value pairs.

   * - :expression:`$mergeObjects`

     - Combines multiple documents into a single document.

   * - :expression:`$dateFromString`

     - Converts a date/time string to a date object.

   * - :expression:`$dateFromParts`
     - Constructs a BSON Date object given the date's constituent
       parts.

   * - :expression:`$dateToParts`
     - Returns a document containing the constituent parts of a date.


New Aggregation Helper
~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 adds a helper, :method:`db.aggregate()`, to perform
aggregations that do not rely on an underlying collection, such
as those that start with :pipeline:`$currentOp` or
:pipeline:`$listLocalSessions`.

New Aggregation Variable
~~~~~~~~~~~~~~~~~~~~~~~~

:variable:`REMOVE` allows for the conditional exclusion of a field.

New Options
~~~~~~~~~~~

:dbcommand:`aggregate` command and the
:method:`db.collection.aggregate()` method support the following new options:

- ``hint`` option to specify the index to use.

  .. note::

     The ``hint`` does not apply to :pipeline:`$lookup` and
     :pipeline:`$graphLookup` stages.

- ``comment`` option to help trace the operation through the database
  profiler, currentOp, and logs.

Support for Time Zones
~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 adds support for time zones to :doc:`aggregation date
operators </reference/operator/aggregation-date>`.

.. seealso:: :ref:`Aggregation Compatibility Changes <aggregate-compatibility>`


Array Update Operator Enhancements
----------------------------------

.. _3.6-arrayFilters:

``arrayFilters``
~~~~~~~~~~~~~~~~

The following commands and methods can accept an ``arrayFilters``
parameter to specify which elements to modify in an array field:

.. list-table::
   :header-rows: 1
   :widths: 30 70

   * - Commands
     - Methods

   * - :dbcommand:`findAndModify`
     - | :method:`db.collection.findOneAndUpdate()`
       | :method:`db.collection.findAndModify()`

   * - :dbcommand:`update`
     - | :method:`db.collection.updateOne()`
       | :method:`db.collection.updateMany()`
       | :method:`db.collection.update()`

   * -

     - | :method:`db.collection.bulkWrite()` for :ref:`updateOne and
          updateMany operations <bulkwrite-write-operations-updateOneMany>`

       | :method:`Bulk.find.arrayFilters()` for ``Bulk()`` operation
         methods :method:`~Bulk.find.updateOne()` and
         :method:`~Bulk.find.update()`.

Multi-Element Array Updates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 adds the following new positional operators for update
operations on arrays and nested arrays:

- The all positional :update:`$[]` operator updates all elements in
  an array.

- The filtered positional :update:`$[\<identifier\>]` operator updates
  all elements in an array that match the :ref:`3.6-arrayFilters`
  criteria.

Negative Array Index Position for ``push``
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The :update:`$position` modifier for the :update:`push` update operator
can accept a negative array index value to indicate a position starting
from the end of the array.

.. _3.6-change-streams:

Change Streams
--------------

MongoDB 3.6 supports opening change streams against replica sets and
sharded clusters with replica set shards.

Change streams allow applications to access real-time data changes 
without the complexity and risk of tailing the :term:`oplog`. 
Applications can use change streams to subscribe to all data changes
on a collection and respond to those changes.

You can open a change stream from any 3.6-series driver using the
:method:`db.collection.watch()` method. See the documentation for 
your preferred driver for complete instructions on usage.

See :ref:`changeStreams` for more information. 

.. important::

   To use change streams, ``featureCompatibilityVersion`` must be set to
   "3.6". For more information, see :ref:`view-fcv` and
   :dbcommand:`setFeatureCompatibilityVersion`.

.. _3.6-sessions:


Sessions
--------

To provide causal consistency, MongoDB 3.6 enables :ref:`causal
consistency <causal-consistency>` in :ref:`sessions <sessions>`. A
causally consistent session denotes that the associated sequence of
read and *acknowledged* write operations have a causal relationship
that is reflected by their ordering. Client applications must ensure
that only one thread at a time executes these operations in a session.

Clients can start a :ref:`session <sessions>` and associate operations
with a specific session. Client applications must ensure that only one
thread at a time executes these operations in a session.

.. important::

   To use sessions, ``featureCompatibilityVersion`` must be set to
   "3.6". For more information, see :ref:`view-fcv` and
   :dbcommand:`setFeatureCompatibilityVersion`.

Sessions Commands
~~~~~~~~~~~~~~~~~

The following session commands are available:

.. list-table::
   :header-rows: 1
   :widths: 15 50

   * - Commands
     - Descriptions

   * - :dbcommand:`endSessions`

     - Expire specified sessions.

   * - :dbcommand:`killAllSessions`

     - Kill all sessions.

   * - :dbcommand:`killAllSessionsByPattern`

     - Kill all sessions that match the specified pattern.

   * - :dbcommand:`killSessions`

     - Kill specified sessions.

   * - :dbcommand:`refreshSessions`

     - Refresh idle sessions.

   * - :dbcommand:`startSession`

     - Starts a new session.


``mongo`` Shell Changes
~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 adds the new command-line option :option:`--retryWrites` to
the :program:`mongo` shell. The option enables retryable writes as the
default for sessions in the :program:`mongo` shell.

The following new methods have been added to the ``Mongo()`` connection
object in the :program:`mongo` shell:

- :method:`Mongo.isCausalConsistency()`

- :method:`Mongo.startSession()`

- Various :method:`Session` methods

- Various :method:`SessionOptions` methods

Aggregation Stages
~~~~~~~~~~~~~~~~~~

To support sessions, MongoDB 3.6 adds the following new aggregation
pipeline stages:

.. list-table::
   :header-rows: 1
   :widths: 20 80

   * - Operator
     - Description

   * - :pipeline:`$listSessions`

     - Lists sessions in the ``system.sessions`` collection in the
       ``config`` database.

   * - :pipeline:`$listLocalSessions`

     - Lists sessions cached in memory by the server.

Command Options
~~~~~~~~~~~~~~~

The following options are available for all commands:

.. list-table::
   :header-rows: 1
   :widths: 15 15 50

   * - Option
     - Type
     - Description

   * - ``lsid``
     - Document
     - .. include:: /includes/extracts/sessions-option-sessionId.rst

   * - ``txnNumber``

     - 64-bit integer

     - .. include:: /includes/extracts/sessions-option-txnId.rst

For the :dbcommand:`delete`, :dbcommand:`insert`, and :dbcommand:`update`
commands that take an array of statements, the following option is also
available:

.. list-table::
   :header-rows: 1
   :widths: 15 15 50

   * - Option
     - Type
     - Description

   * - ``stmtIds``

     - Array of 32-bit integers

     - .. include:: /includes/extracts/sessions-option-stmtIds.rst

.. |operations| replace:: write operations

.. |operation| replace:: write

Parameters
~~~~~~~~~~

The following new parameters are available for server sessions:

- :parameter:`logicalSessionRefreshMinutes`

- :parameter:`localLogicalSessionTimeoutMinutes`

- :parameter:`maxAcceptableLogicalClockDriftSecs`

JSON Schema
-----------

MongoDB 3.6 adds the :query:`$jsonSchema` operator to support
:doc:`document validation </core/document-validation>` using JSON
Schema. For details, see :query:`$jsonSchema`.

To use :query:`$jsonSchema`, ``featureCompatibilityVersion`` must be
set to "3.6".

Replica Sets
------------

- Deprecate replica set protocol version 0 (``pv0``). For more
  information on the replica set protocol versions, see
  :doc:`/reference/replica-set-protocol-versions`.

- Added the :dbcommand:`replSetResizeOplog` command to dynamically
  resize a replica set member's oplog. Available for instances running
  the WiredTiger storage engine.

- Added the
  :ref:`catchUpTakeoverDelayMillis <repl-conf-catchup-takeover-delay>`
  configuration option, dictating the amount of time a node waits to
  run for election after determining that it is ahead of the current
  :term:`primary`.

- For replica sets that use the protocol version 1 (``pv1``), arbiters
  will vote no in elections if they detect a healthy primary of equal
  or greater priority to the candidate. For more information on replica
  set protocol versions, see
  :doc:`/reference/replica-set-protocol-versions`.

- Added the :parameter:`oplogInitialFindMaxSeconds` parameter to adjust
  how long a member of a :term:`replica set` should wait for its
  :dbcommand:`find` command to finish during :ref:`data synchronization
  <replica-set-sync>`.

- Added the :parameter:`waitForSecondaryBeforeNoopWriteMS` parameter to
  specify how long a secondary must wait if the ``afterClusterTime`` is
  greater than the last applied time from the oplog.

Sharded Clusters
----------------

- Added :parameter:`ShardingTaskExecutorPoolMaxConnecting` parameter
  for :program:`mongos` to control the rate at which :program:`mongos`
  adds connections to a :program:`mongod` instance.


General Enhancements
--------------------

Collection Identifier
~~~~~~~~~~~~~~~~~~~~~

Collections have an immutable :ref:`unique identifier
<collections-uuids>`.

New Operators
~~~~~~~~~~~~~

MongoDB 3.6 adds the following new query operators:

- The new :query:`$jsonSchema` operator matches documents that validate
  against the given JSON Schema. To use :query:`$jsonSchema`,
  ``featureCompatibilityVersion`` must be set to "3.6".

- The :query:`$expr` allows the use of aggregation expressions within
  the query language.

.. seealso::

   :ref:`3.6-compatibility-enabled`

Removed Operators
~~~~~~~~~~~~~~~~~

MongoDB 3.6 removes the deprecated ``$pushAll`` update operator. For more
information, see :ref:`3.6-pushall-compatibility`.

Indexes
~~~~~~~

- An index can cover a query on fields within nested documents.

- Multikey indexes can cover queries over non-array keys if the index
  tracks which fields make it multikey.

- When creating an index, you cannot specify ``*`` as the name of the
  index. See :ref:`3.6-index-asterisk`.

Commands
~~~~~~~~

- Added the following options to the :dbcommand:`listDatabases` admin
  command:

  - ``nameOnly`` to return only the database names (which does not
    require database locks) instead of returning both the database names
    and size information (which does require database locks).

  - ``filter`` to return databases that match the specified match
    criteria on the outputs.

- Modified behavior of the :dbcommand:`validate` command and the
  :method:`db.collection.validate()` method such that only for ``full``
  validation does the WiredTiger storage engine force a checkpoint,
  flush all in-memory data to disk, then verify the on-disk data. See
  also :ref:`3.6-validate-compatibility`.

- The ``<database>.system.profile`` entry for :dbcommand:`update` and
  :dbcommand:`delete` contains the entire update/delete document applied
  to the named collection.

- :dbcommand:`dropDatabase` waits until all collections drops in the
  database have propagated to a majority of the replica set members.

- For commands run on replica sets and sharded clusters, the response
  documents include the ``operationTime`` and ``$clusterTime``. See
  :method:`db.runCommand` and :method:`db.adminCommand`.

Wire Protocol and Compression
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

- MongoDB 3.6 introduces a new :doc:`wire protocol
  </reference/mongodb-wire-protocol>` opcode called :ref:`wire-op-msg`.
  This opcode's message format is extensible and designed to subsume
  the functionality of other opcodes.

- Added support for the ``zlib`` compressor for
  ``--networkMessageCompressors`` option (or
  :setting:`net.compression.compressors` setting if using the
  configuration file). ``--networkMessageCompressors`` option (or
  :setting:`net.compression.compressors` setting) enables network
  compression for communication among :program:`mongod`,
  :program:`mongos`, :program:`mongo` shell, and drivers that support
  the ``OP_COMPRESSED`` message format.

- Enables ``snappy`` network compression for communication, by default,
  among :program:`mongod`, :program:`mongos`, and :program:`mongo`
  shell.

Read Concern
~~~~~~~~~~~~

:readconcern:`"majority"` read concern is always enabled and
deprecates/obsoletes the use of :option:`--enableMajorityReadConcern`
and :setting:`replication.enableMajorityReadConcern`.

FTDC
~~~~

MongoDB 3.6 adds support for Diagnostics Capture (also known as ``FTDC``) in
:program:`mongos`. In previous versions, the feature is available for
:program:`mongod` only. See :ref:`param-ftdc`.

.. note:: FTDC is enabled by default.

Additional Enhancements
~~~~~~~~~~~~~~~~~~~~~~~

MongoDB 3.6 includes the following enhancements:

- Added support for specifying full Unix domain socket paths with
  :option:`--bind_ip`.

- :program:`mongod` now offers a :option:`--timeZoneInfo` option. Use this
  option to specify the path to your system time zone database. The default
  configuration file included with Linux and macOS packages sets this to
  ``/usr/share/zoneinfo``.

- Date operations now accept consistent date ranges across all supported
  operating systems. You may safely work with years in the range ``0``
  through ``9999``.

- The new :parameter:`honorSystemUmask` startup option for
  :program:`mongod` causes new files created by MongoDB to have
  the read/write permissions specified by the `umask
  <https://en.wikipedia.org/wiki/Umask>`_ of the user who runs the
  :program:`mongod` process. Only available on Linux and macOS systems.

- The :limit:`maxWriteBatchSize <Write Command Batch Limit Size>` limit
  of a database, which indicates the maximum number of write operations
  permitted in a write batch, raises from ``1,000`` to ``100,000``.

Changes Affecting Compatibility
-------------------------------

Some changes can affect compatibility and may require user actions. For
a detailed list of compatibility changes, see
:doc:`/release-notes/3.6-compatibility`.

.. _3.6-upgrade:

Upgrade Procedures
------------------

.. note::

   To upgrade, the 3.4 instances must have
   ``featureCompatibilityVersion`` set to 3.4. For more information,
   see :ref:`view-fcv` and :dbcommand:`setFeatureCompatibilityVersion`.

For upgrade instructions, see:

- :doc:`/release-notes/3.6-upgrade-standalone`

- :doc:`/release-notes/3.6-upgrade-replica-set`

- :doc:`/release-notes/3.6-upgrade-sharded-cluster`

If you need guidance on upgrading to 3.6, `MongoDB offers major version
upgrade services
<https://www.mongodb.com/products/consulting?jmp=docs>`_
to help ensure a smooth transition without interruption to your MongoDB application.

Download
--------

To download the MongoDB 3.6 Release Candidate, go to the `MongoDB
Download Center
<https://www.mongodb.com/download-center?jmp=docs#development>`_

.. seealso::

   - `All Third Party License Notices <https://github.com/mongodb/mongo/blob/v3.6/distsrc/THIRD-PARTY-NOTICES>`_.

   - `All JIRA issues resolved in 3.6 <http://bit.ly/2zjO8DD>`_.

Report an Issue
---------------

To report an issue, see
https://github.com/mongodb/mongo/wiki/Submit-Bug-Reports for
instructions on how to file a JIRA ticket for the MongoDB server or one
of the related projects.


.. class:: hidden

   .. toctree::

      /release-notes/3.6-compatibility
      /release-notes/3.6-upgrade-standalone
      /release-notes/3.6-upgrade-replica-set
      /release-notes/3.6-upgrade-sharded-cluster
      /release-notes/3.6-downgrade-standalone
      /release-notes/3.6-downgrade-replica-set
      /release-notes/3.6-downgrade-sharded-cluster