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
InvalidOperation if this cursor has already been used.
`index` should be an index as passed to 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 = pymongo._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
InvalidOperation if this cursor has already been used.
`index` should be an index as passed to 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 = pymongo._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 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 (`pymongo.ASCENDING`,
`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): must be included if key_or_list is a single
key, otherwise must be None
- `unique` (optional): should this index guarantee uniqueness?
- `ttl` (optional): time window (in seconds) during which this index
will be recognized by subsequent calls to `ensure_index` - see
documentation for `ensure_index` for details
"""
to_save = SON()
keys = pymongo._index_list(key_or_list, direction)
name = self._gen_index_name(keys)
to_save["name"] = name
to_save["ns"] = self.full_name()
to_save["key"] = pymongo._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 (`pymongo.ASCENDING`,
`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 `ensure_index` - see
documentation for `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 = pymongo._index_list(key_or_list)
name = self._gen_index_name(keys)
to_save["name"] = name
to_save["ns"] = self.full_name()
to_save["key"] = pymongo._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 (`pymongo.ASCENDING`,
`pymongo.DESCENDING`). 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
"""
self.__check_okay_to_chain()
keys = pymongo._index_list(key_or_list, direction)
self.__ordering = pymongo._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 (`pymongo.ASCENDING`,
`pymongo.DESCENDING`). 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
"""
self.__check_okay_to_chain()
keys = pymongo._index_list(key_or_list, direction)
self.__ordering = pymongo._index_document(keys)
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 (`pymongo.ASCENDING`,
`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 `ensure_index` - see
documentation for `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 = pymongo._index_list(key_or_list)
name = self._gen_index_name(keys)
to_save["name"] = name
to_save["ns"] = self.full_name()
to_save["key"] = pymongo._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"]