Add documentation for MySQL optimizer hints using prefix_with

Fixes: #4667
Change-Id: Iac3345319dc7c5a20bc7a6520492d2f341b64807

1 files changed, 7 insertions, 0 deletions

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)