[Django] #36202: Add examples with nested arrays/objects to JSONField docs for __contains and __contained_by

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Type:
| Cleanup/optimization
Status: new | Component:
| Documentation
Version: 5.2 | Severity: Normal
Keywords: | Triage Stage:
| Unreviewed
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
With data in a JSON field like:
{{{
{"key": [1, 2]}
}}}

I was initially surprised to find that this returns a match, since I
assumed the values would be compared by equality when determining whether
the top-level contains:
{{{
.filter(field__contains={"key": [1]}) # the additional value in the array
doesn't matter
}}}
----

The [https://docs.djangoproject.com/en/5.1/topics/db/queries/#contains
docs] say:
> The returned objects are those where the given dict of key-value pairs
are all contained in the top-level of the field.

From this sentence I assumed values were checked by equality, not
containment all the way down. Apparently this is how it is supposed to
work, see #31836. Of course strings don't behave this way, `{"key":
"value"}` does not contain `{"key": "val"}`.

This seems tricky enough to warrant a little example?
--
Ticket URL: <https://code.djangoproject.com/ticket/36202>
Django <https://code.djangoproject.com/>
The Web framework for perfectionists with deadlines.

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by

--------------------------------------+------------------------------------
Reporter: Jacob Walls | Owner: (none)

Type: Cleanup/optimization | Status: new
Component: Documentation | Version: 5.2

Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

--------------------------------------+------------------------------------
Changes (by Sarah Boyce):

* stage: Unreviewed => Accepted

Comment:

I agree adding an example would be nice, thank you for the ticket Jacob
--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:1>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by

-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned

Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted
Has patch: 0 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0

-------------------------------------+-------------------------------------
Changes (by Clifford Gama):

* owner: (none) => Clifford Gama
* status: new => assigned

--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:2>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:
Keywords: | Triage Stage: Accepted

Has patch: 1 | Needs documentation: 0

Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Changes (by Clifford Gama):

* has_patch: 0 => 1

Comment:

https://github.com/django/django/pull/19226
--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:3>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: assigned
Component: Documentation | Version: 5.2
Severity: Normal | Resolution:

Keywords: | Triage Stage: Ready for
| checkin

Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by Jacob Walls):

* stage: Accepted => Ready for checkin

--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:4>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama

Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: fixed

Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Changes (by GitHub <noreply@…>):

* resolution: => fixed
* status: assigned => closed

Comment:

In [changeset:"304e9f3d6ae8387bbfc261d68b51247a1f5230bb" 304e9f3d]:
{{{#!CommitTicketReference repository=""
revision="304e9f3d6ae8387bbfc261d68b51247a1f5230bb"
Fixed #36202 -- Added examples of JSONField __contains and __contained_by
lookups with nested arrays to docs.
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:5>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------

Comment (by Mariusz Felisiak <felisiak.mariusz@…>):

In [changeset:"bcb6ada288a0faf892e9982bca478e4e0da621ae" bcb6ada2]:
{{{#!CommitTicketReference repository=""
revision="bcb6ada288a0faf892e9982bca478e4e0da621ae"
[5.2.x] Fixed #36202 -- Added examples of JSONField __contains and

__contained_by lookups with nested arrays to docs.

Backport of 304e9f3d6ae8387bbfc261d68b51247a1f5230bb from main
}}}
--
Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:6>

[Django]

#36202: Add examples with nested arrays/objects to JSONField docs for __contains
and __contained_by
-------------------------------------+-------------------------------------
Reporter: Jacob Walls | Owner: Clifford
Type: | Gama
Cleanup/optimization | Status: closed
Component: Documentation | Version: 5.2
Severity: Normal | Resolution: fixed
Keywords: | Triage Stage: Ready for
| checkin
Has patch: 1 | Needs documentation: 0
Needs tests: 0 | Patch needs improvement: 0
Easy pickings: 0 | UI/UX: 0
-------------------------------------+-------------------------------------
Comment (by Mariusz Felisiak <felisiak.mariusz@…>):

In [changeset:"e9acb05b6308e2b07f7f75d70e80e6472a04a336" e9acb05b]:
{{{#!CommitTicketReference repository=""
revision="e9acb05b6308e2b07f7f75d70e80e6472a04a336"
[5.1.x] Fixed #36202 -- Added examples of JSONField __contains and

__contained_by lookups with nested arrays to docs.

Backport of 304e9f3d6ae8387bbfc261d68b51247a1f5230bb from main
}}}
--

Ticket URL: <https://code.djangoproject.com/ticket/36202#comment:7>