Clean up join pushdown docs for JDBC connectors

docs/src/main/sphinx/connector/clickhouse.rst

@@ -191,10 +191,32 @@ ClickHouse        Trino             Notes
 
 .. include:: jdbc-type-mapping.fragment
 
+.. _clickhouse-sql-support:
+
+SQL support
+-----------
+
+The connector provides read and write access to data and metadata in
+a ClickHouse catalog. In addition to the :ref:`globally available
+<sql-globally-available>` and :ref:`read operation <sql-read-operations>`
+statements, the connector supports the following features:
+
+* :doc:`/sql/insert`
+* :doc:`/sql/truncate`
+* :ref:`sql-schema-table-management`
+
+.. include:: alter-schema-limitation.fragment
+
+Performance
+-----------
+
+The connector includes a number of performance improvements, detailed in the
+following sections.
+
 .. _clickhouse-pushdown:
 
 Pushdown
---------
+^^^^^^^^
 
 The connector supports pushdown for a number of operations:
 
@@ -209,19 +231,3 @@ The connector supports pushdown for a number of operations:
 * :func:`sum`
 
 .. include:: no-pushdown-text-type.fragment
-
-.. _clickhouse-sql-support:
-
-SQL support
------------
-
-The connector provides read and write access to data and metadata in
-a ClickHouse catalog. In addition to the :ref:`globally available
-<sql-globally-available>` and :ref:`read operation <sql-read-operations>`
-statements, the connector supports the following features:
-
-* :doc:`/sql/insert`
-* :doc:`/sql/truncate`
-* :ref:`sql-schema-table-management`
-
-.. include:: alter-schema-limitation.fragment

docs/src/main/sphinx/connector/jdbc-case-insensitive-matching.fragment

@@ -1,5 +1,5 @@
 Case insensitive matching
-~~~~~~~~~~~~~~~~~~~~~~~~~
+"""""""""""""""""""""""""
 
 When ``case-insensitive-name-matching`` is set to ``true``, Trino
 is able to query non-lowercase schemas and tables by maintaining a mapping of

docs/src/main/sphinx/connector/jdbc-common-configurations.fragment

@@ -42,8 +42,3 @@ connector:
       Do not change this setting from the default. Non-default values may
       negatively impact performance.
     - ``1000``
-  * - ``join-pushdown.enabled``
-    - Enable :ref:`join pushdown <join-pushdown>`. Equivalent :doc:`catalog
-      session property </sql/set-session>` is ``join_pushdown_enabled``.  Enabling
-      this may negatively impact performance for some queries.
-    - ``false``

docs/src/main/sphinx/connector/join-pushdown-enabled-false.fragment

@@ -0,0 +1,8 @@
+Join pushdown
+"""""""""""""
+
+The ``join-pushdown.enabled`` catalog configuration property or
+``join_pushdown_enabled`` :ref:`catalog session property
+<session-properties-definition>` control whether the connector pushes
+down join operations. The property defaults to ``false``, and enabling join
+pushdowns may negatively impact performance for some queries.

docs/src/main/sphinx/connector/join-pushdown-enabled-true.fragment

@@ -0,0 +1,35 @@
+Cost-based join pushdown
+""""""""""""""""""""""""
+
+The connector supports cost-based :ref:`join-pushdown` to make intelligent
+decisions about whether to push down a join operation to the data source.
+
+When cost-based join pushdown is enabled, the connector only pushes down join
+operations if the available :doc:`/optimizer/statistics` suggest that doing so
+improves performance. Note that if no table statistics are available, join
+operation pushdown does not occur to avoid a potential decrease in query
+performance.
+
+The following table describes catalog configuration properties for
+join pushdown:
+
+.. list-table::
+  :widths: 30, 40, 30
+  :header-rows: 1
+
+  * - Property name
+    - Description
+    - Default value
+  * - ``join-pushdown.enabled``
+    - Enable :ref:`join pushdown <join-pushdown>`. Equivalent :ref:`catalog
+      session property <session-properties-definition>` is
+      ``join_pushdown_enabled``.
+    - ``true``
+  * - ``join-pushdown.strategy``
+    - Strategy used to evaluate whether join operations are pushed down. Set to
+      ``AUTOMATIC`` to enable cost-based join pushdown, or ``EAGER`` to
+      push down joins whenever possible. Note that ``EAGER`` can push down joins
+      even when table statistics are unavailable, which may result in degraded
+      query performance. Because of this, ``EAGER`` is only recommended for
+      testing and troubleshooting purposes.
+    - ``AUTOMATIC``

