- correctly document LIKE / ILIKE, fixes #3890

Change-Id: Ie59e61f53d7c59a4777ab9e6e75a43c71d67523b

2 files changed, 30 insertions, 7 deletions

diff --git a/doc/build/orm/tutorial.rst b/doc/build/orm/tutorial.rst
index 6a7d75fb0..91c6202e1 100644
--- a/doc/build/orm/tutorial.rst
+++ b/doc/build/orm/tutorial.rst
@@ -759,13 +759,26 @@ Here's a rundown of some of the most common operators used in
 
     query.filter(User.name.like('%ed%'))
 
+ .. note:: :meth:`.ColumnOperators.like` renders the LIKE operator, which
+    is case insensitive on some backends, and case sensitive
+    on others.  For guaranteed case-insensitive comparisons, use
+    :meth:`.ColumnOperators.ilike`.
+
+* :meth:`ILIKE <.ColumnOperators.ilike>` (case-insensitive LIKE)::
+
+    query.filter(User.name.ilike('%ed%'))
+
+ .. note:: most backends don't support ILIKE directly.  For those,
+    the :meth:`.ColumnOperators.ilike` operator renders an expression
+    combining LIKE with the LOWER SQL function applied to each operand.
+
 * :meth:`IN <.ColumnOperators.in_>`::
 
     query.filter(User.name.in_(['ed', 'wendy', 'jack']))
 
     # works with query objects too:
     query.filter(User.name.in_(
-            session.query(User.name).filter(User.name.like('%ed%'))
+        session.query(User.name).filter(User.name.like('%ed%'))
     ))
 
 * :meth:`NOT IN <.ColumnOperators.notin_>`::
diff --git a/lib/sqlalchemy/sql/operators.py b/lib/sqlalchemy/sql/operators.py
index 49744568a..d88339299 100644
--- a/lib/sqlalchemy/sql/operators.py
+++ b/lib/sqlalchemy/sql/operators.py
@@ -398,13 +398,16 @@ class ColumnOperators(Operators):
         return self.operate(concat_op, other)
 
     def like(self, other, escape=None):
-        """Implement the ``like`` operator.
+        r"""Implement the ``like`` operator.
 
-        In a column context, produces the clause ``a LIKE other``.
+        In a column context, produces the expression::
+
+            a LIKE other
 
         E.g.::
 
-            select([sometable]).where(sometable.c.column.like("%foobar%"))
+            stmt = select([sometable]).\
+                where(sometable.c.column.like("%foobar%"))
 
         :param other: expression to be compared
         :param escape: optional escape character, renders the ``ESCAPE``
@@ -420,13 +423,20 @@ class ColumnOperators(Operators):
         return self.operate(like_op, other, escape=escape)
 
     def ilike(self, other, escape=None):
-        """Implement the ``ilike`` operator.
+        r"""Implement the ``ilike`` operator, e.g. case insensitive LIKE.
+
+        In a column context, produces an expression either of the form::
+
+            lower(a) LIKE lower(other)
+
+        Or on backends that support the ILIKE operator::
 
-        In a column context, produces the clause ``a ILIKE other``.
+            a ILIKE other
 
         E.g.::
 
-            select([sometable]).where(sometable.c.column.ilike("%foobar%"))
+            stmt = select([sometable]).\
+                where(sometable.c.column.ilike("%foobar%"))
 
         :param other: expression to be compared
         :param escape: optional escape character, renders the ``ESCAPE``