# Poco::MongoDB

# class OpMsgCursor

Library: MongoDB
Package: MongoDB
Header: Poco/MongoDB/OpMsgCursor.h

## Description

OpMsgCursor is a helper class for querying multiple documents using OpMsgMessage. Once all of the data is read with the cursor (see isActive()) it can't be reused.

USAGE: Supports both Connection and ReplicaSetConnection. When using ReplicaSetConnection, cursor operations benefit from automatic retry and failover on retriable errors.

RESOURCE MANAGEMENT: When a cursor is no longer needed, you should call kill() to release server-side resources. If kill() is not called explicitly, the server will keep the cursor open until it times out.

THREAD SAFETY: This class is NOT thread-safe. A cursor must not be used concurrently from multiple threads. Each thread should have its own cursor instances. The next() method modifies internal state and is not safe for concurrent access.

## Inheritance

Direct Base Classes: Document

All Base Classes: Document

## Member Summary

Member Functions: batchSize, cursorID, emptyFirstBatch, isActive, kill, next, query, setBatchSize, setEmptyFirstBatch

Inherited Functions: add, addElement, addNewArray, addNewDocument, clear, elementNames, elements, empty, exists, get, getInteger, isType, read, remove, reserve, size, toString, write

## Constructors

### OpMsgCursor

OpMsgCursor(
const std::string & dbname,
const std::string & collectionName
);

Creates a OpMsgCursor for the given database and collection.

## Destructor

### ~OpMsgCursor

virtual ~OpMsgCursor();

Destroys the OpMsgCursor.

## Member Functions

### batchSize

[[nodiscard]]
Int32 batchSize() const noexcept;

Current batch size (zero or negative number indicates default batch size)

### cursorID

[[nodiscard]]
Int64 cursorID() const noexcept;

### emptyFirstBatch

[[nodiscard]]
bool emptyFirstBatch() const noexcept;

### isActive

[[nodiscard]]
bool isActive() const noexcept;

Is there more data to acquire with this cursor?

### kill

void kill(
Connection & connection
);

Kills the cursor and resets its internal state. Call this method when you don't need all documents to release server resources.

### kill

void kill(
ReplicaSetConnection & connection
);

Kills the cursor and resets its internal state. Call this method when you don't need all documents to release server resources.

This overload provides automatic retry and failover for replica set deployments.

### next

OpMsgMessage & next(
Connection & connection
);

Tries to get the next documents. As long as response message has a cursor ID next can be called to retrieve the next bunch of documents.

The cursor must be killed (see kill()) when not all documents are needed.

### next

OpMsgMessage & next(
ReplicaSetConnection & connection
);

Tries to get the next documents. As long as response message has a cursor ID next can be called to retrieve the next bunch of documents.

The cursor must be killed (see kill()) when not all documents are needed.

This overload provides automatic retry and failover for replica set deployments.

### query

OpMsgMessage & query();

Returns the associated query.

### setBatchSize

void setBatchSize(
Int32 batchSize
) noexcept;

Set non-default batch size

### setEmptyFirstBatch

void setEmptyFirstBatch(
bool empty
) noexcept;

Empty first batch is used to get error response faster with little server processing