Функции базы данных ¶

Cast¶

классCast ( выражение , output_field ) ¶

Заставляет тип результата expressionбыть из output_field.

Пример использования:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cast
>>> Author.objects.create(age=25, name='Margaret Smith')
>>> author = Author.objects.annotate(
...    age_as_float=Cast('age', output_field=FloatField()),
... ).get()
>>> print(author.age_as_float)
25.0

Coalesce¶

классCoalesce ( * выражения , ** дополнительные ) ¶

Принимает список по крайней мере из двух имен полей или выражений и возвращает первое ненулевое значение (обратите внимание, что пустая строка не считается нулевым значением). Все аргументы должны быть одного типа, поэтому смешивание текста и чисел приведет к ошибке базы данных.

Примеры использования:

>>> # Get a screen name from least to most public
>>> from django.db.models import Sum, Value as V
>>> from django.db.models.functions import Coalesce
>>> Author.objects.create(name='Margaret Smith', goes_by='Maggie')
>>> author = Author.objects.annotate(
...    screen_name=Coalesce('alias', 'goes_by', 'name')).get()
>>> print(author.screen_name)
Maggie

>>> # Prevent an aggregate Sum() from returning None
>>> aggregated = Author.objects.aggregate(
...    combined_age=Coalesce(Sum('age'), V(0)),
...    combined_age_default=Sum('age'))
>>> print(aggregated['combined_age'])
0
>>> print(aggregated['combined_age_default'])
None

>>> from django.db.models import DateTimeField
>>> from django.db.models.functions import Cast, Coalesce
>>> from django.utils import timezone
>>> now = timezone.now()
>>> Coalesce('updated', Cast(now, DateTimeField()))

Collate¶

классCollate ( выражение , сопоставление ) ¶

Принимает выражение и имя сопоставления для запроса.

Например, для фильтрации без учета регистра в SQLite:

>>> Author.objects.filter(name=Collate(Value('john'), 'nocase'))
<QuerySet [<Author: John>, <Author: john>]>

Его также можно использовать при заказе, например, с PostgreSQL:

>>> Author.objects.order_by(Collate('name', 'et-x-icu'))
<QuerySet [<Author: Ursula>, <Author: Veronika>, <Author: Ülle>]>

Greatest¶

классGreatest ( * выражения , ** дополнительные ) ¶

Принимает список по крайней мере из двух имен полей или выражений и возвращает наибольшее значение. Все аргументы должны быть одного типа, поэтому смешивание текста и чисел приведет к ошибке базы данных.

Пример использования:

class Blog(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)

class Comment(models.Model):
    body = models.TextField()
    modified = models.DateTimeField(auto_now=True)
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)

>>> from django.db.models.functions import Greatest
>>> blog = Blog.objects.create(body='Greatest is the best.')
>>> comment = Comment.objects.create(body='No, Least is better.', blog=blog)
>>> comments = Comment.objects.annotate(last_updated=Greatest('modified', 'blog__modified'))
>>> annotated_comment = comments.get()

annotated_comment.last_updatedбудет самым последним из blog.modified и comment.modified.

JSONObject¶

классJSONObject ( ** поля ) ¶

Принимает список пар ключ-значение и возвращает объект JSON, содержащий эти пары.

Пример использования:

>>> from django.db.models import F
>>> from django.db.models.functions import JSONObject, Lower
>>> Author.objects.create(name='Margaret Smith', alias='msmith', age=25)
>>> author = Author.objects.annotate(json_object=JSONObject(
...     name=Lower('name'),
...     alias='alias',
...     age=F('age') * 2,
... )).get()
>>> author.json_object
{'name': 'margaret smith', 'alias': 'msmith', 'age': 50}

Least¶

классLeast ( * выражения , ** дополнительные ) ¶

Принимает список по крайней мере из двух имен полей или выражений и возвращает наименьшее значение. Все аргументы должны быть одного типа, поэтому смешивание текста и чисел приведет к ошибке базы данных.

NullIf¶

классNullIf ( выражение1 , выражение2 ) ¶

Принимает два выражения и возвращает, Noneесли они равны, в противном случае возвращает expression1.

Extract¶

classExtract ( выражение , lookup_name = None , tzinfo = None , ** extra ) ¶

Извлекает компонент даты как число.

Принимает expressionпредставляющее DateField, DateTimeField, TimeField, или , DurationFieldи а lookup_name, и возвращает часть даты , на которую ссылаются lookup_nameкак IntegerField. Django обычно использует функцию извлечения базы данных, поэтому вы можете использовать любую, lookup_nameкоторую поддерживает ваша база данных. tzinfoПодкласс, как правило , предусмотрено pytz, может быть передан для извлечения значения в конкретной временной зоне.

Учитывая дату и время, встроенный s возвращает:2015-06-15 23:30:01.000321+00:00lookup_name

• «Год»: 2015
• «Iso_year»: 2015
• «Четверть»: 2
• «Месяц»: 6
• «День»: 15
• «Неделя»: 25
• «День_ недели»: 2
• «Iso_week_day»: 1
• «Час»: 23
• «Минута»: 30
• «Секунда»: 1

Если Australia/Melbourneв Django активен другой часовой пояс, например , datetime преобразуется в часовой пояс перед извлечением значения. Смещение часового пояса для Мельбурна в приведенном выше примере даты составляет +10: 00. Значения, возвращаемые, когда этот часовой пояс активен, будут такими же, как указано выше, за исключением:

