def ensure_index(self, key_or_list, direction=None, unique=False, ttl=300):
"""Ensures that an index exists 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 direction(s) must be one of
(:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`).
Unlike :meth:`create_index`, which attempts to create an index
unconditionally, :meth:`ensure_index` takes advantage of some
caching within the driver such that it only attempts to create
indexes that might not already exist. When an index is created
(or ensured) by PyMongo it is "remembered" for `ttl`
seconds. Repeated calls to :meth:`ensure_index` within that
time limit will be lightweight - they will not attempt to
actually create the index.
Care must be taken when the database is being accessed through
multiple connections at once. If an index is created using
PyMongo and then deleted using another connection any call to
:meth:`ensure_index` within the cache window will fail to
re-create the missing index.
Returns the name of the created index if an index is actually
created. Returns ``None`` if the index already exists.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the index to ensure
- `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`
"""
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)
keys = helpers._index_list(key_or_list)
name = self._gen_index_name(keys)
if self.database().connection()._cache_index(self.__database.name(),
self.name(), name, ttl):
return self.create_index(key_or_list, unique=unique, ttl=ttl)
return None
def ensure_index(self, key_or_list, direction=None, unique=False, ttl=300):
"""Ensures that an index exists 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 direction(s) must be one of
(:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`).
Unlike :meth:`create_index`, which attempts to create an index
unconditionally, :meth:`ensure_index` takes advantage of some
caching within the driver such that it only attempts to create
indexes that might not already exist. When an index is created
(or ensured) by PyMongo it is "remembered" for `ttl`
seconds. Repeated calls to :meth:`ensure_index` within that
time limit will be lightweight - they will not attempt to
actually create the index.
Care must be taken when the database is being accessed through
multiple connections at once. If an index is created using
PyMongo and then deleted using another connection any call to
:meth:`ensure_index` within the cache window will fail to
re-create the missing index.
Returns the name of the created index if an index is actually
created. Returns ``None`` if the index already exists.
:Parameters:
- `key_or_list`: a single key or a list of (key, direction) pairs
specifying the index to ensure
- `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`
"""
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)
keys = helpers._index_list(key_or_list)
name = self._gen_index_name(keys)
if self.database().connection()._cache_index(self.__database.name(),
self.name(),
name, ttl):
return self.create_index(key_or_list, unique=unique, ttl=ttl)
return None
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
