---
title: "Nathanna ceisteanna"
version: 5.2
locale: ga
source: https://docs.djangoproject.com/ga/5.2/ref/models/expressions/
canonical: https://djangodocs.dev/ga/5.2/ref/models/expressions/
---
# Nathanna ceisteanna

Déanann nathanna fiosrúcháin cur síos ar luach nó ar ríomh is féidir a úsáid mar chuid de nuashonrú, cruthú, scagadh, ordú de réir, anótáil nó comhiomlán. Nuair a aschuireann abairt luach boolean, féadfar é a úsáid go díreach i scagairí. Tá roinnt nathanna ionsuite ann (doiciméadaithe thíos) is féidir a úsáid chun cabhrú leat ceisteanna a scríobh. Is féidir nathanna a chomhcheangal, nó i gcásanna áirithe a neadú, chun ríomhanna níos casta a fhoirmiú.

## Uimhrithíocht tacaithe

Tacaíonn Django le diúltú, cur leis, íolrú, iolrú, roinnt, uimhríocht modulo, agus an t-oibreoir cumhachta ar nathanna fiosrúcháin, ag baint úsáide as comhsheasmhainní Python, athróga, agus fiú nathanna eile.

## Réimse aschuir

Tacaíonn go leor de na nathanna doiciméadaithe sa chuid seo le paraiméadar roghnach `output_field`. Má thugtar, luchtálfaidh Django an luach isteach sa réimse sin tar éis é a aisghabháil ón mbunachar sonraí.

Glacann `output_field` sampla réimse samhail, mar ```IntegerField () ``nó ``BooleanField ()```. De ghnáth, ní theastaíonn aon argóintí ón réimse, cosúil le max\_length , ós rud é go mbaineann argóintí réimse le bailíochtú sonraí nach ndéanfar ar luach aschuir an abairt.

Ní theastaíonn `output_field` ach amháin nuair nach bhfuil Django in ann cineál réimse an torthaí a chinneadh go huathoibríoch, mar shampla nathanna casta a mheascann cineálacha réimse. Mar shampla, teastaíonn réimse aschuir ```DecimalField () ``agus ``FloatField ()``` a chur leis, cosúil le output\_field=floatField () .

`output_field` also allows using custom fields that perform type conversions
outside a specific model field context. For example, if you frequently need to
perform date arithmetic with `timedelta`, you can create a custom field that
handles the conversion, ensuring consistent results across databases. See
[Conas réimsí samhail saincheaptha a chruthú](/ga/5.2/howto/custom-model-fields/).

## Roinnt samplaí

```pycon
>>> from django.db.models import Count, F, Value
>>> from django.db.models.functions import Length, Upper
>>> from django.db.models.lookups import GreaterThan

# Find companies that have more employees than chairs.
>>> Company.objects.filter(num_employees__gt=F("num_chairs"))

# Find companies that have at least twice as many employees
# as chairs. Both the querysets below are equivalent.
>>> Company.objects.filter(num_employees__gt=F("num_chairs") * 2)
>>> Company.objects.filter(num_employees__gt=F("num_chairs") + F("num_chairs"))

# How many chairs are needed for each company to seat all employees?
>>> company = (
...     Company.objects.filter(num_employees__gt=F("num_chairs"))
...     .annotate(chairs_needed=F("num_employees") - F("num_chairs"))
...     .first()
... )
>>> company.num_employees
120
>>> company.num_chairs
50
>>> company.chairs_needed
70

# Create a new company using expressions.
>>> company = Company.objects.create(name="Google", ticker=Upper(Value("goog")))
# Be sure to refresh it if you need to access the field.
>>> company.refresh_from_db()
>>> company.ticker
'GOOG'

# Annotate models with an aggregated value. Both forms
# below are equivalent.
>>> Company.objects.annotate(num_products=Count("products"))
>>> Company.objects.annotate(num_products=Count(F("products")))

# Aggregates can contain complex computations also
>>> Company.objects.annotate(num_offerings=Count(F("products") + F("services")))

# Expressions can also be used in order_by(), either directly
>>> Company.objects.order_by(Length("name").asc())
>>> Company.objects.order_by(Length("name").desc())
# or using the double underscore lookup syntax.
>>> from django.db.models import CharField
>>> from django.db.models.functions import Length
>>> CharField.register_lookup(Length)
>>> Company.objects.order_by("name__length")

# Boolean expression can be used directly in filters.
>>> from django.db.models import Exists, OuterRef
>>> Company.objects.filter(
...     Exists(Employee.objects.filter(company=OuterRef("pk"), salary__gt=10))
... )

# Lookup expressions can also be used directly in filters
>>> Company.objects.filter(GreaterThan(F("num_employees"), F("num_chairs")))
# or annotations.
>>> Company.objects.annotate(
...     need_chairs=GreaterThan(F("num_employees"), F("num_chairs")),
... )
```

## Nathanna tógtha

> **Note**
>
> Sainmhínítear na nathanna seo in django.db.models.expressions\` agus `django.db.models.aggregates`, ach ar mhaithe le háisiúlacht bíonn siad ar fáil agus de ghnáth allmhairithe ó:mod: django.db.models.

### Nathanna F () \`\`

#### `class F`

Léiríonn réad F () luach réimse samhail, luach claochlaithe réimse samhail, nó colún anótaithe. De bharr sé gur féidir tagairt a dhéanamh do luachanna réimse samhail agus oibríochtaí bunachar sonraí a dhéanamh ag baint úsáide as iad gan iad a tharraingt amach as an mbunachar sonraí isteach i gcuimhne Python.

Ina áit sin, úsáideann Django an réad F () chun abairt SQL a ghiniúint a thugann cur síos ar an oibríocht riachtanach ag leibhéal an bhunachar sonraí.

Déanaimis triail a bhaint as seo le sampla. De ghnáth, d'fhéadfadh duine rud éigin mar seo a dhéanamh:

```
# Tintin filed a news story!
reporter = Reporters.objects.get(name="Tintin")
reporter.stories_filed += 1
reporter.save()
```

Anseo, tarraingamar luach `reporter.stories_filed` ón mbunachar sonraí isteach i gcuimhne agus rinneamar é a ionramháil ag baint úsáide as oibreoirí Python eolach, agus ansin shábháil an réad ar ais chuig an mbunachar sonraí. Ach ina ionad sin d'fhéadfaimis a dhéanamh freisin:

```
from django.db.models import F

