From 6cf5e2a188fc5e337d22a098a5fe9a9fe10cc7e7 Mon Sep 17 00:00:00 2001
From: Mike Bayer <mike_mp@zzzcomputing.com>
Date: Wed, 7 Aug 2024 14:31:48 -0400
Subject: [PATCH] note prefix_with as a hint mechanism

References: #11702
References: #11704
Change-Id: Ieee0780f6d132a29269430fc26de5c0664b16c2e
---
 lib/sqlalchemy/sql/selectable.py | 35 +++++++++++++++++++++++++++-----
 1 file changed, 30 insertions(+), 5 deletions(-)

diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index ad12b00342..f38e6cea0a 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -483,10 +483,20 @@ class HasHints:
         """Add a statement hint to this :class:`_expression.Select` or
         other selectable object.
 
-        This method is similar to :meth:`_expression.Select.with_hint`
-        except that
-        it does not require an individual table, and instead applies to the
-        statement as a whole.
+        .. tip::
+
+            :meth:`_expression.Select.with_statement_hint` generally adds hints
+            **at the trailing end** of a SELECT statement.  To place
+            dialect-specific hints such as optimizer hints at the **front** of
+            the SELECT statement after the SELECT keyword, use the
+            :meth:`_expression.Select.prefix_with` method for an open-ended
+            space, or for table-specific hints the
+            :meth:`_expression.Select.with_hint` may be used, which places
+            hints in a dialect-specific location.
+
+        This method is similar to :meth:`_expression.Select.with_hint` except
+        that it does not require an individual table, and instead applies to
+        the statement as a whole.
 
         Hints here are specific to the backend database and may include
         directives such as isolation levels, file directives, fetch directives,
@@ -498,7 +508,7 @@ class HasHints:
 
             :meth:`_expression.Select.prefix_with` - generic SELECT prefixing
             which also can suit some database-specific HINT syntaxes such as
-            MySQL optimizer hints
+            MySQL or Oracle optimizer hints
 
         """
         return self._with_hint(None, text, dialect_name)
@@ -514,6 +524,17 @@ class HasHints:
         selectable to this :class:`_expression.Select` or other selectable
         object.
 
+        .. tip::
+
+            The :meth:`_expression.Select.with_hint` method adds hints that are
+            **specific to a single table** to a statement, in a location that
+            is **dialect-specific**.  To add generic optimizer hints to the
+            **beginning** of a statement ahead of the SELECT keyword such as
+            for MySQL or Oracle, use the :meth:`_expression.Select.prefix_with`
+            method.  To add optimizer hints to the **end** of a statement such
+            as for PostgreSQL, use the
+            :meth:`_expression.Select.with_statement_hint` method.
+
         The text of the hint is rendered in the appropriate
         location for the database backend in use, relative
         to the given :class:`_schema.Table` or :class:`_expression.Alias`
@@ -543,6 +564,10 @@ class HasHints:
 
             :meth:`_expression.Select.with_statement_hint`
 
+            :meth:`_expression.Select.prefix_with` - generic SELECT prefixing
+            which also can suit some database-specific HINT syntaxes such as
+            MySQL or Oracle optimizer hints
+
         """
 
         return self._with_hint(selectable, text, dialect_name)
-- 
2.47.2