Fixed #32776 -- Added support for Array subqueries on PostgreSQL.

3 files changed, 43 insertions, 0 deletions

diff --git a/docs/ref/contrib/postgres/expressions.txt b/docs/ref/contrib/postgres/expressions.txt
new file mode 100644
index 0000000000..79590c2393
--- /dev/null
+++ b/docs/ref/contrib/postgres/expressions.txt
@@ -0,0 +1,37 @@
+=====================================
+PostgreSQL specific query expressions
+=====================================
+
+.. module:: django.contrib.postgres.expressions
+   :synopsis: PostgreSQL specific query expressions
+
+These expressions are available from the
+``django.contrib.postgres.expressions`` module.
+
+``ArraySubquery()`` expressions
+===============================
+
+.. class:: ArraySubquery(queryset)
+
+.. versionadded:: 4.0
+
+``ArraySubquery`` is a :class:`~django.db.models.Subquery` that uses the
+PostgreSQL ``ARRAY`` constructor to build a list of values from the queryset,
+which must use :meth:`.QuerySet.values` to return only a single column.
+
+This class differs from :class:`~django.contrib.postgres.aggregates.ArrayAgg`
+in the way that it does not act as an aggregate function and does not require
+an SQL ``GROUP BY`` clause to build the list of values.
+
+For example, if you want to annotate all related books to an author as JSON
+objects::
+
+    >>> from django.db.models import OuterRef
+    >>> from django.db.models.functions import JSONObject
+    >>> from django.contrib.postgres.expressions import ArraySubquery
+    >>> books = Book.objects.filter(author=OuterRef('pk')).values(
+    ...     json=JSONObject(title='title', pages='pages')
+    ... )
+    >>> author = Author.objects.annotate(books=ArraySubquery(books)).first()
+    >>> author.books
+    [{'title': 'Solaris', 'pages': 204}, {'title': 'The Cyberiad', 'pages': 295}]
diff --git a/docs/ref/contrib/postgres/index.txt b/docs/ref/contrib/postgres/index.txt
index 03ff6da1e0..7627043037 100644
--- a/docs/ref/contrib/postgres/index.txt
+++ b/docs/ref/contrib/postgres/index.txt
@@ -30,6 +30,7 @@ a number of PostgreSQL specific data types.
 
     aggregates
     constraints
+    expressions
     fields
     forms
     functions
diff --git a/docs/releases/4.0.txt b/docs/releases/4.0.txt
index 54d0fd4c1d..bc8e1639c8 100644
--- a/docs/releases/4.0.txt
+++ b/docs/releases/4.0.txt
@@ -131,6 +131,11 @@ Minor features
   :class:`~django.contrib.postgres.operations.AddConstraintNotValid` on
   PostgreSQL.
 
+* The new
+  :class:`ArraySubquery() <django.contrib.postgres.expressions.ArraySubquery>`
+  expression allows using subqueries to construct lists of values on
+  PostgreSQL.
+
 :mod:`django.contrib.redirects`
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~