reporter = Reporters.objects.get(name="Tintin")
reporter.stories_filed = F("stories_filed") + 1
reporter.save()
```

Cé go bhfuil cuma `reporter.stories_filed = F ('stories_filed') + 1` cosúil le gnáthshannadh luach Python le tréith sampla, i ndáiríre is tógáil SQL é ag cur síos ar oibríocht ar an mbunachar sonraí.

Nuair a thagann Django le sampla de ```F () ``, a sháraíonn sé na hoibreoirí caighdeánacha Python chun abairt SQL cumhdaithe a chruthú; sa chás seo, ceann a thugann treoir don bhunachar sonraí an réimse bunachar sonraí a léiríonn ``reporter.stories_filed``` a mhéadú.

Cibé luach atá nó a bhí ar reporter.stories\_filed\`, ní fhaigheann Python eolas faoi riamh - déileálann an bunachar sonraí leis go hiomlán. Is é gach rud a dhéanann Python, trí rang F () Django, an comhréiteach SQL a chruthú chun tagairt a dhéanamh don réimse agus cur síos a dhéanamh ar an oibríocht.

Chun rochtain a fháil ar an luach nua a shábháil ar an mbealach seo, caithfear an réad a athluchtú:

```
reporter = Reporters.objects.get(pk=reporter.pk)
# Or, more succinctly:
reporter.refresh_from_db()
```

As well as being used in operations on single instances as above, `F()` can
be used with `update()` to perform bulk updates on a `QuerySet`. This
reduces the two queries we were using above - the `get()` and the
[`save()`](/ga/5.2/ref/models/instances/#django.db.models.Model.save) \- to just one:

```
reporter = Reporters.objects.filter(name="Tintin")
reporter.update(stories_filed=F("stories_filed") + 1)
```

Is féidir linn freisin: meth: ~django.db.models.query.queryset.update () a úsáid chun luach an réimse a mhéadú ar rudaí iolracha - rud a d'fhéadfadh a bheith i bhfad níos gasta ná iad go léir a tharraingt isteach i Python ón mbunachar sonraí, luach réimse gach ceann a mhéadú, agus gach ceann a shábháil ar ais chuig an mbunachar sonraí:

```
Reporter.objects.update(stories_filed=F("stories_filed") + 1)
```

Dá bhrí sin is féidir le F () buntáistí feidhmíochta a thairiscint trí:

- an bunachar sonraí a fháil, seachas Python, chun obair a dhéanamh
- laghdú ar líon na gceisteanna a theastaíonn ó oibríochtaí

#### Ag sliseadh abairtí F () \`\`

> **New in Django 5.1**

For string-based fields, text-based fields, and
[`ArrayField`](/ga/5.2/ref/contrib/postgres/fields/#django.contrib.postgres.fields.ArrayField), you can use Python's
array-slicing syntax. The indices are 0-based. The `step` argument to
`slice` and negative indexing are not supported. For example:

```pycon
>>> # Replacing a name with a substring of itself.
>>> writer = Writers.objects.get(name="Priyansh")
>>> writer.name = F("name")[1:5]
>>> writer.save()
>>> writer.refresh_from_db()
>>> writer.name
'riya'
```

#### Coinníollacha rása a sheachaint ag baint úsáide as F () \`\`

Buntáiste úsáideach eile a bhaineann le F () ná go seachnaíonn an bunachar sonraí - seachas Python - luach réimse a nuashonrú *coinníoll rása*.

Má fhorghníomhaíonn dhá snáithe Python an cód sa chéad shampla thuas, d'fhéadfadh snáithe amháin luach réimse a aisghabháil, a mhéadú agus a shábháil tar éis don duine eile é a aisghabháil ón mbunachar sonraí. Beidh an luach a shábhálann an dara snáithe bunaithe ar an luach bunaidh; caillfear obair an chéad snáithe.

Má tá an bunachar sonraí freagrach as an réimse a nuashonrú, tá an próiseas níos láidre: ní dhéanfaidh sé an réimse a nuashonrú riamh bunaithe ar luach an réimse sa bhunachar sonraí nuair a fhorghníomhaítear an:meth: ~model.save () \`nó \`update () \`, seachas bunaithe ar a luach nuair a aisghabhadh an cás.

#### Leanann tascanna ```F () ``tar éis ``Model.save ()```

Leanann rudaí F () a shanntar do réimsí samhail tar éis an tsamhail a shábháil agus cuirfear i bhfeidhm ar gach ceann: meth: ~Model.save () . Mar shampla:

```
reporter = Reporters.objects.get(name="Tintin")
reporter.stories_filed = F("stories_filed") + 1
reporter.save()

reporter.name = "Tintin Jr."
reporter.save()
```

Déanfar `stories_filed` a nuashonrú faoi dhó sa chás seo. Má tá sé ar dtús `1`, is é `3` an luach deiridh. Is féidir an marthanacht seo a sheachaint tríd an réad samhail a athluchtú tar éis é a shábháil, mar shampla, trí:meth: ~Model.fresh\_from\_db () a úsáid.

#### Ag baint úsáide as F () i scagairí

Tá ```F () ``an-úsáideach freisin i scagairí ``QuerySet```, áit a ndéanann siad sraith rudaí a scagadh i gcoinne critéir bunaithe ar a luachanna réimse, seachas ar luachanna Python.

\<using-f-expressions-in-filters\>Tá sé seo doiciméadaithe in:ref: ag baint úsáide as abairtí F () i gceisteanna .

#### Ag baint úsáide as F () le anótaí

Is féidir F () a úsáid chun réimsí dinimiciúla a chruthú ar do mhúnlaí trí réimsí éagsúla a chomhcheangal le huimhríocht:

```
company = Company.objects.annotate(chairs_needed=F("num_employees") - F("num_chairs"))
```

Má tá na réimsí atá á gcomhcheangal agat de chineálacha éagsúla beidh ort a rá le Django cén cineál réimse a thabharfar ar ais. Tacaíonn an chuid is mó de na nathanna le :ref: output\_field \<output-field\>\`don chás seo, ach ós rud é nach ndéanann \`\`F () \`, beidh ort an abairt a fhilleadh le:class: ExpressionWrapper:

```
from django.db.models import DateTimeField, ExpressionWrapper, F

Ticket.objects.annotate(
    expires=ExpressionWrapper(
        F("active_at") + F("duration"), output_field=DateTimeField()
    )
)
```

Nuair a dhéantar tagairt do réimsí coibhneasta mar `ForeignKey`, tugann F ()\` an príomhluach seachas samhail samhail:

```pycon
>>> car = Company.objects.annotate(built_by=F("manufacturer"))[0]
>>> car.manufacturer
<Manufacturer: Toyota>
>>> car.built_by
3
```

#### Ag baint úsáide as F () chun luachanna neall a shórtáil

Úsáid ```F () ``agus an argóint eochairfhocal ``nulls_first``` nó `nulls_last` to:meth: .expression.asc nô:meth: ~.expression.desc chun ordú luachanna null réimse a rialú. De réir réamhshocrú, braitheann an t-ordú ar do bhunachar sonraí.

Mar shampla, chun cuideachtaí nár tugadh teagmháil leo a shórtáil (`last_contacted` is null) tar éis cuideachtaí a ndearnadh teagmháil leo:

```
from django.db.models import F

Company.objects.order_by(F("last_contacted").desc(nulls_last=True))
```

#### Ag baint úsáide as F () le hoibríochtaí loighciúla

Nathanna ```F () ``is féidir aschur ``Booleanfield``` a dhiúltú go loighciúil leis an oibreoir iompaithe `~F ()`. Mar shampla, chun stádas gníomhachtaithe cuideachtaí a mhalartú:

```
from django.db.models import F

Company.objects.update(is_active=~F("is_active"))
```

### Nathanna Func () \`\`

Is iad abairtí ```Func () ``an bunchineál de na nathanna go léir a mbaineann feidhmeanna bunachar sonraí mar `COALESCE``` agus `LOWER`, nó comhiomlánacha mar SUM\`. Is féidir iad a úsáid go díreach:

```
from django.db.models import F, Func

queryset.annotate(field_lower=Func(F("field"), function="LOWER"))
```

nó is féidir iad a úsáid chun leabharlann feidhmeanna bunachar sonraí a thógáil:

```
class Lower(Func):
    function = "LOWER"

queryset.annotate(field_lower=Lower("field"))
```

Ach beidh tacar ceisteanna mar thoradh ar an dá chás ina ndéantar anótáil ar gach samhail le tréith breise `field_lower` a tháirgtear, go garbh, ón SQL seo a leanas:

```sql
SELECT
    ...
    LOWER("db_table"."field") as "field_lower"
