Menu Docs
Página inicial do Docs
/
Manual do MongoDB
/

Protocolo de conexão do MongoDB

Nesta página

  • Introdução
  • Soquete TCP/IP
  • Tipos e formatos de mensagens
  • Cabeçalho de Mensagem Padrão
  • Mensagens de solicitação do cliente
  • Mensagens de resposta do banco de dados

Observação

Esta especificação do protocolo de conexão do MongoDB está licenciada nos termos da licença Creative Commons Attribution-NonCommercial-ShareAlike 3.0 dos Estados Unidos. Você não pode usar ou adaptar este material para qualquer finalidade comercial, como criar um banco de dados comercial ou uma oferta de banco de dados como serviço.

O MongoDB Wire Protocol é um protocolo simples de estilo solicitação-resposta baseado em soquete. Os clientes se comunicam com o servidor do banco de dados por meio de um soquete TCP/IP regular.

Os clientes devem se conectar ao banco de dados com um soquete TCP/IP regular.

O número de porta padrão para instâncias mongod e mongos é 27017. O número da porta para mongod e mongos é configurável e pode variar.

Todos os números inteiros no protocolo de conexão do MongoDB usam a ordem de bytes little-endian: ou seja, primeiro o byte menos significativo.

O MongoDB usa o opcode OP_MSG para solicitações de clientes e respostas do banco de dados. Existem vários formatos de mensagem usados em versões mais antigas do MongoDB que foram preteridos em favor de OP_MSG.

Observação

  • Esta página usa um struct tipo C para descrever a estrutura da mensagem.

  • Os tipos utilizados neste documento, como int32 e cstring, são os mesmos definidos na especificação BSON.

  • Para indicar repetição, o documento usa a notação de asterisco da especificação BSON. Por exemplo, int64* indica que um ou mais do tipo especificado podem ser gravados no soquete, um após o outro.

  • O cabeçalho da mensagem padrão é digitado como MsgHeader. As constantes inteiras estão em maiúsculas (por exemplo ZERO para o valor inteiro de 0).

Em geral, cada mensagem consiste em um cabeçalho de mensagem padrão seguido de dados específicos do solicitante. O cabeçalho da mensagem padrão é estruturado da seguinte forma:

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
Descrição
messageLength
O tamanho total da mensagem em bytes. Este total inclui os bytes que contêm o comprimento da mensagem.
requestID
Um identificador gerado pelo cliente ou pelo banco de dados que identifica exclusivamente esta mensagem. Para o caso de mensagens geradas pelo cliente (por exemplo, OP_QUERY e OP_GET_MORE), ele será retornado no campo responseTo da mensagem OP_REPLY . Os clientes podem usar os campos requestID e responseTo para associar respostas de query à query de origem.
responseTo
No caso de uma mensagem do banco de dados, será o requestID retirado das mensagens OP_QUERY ou OP_GET_MORE do cliente. Os clientes podem utilizar os campos requestID e responseTo para associar respostas de consulta com a consulta de origem.
opCode
Tipo de mensagem. Consulte Solicitar códigos de opção para obter detalhes.

Observação

  • A partir do MongoDB 2.6 e maxWireVersion 3, os drivers do MongoDB usam os comandos de banco de dados de dados insert, update e delete em vez de OP_INSERT, OP_UPDATE e OP_DELETE para gravações confirmadas. A maioria dos drivers continua a usar opcodes para escritas não reconhecidas.

  • Na versão 4.2, MongoDB remove o protocolo OP_COMMAND e OP_COMMANDREPLY interno obsoleto.

  • Na versão 5.0, O MongoDB descontinua os seguintes opcodes:

    • OP_REPLY

    • OP_UPDATE

    • OP_INSERT

    • OP_QUERY [1]

    • OP_GET_MORE

    • OP_DELETE

    • OP_KILL_CURSORS

    Em vez desses códigos de operação, use OP_MSG.

    [1] O MongoDB 5.0 descontinua as operações de localização OP_QUERY e os comandos OP_QUERY . Como exceção, o site OP_QUERY ainda é compatível com a execução dos comandos hello e isMaster como parte do handshake da conexão.

O MongoDB aceita estes valores opCode :

