Um cursor é um ponteiro para os resultados de uma consulta. Os cursores permitem iterar sobre os resultados do banco de dados um lote de cada vez.
Casos de uso
Quando você executa os métodos find() aggregate() e usando mongosh ou um driver, eles retornam um cursor contendo um lote de resultados. Você pode acessar os documentos resultantes iterando manualmente o cursor ou usando o método. Para mais informações,toArray() consulte Iterar um cursor mongosh no.
Se você estiver acessando uma collection limitada, poderá usar um cursor persistente que recupera novos documentos à medida que eles são inseridos na collection. Para obter mais informações, consulte Cursores tailable.
Comportamento
Os cursores criados dentro de uma sessão do cliente são fechados nos seguintes cenários:
O cliente esgota o cursor.
Um usuário fecha manualmente o cursor.
Um usuário encerra manualmente a sessão.
A sessão expira.
O parâmetro cursorTimeoutMillis especifica o tempo limite para cursores ociosos e tem um valor padrão de 10 minutos. O MongoDB atinge o tempo limite dos cursores ociosos criados fora das sessões após esse limite. O MongoDB estende o tempo limite do cursor toda vez que o cursor retorna um novo lote. Para fechar manualmente um cursor, utilize killCursors.
O tempo limite da sessão do servidor é especificado pelo parâmetro localLogicalSessionTimeoutMinutes e tem um valor padrão de 30 minutos. Para estender uma sessão além de 30 minutos, use refreshSessions. Para encerrar manualmente uma sessão, utilize killSessions.
Se um cursor for aberto fora de uma sessão, os drivers do MongoDB e mongosh criarão uma sessão implícita e a associarão à operação.
Atualizações simultâneas ao usar um cursor
Enquanto um cursor retorna documentos, outras operações podem ser executadas em segundo plano e afetar os resultados, dependendo do nível da preocupação de leitura . Para obter detalhes, consulte Isolamento de leitura, consistência e recência.
Começar
Detalhes
Quando você executa uma operação find ou aggregate, o banco de dados executa uma query até encontrar documentos suficientes para preencher um lote. Quando um lote é preenchido, a query é pausada. A query pausada no servidor é chamada de cursor, e o ID associado à query pausada é um ID de cursor.
O banco de dados retorna o lote resultante e a ID do cursor para o cliente. Os drivers e o mongosh do MongoDB armazenam esses dados em uma instância do cursor no lado do cliente . Se houver mais documentos correspondentes quando você chegar ao final de um lote, o cursor do lado do cliente recuperará automaticamente o próximo lote do servidor usando getMore. Para ver quantos resultados permanecem no lote atual, use cursor.objsLeftInBatch(). Para verificar se há algum resultado restante no lote atual ou no servidor, use cursor.hasNext().
Lotes de cursores
Os cursores retornam resultados em lotes. A quantidade de dados em um lote deve ser menor que o tamanho máximo do documento BSON (16 MiB). Para especificar o número máximo de documentos permitidos em um lote, consulte cursor.batchSize(). Por padrão, o tamanho do lote para operações find() e aggregate() é 101. As operações getMore emitidas contra o cursor resultante não têm tamanho de lote padrão, portanto, são limitadas apenas pelo tamanho da mensagem de mebibyte 16.
Classificação
Para consultas que incluem uma operação de classificação sem índice, o servidor deve carregar todos os documentos na memória para executar a classificação antes de retornar quaisquer resultados.
Informações do cursor
O método db.serverStatus() retorna um documento que inclui um campo metrics. O campo metrics contém um campo metrics.cursor com informações detalhadas do cursor. Para saber mais, consulte metrics.cursor.