{"title":"Fonctions de base de données","version":"2.0","locale":"fr","docname":"ref/models/database-functions","url":"/fr/2.0/ref/models/database-functions/","canonical":"https://djangodocs.dev/fr/2.0/ref/models/database-functions/","summary":"Les classes documentées ci-dessous permettent d’exploiter dans Django les fonctions fournies par la base de données sous-jacente telles que les annotations…","html":"

Fonctions de base de donnéesLien vers cette rubrique#

\n

Les classes documentées ci-dessous permettent d’exploiter dans Django les fonctions fournies par la base de données sous-jacente telles que les annotations, les agrégations ou les filtres. Les fonctions sont également des expressions, elles peuvent donc être utilisées et combinées avec d’autres expressions comme les fonctions d’agrégation.

\n

Nous allons utiliser le modèle suivant dans les exemples de chaque fonction :

\n
Code
class Author(models.Model):\n    name = models.CharField(max_length=50)\n    age = models.PositiveIntegerField(null=True, blank=True)\n    alias = models.CharField(max_length=50, null=True, blank=True)\n    goes_by = models.CharField(max_length=50, null=True, blank=True)\n
\n

Nous ne recommandons généralement pas de définir null=True pour les champs CharField car cela permet au champ de posséder deux valeurs « vides » différentes, mais nous l’utilisons ici pour l’exemple Coalesce ci-dessous.

\n
\n

Fonctions de comparaison et de conversionLien vers cette rubrique#

\n
\n

CastLien vers cette rubrique#

\n
\n
\nclass Cast(expression, output_field)Lien vers cette définition#
\n
\n\n

Force le type de résultat de expression à celui de output_field.

\n

Exemple d’utilisation :

\n
Code
>>> from django.db.models import FloatField\n>>> from django.db.models.functions import Cast\n>>> Value.objects.create(integer=4)\n>>> value = Value.objects.annotate(as_float=Cast('integer', FloatField())).get()\n>>> print(value.as_float)\n4.0\n
\n
\n
\n

CoalesceLien vers cette rubrique#

\n
\n
\nclass Coalesce(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Accepte une liste d’au moins deux noms de champ ou expressions et renvoie la première valeur non nulle (notez qu’une chaîne vide n’est pas considérée comme une valeur nulle). Chaque paramètre doit être d’un type similaire ; si vous mélangez des textes et des nombres, la base de données produira une erreur.

\n

Exemples d’utilisation :

\n
Code
>>> # Get a screen name from least to most public\n>>> from django.db.models import Sum, Value as V\n>>> from django.db.models.functions import Coalesce\n>>> Author.objects.create(name='Margaret Smith', goes_by='Maggie')\n>>> author = Author.objects.annotate(\n...    screen_name=Coalesce('alias', 'goes_by', 'name')).get()\n>>> print(author.screen_name)\nMaggie\n\n>>> # Prevent an aggregate Sum() from returning None\n>>> aggregated = Author.objects.aggregate(\n...    combined_age=Coalesce(Sum('age'), V(0)),\n...    combined_age_default=Sum('age'))\n>>> print(aggregated['combined_age'])\n0\n>>> print(aggregated['combined_age_default'])\nNone\n
\n\n
\n
\n

GreatestLien vers cette rubrique#

\n
\n
\nclass Greatest(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Accepte une liste d’au moins deux noms de champ ou expressions et renvoie la plus grande valeur. Chaque paramètre doit être d’un type similaire ; si vous mélangez des textes et des nombres, la base de données produira une erreur.

\n

Exemple d’utilisation :

\n
Code
class Blog(models.Model):\n    body = models.TextField()\n    modified = models.DateTimeField(auto_now=True)\n\nclass Comment(models.Model):\n    body = models.TextField()\n    modified = models.DateTimeField(auto_now=True)\n    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n\n>>> from django.db.models.functions import Greatest\n>>> blog = Blog.objects.create(body='Greatest is the best.')\n>>> comment = Comment.objects.create(body='No, Least is better.', blog=blog)\n>>> comments = Comment.objects.annotate(last_updated=Greatest('modified', 'blog__modified'))\n>>> annotated_comment = comments.get()\n
\n

annotated_comment.last_updated sera la valeur la plus récente entre blog.modified et comment.modified.

\n\n
\n
\n

LeastLien vers cette rubrique#

\n
\n
\nclass Least(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Accepte une liste d’au moins deux noms de champ ou expressions et renvoie la plus petite valeur. Chaque paramètre doit être d’un type similaire ; si vous mélangez des textes et des nombres, la base de données produira une erreur.

\n\n
\n
\n
\n

Fonctions de dateLien vers cette rubrique#

\n

Nous allons utiliser le modèle suivant dans les exemples de chaque fonction :

\n
Code
class Experiment(models.Model):\n    start_datetime = models.DateTimeField()\n    start_date = models.DateField(null=True, blank=True)\n    start_time = models.TimeField(null=True, blank=True)\n    end_datetime = models.DateTimeField(null=True, blank=True)\n    end_date = models.DateField(null=True, blank=True)\n    end_time = models.TimeField(null=True, blank=True)\n
\n
\n

ExtractLien vers cette rubrique#

\n
\n
\nclass Extract(expression, lookup_name=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n\n

Extrait un composant de date sous forme de nombre.

\n

Accepte une expression représentant un champ DateField, DateTimeField, TimeField ou DurationField ainsi qu’un nom d’expression lookup_name, et renvoie la partie de date référencée par lookup_name sous forme de champ IntegerField. Django utilise habituellement la fonction d’extraction des bases de données, il est donc possible d’utiliser n’importe quel nom lookup_name pris en charge par la base de données en cours. Il est possible de passer aussi une sous-classe de tzinfo, habituellement fournie par pytz, pour extraire une valeur dans un fuseau horaire spécifique.

\n\n

Étant donnée la date/heure 2015-06-15 23:30:01.000321+00:00, les valeurs lookup_name possibles renvoient :

\n\n

Si un fuseau horaire différent comme Australia/Melbourne est actif dans Django, la date/heure est convertie dans le fuseau avant que la valeur soit extraite. Le décalage horaire de Melbourne dans la date d’exemple ci-dessus est +10:00. Les valeurs renvoyées lorsque ce fuseau est actif seront les mêmes que ci-dessus, à l’exception de :

\n\n\n\n

Chaque valeur lookup_name ci-dessus possède une sous-classe de Extract correspondante (énumérées ci-dessous) qui devrait être utilisée au lieu de l’équivalent plus bavard, c’est-à-dire ExtractYear(...) au lieu de Extract(..., lookup_name='year').

\n

Exemple d’utilisation :

\n
Code
>>> from datetime import datetime\n>>> from django.db.models.functions import Extract\n>>> start = datetime(2015, 6, 15)\n>>> end = datetime(2015, 7, 2)\n>>> Experiment.objects.create(\n...    start_datetime=start, start_date=start.date(),\n...    end_datetime=end, end_date=end.date())\n>>> # Add the experiment start year as a field in the QuerySet.\n>>> experiment = Experiment.objects.annotate(\n...    start_year=Extract('start_datetime', 'year')).get()\n>>> experiment.start_year\n2015\n>>> # How many experiments completed in the same year in which they started?\n>>> Experiment.objects.filter(\n...    start_datetime__year=Extract('end_datetime', 'year')).count()\n1\n
\n
\n

Extractions DateFieldLien vers cette rubrique#

\n
\n
\nclass ExtractYear(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'year'
\n
\n\n
\n\n
\n
\nclass ExtractMonth(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'month'
\n
\n\n
\n\n
\n
\nclass ExtractDay(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'day'
\n
\n\n
\n\n
\n
\nclass ExtractWeekDay(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'week_day'
\n
\n\n
\n\n
\n
\nclass ExtractWeek(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\n
\nlookup_name = 'week'
\n
\n\n
\n\n
\n
\nclass ExtractQuarter(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\n
\nlookup_name = 'quarter'
\n
\n\n
\n\n

Il s’agit d’équivalents logiques à Extract('champ_date', lookup_name). Chaque classe est aussi une classe Transform inscrite pour les champs DateField et DateTimeField comme __(lookup_name), par ex. __year.

\n

Comme les champs DateField n’ont pas de composant d’heure, seules les sous-classes de Extract qui s’appliquent aux parties de date peuvent être utilisées avec DateField:

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

Extractions DateTimeFieldLien vers cette rubrique#

\n

En plus de ce qui suit, toutes les extractions pour DateField énumérées ci-dessus peuvent aussi être utilisées pour DateTimeField.

\n
\n
\nclass ExtractHour(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'hour'
\n
\n\n
\n\n
\n
\nclass ExtractMinute(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'minute'
\n
\n\n
\n\n
\n
\nclass ExtractSecond(expression, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'second'
\n
\n\n
\n\n

Il s’agit d’équivalents logiques à Extract('champ_datetime', lookup_name). Chaque classe est aussi une classe Transform inscrite pour le champ DateTimeField comme __(lookup_name), par ex. __minute.

\n

Exemples DateTimeField:

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

Lorsque USE_TZ vaut True, les dates/heures sont stockées en UTC dans la base de données. Si un autre fuseau horaire est actif dans Django, la date/heure est convertie dans ce fuseau avant que la valeur soit extraite. L’exemple ci-dessous convertit dans le fuseau horaire de Melbourne (UTC +10:00), ce qui modifie les valeurs du jour, du jour de la semaine et de l’heure qui sont renvoyées :

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

Le passage explicite du fuseau horaire à la fonction Extract fonctionne de la même manière et prend la priorité sur le fuseau horaire actif :

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

NowLien vers cette rubrique#

\n
\n
\nclass NowLien vers cette définition#
\n
\n\n

Renvoie la date et l’heure courante du serveur de base de données au moment où la requête est exécutée, typiquement en utilisant le code SQL CURRENT_TIMESTAMP.

\n

Exemple d’utilisation :

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

TruncLien vers cette rubrique#

\n
\n
\nclass Trunc(expression, kind, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n\n

Tronque une date jusqu’à un composant significatif.

\n

Lorsque vous ne voulez que savoir si quelque chose s’est produit durant une année, une heure ou un jour particulier, mais pas à quelle seconde, Trunc (et ses sous-classes) peut être utile pour filtrer ou agréger vos données. Par exemple, vous pouvez utiliser Trunc pour calculer le nombre de ventes par jour.

\n

Trunc accepte une seule expression, représentant un champ DateField, TimeField ou DateTimeField, une variable kind représentant une partie de date ou d’heure et un champ output_field qui vaut DateTimeField(), TimeField()` ou DateField(). Elle renvoie une date, une heure ou une date/heure en fonction de output_field, avec les champs jusqu’à kind définis à leur valeur minimale. Si output_field est omis, la valeur par défaut sera le type output_field de expression. Il est possible de passer aussi une sous-classe de tzinfo, habituellement fournie par pytz, pour tronquer une valeur dans un fuseau horaire spécifique.

\n

Étant donnée la date/heure 2015-06-15 14:30:50.000321+00:00, les valeurs kind possibles renvoient :

\n\n

Si un fuseau horaire différent comme Australia/Melbourne est actif dans Django, la date/heure est convertie dans le nouveau fuseau avant que la valeur soit tronquée. Le décalage horaire de Melbourne dans la date d’exemple ci-dessus est +10:00. Les valeurs renvoyées lorsque ce fuseau est actif seront :

\n\n

L’année présente un décalage de +11:00 parce que le résultat traverse un passage à l’heure d’été.

\n

Chaque valeur kind ci-dessus possède une sous-classe de Trunc correspondante (énumérées ci-dessous) qui devrait être utilisée au lieu de l’équivalent plus bavard, c’est-à-dire TruncYear(...) au lieu de Trunc(..., kind='year').

\n

Les sous-classes sont toutes définies comme des transformations, mais elles ne sont inscrites pour aucun champ, car les noms de requête qui s’imposent sont déjà réservés par les sous-classes de Extract.

\n

Exemple d’utilisation :

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

Troncature de DateFieldLien vers cette rubrique#

\n
\n
\nclass TruncYear(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'year'
\n
\n\n
\n\n
\n
\nclass TruncMonth(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'month'
\n
\n\n
\n\n
\n
\nclass TruncQuarter(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\n
\nkind = 'quarter'
\n
\n\n
\n\n

Ce sont des équivalences logiques à Trunc('champ_date', kind). Elles tronquent toutes les parties de la date jusqu’à kind, ce qui permet de grouper ou de filtrer des dates avec une plus faible précision. expression peut avoir une valeur output_field de DateField ou de DateTimeField.

\n

Comme les champs DateField n’ont pas de composant d’heure, seules les sous-classes de Trunc qui s’appliquent aux parties de date peuvent être utilisées avec DateField:

\n
Code
>>> from datetime import datetime\n>>> from django.db.models import Count\n>>> from django.db.models.functions import TruncMonth, TruncYear\n>>> from django.utils import timezone\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)\n>>> start2 = datetime(2015, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)\n>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())\n>>> Experiment.objects.create(start_datetime=start2, start_date=start2.date())\n>>> Experiment.objects.create(start_datetime=start3, start_date=start3.date())\n>>> experiments_per_year = Experiment.objects.annotate(\n...    year=TruncYear('start_date')).values('year').annotate(\n...    experiments=Count('id'))\n>>> for exp in experiments_per_year:\n...     print(exp['year'], exp['experiments'])\n...\n2014-01-01 1\n2015-01-01 2\n\n>>> import pytz\n>>> melb = pytz.timezone('Australia/Melbourne')\n>>> experiments_per_month = Experiment.objects.annotate(\n...    month=TruncMonth('start_datetime', tzinfo=melb)).values('month').annotate(\n...    experiments=Count('id'))\n>>> for exp in experiments_per_month:\n...     print(exp['month'], exp['experiments'])\n...\n2015-06-01 00:00:00+10:00 1\n2016-01-01 00:00:00+11:00 1\n2014-06-01 00:00:00+10:00 1\n
\n
\n
\n

Troncature de DateTimeFieldLien vers cette rubrique#

\n
\n
\nclass TruncDate(expression, **extra)Lien vers cette définition#
\n
\n
\nlookup_name = 'date'
\n
\n\n
\n
\noutput_field = DateField()
\n
\n\n
\n\n

TruncDate force le type de expression à une date plutôt que d’utiliser l’instruction SQL de troncature. Elle est aussi inscrite comme transformation pour DateTimeField sous la forme __date.

\n
\n
\nclass TruncTime(expression, **extra)Lien vers cette définition#
\n
\n\n\n

TruncTime force le type de expression à une heure plutôt que d’utiliser l’instruction SQL de troncature. Elle est aussi inscrite comme transformation pour DateTimeField sous la forme __time.

\n
\n
\nclass TruncDay(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'day'
\n
\n\n
\n\n
\n
\nclass TruncHour(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'hour'
\n
\n\n
\n\n
\n
\nclass TruncMinute(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'minute'
\n
\n\n
\n\n
\n
\nclass TruncSecond(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'second'
\n
\n\n
\n\n

Ce sont des équivalences logiques à Trunc('champ_dateheure', kind). Elles tronquent toutes les parties de la date jusqu’à kind, ce qui permet de grouper ou de filtrer des dates/heures avec une plus faible précision. expression doit avoir une valeur output_field de DateTimeField.

\n

Exemple d’utilisation :

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

Troncature de TimeFieldLien vers cette rubrique#

\n\n
\n
\nclass TruncHour(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'hour'
\n
\n\n
\n\n
\n
\nclass TruncMinute(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'minute'
\n
\n\n
\n\n
\n
\nclass TruncSecond(expression, output_field=None, tzinfo=None, **extra)Lien vers cette définition#
\n
\n
\nkind = 'second'
\n
\n\n
\n\n

Ce sont des équivalences logiques à Trunc('champ_heure', kind). Elles tronquent toutes les parties de l’heure jusqu’à kind, ce qui permet de grouper ou de filtrer des heures avec une plus faible précision. expression peut avoir une valeur output_field de TimeField ou de DateTimeField.

\n

Comme les champs TimeField n’ont pas de composant de date, seules les sous-classes de Trunc qui s’appliquent aux parties d’heure peuvent être utilisées avec TimeField:

\n
Code
>>> from datetime import datetime\n>>> from django.db.models import Count, TimeField\n>>> from django.db.models.functions import TruncHour\n>>> from django.utils import timezone\n>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)\n>>> start2 = datetime(2014, 6, 15, 14, 40, 2, 123, tzinfo=timezone.utc)\n>>> start3 = datetime(2015, 12, 31, 17, 5, 27, 999, tzinfo=timezone.utc)\n>>> Experiment.objects.create(start_datetime=start1, start_time=start1.time())\n>>> Experiment.objects.create(start_datetime=start2, start_time=start2.time())\n>>> Experiment.objects.create(start_datetime=start3, start_time=start3.time())\n>>> experiments_per_hour = Experiment.objects.annotate(\n...    hour=TruncHour('start_datetime', output_field=TimeField()),\n... ).values('hour').annotate(experiments=Count('id'))\n>>> for exp in experiments_per_hour:\n...     print(exp['hour'], exp['experiments'])\n...\n14:00:00 2\n17:00:00 1\n\n>>> import pytz\n>>> melb = pytz.timezone('Australia/Melbourne')\n>>> experiments_per_hour = Experiment.objects.annotate(\n...    hour=TruncHour('start_datetime', tzinfo=melb),\n... ).values('hour').annotate(experiments=Count('id'))\n>>> for exp in experiments_per_hour:\n...     print(exp['hour'], exp['experiments'])\n...\n2014-06-16 00:00:00+10:00 2\n2016-01-01 04:00:00+11:00 1\n
\n
\n
\n
\n
\n

Fonctions textuellesLien vers cette rubrique#

\n
\n

ConcatLien vers cette rubrique#

\n
\n
\nclass Concat(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Accepte une liste d’au moins deux champs textes ou expressions et renvoie la concaténation de ces paramètres. Chaque paramètre doit être de type texte ou caractère. Si vous voulez concaténer un champ TextField() avec un champ CharField(), prenez alors la précaution d’indiquer à Django que le résultat output_field sera un champ TextField(). C’est aussi nécessaire lors de la concaténation avec une valeur Value comme dans l’exemple ci-dessous.

\n

Le résultat de cette fonction n’est jamais nul. Pour les moteurs où un paramètre nul aboutit à ce que toute l’expression devienne nulle, Django s’assure que chaque partie nulle est préalablement convertie en chaîne vide.

\n

Exemple d’utilisation :

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

LengthLien vers cette rubrique#

\n
\n
\nclass Length(expression, **extra)Lien vers cette définition#
\n
\n\n

Accepte un champ texte ou une expression unique et renvoie le nombre de caractères de la valeur. Si l’expression est nulle, la longueur renvoyée sera également nulle.

\n

Exemple d’utilisation :

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

Cette expression peut aussi être inscrite comme transformation. Par exemple :

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

LowerLien vers cette rubrique#

\n
\n
\nclass Lower(expression, **extra)Lien vers cette définition#
\n
\n\n

Accepte un champ texte ou une expression unique et renvoie sa représentation en minuscules.

\n

Cette expression peut aussi être inscrite comme transformation comme expliqué pour Length.

\n

Exemple d’utilisation :

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

StrIndexLien vers cette rubrique#

\n
\n
\nclass StrIndex(string, substring, **extra)Lien vers cette définition#
\n
\n\n\n

Renvoie un nombre entier positif correspondant à la position indicée (commençant à 1) de la première occurrence de substring dans string, ou 0 si substring est introuvable.

\n

Exemple d’utilisation :

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

SubstrLien vers cette rubrique#

\n
\n
\nclass Substr(expression, pos, length=None, **extra)Lien vers cette définition#
\n
\n\n

Renvoie une sous-chaîne de longueur length extraite du champ ou de l’expression à partir de la position pos. L’indice de position commence à 1, il doit donc être plus grand que 0. Si length vaut None, tout le reste de la chaîne est renvoyé comme résultat.

\n

Exemple d’utilisation :

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

UpperLien vers cette rubrique#

\n
\n
\nclass Upper(expression, **extra)Lien vers cette définition#
\n
\n\n

Accepte un champ texte ou une expression unique et renvoie sa représentation en majuscules.

\n

Cette expression peut aussi être inscrite comme transformation comme expliqué pour Length.

\n

Exemple d’utilisation :

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

Fonctions de fenêtrageLien vers cette rubrique#

\n\n

Il existe un certain nombre de fonctions à utiliser dans une expression Window pour calculer la position des éléments ou le Ntile de certaines lignes.

\n
\n

CumeDistLien vers cette rubrique#

\n
\n
\nclass CumeDist(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Calcule la distribution cumulative d’une valeur à l’intérieur d’une fenêtre ou d’une partition. La distribution cumulative est définie comme le nombre de lignes précédant ou apparentées à la ligne actuelle divisé par le nombre total de lignes dans l’intervalle.

\n
\n
\n

DenseRankLien vers cette rubrique#

\n
\n
\nclass DenseRank(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Équivalent à Rank mais sans « trous ».

\n
\n
\n

FirstValueLien vers cette rubrique#

\n
\n
\nclass FirstValue(expression, **extra)Lien vers cette définition#
\n
\n\n

Renvoie la valeur évaluée à la ligne se situant en premier dans l’intervalle de fenêtre, ou None si une telle valeur n’existe pas.

\n
\n
\n

LagLien vers cette rubrique#

\n
\n
\nclass Lag(expression, offset=1, default=None, **extra)Lien vers cette définition#
\n
\n\n

Calcule le décalage de valeur selon offset, et si aucune ligne n’existe à cet endroit, renvoie default.

\n

default doit avoir le même type que expression; cependant, cette validation se fait dans la base de données et pas dans le code Python.

\n
\n
\n

LastValueLien vers cette rubrique#

\n
\n
\nclass LastValue(expression, **extra)Lien vers cette définition#
\n
\n\n

Comparable à FirstValue, renvoie la dernière valeur dans une clause d’intervalle donnée.

\n
\n
\n

LeadLien vers cette rubrique#

\n
\n
\nclass Lead(expression, offset=1, default=None, **extra)Lien vers cette définition#
\n
\n\n

Calcule la valeur de tête dans un intervalle donné. offset et default sont tous deux évalués en fonction de la ligne actuelle.

\n

default doit avoir le même type que expression; cependant, cette validation se fait dans la base de données et pas dans le code Python.

\n
\n
\n

NthValueLien vers cette rubrique#

\n
\n
\nclass NthValue(expression, nth=1, **extra)Lien vers cette définition#
\n
\n\n

Calcule la ligne relative au décalage nth (la valeur doit être positive) à l’intérieur de la fenêtre. Renvoie None si aucune ligne ne correspond.

\n

Certaines bases de données gèrent différemment une nième valeur inexistante. Par exemple, Oracle renvoie une chaîne vide au lieu de None pour les expressions basées sur des caractères. Django n’applique aucune conversion dans ces cas.

\n
\n
\n

NtileLien vers cette rubrique#

\n
\n
\nclass Ntile(num_buckets=1, **extra)Lien vers cette définition#
\n
\n\n

Calcule une partition pour chacune des lignes dans la clause d’intervalle, distribuant les nombres aussi également que possible entre 1 et num_buckets. Si les lignes ne sont pas divisibles de manière égale par le nombre de « buckets », un ou plusieurs de ceux-ci seront représentés plus fréquemment.

\n
\n
\n

PercentRankLien vers cette rubrique#

\n
\n
\nclass PercentRank(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Calcule le rang de centile des lignes dans la clause d’intervalle. Ce calcul est équivalent à l’évaluation de

\n
Code
(rank - 1) / (total rows - 1)\n
\n

Le tableau suivant explique le calcul du rang de centile d’une ligne :

\n
\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n\n

N° de ligne

Valeur

Rang

Calcul

Rang en pourcentage

1

15

1

(1-1)/(7-1)

0.0000

2

20

2

(2-1)/(7-1)

0.1666

3

20

2

(2-1)/(7-1)

0.1666

4

20

2

(2-1)/(7-1)

0.1666

5

30

5

(5-1)/(7-1)

0.6666

6

30

5

(5-1)/(7-1)

0.6666

7

40

7

(7-1)/(7-1)

1.0000

\n
\n
\n
\n

RankLien vers cette rubrique#

\n
\n
\nclass Rank(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Comparable à RowNumber, cette fonction calcule le rang des lignes de la fenêtre. Le rang calculé comporte des trous. Utilisez DenseRank pour calculer le rang sans trous.

\n
\n
\n

RowNumberLien vers cette rubrique#

\n
\n
\nclass RowNumber(*expressions, **extra)Lien vers cette définition#
\n
\n\n

Calcule le numéro de ligne selon le tri de la clause d’intervalle ou selon le tri de toute la requête s’il n’y a pas partition dans l”intervalle de fenêtre.

\n
\n
","rootId":"module-django.db.models.functions","toc":[{"title":"Fonctions de comparaison et de conversion","anchor":"comparison-and-conversion-functions","children":[{"title":"Cast","anchor":"cast","children":[]},{"title":"Coalesce","anchor":"coalesce","children":[]},{"title":"Greatest","anchor":"greatest","children":[]},{"title":"Least","anchor":"least","children":[]}]},{"title":"Fonctions de date","anchor":"date-functions","children":[{"title":"Extract","anchor":"extract","children":[{"title":"Extractions DateField","anchor":"datefield-extracts","children":[]},{"title":"Extractions DateTimeField","anchor":"datetimefield-extracts","children":[]}]},{"title":"Now","anchor":"now","children":[]},{"title":"Trunc","anchor":"trunc","children":[{"title":"Troncature de DateField","anchor":"datefield-truncation","children":[]},{"title":"Troncature de DateTimeField","anchor":"datetimefield-truncation","children":[]},{"title":"Troncature de TimeField","anchor":"timefield-truncation","children":[]}]}]},{"title":"Fonctions textuelles","anchor":"text-functions","children":[{"title":"Concat","anchor":"concat","children":[]},{"title":"Length","anchor":"length","children":[]},{"title":"Lower","anchor":"lower","children":[]},{"title":"StrIndex","anchor":"strindex","children":[]},{"title":"Substr","anchor":"substr","children":[]},{"title":"Upper","anchor":"upper","children":[]}]},{"title":"Fonctions de fenêtrage","anchor":"window-functions","children":[{"title":"CumeDist","anchor":"cumedist","children":[]},{"title":"DenseRank","anchor":"denserank","children":[]},{"title":"FirstValue","anchor":"firstvalue","children":[]},{"title":"Lag","anchor":"lag","children":[]},{"title":"LastValue","anchor":"lastvalue","children":[]},{"title":"Lead","anchor":"lead","children":[]},{"title":"NthValue","anchor":"nthvalue","children":[]},{"title":"Ntile","anchor":"ntile","children":[]},{"title":"PercentRank","anchor":"percentrank","children":[]},{"title":"Rank","anchor":"rank","children":[]},{"title":"RowNumber","anchor":"rownumber","children":[]}]}],"breadcrumbs":[{"docname":"ref/index","title":"Référence de l’API","url":"/fr/2.0/ref/"},{"docname":"ref/models/index","title":"Modèles","url":"/fr/2.0/ref/models/"}],"prev":{"docname":"ref/models/conditional-expressions","title":"Expressions conditionnelles","url":"/fr/2.0/ref/models/conditional-expressions/"},"next":{"docname":"ref/request-response","title":"Les objets requête et réponse","url":"/fr/2.0/ref/request-response/"},"formats":{"html":"/fr/2.0/ref/models/database-functions/","markdown":"/fr/2.0/ref/models/database-functions.md","json":"/fr/2.0/ref/models/database-functions.json"},"source":"https://github.com/django/django/blob/stable/2.0.x/docs/ref/models/database-functions.txt","official":"https://docs.djangoproject.com/fr/2.0/ref/models/database-functions/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}