• «День»: 16
• «День_ недели»: 3
• «Iso_week_day»: 2
• «Час»: 9

>>> from datetime import datetime
>>> dt = datetime(2015, 6, 15)
>>> (dt.isoweekday() % 7) + 1
2

У каждого из lookup_nameвышеперечисленных есть соответствующий Extractподкласс (перечисленный ниже), который обычно следует использовать вместо более подробного эквивалента, например, использовать ExtractYear(...)вместо .Extract(..., lookup_name='year')

Пример использования:

>>> 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_year
2015
>>> # How many experiments completed in the same year in which they started?
>>> Experiment.objects.filter(
...    start_datetime__year=Extract('end_datetime', 'year')).count()
1

>>> from datetime import datetime
>>> from django.utils import timezone
>>> from django.db.models.functions import (
...     ExtractDay, ExtractMonth, ExtractQuarter, ExtractWeek,
...     ExtractIsoWeekDay, ExtractWeekDay, ExtractIsoYear, ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...    start_datetime=start_2015, start_date=start_2015.date(),
...    end_datetime=end_2015, end_date=end_2015.date())
>>> Experiment.objects.annotate(
...     year=ExtractYear('start_date'),
...     isoyear=ExtractIsoYear('start_date'),
...     quarter=ExtractQuarter('start_date'),
...     month=ExtractMonth('start_date'),
...     week=ExtractWeek('start_date'),
...     day=ExtractDay('start_date'),
...     weekday=ExtractWeekDay('start_date'),
...     isoweekday=ExtractIsoWeekDay('start_date'),
... ).values(
...     'year', 'isoyear', 'quarter', 'month', 'week', 'day', 'weekday',
...     'isoweekday',
... ).get(end_date__year=ExtractYear('start_date'))
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1}

>>> from datetime import datetime
>>> from django.utils import timezone
>>> from django.db.models.functions import (
...     ExtractDay, ExtractHour, ExtractMinute, ExtractMonth,
...     ExtractQuarter, ExtractSecond, ExtractWeek, ExtractIsoWeekDay,
...     ExtractWeekDay, ExtractIsoYear, ExtractYear,
... )
>>> start_2015 = datetime(2015, 6, 15, 23, 30, 1, tzinfo=timezone.utc)
>>> end_2015 = datetime(2015, 6, 16, 13, 11, 27, tzinfo=timezone.utc)
>>> Experiment.objects.create(
...    start_datetime=start_2015, start_date=start_2015.date(),
...    end_datetime=end_2015, end_date=end_2015.date())
>>> Experiment.objects.annotate(
...     year=ExtractYear('start_datetime'),
...     isoyear=ExtractIsoYear('start_datetime'),
...     quarter=ExtractQuarter('start_datetime'),
...     month=ExtractMonth('start_datetime'),
...     week=ExtractWeek('start_datetime'),
...     day=ExtractDay('start_datetime'),
...     weekday=ExtractWeekDay('start_datetime'),
...     isoweekday=ExtractIsoWeekDay('start_datetime'),
...     hour=ExtractHour('start_datetime'),
...     minute=ExtractMinute('start_datetime'),
...     second=ExtractSecond('start_datetime'),
... ).values(
...     'year', 'isoyear', 'month', 'week', 'day',
...     'weekday', 'isoweekday', 'hour', 'minute', 'second',
... ).get(end_datetime__year=ExtractYear('start_datetime'))
{'year': 2015, 'isoyear': 2015, 'quarter': 2, 'month': 6, 'week': 25,
 'day': 15, 'weekday': 2, 'isoweekday': 1, 'hour': 23, 'minute': 30,
 'second': 1}

>>> import pytz
>>> melb = pytz.timezone('Australia/Melbourne')  # UTC+10:00
>>> with timezone.override(melb):
...    Experiment.objects.annotate(
...        day=ExtractDay('start_datetime'),
...        weekday=ExtractWeekDay('start_datetime'),
...        isoweekday=ExtractIsoWeekDay('start_datetime'),
...        hour=ExtractHour('start_datetime'),
...    ).values('day', 'weekday', 'isoweekday', 'hour').get(
...        end_datetime__year=ExtractYear('start_datetime'),
...    )
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

>>> import pytz
>>> melb = pytz.timezone('Australia/Melbourne')
>>> Experiment.objects.annotate(
...     day=ExtractDay('start_datetime', tzinfo=melb),
...     weekday=ExtractWeekDay('start_datetime', tzinfo=melb),
...     isoweekday=ExtractIsoWeekDay('start_datetime', tzinfo=melb),
...     hour=ExtractHour('start_datetime', tzinfo=melb),
... ).values('day', 'weekday', 'isoweekday', 'hour').get(
...     end_datetime__year=ExtractYear('start_datetime'),
... )
{'day': 16, 'weekday': 3, 'isoweekday': 2, 'hour': 9}

Now¶

класс Now¶

Возвращает текущую дату и время сервера базы данных при выполнении запроса, обычно с использованием SQL CURRENT_TIMESTAMP.

Пример использования:

>>> from django.db.models.functions import Now
>>> Article.objects.filter(published__lte=Now())
<QuerySet [<Article: How to Django>]>