```

Féach: doc: feidhmeanna bunachar sonraí le haghaidh liosta de fheidhmeanna bunachar sonraí ionsuite.

Is é seo a leanas an API Func\`:

#### `class Func(*expressions, **extra)`

#### `function`

Tréith aicme a dhéanann cur síos ar an bhfeidhm a ghinteofar. Go sonrach, déanfar an feidhm \`\`idirphóilte mar shealbhóir an \`\`feidhmi\` laistigh de: attr: teimpléad. Réamhshocraithe go `None`.

#### `template`

Tréith aicme, mar shreang formáide, a chuireann síos ar an SQL a ghintear don fheidhm seo. Réamhshocraithe go '% (function) s (% (expressions) s) '.

Má tá SQL á thógáil agat cosúil le strftime ('%W', 'date') \`\`agus má theastaíonn carachtar liteartha \`\`%\` sa cheist, é a cheathrú (`%%%%%`) sa tréith `teimpléad` toisc go ndéantar an sreang idirphóilte dhá uair: uair amháin le linn an teimpléid in as\_sql ()\` agus uair amháin san idirpholú SQL leis na paraiméadair iarratais sa chúrsóir bunachar sonraí.

#### `arg_joiner`

Tréith aicme a léiríonn an carachtar a úsáidtear chun páirt a ghlacadh le liosta `léiritheach` le chéile. Réamhshocraithe go `', '`.

#### `arity`

Tréith aicme a léiríonn líon na n-argóintí a nglacann an fheidhm leis. Má shocraítear an tréith seo agus má thugtar an fheidhm le líon difriúil nathanna, ardófar `TypeError`. Réamhshocraithe go `None`.

#### `as_sql(compiler, connection, function=None, template=None, arg_joiner=None, **extra_context)`

Gineann sé an blúire SQL don fheidhm bhunachar sonraí. Filleann sé tuple `(sql, params)`, áit gurb é sql\` an teaghrán SQL, agus params\` an liosta nó an tiúpla de pharaiméadair fiosrúcháin.

Ba chóir do na modhanna ```as_vendor () ``úsáid a bhaint as na paraiméadair``` feidhm ``, `teimpléad``, arg\_joiner\`, agus aon pharaiméadair `**extra_context` eile chun an SQL a shaincheapadh de réir mar is gá. Mar shampla:

*`django/db/samhlacha/feidhmeanna. py`*

```python
class ConcatPair(Func):
    ...
    function = "CONCAT"
    ...

    def as_mysql(self, compiler, connection, **extra_context):
        return super().as_sql(
            compiler,
            connection,
            function="CONCAT_WS",
            template="%(function)s('', %(expressions)s)",
            **extra_context
        )
```

Chun leochaileacht insteallta SQL a sheachaint, ní chóir go mbeadh ionchur úsáideora neamhiontaofa ag `extra_context` \<avoiding-sql-injection-in-query-expressions\>\`: ref: mar go ndéantar na luachanna seo a idirphóladh isteach sa sreangán SQL seachas a rith mar pharaiméadair fiosrúcháin, áit a n-éalódh tiománaí bunachar sonraí iad.

Is liosta de na nathanna seasaimh a chuirfear i bhfeidhm ar an bhfeidhm é an argóint \* sainráitigh \`. Déanfar na nathanna a thiontú go teaghráin, a chur le chéile le arg\_joiner\`, agus ansin idirphóilfear isteach sa teimpléad \`\`mar shealbhóir áite \`\`léirithe\`.

Is féidir le hargóintí seasaimh a bheith ina nathanna nó luachanna Python. Glactar leis gur tagairtí colún iad na teaghráin agus fillfear iad in abairtí ```F () ``agus cuirfear luachanna eile fillte in abairtí ``Luach ()```.

Is iad na kwargs `**extra` péirí `eochair=luach` is féidir iad a ionghabháil isteach sa tréith ```teimpléad ``. Chun leochaileacht insteallta SQL a sheachaint, ní chóir go mbeadh ionchur úsáideora neamhion <avoiding-sql-injection-in-query-expressions>taofa ag ``extra```: ref: mar go ndéantar na luachanna seo a idirphóladh isteach sa sreang SQL seachas a rith mar pharaiméadair cheisteanna, áit a n-éalfadh tiománaí an bunachar sonraí iad.

Is féidir na heochairfhocail `feidhm`, teimpléad\`, agus `arg_joiner` a úsáid chun tréithe an ainm céanna a chur in ionad gan do rang féin a shainiú. :ref: is féidir output\_field \<output-field\>\`a úsáid chun an cineál tuairisceáin a bhfuil súil leis a shainiú.

### Nathanna Comhiomlán () \`\`

Is cás speisialta é abairt comhiomlán de a:ref: Func () abairt \<func-expressions\>\`a chuireann in iúl don cheist go bhfuil clásal \`\`GROUP BY\` ag teastáil. Tá gach ceann de na feidhmeanna:ref: comhiomlán \<aggregation-functions\>, cosúil le ```Sum () ``agus ``Count ()```, oidhreacht ó Comhiomlán () .

Ós rud é gur abairtí agus nathanna fillte iad `Comhiomlán`, is féidir leat roinnt ríomhanna casta a léiriú:

```
from django.db.models import Count

Company.objects.annotate(
    managers_required=(Count("num_employees") / 4) + Count("num_managers")
)
```

Is é seo a leanas an API `Comhléad`:

#### `class Aggregate(*expressions, output_field=None, distinct=False, filter=None, default=None, **extra)`

#### `template`

Tréith aicme, mar shreang formáide, a chuireann síos ar an SQL a ghintear don chomhiomlán seo. Réamhshocraithe go '% (function) s (% (difriúil) s% (abairtí) s) '.

#### `function`

Tréith aicme a dhéanann cur síos ar an bhfeidhm chomhiomlán a ghinteofar. Go sonrach, déanfar an feidhm \`\`idirphóilte mar shealbhóir an \`\`feidhmi\` laistigh de: attr: teimpléad. Réamhshocraithe go `None`.

#### `window_compatible`

Réamhshocraithe go `True` ós rud é gur féidir an chuid is mó de na feidhmeanna comhiomlána a úsáid mar an abairt foinse in:class: ~Django.db.Models.Expressions.Window.

#### `allow_distinct`

Tréith aicme a chinneann cibé an gceadaíonn an fheidhm chomhiomlán seo argóint eochairfhocal “difriúil” a rith nó nach bhfuil. Má tá sé socraithe go `False` (réamhshocraithe), ardaítear `TypeError` má chuirtear `Distinct=True`.

#### `empty_result_set_value`

Réamhshocraithe go `None` ós rud é go mbíonn NULL\` mar thoradh ar an gcuid is mó de na feidhmeanna comhiomlána nuair a chuirtear i bhfeidhm ar shraith torthaí folamh.

Is féidir leis na hargóintí seasaimh `léiritheach` abairtí, claochruithe an réimse samhail, nó ainmneacha réimsí samhail a bheith san áireamh. Déanfar iad a thiontú go sreang agus úsáidfear iad mar shealbhóir áit léiritheoir\` laistigh den teimpléad.

Cinneann an argóint ```difriúil ``cibé an gcaithfear an fheidhm chomhiomlán a ghairm nó nach bhfuil i gcás gach luach ar leith ``léiritheach``` (nó tacar luachanna, le haghaidh iolracha `léiritheach`). Ní thacaítear leis an argóint ach ar chomhiomláin a bhfuil: attr: ~Aggregate.allow\_Distinct socraithe go `True`.

Tógann an argóint `scagair` a:class: Q rud \`a úsáidtear chun na sraithe \<django.db.models.Q\>anna atá comhiomlánaithe a scagadh. Féach: ref: \`comhiomlánú coinníollach agus:ref: filtering-on-annotations mar shampla úsáid.

Glacann an argóint default\` luach a chuirfear in éineacht leis an comhiomlán chuig:class: ~Django.db.Models.Functions.Coalesce. Tá sé seo úsáideach chun luach atá le tabhairt ar ais seachas `None` a shonrú nuair nach bhfuil aon iontrálacha sa tacar fiosrúcháin (nó an ghrúpáil).

Is iad na kwargs `**extra` péirí `eochair=luach` is féidir iad a ionghabháil isteach sa tréith teimpléad .

### Do Feidhmeanna Comhiomlánacha féin a

Is féidir leat do fheidhmeanna comhiomlána féin a chruthú freisin. Ar a laghad, ní mór duit feidhm a shainiú, ach is féidir leat an SQL a ghintear a shaincheapadh go hiomlán freisin. Seo sampla gairid:

```
from django.db.models import Aggregate

class Sum(Aggregate):
    # Supports SUM(ALL field).
    function = "SUM"
    template = "%(function)s(%(all_values)s%(expressions)s)"
    allow_distinct = False
    arity = 1

    def __init__(self, expression, all_values=False, **extra):
        super().__init__(expression, all_values="ALL " if all_values else "", **extra)
