Traducido por Miguel A. Ponce

documentación de Django - 5.2.15.dev20260527181452

Home | Table of contents | Index | Modules

« previous | up | next »

Funciones del Base de Datos¶

Las clases documentadas a continuación proporcionan una forma para que los usuarios utilicen funciones proporcionadas por la base de datos subyacente como anotaciones, agregaciones o filtros en Django. Las funciones también son expresiones, por lo que se pueden utilizar y combinar con otras expresiones como las funciones de agregación.

Usaremos el siguiente modelo en los ejemplos de cada función:

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

No recomendamos usualmente permitir null=True para CharField ya que esto permite al campo tener dos «valores vacíos», pero es importante para el ejemplo de Coalesce a continuación.

Funciones de comparación y conversión¶

`Cast`¶

class Cast(expression, output_field)[fuente]¶

Fuerza el tipo de resultado de expression a ser el del output_field.

Ejemplo de uso:

>>> 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¶

class Coalesce(*expressions, **extra)[fuente]¶

Acepta una lista con al menos dos nombres de campos o expresiones y devuelve el primer valor no nulo (ten en cuenta que una cadena vacía no se considera un valor nulo). Cada argumento debe ser del mismo tipo, por lo tanto mezclar texto y números dará como resultado un error de base de datos.

Ejemplos de uso:

>>> # Get a screen name from least to most public
>>> from django.db.models import Sum
>>> 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
>>> # The aggregate default argument uses Coalesce() under the hood.
>>> aggregated = Author.objects.aggregate(
...     combined_age=Sum("age"),
...     combined_age_default=Sum("age", default=0),
...     combined_age_coalesce=Coalesce(Sum("age"), 0),
... )
>>> print(aggregated["combined_age"])
None
>>> print(aggregated["combined_age_default"])
0
>>> print(aggregated["combined_age_coalesce"])
0

Advertencia

Un valor Python pasado a Coalesce en MySQL puede ser convertido a un tipo incorrecto a menos que se convierta explícitamente al tipo correcto de la base de datos:

>>> 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¶

class Collate(expression, collation)[fuente]¶

Toma una expresión y el nombre de collación para consultar.

Por ejemplo, para filtrar de manera case-insensible en SQLite:

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

También se puede utilizar cuando se ordena, por ejemplo con PostgreSQL:

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

Greatest¶

class Greatest(*expressions, **extra)[fuente]¶

A continuación te dejo las traducciones de los textos originales manteniendo todas sus etiquetas intactas.

Ejemplo de uso:

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 será la más reciente de blog.modified y comment.modified.

Advertencia

El comportamiento de Greatest cuando uno o varios expresiones pueden ser null varía entre bases de datos:

PostgreSQL: Greatest devolverá la expresión no nula más grande, o null si todas las expresiones son null.
SQLite, Oracle y MySQL: Si alguna expresión es null, Greatest devolverá null.

El comportamiento de PostgreSQL se puede emular utilizando Coalesce si conoces un valor mínimo sensato para proporcionar como valor por defecto.

`Least`¶

class Least(*expressions, **extra)[fuente]¶

Accepts a list of at least two field names or expressions and returns the least value. Each argument must be of a similar type, so mixing text and numbers will result in a database error.

Advertencia

El comportamiento de Least cuando uno o varios expresiones pueden ser null varía entre bases de datos:

PostgreSQL: Least devolverá la expresión no nula más pequeña, o null si todas las expresiones son null.
SQLite, Oracle y MySQL: Si alguna expresión es null, Least devolverá null.

El comportamiento de PostgreSQL se puede emular utilizando Coalesce si conoces un valor máximo sensato para proporcionar como valor por defecto.

`NullIf`¶

class NullIf(expression1, expression2)[fuente]¶

Acepta dos expresiones y devuelve None si son iguales, en caso contrario devuelve expression1.

Cautelas sobre Oracle

Debido a una convención de Oracle, esta función devuelve la cadena vacía en lugar de None cuando las expresiones son del tipo CharField.

Proporcionar Value(None) a expression1 está prohibido en Oracle ya que Oracle no acepta NULL como el primer argumento.

Funciones de fecha¶