Trunc¶

classTrunc ( выражение , вид , output_field = None , tzinfo = None , is_dst = None , ** extra ) ¶

Усекает дату до значимого компонента.

Когда вас интересует только то, что произошло в конкретный год, час или день, но не точная секунда, тогда Trunc(и его подклассы) могут быть полезны для фильтрации или агрегирования ваших данных. Например, вы можете использовать Truncдля расчета количества продаж в день.

Truncпринимает один expression, представляющий собой DateField, TimeFieldили DateTimeField, kindпредставляющая дату или часть времени, и output_fieldэто либо DateTimeField(), TimeField()или DateField(). Он возвращает дату и время, дату или время в зависимости от того output_field, что для полей kindустановлено минимальное значение. Если output_fieldне указан, по умолчанию будет использоваться значение output_field of expression. tzinfoПодкласс, как правило , предусмотрено pytz, может быть передан усечь значение в конкретной временной зоне.

is_dstПараметр указывает , является ли pytzследует интерпретировать несуществующие и неоднозначные DateTimes в летнее время. По умолчанию (когда is_dst=None) pytzвызывает исключение для таких дат.

Учитывая дату и время, встроенный s возвращает:2015-06-15 14:30:50.000321+00:00kind

• «Год»: 2015-01-01 00: 00: 00 + 00: 00
• «Квартал»: 2015-04-01 00: 00: 00 + 00: 00
• «Месяц»: 2015-06-01 00: 00: 00 + 00: 00
• «Неделя»: 2015-06-15 00: 00: 00 + 00: 00
• «День»: 2015-06-15 00: 00: 00 + 00: 00
• «Час»: 2015-06-15 14: 00: 00 + 00: 00
• «Минута»: 2015-06-15 14: 30: 00 + 00: 00
• «Второй»: 2015-06-15 14: 30: 50 + 00: 00

Если Australia/Melbourneв Django активен другой часовой пояс, например , datetime преобразуется в новый часовой пояс перед усечением значения. Смещение часового пояса для Мельбурна в приведенном выше примере даты составляет +10: 00. Значения, возвращаемые, когда этот часовой пояс активен, будут:

• «Год»: 2015-01-01 00: 00: 00 + 11: 00
• «Квартал»: 2015-04-01 00: 00: 00 + 10: 00
• «Месяц»: 2015-06-01 00: 00: 00 + 10: 00
• «Неделя»: 2015-06-16 00: 00: 00 + 10: 00
• «День»: 2015-06-16 00: 00: 00 + 10: 00
• «Час»: 2015-06-16 00: 00: 00 + 10: 00
• «Минута»: 2015-06-16 00: 30: 00 + 10: 00
• «Второй»: 2015-06-16 00: 30: 50 + 10: 00

Год имеет смещение +11: 00, потому что результат перешел на летнее время.

У каждого из kindвышеперечисленных есть соответствующий Truncподкласс (перечисленный ниже), который обычно следует использовать вместо более подробного эквивалента, например, использовать TruncYear(...)вместо .Trunc(..., kind='year')

Все подклассы определены как преобразования, но они не зарегистрированы ни в каких полях, потому что имена поиска уже зарезервированы Extract подклассами.

Пример использования:

>>> from datetime import datetime
>>> from django.db.models import Count, DateTimeField
>>> from django.db.models.functions import Trunc
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 30, 50, 321))
>>> Experiment.objects.create(start_datetime=datetime(2015, 6, 15, 14, 40, 2, 123))
>>> Experiment.objects.create(start_datetime=datetime(2015, 12, 25, 10, 5, 27, 999))
>>> experiments_per_day = Experiment.objects.annotate(
...    start_day=Trunc('start_datetime', 'day', output_field=DateTimeField())
... ).values('start_day').annotate(experiments=Count('id'))
>>> for exp in experiments_per_day:
...     print(exp['start_day'], exp['experiments'])
...
2015-06-15 00:00:00 2
2015-12-25 00:00:00 1
>>> experiments = Experiment.objects.annotate(
...    start_day=Trunc('start_datetime', 'day', output_field=DateTimeField())
... ).filter(start_day=datetime(2015, 6, 15))
>>> for exp in experiments:
...     print(exp.start_datetime)
...
2015-06-15 14:30:50.000321
2015-06-15 14:40:02.000123

>>> from datetime import datetime
>>> from django.db.models import Count
>>> from django.db.models.functions import TruncMonth, TruncYear
>>> from django.utils import timezone
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())
>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())
>>> experiments_per_year = Experiment.objects.annotate(
...    year=TruncYear('start_date')).values('year').annotate(
...    experiments=Count('id'))
>>> for exp in experiments_per_year:
...     print(exp['year'], exp['experiments'])
...
2014-01-01 1
2015-01-01 2

>>> import pytz
>>> melb = pytz.timezone('Australia/Melbourne')
>>> experiments_per_month = Experiment.objects.annotate(
...    month=TruncMonth('start_datetime', tzinfo=melb)).values('month').annotate(
...    experiments=Count('id'))
>>> for exp in experiments_per_month:
...     print(exp['month'], exp['experiments'])
...
2015-06-01 00:00:00+10:00 1
2016-01-01 00:00:00+11:00 1
2014-06-01 00:00:00+10:00 1

