Nota
Esta especificación del protocolo MongoDB Wire está licenciada bajo una licencia Creative Commons Atribución-NoComercial-CompartirIgual 3.0 de Estados Unidos.No puede utilizar ni adaptar este material para ningún propósito comercial, como crear una base de datos comercial o una oferta de base de datos como servicio.
Introducción
El protocolo de conexión de MongoDB es un protocolo sencillo de tipo solicitud-respuesta basado en sockets. Los clientes se comunican con el servidor de bases de datos a través de un socket TCP/IP normal.
Socket TCP/IP
Los clientes deben conectarse a la base de datos con un socket TCP/IP normal.
Puerto
El número de puerto predeterminado para mongodLas mongos instancias y 27017 son. El número de puerto para mongod y es configurable y puede mongos variar.
Orden de bytes
Todos los números enteros en el protocolo de conexión de MongoDB utilizan el orden de bytes little-endian, es decir, el byte menos significativo primero.
Tipos y formatos de mensajes
MongoDB utiliza el código de operación OP_MSG tanto para las solicitudes del cliente como para las respuestas de la base de datos. Hay varios formatos de mensaje utilizados en versiones anteriores de MongoDB que han quedado obsoletos en favor de OP_MSG.
Nota
Esta página utiliza un
structtipo C para describir la estructura del mensaje.Los tipos utilizados en este documento, como
int32ycstring, son los mismos que los definidos en la especificación BSON.Para indicar la repetición, el documento utiliza la notación de asterisco de la especificación BSON. Por ejemplo,
int64*indica que se pueden escribir en el socket uno o más caracteres del tipo especificado, uno tras otro.El encabezado del mensaje estándar se escribe como
MsgHeader. Las constantes enteras se escriben en mayúsculas (p. ej.,ZEROpara el valor entero 0).
Encabezado de mensaje estándar
En general, cada mensaje consta de un encabezado de mensaje estándar seguido de datos específicos de la solicitud. El encabezado del mensaje estándar está estructurado de la siguiente manera:
struct MsgHeader { int32 messageLength; // total message size, including this int32 requestID; // identifier for this message int32 responseTo; // requestID from the original request // (used in responses from db) int32 opCode; // request type - see table below for details }
Campo | Descripción |
|---|---|
| El tamaño total del mensaje en bytes. Este total incluye los 4 bytes que contienen la longitud del mensaje. |
| Un identificador generado por el cliente o la base de datos que identifica de forma única este mensaje. En el caso de los mensajes generados por el cliente (p. ej., OP_QUERY y OP_GET_MORE), se devolverá en el |
| En el caso de un mensaje de la base de datos, este será el |
| Tipo de mensaje.Consulte "Códigos de operación de solicitud" para obtener más información. |
Solicitar códigos de operación
Nota
A partir de MongoDB 2.6
maxWireVersion3y, los controladores de MongoDB utilizan los comandos de base deinsertdatos,updatey endeletelugarOP_INSERTde,OP_UPDATEyOP_DELETEpara las escrituras confirmadas. La mayoría de los controladores siguen utilizando códigos de operación para las escrituras no confirmadas.En la versión 4.2, MongoDB remueve los protocolos internos obsoletos
OP_COMMANDyOP_COMMANDREPLY.En la versión 5.0, MongoDB descontinúa los siguientes códigos de operación:
OP_REPLYOP_UPDATEOP_INSERTOP_QUERY[1]OP_GET_MOREOP_DELETEOP_KILL_CURSORS
En lugar de estos códigos de operación, utilice OP_MSG.
[1] MongoDB deja 5.0 obsoletas OP_QUERYlas operaciones de búsqueda y losOP_QUERYcomandos. Como excepción,OP_QUERYaún es compatible para ejecutar loshelloisMastercomandos y como parte del protocolo de enlace de conexión.
MongoDB admite estos valores opCode:
Nombre del opcode | Valor | Comment |
|---|---|---|
| 2013 | Envía un mensaje utilizando el formato introducido en MongoDB 3.6. |
OP_REPLYDeprecated in MongoDB 5.0. | 1 | Responder a una solicitud de un cliente. |
OP_UPDATEDeprecated in MongoDB 5.0. | 2001 | Update document. |
OP_INSERTDeprecated in MongoDB 5.0. | 2002 | Inserta un nuevo documento. |
| 2003 | Anteriormente utilizado para OP_GET_BY_OID. |
OP_QUERYDeprecated in MongoDB 5.0. | 2004 | Realiza un query a una colección. |
OP_GET_MOREDeprecated in MongoDB 5.0. | 2005 | Obtén más datos de un query. Consulta Cursores. |
OP_DELETEDeprecated in MongoDB 5.0. | 2006 | Borra documentos. |
OP_KILL_CURSORSDeprecated in MongoDB 5.0. | 2007 | Notifica a la base de datos que el cliente ha terminado con el cursor. |
| 2012 | Abarca otros códigos de operación mediante compresión |
Mensajes de solicitud del cliente
OP_MSG
OP_MSG Es un formato de mensaje extensible diseñado para absorber la funcionalidad de otros códigos de operación. Este código de operación tiene el siguiente formato:
OP_MSG { MsgHeader header; // standard message header uint32 flagBits; // message flags Sections[] sections; // data sections optional<uint32> checksum; // optional CRC-32C checksum }
Campo | Descripción |
|---|---|
| Encabezado de mensaje estándar, como se describe en Encabezado de mensaje estándar. |
| Una máscara de bits enteros que contiene marcas de mensajes, como se describe en Bits de marca. |
| Secciones del cuerpo del mensaje, como se describen en Secciones. |
| Una suma de verificación CRC-32C opcional, como se describe en Suma de verificación. |
Bits de marca
El número entero flagBits es una máscara de bits que codifica marcas para modificar el formato y el comportamiento de OP_MSG.
Los primeros 16 bits (0-15) son obligatorios y los analizadores DEBEN mostrar un error si se establece un bit desconocido.
Los últimos 16 bits (16 a 31) son opcionales y los analizadores DEBEN ignorar cualquier bit de conjunto desconocido. Los proxies y otros reenviadores de mensajes DEBEN borrar cualquier bit opcional desconocido antes de reenviar los mensajes.
Bit | Nombre | Solicitud | Respuesta | Descripción |
|---|---|---|---|---|
0 |
| ✓ | ✓ | El mensaje termina con 4 bytes que contienen una suma de verificación CRC-32C [2]. Consulta Suma de verificación para obtener detalles. |
1 |
| ✓ | ✓ | Se enviará otro mensaje después de este sin que el receptor realice otra acción. El receptor NO DEBE enviar otro mensaje hasta recibir uno con |
16 |
| ✓ | El cliente está preparado para varias respuestas a esta solicitud con el bit Esto garantiza que se envíen varias respuestas solo cuando la capa de red del solicitante esté preparada para recibirlas. ImportanteMongoDB 3.6 ignora esta bandera y responderá con un solo mensaje. |
Secciones
Un mensaje OP_MSG contiene una o varias secciones. Cada sección comienza con un byte kind que indica su tipo. Todo lo que viene después del byte kind constituye la carga útil de la sección.
Los tipos de secciones disponibles son los siguientes.
Tipo 0: Cuerpo
Una sección del cuerpo se codifica como un único objeto BSON. El tamaño en el objeto BSON también sirve como tamaño de la sección. Este tipo de sección es el cuerpo estándar de solicitud y respuesta de comandos.
Todos los campos de nivel superior DEBEN tener un nombre único.
Tipo 1: Secuencia de documentos
Tipo | Descripción |
|---|---|
int32 | Tamaño de la sección en bytes. |
String C | Identificador de secuencia de documento. En todos los comandos actuales, este campo es el campo (posiblemente anidado) que está reemplazando de la sección del cuerpo. Este campo NO DEBE existir también en la sección del cuerpo. |
Cero o más objetos BSON |
|
suma de verificación
Cada mensaje PUEDE terminar con una suma de verificación CRC-32C [2] que cubra todos los bytes del mensaje excepto la propia suma de verificación.
Comenzando en MongoDB 4.2:
mongodinstancias,mongosinstancias y instancias de shell intercambiaránmongomensajes con sumas de comprobación si no utilizan la conexión TLS/SSL.mongodinstancias, instanciasmongosmongoy instancias de shell omitirán la suma de comprobación si se utiliza una conexión TLS/SSL.
Los drivers y los binarios más antiguos ignorarán la suma de verificación si se presentan con mensajes que contengan dicha suma.
La presencia de una suma de verificación se indica con el bit de marca checksumPresent.
OP_UPDATE
Obsoleto en MongoDB 5.0.
El mensaje OP_UPDATE se utiliza para actualizar un documento de una colección. Su formato es el siguiente:
struct OP_UPDATE { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use cstring fullCollectionName; // "dbname.collectionname" int32 flags; // bit vector. see below document selector; // the query to select the document document update; // specification of the update to perform }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Valor entero de 0. Reservado para uso futuro. |
| El nombre completo de la colección; es decir, el espacio de nombres. El nombre completo de la colección es la concatenación del nombre de la base de datos con el nombre de la colección, utilizando un |
| Vector de bits para especificar indicadores para la operación. Los valores de los bits corresponden a lo siguiente:
|
| Documento BSON que especifica la consulta para la selección del documento a actualizar. |
| Documento BSON que especifica la actualización a realizar. Para obtener información sobre cómo especificar las actualizaciones, consulte la documentación de Operaciones de actualización. |
No hay respuesta a un mensaje OP_UPDATE.
OP_INSERT
Obsoleto en MongoDB 5.0.
El mensaje OP_INSERT se utiliza para insertar uno o más documentos en una colección. El formato del mensaje OP_INSERT es
struct { MsgHeader header; // standard message header int32 flags; // bit vector - see below cstring fullCollectionName; // "dbname.collectionname" document* documents; // one or more documents to insert into the collection }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Vector de bits para especificar indicadores para la operación. Los valores de los bits corresponden a lo siguiente:
|
| El nombre completo de la colección; es decir, el espacio de nombres. El nombre completo de la colección es la concatenación del nombre de la base de datos con el nombre de la colección, utilizando un |
| Uno o más documentos para insertar en la colección. Si hay más de uno, se escriben en el socket secuencialmente, uno tras otro. |
No hay respuesta a un mensaje OP_INSERT.
OP_QUERY
Obsoleto en MongoDB 5.0.
El mensaje OP_QUERY se utiliza para consultar la base de datos de documentos de una colección. Su formato es:
struct OP_QUERY { MsgHeader header; // standard message header int32 flags; // bit vector 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. }
Campo | Descripción | |
|---|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. | |
| Vector de bits para especificar indicadores para la operación. Los valores de los bits corresponden a lo siguiente:
| |
| El nombre completo de la colección; es decir, el espacio de nombres. El nombre completo de la colección es la concatenación del nombre de la base de datos con el nombre de la colección, utilizando un | |
| Establece la cantidad de documentos que se deben omitir (comenzando por el primer documento del conjunto de datos resultante) al devolver el resultado de la consulta. | |
| Limita el número de documentos en el primer mensaje OP_REPLY de la query. Sin embargo, la base de datos aún establecerá un cursor y devolverá el valor | |
| Documento BSON que representa la consulta. La consulta contendrá uno o más elementos, todos los cuales deben coincidir para que un documento se incluya en el conjunto de resultados. Los elementos posibles incluyen | |
| Opcional. Documento BSON que limita los campos en los documentos devueltos. El |
La base de datos responderá a un mensaje OP_QUERY con un mensaje OP_REPLY.
OP_OBTENER_MÁS
Obsoleto en MongoDB 5.0.
El mensaje OP_GET_MORE se utiliza para consultar la base de datos en busca de documentos de una colección. Su formato es:
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 }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Valor entero de 0. Reservado para uso futuro. |
| El nombre completo de la colección; es decir, el espacio de nombres. El nombre completo de la colección es la concatenación del nombre de la base de datos con el nombre de la colección, utilizando un |
| Limita el número de documentos en el primer mensaje OP_REPLY de la consulta. Sin embargo, la base de datos establecerá un cursor y devolverá |
| Identificador del cursor incluido en OP_REPLY. Debe ser el valor de la base de datos. |
La base de datos responderá a un mensaje OP_GET_MORE con un mensaje OP_REPLY.
OP_BORRAR
Obsoleto en MongoDB 5.0.
El mensaje OP_DELETE se utiliza para eliminar uno o más documentos de una colección. Su formato es:
struct { MsgHeader header; // standard message header int32 ZERO; // 0 - reserved for future use cstring fullCollectionName; // "dbname.collectionname" int32 flags; // bit vector - see below for details. document selector; // query object. See below for details. }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Valor entero de 0. Reservado para uso futuro. |
| El nombre completo de la colección; es decir, el espacio de nombres. El nombre completo de la colección es la concatenación del nombre de la base de datos con el nombre de la colección, utilizando un |
| Vector de bits para especificar indicadores para la operación. Los valores de los bits corresponden a lo siguiente:
|
| Documento BSON que representa la consulta utilizada para seleccionar los documentos que se eliminarán. El selector contendrá uno o más elementos, todos los cuales deben coincidir para que un documento se elimine de la colección. |
No hay respuesta a un mensaje OP_DELETE.
OP_KILL_CURSORES
Obsoleto en MongoDB 5.0.
El mensaje OP_KILL_CURSORS se utiliza para cerrar un cursor activo en la base de datos. Esto es necesario para garantizar que los recursos de la base de datos se recuperen al final de la consulta. El formato del mensaje OP_KILL_CURSORS es:
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 }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Valor entero de 0. Reservado para uso futuro. |
| La cantidad de identificaciones de cursor que hay en el mensaje. |
| Matriz de IDs de cursor que se cerrarán. Si hay más de uno, se escriben en el socket secuencialmente, uno tras otro. |
Si se lee un cursor hasta agotarlo (se lee hasta que OP_QUERY u OP_GET_MORE devuelve cero para el ID del cursor), no es necesario matar el cursor.
OP_COMPRIMIDO
Cualquier código de operación se puede comprimir y encapsular en un encabezado OP_COMPRESSED. El mensaje OP_COMPRESSED contiene el mensaje de código de operación comprimido original junto con los metadatos necesarios para procesarlo y descomprimirlo.
El formato del mensaje OP_COMPRESSED es:
struct { MsgHeader header; // standard message header int32 originalOpcode; // value of wrapped opcode int32 uncompressedSize; // size of deflated compressedMessage, excluding MsgHeader uint8 compressorId; // ID of compressor that compressed message char *compressedMessage; // opcode itself, excluding MsgHeader }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Contiene el valor del código de operación incluido. |
| El tamaño del |
| El ID del compresor que comprimió el mensaje. A continuación, se proporciona una lista de valores de |
| El propio código de operación, excluido el |
A cada compresor se le asigna un ID de compresor predefinido de la siguiente manera:
compressorId | Valor de protocolo de enlace | Descripción |
|---|---|---|
| noop | El contenido del mensaje no está comprimido. Esto se utiliza para pruebas. |
| rápido | El contenido del mensaje se comprime mediante snappy. |
| zlib | El contenido del mensaje se comprime mediante zlib. |
| zstd | El contenido del mensaje se comprime mediante zstd. |
| reservado | Reservado para uso futuro. |
Mensajes de respuesta de la base de datos
OP_RESPUESTA
Obsoleto en MongoDB 5.0.
La base de datos envía el mensaje en respuesta OP_REPLY a un mensaje OP_QUERY u OP_GET_MORE. El formato de un mensaje OP_REPLY es:
struct { MsgHeader header; // standard message header int32 responseFlags; // bit vector - 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 }
Campo | Descripción |
|---|---|
| Encabezado del mensaje, como se describe en Encabezado del mensaje estándar. |
| Vector de bits para especificar indicadores. Los valores de bits corresponden a lo siguiente:
|
| El |
| Posición inicial en el cursor. |
| Número de documentos en la respuesta. |
| Documentos devueltos. |
Notas al pie
| [2] | (,1 2) 32bits CRC calculado con el polinomio de Castagnoli como se describe en https://tools.ietf.org/html/rfc4960#page-.140 |