Join us at MongoDB.local London on 7 May to unlock new possibilities for your data. Use WEB50 to save 50%.
Register now >
Docs Menu
Docs Home
/
Manual de MongoDB
/

Protocolo de conexión de MongoDB

Nota

Esta especificación del protocolo de conexión de MongoDB está licenciada bajo una Licencia Creative Commons Attribution-NonCommercial-ShareAlike 3.0 de Estados UnidosNo 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.

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.

Los clientes deben conectarse a la base de datos con un socket TCP/IP normal.

El número de puerto predeterminado para mongod e mongos instancias es 27017. El número de puerto para mongod y mongos es configurable y puede variar.

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.

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 struct tipo C para describir la estructura del mensaje.

  • Los tipos utilizados en este documento, como int32 y cstring, son los mismos que los definidos en la especificación BSON.

  • Para denotar la repetición, el documento utiliza la notación del asterisco de la Especificación BSON. Por ejemplo, int64* indica que se puede escribir uno o más del tipo especificado en el socket, uno tras otro.

  • El encabezado de mensaje estándar está tipificado como MsgHeader. Las constantes enteras se escriben en mayúsculas (por ejemplo, ZERO para el valor entero de 0) .

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

messageLength

El tamaño total del mensaje en bytes. Este total incluye los 4 bytes que contienen la longitud del mensaje.

requestID

Un identificador generado por el cliente o la base de datos que identifica de manera única este mensaje. En el caso de los mensajes generados por el cliente (por ejemplo, OP_QUERY y OP_GET_MORE), será devuelto en el campo responseTo del mensaje OP_REPLY. Los clientes pueden utilizar los campos requestID y responseTo para asociar las respuestas de las queries con la query de origen.

responseTo

En el caso de un mensaje de la base de datos, este será el requestID tomado de los mensajes OP_QUERY o OP_GET_MORE del cliente. Los clientes pueden utilizar los campos requestID y responseTo para asociar las respuestas de queries con la query original.

opCode

Tipo de mensaje. Consulte Solicitud Opcodes para obtener más detalles.

Nota

  • A partir de MongoDB 2.6 y maxWireVersion 3, los drivers de MongoDB utilizan los comandos de base de datos insert, update y delete en lugar de OP_INSERT, OP_UPDATE y OP_DELETE para guardados reconocidos. La mayoría de los controladores siguen utilizando códigos de operación para escrituras no reconocidas.

  • En la versión 4.2, MongoDB remueve los protocolos internos obsoletos OP_COMMAND y OP_COMMANDREPLY.

  • En la versión 5.0, MongoDB descontinúa los siguientes códigos de operación:

    • OP_REPLY

    • OP_UPDATE

    • OP_INSERT

    • OP_QUERY [1]

    • OP_GET_MORE

    • OP_DELETE

    • OP_KILL_CURSORS

    En lugar de estos códigos de operación, utiliza OP_MSG.

    [1] MongoDB 5.0 desaprueba tanto las OP_QUERY operaciones de búsqueda como los OP_QUERY comandos. Como excepción, OP_QUERY sigue siendo admitido para ejecutar los comandos hello y isMaster como parte del apretón de manos de conexión.

MongoDB admite estos valores opCode:

Nombre del opcode
Valor
Comment

OP_MSG

2013

Envía un mensaje utilizando el formato introducido en MongoDB 3.6.

OP_REPLY
Deprecated in MongoDB 5.0.

1

Responder a una solicitud de un cliente. responseTo está configurado.

OP_UPDATE
Deprecated in MongoDB 5.0.

2001

Update document.

OP_INSERT
Deprecated in MongoDB 5.0.

2002

Inserta un nuevo documento.

RESERVED

2003

Anteriormente utilizado para OP_GET_BY_OID.

OP_QUERY
Deprecated in MongoDB 5.0.

2004

Realiza un query a una colección.

OP_GET_MORE
Deprecated in MongoDB 5.0.

2005

Obtén más datos de un query. Consulta Cursores.

