Suggesting: Documentation update for bulk_create method

[Peter Vlasveld]

This suggestion relates to the bulk_create method for creating model objects ​https://docs.djangoproject.com/en/2.2/ref/models/querysets/#bulk-create. Currently the documentation states what the method does and the caveats associated with its use, but there is no information on what it returns, and in what order the list is returned.

I would be willing to make this modification myself, but I actually don't know if the order of the list is guaranteed to be the same as the order of the input list. This would be really useful information for developers. For example, I currently have a piece of code in my codebase that uses bulk_create and then performs an additional check on the output list to ensure that it is ordered properly. This step would be able to be removed if I know that the bulk_create method outputs the list in the same order as the input list every time. If someone who knows this information could send it to me, I can make this change in the documentation myself, otherwise, someone with that knowledge can make the change.

[Simon Charette]

AFAIK the model instances are returned in the order they were provided.

[Baptiste Mispelon]

You can see the code for bulk_create over there: ​https://github.com/django/django/blob/master/django/db/models/query.py#L514

As it is now, it returns the same object as the one that was passed to the function, so it is in the same order.

However, I'm not sure if this behavior is guaranteed because there don't seem to be any tests for it (I changed the code to reverse the list before returning it and the test suite still passes).
It would be good to add a test for the behavior at the same time as you're documenting it (there's a dedicated file for the bulk_create tests located there: ​https://github.com/django/django/blob/master/tests/bulk_create/tests.py).

[Mariusz Felisiak]

bulk_create() returns new instances in the same order with PKs only on PostgreSQL back-end (and this behavior is tested in tests.postgres_tests, e.g. tests.postgres_tests.test_bulk_update), on other back-ends it returns exactly the same objects without PKs so they are rather useless.

[Mariusz Felisiak]

​PR

[Mariusz Felisiak <felisiak.mariusz@…>]

In 382af9b1:

Fixed #31003 -- Doc'd and tested return value of QuerySet.bulk_create().

[Mariusz Felisiak <felisiak.mariusz@…>]

In cac9ec73:

Refs #31003 -- Moved note about return value of QuerySet.bulk_create() to the first paragraph.

[Mariusz Felisiak <felisiak.mariusz@…>]

In 3eb72ad3:

[3.2.x] Refs #31003 -- Moved note about return value of QuerySet.bulk_create() to the first paragraph.

Backport of cac9ec73db35a6d38d33f271f4724da486c60e9f from main.