[JAVA-1097] deprecate ensureIndex() methods Created: 30/Jan/14  Updated: 11/Dec/15  Resolved: 30/Jan/14

Status: Closed
Project: Java Driver
Component/s: API
Affects Version/s: 2.12.0
Fix Version/s: 2.12.0

Type: Task Priority: Major - P3
Reporter: Justin Lee Assignee: Justin Lee
Resolution: Done Votes: 0
Labels: None
Remaining Estimate: Not Specified
Time Spent: Not Specified
Original Estimate: Not Specified

Issue Links:
Depends
is depended on by JAVA-1098 remove ensureIndex() methods Closed
Related
related to DOCS-4539 db.collection.createIndex() should no... Closed
related to DOCS-4540 db.collection.ensureIndex() should be... Closed

 Description   

Deprecate DBCollection.ensureIndex (all overloads) and DBCollection.resetIndexCache. Caching of which indexes have been created is really not something the driver should be doing, as it is prone to race conditions with other clients.



 Comments   
Comment by Nitin Dandriyal [ 11/Dec/15 ]

Thanks Ross Lawley, I was afraid because it seems that the handling of DBCollection.createIndex() is different for mongodb server version prior to 2.6

Comment by Ross Lawley [ 11/Dec/15 ]

nitin.dandriyal@gmail.com - thats fine as DBCollection.createIndex() will only create the index if it doesn't already exist.

Comment by Nitin Dandriyal [ 11/Dec/15 ]

Hi Justin Lee,

I am upgrading from driver version 2.9.3 to 3.2.0-rc0
Mongo Server version : 2.4.5

I was using DBCollection.ensureIndex() method during application start, now while upgrading I saw that this method has been removed. Can I directly use DBCollection.createIndex()? I am worried, after change I do not end up rebuilding indexes everytime my application starts. Thanks in advance

Comment by Jeffrey Yemin [ 16/Oct/14 ]

One clarification: there is no such thing as ensureIndex on the server: ensureIndex is just a MongoDB shell/driver helper method. Until MongoDB 2.6 there was no command to create an index. Driver implementations just inserted a document in the special system.indexes collections. MongoDB 2.6 introduced the createIndexes command, which allows you to create multiple indexes at once, potentially in parallel. As of 2.12.0, the Java driver implementation of both ensureIndex and createIndex will detect the server version and use the createIndexes command if it's available (though there is currently no helper that exposes the ability of createIndexes to create multiple indexes).

Comment by Jens Grivolla [ 16/Oct/14 ]

Thanks for your reply, I think this should be clearer in the documentation. It is very confusing like this, and people are getting misled: https://stackoverflow.com/questions/25968592/difference-between-createindex-and-ensureindex-in-java-using-mongodb/26386601

In summary, if I understand correctly, `createIndex` in Java corresponds to `ensureIndex` on the server, but it can't be called that because there was another method with that name earlier that had to be deprecated because it was broken. Couldn't the name `ensureIndex` be reused on the Java side with the correct functionality (i.e. server side `ensureIndex` instead of client side index caching)?

Comment by Ross Lawley [ 16/Oct/14 ]

Hi jgrivolla, its an unfortunate artefact about the behaviour of ensureIndex that has led it to being deprecated. Drivers shouldn't cache if an index has been created or not as they aren't wholly in possession of that information, this has in the past caused issues to users. So the decision was made to deprecate this behaviour in drivers that supported it.

In reality ensureIndex on the server and createIndex in the driver will do the same thing and will not error if an index already exists. In the future we'll work closer to ensure the shell api and the drivers api follow the same theme.

Comment by Jens Grivolla [ 15/Oct/14 ]

Why is this exactly opposite of the general MongoDB API? Does the Java createIndex() correspond to MongoDB's ensureIndex() or does this mean that Java users have to use a method that's actually deprecated in MongoDB?

Comment by Githook User [ 30/Jan/14 ]

Author:

{u'username': u'evanchooly', u'name': u'Justin Lee', u'email': u'justin.lee@10gen.com'}

Message: fixes JAVA-1097 deprecate ensureIndex() methods
Branch: master
https://github.com/mongodb/mongo-java-driver/commit/5d22fd734370d644cbf403012c1885de6787fb06

Generated at Thu Feb 08 08:53:48 UTC 2024 using Jira 9.7.1#970001-sha1:2222b88b221c4928ef0de3161136cc90c8356a66.