```

### Nathanna Luach () \`\`

#### `class Value(value, output_field=None)`

Léiríonn réad Luach () an chomhpháirt is lú is féidir de abairt: luach simplí. Nuair is gá duit luach sláimhir, boolean nó sreang a léiriú laistigh de abairt, is féidir leat an luach sin a fhilleadh laistigh de Luach () .

Is annamh a bheidh ort ```Luach () ``a úsáid go díreach. Nuair a scríobhann tú an abairt ``F ('field') + 1```, fillteann Django an `1` go hinneach i Luach () , ag ligean luachanna simplí a úsáid i nathanna níos casta. Beidh ort Luach () a úsáid nuair is mian leat teaghrán a chur chuig abairt. Léirmhíníonn an chuid is mó de na nathanna argóint teaghrán mar ainm réimse, cosúil le Lower ('ainm') .

Déanann an argóint `luach` cur síos ar an luach atá le cur san áireamh sa abairt, mar shampla `` `1 ``, True\`, nó `None`. Tá a fhios ag Django conas na luachanna Python seo a thiontú ina gcineál bunachar sonraí comhfhreag

Má shonraítear no:ref: output\_field \<output-field\>, déanfar é a thabhairt chun cinn ó chineál an luach\` a chuirtear ar fáil do go leor cineálacha coitianta. Mar shampla, ag rith sampla de:py:class: datetime.datetime mar value\` réamhshocraithe `output_field` chuig:class: ~django.db.models.DateTimeField.

### Nathanna ExpressionWrapper () \`\`

#### `class ExpressionWrapper(expression, output_field)`

\<output-field\>Tá `ExpressionWrapper` timpeall ar abairt eile agus soláthraíonn sé rochtain ar airíonna, mar shampla:ref: output\_field \`, nach mbeadh ar fáil ar abairtí eile. Tá \`\`ExpressionWrapper\` riachtanach nuair a úsáidtear uimhríocht ar abairtí F () le cineálacha éagsúla mar a thuairiscítear in:ref: using-f-with-annotations.

> **Database casting not performed**
>
> `ExpressionWrapper` only sets the output field for the ORM and does not
> perform any database-level casting. To ensure a specific type is returned
> from the database, use [`Cast`](/ga/5.2/ref/models/database-functions/#django.db.models.functions.Cast) instead.

### Nathanna coinníollach

Ligeann nathanna coinníollach duit úsáid:keyword: if \`... :keyword: \`elif... :keyword: loighic else i gceisteanna. Tacaíonn Django le nathanna SQL `CASE` go dúchasach. Le haghaidh tuilleadh sonraí féach:doc: conditional-expressions.

### Nathanna Subquest () \`\`

#### `class Subquery(queryset, output_field=None)`

Is féidir leat fo-cheist sainráite a chur le `QuerySet` ag baint úsáide as an abairt `SubQuery`.

Mar shampla, chun gach post a anótáil le seoladh ríomhphoist údar an trácht is nua ar an bpost sin:

```pycon
>>> from django.db.models import OuterRef, Subquery
>>> newest = Comment.objects.filter(post=OuterRef("pk")).order_by("-created_at")
>>> Post.objects.annotate(newest_commenter_email=Subquery(newest.values("email")[:1]))
```

Ar PostgreSQL, tá cuma ar an SQL:

```sql
SELECT "post"."id", (
    SELECT U0."email"
    FROM "comment" U0
    WHERE U0."post_id" = ("post"."id")
    ORDER BY U0."created_at" DESC LIMIT 1
) AS "newest_commenter_email" FROM "post"
```

> **Note**
>
> Tá na samplaí sa chuid seo deartha chun a thaispeáint conas iallach a chur ar Django focheist a fhorghníomhú. I gcásanna áirithe d'fhéadfadh sé a bheith indéanta tacar ceisteanna coibhéiseach a scríobh a dhéanann an tasc céanna níos soiléire nó níos éifeachtaí.

#### Tagairt do cholúin ón tacar ceisteanna seachtrach

#### `class OuterRef(field)`

Úsáid `OuterRef` nuair is gá le tacar ceisteanna i `Focheiste` tagairt a dhéanamh do réimse ón bhfiosrú seachtrach nó a chlaochlú. Feidhmíonn sé cosúil le léiriú: aicme: F ach amháin nach ndéantar an seiceáil chun a fheiceáil an dtagraíonn sé do réimse bailí go dtí go réitear an tacar ceisteanna seachtrach.

Féadfar cásanna `OuterRef` a úsáid i gcomhar le cásanna neadaithe de `Subcheiste` chun tagairt a dhéanamh do thacar fiosrúcháin ina bhfuil nach é an tuismitheoir láithreach. Mar shampla, caithfeadh an tacar ceisteanna seo a bheith laistigh de phéire neadaithe cásanna `Subcheiste` chun réiteach i gceart:

```pycon
>>> Book.objects.filter(author=OuterRef(OuterRef("pk")))
```

#### Focheisteanna a theorannú go colún amháin

Tá amanna ann nuair a chaithfear colún amháin a thabhairt ar ais ó `Subcheiste`, mar shampla, chun `Subcheiste` a úsáid mar sprioc chuardaigh `__in`. Chun gach trácht ar phoist a fhoilsíodh laistigh den lá deireanach a thabhairt ar ais:

```pycon
>>> from datetime import timedelta
>>> from django.utils import timezone
>>> one_day_ago = timezone.now() - timedelta(days=1)
>>> posts = Post.objects.filter(published_at__gte=one_day_ago)
>>> Comment.objects.filter(post__in=Subquery(posts.values("pk")))
```

Sa chás seo, ní mór don fho-cheist a úsáid: meth: ~.queryset.values chun colún amháin a thabhairt ar ais: príomh-eochair an phoist.

#### An fho-cheist a theorannú go sraith amháin

Chun fo-cheist a chosc ó iliomad sraitheanna a thabhairt ar ais, úsáidtear slisnas (`[:1]`) den tacar fiosrúcháin:

```pycon
>>> subquery = Subquery(newest.values("email")[:1])
>>> Post.objects.annotate(newest_commenter_email=subquery)
```

Sa chás seo, ní mór don fho-cheist ach colún aon\* agus\* sraith amháin a thabhairt ar ais: seoladh ríomhphoist an trácht is déanaí a cruthaíodh.

(Teipfeadh ag baint úsáid:Meth: ~.querySet.get in ionad slisnas toisc nach féidir an `OuterRef` a réiteach go dtí go n-úsáidfear an tacar fiosrúcháin laistigh de `Subcheiste`.)

#### Focheisteanna Tá ann () \`\`

#### `class Exists(queryset)`

Is fo-aicme `` `Subcheiste `` é Exists\` a úsáideann ráiteas SQL `EXISTS`. I go leor cásanna feidhmeoidh sé níos fearr ná fo-cheist ós rud é go bhfuil an bunachar sonraí in ann stop a chur le meastóireacht ar an bhfo-cheist nuair a aimsítear an chéad tsraith meaitseála.

Mar shampla, chun gach post a anótáil le cibé an bhfuil trácht aige laistigh den lá deireanach nó nach bhfuil:

```pycon
>>> from django.db.models import Exists, OuterRef
>>> from datetime import timedelta
>>> from django.utils import timezone
>>> one_day_ago = timezone.now() - timedelta(days=1)
>>> recent_comments = Comment.objects.filter(
...     post=OuterRef("pk"),
...     created_at__gte=one_day_ago,
... )
>>> Post.objects.annotate(recent_comment=Exists(recent_comments))
```

Ar PostgreSQL, tá cuma ar an SQL:

```sql
SELECT "post"."id", "post"."published_at", EXISTS(
    SELECT (1) as "a"
    FROM "comment" U0
    WHERE (
        U0."created_at" >= YYYY-MM-DD HH:MM:SS AND
        U0."post_id" = "post"."id"
    )
    LIMIT 1
) AS "recent_comment" FROM "post"
```

Ní gá iallach ar `Exists` tagairt a dhéanamh do cholún amháin, ós rud é go ndéantar na colúin a chaitheamh agus cuirtear toradh boolean ar ais. Ar an gcaoi chéanna, ós rud é nach bhfuil ordú tábhachtach laistigh de fhocheistiú SQL EXISTS agus nach ndéanfadh sé ach feidhmíocht a laghdú, baintear é go huathoibríoch.

Is féidir leat ceist a dhéanamh ag baint úsáide as `NOT EXISTS` le ~Exists () .

#### Scagadh ar nathanna `Focheist ()` nó `Existents ()` \`

Is féidir ```Subquery () ``a thugann luach boolean agus ``Existents ()``` a úsáid mar `coinníoll` in:class: ~django.db.Models.Expressions.When abairtí, nó chun tacar fiosrúcháin a scagadh go díreach:

```pycon
>>> recent_comments = Comment.objects.filter(...)  # From above
>>> Post.objects.filter(Exists(recent_comments))
```

Cinnteoidh sé seo nach gcuirfear an fo-cheist leis na colúin `SELECT`, rud a d'fhéadfadh feidhmíocht níos fearr a bheith mar thoradh air.

#### Ag baint úsáide as comhiomlánaithe laistigh de abairt Focheisteanna \`

Is féidir comhiomláin a úsáid laistigh de `SubQuery`, ach teastaíonn teaglaim shonrach uathu de:meth: ~.queryset.filter, :meth: ~.queryset.values, agus:meth: ~.queryset.annotate chun an grúpáil fo-cheisteanna a chur i gceart.

Ag glacadh leis go bhfuil réimse fad ag an dá mhúnla, chun poist a aimsiú ina bhfuil fad an phoist níos mó ná fad iomlán na dtuairimí comhcheangailte go léir:

```pycon
>>> from django.db.models import OuterRef, Subquery, Sum
>>> comments = Comment.objects.filter(post=OuterRef("pk")).order_by().values("post")
>>> total_comments = comments.annotate(total=Sum("length")).values("total")
>>> Post.objects.filter(length__gt=Subquery(total_comments))
```

Cuireann an “scagaire (...)” tosaigh teorainn leis an bhfocheistiú go dtí na paraiméadair ábhartha. Baineann ```order_by () ``an réamhshocraithe:attr: `~Django.db.Models.Options.Ordering` (más ann) ar an tsamhail ``Comment```. Comhiomlánann ```luachanna ('post') ``tuairimí le ``Post```. Faoi dheireadh, déanann annotate (...) an comhiomlánú. Tá an t-ord ina gcuirtear na modhanna ceisteanna seo i bhfeidhm tábhachtach. Sa chás seo, ós rud é go gcaithfear an fo-cheist a bheith teoranta do cholún amháin, tá gá le luachanna ('iomlán') \`.

Is é seo an t-aon bhealach chun comhiomlánú a dhéanamh laistigh de `SubQuery`, mar a úsáideann: meth: ~.queryset.aggregate iarracht an tacar ceisteanna a mheas (agus má tá `OuterRef` ann, ní féidir é seo a réiteach).

### Nathanna amh SQL

#### `class RawSQL(sql, params, output_field=None)`

Uaireanta ní féidir le nathanna bunachar sonraí clásal casta `WHERE` a chur in iúl go héasca. Sna cásanna imeall seo, bain úsáid as an abairt Rawsql\`. Mar shampla:

```pycon
>>> from django.db.models.expressions import RawSQL
>>> queryset.annotate(val=RawSQL("select col from sometable where othercol = %s", (param,)))
```

B'fhéidir nach mbeidh na cuardaigh breise seo iniompartha d'innill bhunachar sonraí éagsúla (toisc go bhfuil cód SQL á scríobh go sainráite agat) agus sáraíonn tú prionsabal DRY, mar sin ba cheart duit iad a sheachaint más féidir.

Is féidir nathanna `Rawsql` a úsáid freisin mar sprioc scagairí `__in`:

```pycon
>>> queryset.filter(id__in=RawSQL("select id from sometable where col = %s", (param,)))
```

> **Warning**
>
> Chun cosaint a dhéanamh ar ionsaithe insteallta SQL \_ \< [https://en.wikipedia.org/wiki/SQL\_injection](https://en.wikipedia.org/wiki/SQL_injection)\>, ní mór duit éalú aon pharaiméadair is féidir leis an úsáideoir a rialú trí params' a úsáid. Is argóint riachtanach é params' chun iallach ort a admháil nach bhfuil tú ag idirphóiriú do SQL le sonraí a sholáthraíonn an úsáideoir.
>
> Ní mór duit sealbhóirí áiteanna a lua sa teaghrán SQL freisin. Tá an sampla seo leochaileach do instealladh SQL mar gheall ar na luachana timpeall `%s`:
>
> ```
> RawSQL("select col from sometable where othercol = '%s'")  # unsafe!
> ```
>
> \<sql-injection-protection\>Is féidir leat tuilleadh a léamh faoin gcaoi a n-oibríonn Django's:ref: Cosaint insteallta SQL .

### Feidhmeanna fuinn

Soláthraíonn feidhmeanna fuinneoige bealach chun feidhmeanna a chur i bhfeidhm ar Murab ionann agus gnáthfheidhm chomhiomlánaithe a ríomhaíonn toradh deiridh do gach tacar a shainmhíníonn an grúpa ag, oibríonn feidhmeanna fuinneoige ar:ref: frámaí \<window-frames\>\`agus deighiltí, agus ríomhaíonn siad an toradh do gach sraith.

Is féidir leat fuinneoga iolracha a shonrú san fhiosrúchán céanna a bheadh i Django ORM comhionann le nathanna iolracha a áireamh in a:doc: Query\</topics/db/aggregation\> Set.annotate () glao. Ní úsáideann an ORM fuinneoga ainmnithe, ina ionad sin tá siad mar chuid de na colúin roghnaithe.

#### `class Window(expression, partition_by=None, order_by=None, frame=None, output_field=None)`

#### `template`

Réamhshocraithe go ```% (abairt) s OVER (% (window) s) `. Mura gcuirtear ach an argóint ``léirithe``` ar fáil, beidh clásal na fuinneoige bán.

