def ensure_index(self, key_or_list, cache_for=300, **kwargs):
"""Ensures that an index exists on this collection.
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 `cache_for`
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 Database objects at once. If an index is created and
then deleted using another database object any call to
:meth:`ensure_index` within the cache window will fail to
re-create the missing index.
.. seealso:: :meth:`create_index`
"""
if "name" in kwargs:
name = kwargs["name"]
else:
keys = _index_list(key_or_list)
name = kwargs["name"] = helpers._gen_index_name(keys)
if not self._database._cached(self._collection, name):
return self.create_index(key_or_list, cache_for, **kwargs)
def drop_index(self, name):
"""Drops the specified index on this collection.
Can be used on non-existant collections or collections with no
indexes. Raises OperationFailure on an error. `name`
can be either an index name (as returned by `create_index`),
or an index specifier (as passed to `create_index`). An index
specifier should be a list of (key, direction) pairs. Raises
TypeError if index is not an instance of (str, unicode, list).
.. warning::
if a custom name was used on index creation (by
passing the `name` parameter to :meth:`create_index` or
:meth:`ensure_index`) the index **must** be dropped by name.
:Parameters:
- `name`: index (or name of index) to drop
"""
if isinstance(name, list):
name = helpers._gen_index_name(name)
if not isinstance(name, basestring):
raise TypeError("index_or_name must be an index name or list")
self._database._purge_index(self._collection, name)
self._database.command("dropIndexes", self._collection, index=name,
allowable_errors=["ns not found"])
def create_index(self, key_or_list, cache_for=300, **kwargs):
"""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 :class:`basestring`
(:class:`str` in python 3), and the directions must be one of
(:data:`~pymongo.ASCENDING`, :data:`~pymongo.DESCENDING`,
:data:`~pymongo.GEO2D`). Returns the name of the created index.
All optional index creation paramaters should be passed as
keyword arguments to this method. Valid options include:
check http://docs.mongodb.org/manual/reference/method/db.collection.ensureIndex/#db.collection.ensureIndex
"""
keys = _index_list(key_or_list)
index = {"key": _index_document(keys), "ns": self._collection_name}
name = "name" in kwargs and kwargs["name"] or helpers._gen_index_name(keys)
index["name"] = name
index.update(kwargs)
Client(self._database, 'system.indexes').insert(index, check_keys=False)
self._database._cache_index(self._collection, name, cache_for)
return name