>>> from datetime import date, datetime
>>> from django.db.models import Count
>>> from django.db.models.functions import (
...     TruncDate, TruncDay, TruncHour, TruncMinute, TruncSecond,
... )
>>> from django.utils import timezone
>>> import pytz
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> melb = pytz.timezone('Australia/Melbourne')
>>> Experiment.objects.annotate(
...     date=TruncDate('start_datetime'),
...     day=TruncDay('start_datetime', tzinfo=melb),
...     hour=TruncHour('start_datetime', tzinfo=melb),
...     minute=TruncMinute('start_datetime'),
...     second=TruncSecond('start_datetime'),
... ).values('date', 'day', 'hour', 'minute', 'second').get()
{'date': datetime.date(2014, 6, 15),
 'day': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=<DstTzInfo 'Australia/Melbourne' AEST+10:00:00 STD>),
 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=<DstTzInfo 'Australia/Melbourne' AEST+10:00:00 STD>),
 'minute': 'minute': datetime.datetime(2014, 6, 15, 14, 30, tzinfo=<UTC>),
 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=<UTC>)
}

>>> from datetime import datetime
>>> from django.db.models import Count, TimeField
>>> from django.db.models.functions import TruncHour
>>> from django.utils import timezone
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)
>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())
>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())
>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())
>>> experiments_per_hour = Experiment.objects.annotate(
...    hour=TruncHour('start_datetime', output_field=TimeField()),
... ).values('hour').annotate(experiments=Count('id'))
>>> for exp in experiments_per_hour:
...     print(exp['hour'], exp['experiments'])
...
14:00:00 2
17:00:00 1

>>> import pytz
>>> melb = pytz.timezone('Australia/Melbourne')
>>> experiments_per_hour = Experiment.objects.annotate(
...    hour=TruncHour('start_datetime', tzinfo=melb),
... ).values('hour').annotate(experiments=Count('id'))
>>> for exp in experiments_per_hour:
...     print(exp['hour'], exp['experiments'])
...
2014-06-16 00:00:00+10:00 2
2016-01-01 04:00:00+11:00 1

Abs¶

classAbs ( выражение , ** extra ) ¶

Возвращает абсолютное значение числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Abs
>>> Vector.objects.create(x=-0.5, y=1.1)
>>> vector = Vector.objects.annotate(x_abs=Abs('x'), y_abs=Abs('y')).get()
>>> vector.x_abs, vector.y_abs
(0.5, 1.1)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Abs
>>> FloatField.register_lookup(Abs)
>>> # Get vectors inside the unit cube
>>> vectors = Vector.objects.filter(x__abs__lt=1, y__abs__lt=1)

ACos¶

classACos ( выражение , ** extra ) ¶

Возвращает арккосинус числового поля или выражения. Значение выражения должно находиться в диапазоне от -1 до 1.

Пример использования:

>>> from django.db.models.functions import ACos
>>> Vector.objects.create(x=0.5, y=-0.9)
>>> vector = Vector.objects.annotate(x_acos=ACos('x'), y_acos=ACos('y')).get()
>>> vector.x_acos, vector.y_acos
(1.0471975511965979, 2.6905658417935308)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ACos
>>> FloatField.register_lookup(ACos)
>>> # Get vectors whose arccosine is less than 1
>>> vectors = Vector.objects.filter(x__acos__lt=1, y__acos__lt=1)

ASin¶

classASin ( выражение , ** extra ) ¶

Возвращает арксинус числового поля или выражения. Значение выражения должно быть в диапазоне от -1 до 1.

Пример использования:

>>> from django.db.models.functions import ASin
>>> Vector.objects.create(x=0, y=1)
>>> vector = Vector.objects.annotate(x_asin=ASin('x'), y_asin=ASin('y')).get()
>>> vector.x_asin, vector.y_asin
(0.0, 1.5707963267948966)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ASin
>>> FloatField.register_lookup(ASin)
>>> # Get vectors whose arcsine is less than 1
>>> vectors = Vector.objects.filter(x__asin__lt=1, y__asin__lt=1)

ATan¶

classATan ( выражение , ** extra ) ¶

Возвращает арктангенс числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import ATan
>>> Vector.objects.create(x=3.12, y=6.987)
>>> vector = Vector.objects.annotate(x_atan=ATan('x'), y_atan=ATan('y')).get()
>>> vector.x_atan, vector.y_atan
(1.2606282660069106, 1.428638798133829)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import ATan
>>> FloatField.register_lookup(ATan)
>>> # Get vectors whose arctangent is less than 2
>>> vectors = Vector.objects.filter(x__atan__lt=2, y__atan__lt=2)

ATan2¶

классATan2 ( выражение1 , выражение2 , ** дополнительно ) ¶

Возвращает арктангенс .expression1 / expression2

Пример использования:

>>> from django.db.models.functions import ATan2
>>> Vector.objects.create(x=2.5, y=1.9)
>>> vector = Vector.objects.annotate(atan2=ATan2('x', 'y')).get()
>>> vector.atan2
0.9209258773829491

Ceil¶

classCeil ( выражение , ** extra ) ¶

Возвращает наименьшее целое число, большее или равное числовому полю или выражению.

Пример использования:

