From e74e207cce54802f897adcb42149440ee154821e Mon Sep 17 00:00:00 2001 From: Aymeric Augustin Date: Sun, 10 Feb 2013 16:15:49 +0100 Subject: Fixed #17260 -- Added time zone aware aggregation and lookups. Thanks Carl Meyer for the review. Squashed commit of the following: commit 4f290bdb60b7d8534abf4ca901bd0844612dcbda Author: Aymeric Augustin Date: Wed Feb 13 21:21:30 2013 +0100 Used '0:00' instead of 'UTC' which doesn't always exist in Oracle. Thanks Ian Kelly for the suggestion. commit 01b6366f3ce67d57a58ca8f25e5be77911748638 Author: Aymeric Augustin Date: Wed Feb 13 13:38:43 2013 +0100 Made tzname a parameter of datetime_extract/trunc_sql. This is required to work around a bug in Oracle. commit 924a144ef8a80ba4daeeafbe9efaa826566e9d02 Author: Aymeric Augustin Date: Wed Feb 13 14:47:44 2013 +0100 Added support for parameters in SELECT clauses. commit b4351d2890cd1090d3ff2d203fe148937324c935 Author: Aymeric Augustin Date: Mon Feb 11 22:30:22 2013 +0100 Documented backwards incompatibilities in the two previous commits. commit 91ef84713c81bd455f559dacf790e586d08cacb9 Author: Aymeric Augustin Date: Mon Feb 11 09:42:31 2013 +0100 Used QuerySet.datetimes for the admin's date_hierarchy. commit 0d0de288a5210fa106cd4350961eb2006535cc5c Author: Aymeric Augustin Date: Mon Feb 11 09:29:38 2013 +0100 Used QuerySet.datetimes in date-based generic views. commit 9c0859ff7c0b00734afe7fc15609d43d83215072 Author: Aymeric Augustin Date: Sun Feb 10 21:43:25 2013 +0100 Implemented QuerySet.datetimes on Oracle. commit 68ab511a4ffbd2b811bf5da174d47e4dd90f28fc Author: Aymeric Augustin Date: Sun Feb 10 21:43:14 2013 +0100 Implemented QuerySet.datetimes on MySQL. commit 22d52681d347a8cdf568dc31ed032cbc61d049ef Author: Aymeric Augustin Date: Sun Feb 10 21:42:29 2013 +0100 Implemented QuerySet.datetimes on SQLite. commit f6800fd04c93722b45f9236976389e0b2fe436f5 Author: Aymeric Augustin Date: Sun Feb 10 21:43:03 2013 +0100 Implemented QuerySet.datetimes on PostgreSQL. commit 0c829c23f4cf4d6804cadcc93032dd4c26b8c65e Author: Aymeric Augustin Date: Sun Feb 10 21:41:08 2013 +0100 Added datetime-handling infrastructure in the ORM layers. commit 104d82a7778cf3f0f5d03dfa53709c26df45daad Author: Aymeric Augustin Date: Mon Feb 11 10:05:55 2013 +0100 Updated null_queries tests to avoid clashing with the __second lookup. commit c01bbb32358201b3ac8cb4291ef87b7612a2b8e6 Author: Aymeric Augustin Date: Sun Feb 10 23:07:41 2013 +0100 Updated tests of .dates(). Replaced .dates() by .datetimes() for DateTimeFields. Replaced dates with datetimes in the expected output for DateFields. commit 50fb7a52462fecf0127b38e7f3df322aeb287c43 Author: Aymeric Augustin Date: Sun Feb 10 21:40:09 2013 +0100 Updated and added tests for QuerySet.datetimes. commit a8451a5004c437190e264667b1e6fb8acc3c1eeb Author: Aymeric Augustin Date: Sun Feb 10 22:34:46 2013 +0100 Documented the new time lookups and updated the date lookups. commit 29413eab2bd1d5e004598900c0dadc0521bbf4d3 Author: Aymeric Augustin Date: Sun Feb 10 16:15:49 2013 +0100 Documented QuerySet.datetimes and updated QuerySet.dates. --- docs/ref/models/querysets.txt | 157 ++++++++++++++++++++++++++++++++++++------ 1 file changed, 136 insertions(+), 21 deletions(-) (limited to 'docs/ref/models') diff --git a/docs/ref/models/querysets.txt b/docs/ref/models/querysets.txt index 171c2d3dcd..f77f87dd8e 100644 --- a/docs/ref/models/querysets.txt +++ b/docs/ref/models/querysets.txt @@ -550,14 +550,19 @@ dates .. method:: dates(field, kind, order='ASC') Returns a ``DateQuerySet`` — a ``QuerySet`` that evaluates to a list of -``datetime.datetime`` objects representing all available dates of a particular -kind within the contents of the ``QuerySet``. +:class:`datetime.date` objects representing all available dates of a +particular kind within the contents of the ``QuerySet``. -``field`` should be the name of a ``DateField`` or ``DateTimeField`` of your -model. +.. versionchanged:: 1.6 + ``dates`` used to return a list of :class:`datetime.datetime` objects. + +``field`` should be the name of a ``DateField`` of your model. + +.. versionchanged:: 1.6 + ``dates`` used to accept operating on a ``DateTimeField``. ``kind`` should be either ``"year"``, ``"month"`` or ``"day"``. Each -``datetime.datetime`` object in the result list is "truncated" to the given +``datetime.date`` object in the result list is "truncated" to the given ``type``. * ``"year"`` returns a list of all distinct year values for the field. @@ -572,21 +577,60 @@ model. Examples:: >>> Entry.objects.dates('pub_date', 'year') - [datetime.datetime(2005, 1, 1)] + [datetime.date(2005, 1, 1)] >>> Entry.objects.dates('pub_date', 'month') - [datetime.datetime(2005, 2, 1), datetime.datetime(2005, 3, 1)] + [datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)] >>> Entry.objects.dates('pub_date', 'day') - [datetime.datetime(2005, 2, 20), datetime.datetime(2005, 3, 20)] + [datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)] >>> Entry.objects.dates('pub_date', 'day', order='DESC') - [datetime.datetime(2005, 3, 20), datetime.datetime(2005, 2, 20)] + [datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)] >>> Entry.objects.filter(headline__contains='Lennon').dates('pub_date', 'day') - [datetime.datetime(2005, 3, 20)] + [datetime.date(2005, 3, 20)] -.. warning:: +datetimes +~~~~~~~~~ + +.. versionadded:: 1.6 + +.. method:: datetimes(field, kind, order='ASC', tzinfo=None) + +Returns a ``DateTimeQuerySet`` — a ``QuerySet`` that evaluates to a list of +:class:`datetime.datetime` objects representing all available dates of a +particular kind within the contents of the ``QuerySet``. + +``field`` should be the name of a ``DateTimeField`` of your model. + +``kind`` should be either ``"year"``, ``"month"``, ``"day"``, ``"hour"``, +``"minute"`` or ``"second"``. Each ``datetime.datetime`` object in the result +list is "truncated" to the given ``type``. + +``order``, which defaults to ``'ASC'``, should be either ``'ASC'`` or +``'DESC'``. This specifies how to order the results. + +``tzinfo`` defines the time zone to which datetimes are converted prior to +truncation. Indeed, a given datetime has different representations depending +on the time zone in use. This parameter must be a :class:`datetime.tzinfo` +object. If it's ``None``, Django uses the :ref:`current time zone +`. It has no effect when :setting:`USE_TZ` is +``False``. + +.. _database-time-zone-definitions: + +.. note:: - When :doc:`time zone support ` is enabled, Django - uses UTC in the database connection, which means the aggregation is - performed in UTC. This is a known limitation of the current implementation. + This function performs time zone conversions directly in the database. + As a consequence, your database must be able to interpret the value of + ``tzinfo.tzname(None)``. This translates into the following requirements: + + - SQLite: install pytz_ — conversions are actually performed in Python. + - PostgreSQL: no requirements (see `Time Zones`_). + - Oracle: no requirements (see `Choosing a Time Zone File`_). + - MySQL: load the time zone tables with `mysql_tzinfo_to_sql`_. + + .. _pytz: http://pytz.sourceforge.net/ + .. _Time Zones: http://www.postgresql.org/docs/9.2/static/datatype-datetime.html#DATATYPE-TIMEZONES + .. _Choosing a Time Zone File: http://docs.oracle.com/cd/B19306_01/server.102/b14225/ch4datetime.htm#i1006667 + .. _mysql_tzinfo_to_sql: http://dev.mysql.com/doc/refman/5.5/en/mysql-tzinfo-to-sql.html none ~~~~ @@ -2020,7 +2064,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:: @@ -2032,6 +2076,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 @@ -2050,12 +2097,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:: @@ -2070,6 +2120,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 @@ -2091,12 +2144,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 ` 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 -- cgit v1.3