Is é an rang ```Windows ``an príomh-abairt do chlásal ``OVER```.

Is é an argóint `léirithe` a: ref: feidhm fuinneog \`\<window-functions\>, an:ref: \`feidhm chomhiomlán, nó abairt atá comhoiriúnach i gclá \<aggregation-functions\>sal fuinneoige.

Glacann an argóint partition\_by\` le abairt nó le seicheamh abairtí (ba chóir ainmneacha colún a fhilleadh i réad `F`) a rialaíonn deighilt na sraitheanna. Déanann deighilt a chúngú cé na sraitheanna a úsáidtear chun an tacar torthaí a ríomh.

Sonraítear an:ref: output\_field \<output-field\>\`mar argóint nó leis an abairt.

Glacann an argóint order\_by\` le abairt ar féidir leat glao:meth: ~django.db.models.expression.asc agus:meth: ~django.db.models.expression.desc, teaghrán ainm réimse (le réimír roghnach `” -"` a léiríonn ord íslitheach), nó liosta teaghráin agus/nó nathanna. Rialaíonn an t-ordú an t-ord ina gcuirtear an abairt i bhfeidhm. Mar shampla, má chuireann tú suim thar na sraitheanna i ndeighilt, is é an chéad toradh luach an chéad shraith, is é an dara ceann suim den chéad agus an dara sraith.

Sonraíonn an paraiméadar fráma na sraitheanna eile ba chóir a úsáid sa ríomh. Féach: Ref: fhrámaí fuinneog le haghaidh sonraí.

Mar shampla, chun anótáil a dhéanamh ar gach scannán leis an meánrátáil do na scannáin ag an stiúideo céanna sa seánra agus sa bhliain scaoilte céanna:

```pycon
>>> from django.db.models import Avg, F, Window
>>> Movie.objects.annotate(
...     avg_rating=Window(
...         expression=Avg("rating"),
...         partition_by=[F("studio"), F("genre")],
...         order_by="released__year",
...     ),
... )
```

Ligeann sé seo duit seiceáil an bhfuil scannán a rátáil níos fearr nó níos measa ná a phiaraí.