>>> from django.db.models.functions import Ceil
>>> Vector.objects.create(x=3.12, y=7.0)
>>> vector = Vector.objects.annotate(x_ceil=Ceil('x'), y_ceil=Ceil('y')).get()
>>> vector.x_ceil, vector.y_ceil
(4.0, 7.0)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ceil
>>> FloatField.register_lookup(Ceil)
>>> # Get vectors whose ceil is less than 10
>>> vectors = Vector.objects.filter(x__ceil__lt=10, y__ceil__lt=10)

Cos¶

classCos ( выражение , ** extra ) ¶

Возвращает косинус числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Cos
>>> Vector.objects.create(x=-8.0, y=3.1415926)
>>> vector = Vector.objects.annotate(x_cos=Cos('x'), y_cos=Cos('y')).get()
>>> vector.x_cos, vector.y_cos
(-0.14550003380861354, -0.9999999999999986)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cos
>>> FloatField.register_lookup(Cos)
>>> # Get vectors whose cosine is less than 0.5
>>> vectors = Vector.objects.filter(x__cos__lt=0.5, y__cos__lt=0.5)

Cot¶

classCot ( выражение , ** extra ) ¶

Возвращает котангенс числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Cot
>>> Vector.objects.create(x=12.0, y=1.0)
>>> vector = Vector.objects.annotate(x_cot=Cot('x'), y_cot=Cot('y')).get()
>>> vector.x_cot, vector.y_cot
(-1.5726734063976826, 0.642092615934331)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Cot
>>> FloatField.register_lookup(Cot)
>>> # Get vectors whose cotangent is less than 1
>>> vectors = Vector.objects.filter(x__cot__lt=1, y__cot__lt=1)

Degrees¶

classDegrees ( выражение , ** extra ) ¶

Преобразует числовое поле или выражение из радиан в градусы.

Пример использования:

>>> from django.db.models.functions import Degrees
>>> Vector.objects.create(x=-1.57, y=3.14)
>>> vector = Vector.objects.annotate(x_d=Degrees('x'), y_d=Degrees('y')).get()
>>> vector.x_d, vector.y_d
(-89.95437383553924, 179.9087476710785)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Degrees
>>> FloatField.register_lookup(Degrees)
>>> # Get vectors whose degrees are less than 360
>>> vectors = Vector.objects.filter(x__degrees__lt=360, y__degrees__lt=360)

Exp¶

classExp ( выражение , ** extra ) ¶

Возвращает значение e(основание натурального логарифма), возведенное в степень числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Exp
>>> Vector.objects.create(x=5.4, y=-2.0)
>>> vector = Vector.objects.annotate(x_exp=Exp('x'), y_exp=Exp('y')).get()
>>> vector.x_exp, vector.y_exp
(221.40641620418717, 0.1353352832366127)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Exp
>>> FloatField.register_lookup(Exp)
>>> # Get vectors whose exp() is greater than 10
>>> vectors = Vector.objects.filter(x__exp__gt=10, y__exp__gt=10)

Floor¶

classFloor ( выражение , ** extra ) ¶

Возвращает наибольшее целочисленное значение, не превышающее числовое поле или выражение.

Пример использования:

>>> from django.db.models.functions import Floor
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_floor=Floor('x'), y_floor=Floor('y')).get()
>>> vector.x_floor, vector.y_floor
(5.0, -3.0)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Floor
>>> FloatField.register_lookup(Floor)
>>> # Get vectors whose floor() is greater than 10
>>> vectors = Vector.objects.filter(x__floor__gt=10, y__floor__gt=10)

Ln¶

classLn ( выражение , ** extra ) ¶

Возвращает натуральный логарифм числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Ln
>>> Vector.objects.create(x=5.4, y=233.0)
>>> vector = Vector.objects.annotate(x_ln=Ln('x'), y_ln=Ln('y')).get()
>>> vector.x_ln, vector.y_ln
(1.6863989535702288, 5.4510384535657)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Ln
>>> FloatField.register_lookup(Ln)
>>> # Get vectors whose value greater than e
>>> vectors = Vector.objects.filter(x__ln__gt=1, y__ln__gt=1)

Log¶

классLog ( выражение1 , выражение2 , ** дополнительно ) ¶

Принимает два числовых поля или выражения и возвращает логарифм первого числа по основанию второго.

Пример использования:

>>> from django.db.models.functions import Log
>>> Vector.objects.create(x=2.0, y=4.0)
>>> vector = Vector.objects.annotate(log=Log('x', 'y')).get()
>>> vector.log
2.0

Mod¶

классMod ( выражение1 , выражение2 , ** дополнительно ) ¶

Принимает два числовых поля или выражения и возвращает остаток от первого, деленный на второе (операция по модулю).

Пример использования:

>>> from django.db.models.functions import Mod
>>> Vector.objects.create(x=5.4, y=2.3)
>>> vector = Vector.objects.annotate(mod=Mod('x', 'y')).get()
>>> vector.mod
0.8

Pi¶

классPi ( ** экстра ) ¶

Возвращает значение математической константы π.

Power¶

классPower ( выражение1 , выражение2 , ** дополнительно ) ¶

Принимает два числовых поля или выражения и возвращает значение первого в степени второго.

Пример использования:

>>> from django.db.models.functions import Power
>>> Vector.objects.create(x=2, y=-2)
>>> vector = Vector.objects.annotate(power=Power('x', 'y')).get()
>>> vector.power
0.25

