diff --git a/docs/python-api.rst b/docs/python-api.rst
index 78b069c..3745ffa 100644
--- a/docs/python-api.rst
+++ b/docs/python-api.rst
@@ -202,7 +202,13 @@ You can filter rows by a WHERE clause using ``.rows_where(where, where_args)``::
     ...     print(row)
     {'id': 1, 'age': 4, 'name': 'Cleo'}
 
-To return custom columns (instead of using ``select *``) pass ``select=``::
+The first argument is a fragment of SQL. The second, optional argument is values to be passed to that fragment - you can use ``?`` placeholders and pass an array, or you can use ``:named`` parameters and pass a dictionary, like this::
+
+    >>> for row in db["dogs"].rows_where("age > :age", {"age": 3}):
+    ...     print(row)
+    {'id': 1, 'age': 4, 'name': 'Cleo'}
+
+To return custom columns (instead of the default that uses ``select *``) pass ``select="column1, column2"``::
 
     >>> db = sqlite_utils.Database("dogs.db")
     >>> for row in db["dogs"].rows_where(select='name, age'):
diff --git a/tests/test_rows.py b/tests/test_rows.py
index 73bd94f..3ac52f9 100644
--- a/tests/test_rows.py
+++ b/tests/test_rows.py
@@ -13,6 +13,7 @@ def test_rows(existing_db):
     [
         ("name = ?", ["Pancakes"], {2}),
         ("age > ?", [3], {1}),
+        ("age > :age", {"age": 3}, {1}),
         ("name is not null", [], {1, 2}),
         ("is_good = ?", [True], {1, 2}),
     ],