Skip to content

HTTPS clone URL

Subversion checkout URL

You can clone with HTTPS or Subversion.

Download ZIP
Browse files

Documented the new time lookups and updated the date lookups.

  • Loading branch information...
commit a8451a5004c437190e264667b1e6fb8acc3c1eeb 1 parent 29413ea
@aaugustin aaugustin authored
Showing with 84 additions and 7 deletions.
  1. +78 −7 docs/ref/models/querysets.txt
  2. +6 −0 docs/releases/1.6.txt
View
85 docs/ref/models/querysets.txt
@@ -2062,7 +2062,7 @@ numbers and even characters.
year
~~~~
-For date/datetime fields, exact year match. Takes a four-digit year.
+For date and datetime fields, an exact year match. Takes an integer year.
Example::
@@ -2074,6 +2074,9 @@ SQL equivalent::
(The exact SQL syntax varies for each database engine.)
+When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
+current time zone before filtering.
+
.. fieldlookup:: month
month
@@ -2092,12 +2095,15 @@ SQL equivalent::
(The exact SQL syntax varies for each database engine.)
+When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
+current time zone before filtering.
+
.. fieldlookup:: day
day
~~~
-For date and datetime fields, an exact day match.
+For date and datetime fields, an exact day match. Takes an integer day.
Example::
@@ -2112,6 +2118,9 @@ SQL equivalent::
Note this will match any record with a pub_date on the third day of the month,
such as January 3, July 3, etc.
+When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
+current time zone before filtering.
+
.. fieldlookup:: week_day
week_day
@@ -2133,12 +2142,74 @@ Note this will match any record with a ``pub_date`` that falls on a Monday (day
2 of the week), regardless of the month or year in which it occurs. Week days
are indexed with day 1 being Sunday and day 7 being Saturday.
-.. warning::
+When :setting:`USE_TZ` is ``True``, datetime fields are converted to the
+current time zone before filtering.
+
+.. fieldlookup:: hour
+
+hour
+~~~~
+
+.. versionadded:: 1.6
+
+For datetime fields, an exact hour match. Takes an integer between 0 and 23.
+
+Example::
+
+ Event.objects.filter(timestamp__hour=23)
+
+SQL equivalent::
+
+ SELECT ... WHERE EXTRACT('hour' FROM timestamp) = '23';
+
+(The exact SQL syntax varies for each database engine.)
+
+When :setting:`USE_TZ` is ``True``, values are converted to the current time
+zone before filtering.
+
+.. fieldlookup:: minute
+
+minute
+~~~~~~
+
+.. versionadded:: 1.6
+
+For datetime fields, an exact minute match. Takes an integer between 0 and 59.
+
+Example::
+
+ Event.objects.filter(timestamp__minute=29)
+
+SQL equivalent::
+
+ SELECT ... WHERE EXTRACT('minute' FROM timestamp) = '29';
+
+(The exact SQL syntax varies for each database engine.)
+
+When :setting:`USE_TZ` is ``True``, values are converted to the current time
+zone before filtering.
+
+.. fieldlookup:: second
+
+second
+~~~~~~
+
+.. versionadded:: 1.6
+
+For datetime fields, an exact second match. Takes an integer between 0 and 59.
+
+Example::
+
+ Event.objects.filter(timestamp__second=31)
+
+SQL equivalent::
+
+ SELECT ... WHERE EXTRACT('second' FROM timestamp) = '31';
+
+(The exact SQL syntax varies for each database engine.)
- When :doc:`time zone support </topics/i18n/timezones>` is enabled, Django
- uses UTC in the database connection, which means the ``year``, ``month``,
- ``day`` and ``week_day`` lookups are performed in UTC. This is a known
- limitation of the current implementation.
+When :setting:`USE_TZ` is ``True``, values are converted to the current time
+zone before filtering.
.. fieldlookup:: isnull
View
6 docs/releases/1.6.txt
@@ -57,6 +57,9 @@ Minor features
* Added :meth:`~django.db.models.query.QuerySet.earliest` for symmetry with
:meth:`~django.db.models.query.QuerySet.latest`.
+* In addition to :lookup:`year`, :lookup:`month` and :lookup:`day`, the ORM
+ now supports :lookup:`hour`, :lookup:`minute` and :lookup:`second` lookups.
+
* The default widgets for :class:`~django.forms.EmailField` and
:class:`~django.forms.URLField` use the new type attributes available in
HTML5 (type='email', type='url').
@@ -99,6 +102,9 @@ Backwards incompatible changes in 1.6
list of :class:`~datetime.date`. It used to return a list of
:class:`~datetime.datetime`.
+* Model fields named ``hour``, ``minute`` or ``second`` may clash with the new
+ lookups. Append an explicit :lookup:`exact` lookup if this is an issue.
+
* If your CSS/Javascript code used to access HTML input widgets by type, you
should review it as ``type='text'`` widgets might be now output as
``type='email'`` or ``type='url'`` depending on their corresponding field type.
Please sign in to comment.
Something went wrong with that request. Please try again.