Add documentation for MySQL optimizer hints using prefix_with

Fixes: #4667
Change-Id: Iac3345319dc7c5a20bc7a6520492d2f341b64807

1 files changed, 10 insertions, 4 deletions

diff --git a/lib/sqlalchemy/orm/query.py b/lib/sqlalchemy/orm/query.py
index 5d340654c..6d777ceae 100644
--- a/lib/sqlalchemy/orm/query.py
+++ b/lib/sqlalchemy/orm/query.py
@@ -1576,6 +1576,10 @@ class Query(object):
 
             :meth:`.Query.with_statement_hint`
 
+            :meth:.`.Query.prefix_with` - generic SELECT prefixing which also
+            can suit some database-specific HINT syntaxes such as MySQL
+            optimizer hints
+
         """
         if selectable is not None:
             selectable = inspect(selectable).selectable
@@ -3107,18 +3111,20 @@ class Query(object):
         ``Query``.
 
         :param \*prefixes: optional prefixes, typically strings,
-         not using any commas.   In particular is useful for MySQL keywords.
+         not using any commas.   In particular is useful for MySQL keywords
+         and optimizer hints:
 
         e.g.::
 
             query = sess.query(User.name).\
                 prefix_with('HIGH_PRIORITY').\
-                prefix_with('SQL_SMALL_RESULT', 'ALL')
+                prefix_with('SQL_SMALL_RESULT', 'ALL').\
+                prefix_with('/*+ BKA(user) */')
 
         Would render::
 
-            SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL users.name AS users_name
-            FROM users
+            SELECT HIGH_PRIORITY SQL_SMALL_RESULT ALL /*+ BKA(user) */
+            users.name AS users_name FROM users
 
         .. seealso::