docs/src/main/sphinx/connector/memsql.rst

@@ -117,19 +117,6 @@ Type mapping
 
 .. include:: jdbc-type-mapping.fragment
 
-.. _singlestore-pushdown:
-
-Pushdown
---------
-
-The connector supports pushdown for a number of operations:
-
-* :ref:`join-pushdown`
-* :ref:`limit-pushdown`
-* :ref:`topn-pushdown`
-
-.. include:: no-pushdown-text-type.fragment
-
 .. _singlestore-sql-support:
 
 SQL support
@@ -153,3 +140,24 @@ statements, the connector supports the following features:
 .. include:: sql-delete-limitation.fragment
 
 .. include:: alter-table-limitation.fragment
+
+Performance
+-----------
+
+The connector includes a number of performance improvements, detailed in the
+following sections.
+
+.. _singlestore-pushdown:
+
+Pushdown
+^^^^^^^^
+
+The connector supports pushdown for a number of operations:
+
+* :ref:`join-pushdown`
+* :ref:`limit-pushdown`
+* :ref:`topn-pushdown`
+
+.. include:: join-pushdown-enabled-false.fragment
+
+.. include:: no-pushdown-text-type.fragment

docs/src/main/sphinx/connector/mysql.rst

@@ -285,6 +285,27 @@ Finally, you can access the ``clicks`` table in the ``web`` database::
 If you used a different name for your catalog properties file, use
 that catalog name instead of ``mysql`` in the above examples.
 
+.. _mysql-sql-support:
+
+SQL support
+-----------
+
+The connector provides read access and write access to data and metadata in the
+MySQL database. In addition to the :ref:`globally available <sql-globally-available>` and
+:ref:`read operation <sql-read-operations>` statements, the connector supports
+the following statements:
+
+* :doc:`/sql/insert`
+* :doc:`/sql/delete`
+* :doc:`/sql/truncate`
+* :doc:`/sql/create-table`
+* :doc:`/sql/create-table-as`
+* :doc:`/sql/drop-table`
+* :doc:`/sql/create-schema`
+* :doc:`/sql/drop-schema`
+
+.. include:: sql-delete-limitation.fragment
+
 Performance
 -----------
 
@@ -361,25 +382,6 @@ The connector supports pushdown for a number of operations:
 * :func:`var_pop`
 * :func:`var_samp`
 
-.. include:: no-pushdown-text-type.fragment
+.. include:: join-pushdown-enabled-true.fragment
 
-.. _mysql-sql-support:
-
-SQL support
------------
-
-The connector provides read access and write access to data and metadata in the
-MySQL database. In addition to the :ref:`globally available <sql-globally-available>` and
-:ref:`read operation <sql-read-operations>` statements, the connector supports
-the following statements:
-
-* :doc:`/sql/insert`
-* :doc:`/sql/delete`
-* :doc:`/sql/truncate`
-* :doc:`/sql/create-table`
-* :doc:`/sql/create-table-as`
-* :doc:`/sql/drop-table`
-* :doc:`/sql/create-schema`
-* :doc:`/sql/drop-schema`
-
-.. include:: sql-delete-limitation.fragment
+.. include:: no-pushdown-text-type.fragment

docs/src/main/sphinx/connector/no-inequality-pushdown-text-type.fragment

@@ -1,5 +1,5 @@
 Predicate pushdown support
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""
 
 The connector does not support pushdown of inequality predicates, such as
 ``!=``, and range predicates such as ``>``, or ``BETWEEN``, on columns with

docs/src/main/sphinx/connector/no-pushdown-text-type.fragment

