legacy-opcodes.txt

.. _wire-legacy-opcodes:

==============
Legacy Opcodes
==============

.. default-domain:: mongodb

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

This page describes legacy opcodes that are no longer supported by
MongoDB. These legacy opcodes are:

- Deprecated as of MongoDB 5.0.
- Unsupported as of MongoDB 5.1.

Starting in MongoDB 5.1, :ref:`OP_MSG <wire-op-msg>` and
:ref:`OP_COMPRESSED <wire-op-compressed>` are the only supported opcodes
to send requests to a MongoDB server.

.. _wire-op-delete:

OP_DELETE
---------

The OP_DELETE message is used to remove one or more documents from a
collection. The format of the OP_DELETE message is:

.. code-block:: c

   struct {
       MsgHeader header;             // standard message header
       int32     ZERO;               // 0 - reserved for future use
       cstring   fullCollectionName; // "dbname.collectionname"
       int32     flags;              // bit values - see below for details.
       document  selector;           // query object.  See below for details.
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``ZERO``

     - Integer value of 0.  Reserved for future use.

   * - ``fullCollectionName``

     - The full collection name, specifically its namespace. The
       namespace is the concatenation of the database name with the
       collection name, using a ``.`` for the concatenation. For
       example, for the database ``test`` and the collection
       ``contacts``, the full collection name is ``test.contacts``.

   * - ``flags``

     - Bit values for the operation: The bit values correspond to the
       following:

       - ``0`` corresponds to SingleRemove. If set, the database will
         remove only the first matching document in the collection.
         Otherwise all matching documents will be removed.

       - ``1``-``31`` are reserved. Must be set to 0.

   * - ``selector``

     - BSON document that represent the query used to select the
       documents to be removed. The selector contains one or more
       elements, all of which must match for a document to be removed
       from the collection.

There is no response to an OP_DELETE message.

.. _wire-op-get-more:

OP_GET_MORE
-----------

The OP_GET_MORE message is used to query the database for documents in a
collection. The format of the OP_GET_MORE message is:

.. code-block:: c

   struct {
       MsgHeader header;             // standard message header
       int32     ZERO;               // 0 - reserved for future use
       cstring   fullCollectionName; // "dbname.collectionname"
       int32     numberToReturn;     // number of documents to return
       int64     cursorID;           // cursorID from the OP_REPLY
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``ZERO``

     - Integer value of 0.  Reserved for future use.

   * - ``fullCollectionName``

     - The full collection name, specifically its namespace. The
       namespace is the concatenation of the database name with the
       collection name, using a ``.`` for the concatenation. For
       example, for the database ``test`` and the collection
       ``contacts``, the full collection name is ``test.contacts``.

   * - ``numberToReturn``

     - Limits the number of documents in the first :ref:`OP_REPLY
       <wire-op-reply>` message to the query. However, the database will
       still establish a cursor and return the ``cursorID`` to the
       client if there are more results than ``numberToReturn``. If the
       client driver offers 'limit' functionality (like the SQL LIMIT
       keyword), then it is up to the client driver to ensure that no
       more than the specified number of document are returned to the
       calling application.

       If ``numberToReturn`` is:
       
       - ``0``, the database uses the default
         return size.
         
       - Negative, the database returns that number and close the
         cursor. No further results for that query can be fetched.
         
       - ``1``, the server will treat the value  as ``-1`` (closing the
         cursor automatically).

   * - ``cursorID``
     - Cursor identifier that came in the :ref:`OP_REPLY
       <wire-op-reply>`. This must be the value that came from the
       database.

The database will respond to an OP_GET_MORE message with an
:ref:`OP_REPLY <wire-op-reply>` message.

.. _wire-op-insert:

OP_INSERT
---------

The OP_INSERT message is used to insert one or more documents into a
collection. The format of the OP_INSERT message is:

.. code-block:: c

   struct {
       MsgHeader header;             // standard message header
       int32     flags;              // bit values - see below
       cstring   fullCollectionName; // "dbname.collectionname"
       document* documents;          // one or more documents to insert into the collection
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``flags``

     - Bit values for the operation: The bit values correspond to the
       following:

       - ``0`` corresponds to ContinueOnError. If set, the database
         will not stop processing a bulk insert if one fails (for
         example, due to duplicate IDs). This makes bulk insert behave
         similarly to a series of single inserts, except lastError will
         be set if any insert fails, not just the last one. If multiple
         errors occur, only the most recent will be reported by
         getLastError.

       - ``1``-``31`` are reserved. Must be set to 0.

   * - ``fullCollectionName``

     - The full collection name, specifically its namespace. The
       namespace is the concatenation of the database name with the
       collection name, using a ``.`` for the concatenation. For
       example, for the database ``test`` and the collection
       ``contacts``, the full collection name is ``test.contacts``.

   * - ``documents``

     - One or more documents to insert into the collection. If there
       are more than one, they are written to the socket in sequence,
       one after another.

There is no response to an OP_INSERT message.

.. _wire-op-kill-cursors:

OP_KILL_CURSORS
---------------

The OP_KILL_CURSORS message is used to close an active cursor in the
database. This is necessary to ensure that database resources are
reclaimed at the end of the query. The format of the OP_KILL_CURSORS
message is:

.. code-block:: bash

   struct {
       MsgHeader header;            // standard message header
       int32     ZERO;              // 0 - reserved for future use
       int32     numberOfCursorIDs; // number of cursorIDs in message
       int64*    cursorIDs;         // sequence of cursorIDs to close
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``ZERO``

     - Integer value of 0.  Reserved for future use.

   * - ``numberOfCursorIDs``

     - The number of cursor IDs that are in the message.

   * - ``cursorIDs``

     - "Array" of cursor IDs to be closed. If there are more than one,
       they are written to the socket in sequence, one after another.

If a cursor is read until exhausted (read until :ref:`OP_QUERY <wire-op-query>`
or :ref:`OP_GET_MORE <wire-op-get-more>` returns zero
for the cursor id), there is no need to kill the cursor.

.. _wire-op-query:

OP_QUERY
--------

The OP_QUERY message is used to query the database for documents in a
collection. The format of the OP_QUERY message is:

.. code-block:: c

   struct OP_QUERY {
       MsgHeader header;                 // standard message header
       int32     flags;                  // bit values of query options.  See below for details.
       cstring   fullCollectionName ;    // "dbname.collectionname"
       int32     numberToSkip;           // number of documents to skip
       int32     numberToReturn;         // number of documents to return
                                         //  in the first OP_REPLY batch
       document  query;                  // query object.  See below for details.
     [ document  returnFieldsSelector; ] // Optional. Selector indicating the fields
                                         //  to return.  See below for details.
   }


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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``flags``

     - Bit values for the operation: The bit values correspond to the
       following:

       - ``0`` is reserved. Must be set to 0.

       - ``1`` corresponds to TailableCursor. Tailable means cursor is
         not closed when the last data is retrieved. Rather, the cursor
         marks the final object's position. You can resume using the
         cursor later, from where it was located, if more data were
         received. Like any latent cursor, the cursor may become
         invalid at some point (CursorNotFound) – for example if the
         final object it references were deleted.

       - ``2`` corresponds to SlaveOk. Allow query of replica slave.
         Normally these return an error except for namespace "local".

       - ``3`` corresponds to OplogReplay. You need not specify this flag 
         because the optimization automatically happens for eligible queries on 
         the oplog. See :ref:`oplogReplay <find-cmd-fields>` for more 
         information.

       - ``4`` corresponds to NoCursorTimeout. The server normally
         times out idle cursors after an inactivity period (10 minutes)
         to prevent excess memory use. Set this option to prevent that.

       - ``5`` corresponds to AwaitData. Use with TailableCursor. If
         the cursor is at the end of the data, block for a while rather
         than returning no data. After a timeout period, the server
         returns as normal.

       - ``6`` corresponds to Exhaust. Stream the data down full blast
         in multiple "more" packages, on the assumption that the client
         will fully read all data queried. Faster when you are pulling
         a lot of data and know you want to pull it all down. Note: the
         client is not allowed to not read all the data unless it
         closes the connection.

       - ``7`` corresponds to Partial. Get partial results from a
         mongos if some shards are down (instead of throwing an error)

       - ``8``-``31`` are reserved. Must be set to 0.

   * - ``fullCollectionName``

     - The full collection name, specifically its namespace. The
       namespace is the concatenation of the database name with the
       collection name, using a ``.`` for the concatenation. For
       example, for the database ``test`` and the collection
       ``contacts``, the full collection name is ``test.contacts``.

   * - ``numberToSkip``

     - Sets the number of documents to omit - starting from the first
       document in the resulting dataset - when returning the result of
       the query.

   * - ``numberToReturn``

     - Limits the number of documents in the first :ref:`OP_REPLY
       <wire-op-reply>` message to the query. However, the database will
       still establish a cursor and return the ``cursorID`` to the
       client if there are more results than ``numberToReturn``. If the
       client driver offers 'limit' functionality (like the SQL LIMIT
       keyword), then it is up to the client driver to ensure that no
       more than the specified number of document are returned to the
       calling application.
       
       If ``numberToReturn`` is:
       
       - ``0``, the database uses the default
         return size.
         
       - Negative, the database returns that number and close the
         cursor. No further results for that query can be fetched.
         
       - ``1``, the server will treat the value  as ``-1`` (closing the
         cursor automatically).

   * - ``query``
     - BSON document that represents the query. The query contains
       one or more elements, all of which must match for a document to
       be included in the result set. Possible elements include
       ``$query``, ``$orderby``, ``$hint``, and ``$explain``.

   * - ``returnFieldsSelector``

     - Optional. BSON document that limits the fields in the returned
       documents. The ``returnFieldsSelector`` contains one or more
       elements, each of which is the name of a field that should be
       returned, and and the integer value ``1``. In JSON notation, a
       ``returnFieldsSelector`` to limit to the fields ``a``, ``b`` and
       ``c`` would be:

       .. code-block:: javascript

          { a : 1, b : 1, c : 1}

The database will respond to an OP_QUERY message with an
:ref:`OP_REPLY <wire-op-reply>` message.

.. note::

   MongoDB 5.1 removes support for both ``OP_QUERY`` find operations
   and ``OP_QUERY`` commands. As an exception, ``OP_QUERY`` is still
   supported for running the :dbcommand:`hello` and ``isMaster``
   commands as part of the connection handshake.

.. _wire-op-reply:

OP_REPLY
--------

The ``OP_REPLY`` message is sent by the database in response to an
:ref:`OP_QUERY <wire-op-query>` or :ref:`OP_GET_MORE
<wire-op-get-more>` message. The format of an OP_REPLY message is:

.. code-block:: bash

   struct {
       MsgHeader header;         // standard message header
       int32     responseFlags;  // bit values - see details below
       int64     cursorID;       // cursor ID if client needs to do get more's
       int32     startingFrom;   // where in the cursor this reply is starting
       int32     numberReturned; // number of documents in the reply
       document* documents;      // documents
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``responseFlags``

     - Bit values for the operation: The bit values correspond to the
       following:

       - ``0`` corresponds to CursorNotFound. Is set when ``getMore`` is
         called but the cursor ID is not valid at the server. Returned
         with zero results.

       - ``1`` corresponds to QueryFailure. Is set when query failed.
         Results consist of one document containing an "$err" field
         describing the failure.

       - ``2`` corresponds to ShardConfigStale. Drivers should ignore
         this. Only :binary:`~bin.mongos` will ever see this set, in which
         case, it needs to update config from the server.

       - ``3`` corresponds to AwaitCapable. Is set when the server
         supports the AwaitData Query option. If it doesn't, a client
         should sleep a little between getMore's of a Tailable cursor.

       - ``4``-``31`` are reserved. Ignore.

   * - ``cursorID``

     - The ``cursorID`` that this OP_REPLY is a part of. In the event
       that the result set of the query fits into one OP_REPLY message,
       ``cursorID`` will be 0. This ``cursorID`` must be used in any
       :ref:`OP_GET_MORE <wire-op-get-more>` messages used to get more
       data, and also must be closed by the client when no longer
       needed via a :ref:`OP_KILL_CURSORS <wire-op-kill-cursors>`
       message.

   * - ``startingFrom``

     - Starting position in the cursor.

   * - ``numberReturned``

     - Number of documents in the reply.

   * - ``documents``

     - Returned documents.

.. _wire-op-update:

OP_UPDATE
---------

The OP_UPDATE message is used to update a document in a collection. The
format of a OP_UPDATE message is the following:

.. code-block:: c

   struct OP_UPDATE {
       MsgHeader header;             // standard message header
       int32     ZERO;               // 0 - reserved for future use
       cstring   fullCollectionName; // "dbname.collectionname"
       int32     flags;              // bit values. see below
       document  selector;           // the query to select the document
       document  update;             // specification of the update to perform
   }

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

   * - Field
     - Description

   * - ``header``

     - Message header. See :ref:`wp-message-header`.

   * - ``ZERO``

     - Integer value of 0.  Reserved for future use.

   * - ``fullCollectionName``

     - The full collection name, specifically its namespace. The
       namespace is the concatenation of the database name with the
       collection name, using a ``.`` for the concatenation. For
       example, for the database ``test`` and the collection
       ``contacts``, the full collection name is ``test.contacts``.

   * - ``flags``

     - Bit values for the operation: The bit values correspond to the
       following:

       - ``0`` corresponds to Upsert. If set, the database will insert
         the supplied object into the collection if no matching
         document is found.

       - ``1`` corresponds to MultiUpdate.If set, the database will
         update all matching objects in the collection. Otherwise only
         updates first matching document.

       - ``2``-``31`` are reserved. Must be set to 0.

   * - ``selector``

     - BSON document that specifies the query for selection of the
       document to update.

   * - ``update``

     - BSON document that specifies the update to be performed. For
       information on specifying updates see the :ref:`Update
       Operations <update-operators>` documentation.

There is no response to an OP_UPDATE message.