This ticket tracks changes to aggregate, count, distinct, find, and find_one to comply with the new CRUD spec. The changes to count and distinct are fully backward compatible. The changes to aggregate, find and find_one will be backwards breaking for some applications.

The aggregate method will now always return an instance of pymongo.command_cursor.CommandCursor, regardless of server version or options. If you are using MongoDB 2.6 or newer, you can prepare existing applications by passing "cursor={}" to the existing aggregate helper. We will make some small changes in PyMongo 2.9 to allow "cursor={}" to work with older server versions, providing an upgrade path.

The find and find_one API (for both Collection and GridFS) will change as follows:

• Changed parameter names (default values and behaviors remain the same):
  • spec (spec_or_id in find_one) -> filter
  • fields -> projection
  • partial -> allow_partial_results

• The "timeout" option is renamed to "no_cursor_timeout" with its default changed to False.

• The tailable, await_data, and exhaust options will be replaced with a cursor_type option. Valid values:
  • cursor.NON_TAILABLE
  • cursor.TAILABLE
  • cursor.TAILABLE_AWAIT
  • cursor.EXHAUST

• The following options are added:
  • oplog_replay (bool - default False) - only valid with tailable cursors against the oplog.
  • modifiers (document - default None) - A dict of query modifiers. See http://docs.mongodb.org/manual/reference/operator/query-modifier/#modifiers for options.

• The following options are removed, replaced by the "modifiers" option:
  • max_scan
  • snapshot

• The as_class option is removed. Use Collection.with_options instead.

The 2.9 PyMongo release will backport the new find/find_one parameters in a non-backward breaking way to provide an upgrade path.