B'fhéidir gur mhaith leat nathanna iolracha a chur i bhfeidhm thar an bhfuinneog chéanna, ie, an deighilt agus an fráma céanna. Mar shampla, d'fhéadfá an sampla roimhe seo a mhodhnú chun an rátáil is fearr agus is measa a áireamh i ngrúpa gach scannáin (an stiúideo céanna, an seánra agus an bhliain scaoilte céanna) trí fheidhm fuinneoige a úsáid san fhiosrú céanna. Baintear an deighilt agus an t-ordú ón sampla roimhe seo isteach i bhfoclóir chun athrá a laghdú:

```pycon
>>> from django.db.models import Avg, F, Max, Min, Window
>>> window = {
...     "partition_by": [F("studio"), F("genre")],
...     "order_by": "released__year",
... }
>>> Movie.objects.annotate(
...     avg_rating=Window(
...         expression=Avg("rating"),
...         **window,
...     ),
...     best=Window(
...         expression=Max("rating"),
...         **window,
...     ),
...     worst=Window(
...         expression=Min("rating"),
...         **window,
...     ),
... )
```

Tacaítear le scagadh i gcoinne feidhmeanna fuinneoige chomh fada agus nach bhfuil cuardaigh díghníomhach (gan úsáid OR\` nó `XOR` mar chónascaire) agus i gcoinne tacar cheisteanna a dhéanann comhiomlánú.

Mar shampla, ní thacaítear le ceist a bhraitheann ar chomhiomlánú agus a bhfuil scagaire `Or` -ED aige i gcoinne feidhm fuinneoige agus réimse. D'fhéadfadh go gcuirfí sraitheanna a eisiamh ó ghrúpaí de ghnáth a chur san áireamh iar-chomhiomlánú réamhchóga comhcheang

```pycon
>>> qs = Movie.objects.annotate(
...     category_rank=Window(Rank(), partition_by="category", order_by="-rating"),
...     scenes_count=Count("actors"),
... ).filter(Q(category_rank__lte=3) | Q(title__contains="Batman"))
>>> list(qs)
NotImplementedError: Heterogeneous disjunctive predicates against window functions
are not implemented when performing conditional aggregation.
```

I measc cúltaca bunachar sonraí ionsuite Django, tacaíonn MySQL, PostgreSQL, agus Oracle nathanna fuinneoige. Athraíonn tacaíocht do ghnéithe éagsúla léirithe fuinneoige i measc na mbun Mar shampla, ní fhéadfar tacú leis na roghanna in:meth: ~Django.db.Models.Expression.asc agus:meth: ~Django.db.Models.Expression.desc. Téigh i gcomhairle leis na cáipéisíocht do do bhunachar sonraí

#### Frámaí

Maidir le fráma fuinneoige, is féidir leat seicheamh sraitheanna bunaithe ar raon nó gnáthseicheamh sraitheanna a roghnú.

#### `class ValueRange(start=None, end=None, exclusion=None)`

#### `frame_type`

Tá an tréith seo socraithe go `'RANGE`.

Tá tacaíocht theoranta ag PostgreSQL do ValueRange\` agus ní thacaíonn sé ach le húsáid na bpointí tosaigh agus deiridh caighdeánacha, mar shampla `CURRENT ROW` agus `UNBOUNDED FOLLOWING`.

> **Changed in Django 5.1**
>
> Cuireadh an argóint `eisiaim` leis.

#### `class RowRange(start=None, end=None, exclusion=None)`

#### `frame_type`

Tá an tréith seo socraithe go `'ROWS'`.

> **Changed in Django 5.1**
>
> Cuireadh an argóint `eisiaim` leis.

Tugann an dá rang SQL ar ais leis an teimpléad:

```sql
%(frame_type)s BETWEEN %(start)s AND %(end)s
```

#### `class WindowFrameExclusion`

> **New in Django 5.1**

#### `CURRENT_ROW`

#### `GROUP`

#### `TIES`

#### `NO_OTHERS`

Ceadaíonn an argóint eisiamh sraitheanna (:attr: ~WindowFrameExclusion.current\_row), grúpaí (:attr: ~WindowFrameExclusion.group), agus ceangail (:attr: ~WindowFrameExclusion.ties) a eisiamh ó na frámaí fuinneoige ar bhunachar sonraí tacaithe:

```sql
%(frame_type)s BETWEEN %(start)s AND %(end)s EXCLUDE %(exclusion)s
```

Cuimsíonn frámaí na sraitheanna a úsáidtear chun an toradh a ríomh. Aistríonn siad ó phointe tosaigh éigin go pointe deiridh sonraithe éigin. Is féidir frámaí a úsáid le deighiltí agus gan deighiltí, ach is minic gur smaoineamh maith é ordú na fuinneoige a shonrú chun toradh cinntitheach a chinntiú. I bhfráma, is é piaraí i bhfráma ina chéile le luach coibhéiseach, nó gach sraitheanna mura bhfuil clásal ordaithe i láthair.

Is é an pointe tosaigh réamhshocraithe le haghaidh fráma ná `UNBOUNDED PRESEING` arb é an chéad tsraith den dheighilt. Cuirtear an pointe deiridh san áireamh go sainráite i gcónaí sa SQL a ghineann an ORM agus de réir réamhshocraithe é “FOLLOWING UNBOUNDED”. Cuimsíonn an fráma réamhshocraithe gach sraitheanna ón deighilt go dtí an tsraith deireanach sa tacar.

Is iad na luachanna a nglactar leis do na hargóintí ```tús ``agus ``deireadh``` ná `None`, sláimhir, nó nialas. Mar thoradh ar shláimhir dhiúltach do `tosaithe` bíonn `N ROIMH ROIMH` mar thoradh ar ``` ``None ``` ROIMH \`ROIMH NEAMHTHEANNA\`. I mód ```ROWS`, is féidir sláimhir dhearfach a úsáid le haghaidh ``tús ``mar thoradh ar ``N FOLLOWING```. Glactar le sláimhreacha dearfacha le haghaidh ```deireadh ``agus bíonn `N FOLLOWING``` mar thoradh air. I mód ```ROWS`, is féidir sláimhir dhiúltach a úsáid le haghaidh ``deireadh ``mar thoradh air sin ``N ROIMH```. Maidir le `tosa` agus ```deireadh ``araon, fillfidh nialas ``CURRENT ROW```.

Tá difríocht ann maidir leis an méid a chuimsíonn `CURRENT ROW`. Nuair a shonraítear i mód ```ROWS`, tosaíonn nó críochnaíonn an fráma leis an tsraith reatha. Nuair a shonraítear i mód “RANGE”, tosaíonn nó críochnaíonn an fráma ag an gcéad piara nó an piara deireanach de réir an chlásal ordaithe. Dá bhrí sin, déanann `RANGE CURRENT ROW` measúnú ar an abairt do shraitheanna a bhfuil an luach céanna acu a shonraítear leis an ordú. Toisc go n-áirítear sa teimpléad na pointí ``tosaithe``` agus deireadh araon, féadfar é seo a chur in iúl le:

```
ValueRange(start=0, end=0)
```

Má dhéantar cur síos ar “phiaraí” scannáin mar scannáin a d'eisigh an stiúideo céanna sa seánra céanna sa bhliain chéanna, déanann an sampla Rowrange\` seo anótáil gach scannán le meán-rátáil dhá phiaraí roimhe seo agus beirt phiaraí scannáin seo a leanas:

```pycon
>>> from django.db.models import Avg, F, RowRange, Window
>>> Movie.objects.annotate(
...     avg_rating=Window(
...         expression=Avg("rating"),
...         partition_by=[F("studio"), F("genre")],
...         order_by="released__year",
...         frame=RowRange(start=-2, end=2),
...     ),
... )
```

Má thacaíonn an bunachar sonraí leis, is féidir leat na pointí tosaigh agus deiridh a shonrú bunaithe ar luachanna léirithe sa dheighilt. Má stóráil réimse `scaoil` den tsamhail Scannán mhí scaoilte gach scannáin, déanann an sampla ValueRange\` seo anótáil gach scannán le meánrátáil piaraí scannáin a eisíodh idir dhá mhí dhéag roimh agus dhá mhí dhá tar éis gach scannán:

```pycon
>>> from django.db.models import Avg, F, ValueRange, Window
>>> Movie.objects.annotate(
...     avg_rating=Window(
...         expression=Avg("rating"),
...         partition_by=[F("studio"), F("genre")],
...         order_by="released__year",
...         frame=ValueRange(start=-12, end=12),
...     ),
... )
```

> **Changed in Django 5.1**
>
> Cuireadh tacaíocht do shláimhir dearfach ``` `tús ``agus sláimhir dhiúltach ``deireadh ``` le haghaidh Rowrange\`.

## Eolas Teicniúil

Anseo thíos gheobhaidh tú sonraí feidhme teicniúla a d'fhéadfadh a bheith úsáideach d'údair leabharlainne Cuideoidh an API teicniúil agus na samplaí thíos le nathanna ceisteanna cineálacha a chruthú ar féidir leo an fheidhmiúlacht ionsuite a sholáthraíonn Django

### API léiriú

Cuireann nathanna fiosrúcháin an: ref: abairt fiosraithe API \<query-expression\>\`i bhfeidhm, ach nochtann roinnt modhanna agus tréithe breise atá liostaithe thíos freisin. Caithfidh gach abairt fiosrúcháin a oidhreacht ó Expression () nó ó fho-aicme ábhartha.

Nuair a fhilleann abairt fiosrúcháin abairt eile, tá sé freagrach as na modhanna cuí a ghlaoch ar an abairt fillte.

#### `class Expression`

#### `allowed_default`

Insíonn sé le Django gur féidir an abairt seo a úsáid in:attr: Field.db\_default. Réamhshocraithe go `False`.

#### `constraint_validation_compatible`

> **New in Django 5.1**

Insíonn sé le Django gur féidir an abairt seo a úsáid le linn bailíochtú srianta. Ní mór ach abairt foinse amháin a bheith ag abhairtí le `restricint_validation_compatible` atá socraithe go `False`. Réamhshocraithe go `True`.

#### `contains_aggregate`

Insíonn sé le Django go bhfuil comhiomlán sa abairt seo agus gur gá clásal GROUP BY a chur leis an gceist.

#### `contains_over_clause`

Insíonn sé le Django go bhfuil a: aicme: ~Django.db.Models.Expressions.Window léiriú sa abairt seo. Úsáidtear é, mar shampla, chun nathanna feidhme fuinneoige a dhícheadú i gceisteanna a mhodhnóidh sonraí.

#### `filterable`

Insíonn sé le Django gur féidir tagairt a thabhairt don abairt seo in:meth: .querySet.filter. Réamhshocraithe go `True`.

#### `window_compatible`

Insíonn sé le Django gur féidir an abairt seo a úsáid mar an abairt foinse in:class: ~Django.db.Models.Expressions.Window. Réamhshocraithe go `False`.

#### `empty_result_set_value`

Insíonn sé le Django cén luach ba chóir a thabhairt ar ais nuair a úsáidtear an abairt chun feidhm a chur i bhfeidhm thar shraith torthaí folamh. Réamhshocraithe to:py:data: NotImplemented a chuireann iallach ar an abairt a ríomh ar an mbunachar sonraí.

#### `set_returning`

> **New in Django 5.2**

Tells Django that this expression contains a set-returning function,
enforcing subquery evaluation. It's used, for example, to allow some
Postgres set-returning functions (e.g. `JSONB_PATH_QUERY`,
`UNNEST`, etc.) to skip optimization and be properly evaluated when
annotations spawn rows themselves. Defaults to `False`.

#### `allows_composite_expressions`

> **New in Django 5.2**

Tells Django that this expression allows composite expressions, for
example, to support [composite primary keys](/ga/5.2/topics/composite-primary-key/#cpk-and-database-functions). Defaults to `False`.

#### `resolve_expression(query=None, allow_joins=True, reuse=None, summarize=False, for_save=False)`

Soláthraíonn sé deis aon réamhphróiseáil nó bailíochtú an abairt a dhéanamh sula gcuirtear é leis an bhfiosrú. Ní mór ```resolve_expression () ``a ghlaoch freisin ar aon nathanna neadaithe. Ba chóir ``cóip () ``de ``féin``` a thabhairt ar ais le haon claochlú riachtanach.

Is é `fiosraithe` cur i bhfeidhm na ceisteanna cúltaca.

Is boolean é allow\_joins\` a cheadaíonn nó a dhiúltaíonn úsáid comhpháirteanna sa cheist.

Is sraith de chomhpháirteanna in-athúsáidte é athúsáid\` le haghaidh cásanna ilcheangailte.

Is boolean é ```achoimre ``a thugann comharthaíocht, nuair a dhéanann ``True```, gur ceist chomhiomlán críochfoirt é an cheist atá á ríomh.

Is boolean é `for_save` a thugann comharthaíocht, nuair a dhéanann `True`, go bhfuil an ceist atá á fhorghníomhú ag déanamh cruthú nó nuashonrú.

#### `get_source_expressions()`

Tugann liosta ordaithe de nathanna istigh ar ais. Mar shampla:

```pycon
>>> Sum(F("foo")).get_source_expressions()
[F('foo')]
```

#### `set_source_expressions(expressions)`

Tógann sé liosta nathanna agus stóráilíonn sé iad ionas gur féidir le get\_source\_expressions () iad a thabhairt ar ais.

#### `relabeled_clone(change_map)`

Tugann clón (cóip) de `féin` ar ais, le haon ainmneacha colún athlipéadaithe. Athainmnítear ainmneacha colún nuair a chruthaítear fo-cheisteanna. Ba chóir relabeled\_clone () a ghlaoch freisin ar aon nathanna neadaithe agus a shannadh don chlón.

Is foclóir é `change_map` a mhapáil sean-ainmneacha chuig ainmneacha nua.

Sampla:

```
def relabeled_clone(self, change_map):
    clone = copy.copy(self)
    clone.expression = self.expression.relabeled_clone(change_map)
    return clone
```

#### `convert_value(value, expression, connection)`

Crúca a ligeann don abairt “luach” a chur i gcrích níos oiriúnaí.

Tá `léirithe` mar an gcéanna le `féin`.

#### `get_group_by_cols()`

Freagrach as liosta na dtagairtí colúin a thabhairt ar ais leis an abairt seo. Ba chóir get\_group\_by\_cols () a ghlaoch ar aon abairtí neadaithe. Tá tagairt do cholún go háirithe ag rudaí F () .

#### `asc(nulls_first=None, nulls_last=None)`

Filleann sé an abairt atá réidh le sórtáil in ord ardaitheach.

Sainmhíníonn `nulls_first` agus `nulls_last` conas a shórtáiltear luachanna null. Féach:ref: using-f-to-sort-null-values mar shampla úsáid.

#### `desc(nulls_first=None, nulls_last=None)`

Filleann sé an abairt atá réidh le sórtáil in ord íslitheach.

Sainmhíníonn `nulls_first` agus `nulls_last` conas a shórtáiltear luachanna null. Féach:ref: using-f-to-sort-null-values mar shampla úsáid.

#### `reverse_ordering()`

Tugann sé “féin” ar ais le haon mhodhnuithe a theastaíonn chun an t-ordú sórtála a aisiompú laistigh de ghlao `order_by`. Mar shampla, athródh abairt a chur i bhfeidhm `NULLS LAST` a luach go NULLS FIRST\`. Ní theastaíonn modhnuithe ach le haghaidh nathanna a chuireann ord sórtála i bhfeidhm mar Orderby\`. Tugtar an modh seo nuair a ghlaítear: meth: ~django.db.models.query.queryset.reverse () ar fhiosraith.

### Scríobh do chuid Nathanna Fiosrúcháin

Is féidir leat d'aicmí léirithe fiosrúcháin féin a scríobh a úsáideann nathanna fiosrúcháin eile agus is féidir leo comhtháthú leo. \<func-expressions\>Déanaimis céim trí shampla trí chur i bhfeidhm an fheidhm `COALESCE` SQL a scríobh, gan na nathanna ionsuite: ref: Func () a úsáid.

Sainmhínítear an fheidhm SQL COALESCE\` mar liosta de cholúin nó luachanna a ghlacadh. Cuirfidh sé an chéad cholún nó an luach ar ais nach `NULL`.

Tosóimid tríd an teimpléad atá le húsáid le haghaidh giniúint SQL agus modh \_\_init\_\_ () a shainiú chun roinnt tréithe a shocrú:

```
from django.db.models import Expression

class Coalesce(Expression):
    template = "COALESCE( %(expressions)s )"

    def __init__(self, expressions, output_field):
        super().__init__(output_field=output_field)
        if len(expressions) < 2:
            raise ValueError("expressions must have at least 2 elements")
        for expression in expressions:
            if not hasattr(expression, "resolve_expression"):
                raise TypeError("%r is not an Expression" % expression)
        self.expressions = expressions
```

Déanaimid roinnt bailíochtú bunúsach ar na paraiméadair, lena n-áirítear 2 cholún nó luach ar a laghad a éileamh, agus a chinntiú gur nathanna iad Táimid ag iarraidh:ref: output\_field \<output-field\>\`anseo ionas go mbeidh a fhios ag Django cén cineál réimse samhail chun an toradh deiridh a shannadh dó.

Anois cuirimid an réamhphróiseáil agus bailíochtú i bhfeidhm. Ós rud é nach bhfuil aon cheann dár mbailíochtú féin againn ag an bpointe seo, tarmligimid chuig na nathanna neadaithe:

```
def resolve_expression(
    self, query=None, allow_joins=True, reuse=None, summarize=False, for_save=False
):
    c = self.copy()
    c.is_summary = summarize
    for pos, expression in enumerate(self.expressions):
        c.expressions[pos] = expression.resolve_expression(
            query, allow_joins, reuse, summarize, for_save
        )
    return c
```

Ansin, scríobhaimid an modh atá freagrach as an SQL a ghiniúint:

```
def as_sql(self, compiler, connection, template=None):
    sql_expressions, sql_params = [], []
    for expression in self.expressions:
        sql, params = compiler.compile(expression)
        sql_expressions.append(sql)
        sql_params.extend(params)
    template = template or self.template
    data = {"expressions": ",".join(sql_expressions)}
    return template % data, sql_params

def as_oracle(self, compiler, connection):
    """
    Example of vendor specific handling (Oracle in this case).
    Let's make the function name lowercase.
    """
    return self.as_sql(compiler, connection, template="coalesce( %(expressions)s )")
```

Is féidir le modhanna ```as_sql () ``tacú le hargóintí saincheaptha eochairfhocal, rud a ligeann do mhodhanna ``as_vendorname ()``` sonraí a úsáidtear chun an teaghrán SQL a ghiniúint a shárú. Is fearr argóintí eochairfhocal ```as_sql () ``a úsáid le haghaidh saincheaptha ná ``self``` a athrú laistigh de mhodhanna as\_vendorname ()\` mar is féidir earráidí a bheith mar thoradh ar an dara ceann agus iad ag rith ar chúlpháirteanna éagsúla bunachar sonraí. Má bhíonn do rang ag brath ar thréithe ranga chun sonraí a shainiú, smaoinigh ar sháraitheanna a cheadú i do mhodh as\_sql () \`.

Gineann muid an SQL do gach ceann de na “léirithe” tríd an modh compiler.compiler.compiler () a úsáid, agus cuirimid an toradh in éineacht le camóga. Ansin líontar an teimpléad lenár sonraí agus cuirtear an SQL agus na paraiméadair ar ais.

Tá cur i bhfeidhm saincheaptha sainmhínithe againn freisin atá sonrach don chúlcheann Oracle. Glaofar an fheidhm ```as_oracle () ``in ionad ``as_sql ()``` má tá cúltaca Oracle in úsáid.

Faoi dheireadh, cuirimid an chuid eile de na modhanna i bhfeidhm a ligeann dár léiriú ceisteanna imirt go deas le nathanna ceisteanna eile:

```
def get_source_expressions(self):
    return self.expressions

def set_source_expressions(self, expressions):
    self.expressions = expressions
```

Feicfimid conas a oibríonn sé:

```pycon
>>> from django.db.models import F, Value, CharField
>>> qs = Company.objects.annotate(
...     tagline=Coalesce(
...         [F("motto"), F("ticker_name"), F("description"), Value("No Tagline")],
...         output_field=CharField(),
...     )
... )
>>> for c in qs:
...     print("%s: %s" % (c.name, c.tagline))
...
Google: Do No Evil
Apple: AAPL
Yahoo: Internet Company
Django Software Foundation: No Tagline
```

#### Instealladh SQL a sheachaint

Ós rud é go ndéantar argóintí eochairfhocal `Func` do \_\_init\_\_ () \`\`(\`\`\*\*extra\_context\`)\`\` (`**extra_context`) idirphóilte isteach sa teaghrán SQL seachas a rith mar pharaiméadair cheistiúcháin (áit a n-éalfadh an tiománaí bunachar sonraí iad), ní mór ionchur úsáideora neamhiontaofa iontu.

Mar shampla, má sholáthraítear `foshraithe` ón úsáideoir, tá an fheidhm seo leochaileach do instealladh SQL:

```
from django.db.models import Func

class Position(Func):
    function = "POSITION"
    template = "%(function)s('%(substring)s' in %(expressions)s)"

    def __init__(self, expression, substring):
        # substring=substring is an SQL injection vulnerability!
        super().__init__(expression, substring=substring)
```

Gineann an fheidhm seo teaghrán SQL gan aon pharaiméadair. Ós rud é go gcuirtear `foshraithe` ar aghaidh chuig super (). \_\_init\_\_ () mar argóint eochairfhocal, déantar é a idirphóladh isteach sa teaghrán SQL sula seoltar an cheist chuig an mbunachar sonraí.

Seo athscríobh ceartaithe:

```
class Position(Func):
    function = "POSITION"
    arg_joiner = " IN "

    def __init__(self, expression, substring):
        super().__init__(substring, expression)
```

Le “foshraitheacht” a rith mar argóint seasaimh ina ionad sin, cuirfear ar aghaidh mar pharaiméadar san fhiosrúchán bunachar sonraí.

### Tacaíocht a chur i gcúltaca bunachar sonraí tríú

Má tá cúltaca bunachar sonraí á úsáid agat a úsáideann comhréir SQL difriúil le haghaidh feidhm áirithe, is féidir leat tacaíocht a chur leis trí mhoncaí modh nua a phaiteáil ar rang na feidhme.

Abair go bhfuilimid ag scríobh cúltaca do Freastalaí SQL Microsoft a úsáideann an SQL `LEN` in ionad `LENGTH` don fheidhme:class: ~functions.LENGTH. Déanfaimid moncaí modh nua ar a dtugtar ```as_sqlserver () ``a phaisteáil ar an rang ``Length```:

```
from django.db.models.functions import Length

def sqlserver_length(self, compiler, connection):
    return self.as_sql(compiler, connection, function="LEN")

Length.as_sqlserver = sqlserver_length
```

Is féidir leat an SQL a shaincheapadh freisin ag baint úsáide as an paraiméadar `teimpléad` de as\_sql () \`.

Úsáidimid ```as_sqlserver () ``toisc go bhfilleann ``django.db.connection.vendor``` `sqlserver` don chúltaca.

Is féidir le cúltaca tríú páirtí a gcuid feidhmeanna a chlárú i gcomhad `__init__.py` barr leibhéal an phacáiste cúltaca nó i gcomhad `expressions.py` barr leibhéal (nó pacáiste) a allmhairítear ón leibhéal barr `__init__.py`.

\<django.apps.AppConfig.ready\>Maidir le tionscadail úsáideora atá ag iarraidh an cúltaca atá á úsáid acu a phaiseáil, ba chóir go mbeadh an cód seo i modh: meth: AppConfig.ready () .