OP_DELETE
Deprecated in MongoDB 5.0.

2006

Borra documentos.

OP_KILL_CURSORS
Deprecated in MongoDB 5.0.

2007

Notifica a la base de datos que el cliente ha terminado con el cursor.

OP_COMPRESSED

2012

Abarca otros códigos de operación mediante compresión

OP_MSG es un formato de mensaje extensible diseñado para absorber la funcionalidad de otros códigos operacionales. Este opcode 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

header

Encabezado de mensaje estándar, como se describe en Encabezado de mensaje estándar.

flagBits

Una máscara de bits enteros que contiene marcas de mensajes, como se describe en Bits de marca.

sections

Secciones del cuerpo del mensaje, como se describen en Secciones.

checksum

Una suma de verificación CRC-32C opcional, como se describe en Suma de verificación.

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

checksumPresent

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

moreToCome

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 moreToCome establecido en 0, ya que los envíos pueden bloquearse y generar un bloqueo. Las solicitudes con el bit de moreToCome activado no recibirán respuesta. Las respuestas solo tendrán esta configuración ante las solicitudes con el conjunto de bits exhaustAllowed.

16

exhaustAllowed

El cliente está preparado para varias respuestas a esta solicitud con el bit moreToCome. El servidor nunca producirá respuestas con el bit de moreToCome activado a menos que la solicitud tenga ese bit activado.

Esto garantiza que se envíen varias respuestas solo cuando la capa de red del solicitante esté preparada para recibirlas.

Importante

MongoDB 3.6 ignora este indicador y responderá con un único mensaje.

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.

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
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

  • Los objetos se secuencian de forma consecutiva sin separadores.

  • Cada objeto está limitado a los maxBSONObjectSize del servidor. La combinación de todos los objetos no se limita a maxBSONObjSize.

  • La secuencia del documento finaliza una vez que se consumen size bytes.

  • Los analizadores PUEDEN optar por fusionar estos objetos en el cuerpo como un arreglo en la ruta especificada por el identificador de secuencia al convertirlos en objetos de nivel de lenguaje.

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.

A partir de MongoDB 4.2:

  • Las instancias mongod, mongos y las instancias shell mongo intercambiarán mensajes con sumas de verificación si no utilizan conexión TLS/SSL.

  • mongod instancias, mongos instancias y mongo shell instancias saltarán la suma de verificación si utilizan 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.

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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

ZERO

Valor entero de 0. Reservado para uso futuro.

fullCollectionName

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 . para la concatenación. Por ejemplo, para la base de datos foo y la colección bar, el nombre completo de la colección es foo.bar.

flags

Vector de bits para especificar flags para la operación. Los valores de bits corresponden a lo siguiente:

  • 0 corresponde a inserción. Si se configura, la base de datos insertará el objeto proporcionado en la colección si no se encuentra ningún documento coincidente.

  • 1 corresponde a MultiUpdate. Si se establece, la base de datos actualizará todos los objetos que coincidan en la colección. De lo contrario, solo actualiza el primer documento coincidente.

  • 2-31 están reservados. Debe establecerse en 0.

selector

Documento BSON que especifica la query para la selección del documento que se va a actualizar.

update

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.

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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

flags

Vector de bits para especificar flags para la operación. Los valores de bits corresponden a lo siguiente:

  • 0 corresponde a ContinueOnError. Si se establece, la base de datos no detendrá el procesamiento de una inserción masiva si una falla (por ejemplo, debido a ID duplicados). Esto hace que la inserción masiva se comporte de manera similar a una serie de inserciones individuales, excepto que se establecerá lastError si alguna inserción falla, no solo la última. Si se producen varios errores, getLastError solo informará el más reciente.

  • 1-31 están reservados. Debe establecerse en 0.

fullCollectionName

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 . para la concatenación. Por ejemplo, para la base de datos foo y la colección bar, el nombre completo de la colección es foo.bar.

documents

Uno o más documentos para insertar en la colección. Si hay más de uno, se escriben en el socket en secuencia, uno tras otro.

