class Extract(expression, lookup_name=None, tzinfo=None, **extra) [source]
Extracts a component of a date as a number.
Takes an expression representing a DateField or DateTimeField and a lookup_name, and returns the part of the date referenced by lookup_name as an IntegerField. Django usually uses the databases’ extract function, so you may use any lookup_name that your database supports. A tzinfo subclass, usually provided by pytz, can be passed to extract a value in a specific timezone.
Given the datetime 2015-06-15 23:30:01.000321+00:00, the built-in lookup_names return:
- “year”: 2015
- “month”: 6
- “day”: 15
- “week_day”: 2
- “hour”: 23
- “minute”: 30
- “second”: 1
If a different timezone like Australia/Melbourne is active in Django, then the datetime is converted to the timezone before the value is extracted. The timezone offset for Melbourne in the example date above is +10:00. The values returned when this timezone is active will be the same as above except for:
- “day”: 16
- “week_day”: 3
- “hour”: 9
week_day values
The week_day lookup_type is calculated differently from most databases and from Python’s standard functions. This function will return 1 for Sunday, 2 for Monday, through 7 for Saturday.
The equivalent calculation in Python is:
1 2 3 4 | >>> from datetime import datetime>>> dt = datetime(2015, 6, 15)>>> (dt.isoweekday() % 7) + 12 |
Each lookup_name above has a corresponding Extract subclass (listed below) that should typically be used instead of the more verbose equivalent, e.g. use ExtractYear(...) rather than Extract(..., lookup_name='year').
Usage example:
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 | >>> from datetime import datetime>>> from django.db.models.functions import Extract>>> start = datetime(2015, 6, 15)>>> end = datetime(2015, 7, 2)>>> Experiment.objects.create(... start_datetime=start, start_date=start.date(),... end_datetime=end, end_date=end.date())>>> # Add the experiment start year as a field in the QuerySet.>>> experiment = Experiment.objects.annotate(... start_year=Extract('start_datetime', 'year')).get()>>> experiment.start_year2015>>> # How many experiments completed in the same year in which they started?>>> Experiment.objects.filter(... start_datetime__year=Extract('end_datetime', 'year')).count()1 |
Please login to continue.