asyncio GridFS Classes

Store blobs of data in GridFS.

class motor.motor_asyncio.AsyncIOMotorGridFSBucket

Create a new instance of AsyncIOMotorGridFSBucket.

Raises TypeError if database is not an instance of AsyncIOMotorDatabase.

Raises ConfigurationError if write_concern is not acknowledged.

Parameters:
  • database: database to use.
  • bucket_name (optional): The name of the bucket. Defaults to ‘fs’.
  • chunk_size_bytes (optional): The chunk size in bytes. Defaults to 255KB.
  • write_concern (optional): The WriteConcern to use. If None (the default) db.write_concern is used.
  • read_preference (optional): The read preference to use. If None (the default) db.read_preference is used.

See general MongoDB documentation

gridfs

coroutine delete(self, file_id)

Delete a file’s metadata and data chunks from a GridFS bucket:

async def delete():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # Get _id of file to delete
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    await fs.delete(file_id)

Raises NoFile if no file with file_id exists.

Parameters:
  • file_id: The _id of the file to be deleted.
coroutine download_to_stream(self, file_id, destination)

Downloads the contents of the stored file specified by file_id and writes the contents to destination:

async def download():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # Get _id of file to read
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    # Get file to write to
    file = open('myfile','wb+')
    await fs.download_to_stream(file_id, file)
    file.seek(0)
    contents = file.read()

Raises NoFile if no file with file_id exists.

Parameters:
  • file_id: The _id of the file to be downloaded.
  • destination: a file-like object implementing write().
coroutine download_to_stream_by_name(self, filename, destination, revision=-1)

Write the contents of filename (with optional revision) to destination.

For example:

async def download_by_name():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # Get file to write to
    file = open('myfile','wb')
    await fs.download_to_stream_by_name("test_file", file)

Raises NoFile if no such version of that file exists.

Raises ValueError if filename is not a string.

