Pymongo / MongoDB: create index or ensure index?

@andreas-jung is right in that ensure_index() is a wrapper over create_index(), I think the confusion arises with the phrase:

When an index is created (or ensured) by PyMongo it is “remembered” for ttl seconds.

It's not that the index is temporary or "transient", what happens is that during the specified amount of seconds, a call to ensure_index() trying to create the same index again will not have any effect and will not call create_index() underneath, but after that "cache" expires, a call to ensure_index() will again call create_index() underneath.

I perfectly understand your confusion because quite frankly PyMongo's docs don't make a very good job at explaining how this works, but if you head over to the Ruby docs, the explanation is a little clearer:

• (String) ensure_index(spec, opts = {})

Calls create_index and sets a flag to not do so again for another X minutes. this time can be specified as an option when initializing a Mongo::DB object as options[:cache_time] Any changes to an index will be propogated through regardless of cache time (e.g., a change of index direction)

The parameters and options for this methods are the same as those for Collection#create_index.

Examples:

Call sequence:

Time t: @posts.ensure_index([['subject', Mongo::ASCENDING]) -- calls create_index and sets the 5 minute cache

Time t+2min : @posts.ensure_index([['subject', Mongo::ASCENDING]) -- doesn't do anything

Time t+3min : @posts.ensure_index([['something_else', Mongo::ASCENDING]) -- calls create_index and sets 5 minute cache

Time t+10min : @posts.ensure_index([['subject', Mongo::ASCENDING]) -- calls create_index and resets the 5 minute counter

I'm not claiming drivers work exactly the same, it's just that for illustration purposes their explanation is a little better IMHO.

Keep in mind that in Mongo 3.x ensureIndex is deprecated and should be discouraged.

Deprecated since version 3.0.0: db.collection.ensureIndex() is now an alias for db.collection.createIndex().

The same is in pymongo:

DEPRECATED - Ensures that an index exists on this collection.

Which means that you should always use create_index.