Docs Menu

Docs HomeDevelop ApplicationsMongoDB Manual

Legacy Opcodes

On this page

  • OP_DELETE
  • OP_GET_MORE
  • OP_INSERT
  • OP_KILL_CURSORS
  • OP_QUERY
  • OP_REPLY
  • OP_UPDATE

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, OP_MSG and OP_COMPRESSED are the only supported opcodes to send requests to a MongoDB server.

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

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.
}
Field
Description
header
Message header. See Standard 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.

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:

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
}
Field
Description
header
Message header. See Standard 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 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 OP_REPLY. This must be the value that came from the database.

The database will respond to an OP_GET_MORE message with an OP_REPLY message.

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

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
}
Field
Description
header
Message header. See Standard 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.

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:

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
}
Field
Description
header
Message header. See Standard 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 OP_QUERY or OP_GET_MORE returns zero for the cursor id), there is no need to kill the cursor.

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

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.
}
Field
Description
header
Message header. See Standard 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. Starting in MongoDB 4.4, you need not specify this flag because the optimization automatically happens for eligible queries on the oplog. See oplogReplay 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 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:

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

The database will respond to an OP_QUERY message with an 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 hello and isMaster commands as part of the connection handshake.

The OP_REPLY message is sent by the database in response to an OP_QUERY or OP_GET_MORE message. The format of an OP_REPLY message is:

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
}
Field
Description
header
Message header. See Standard 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 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 OP_GET_MORE messages used to get more data, and also must be closed by the client when no longer needed via a OP_KILL_CURSORS message.
startingFrom
Starting position in the cursor.
numberReturned
Number of documents in the reply.
documents
Returned documents.

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

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
}
Field
Description
header
Message header. See Standard 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 Update Operations documentation.

There is no response to an OP_UPDATE message.

←  MongoDB Wire ProtocolLog Messages →