Radians¶

classRadians ( выражение , ** extra ) ¶

Преобразует числовое поле или выражение из градусов в радианы.

Пример использования:

>>> from django.db.models.functions import Radians
>>> Vector.objects.create(x=-90, y=180)
>>> vector = Vector.objects.annotate(x_r=Radians('x'), y_r=Radians('y')).get()
>>> vector.x_r, vector.y_r
(-1.5707963267948966, 3.141592653589793)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Radians
>>> FloatField.register_lookup(Radians)
>>> # Get vectors whose radians are less than 1
>>> vectors = Vector.objects.filter(x__radians__lt=1, y__radians__lt=1)

Random¶

классRandom ( ** экстра ) ¶

Возвращает случайное значение из диапазона .0.0 ≤ x < 1.0

Round¶

classRound ( выражение , ** extra ) ¶

Округляет числовое поле или выражение до ближайшего целого числа. Округление половинных значений в большую или меньшую сторону зависит от базы данных.

Пример использования:

>>> from django.db.models.functions import Round
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_r=Round('x'), y_r=Round('y')).get()
>>> vector.x_r, vector.y_r
(5.0, -2.0)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Round
>>> FloatField.register_lookup(Round)
>>> # Get vectors whose round() is less than 20
>>> vectors = Vector.objects.filter(x__round__lt=20, y__round__lt=20)

Sign¶

classSign ( выражение , ** extra ) ¶

Возвращает знак (-1, 0, 1) числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Sign
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sign=Sign('x'), y_sign=Sign('y')).get()
>>> vector.x_sign, vector.y_sign
(1, -1)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sign
>>> FloatField.register_lookup(Sign)
>>> # Get vectors whose signs of components are less than 0.
>>> vectors = Vector.objects.filter(x__sign__lt=0, y__sign__lt=0)

Sin¶

classSin ( выражение , ** extra ) ¶

Возвращает синус числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Sin
>>> Vector.objects.create(x=5.4, y=-2.3)
>>> vector = Vector.objects.annotate(x_sin=Sin('x'), y_sin=Sin('y')).get()
>>> vector.x_sin, vector.y_sin
(-0.7727644875559871, -0.7457052121767203)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sin
>>> FloatField.register_lookup(Sin)
>>> # Get vectors whose sin() is less than 0
>>> vectors = Vector.objects.filter(x__sin__lt=0, y__sin__lt=0)

Sqrt¶

classSqrt ( выражение , ** extra ) ¶

Возвращает квадратный корень из неотрицательного числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Sqrt
>>> Vector.objects.create(x=4.0, y=12.0)
>>> vector = Vector.objects.annotate(x_sqrt=Sqrt('x'), y_sqrt=Sqrt('y')).get()
>>> vector.x_sqrt, vector.y_sqrt
(2.0, 3.46410)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Sqrt
>>> FloatField.register_lookup(Sqrt)
>>> # Get vectors whose sqrt() is less than 5
>>> vectors = Vector.objects.filter(x__sqrt__lt=5, y__sqrt__lt=5)

Tan¶

classTan ( выражение , ** extra ) ¶

Возвращает тангенс числового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Tan
>>> Vector.objects.create(x=0, y=12)
>>> vector = Vector.objects.annotate(x_tan=Tan('x'), y_tan=Tan('y')).get()
>>> vector.x_tan, vector.y_tan
(0.0, -0.6358599286615808)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import FloatField
>>> from django.db.models.functions import Tan
>>> FloatField.register_lookup(Tan)
>>> # Get vectors whose tangent is less than 0
>>> vectors = Vector.objects.filter(x__tan__lt=0, y__tan__lt=0)

Chr¶

classChr ( выражение , ** extra ) ¶

Принимает числовое поле или выражение и возвращает текстовое представление выражения в виде одного символа. Работает так же, как chr() функция Python .

Мол Length, это можно прописать как трансформацию на IntegerField. Имя поиска по умолчанию - chr.

Пример использования:

>>> from django.db.models.functions import Chr
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.filter(name__startswith=Chr(ord('M'))).get()
>>> print(author.name)
Margaret Smith

Concat¶

классConcat ( * выражения , ** дополнительные ) ¶

Принимает список как минимум из двух текстовых полей или выражений и возвращает объединенный текст. Каждый аргумент должен иметь текстовый или символьный тип. Если вы хотите объединить a TextField()с a CharField(), обязательно сообщите Django, что это output_fieldдолжен быть файл TextField(). Указание output_fieldтакже требуется при конкатенации, Valueкак в примере ниже.

Эта функция никогда не будет иметь нулевого результата. В бэкэндах, где нулевой аргумент приводит к тому, что все выражение становится нулевым, Django гарантирует, что каждая пустая часть сначала будет преобразована в пустую строку.

Пример использования:

>>> # Get the display name as "name (goes_by)"
>>> from django.db.models import CharField, Value as V
>>> from django.db.models.functions import Concat
>>> Author.objects.create(name='Margaret Smith', goes_by='Maggie')
>>> author = Author.objects.annotate(
...     screen_name=Concat(
...         'name', V(' ('), 'goes_by', V(')'),
...         output_field=CharField()
...     )
... ).get()
>>> print(author.screen_name)
Margaret Smith (Maggie)