Nome do Código de Operação
Valor
Comment
OP_MSG
2013
Envie uma mensagem usando o formato introduzido no MongoDB 3.6.
OP_REPLY
Deprecated in MongoDB 5.0.
1
Responda a uma solicitação do cliente. responseTo está definido.
OP_UPDATE
Deprecated in MongoDB 5.0.
2001
Update document.
OP_INSERT
Deprecated in MongoDB 5.0.
2002
Inserir novo documento.
RESERVED
2003
Anteriormente usado para OP_GET_BY_OID.
OP_QUERY
Deprecated in MongoDB 5.0.
2004
Consultar uma coleção.
OP_GET_MORE
Deprecated in MongoDB 5.0.
2005
Obtenha mais dados de uma consulta. Consulte Cursores.
OP_DELETE
Deprecated in MongoDB 5.0.
2006
Excluir documentos.
OP_KILL_CURSORS
Deprecated in MongoDB 5.0.
2007
Notifique o banco de dados que o cliente terminou com o cursor.
OP_COMPRESSED
2012
Envolve outros códigos de operação usando compressão

OP_MSG é um formato de mensagem extensível projetado para incluir a funcionalidade de outros códigos de operação. Este código de operação tem o seguinte formato:

OP_MSG {
MsgHeader header; // standard message header
uint32 flagBits; // message flags
Sections[] sections; // data sections
optional<uint32> checksum; // optional CRC-32C checksum
}
Campo
Descrição
header
Cabeçalho de mensagem padrão, conforme descrito em Cabeçalho de mensagem padrão.
flagBits
Uma máscara de bits de números inteiros contendo sinalizadores de mensagem, conforme descrito em Flag Bits.
sections
Seções do corpo da mensagem, conforme descrito em Seções.
checksum
Um checksum CRC-32C opcional, conforme descrito em Checksum.

O número inteiro flagBits é um sinalizador de codificação bitmask que modifica o formato e comportamento de OP_MSG.

Os primeiros 16 bits (0-15) são obrigatórios e os analisadores DEVEM apresentar erro se um bit desconhecido for definido.

Os últimos 16 bits (16-31) são opcionais, e os analisadores DEVEM ignorar qualquer conjunto de bits desconhecido. Os proxies e outros encaminhadores de mensagens DEVEM limpar todos os bits opcionais desconhecidos antes de encaminhar as mensagens.

Bit
Nome
Solicitar
Resposta
Descrição
0
checksumPresent

A mensagem termina com 4 bytes contendo uma soma de verificação CRC-32C [2] . Consulte Checksum para obter detalhes.
1
moreToCome

Outra mensagem seguirá esta sem qualquer ação adicional do receptor. O receptor NÃO DEVE enviar outra mensagem até receber uma com moreToCome definido como 0, pois os envios podem bloquear, causando impasse. As solicitações com o conjunto de moreToCome bits não receberão uma resposta. As respostas só terão esta definição em resposta a pedidos com o conjunto de exhaustAllowed bits.
16
exhaustAllowed

O cliente está preparado para múltiplas respostas a esta solicitação usando o bit moreToCome. O servidor nunca produzirá respostas com o bit moreToCome definido, a menos que a solicitação tenha esse bit definido.

Isso garante que várias respostas só sejam enviadas quando a camada de rede do solicitante estiver preparada para eles.

Importante

O MongoDB 3.6 ignora esta sinalização e responderá com uma única mensagem.

Uma mensagem OP_MSG contém uma ou mais seções. Cada seção começa com um byte kind indicando seu tipo. Tudo após o byte de kind constitui a carga útil da seção.

Seguem os tipos de seções disponíveis.

Uma seção do corpo é codificada como um único objeto BSON. O tamanho no objeto BSON também serve como tamanho da seção. Este tipo de seção é a solicitação de comando padrão e o corpo de resposta.

Todos os campos de nível superior DEVEM ter um nome exclusivo.

Tipo
Descrição
int32
Tamanho da seção em bytes.
Cadeia C

Identificador de sequência do documento. Em todos os comandos atuais este campo é o campo (possivelmente aninhado) que ele está substituindo da seção do corpo.

Este campo NÃO PODE existir na seção do corpo.