No hay respuesta a un mensaje OP_INSERT.

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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

flags

Vector de bits para especificar flags para la operación. Los valores de bits corresponden a lo siguiente:

  • 0 está reservada. Debe establecerse en 0.

  • 1 Corresponde a TailableCursor. Tailable significa que el cursor no se cierra al recuperar los últimos datos. En su lugar, el cursor marca la posición del objeto final. Puede reanudar su uso más tarde, desde donde se encontraba, si se recibieron más datos. Como cualquier cursor latente, el cursor puede volverse inválido en algún momento (CursorNotFound), por ejemplo, si se eliminó el objeto final al que hace referencia.

  • 2 corresponde a SlaveOk. Permitir query al esclavo de réplica. Normalmente, estos devuelven un error, excepto para el espacio de nombres "local".

  • 3 corresponde a OplogReplay. A partir de MongoDB 4.4, no es necesario especificar este flag porque la optimización se realiza automáticamente para las queries elegibles en el oplog. Consulte oplogReplay para obtener más información.

  • 4 corresponde a NoCursorTimeout. El servidor normalmente agota el tiempo de espera de los cursores inactivos después de un período de inactividad (10 minutos) para evitar el uso excesivo de memoria. Establece esta opción para evitarlo.

  • 5 Corresponde a AwaitData. Se usa con TailableCursor. Si se llega al final de los datos, se bloquea por un tiempo en lugar de no devolver ningún dato. Tras un tiempo de espera, se retorna normalmente.

  • 6 corresponde a Exhaust. Transmita los datos a máxima velocidad en múltiples paquetes "más", asumiendo que el cliente leerá completamente todos los datos consultados. Más rápido cuando estás extrayendo muchos datos y sabes que quieres bajarlos todos. Nota: no se permite que el cliente no lea todos los datos a menos que cierre la conexión.

  • 7 corresponde a Parcial. Obtén resultados parciales de un mongos si algunas particiones están caídas (en lugar de arrojar un error)

  • 8-31 están reservados. Debe establecerse en 0.

fullCollectionName

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 . para la concatenación. Por ejemplo, para la base de datos foo y la colección bar, el nombre completo de la colección es foo.bar.

numberToSkip

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.

numberToReturn

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 cursorID al cliente si hay más resultados que numberToReturn. Si el controlador del cliente ofrece funcionalidad de 'límite' (como la palabra clave LIMIT de SQL), entonces depende del controlador del cliente garantizar que no se devuelva más que el número especificado de documentos a la aplicación que realiza la llamada. Si numberToReturn es 0, la base de datos usará el tamaño de retorno por defecto. Si el número es negativo, la base de datos devolverá ese número y cerrará el cursor. No se pueden obtener más resultados para esa query. Si numberToReturn es 1, el servidor lo tratará como -1 (cerrando el cursor automáticamente).

query

Documento BSON que representa la query. La query contendrá uno o más elementos, todos los cuales deben coincidir para que un documento se incluya en el conjunto de resultados. Posibles elementos incluyen $query, $orderby, $hint y $explain.

returnFieldsSelector

opcional. Documento BSON que limita los campos en los documentos devueltos. El returnFieldsSelector contiene uno o más elementos, cada uno de los cuales es el nombre del campo que se debe devolver y el valor entero 1. En notación JSON, un returnFieldsSelector para limitar los campos a, b y c sería:

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

La base de datos responderá a un mensaje OP_QUERY con un mensaje OP_REPLY.

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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

ZERO

Valor entero de 0. Reservado para uso futuro.

fullCollectionName

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 . para la concatenación. Por ejemplo, para la base de datos foo y la colección bar, el nombre completo de la colección es foo.bar.

numberToReturn

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 cursorID al cliente si hay más resultados que numberToReturn. Si el controlador de cliente ofrece funcionalidad de 'limit' (como la palabra clave LIMIT en SQL), entonces depende del controlador de cliente asegurar que no se devuelvan más documentos que el número especificado a la aplicación llamante. Si numberToReturn es 0, la base de datos usará el tamaño de retorno por defecto.

