Skip to content
This repository

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse code

Clarify the documentation around SQLite and case-sensitive string mat…

…ching.

This was still causing some confusion, so I rewrote the section in the
database notes to encompass both substring matching and non-ASCII
case-insensitive equality checks, as well as putting in a stronger
callout on the "contains" filter.

Refs #16569.

git-svn-id: http://code.djangoproject.com/svn/django/trunk@16694 bcc190cf-cafb-0310-a4f2-bffc1f526a37
  • Loading branch information...
commit 4d2151196163f401c42da5adae4bb06f6adf3d71 1 parent c9da5db
Malcolm Tredinnick authored
29  docs/ref/databases.txt
@@ -380,14 +380,27 @@ specific to SQLite that you should be aware of.
380 380
 
381 381
 .. _sqlite-string-matching:
382 382
 
383  
-String matching for non-ASCII strings
384  
---------------------------------------
385  
-
386  
-SQLite doesn't support case-insensitive matching for non-ASCII strings. Some
387  
-possible workarounds for this are `documented at sqlite.org`_, but they are
388  
-not utilised by the default SQLite backend in Django. Therefore, if you are
389  
-using the ``iexact`` lookup type in your queryset filters, be aware that it
390  
-will not work as expected for non-ASCII strings.
  383
+Substring matching and case sensitivity
  384
+-----------------------------------------
  385
+
  386
+For all SQLite versions, there is some slightly counter-intuitive behavior when
  387
+attempting to match some types of strings.  These are triggered when using the
  388
+:lookup:`iexact` or :lookup:`contains` filters in Querysets. The behavior
  389
+splits into two cases:
  390
+
  391
+1. For substring matching, all matches are done case-insensitively. That is a
  392
+filter such as ``filter(name__contains="aa")`` will match a name of ``"Aabb"``.
  393
+
  394
+2. For strings containing characters outside the ASCII range, all exact string
  395
+matches are performed case-sensitively, even when the case-insensitive options
  396
+are passed into the query. So the :lookup:`iexact` filter will behave exactly
  397
+the same as the :lookup:`exact` filter in these cases.
  398
+
  399
+Some possible workarounds for this are `documented at sqlite.org`_, but they
  400
+aren't utilised by the default SQLite backend in Django, as incorporating them
  401
+would be fairly difficult to do robustly. Thus, Django exposes the default
  402
+SQLite behavior and you should be aware of this when doing case-insensitive or
  403
+substring filtering.
391 404
 
392 405
 .. _documented at sqlite.org: http://www.sqlite.org/faq.html#q18
393 406
 
8  docs/ref/models/querysets.txt
@@ -1476,8 +1476,12 @@ SQL equivalent::
1476 1476
 Note this will match the headline ``'Today Lennon honored'`` but not
1477 1477
 ``'today lennon honored'``.
1478 1478
 
1479  
-SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains`` acts
1480  
-like ``icontains`` for SQLite.
  1479
+.. admonition:: SQLite users
  1480
+
  1481
+    SQLite doesn't support case-sensitive ``LIKE`` statements; ``contains``
  1482
+    acts like ``icontains`` for SQLite. See the :ref:`database note
  1483
+    <sqlite-string-matching>` for more information.
  1484
+
1481 1485
 
1482 1486
 .. fieldlookup:: icontains
1483 1487
 

0 notes on commit 4d21511

Please sign in to comment.
Something went wrong with that request. Please try again.