Mongodb-odm: Documentation inconsistency

[caiquecastro]

In the docs, there is this page: https://github.com/doctrine/mongodb-odm/blob/master/docs/en/reference/find-and-update.rst.

On this page, there is a note: "If you don't need to return the document, you can use just run a normal update which can affect multiple documents, as well.", but if I have something like this:

$this->createQueryBuilder()
     ->update()
     ->field('default')->equals(true)
     ->field('default')->set(false)
     ->getQuery()
     ->execute();

It does not update multiple documents, you have to include ->multiple() on the query builder. The code behavior seems right to me, but the docs doesn't. If you agree, I can submit a PR, where I can add as well, a note about the multiple method of the query builder.

[malarzm]

@caiquecastro thanks for raising this! I wanted to say that instead of adding code to example we should add a note instead that by default one document is updated unless ->multiple() is used however I found that we already have such note here: https://github.com/doctrine/mongodb-odm/blob/master/docs/en/reference/query-builder-api.rst#updating-multiple-documents - I think this should be enough?

[Steveb-p]

I got caught by surprise by this sometime ago (coming from pure SQL background I didn't expect that MongoDB updates only one document by default, now I'm aware ;) ). Since those documentation examples are quite distant from one another I would vote for adding a little note there.

[malarzm]

Vote counted, let's add a note then! @caiquecastro still interested in doing so? :)

[alcaeus]

by default one document is updated unless ->multiple() is used

I presume this is why the new driver/library combination has explicit updateOne and updateMany methods. Considering that and the fact that we have the chance to clean up the API with 2.0, I'd suggest the following:

1. For ODM 1.2, add updateOne and updateMany methods to the Query\Builder class, with the latter being the same as calling updateOne followed by multiple.
2. Deprecate the multiple and update methods in 1.2 and remove them in the 2.0 branch.

Thoughts?

[malarzm]

@alcaeus :+1:

[alcaeus]

@malarzm PR in doctrine/mongodb has been created. I'll leave this open to track the documentation changes required to explain the deprecation and new methods.

[Steveb-p]

Is it alright that builder does not complain when mixing findAndUpdate with multiple?

As far as I can tell - judging from how it behaves in my project - those two operations are mutually exclusive, i.e. you can't find and update multiple documents?

[alcaeus]

You are correct - the multiple method does not throw an error if it's applied to a query that does not support it.

[malarzm]

I think there are more places where query builder allows you to shoot yourself in the foot, assumption is that developer knows what's he doing (more or less). Offhand I was caught by findAndUpdate + multiple not working together too ;)