cursorID

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.

Obsoleto en MongoDB 5.0.

El mensaje OP_DELETE se utiliza para remover uno o más documentos de una colección. El formato del mensaje OP_DELETE 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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

ZERO

Valor entero de 0. Reservado para uso futuro.

fullCollectionName

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 . para la concatenación. Por ejemplo, para la base de datos foo y la colección bar, el nombre completo de la colección es foo.bar.

flags

Vector de bits para especificar flags para la operación. Los valores de bits corresponden a lo siguiente:

  • 0 Corresponde a SingleRemove. Si se configura, la base de datos eliminará solo el primer documento coincidente de la colección. De lo contrario, se eliminarán todos los documentos coincidentes.

  • 1-31 están reservados. Debe establecerse en 0.

selector

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.

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 finalizar la query. 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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

ZERO

Valor entero de 0. Reservado para uso futuro.

numberOfCursorIDs

El número de IDs de cursor que están en el mensaje.

cursorIDs

"arreglo" de ID de cursor que se cerrarán. Si hay más de uno, se escriben en el socket en secuencia, uno tras otro.

Si se lee un cursor hasta agotarlo (leer hasta que OP_QUERY o OP_GET_MORE devuelve cero para el id del cursor), no es necesario matar el cursor.

Cualquier opcode puede comprimirse y enviarse con un encabezado OP_COMPRESSED. El mensaje OP_COMPRESSED contiene el mensaje original comprimido del código de operación 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

MsgHeader

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

originalOpcode

Contiene el valor del código de operación incluido.

uncompressedSize

El tamaño del compressedMessage desinflado, que excluye el MsgHeader.

compressorId

El ID del compresor que comprimió el mensaje. A continuación, se proporciona una lista de valores de compressorId.

compressedMessage

El propio código de operación, excluido el MsgHeader.

A cada compresor se le asigna un ID de compresor predefinido de la siguiente manera:

compressorId
Valor de protocolo de enlace
Descripción

0

noop

El contenido del mensaje no está comprimido. Esto se utiliza para pruebas.

1

rápido

El contenido del mensaje se comprime mediante snappy.

2

zlib

El contenido del mensaje se comprime mediante zlib.

3

zstd

El contenido del mensaje se comprime mediante zstd.

4-255

reservado

Reservado para uso futuro.

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

header

Encabezado del mensaje, como se describe en Encabezado del mensaje estándar.

responseFlags

Vector de bits para especificar indicadores. Los valores de bits corresponden a lo siguiente:

  • 0 corresponde a CursorNotFound. Se establece cuando se llama a getMore, pero el id del cursor no es válido en el servidor. Devuelto con cero resultados.

  • 1 Corresponde a QueryFailure. Se activa cuando la consulta falla. Los resultados consisten en un documento que contiene un campo "$err" que describe el fallo.

  • 2 对应于 ShardConfigStale。 Los controladores deben ignorar esto. 仅 mongos 会看到此设置,这种情况下,它需要从 el servidor actualizar configuración。

  • 3 corresponde a AwaitCapable. Se establece cuando el servidor admite la opción de query AwaitData. Si no lo hace, el cliente debe esperar un poco entre los getMore de un cursor con seguimiento. La versión Mongod 1.6 admite AwaitData y, por lo tanto, siempre establece AwaitCapable.

  • 4-31 están reservados. Ignorar.

cursorID

El cursorID del que forma parte este OP_REPLY. En el evento de que el conjunto de resultados de la query quepa en un mensaje OP_REPLY, cursorID será 0. Este cursorID debe ser utilizado en todos los mensajes de OP_GET_MORE para obtener más datos, y además debe ser cerrado por el cliente cuando ya no se necesite a través de un mensaje OP_KILL_CURSORS.

startingFrom

Posición inicial en el cursor.

numberReturned

Número de documentos en la respuesta.

documents

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.

Volver

Límites y umbrales

En esta página