Parameters:
  • filename: The name of the file to read from.
  • destination: A file-like object that implements write().
  • revision (optional): Which revision (documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (the most recent revision).
Note:

Revision numbers are defined as follows:

  • 0 = the original stored file
  • 1 = the first revision
  • 2 = the second revision
  • etc...
  • -2 = the second most recent revision
  • -1 = the most recent revision
find(self, *args, **kwargs)

Find and return the files collection documents that match filter.

Returns a cursor that iterates across files matching arbitrary queries on the files collection. Can be combined with other modifiers for additional control.

For example:

async def find():
    cursor = fs.find({"filename": "lisa.txt"},
                     no_cursor_timeout=True)

    async for grid_data in cursor:
        data = grid_data.read()

iterates through all versions of “lisa.txt” stored in GridFS. Setting no_cursor_timeout may be important to prevent the cursor from timing out during long multi-file processing work.

As another example, the call:

most_recent_three = fs.find().sort("uploadDate", -1).limit(3)

returns a cursor to the three most recently uploaded files in GridFS.

Follows a similar interface to find() in AsyncIOMotorCollection.

Parameters:
  • filter: Search query.
  • batch_size (optional): The number of documents to return per batch.
  • limit (optional): The maximum number of documents to return.
  • no_cursor_timeout (optional): The server normally times out idle cursors after an inactivity period (10 minutes) to prevent excess memory use. Set this option to True prevent that.
  • skip (optional): The number of documents to skip before returning.
  • sort (optional): The order by which to sort results. Defaults to None.
coroutine open_download_stream(self, file_id)

Opens a stream to read the contents of the stored file specified by file_id:

async def download_stream():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    grid_out = await fs.open_download_stream(file_id)
    contents = await grid_out.read()

Raises NoFile if no file with file_id exists.

Parameters:
  • file_id: The _id of the file to be downloaded.

Returns a AsyncIOMotorGridOut.

coroutine open_download_stream_by_name(self, filename, revision=-1)

Opens a stream to read the contents of filename and optional revision:

async def download_by_name():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")
    grid_out = await fs.open_download_stream_by_name(file_id)
    contents = await grid_out.read()

Raises NoFile if no such version of that file exists.

Raises ValueError filename is not a string.

Parameters:
  • filename: The name of the file to read from.
  • revision (optional): Which revision (documents with the same filename and different uploadDate) of the file to retrieve. Defaults to -1 (the most recent revision).

Returns a AsyncIOMotorGridOut.

Note:

Revision numbers are defined as follows:

  • 0 = the original stored file
  • 1 = the first revision
  • 2 = the second revision
  • etc...
  • -2 = the second most recent revision
  • -1 = the most recent revision
open_upload_stream(self, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filename, and add any additional information in the metadata field of the file document or modify the chunk size:

async def upload():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    grid_in, file_id = fs.open_upload_stream(
        "test_file", chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

    await grid_in.write(b"data I want to store!")
    await grid_in.close()  # uploaded on close

Returns an instance of AsyncIOMotorGridIn.

Raises NoFile if no such version of that file exists. Raises ValueError if filename is not a string.

In a Python 3.5 native coroutine, the “async with” statement calls close() automatically:

async def upload():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    async with await fs.new_file() as gridin:
        await gridin.write(b'First part\n')
        await gridin.write(b'Second part')

    # gridin is now closed automatically.
Parameters:
  • filename: The name of the file to upload.
  • chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes in AsyncIOMotorGridFSBucket.
  • metadata (optional): User data for the ‘metadata’ field of the files collection document. If not provided the metadata field will be omitted from the files collection document.
open_upload_stream_with_id(self, file_id, filename, chunk_size_bytes=None, metadata=None)

Opens a stream for writing.

Specify the filed_id and filename, and add any additional information in the metadata field of the file document, or modify the chunk size:

async def upload():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    grid_in, file_id = fs.open_upload_stream_with_id(
        ObjectId(),
        "test_file",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

    await grid_in.write(b"data I want to store!")
    await grid_in.close()  # uploaded on close

Returns an instance of AsyncIOMotorGridIn.

Raises NoFile if no such version of that file exists. Raises ValueError if filename is not a string.

Parameters:
  • file_id: The id to use for this file. The id must not have already been used for another file.
  • filename: The name of the file to upload.
  • chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes in AsyncIOMotorGridFSBucket.
  • metadata (optional): User data for the ‘metadata’ field of the files collection document. If not provided the metadata field will be omitted from the files collection document.
coroutine rename(self, file_id, new_filename)

Renames the stored file with the specified file_id.

For example:

async def rename():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    # get _id of file to read.
    file_id = await fs.upload_from_stream("test_file",
                                          b"data I want to store!")

    await fs.rename(file_id, "new_test_name")

Raises NoFile if no file with file_id exists.

Parameters:
  • file_id: The _id of the file to be renamed.
  • new_filename: The new name of the file.
coroutine upload_from_stream(self, filename, source, chunk_size_bytes=None, metadata=None)

Uploads a user file to a GridFS bucket.

Reads the contents of the user file from source and uploads it to the file filename. Source can be a string or file-like object. For example:

async def upload_from_stream():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    file_id = await fs.upload_from_stream(
        "test_file",
        b"data I want to store!",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

Raises NoFile if no such version of that file exists. Raises ValueError if filename is not a string.

Parameters:
  • filename: The name of the file to upload.
  • source: The source stream of the content to be uploaded. Must be a file-like object that implements read() or a string.
  • chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes of AsyncIOMotorGridFSBucket.
  • metadata (optional): User data for the ‘metadata’ field of the files collection document. If not provided the metadata field will be omitted from the files collection document.

Returns the _id of the uploaded file.

coroutine upload_from_stream_with_id(self, file_id, filename, source, chunk_size_bytes=None, metadata=None)

Uploads a user file to a GridFS bucket with a custom file id.

Reads the contents of the user file from source and uploads it to the file filename. Source can be a string or file-like object. For example:

async def upload_from_stream_with_id():
    my_db = AsyncIOMotorClient().test
    fs = AsyncIOMotorGridFSBucket(my_db)
    file_id = await fs.upload_from_stream_with_id(
        ObjectId(),
        "test_file",
        b"data I want to store!",
        chunk_size_bytes=4,
        metadata={"contentType": "text/plain"})

Raises NoFile if no such version of that file exists. Raises ValueError if filename is not a string.

Parameters:
  • file_id: The id to use for this file. The id must not have already been used for another file.
  • filename: The name of the file to upload.
  • source: The source stream of the content to be uploaded. Must be a file-like object that implements read() or a string.
  • chunk_size_bytes (options): The number of bytes per chunk of this file. Defaults to the chunk_size_bytes of AsyncIOMotorGridFSBucket.
  • metadata (optional): User data for the ‘metadata’ field of the files collection document. If not provided the metadata field will be omitted from the files collection document.
class motor.motor_asyncio.AsyncIOMotorGridFS(database, collection='fs')

DEPRECATED: Use MotorGridFSBucket or AsyncIOMotorGridFSBucket.

An instance of GridFS on top of a single Database.

Parameters:
  • database: a MotorDatabase
  • collection (optional): A string, name of root collection to use, such as “fs” or “my_files”

See general MongoDB documentation

gridfs

Changed in version 0.2: open method removed; no longer needed.

coroutine find_one(self, filter=None, *args, **kwargs)

Get a single file from gridfs.

All arguments to find() are also valid arguments for find_one(), although any limit argument will be ignored. Returns a single AsyncIOMotorGridOut, or None if no matching file is found. For example:

file = await fs.find_one({"filename": "lisa.txt"})
Parameters:
  • filter (optional): a dictionary specifying the query to be performing OR any other type to be used as the value for a query for "_id" in the file collection.
  • *args (optional): any additional positional arguments are the same as the arguments to find().
  • **kwargs (optional): any additional keyword arguments are the same as the arguments to find().
coroutine put(self, data, **kwargs)

Put data in GridFS as a new file.

Equivalent to doing:

try:
    f = await fs.new_file(**kwargs)
    await f.write(data)
finally:
    await f.close()

data can be a bytes instance or a file-like object providing a read() method. If an encoding keyword argument is passed, data can also be a str, which will be encoded as encoding before being written. Any keyword arguments will be passed through to the created file - see AsyncIOMotorGridIn for possible arguments. Returns the "_id" of the created file.

If the "_id" of the file is manually specified, it must not already exist in GridFS. Otherwise FileExists is raised.

Parameters:
  • data: data to be written as a file.
  • **kwargs (optional): keyword arguments for file creation
coroutine delete(file_id)

Delete a file from GridFS by "_id".

Deletes all data belonging to the file with "_id": file_id.

Warning

Any processes/threads reading from the file while this method is executing will likely see an invalid/corrupt file. Care should be taken to avoid concurrent reads to a file while it is being deleted.

Note

Deletes of non-existent files are considered successful since the end result is the same: no file with that _id remains.

Parameters:
  • file_id: "_id" of the file to delete
coroutine exists(document_or_id=None, **kwargs)

Check if a file exists in this instance of GridFS.

The file to check for can be specified by the value of its _id key, or by passing in a query document. A query document can be passed in as dictionary, or by using keyword arguments. Thus, the following three calls are equivalent:

>>> fs.exists(file_id)
>>> fs.exists({"_id": file_id})
>>> fs.exists(_id=file_id)

As are the following two calls:

>>> fs.exists({"filename": "mike.txt"})
>>> fs.exists(filename="mike.txt")

And the following two:

>>> fs.exists({"foo": {"$gt": 12}})
>>> fs.exists(foo={"$gt": 12})

Returns True if a matching file exists, False otherwise. Calls to exists() will not automatically create appropriate indexes; application developers should be sure to create indexes if needed and as appropriate.

Parameters:
  • document_or_id (optional): query document, or _id of the document to check for
  • **kwargs (optional): keyword arguments are used as a query document, if they’re present.
find(*args, **kwargs)

Query GridFS for files.

Returns a cursor that iterates across files matching arbitrary queries on the files collection. Can be combined with other modifiers for additional control. For example:

cursor = fs.find({"filename": "lisa.txt"}, no_cursor_timeout=True)
while (yield cursor.fetch_next):
    grid_out = cursor.next_object()
    data = yield grid_out.read()

This iterates through all versions of “lisa.txt” stored in GridFS. Note that setting no_cursor_timeout may be important to prevent the cursor from timing out during long multi-file processing work.

As another example, the call:

most_recent_three = fs.find().sort("uploadDate", -1).limit(3)

would return a cursor to the three most recently uploaded files in GridFS.

find() follows a similar interface to find() in MotorCollection.

Parameters:
  • filter (optional): a SON object specifying elements which must be present for a document to be included in the result set
  • skip (optional): the number of files to omit (from the start of the result set) when returning the results
  • limit (optional): the maximum number of results to return
  • no_cursor_timeout (optional): if False (the default), any returned cursor is closed by the server after 10 minutes of inactivity. If set to True, the returned cursor will never time out on the server. Care should be taken to ensure that cursors with no_cursor_timeout turned on are properly closed.
  • sort (optional): a list of (key, direction) pairs specifying the sort order for this query. See sort() for details.

Raises TypeError if any of the arguments are of improper type. Returns an instance of GridOutCursor corresponding to this query.

Changed in version 1.0: Removed the read_preference, tag_sets, and secondary_acceptable_latency_ms options.

New in version 0.2.

See general MongoDB documentation

find

coroutine get(file_id)

Get a file from GridFS by "_id".

Returns an instance of GridOut, which provides a file-like interface for reading.

Parameters:
  • file_id: "_id" of the file to get
coroutine get_last_version(filename=None, **kwargs)

Get the most recent version of a file in GridFS by "filename" or metadata fields.

Equivalent to calling get_version() with the default version (-1).

Parameters:
  • filename: "filename" of the file to get, or None
  • **kwargs (optional): find files by custom metadata.
coroutine get_version(filename=None, version=-1, **kwargs)

Get a file from GridFS by "filename" or metadata fields.

Returns a version of the file in GridFS whose filename matches filename and whose metadata fields match the supplied keyword arguments, as an instance of GridOut.

Version numbering is a convenience atop the GridFS API provided by MongoDB. If more than one file matches the query (either by filename alone, by metadata fields, or by a combination of both), then version -1 will be the most recently uploaded matching file, -2 the second most recently uploaded, etc. Version 0 will be the first version uploaded, 1 the second version, etc. So if three versions have been uploaded, then version 0 is the same as version -3, version 1 is the same as version -2, and version 2 is the same as version -1.

Raises NoFile if no such version of that file exists.

Parameters:
  • filename: "filename" of the file to get, or None
  • version (optional): version of the file to get (defaults to -1, the most recent version uploaded)
  • **kwargs (optional): find files by custom metadata.
coroutine list()

List the names of all files stored in this instance of GridFS.

coroutine new_file(**kwargs)

Create a new file in GridFS.

Returns a new GridIn instance to which data can be written. Any keyword arguments will be passed through to GridIn().

If the "_id" of the file is manually specified, it must not already exist in GridFS. Otherwise FileExists is raised.

Parameters:
  • **kwargs (optional): keyword arguments for file creation
class motor.motor_asyncio.AsyncIOMotorGridIn(root_collection, delegate=None, **kwargs)

Class to write data to GridFS. Application developers should not generally need to instantiate this class - see open_upload_stream().

Any of the file level options specified in the GridFS Spec may be passed as keyword arguments. Any additional keyword arguments will be set as additional fields on the file document. Valid keyword arguments include:

  • "_id": unique ID for this file (default: ObjectId) - this "_id" must not have already been used for another file
  • "filename": human name for the file
  • "contentType" or "content_type": valid mime-type for the file
  • "chunkSize" or "chunk_size": size of each of the chunks, in bytes (default: 256 kb)
  • "encoding": encoding used for this file. In Python 2, any unicode that is written to the file will be converted to a str. In Python 3, any str that is written to the file will be converted to bytes.
Parameters:
  • root_collection: A MotorCollection, the root

    collection to write to

  • **kwargs (optional): file level options (see above)

Changed in version 0.2: open method removed, no longer needed.

coroutine abort()

Remove all chunks/files that may have been uploaded and close.

coroutine close()

Flush the file and close it.

A closed file cannot be written any more. Calling close() more than once is allowed.

coroutine set(name, value)

Set an arbitrary metadata attribute on the file. Stores value on the server as a key-value pair within the file document once the file is closed. If the file is already closed, calling set() will immediately update the file document on the server.

Metadata set on the file appears as attributes on a MotorGridOut object created from the file.

Parameters:
  • name: Name of the attribute, will be stored as a key in the file document on the server
  • value: Value of the attribute
coroutine write(data)

Write data to the file. There is no return value.

data can be either a string of bytes or a file-like object (implementing read()). If the file has an encoding attribute, data can also be a unicode (str in python 3) instance, which will be encoded as encoding before being written.

Due to buffering, the data may not actually be written to the database until the close() method is called. Raises ValueError if this file is already closed. Raises TypeError if data is not an instance of str (bytes in python 3), a file-like object, or an instance of unicode (str in python 3). Unicode data is only allowed if the file has an encoding attribute.

Parameters:
  • data: string of bytes or file-like object to be written to the file
coroutine writelines(sequence)

Write a sequence of strings to the file.

Does not add seperators.

chunk_size

Chunk size for this file.

This attribute is read-only.

closed

Is this file closed?

content_type

Mime-type for this file.

filename

Name of this file.

length

Length (in bytes) of this file.

This attribute is read-only and can only be read after close() has been called.

md5

MD5 of the contents of this file (generated on the server).

This attribute is read-only and can only be read after close() has been called.

name

Alias for filename.

upload_date

Date that this file was uploaded.

This attribute is read-only and can only be read after close() has been called.

class motor.motor_asyncio.AsyncIOMotorGridOut(root_collection, file_id=None, file_document=None, delegate=None)

Class to read data out of GridFS.

MotorGridOut supports the same attributes as PyMongo’s GridOut, such as _id, content_type, etc.

You don’t need to instantiate this class directly - use the methods provided by MotorGridFSBucket. If it is instantiated directly, call open(), read(), or readline() before accessing its attributes.

coroutine open(callback=None)

Retrieve this file’s attributes from the server.

Takes an optional callback, or returns a Future.

Parameters:
  • callback: Optional function taking parameters (self, error)

Changed in version 0.2: MotorGridOut now opens itself on demand, calling open explicitly is rarely needed.

coroutine read(size=-1)

Read at most size bytes from the file (less if there isn’t enough data).

The bytes are returned as an instance of str (bytes in python 3). If size is negative or omitted all data is read.

Parameters:
  • size (optional): the number of bytes to read
coroutine readchunk()

Reads a chunk at a time. If the current position is within a chunk the remainder of the chunk is returned.

coroutine readline(size=-1)

Read one line or up to size bytes from the file.

Parameters:
  • size (optional): the maximum number of bytes to read
coroutine stream_to_handler(request_handler)

Write the contents of this file to a tornado.web.RequestHandler. This method calls flush() on the RequestHandler, so ensure all headers have already been set. For a more complete example see the implementation of GridFSHandler.

class FileHandler(tornado.web.RequestHandler):
    @tornado.web.asynchronous
    @gen.coroutine
    def get(self, filename):
        db = self.settings['db']
        fs = yield motor.MotorGridFSBucket(db())
        try:
            gridout = yield fs.open_download_stream_by_name(filename)
        except gridfs.NoFile:
            raise tornado.web.HTTPError(404)

        self.set_header("Content-Type", gridout.content_type)
        self.set_header("Content-Length", gridout.length)
        yield gridout.stream_to_handler(self)
        self.finish()

See also

Tornado RequestHandler

aliases

List of aliases for this file.

This attribute is read-only.

chunk_size

Chunk size for this file.

This attribute is read-only.

close

Make GridOut more generically file-like.

content_type

Mime-type for this file.

This attribute is read-only.

filename

Name of this file.

This attribute is read-only.

length

Length (in bytes) of this file.

This attribute is read-only.

md5

MD5 of the contents of this file (generated on the server).

This attribute is read-only.

metadata

Metadata attached to this file.

This attribute is read-only.

name

Alias for filename.

This attribute is read-only.

seek

Set the current position of this file.

Parameters:
  • pos: the position (or offset if using relative positioning) to seek to
  • whence (optional): where to seek from. os.SEEK_SET (0) for absolute file positioning, os.SEEK_CUR (1) to seek relative to the current position, os.SEEK_END (2) to seek relative to the file’s end.
tell

Return the current position of this file.

upload_date

Date that this file was first uploaded.

This attribute is read-only.

class motor.motor_asyncio.AsyncIOMotorGridOutCursor(cursor, collection)

Don’t construct a cursor yourself, but acquire one from methods like MotorCollection.find() or MotorCollection.aggregate().

Note

There is no need to manually close cursors; they are closed by the server after being fully iterated with to_list(), each(), or fetch_next, or automatically closed by the client when the MotorCursor is cleaned up by the garbage collector.

add_option(mask)

Set arbitrary query flags using a bitmask.

To set the tailable flag: cursor.add_option(2)

batch_size(batch_size)

Limits the number of documents returned in one batch. Each batch requires a round trip to the server. It can be adjusted to optimize performance and limit data transfer.

Note

batch_size can not override MongoDB’s internal limits on the amount of data it will return to the client in a single batch (i.e if you set batch size to 1,000,000,000, MongoDB will currently only return 4-16MB of results per batch).

Raises TypeError if batch_size is not an integer. Raises ValueError if batch_size is less than 0. Raises InvalidOperation if this Cursor has already been used. The last batch_size applied to this cursor takes precedence.

Parameters:
  • batch_size: The size of each batch of results requested.
clone()

Get a clone of this cursor.

coroutine close()

Explicitly kill this cursor on the server. Call like (in Tornado):

yield cursor.close()
comment(comment)

Adds a ‘comment’ to the cursor.

http://docs.mongodb.org/manual/reference/operator/comment/

Parameters:
  • comment: A string or document
coroutine count(with_limit_and_skip=False)

Get the size of the results set for this query.

Returns the number of documents in the results set for this query. Does not take limit() and skip() into account by default - set with_limit_and_skip to True if that is the desired behavior. Raises OperationFailure on a database error.

When used with MongoDB >= 2.6, count() uses any hint() applied to the query. In the following example the hint is passed to the count command:

collection.find({‘field’: ‘value’}).hint(‘field_1’).count()

The count() method obeys the read_preference of the Collection instance on which find() was called.

Parameters:
  • with_limit_and_skip (optional): take any limit() or skip() that has been applied to this cursor into account when getting the count

Note

The with_limit_and_skip parameter requires server version >= 1.1.4-

coroutine distinct(key)

Get a list of distinct values for key among all documents in the result set of this query.

Raises TypeError if key is not an instance of basestring (str in python 3).

The distinct() method obeys the read_preference of the Collection instance on which find() was called.

Parameters:
  • key: name of key for which we want to get the distinct values
each(callback)

Iterates over all the documents for this cursor.

each() returns immediately, and callback is executed asynchronously for each document. callback is passed (None, None) when iteration is complete.

Cancel iteration early by returning False from the callback. (Only False cancels iteration: returning None or 0 does not.)

>>> def inserted(result, error):
...     if error:
...         raise error
...     cursor = collection.find().sort([('_id', 1)])
...     cursor.each(callback=each)
...
>>> def each(result, error):
...     if error:
...         raise error
...     elif result:
...         sys.stdout.write(str(result['_id']) + ', ')
...     else:
...         # Iteration complete
...         IOLoop.current().stop()
...         print('done')
...
>>> collection.insert_many(
...     [{'_id': i} for i in range(5)], callback=inserted)
>>> IOLoop.current().start()
0, 1, 2, 3, 4, done

Note

Unlike other Motor methods, each requires a callback and does not return a Future, so it cannot be used in a coroutine. async for, to_list(), fetch_next are much easier to use.

Parameters:
  • callback: function taking (document, error)
coroutine explain()

Returns an explain plan record for this cursor.

See general MongoDB documentation

explain

hint(index)

Adds a ‘hint’, telling Mongo the proper index to use for the query.

Judicious use of hints can greatly improve query performance. When doing a query on multiple fields (at least one of which is indexed) pass the indexed field as a hint to the query. Hinting will not do anything if the corresponding index does not exist. Raises InvalidOperation if this cursor has already been used.

index should be an index as passed to create_index() (e.g. [('field', ASCENDING)]) or the name of the index. If index is None any existing hint for this query is cleared. The last hint applied to this cursor takes precedence over all others.

Parameters:
  • index: index to hint on (as an index specifier)
limit(limit)

Limits the number of results to be returned by this cursor.

Raises TypeError if limit is not an integer. Raises InvalidOperation if this Cursor has already been used. The last limit applied to this cursor takes precedence. A limit of 0 is equivalent to no limit.

Parameters:
  • limit: the number of results to return

See general MongoDB documentation

limit

max(spec)

Adds max operator that specifies upper bound for specific index.

Parameters:
  • spec: a list of field, limit pairs specifying the exclusive upper bound for all keys of a specific index in order.
max_await_time_ms(max_await_time_ms)

Specifies a time limit for a getMore operation on a TAILABLE_AWAIT cursor. For all other types of cursor max_await_time_ms is ignored.

Raises TypeError if max_await_time_ms is not an integer or None. Raises InvalidOperation if this Cursor has already been used.

Note

max_await_time_ms requires server version >= 3.2

Parameters:
  • max_await_time_ms: the time limit after which the operation is aborted
max_scan(max_scan)

Limit the number of documents to scan when performing the query.

Raises InvalidOperation if this cursor has already been used. Only the last max_scan() applied to this cursor has any effect.

Parameters:
  • max_scan: the maximum number of documents to scan
max_time_ms(max_time_ms)

Specifies a time limit for a query operation. If the specified time is exceeded, the operation will be aborted and ExecutionTimeout is raised. If max_time_ms is None no limit is applied.

Raises TypeError if max_time_ms is not an integer or None. Raises InvalidOperation if this Cursor has already been used.

Parameters:
  • max_time_ms: the time limit after which the operation is aborted
min(spec)

Adds min operator that specifies lower bound for specific index.

Parameters:
  • spec: a list of field, limit pairs specifying the inclusive lower bound for all keys of a specific index in order.
next_object()

Get next GridOut object from cursor.

remove_option(mask)

Unset arbitrary query flags using a bitmask.

To unset the tailable flag: cursor.remove_option(2)

rewind()

Rewind this cursor to its unevaluated state.

skip(skip)

Skips the first skip results of this cursor.

Raises TypeError if skip is not an integer. Raises ValueError if skip is less than 0. Raises InvalidOperation if this Cursor has already been used. The last skip applied to this cursor takes precedence.

Parameters:
  • skip: the number of results to skip
sort(key_or_list, direction=None)

Sorts this cursor’s results.

Pass a field name and a direction, either ASCENDING or DESCENDING:

for doc in collection.find().sort('field', pymongo.ASCENDING):
    print(doc)

To sort by multiple fields, pass a list of (key, direction) pairs:

for doc in collection.find().sort([
        ('field1', pymongo.ASCENDING),
        ('field2', pymongo.DESCENDING)]):
    print(doc)

Beginning with MongoDB version 2.6, text search results can be sorted by relevance:

cursor = db.test.find(
    {'$text': {'$search': 'some words'}},
    {'score': {'$meta': 'textScore'}})

# Sort by 'score' field.
cursor.sort([('score', {'$meta': 'textScore'})])

for doc in cursor:
    print(doc)

Raises InvalidOperation if this cursor has already been used. Only the last sort() applied to this cursor has any effect.

Parameters:
  • key_or_list: a single key or a list of (key, direction) pairs specifying the keys to sort on
  • direction (optional): only used if key_or_list is a single key, if not given ASCENDING is assumed
coroutine to_list(length, callback=None)

Get a list of documents.

>>> from motor.motor_tornado import MotorClient
>>> collection = MotorClient().test.test_collection
>>>
>>> @gen.coroutine
... def f():
...     yield collection.insert_many([{'_id': i} for i in range(4)])
...     cursor = collection.find().sort([('_id', 1)])
...     docs = yield cursor.to_list(length=2)
...     while docs:
...         print(docs)
...         docs = yield cursor.to_list(length=2)
...
...     print('done')
...
>>> ioloop.IOLoop.current().run_sync(f)
[{'_id': 0}, {'_id': 1}]
[{'_id': 2}, {'_id': 3}]
done
Parameters:
  • length: maximum number of documents to return for this call, or None
  • callback (optional): function taking (documents, error)

If a callback is passed, returns None, else returns a Future.

Changed in version 0.2: callback must be passed as a keyword argument, like to_list(10, callback=callback), and the length parameter is no longer optional.

where(code)

Adds a $where clause to this query.

The code argument must be an instance of basestring (str in python 3) or Code containing a JavaScript expression. This expression will be evaluated for each document scanned. Only those documents for which the expression evaluates to true will be returned as results. The keyword this refers to the object currently being scanned.

Raises TypeError if code is not an instance of basestring (str in python 3). Raises InvalidOperation if this Cursor has already been used. Only the last call to where() applied to a Cursor has any effect.

Parameters:
  • code: JavaScript expression to use as a filter
address

The (host, port) of the server used, or None.

Changed in version 3.0: Renamed from “conn_id”.

alive

Does this cursor have the potential to return more data?

This is mostly useful with tailable cursors since they will stop iterating even though they may return more results in the future.

With regular cursors, simply use a for loop instead of alive:

for doc in collection.find():
    print(doc)

Note

Even if alive is True, next() can raise StopIteration. alive can also be True while iterating a cursor from a failed server. In this case alive will return False after next() fails to retrieve the next batch of results from the server.

collation

Adds a Collation to this query.

This option is only supported on MongoDB 3.4 and above.

Raises TypeError if collation is not an instance of Collation or a dict. Raises InvalidOperation if this Cursor has already been used. Only the last collation applied to this cursor has any effect.

Parameters:
cursor_id

Returns the id of the cursor

Useful if you need to manage cursor ids and want to handle killing cursors manually using kill_cursors()

New in version 2.2.

fetch_next

A Future used with gen.coroutine to asynchronously retrieve the next document in the result set, fetching a batch of documents from the server if necessary. Resolves to False if there are no more documents, otherwise next_object() is guaranteed to return a document.

>>> @gen.coroutine
... def f():
...     yield collection.insert_many([{'_id': i} for i in range(5)])
...     cursor = collection.find().sort([('_id', 1)])
...     while (yield cursor.fetch_next):
...         doc = cursor.next_object()
...         sys.stdout.write(str(doc['_id']) + ', ')
...     print('done')
...
>>> IOLoop.current().run_sync(f)
0, 1, 2, 3, 4, done

While it appears that fetch_next retrieves each document from the server individually, the cursor actually fetches documents efficiently in large batches.

In Python 3.5 and newer, cursors can be iterated elegantly and very efficiently in native coroutines with async for:

>>> async def f():
...     async for doc in collection.find():
...         sys.stdout.write(str(doc['_id']) + ', ')
...     print('done')
...
>>> IOLoop.current().run_sync(f)
0, 1, 2, 3, 4, done