Left¶

классLeft ( выражение , длина , ** дополнительно ) ¶

Возвращает первые lengthсимволы заданного текстового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Left
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(first_initial=Left('name', 1)).get()
>>> print(author.first_initial)
M

Length¶

classLength ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает количество символов в значении. Если выражение имеет значение NULL, длина также будет равна NULL.

Пример использования:

>>> # Get the length of the name and goes_by fields
>>> from django.db.models.functions import Length
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(
...    name_length=Length('name'),
...    goes_by_length=Length('goes_by')).get()
>>> print(author.name_length, author.goes_by_length)
(14, None)

Его также можно зарегистрировать как преобразование. Например:

>>> from django.db.models import CharField
>>> from django.db.models.functions import Length
>>> CharField.register_lookup(Length)
>>> # Get authors whose name is longer than 7 characters
>>> authors = Author.objects.filter(name__length__gt=7)

Lower¶

classLower ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает его в нижнем регистре.

Его также можно зарегистрировать как преобразование, как описано в Length.

Пример использования:

>>> from django.db.models.functions import Lower
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(name_lower=Lower('name')).get()
>>> print(author.name_lower)
margaret smith

LPad¶

classLPad ( выражение , длина , fill_text = Value ('') , ** extra ) ¶

Возвращает значение заданного текстового поля или выражения, дополненное с левой стороны, fill_textчтобы результирующее значение состояло из lengthсимволов. По умолчанию fill_textэто пробел.

Пример использования:

>>> from django.db.models import Value
>>> from django.db.models.functions import LPad
>>> Author.objects.create(name='John', alias='j')
>>> Author.objects.update(name=LPad('name', 8, Value('abc')))
1
>>> print(Author.objects.get(alias='j').name)
abcaJohn

LTrim¶

classLTrim ( выражение , ** extra ) ¶

Аналогично Trim, но удаляет только начальные пробелы.

MD5¶

classMD5 ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает хеш-код строки MD5.

Его также можно зарегистрировать как преобразование, как описано в Length.

Пример использования:

>>> from django.db.models.functions import MD5
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(name_md5=MD5('name')).get()
>>> print(author.name_md5)
749fb689816b2db85f5b169c2055b247

Ord¶

classOrd ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает значение кодовой точки Unicode для первого символа этого выражения. Он работает аналогично ord()функции Python , но исключение не возникает, если выражение содержит более одного символа.

Его также можно зарегистрировать как преобразование, как описано в Length. Имя поиска по умолчанию - ord.

Пример использования:

>>> from django.db.models.functions import Ord
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(name_code_point=Ord('name')).get()
>>> print(author.name_code_point)
77

Repeat¶

классRepeat ( выражение , число , ** экстра ) ¶

Возвращает значение заданного текстового поля или выражения, повторяющееся несколько number раз.

Пример использования:

>>> from django.db.models.functions import Repeat
>>> Author.objects.create(name='John', alias='j')
>>> Author.objects.update(name=Repeat('name', 3))
1
>>> print(Author.objects.get(alias='j').name)
JohnJohnJohn

Replace¶

classReplace ( выражение , текст , замена = значение ('') , ** дополнительно ) ¶

Заменяет все вхождения textс replacementв expression. Текст замены по умолчанию - пустая строка. Аргументы функции чувствительны к регистру.

Пример использования:

>>> from django.db.models import Value
>>> from django.db.models.functions import Replace
>>> Author.objects.create(name='Margaret Johnson')
>>> Author.objects.create(name='Margaret Smith')
>>> Author.objects.update(name=Replace('name', Value('Margaret'), Value('Margareth')))
2
>>> Author.objects.values('name')
<QuerySet [{'name': 'Margareth Johnson'}, {'name': 'Margareth Smith'}]>

Reverse¶

classReverse ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает символы этого выражения в обратном порядке.

Его также можно зарегистрировать как преобразование, как описано в Length. Имя поиска по умолчанию - reverse.

Пример использования:

>>> from django.db.models.functions import Reverse
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(backward=Reverse('name')).get()
>>> print(author.backward)
htimS teragraM

Right¶

классRight ( выражение , длина , ** дополнительно ) ¶

Возвращает последние lengthсимволы заданного текстового поля или выражения.

Пример использования:

>>> from django.db.models.functions import Right
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(last_letter=Right('name', 1)).get()
>>> print(author.last_letter)
h

RPad¶

classRPad ( выражение , длина , fill_text = Value ('') , ** extra ) ¶

Аналогично LPad, но колодки с правой стороны.

RTrim¶

classRTrim ( выражение , ** extra ) ¶

Аналогично Trim, но удаляет только конечные пробелы.

SHA1, SHA224, SHA256, SHA384, И SHA512¶

classSHA1 ( выражение , ** extra ) ¶

classSHA224 ( выражение , ** extra ) ¶

classSHA256 ( выражение , ** extra ) ¶

classSHA384 ( выражение , ** extra ) ¶

classSHA512 ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает конкретный хэш строки.

Их также можно зарегистрировать как преобразования, как описано в Length.

Пример использования:

>>> from django.db.models.functions import SHA1
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(name_sha1=SHA1('name')).get()
>>> print(author.name_sha1)
b87efd8a6c991c390be5a68e8a7945a7851c7e5c

