def hint(self, 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
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used.
`index` should be an index as passed to
:meth:`~pymongo.collection.Collection.create_index`
(e.g. ``[('field', ASCENDING)]``). If `index`
is ``None`` any existing hints for this query are cleared. The
last hint applied to this cursor takes precedence over all
others.
:Parameters:
- `index`: index to hint on (as an index specifier)
"""
self.__check_okay_to_chain()
if index is None:
self.__hint = None
return self
if not isinstance(index, (types.ListType)):
raise TypeError("hint takes a list specifying an index")
self.__hint = helpers._index_document(index)
return self
def hint(self, 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
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used.
`index` should be an index as passed to
:meth:`~pymongo.collection.Collection.create_index`
(e.g. ``[('field', ASCENDING)]``). If `index`
is ``None`` any existing hints for this query are cleared. The
last hint applied to this cursor takes precedence over all
others.
:Parameters:
- `index`: index to hint on (as an index specifier)
"""
self.__check_okay_to_chain()
if index is None:
self.__hint = None
return self
if not isinstance(index, (types.ListType)):
raise TypeError("hint takes a list specifying an index")
self.__hint = helpers._index_document(index)
return self
def create_index(self, key_or_list, direction=None, unique=False, ttl=300):
"""Creates an index on this collection.
Takes either a single key or a list of (key, direction) pairs.
The key(s) must be an instance of ``(str, unicode)``, and the
directions must be one of (:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Returns the name of the created
index.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the index to create
- `direction` (optional): DEPRECATED this option will be removed
- `unique` (optional): should this index guarantee uniqueness?
- `ttl` (optional): time window (in seconds) during which this index
will be recognized by subsequent calls to :meth:`ensure_index` -
see documentation for :meth:`ensure_index` for details
"""
if not isinstance(key_or_list, (str, unicode, list)):
raise TypeError(
"key_or_list must either be a single key or a list of (key, direction) pairs"
)
if direction is not None:
warnings.warn(
"specifying a direction for a single key index is "
"deprecated and will be removed. there is no need "
"for a direction on a single key index", DeprecationWarning)
to_save = SON()
keys = helpers._index_list(key_or_list)
name = self._gen_index_name(keys)
to_save["name"] = name
to_save["ns"] = self.full_name()
to_save["key"] = helpers._index_document(keys)
to_save["unique"] = unique
self.database().connection()._cache_index(self.__database.name(),
self.name(), name, ttl)
self.database().system.indexes.insert(to_save,
manipulate=False,
check_keys=False)
return to_save["name"]
def create_index(self, key_or_list, direction=None, unique=False, ttl=300):
"""Creates an index on this collection.
Takes either a single key or a list of (key, direction) pairs.
The key(s) must be an instance of ``(str, unicode)``, and the
directions must be one of (:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Returns the name of the created
index.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the index to create
- `direction` (optional): DEPRECATED this option will be removed
- `unique` (optional): should this index guarantee uniqueness?
- `ttl` (optional): time window (in seconds) during which this index
will be recognized by subsequent calls to :meth:`ensure_index` -
see documentation for :meth:`ensure_index` for details
"""
if not isinstance(key_or_list, (str, unicode, list)):
raise TypeError("key_or_list must either be a single key or a list of (key, direction) pairs")
if direction is not None:
warnings.warn("specifying a direction for a single key index is "
"deprecated and will be removed. there is no need "
"for a direction on a single key index",
DeprecationWarning)
to_save = SON()
keys = helpers._index_list(key_or_list)
name = self._gen_index_name(keys)
to_save["name"] = name
to_save["ns"] = self.full_name()
to_save["key"] = helpers._index_document(keys)
to_save["unique"] = unique
self.database().connection()._cache_index(self.__database.name(),
self.name(),
name, ttl)
self.database().system.indexes.insert(to_save, manipulate=False,
check_keys=False)
return to_save["name"]
def sort(self, key_or_list, direction=None):
"""Sorts this cursor's results.
Takes either a single key and a direction, or a list of (key,
direction) pairs. The key(s) must be an instance of ``(str,
unicode)``, and the direction(s) must be one of
(:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Raises
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used. Only the last :meth:`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 :data:`~pymongo.ASCENDING` is assumed
"""
self.__check_okay_to_chain()
keys = helpers._index_list(key_or_list, direction)
self.__ordering = helpers._index_document(keys)
return self
def sort(self, key_or_list, direction=None):
"""Sorts this cursor's results.
Takes either a single key and a direction, or a list of (key,
direction) pairs. The key(s) must be an instance of ``(str,
unicode)``, and the direction(s) must be one of
(:data:`~pymongo.ASCENDING`,
:data:`~pymongo.DESCENDING`). Raises
:class:`~pymongo.errors.InvalidOperation` if this cursor has
already been used. Only the last :meth:`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 :data:`~pymongo.ASCENDING` is assumed
"""
self.__check_okay_to_chain()
keys = helpers._index_list(key_or_list, direction)
self.__ordering = helpers._index_document(keys)
return self
def find(self, spec=None, fields=None, skip=0, limit=0,
timeout=True, snapshot=False, tailable=False, sort=None,
max_scan=None,
_must_use_master=False, _is_command=False,
callback=None):
"""Query the database.
The `spec` argument is a prototype document that all results
must match. For example:
>>> db.test.find({"hello": "world"}, callback=...)
only matches documents that have a key "hello" with value
"world". Matches can have other keys *in addition* to
"hello". The `fields` argument is used to specify a subset of
fields that should be included in the result documents. By
limiting results to a certain subset of fields you can cut
down on network traffic and decoding time.
Raises :class:`TypeError` if any of the arguments are of
improper type.
:Parameters:
- `spec` (optional): a SON object specifying elements which
must be present for a document to be included in the
result set
- `fields` (optional): a list of field names that should be
returned in the result set ("_id" will always be
included), or a dict specifying the fields to return
- `skip` (optional): the number of documents to omit (from
the start of the result set) when returning the results
- `limit` (optional): the maximum number of results to
return
- `timeout` (optional): if True, any returned cursor will be
subject to the normal timeout behavior of the mongod
process. Otherwise, the returned cursor will never timeout
at the server. Care should be taken to ensure that cursors
with timeout turned off are properly closed.
- `snapshot` (optional): if True, snapshot mode will be used
for this query. Snapshot mode assures no duplicates are
returned, or objects missed, which were present at both
the start and end of the query's execution. For details,
see the `snapshot documentation
<http://dochub.mongodb.org/core/snapshot>`_.
- `tailable` (optional): the result of this find call will
be a tailable cursor - tailable cursors aren't closed when
the last data is retrieved but are kept open and the
cursors location marks the final document's position. if
more data is received iteration of the cursor will
continue from the last document received. For details, see
the `tailable cursor documentation
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_.
- `sort` (optional): a list of (key, direction) pairs
specifying the sort order for this query. See
:meth:`~pymongo.cursor.Cursor.sort` for details.
- `max_scan` (optional): limit the number of documents
examined when performing the query
.. mongodoc:: find
"""
if spec is None:
spec = {}
if not isinstance(spec, dict):
raise TypeError("spec must be an instance of dict")
if not isinstance(skip, int):
raise TypeError("skip must be an instance of int")
if not isinstance(limit, int):
raise TypeError("limit must be an instance of int")
if not isinstance(timeout, bool):
raise TypeError("timeout must be an instance of bool")
if not isinstance(snapshot, bool):
raise TypeError("snapshot must be an instance of bool")
if not isinstance(tailable, bool):
raise TypeError("tailable must be an instance of bool")
if not callable(callback):
raise TypeError("callback must be callable")
if fields is not None:
if not fields:
fields = {"_id": 1}
if not isinstance(fields, dict):
fields = helpers._fields_list_to_dict(fields)
self.__spec = spec
self.__fields = fields
self.__skip = skip
self.__limit = limit
self.__batch_size = 0
self.__timeout = timeout
self.__tailable = tailable
self.__snapshot = snapshot
self.__ordering = sort and helpers._index_document(sort) or None
self.__max_scan = max_scan
self.__explain = False
self.__hint = None
# self.__as_class = as_class
self.__tz_aware = False #collection.database.connection.tz_aware
self.__must_use_master = _must_use_master
self.__is_command = _is_command
connection = self.__pool.connection()
try:
connection.send_message(
message.query(self.__query_options(),
self.full_collection_name,
self.__skip,
self.__limit,
self.__query_spec(),
self.__fields),
callback=functools.partial(self._handle_response, orig_callback=callback))
except Exception as e:
connection.close()
def find(self, spec=None, fields=None, skip=0, limit=0,
timeout=True, snapshot=False, tailable=False, sort=None,
max_scan=None, slave_okay=False,
_must_use_master=False, _is_command=False,
callback=None):
"""Query the database.
The `spec` argument is a prototype document that all results
must match. For example:
>>> db.test.find({"hello": "world"}, callback=...)
only matches documents that have a key "hello" with value
"world". Matches can have other keys *in addition* to
"hello". The `fields` argument is used to specify a subset of
fields that should be included in the result documents. By
limiting results to a certain subset of fields you can cut
down on network traffic and decoding time.
Raises :class:`TypeError` if any of the arguments are of
improper type.
:Parameters:
- `spec` (optional): a SON object specifying elements which
must be present for a document to be included in the
result set
- `fields` (optional): a list of field names that should be
returned in the result set ("_id" will always be
included), or a dict specifying the fields to return
- `skip` (optional): the number of documents to omit (from
the start of the result set) when returning the results
- `limit` (optional): the maximum number of results to
return
- `timeout` (optional): if True, any returned cursor will be
subject to the normal timeout behavior of the mongod
process. Otherwise, the returned cursor will never timeout
at the server. Care should be taken to ensure that cursors
with timeout turned off are properly closed.
- `snapshot` (optional): if True, snapshot mode will be used
for this query. Snapshot mode assures no duplicates are
returned, or objects missed, which were present at both
the start and end of the query's execution. For details,
see the `snapshot documentation
<http://dochub.mongodb.org/core/snapshot>`_.
- `tailable` (optional): the result of this find call will
be a tailable cursor - tailable cursors aren't closed when
the last data is retrieved but are kept open and the
cursors location marks the final document's position. if
more data is received iteration of the cursor will
continue from the last document received. For details, see
the `tailable cursor documentation
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_.
- `sort` (optional): a list of (key, direction) pairs
specifying the sort order for this query. See
:meth:`~pymongo.cursor.Cursor.sort` for details.
- `max_scan` (optional): limit the number of documents
examined when performing the query
- `slave_okay` (optional): is it okay to connect directly
to and perform queries on a slave instance
.. mongodoc:: find
"""
if spec is None:
spec = {}
if not isinstance(spec, dict):
raise TypeError("spec must be an instance of dict")
if not isinstance(skip, int):
raise TypeError("skip must be an instance of int")
if not isinstance(limit, int):
raise TypeError("limit must be an instance of int")
if not isinstance(timeout, bool):
raise TypeError("timeout must be an instance of bool")
if not isinstance(snapshot, bool):
raise TypeError("snapshot must be an instance of bool")
if not isinstance(tailable, bool):
raise TypeError("tailable must be an instance of bool")
if not callable(callback):
raise TypeError("callback must be callable")
if fields is not None:
if not fields:
fields = {"_id": 1}
if not isinstance(fields, dict):
fields = helpers._fields_list_to_dict(fields)
self.__spec = spec
self.__fields = fields
self.__skip = skip
self.__limit = limit
self.__batch_size = 0
self.__timeout = timeout
self.__tailable = tailable
self.__snapshot = snapshot
self.__ordering = sort and helpers._index_document(sort) or None
self.__max_scan = max_scan
self.__slave_okay = slave_okay
self.__explain = False
self.__hint = None
# self.__as_class = as_class
self.__tz_aware = False #collection.database.connection.tz_aware
self.__must_use_master = _must_use_master
self.__is_command = _is_command
connection = self.__pool.connection()
try:
connection.send_message(
message.query(self.__query_options(),
self.full_collection_name,
self.__skip,
self.__limit,
self.__query_spec(),
self.__fields),
callback=functools.partial(self._handle_response, orig_callback=callback))
except Exception, e:
logging.error('Error sending query %s' % e)
connection.close()
raise
def find(self, spec=None, fields=None, skip=0, limit=0,
timeout=True, snapshot=False, tailable=False, sort=None,
max_scan=None, slave_okay=False,
await_data=False,
_must_use_master=False, _is_command=False,
callback=None, batch_size=0):
"""Query the database.
The `spec` argument is a prototype document that all results
must match. For example:
>>> db.test.find({"hello": "world"}, callback=...)
only matches documents that have a key "hello" with value
"world". Matches can have other keys *in addition* to
"hello". The `fields` argument is used to specify a subset of
fields that should be included in the result documents. By
limiting results to a certain subset of fields you can cut
down on network traffic and decoding time.
Raises :class:`TypeError` if any of the arguments are of
improper type.
Returns a cursor. find() calls your callback either with an error,
or with the first 100 documents. You must call get_more() repeatedly
on the cursor until it is exhausted:
class Handler(tornado.web.RequestHandler):
@tornado.web.asynchronous
def get(self):
self.cursor = self.db.collection.find({}, batch_size=300,
callback=self._on_response
)
def _on_response(self, response, error):
assert not error
self.write(str(response))
if self.cursor.alive:
self.cursor.get_more(self._on_response)
else:
self.finish()
:Parameters:
- `spec` (optional): a SON object specifying elements which
must be present for a document to be included in the
result set
- `fields` (optional): a list of field names that should be
returned in the result set ("_id" will always be
included), or a dict specifying the fields to return
- `skip` (optional): the number of documents to omit (from
the start of the result set) when returning the results
- `limit` (optional): the maximum number of results to
return
- `timeout` (optional): if True, any returned cursor will be
subject to the normal timeout behavior of the mongod
process. Otherwise, the returned cursor will never timeout
at the server. Care should be taken to ensure that cursors
with timeout turned off are properly closed.
- `snapshot` (optional): if True, snapshot mode will be used
for this query. Snapshot mode assures no duplicates are
returned, or objects missed, which were present at both
the start and end of the query's execution. For details,
see the `snapshot documentation
<http://dochub.mongodb.org/core/snapshot>`_.
- `tailable` (optional): the result of this find call will
be a tailable cursor - tailable cursors aren't closed when
the last data is retrieved but are kept open and the
cursors location marks the final document's position. if
more data is received iteration of the cursor will
continue from the last document received. For details, see
the `tailable cursor documentation
<http://www.mongodb.org/display/DOCS/Tailable+Cursors>`_.
.. versionadded:: 1.2
- `sort` (optional): a list of (key, direction) pairs
specifying the sort order for this query. See
:meth:`~pymongo.cursor.Cursor.sort` for details.
- `max_scan` (optional): limit the number of documents
examined when performing the query
- `slave_okay` (optional): is it okay to connect directly
to and perform queries on a slave instance
- `await_data` (optional): if True, the server will block for
some extra time before returning, waiting for more data to
return. Ignored if `tailable` is False.
.. versionadded:: 1.2
- `callback` (optional): a function that takes arguments (result,
error): a list of result documents, or an Exception
- `batch_size`: The size of each batch of results requested.
.. versionadded:: 1.2
.. mongodoc:: find
"""
if self.__id and self.alive:
logging.warn("Do not call find() twice on the same collection object")
if spec is None:
spec = {}
if limit is None:
limit = 0
if not isinstance(spec, dict):
raise TypeError("spec must be an instance of dict")
if not isinstance(skip, int):
raise TypeError("skip must be an instance of int")
if not isinstance(limit, int):
raise TypeError("limit must be an instance of int or None")
if not isinstance(timeout, bool):
raise TypeError("timeout must be an instance of bool")
if not isinstance(snapshot, bool):
raise TypeError("snapshot must be an instance of bool")
if not isinstance(tailable, bool):
raise TypeError("tailable must be an instance of bool")
if not isinstance(await_data, bool):
raise TypeError("await_data must be an instance of bool")
if not callable(callback):
raise TypeError("callback must be callable")
if fields is not None:
if not fields:
fields = {"_id": 1}
if not isinstance(fields, dict):
fields = helpers._fields_list_to_dict(fields)
self.__spec = spec
self.__fields = fields
self.__skip = skip
self.__limit = limit
self.__batch_size = batch_size
self.__timeout = timeout
self.__tailable = tailable
self.__await_data = tailable and await_data
self.__snapshot = snapshot
self.__ordering = sort and helpers._index_document(sort) or None
self.__max_scan = max_scan
self.__slave_okay = slave_okay
self.__explain = False
self.__hint = None
# self.__debug = debug
# self.__as_class = as_class
self.__tz_aware = False #collection.database.connection.tz_aware
self.__must_use_master = _must_use_master
self.__is_command = _is_command
self.__killed = False
ntoreturn = self.__batch_size
if self.__limit:
if self.__batch_size:
ntoreturn = min(self.__limit, self.__batch_size)
else:
ntoreturn = self.__limit
def _handle_conn(connection):
try:
connection.send_message(
message.query(self.__query_options(),
self.full_collection_name,
self.__skip,
ntoreturn,
self.__query_spec(),
self.__fields),
callback=functools.partial(self._handle_response, orig_callback=callback))
except Exception, e:
logging.error('Error sending query %s' % e)
connection.close()
raise