Usaremos el siguiente modelo en los ejemplos de cada función:

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

`Extract`¶

class Extract(expression, lookup_name=None, tzinfo=None, **extra)[fuente]¶

Extrae un componente de una fecha como número.

Toma una expression que representa un campo de fecha DateField, un campo de fecha y hora DateTimeField, un campo de hora TimeField o un campo de duración DurationField, y un lookup_name, y devuelve la parte de la fecha referenciada por lookup_name como un campo entero IntegerField. Django suele utilizar la función extract del motor de base de datos, por lo que puedes usar cualquier lookup_name que tu base de datos admita. Se puede pasar una subclase de tzinfo, normalmente proporcionada por zoneinfo, para extraer un valor en una zona horaria específica.

Dada la fecha y hora datetime «2015-06-15 23:30:01.000321+00:00», los nombres de lookup integrados devuelven:

«año»: 2015
«año_iso»: 2015
«cuarto»: 2
«mes»: 6
«día»: 15
«semana»: 25
«week_day»: 2
«iso_week_day»: 1
«hora»: 23
«minuto»: 30
«segundo»: 1

Si una zona horaria diferente como Australia/Melbourne está activa en Django, entonces la fecha y hora se convierte a la zona horaria antes de extraer el valor. El desplazamiento horario para Melbourne en la fecha del ejemplo anterior es +10:00. Los valores devueltos cuando esta zona horaria está activa serán los mismos que arriba excepto por:

«día»: 16
«día_de_la_semana»: 3
«día_de_la_semana_iso»: 2
«hora»: 9

Los valores de día_de_la_semana

El día_de_la_semana lookup_type se calcula de manera diferente a la mayoría de las bases de datos y a las funciones estándar de Python. Esta función devolverá 1 para domingo, 2 para lunes, hasta 7 para sábado.

La traducción de los textos es la siguiente:

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

valores de week

El tipo de búsqueda week se calcula según ISO-8601, es decir, una semana comienza el lunes. La primera semana de un año es la que contiene el primer jueves del año, es decir, la primera semana tiene la mayoría (cuatro o más) de sus días en el año. El valor devuelto está en el rango 1 a 52 o 53.

Cada lookup_name anterior tiene un subclase correspondiente Extract (listado a continuación) que se debe utilizar típicamente en lugar del equivalente más verbose, por ejemplo, utilice ExtractYear(...) en lugar de Extract(..., lookup_name='year').

Ejemplo de uso:

>>> 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

`DateField` extrae¶