@@ -1,5 +1,5 @@
 Predicate pushdown support
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""
 
 The connector does not support pushdown of any predicates on columns with
 :ref:`textual types <string-data-types>` like ``CHAR`` or ``VARCHAR``.

docs/src/main/sphinx/connector/oracle.rst

@@ -377,8 +377,37 @@ Number to decimal configuration properties
 
     - ``UNNECESSARY``
 
+.. _oracle-sql-support:
+
+SQL support
+-----------
+
+The connector provides read access and write access to data and metadata in
+Oracle. In addition to the :ref:`globally available <sql-globally-available>`
+and :ref:`read operation <sql-read-operations>` statements, the connector
+supports the following statements:
+
+* :doc:`/sql/insert`
+* :doc:`/sql/delete`
+* :doc:`/sql/truncate`
+* :doc:`/sql/create-table`
+* :doc:`/sql/create-table-as`
+* :doc:`/sql/drop-table`
+* :doc:`/sql/alter-table`
+* :doc:`/sql/comment`
+
+.. include:: sql-delete-limitation.fragment
+
+.. include:: alter-table-limitation.fragment
+
+Performance
+-----------
+
+The connector includes a number of performance improvements, detailed in the
+following sections.
+
 Synonyms
---------
+^^^^^^^^
 
 Based on performance reasons, Trino disables support for Oracle ``SYNONYM``. To
 include ``SYNONYM``, add the following configuration property:
@@ -390,7 +419,7 @@ include ``SYNONYM``, add the following configuration property:
 .. _oracle-pushdown:
 
 Pushdown
---------
+^^^^^^^^
 
 The connector supports pushdown for a number of operations:
 
@@ -421,10 +450,12 @@ with the following functions:
 * :func:`covar_samp()`
 * :func:`covar_pop()`
 
+.. include:: join-pushdown-enabled-false.fragment
+
 .. _oracle-predicate-pushdown:
 
 Predicate pushdown support
-^^^^^^^^^^^^^^^^^^^^^^^^^^
+""""""""""""""""""""""""""
 
 The connector does not support pushdown of any predicates on columns that use
 the ``CLOB``, ``NCLOB``, ``BLOB``, or ``RAW(n)`` Oracle database types, or Trino
@@ -465,26 +496,3 @@ since ``name`` is a column of type ``VARCHAR(25)``, which maps to
 
     SELECT * FROM nation WHERE name > 'CANADA';
     SELECT * FROM nation WHERE name = 'CANADA';
-
-.. _oracle-sql-support:
-
-SQL support
------------
-
-The connector provides read access and write access to data and metadata in
-Oracle. In addition to the :ref:`globally available <sql-globally-available>`
-and :ref:`read operation <sql-read-operations>` statements, the connector
-supports the following statements:
-
-* :doc:`/sql/insert`
-* :doc:`/sql/delete`
-* :doc:`/sql/truncate`
-* :doc:`/sql/create-table`
-* :doc:`/sql/create-table-as`
-* :doc:`/sql/drop-table`
-* :doc:`/sql/alter-table`
-* :doc:`/sql/comment`
-
-.. include:: sql-delete-limitation.fragment
-
-.. include:: alter-table-limitation.fragment

docs/src/main/sphinx/connector/postgresql.rst

@@ -265,6 +265,8 @@ The connector supports pushdown for a number of operations:
 * :func:`regr_intercept`
 * :func:`regr_slope`
 
+.. include:: join-pushdown-enabled-true.fragment
+
 Predicate pushdown support
 ^^^^^^^^^^^^^^^^^^^^^^^^^^
 

docs/src/main/sphinx/connector/sqlserver.rst

@@ -164,7 +164,6 @@ supports the following features:
 
 .. include:: alter-table-limitation.fragment
 
-
 Performance
 -----------
 
@@ -229,6 +228,8 @@ The connector supports pushdown for a number of operations:
 * :func:`var_pop`
 * :func:`var_samp`
 
+.. include:: join-pushdown-enabled-true.fragment
+
 .. include:: no-pushdown-text-type.fragment
 
 Data compression