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 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 (`pymongo.ASCENDING`,
`pymongo.DESCENDING`).
Unlike `create_index`, which attempts to create an index
unconditionally, `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 `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 `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 `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 = pymongo._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 (`pymongo.ASCENDING`,
`pymongo.DESCENDING`).
Unlike `create_index`, which attempts to create an index
unconditionally, `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 `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 `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 `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 = pymongo._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 (`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"]