Zero ou mais objetos BSON
  • Objetos são sequenciados de trás para frente sem separadores.

  • Cada objeto é limitado a maxBSONObjectSize do servidor. A combinação de todos os objetos não está limitada a maxBSONObjSize.

  • A sequência do documento termina assim que bytes size forem consumidos.

  • Os analisadores PODEM optar por mesclar esses objetos no corpo como uma array no caminho especificado pelo identificador de sequência ao converter em objetos de nível de idioma.

Cada mensagem PODE terminar com uma soma de verificação CRC-32C [2] que abrange todos os bytes da mensagem, exceto a própria soma de verificação.

Começando no MongoDB 4.2:

  • As instâncias mongod , mongos e mongo instâncias de shell trocarão mensagens com somas de verificação se não estiverem usando conexão TLS/SSL.

  • As instâncias mongod , mongos e mongo instâncias de shell ignorarão a checksum de verificação se estiverem usando a conexão TLS/SSL.

Drivers e binários mais antigos ignorarão a soma de verificação se houver mensagens com soma de verificação.

A presença de uma checksum é indicada pelo bit de sinalização checksumPresent.

Obsoleto no MongoDB 5.0.

A mensagem OP_UPDATE é usada para atualizar um documento em uma coleção. O formato de uma mensagem OP_UPDATE é o seguinte:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
ZERO
Valor total de 0. Reservado para uso futuro.
fullCollectionName
O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar, o nome completo da coleção é foo.bar.
flags

Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:

  • 0 corresponde ao Upsert. Se definido, o banco de dados inserirá o objeto fornecido na coleção se nenhum documento correspondente for encontrado.

  • 1 corresponde a MultiUpdate.Se configurado, o banco de dados atualizará todos os objetos correspondentes na coleção. Caso contrário, apenas atualiza o primeiro documento correspondente.

  • 2-31 estão reservados. Deve ser 0.

selector
Documento JSON que especifica a query para seleção do documento a ser atualizado.
update
Documento JSON que especifica a atualização a ser executada. Para obter informações sobre como especificar atualizações, consulte a documentação das Operações de Atualização.

Não há resposta a uma mensagem OP_UPDATE.

Obsoleto no MongoDB 5.0.

A mensagem OP_INSERT é usada para inserir um ou mais documentos em uma coleção. O formato da mensagem OP_INSERT é

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
flags

Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:

  • 0 corresponde ao ContinueOnError. Se definido, o banco de dados não interromperá o processamento de uma bulk insert se alguma falhar (por exemplo, devido a IDs duplicados). Isso faz com que a inserção em massa se comporte de forma semelhante a uma série de inserções únicas, exceto lastError será definido se qualquer inserção falhar, não apenas a última. Se ocorrerem vários erros, apenas o mais recente será relatado por getLastError.

  • 1-31 estão reservados. Deve ser 0.

fullCollectionName
O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar, o nome completo da coleção é foo.bar.
documents
Um ou mais documentos para inserir na coleção. Se houver mais de um, eles serão gravados no soquete em sequência, um após o outro.

Não há resposta a uma mensagem OP_INSERT.

Obsoleto no MongoDB 5.0.

A mensagem OP_QUERY é usada para executar query do banco de dados para documentos em uma coleção. O formato da mensagem OP_QUERY é:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
flags

Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:

  • 0 está reservado. Deve ser 0.

  • 1 corresponde ao TailableCursor. Tailable significa que o cursor não está fechado quando os últimos dados são recuperados. Em vez disso, o cursor marca a posição do objeto final. Você pode continuar usando o cursor mais tarde, de onde ele estava localizado, se mais dados foram recebidos. Como qualquer "cursor latente", o cursor pode se tornar inválido em algum momento (CursorNotFound) – por exemplo, se o objeto final ao qual ele faz referência foi excluído.

  • 2 corresponde ao SlaveOk. Permitir query de réplica escrava. Normalmente estes retornam um erro, exceto para o namespace "local".

  • 3 corresponde à OplogReplay. A partir do MongoDB 4.4, você não precisa especificar esse sinalizador porque a otimização acontece automaticamente para queries qualificadas no oplog. Consulte oplogReplay para mais informações.

  • 4 corresponde ao NoCursorTimeout. O servidor normalmente atinge o tempo limite dos cursores ociosos após um período de inatividade (10 minutos) para evitar o uso excessivo de memória. Defina esta opção para evitar isso.

  • 5 corresponde a AwaitData. Use com TailableCursor. Se estivermos no final dos dados, bloqueie por um tempo em vez de não retornar nenhum dado. Após um período de tempo limite, retornamos ao normal.

  • 6 corresponde à escape. Transmitir os dados de forma intensa em vários pacotes "mais", partindo do pressuposto de que o cliente lerá integralmente todos os dados consultados. Mais rápido quando você está extraindo muitos dados e sabe que deseja extrair tudo. Observação: o cliente não tem permissão para não ler todos os dados, a menos que feche a conexão.

  • 7 corresponde a Parcial. Obtenha resultados parciais de um mongo se alguns shards estiverem inativos (em vez de gerar um erro)

  • 8-31 estão reservados. Deve ser 0.

