Add documentation for MySQL optimizer hints using prefix_with

Fixes: #4667
Change-Id: Iac3345319dc7c5a20bc7a6520492d2f341b64807

3 files changed, 27 insertions, 6 deletions

diff --git a/lib/sqlalchemy/dialects/mysql/base.py b/lib/sqlalchemy/dialects/mysql/base.py
index 02929fc5d..44f90c47c 100644
--- a/lib/sqlalchemy/dialects/mysql/base.py
+++ b/lib/sqlalchemy/dialects/mysql/base.py
@@ -323,14 +323,22 @@ available.
 * INSERT..ON DUPLICATE KEY UPDATE:  See
   :ref:`mysql_insert_on_duplicate_key_update`
 
-* SELECT pragma::
+* SELECT pragma, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
 
-    select(..., prefixes=['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
+    select(...).prefix_with(['HIGH_PRIORITY', 'SQL_SMALL_RESULT'])
 
 * UPDATE with LIMIT::
 
     update(..., mysql_limit=10)
 
+* optimizer hints, use :meth:`.Select.prefix_with` and :meth:`.Query.prefix_with`::
+
+    select(...).prefix_with("/*+ NO_RANGE_OPTIMIZATION(t4 PRIMARY) */")
+
+* index hints, use :meth:`.Select.with_hint` and :meth:`.Query.with_hint`::
+
+    select(...).with_hint(some_table, "USE INDEX xyz")
+
 .. _mysql_insert_on_duplicate_key_update:
 
 INSERT...ON DUPLICATE KEY UPDATE (Upsert)
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::
 
diff --git a/lib/sqlalchemy/sql/selectable.py b/lib/sqlalchemy/sql/selectable.py
index a44e94da7..ff9ab984e 100644
--- a/lib/sqlalchemy/sql/selectable.py
+++ b/lib/sqlalchemy/sql/selectable.py
@@ -165,6 +165,9 @@ class HasPrefixes(object):
 
             stmt = table.insert().prefix_with("LOW_PRIORITY", dialect="mysql")
 
+            # MySQL 5.7 optimizer hints
+            stmt = select([table]).prefix_with("/*+ BKA(t1) */", dialect="mysql")
+
         Multiple prefixes can be specified by multiple calls
         to :meth:`.prefix_with`.
 
@@ -3152,6 +3155,10 @@ class Select(HasPrefixes, HasSuffixes, GenerativeSelect):
 
             :meth:`.Select.with_hint`
 
+            :meth:.`.Select.prefix_with` - generic SELECT prefixing which also
+            can suit some database-specific HINT syntaxes such as MySQL
+            optimizer hints
+
         """
         return self.with_hint(None, text, dialect_name)