Fixed #28423 -- Updated index docs for JSONField, HStoreField and Arr…

[atombrella]

…ayField

Would it be considerable to backport this to 1.11? Both GinIndex and the class-based indexes were introduced in that release.

https://code.djangoproject.com/ticket/28423

[timgraham]

I'm unsure if repeating a similar thing three times is best approach or if a shared section would be better.

[timgraham]

an Index

[timgraham]

a gist index. The latter can be implemented with an class:~django.db.models.Index subclass.

[timgraham]

We lost the advice about "This does not offer particularly significant help to querying." with regards to btree indexes. Can you give similar advice for other fields?

[atombrella]

@timgraham Yes, I'll adjust it this week. I think a common section in the bottom (or top) would be fine.

[timgraham]

Here's a version with some edits:

:class:`~django.db.models.Index` and :attr:`.Field.db_index` both create a
B-tree index, which isn't particularly helpful when querying complex data types.
Indexes such as :class:`~django.contrib.postgres.indexes.GinIndex` and
:class:`~django.contrib.postgres.indexes.GistIndex` are better suited, though
the index choice is dependent on the queries you're using. GiST may be a good
choice for the :ref:`range fields <range-fields>` and :class:`HStoreField`,
and GIN may be helpful for :class:`ArrayField` and :class:`JSONField`.

I don't have expertise here, but I was reading https://www.postgresql.org/docs/current/static/datatype-json.html and it seems like we should avoid making strong general recommendations (hence wording like "may be").

[timgraham]

Mads, what do you think about the proposed wording?

[atombrella]

LGTM. Sorry for the late follow-up. I'll push it. I was considering whether a reference to https://www.postgresql.org/docs/current/static/textsearch-indexes.html would be an idea, but it's in a chapter targeting full-text search.

[atombrella]

Shouldn't we do a backport of this to 1.11? I think it's just a matter of rephrasing the gist reference to a class-based index. "and a gist index are better suited ... The latter can be implemented with an class:~django.db.models.Index subclass."

[timgraham]

I don't think it's particularly critical but if you want to send a PR, I'm okay to merge it. At some point (after the release of Django 2.0, I guess), the 1.11 docs are frozen except for really critical fixes. In part, that's so that we don't introduce untranslated text into the translated docs. Only the "stable" documentation receives translation updates.