fullCollectionName
O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar, o nome completo da coleção é foo.bar.
numberToSkip
Define o número de documentos a serem omitidos, começando pelo primeiro documento no conjunto de dados resultante, ao retornar o resultado da query.
numberToReturn
Limita o número de documentos na primeira mensagem OP_REPLY à query. No entanto, o banco de dados de dados ainda estabelecerá um cursor e retornará o cursorID ao cliente se houver mais resultados do que numberToReturn. Se o driver cliente oferecer funcionalidade 'limit' (como a palavra-chave SQL LIMIT), caberá ao driver cliente garantir que não mais do que o número especificado de documento seja retornado ao aplicação de chamada. Se numberToReturn for 0, o banco de dados usará o tamanho de retorno padrão. Se o número for negativo, o banco de dados de dados retornará esse número e fechará o cursor. Nenhum resultado adicional para essa query pode ser obtido. Se numberToReturn for 1 o servidor tratará como -1 (fechando o cursor automaticamente).
query
Documento BSON que representa a query. A query conterá um ou mais elementos, todos os quais devem corresponder para que um documento seja incluído no conjunto de resultados. Os possíveis elementos incluem $query, $orderby, $hint e $explain.
returnFieldsSelector

Opcional. Documento JSON que limita os campos nos documentos devolvidos. O returnFieldsSelector contém um ou mais elementos, cada um dos quais é o nome de um campo que deve ser retornado e o valor inteiro 1. Na notação JSON, um returnFieldsSelector para limitar aos campos a, b e c seria:

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

O banco de dados responderá a uma mensagem OP_QUERY com uma mensagem OP_REPLY.

Obsoleto no MongoDB 5.0.

A mensagem OP_GET_MORE é usada para executar query no banco de dados para documentos em uma coleção. O formato da mensagem OP_GET_MORE é:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
ZERO
Valor total de 0. Reservado para uso futuro.
fullCollectionName
O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar, o nome completo da coleção é foo.bar.
numberToReturn
Limita o número de documentos na primeira mensagem OP_REPLY à query. No entanto, o banco de dados ainda estabelecerá um cursor e retornará o cursorID ao cliente se houver mais resultados do que numberToReturn. Se o driver cliente oferecer funcionalidade 'limit' (como a palavra-chave SQL LIMIT), caberá ao driver cliente garantir que não mais do que o número especificado de documento seja retornado ao aplicativo de chamada. Se numberToReturn for 0, o db usará o tamanho de retorno padrão.
cursorID
Identificador do cursor que veio em OP_REPLY. Este deve ser o valor que veio do banco de dados.

O banco de dados responderá a uma mensagem OP_GET_MORE com uma mensagem OP_REPLY.

Obsoleto no MongoDB 5.0.

A mensagem OP_DELETE é usada para remover um ou mais documentos de uma coleção. O formato da mensagem OP_DELETE é:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
ZERO
Valor total de 0. Reservado para uso futuro.
fullCollectionName
O nome completo da collection; ou seja, namespace. O nome completo da coleção é a concatenação do nome do banco de dados com o nome da coleção, utilizando um . para a concatenação. Por exemplo, para o banco de dados foo e a coleção bar, o nome completo da coleção é foo.bar.
flags

Vetor de bits para especificar sinalizadores para a operação. Os valores de bits correspondem ao seguinte:

  • 0 corresponde a SingleRemove. Se definido, o banco de dados removerá apenas o primeiro documento correspondente na coleção. Caso contrário, todos os documentos correspondentes serão removidos.

  • 1-31 estão reservados. Deve ser 0.

