From 6d90f3c858776c222c69b682e25b915eae01ed78 Mon Sep 17 00:00:00 2001
From: Mark Story <mark@mark-story.com>
Date: Sun, 8 Sep 2024 00:36:12 -0400
Subject: [PATCH] Document changes in cakephp/cakephp#17882

---
 en/appendices/5-1-migration-guide.rst |  6 ++++++
 en/orm/query-builder.rst              | 28 +++++++++++++++++++++++++++
 2 files changed, 34 insertions(+)

diff --git a/en/appendices/5-1-migration-guide.rst b/en/appendices/5-1-migration-guide.rst
index c6d9e51f3a..7466978631 100644
--- a/en/appendices/5-1-migration-guide.rst
+++ b/en/appendices/5-1-migration-guide.rst
@@ -36,6 +36,7 @@ Behavior Changes
 - The default value for ``valueSeparator`` in ``Table::findList()`` is now
   a single space instead of ``;``.
 - ``ErrorLogger`` uses ``Psr\Log\LogTrait`` now.
+- ``Database\QueryCompiler::$_orderedUnion`` was removed.
 
 Deprecations
 ============
@@ -100,6 +101,11 @@ Database
   functions to manipulate data as geospatial values.
 - ``SelectQuery::__debugInfo()`` now includes which connection role the query
   is for.
+- ``SelectQuery::intersect()`` and ``SelectQuery::intersectAll()`` were added.
+  These methods enable queries using ``INTERSECT`` and ``INTERSECT ALL``
+  conjunctions to be expressed.
+- New supports features were added for ``intersect``, ``intersect-all`` and
+  ``set-operations-order-by`` features.
 
 Datasource
 ----------
diff --git a/en/orm/query-builder.rst b/en/orm/query-builder.rst
index 6c8f86e789..4087a249c8 100644
--- a/en/orm/query-builder.rst
+++ b/en/orm/query-builder.rst
@@ -1706,6 +1706,34 @@ You can create ``UNION ALL`` queries using the ``unionAll()`` method::
 
     $unpublished->unionAll($inReview);
 
+Intersections
+-------------
+
+Intersections allow you to combine the result sets of two queries together and
+finding results with overlapping results. Intersections are created by composing
+one or more select queries together::
+
+    $inReview = $articles->find()
+        ->where(['need_review' => true]);
+
+    $unpublished = $articles->find()
+        ->where(['published' => false]);
+
+    $unpublished->intersect($inReview);
+
+You can create ``INTERSECT ALL`` queries using the ``intersectAll()`` method::
+
+    $inReview = $articles->find()
+        ->where(['need_review' => true]);
+
+    $unpublished = $articles->find()
+        ->where(['published' => false]);
+
+    $unpublished->intersectAll($inReview);
+
+.. versionadded:: 5.1.0
+    ``intersect()`` and ``intersectAll()`` were added.
+
 Subqueries
 ----------