StrIndex¶

классStrIndex ( строка , подстрока , ** дополнительно ) ¶

Возвращает положительное целое число, соответствующее позиции с индексом 1 первого вхождения substringinside string, или 0, если substringне найдено.

Пример использования:

>>> from django.db.models import Value as V
>>> from django.db.models.functions import StrIndex
>>> Author.objects.create(name='Margaret Smith')
>>> Author.objects.create(name='Smith, Margaret')
>>> Author.objects.create(name='Margaret Jackson')
>>> Author.objects.filter(name='Margaret Jackson').annotate(
...     smith_index=StrIndex('name', V('Smith'))
... ).get().smith_index
0
>>> authors = Author.objects.annotate(
...    smith_index=StrIndex('name', V('Smith'))
... ).filter(smith_index__gt=0)
<QuerySet [<Author: Margaret Smith>, <Author: Smith, Margaret>]>

Substr¶

classSubstr ( выражение , pos , length = None , ** extra ) ¶

Возвращает подстроку длины lengthиз поля или выражения, начиная с позиции pos. Позиция имеет индекс 1, поэтому позиция должна быть больше 0. Если lengthесть None, то будет возвращена остальная часть строки.

Пример использования:

>>> # Set the alias to the first 5 characters of the name as lowercase
>>> from django.db.models.functions import Lower, Substr
>>> Author.objects.create(name='Margaret Smith')
>>> Author.objects.update(alias=Lower(Substr('name', 1, 5)))
1
>>> print(Author.objects.get(name='Margaret Smith').alias)
marga

Trim¶

classTrim ( выражение , ** extra ) ¶

Возвращает значение заданного текстового поля или выражения без начальных и конечных пробелов.

Пример использования:

>>> from django.db.models.functions import Trim
>>> Author.objects.create(name='  John  ', alias='j')
>>> Author.objects.update(name=Trim('name'))
1
>>> print(Author.objects.get(alias='j').name)
John

Upper¶

classUpper ( выражение , ** extra ) ¶

Принимает одно текстовое поле или выражение и возвращает его представление в верхнем регистре.

Его также можно зарегистрировать как преобразование, как описано в Length.

Пример использования:

>>> from django.db.models.functions import Upper
>>> Author.objects.create(name='Margaret Smith')
>>> author = Author.objects.annotate(name_upper=Upper('name')).get()
>>> print(author.name_upper)
MARGARET SMITH

CumeDist¶

классCumeDist ( * выражения , ** дополнительные ) ¶

Вычисляет совокупное распределение значения в окне или разделе. Совокупное распределение определяется как количество строк, предшествующих текущей строке или связанных с ней, деленное на общее количество строк в кадре.

DenseRank¶

классDenseRank ( * выражения , ** дополнительные ) ¶

Эквивалентен, Rankно не имеет пробелов.

FirstValue¶

classFirstValue ( выражение , ** extra ) ¶

Возвращает значение, вычисленное в строке, которая является первой строкой рамки окна, или Noneесли такого значения не существует.

Lag¶

classLag ( выражение , смещение = 1 , по умолчанию = None , ** extra ) ¶

Вычисляет значение, смещенное на offset, и, если там нет строки, возвращает default.

defaultдолжен иметь тот же тип, что и expression, однако, это проверяется только базой данных, а не в Python.

LastValue¶

classLastValue ( выражение , ** extra ) ¶

По сравнению с FirstValue, он вычисляет последнее значение в данном предложении кадра.

Lead¶

classLead ( выражение , смещение = 1 , по умолчанию = None , ** extra ) ¶

Вычисляет значение интерлиньяжа в заданном кадре . Оба offsetи defaultоцениваются относительно текущей строки.

defaultдолжен иметь тот же тип, что и expression, однако, это проверяется только базой данных, а не в Python.

NthValue¶

classNthValue ( выражение , nth = 1 , ** extra ) ¶

Вычисляет строку относительно смещения nth(должно быть положительным значением) внутри окна. Возвращает, Noneесли строки не существует.

Некоторые базы данных могут по-разному обрабатывать несуществующее n-е значение. Например, Oracle возвращает пустую строку, а не Noneсимвольные выражения. В этих случаях Django не выполняет никаких преобразований.

Ntile¶

классNtile ( num_buckets = 1 , ** дополнительно ) ¶

Вычисляет раздел для каждой строки в предложении кадра, распределяя числа как можно более равномерно между 1 и num_buckets. Если строки не делятся равномерно на несколько сегментов, одно или несколько сегментов будут представлены чаще.

PercentRank¶

классPercentRank ( * выражения , ** дополнительные ) ¶

Вычисляет процентильный ранг строк в предложении кадра. Это вычисление эквивалентно оценке:

(rank - 1) / (total rows - 1)

В следующей таблице объясняется расчет процентильного ранга строки:

Rank¶

классRank ( * выражения , ** дополнительные ) ¶

По сравнению с RowNumber, эта функция ранжирует строки в окне. Вычисленный ранг содержит пробелы. Используется DenseRankдля вычисления ранга без пробелов.

RowNumber¶

классRowNumber ( * выражения , ** дополнительные ) ¶

Вычисляет номер строки в соответствии с порядком предложения фрейма или всего запроса, если оконный фрейм не разбит на части .