--- title: "Tagairt API cuardaigh" version: 5.2 locale: ga source: https://docs.djangoproject.com/ga/5.2/ref/models/lookups/ canonical: https://djangodocs.dev/ga/5.2/ref/models/lookups/ --- # Tagairt API cuardaigh Tá tagairtí API na cuardaigh sa doiciméad seo, an API Django chun clásal `WHERE` d'fhiosrúchán bunachar sonraí a thógáil. Chun foghlaim conas\* cuardaithe\* a úsáid, féach: doc: /topics/db/queries; chun foghlaim conas\*cuardaigh nua\* a chruthú, féach: doc: /howto/custom-lookups. Tá dhá chomhpháirt ag an API cuardaigh: a:class: ~Lookups.RegisterLookUpMixin aicme a chláraíonn cuardaigh, agus an:ref: Query Expression API \, sraith modhanna a chaithfidh rang a chur i bhfeidhm chun a bheith inchláraithe mar chuardach. Tá dhá rang bonn ag Django a leanann an API abairt fiosrúcháin agus ón áit a ndíorthaítear gach cuardach tógtha Django: - [`Lookup`](#django.db.models.Lookup): to lookup a field (e.g. the `exact` of `field_name__exact`) - [`Transform`](#django.db.models.Transform): to transform a field Is éard atá i léiriú cuardaigh trí chuid: - Cuid réimsí (m.sh. Book.Objects.Filter (author\_\_best\_friends\_\_first\_name... \`); - Athraíonn sé cuid (féadfar é a fhágáil) (m.sh. `__lower__first3chars__reversed`); - Cuardach (m.sh. `__icontains`) a thagann réamhshocraithe go `__exact` má fhágtar amach. ## API Clárúcháin Úsáideann Django: class: ~Lookups.RegisterLookUpMixin chun an comhéadan a thabhairt do rang chun cuardaigh a chlárú air féin nó ar a chásanna. Is iad an dá shampla suntasach ná: aicme: ~django.db.models.field, bunaicme gach réimse samhail, agus:class: Transform, bunaicme gach Django a athraíonn. #### `class lookups.RegisterLookupMixin` Mixin a chuireann an API cuardaigh i bhfeidhm ar rang. #### `classmethod register_lookup(lookup, lookup_name=None)` Cláraíonn sé cuardach nua sa rang nó sa rang. Mar shampla: ``` DateField.register_lookup(YearExact) User._meta.get_field("date_joined").register_lookup(MonthExact) ``` \cláróidh sé cuardach ```YearExact ``ar `DateField``` agus `MonthExact` cuardach ar `User.Date_Joined` (is féidir leat:ref: Field Access API \`a úsáid chun sampla réimse amháin a aisghabháil). Sáraíonn sé cuardach atá ann cheana leis an ainm céanna. Tá tosaíocht ag cuardaigh atá cláraithe ar chásanna allamuigh seachas na cuardaigh atá cláraithe ar ranganna. Úsáidfear \`\`lookup\_name\` don chuardach seo má chuirtear ar fáil, ar shlí eile úsáidfear `lookup.lookup_name`. #### `get_lookup(lookup_name)` Filleann sé an:class: Lookup darb ainm `lookup_name` atá cláraithe sa rang nó sa rang ag brath ar an méid a ghlaonn air. Breathnaíonn an cur i bhfeidhm réamhshocraithe go athshlánach ar gach rang tuismitheora agus seiceálann sé an bhfuil cuardach cláraithe ag duine ar bith darb ainm lookup\_name\`, agus an chéad chluiche ar ais. Déanfadh cuardach samplaí a shárú ar aon chuardach ranga leis an `lookup_name` céanna. #### `get_lookups()` Tugann foclóir ar ais de gach ainm cuardaigh atá cláraithe sa rang nó sa rang atá mapáilte chuig rang:class: Lookup. #### `get_transform(transform_name)` Tuairisceáin a:class: Transform darb ainm `transform_name` cláraithe sa rang nó i gcás ranga. Breathnaíonn an cur i bhfeidhm réamhshocraithe go athshlánach ar gach rang tuismitheora chun a sheiceáil an bhfuil an claochlú cláraithe darb ainm transform\_name\` ag aon duine, ag tabhairt ar ais an gcéad \Chun rang a bheith ina chuardach, caithfidh sé an: ref: Query Expression API \`a leanúint. Leanann: class: \`~Lookup agus:class: ~Transform an API seo go nádúrtha. ## An API Léiriú Fiosrúcháin Is sraith coitianta modhanna é an API abairt fiosrúcháin a shainmhíníonn ranganna le bheith inúsáidte in abairtí fiosrúcháin chun iad féin a aistriú go nathanna SQL. Is samplaí iad tagairtí díreacha réimse, comhiomláin, agus Transform \`\` \`\` \`\` \`\` \`\` \`\` \` Deirtear go leanann rang an API abairt fiosrúcháin nuair a chuireann sé na modhanna seo a leanas i bhfeidhm: #### `as_sql(compiler, connection)` Gineann sé an blúire SQL don abairt. 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. Is réad `SQLcompiler` é an compiler\`, a bhfuil modh ```compileáil () ``aige is féidir a úsáid chun nathanna eile a thiomsú. Is é an `nasc``` an nasc a úsáidtear chun an ceist a fhorghníomhú. Is gnách go mbíonn glaoch ar ```expression.as_sql () ``mícheart - ina ionad sin ba chóir ``compiler.compiler.compilation (focal)``` a úsáid. Tabharfaidh an modh compiler.compiler.compilation () aire do mhodhanna an abairt a ghlaoch ar mhodhanna sonracha don dhíoltóir. Féadfar argóintí eochairfhocal saincheaptha a shainiú ar an modh seo más dóichí go mbeidh ar mhodhanna nó fo-aicmí as\_vendorname () \`sonraí a sholáthar chun giniúint an teaghrán SQL a shárú. Féach: Meth: \`Func.as\_sql mar shampla úsáid. #### `as_vendorname(compiler, connection)` Oibríonn sé cosúil le modh as\_sql () \`. Nuair a thiomsaíonn abairt ag ```compiler.compiler () ``, déanfaidh Django iarracht glaoch ar ``as_vendorname ()``` ar dtús, áit a bhfuil vendorname\` ainm díoltóra an chúltaca a úsáidtear chun an cheist a fhorghníomhú. Tá an `vendorname` ar cheann de `postgresql`, `oracle`, sqlite\`, nó `mysql` le haghaidh cúltaca ionsuite Django. #### `get_lookup(lookup_name)` Ní mór an cuardach darb ainm `lookup_name` a thabhairt ar ais. Mar shampla, trí self.output\_field.get\_lookup (lookup\_name) a thabhairt ar ais. #### `get_transform(transform_name)` Ní mór an cuardach darb ainm `transform_name` a thabhairt ar ais. Mar shampla, trí self.output\_field.get\_transformer (transform\_name) a thabhairt ar ais. #### `output_field` Sainmhíníonn an cineál ranga a chuirtear ar ais leis an modh get\_lookup () . Caithfidh sé a: class: ~django.db.models.field sampla. ## Tagairt `Transform` #### `class Transform` Is aicme cineálach é `Transform` chun claochlú allamuigh a chur i bhfeidhm. Sampla suntasach is ea `__year` a athraíonn `DataField` go `ComhlánField`. \\Is é `__` \`\` Transform ``a úsáid i léiriú cuardaigh (m.sh. `dáta__bliain``). \\\Leanann an rang seo an:ref: Query Expression API \, rud a thugann le tuiscint gur féidir leat `__ __` a úsáid. Is léiriú speisialaithe é: ref: Func () \\`nach nglacann ach argóint amháin. Is féidir é a úsáid freisin ar thaobh na láimhe deise de scagaire nó go díreach mar anótáil. #### `bilateral` Boolean a léiríonn an chóir go mbeadh feidhm ag an gclaochlú seo maidir le lhs\` agus rhs\` araon. Cuirfear claochlú déthaobhacha i bhfeidhm ar `rhs` san ord céanna agus atá le feiceáil sa léiriú cuardaigh. De réir réamhshocraithe tá sé socraithe go `False`. Mar shampla úsáid, féach: doc: /howto/custom-lookups. #### `lhs` An taobh clé - cad atá á athrú. \Caithfidh sé an: ref: Fiosraithe Expression API a leanúint. #### `lookup_name` Ainm an chuardaigh, a úsáidtear chun é a aithint ar nathanna fiosrúcháin a pháirseáil. Ní féidir leis an sreang `"__"` a bheith ann. #### `output_field` Sainmhíníonn an rang a aschuireann an claochlú seo Caithfidh sé a: class: ~django.db.models.field sampla. De réir réamhshocraithe tá sé mar an gcéanna lena lhs.output\_field\`. ## Tagairt `` `Lookup `` #### `class Lookup` Is aicme cineálach é `Lookup` chun cuardaigh a chur i bhfeidhm. Is léiriú fiosrúcháin é cuardach le taobh clé, :attr: lhs; taobh ar dheis, :attr: rhs; agus `lookup_name` a úsáidtear chun comparáid boolean a tháirgeadh idir lhs\` agus rhs\` mar `lhs i rhs` nó `lhs > rhs`. \\Is é `__ =` an príomh-nótaí chun cuardach a úsáid i abairt. Is féidir cuardaigh a úsáid go díreach i scagairí QuerySet\`: ``` Book.objects.filter(LessThan(F("word_count"), 7500)) ``` ... nó anótaí: ``` Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500)) ``` #### `lhs` An taobh clé - cad atá á breathnú suas. \De ghnáth leanann an réad an:ref: Fiosraithe Expression API . D'fhéadfadh sé a bheith ina luach simplí freisin. #### `rhs` An taobh na láimhe deise - cad atá lhs\` á chur i gcomparáid ina choinne. Is féidir é a bheith ina luach simplí, nó rud éigin a thiomsaíonn isteach i SQL, de ghnáth rud ```F () ``nó ``QuerySet```. #### `lookup_name` Ainm an chuardaigh seo, a úsáidtear chun é a aithint ar nathanna fiosrúcháin a pháirseáil. Ní féidir leis an sreang `"__"` a bheith ann. #### `prepare_rhs` Réamhshocraithe go `True`. Nuair: attr: Is luach simplí é rhs, :attr: prepare\_rhs cinneann an chóir é a ullmhú le húsáid mar pharaiméadar i bhfiosrúchán. \D'fhonn é sin a dhéanamh, tugtar ```lhs.output_field.get_prep_value () ``má shainmhínítear, nó tá `rhs``` fillte in:class: Value () ar shlí eile. #### `process_lhs(compiler, connection, lhs=None)` Tugann sé tuple `(lhs_string, lhs_params)` ar ais ag ```compiler.compiler.compiler (lhs) ``. Is féidir an modh seo a shárú chun an chaoi a ndéantar an `lhs``` a phróiseáil a thiúnadh. Is réad `sqlcompiler` é compiler\`, le húsáid cosúil le ```compiler.compiler.compiler (lhs) ``chun `lhs``` a thiomsú. Is féidir an `nasc` a úsáid chun SQL sonrach don díoltóir a thiomsú. Mura bhfuil `lhs` `None`, bain úsáid as mar an lhs\` próiseáilte in ionad `self.lhs`. #### `process_rhs(compiler, connection)` Iompraíonn sé ar an mbealach céanna le: meth: process\_lhs, don taobh na láimhe deise.