class ExtractYear(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'year'

class ExtractIsoYear(expression, tzinfo=None, **extra)[fuente]¶

Devuelve el año ISO-8601 de numeración de semana.

lookup_name = 'iso_year'

class ExtractMonth(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'month'

class ExtractDay(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'day'

class ExtractWeekDay(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'week_day'

class ExtractIsoWeekDay(expression, tzinfo=None, **extra)[fuente]¶

Devuelve el día de la semana ISO-8601 con el día 1 siendo lunes y el día 7 siendo domingo.

lookup_name = 'iso_week_day'

class ExtractWeek(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'week'

class ExtractQuarter(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'quarter'

Estos son equivalentes lógicos a Extract('date_field', lookup_name). Cada clase también es un Transform registrado en DateField y DateTimeField como __(lookup_name), por ejemplo, __year.

Dado que los campos de fecha DateField no tienen una componente de hora, solo se pueden utilizar subclases Extract que traten partes de fechas con DateField:

>>> from datetime import datetime, 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}

`DateTimeField` extrae¶

Además de lo siguiente, todos los extractos para DateField listados anteriormente también pueden usarse en DateTimeField.

class ExtractHour(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'hour'

class ExtractMinute(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'minute'

class ExtractSecond(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'second'

Estos son lógicamente equivalentes a Extract('datetime_field', lookup_name). Cada clase es también un Transform registrado en DateTimeField como __(lookup_name), p. ej. __minute.

DateTimeField ejemplos:

>>> from datetime import datetime, 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}

Cuando USE_TZ es True, los datetimes se almacenan en la base de datos en UTC. Si una zona horaria diferente está activa en Django, el datetime se convierte a esa zona horaria antes de que se extraiga el valor. El ejemplo siguiente convierte a la zona horaria de Melbourne (UTC +10:00), lo que cambia los valores del día, semana y hora que se devuelven:

>>> from django.utils import timezone
>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("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}

Pasando explícitamente la zona horaria a la función Extract se comporta de la misma manera y tiene prioridad sobre una zona horaria activa.

>>> import zoneinfo
>>> melb = zoneinfo.ZoneInfo("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}

Ahora¶

class Now[fuente]¶

Devuelve la fecha y hora actual del servidor de base de datos cuando se ejecuta la consulta, típicamente utilizando el SQL CURRENT_TIMESTAMP.

Ejemplo de uso:

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

Consideraciones sobre PostgreSQL

En PostgreSQL, la consulta SQL CURRENT_TIMESTAMP devuelve el tiempo en que comenzó la transacción actual. Por lo tanto, para compatibilidad entre bases de datos, Now() utiliza STATEMENT_TIMESTAMP en su lugar. Si necesitas el timestamp de la transacción, utiliza django.contrib.postgres.functions.TransactionNow.

Oracle

En Oracle, se utiliza la sentencia SQL LOCALTIMESTAMP para evitar problemas con el casting de CURRENT_TIMESTAMP a DateTimeField.

`Trunc`¶

class Trunc(expression, kind, output_field=None, tzinfo=None, **extra)[fuente]¶

Corta una fecha hasta un componente significativo.

Cuando solo te importa si algo ocurrió en un año, hora o día particular, pero no el segundo exacto, entonces Trunc (y sus subclases) pueden ser útiles para filtrar o agrupar tus datos. Por ejemplo, puedes usar Trunc para calcular el número de ventas por día.

Trunc toma una sola expression, que representa un campo de fecha, hora o fecha y hora, un kind que representa una parte de fecha o hora, y un output_field que es ya sea un campo de fecha y hora, un campo de hora o un campo de fecha. Devuelve una fecha, hora o fecha y hora dependiendo de output_field, con los campos hasta kind establecidos en su valor mínimo. Si se omite output_field, se establecerá como el output_field de expression. Se puede pasar un subclase de tzinfo, generalmente proporcionado por zoneinfo, para cortar un valor en una zona horaria específica.

Dada la fecha y hora 2015-06-15 14:30:50.000321+00:00, los kind integrados devuelven:

«year»: 2015-01-01 00:00:00+00:00
«quarter»: 2015-04-01 00:00:00+00:00
«month»: 2015-06-01 00:00:00+00:00
«week»: 2015-06-15 00:00:00+00:00
«day»: 2015-06-15 00:00:00+00:00
«hora»: 2015-06-15 14:00:00+00:00
«minuto»: 2015-06-15 14:30:00+00:00
«segundo»: 2015-06-15 14:30:50+00:00

Si una zona horaria diferente como Australia/Melbourne está activa en Django, entonces la fecha y hora se convierte a la nueva zona horaria antes de que el valor se trunque. El desplazamiento horario de Melbourne en la fecha de ejemplo anterior es +10:00. Los valores devueltos cuando esta zona horaria está activa serán:

«año»: 2015-01-01 00:00:00+11:00
«trimestre»: 2015-04-01 00:00:00+10:00
«mes»: 2015-06-01 00:00:00+10:00
«semana»: 2015-06-16 00:00:00+10:00
«día»: 2015-06-16 00:00:00+10:00
«hora»: 2015-06-16 00:00:00+10:00
«minuto»: 2015-06-16 00:30:00+10:00
«segundo»: 2015-06-16 00:30:50+10:00

El año tiene un desplazamiento de +11:00 porque el resultado pasó a la hora de verano.

Cada kind anterior tiene una clase correspondiente Trunc (listadas a continuación) que se debe utilizar típicamente en lugar del equivalente más verbose, por ejemplo, utilice TruncYear(...) en lugar de Trunc(..., kind='year').

Las clases derivadas están definidas como transformaciones, pero no están registradas con ningún campo, porque los nombres de búsqueda ya están reservados por las clases Extract.

Ejemplo de uso:

>>> 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

La truncación del campo `DateField`¶

class TruncYear(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'year'

class TruncMonth(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'month'

class TruncWeek(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

Se truncan a la medianoche del lunes de la semana.

kind = 'week'

class TruncQuarter(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'quarter'

Estos son lógicamente equivalentes a Trunc('date_field', kind). Truncan todas las partes de la fecha hasta kind lo que permite agrupar o filtrar fechas con menos precisión. expression puede tener un campo de salida de DateField o DateTimeField.

Dado que los campos DateField no tienen una componente de hora, solo se pueden utilizar las clases derivadas Trunc que tratan partes de fechas con los campos DateField:

>>> from datetime import datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import TruncMonth, TruncYear
>>> 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 zoneinfo
>>> melb = zoneinfo.ZoneInfo("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

La truncación del campo `DateTimeField`¶

class TruncDate(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'date'

output_field = DateField()

TruncDate castea expression a una fecha en lugar de utilizar la función de truncado SQL incorporada. También se registra como transformación en el campo de fecha y hora DateTimeField como __date.

class TruncTime(expression, tzinfo=None, **extra)[fuente]¶

lookup_name = 'time'

output_field = TimeField()

TruncTime castea expression a una hora en lugar de utilizar la función de truncado SQL incorporada. También se registra como transformación en el campo de fecha y hora DateTimeField como __time.

class TruncDay(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'day'

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[fuente]¶

kind = 'second'

Estos son lógicamente equivalentes a Trunc('datetime_field', kind). Truncan todos los partes de la fecha hasta kind y permiten agrupar o filtrar fechas y horas con menos precisión. expression debe tener un campo de salida output_field de tipo DateTimeField.

Ejemplo de uso:

>>> from datetime import date, datetime, timezone
>>> from django.db.models import Count
>>> from django.db.models.functions import (
...     TruncDate,
...     TruncDay,
...     TruncHour,
...     TruncMinute,
...     TruncSecond,
... )
>>> import zoneinfo
>>> start1 = datetime(2014, 6, 15, 14, 30, 50, 321, tzinfo=timezone.utc)
>>> Experiment.objects.create(start_datetime=start1, start_date=start1.date())
>>> melb = zoneinfo.ZoneInfo("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=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'hour': datetime.datetime(2014, 6, 16, 0, 0, tzinfo=zoneinfo.ZoneInfo('Australia/Melbourne')),
 'minute': 'minute': datetime.datetime(2014, 6, 15, 14, 30, tzinfo=timezone.utc),
 'second': datetime.datetime(2014, 6, 15, 14, 30, 50, tzinfo=timezone.utc)
}

Truncación de campos de tiempo¶

class TruncHour(expression, output_field=None, tzinfo=None, **extra)[fuente]

kind = 'hour'

class TruncMinute(expression, output_field=None, tzinfo=None, **extra)[fuente]

kind = 'minute'

class TruncSecond(expression, output_field=None, tzinfo=None, **extra)[fuente]

kind = 'second'

Estos son lógicamente equivalentes a Trunc('time_field', kind). Truncan todas las partes del tiempo hasta kind, lo que permite agrupar o filtrar tiempos con menos precisión. expression puede tener un campo de salida output_field de tipo TimeField o DateTimeField.

Dado que los campos de tiempo no tienen una componente de fecha, solo se pueden utilizar las subclases de Trunc que truncan partes del tiempo con los campos de tiempo:

>>> from datetime import datetime, timezone
>>> from django.db.models import Count, TimeField
>>> from django.db.models.functions import TruncHour
>>> 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 zoneinfo
>>> melb = zoneinfo.ZoneInfo("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

Funciones JSON¶

`JSONArray`¶

class JSONArray(*expressions)[fuente]¶

Acepta una lista de nombres de campo o expresiones y devuelve un array JSON conteniendo esos valores.

Ejemplo de uso:

>>> from django.db.models import F
>>> from django.db.models.functions import JSONArray, Lower
>>> Author.objects.create(name="Margaret Smith", alias="msmith", age=25)
>>> author = Author.objects.annotate(
...     json_array=JSONArray(
...         Lower("name"),
...         "alias",
...         F("age") * 2,
...     )
... ).get()
>>> author.json_array
['margaret smith', 'msmith', 50]

`JSONObject`¶

class JSONObject(**fields)[fuente]¶

Toma una lista de pares clave-valor y devuelve un objeto JSON que contiene esos pares.

Ejemplo de uso:

>>> 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}

Funciones Matemáticas¶

Usaremos el siguiente modelo en los ejemplos de funciones matemáticas:

class Vector(models.Model):
    x = models.FloatField()
    y = models.FloatField()

`Abs`¶

class Abs(expression, **extra)[fuente]¶

Devuelve el valor absoluto de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class ACos(expression, **extra)[fuente]¶

Devuelve la arccoseno de un campo numérico o expresión. El valor de la expresión debe estar dentro del rango -1 a 1.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class ASin(expression, **extra)[fuente]¶

Devuelve el arcoseno de un campo numérico o expresión. El valor de la expresión debe estar en el rango -1 a 1.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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¶

class ATan(expression, **extra)[fuente]¶

Devuelve el arco tangente de un campo o expresión numérica.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class ATan2(expression1, expression2, **extra)[fuente]¶

Devuelve el arco tangente de expression1 / expression2.

Ejemplo de uso:

>>> 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`¶

class Ceil(expression, **extra)[fuente]¶

Devuelve el entero más pequeño mayor que o igual a un campo o expresión numérica.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class Cos(expression, **extra)[fuente]¶

Devuelve la coseno de un campo o expresión numérica.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class Cot(expression, **extra)[fuente]¶

Devuelve la cotangente de un campo o expresión numérica.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

Grados¶

class Degrees(expression, **extra)[fuente]¶

Convierte un campo numérico o expresión de radianes a grados.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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¶

class Exp(expression, **extra)[fuente]¶

Devuelve el valor de e (la base del logaritmo natural) elevado a la potencia de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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¶

class Floor(expression, **extra)[fuente]¶

Devuelve el mayor valor entero no superior a un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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¶

class Ln(expression, **extra)[fuente]¶

Devuelve el logaritmo natural de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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¶

class Log(expression1, expression2, **extra)[fuente]¶

Acepta dos campos numéricos o expresiones y devuelve el logaritmo del segundo con base en el primero.

Ejemplo de uso:

>>> 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¶

class Mod(expression1, expression2, **extra)[fuente]¶

Acepta dos campos numéricos o expresiones y devuelve el resto de la primera dividida por la segunda (operación módulo).

Ejemplo de uso:

>>> 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¶

class Pi(**extra)[fuente]¶

Devuelve el valor de la constante matemática π.

Potencia¶

class Power(expression1, expression2, **extra)[fuente]¶

Acepta dos campos numéricos o expresiones y devuelve el valor de la primera elevada a la potencia del segundo.

Ejemplo de uso:

>>> 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

Radiales¶

class Radians(expression, **extra)[fuente]¶

Convierte un campo numérico o expresión de grados a radianes.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

Aleatorio¶

class Random(**extra)[fuente]¶

Devuelve un valor aleatorio en el rango 0.0 ≤ x < 1.0.

`Redondea`¶

class Round(expression, precision=0, **extra)[fuente]¶

Redondea un campo numérico o expresión a precision (debe ser un entero) decimales. Por defecto, redondea al número entero más cercano. Si el valor medio se redondea hacia arriba o hacia abajo depende del motor de base de datos.

Ejemplo de uso:

>>> from django.db.models.functions import Round
>>> Vector.objects.create(x=5.4, y=-2.37)
>>> vector = Vector.objects.annotate(x_r=Round("x"), y_r=Round("y", precision=1)).get()
>>> vector.x_r, vector.y_r
(5.0, -2.4)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

`Signo`¶

class Sign(expression, **extra)[fuente]¶

Devuelve el signo (-1, 0, 1) de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

`Sen`¶

class Sin(expression, **extra)[fuente]¶

Devuelve la seno de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

`Raíz cuadrada`¶

class Sqrt(expression, **extra)[fuente]¶

Devuelve la raíz cuadrada de un campo numérico no negativo o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

`Tangente`¶

class Tan(expression, **extra)[fuente]¶

Devuelve la tangente de un campo numérico o expresión.

Ejemplo de uso:

>>> 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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)

Funciones de texto¶

`Chr`¶

class Chr(expression, **extra)[fuente]¶

Acepta un campo numérico o expresión y devuelve la representación de texto de la expresión como un carácter único. Funciona igual que la función chr() de Python.

Al igual que Length, puede registrarse como una transformación en IntegerField. El nombre de lookup por defecto es chr.

Ejemplo de uso:

>>> 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`¶

class Concat(*expressions, **extra)[fuente]¶

Acepta una lista de al menos dos campos o expresiones de texto y devuelve el texto concatenado. Cada argumento debe ser de tipo texto o char. Si deseas concatenar un TextField() con un CharField(), asegúrate de decirle a Django que el campo de salida debería ser un TextField(). Es necesario especificar un campo de salida también cuando se concatena un Value, como en el ejemplo siguiente.

Esta función nunca tendrá un resultado nulo. En los backends donde un argumento nulo hace que la expresión completa sea nula, Django asegurará de que cada parte nula se convierta en una cadena vacía primero.

Ejemplo de uso:

>>> # 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`¶

class Left(expression, length, **extra)[fuente]¶

Devuelve los primeros length caracteres del campo o expresión de texto dado.

Ejemplo de uso:

>>> 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`¶

class Length(expression, **extra)[fuente]¶

Acepta un solo campo o expresión de texto y devuelve el número de caracteres que tiene el valor. Si la expresión es nula, entonces también será nulo el largo.

Ejemplo de uso:

>>> # 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)

También puede registrarse como una transformación. Por ejemplo:

>>> 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`¶

class Lower(expression, **extra)[fuente]¶

Acepta un campo de texto o expresión única y devuelve la representación en minúsculas.

También se puede registrar como una transformación tal como se describe en Length.

Ejemplo de uso:

>>> 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`¶

class LPad(expression, length, fill_text=Value(' '), **extra)[fuente]¶

Devuelve el valor del campo de texto o expresión dado, rellenado a la izquierda con fill_text para que el resultado tenga length caracteres de largo. El relleno por defecto es un espacio.

Ejemplo de uso:

>>> 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`¶

class LTrim(expression, **extra)[fuente]¶

Similar a Trim, pero elimina solo los espacios en blanco de comienzo.

`MD5`¶

class MD5(expression, **extra)[fuente]¶

Acepta un campo de texto o expresión única y devuelve la suma MD5 del string.

También se puede registrar como una transformación tal como se describe en Length.

Ejemplo de uso:

>>> 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`¶

class Ord(expression, **extra)[fuente]¶

Acepta un campo de texto o expresión única y devuelve el valor del código Unicode del primer carácter de esa expresión. Funciona de manera similar a la función ord() de Python, pero no se levanta una excepción si la expresión es más larga que uno caracter.

También puede registrarse como una transformación tal como se describe en Length. El nombre de búsqueda por defecto es ord.

Ejemplo de uso:

>>> 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`¶

class Repeat(expression, number, **extra)[fuente]¶

Devuelve el valor del campo de texto o expresión dado repetido number veces.

Ejemplo de uso:

>>> 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`¶

class Replace(expression, text, replacement=Value(''), **extra)[fuente]¶

Reemplaza todas las ocurrencias de text con replacement en expression. El texto de reemplazo por defecto es la cadena vacía. Los argumentos de la función son sensibles a mayúsculas y minúsculas.

Ejemplo de uso:

>>> 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'}]>

`Inverso`¶

class Reverse(expression, **extra)[fuente]¶

Acepta un campo de texto o expresión única y devuelve los caracteres de esa expresión en orden inverso.

También puede registrarse como una transformación tal como se describe en Length. El nombre de búsqueda por defecto es reverse.

Ejemplo de uso:

>>> 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`¶

class Right(expression, length, **extra)[fuente]¶

Devuelve los últimos length caracteres del campo de texto o expresión dado.

Ejemplo de uso:

>>> 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`¶

class RPad(expression, length, fill_text=Value(' '), **extra)[fuente]¶

Similar a LPad, pero alinea en el lado derecho.

`RTrim`¶

class RTrim(expression, **extra)[fuente]¶

Similar a Trim, pero elimina solo los espacios de cola.

`SHA1`, `SHA224`, `SHA256`, `SHA384`, y `SHA512`¶

class SHA1(expression, **extra)[fuente]¶

class SHA224(expression, **extra)[fuente]¶

class SHA256(expression, **extra)[fuente]¶

class SHA384(expression, **extra)[fuente]¶

class SHA512(expression, **extra)[fuente]¶

Acepta un campo de texto o expresión única y devuelve la particular hash de la cadena.

Pueden registrarse también como transformaciones tal como se describe en Length.

Ejemplo de uso:

>>> 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

PostgreSQL

La extensión pgcrypto debe estar instalada. Puedes utilizar la operación de migración CryptoExtension para instalarla.

Oracle

Oracle no soporta la función SHA224.

`StrIndex`¶

class StrIndex(string, substring, **extra)[fuente]¶

Returns un entero positivo correspondiente a la posición 1-índice de la primera ocurrencia de substring dentro de string, o 0 si substring no se encuentra.

Ejemplo de uso:

>>> 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>]>

Advertencia

En MySQL, la determinación de la collation de una tabla de base de datos determina si las comparaciones de cadenas (como la expression y el substring de esta función) son sensibles a mayúsculas y minúsculas. Las comparaciones lo son por defecto.

`Substr`¶

class Substr(expression, pos, length=None, **extra)[fuente]¶

Returns un subconjunto de longitud length desde el campo o expresión que comienza en la posición pos. La posición es 1-índice, por lo tanto la posición debe ser mayor que 0. Si length es None, entonces se devolverá el resto de la cadena.

Ejemplo de uso:

>>> # 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`¶

class Trim(expression, **extra)[fuente]¶

Returns el valor del campo o expresión de texto dado con los espacios en blanco de cabeza y cola eliminados.

Ejemplo de uso:

>>> 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`¶

class Upper(expression, **extra)[fuente]¶

Accepts un campo o expresión de texto único y devuelve la representación en mayúsculas.

También se puede registrar como una transformación tal como se describe en Length.

Ejemplo de uso:

>>> 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

Funciones de ventana¶

Hay una serie de funciones para usar en una Window expresión para calcular el rango de elementos o el Ntile de algunas filas.

`CumeDist`¶

class CumeDist(*expressions, **extra)[fuente]¶

Calcula la distribución acumulada de un valor dentro de una ventana o partición. La distribución acumulada se define como el número de filas que preceden o están emparejadas con la fila actual dividido por el total de filas en el marco.

`DenseRank`¶

class DenseRank(*expressions, **extra)[fuente]¶

Equivalente a Rank pero no tiene lagunas.

`FirstValue`¶

class FirstValue(expression, **extra)[fuente]¶

Devuelve el valor evaluado en la fila que es la primera fila del marco de ventana, o None si no existe tal valor.

`Lag`¶

class Lag(expression, offset=1, default=None, **extra)[fuente]¶

Calcula el valor desplazado por offset, y si no existe ninguna fila allí, devuelve default.

default debe tener el mismo tipo que la expression, sin embargo, esto solo se valida en la base de datos y no en Python.

MariaDB y default

MariaDB no soporta el parámetro default.

`LastValue`¶

class LastValue(expression, **extra)[fuente]¶

Similar a FirstValue, calcula el último valor en una cláusula de marco dado.

`Lead`¶

class Lead(expression, offset=1, default=None, **extra)[fuente]¶

Calcula el valor líder en un marco dado:ref:frame <window-frames>. Ambos offset y default se evalúan con respecto a la fila actual.

default debe tener el mismo tipo que la expression, sin embargo, esto solo se valida en la base de datos y no en Python.

MariaDB y default

MariaDB no soporta el parámetro default.

`NthValue`¶

class NthValue(expression, nth=1, **extra)[fuente]¶

Computa la fila relativa al desplazamiento nth (debe ser un valor positivo) dentro de la ventana. Devuelve None si no existe ninguna fila.

Algunas bases de datos pueden manejar una nonexistent nth-value de manera diferente. Por ejemplo, Oracle devuelve una cadena vacía en lugar de None para expresiones basadas en caracteres. Django no realiza ninguna conversión en estos casos.

`Ntile`¶

class Ntile(num_buckets=1, **extra)[fuente]¶

Calcula una partición para cada una de las filas en la cláusula de marco, distribuyendo números de manera lo más uniforme posible entre 1 y num_buckets. Si las filas no se dividen de manera uniforme en un número de cajas, una o más cajas estarán representadas con mayor frecuencia.

`PercentRank`¶

class PercentRank(*expressions, **extra)[fuente]¶

Calcula la posición relativa de las filas en la cláusula frame. Esta computación es equivalente a evaluar:

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

La siguiente tabla explica el cálculo para la posición relativa de una fila:

Nº Fila	Valor	Rango	Cálculo	Posición Relativa
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

`Rango`¶

class Rank(*expressions, **extra)[fuente]¶

Comparable a RowNumber, esta función clasifica las filas en la ventana. El rango calculado contiene lagunas. Utilice DenseRank para calcular el rango sin lagunas.

`Número de fila`¶

class RowNumber(*expressions, **extra)[fuente]¶

Calcula el número de fila según el orden del marco o el orden de toda la consulta si no hay partición en la ventana de marcos.

« previous | up | next »

documentación de Django - 5.2.15.dev20260527181452

Funciones del Base de Datos¶

Funciones de comparación y conversión¶

Cast¶

Coalesce¶

Collate¶

Greatest¶

Least¶

NullIf¶

Funciones de fecha¶

Extract¶

DateField extrae¶

DateTimeField extrae¶

Ahora¶

Trunc¶

La truncación del campo DateField¶

La truncación del campo DateTimeField¶

Truncación de campos de tiempo¶

Funciones JSON¶

JSONArray¶

JSONObject¶

Funciones Matemáticas¶

Abs¶

ACos¶

ASin¶

ATan¶

ATan2¶

Ceil¶

Cos¶

Cot¶

Grados¶

Exp¶

Floor¶

Ln¶

Log¶

Mod¶

Pi¶

Potencia¶

Radiales¶

Aleatorio¶

Redondea¶

Signo¶

Sen¶

Raíz cuadrada¶

Tangente¶

Funciones de texto¶

Chr¶

Concat¶

Left¶

Length¶

Lower¶

LPad¶

LTrim¶

MD5¶

Ord¶

Repeat¶

Replace¶

Inverso¶

Right¶

RPad¶

RTrim¶

SHA1, SHA224, SHA256, SHA384, y SHA512¶

StrIndex¶

Substr¶

Trim¶

Upper¶

Funciones de ventana¶

CumeDist¶

DenseRank¶

FirstValue¶

Lag¶

LastValue¶

Lead¶

NthValue¶

Ntile¶

PercentRank¶

Rango¶

Número de fila¶

Last update:

`Cast`¶

`Least`¶

`NullIf`¶

`Extract`¶

`DateField` extrae¶

`DateTimeField` extrae¶

`Trunc`¶

La truncación del campo `DateField`¶

La truncación del campo `DateTimeField`¶

`JSONArray`¶

`JSONObject`¶

`Abs`¶

`ACos`¶

`ASin`¶

`ATan2`¶

`Ceil`¶

`Cos`¶

`Cot`¶

`Redondea`¶

`Signo`¶

`Sen`¶

`Raíz cuadrada`¶

`Tangente`¶

`Chr`¶

`Concat`¶

`Left`¶

`Length`¶

`Lower`¶

`LPad`¶

`LTrim`¶

`MD5`¶

`Ord`¶

`Repeat`¶

`Replace`¶

`Inverso`¶

`Right`¶

`RPad`¶

`RTrim`¶

`SHA1`, `SHA224`, `SHA256`, `SHA384`, y `SHA512`¶

`StrIndex`¶

`Substr`¶

`Trim`¶

`Upper`¶

`CumeDist`¶

`DenseRank`¶

`FirstValue`¶

`Lag`¶

`LastValue`¶

`Lead`¶

`NthValue`¶

`Ntile`¶

`PercentRank`¶

`Rango`¶

`Número de fila`¶