selector
documento BSON que representa a query usada para selecionar os documentos a serem removidos. O seletor conterá um ou mais elementos, todos os quais devem corresponder para que um documento seja removido da coleção.

Não há resposta a uma mensagem OP_DELETE.

Obsoleto no MongoDB 5.0.

A mensagem OP_KILL_CURSORS é usada para fechar um cursor ativo no banco de dados. Isso é necessário para garantir que os recursos do banco de dados sejam recuperados no final da query. O formato da mensagem OP_KILL_CURSORS é:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
ZERO
Valor total de 0. Reservado para uso futuro.
numberOfCursorIDs
O número de ID de cursor que estão na mensagem.
cursorIDs
"Array" de IDs de cursor a serem fechadas. Se houver mais de um, eles serão gravados no soquete em sequência, um após o outro.

Se um cursor for lido até esgotar (leia até OP_QUERY ou OP_GET_MORE retornar zero para o ID do cursor), não será necessário matar o cursor.

Qualquer opcode pode ser comprimido e encapsulado em um cabeçalho OP_COMPRESSED. A mensagem OP_COMPRESSED contém a mensagem de opcode comprimida original juntamente com os metadados necessários para processá-la e descompactá-la.

O formato da mensagem OP_COMPRESSED é:

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
Descrição
MsgHeader
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
originalOpcode
Contém o valor do código de operação envolto.
uncompressedSize
O tamanho do compressedMessage deflacionado, que exclui o MsgHeader.
compressorId
O ID do compressor que comprimiu a mensagem. Uma lista de compressorId valores é fornecida abaixo.
compressedMessage
O código de operação em si, excluindo o MsgHeader.

Cada compressor recebe um ID de compressor pré-definido da seguinte forma:

compressorId
Valor do Handshake
Descrição
0
noop
O conteúdo da mensagem é descompactado. Isso é usado para testar.
1
snappy
O conteúdo da mensagem é comprimido usando snappy.
2
zlib
O conteúdo da mensagem é comprimido usando zlib.
3
zstd
O conteúdo da mensagem é comprimido usando zstd.
4-255
reservado
Reservado para uso futuro.

Obsoleto no MongoDB 5.0.

A mensagem OP_REPLY é enviada pelo banco de dados em resposta a uma mensagem OP_QUERY ou OP_GET_MORE. O formato de uma mensagem OP_REPLY é:

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
Descrição
header
Cabeçalho da mensagem, conforme descrito em Cabeçalho de mensagem padrão.
responseFlags

Vetor de bits para especificar sinalizadores. Os valores de bits correspondem ao seguinte:

  • 0 corresponde ao CursorNotFound. É definido quando getMore é chamado, mas o ID do cursor não é válido no servidor. Retornado com zero resultados.

  • 1 corresponde a QueryFailure. É definido quando a query falha. Os resultados consistem em um documento contendo um campo "$err" descrevendo a falha.

  • 2 corresponde ao ShardConfigStale. Os drivers devem ignorar isso. Somente mongos verá esse conjunto; nesse caso, ele precisará atualizar a configuração do servidor.

  • 3 corresponde ao AwaitCapable. É definido quando o servidor suporta a opção AwaitData Query. Caso contrário, o cliente deve sono um pouco entre os getMore de um cursor Tailable. mongod versão 1.6 suporta AwaitData e, portanto, sempre define AwaitCapable.

  • 4-31 estão reservados. Ignorar.

cursorID
O cursorID do qual este OP_REPLY faz parte. Caso o conjunto de resultados da query se encaixe em uma mensagem OP_REPLY, cursorID será 0. Este cursorID deve ser usado em qualquer mensagem OP_GET_MORE usada para obter mais dados e também deve ser fechado pelo cliente quando não for mais necessário por meio de uma mensagem OP_KILL_CURSORS .
startingFrom
Posição inicial no cursor.
numberReturned
Número de documentos na resposta.
documents
Documentos devolvidos.

Notas de rodapé

[2](1, 2) 32-bit CRC calculado com o polinômio Castagnoli conforme descrito por https://tools.ietf.org/html/rfc4960#page-140.

Voltar

Limites e limites