{"title":"Penyesuaian Pencarian","version":"2.2","locale":"id","docname":"howto/custom-lookups","url":"/id/2.2/howto/custom-lookups/","canonical":"https://djangodocs.dev/id/2.2/howto/custom-lookups/","summary":"Django menawarkan beragam luas dari built-in lookups untuk penyaringan (sebagai contoh, exact dan icontains).","html":"

Penyesuaian PencarianLink to this heading#

\n

Django menawarkan beragam luas dari built-in lookups untuk penyaringan (sebagai contoh, exact dan icontains). Dokumentasi ini menjelaskan bagaimana menulis penyesuaian pencarian dan bagaimana mengubah pekerjaan dari pencarian yang ada. Untuk acuan API dari pencarian, lihat Lookup API reference.

\n
\n

Sebuah contoh pencarian sederhanaLink to this heading#

\n

Mari kita mulai dengan sebuah penyesuaian pencarian sederhana. Kami akan menulis penyesuaian pencarian ne yang bekerja berlawawan ke exact. Author.objects.filter(name__ne='Jack') akan dirubah ke SQL:

\n
Code
"author"."name" <> 'Jack'\n
\n

Backend SQL berdisi sendiri, sehingga kita tidak perlu khawatir tentang basisdata berbeda.

\n

Terdapat dua langkah untuk membuat ini bekerja. Pertama kami butuh menerapkan pencarian, kemudian kami butuh mengatakan Django tentang ini. Penerapannya sangat mudah:

\n
Code
from django.db.models import Lookup\n\nclass NotEqual(Lookup):\n    lookup_name = 'ne'\n\n    def as_sql(self, compiler, connection):\n        lhs, lhs_params = self.process_lhs(compiler, connection)\n        rhs, rhs_params = self.process_rhs(compiler, connection)\n        params = lhs_params + rhs_params\n        return '%s <> %s' % (lhs, rhs), params\n
\n

Untuk mendaftar pencarian NotEqual kami akan butuh memanggil register_lookup pada kelas bidang kami ingin pencarian menjadi tersedia. Dalam kasus ini, pencarian dapat dimengerti pada semua subkelas Field, jadi kami mendaftarkannya dengan Field secara langsung:

\n
Code
from django.db.models.fields import Field\nField.register_lookup(NotEqual)\n
\n

Pendaftaran pencarian dapat juga dikerjakan menggunakan pola decorator:

\n
Code
from django.db.models.fields import Field\n\n@Field.register_lookup\nclass NotEqualLookup(Lookup):\n    # ...\n
\n

Kami sekarang dapat menggunakan foo__ne untuk setiap bidang foo. Anda akan butuh memastikan bahwa pendaftaran ini terjadi sebelum anda mencoba membuat kumpulan permintaan menggunakannya. Anda dapat menempatkan penerapan dalam sebuah berkas models.py, atau mendaftarkan pencarian dalam cara ready() dari sebuah AppConfig.

\n

Melihat lebih dekat pada penerapan, atribut dibutuhkan pertama adalah lookup_name. Ini mengizinkan ORM untuk memahami bagaimana mengartikan name__ne dan menggunakan NotEqual untuk membangkitkan SQL. Berdasarkan pemufakatan, nama-nama ini selalu deretan karakter huruf kecil mengandung hanya huruf, tetapi persyaratan mutlak adalah bahwa itu harus mengandung deretan karakter __.

\n

Kami lalu butuh menentukan cara as_sql. Ini mengambil obyek SQLCompiler, disebut compiler, dan hubungan aktif basisdata. Obyek SQLCompiler tidak didokumentasikan, tetapi satu-satunya kami butuh diketahui tentang mereka adalah bahwa mereka mempunyai cara compile() yang mengemblikan sebuah tuple mengandung deretan karakter SQL, dan parameter untuk disisipkan kedalam deretan karakter itu. Di kebanyakan kasus, anda tidak butuh menggunakannya secara langsung dan dapat melewatinya ke process_lhs() dan process_rhs().

\n

Sebuah Lookup bekerja terhadap dua nilai, lhs dan rhs, kepanjangan dari left-hand side dan right-hand side. Left-hand side biasanya acuan bidang, tetapi dia dapat menjadi apapun menerapkan query expression API. Right-hand adalah nilai diberikan oleh pengguna. Dalam contoh Author.objects.filter(name__ne='Jack'), sisi tangan-kanan adalah sebuah acuan pada bidang name dari model Author, dan 'Jack' adalah the right-hand side.

\n

Kami memanggil process_lhs dan process_rhs untuk merubah mereka kedalam nilai-nilai kami butuh untuk SQL menggunakan obyek compiler digambarkan sebelumnya. Cara ini mengembalikan tuple mengandung beberapa SQL dan parameter untuk ditambahkan kedaam SQL itu, seperti yang kita perlu untuk mengembalikan cara as_sql kami. Dalam contoh diatas, process_lhs mengembalikan ('"author"."name"', []) dan process_rhs mengembalikan ('"%s"', ['Jack']). Dalam contoh ini tidak ada parameter untuk left hand side, tetapi ini akan tergantung pada obyek kita punya, jadi jami masih butuh menyertakan merekan dalam parameter kami kembalikan.

\n

Akhirnya kami menggabungkan bagian-bagian kedalam sebuah pernyataan SQL dengan <>, dan memasok semua parameter untuk permintaan. Kami lalu mengambalikan sebuah tuple mengandung deretan karakter SQL dan parameter yang dibangkitkan.

\n
\n
\n

Contoh perubahan sederhanaLink to this heading#

\n

Penyesuaian pencarian diatas adalah hebat, tetapi dalam beberapa kasus anda mungkin ingin dapat merangkai pencarian bersama-sama. Sebagai contoh, mari kita misalnya kami sedang membangun sebuah aplikasi dimana kami ingin membuat penggunaan dari operator abs(). Kami mempunyai sebuah model Experiment yang merekam sebuah nilai awal, nilai akhir, dan perubahan (awal - akhir). Kami akan suka menemukan semua percobaan dimana perubahan setara pada bilangan tertentu (Experiment.objects.filter(change__abs=27)), atau dimana itu tidak melebihi bilangan tertentu (Experiment.objects.filter(change__abs__lt=27)).

\n\n

Kami akan mulai dengan menulis sebuah perubahan AbsoluteValue. Ini akan menggunakan fungsi SQL ABS() untuk merubah nilai sebelum dibandingkan:

\n
Code
from django.db.models import Transform\n\nclass AbsoluteValue(Transform):\n    lookup_name = 'abs'\n    function = 'ABS'\n
\n

Selanjutnya, mari kita daftarkan sebagai IntegerField:

\n
Code
from django.db.models import IntegerField\nIntegerField.register_lookup(AbsoluteValue)\n
\n

Kami dapat sekarang menjalankan permintaan kami punyai sebelumnya. Experiment.objects.filter(change__abs=27) akan membangkitkan SQL berikut:

\n
Code
SELECT ... WHERE ABS("experiments"."change") = 27\n
\n

Dengan menggunakan Transform dari pada Lookup itu berarti kami dapat merangkai pencarian lebih lanjut setelahnya. Jadi Experiment.objects.filter(change__abs__lt=27) akan membangkitkan SQL berikut:

\n
Code
SELECT ... WHERE ABS("experiments"."change") < 27\n
\n

Catat bahwa dalam kasus terdapat tidak ada pencarian lain yang ditentukan, Django menterjemahkan change__abs=27 sebagai change__abs__exact=27.

\n

Ini juga mengizinkan hasil digunakan dalam klausa ORDER BY dan DISTINCT ON. Sebagai contoh Experiment.objects.order_by('change__abs') membangkitkan:

\n
Code
SELECT ... ORDER BY ABS("experiments"."change") ASC\n
\n

Dan pada basisdata yang mendukung perbedaan pada bidang (seperti PostgreSQL), Experiment.objects.distinct('change__abs') membangkitkan:

\n
Code
SELECT ... DISTINCT ON ABS("experiments"."change")\n
\n\n

Ketika mencari pencarian mana yang diizinkan setelah Transform diberlakukan, Django menggunakan atribut output_field. Kami tidak butuh menentukan ini disini jika itu tidak berubah, tetapi seharusnya kami memberlakukan AbsoluteValue pada beberapa bidang yang mewakili jenis lebih rumit (sebagai contoh sebuah titik relatif ke yang asli, atau angka rumit) kemudian kami mungkin ingin menentukan bahwa perubahan mengembalikan jenis FloatField untuk pencarian lebih lanjut. Ini dapat dikerjakan dengan menambahkan sebuah atribut output_field untuk perubahan:

\n
Code
from django.db.models import FloatField, Transform\n\nclass AbsoluteValue(Transform):\n    lookup_name = 'abs'\n    function = 'ABS'\n\n    @property\n    def output_field(self):\n        return FloatField()\n
\n

Ini memastikan bahwa pencarian lebih lanjut seperti abs__lte berperilaku seperti mereka lakukan untuk FloatField.

\n
\n
\n

Menulis sebuah pencarian abs__lt efisienLink to this heading#

\n

Ketika menggunakan penulisan diatas pencarian abs, keluaran SQL tidak menggunakan indeks secara efisien dalam beberapa kasus. Khususnya, ketika kami menggunakan change__abs__lt=27, ini setara pada change__gt=-27 AND change__lt=27. (Untuk kasus lte kami akan menggunakan SQL BETWEEN).

\n

Jadi kami akan Experiment.objects.filter(change__abs__lt=27) untuk membangkitkan SQL berikut:

\n
Code
SELECT .. WHERE "experiments"."change" < 27 AND "experiments"."change" > -27\n
\n

Peneprapannya adalah:

\n
Code
from django.db.models import Lookup\n\nclass AbsoluteValueLessThan(Lookup):\n    lookup_name = 'lt'\n\n    def as_sql(self, compiler, connection):\n        lhs, lhs_params = compiler.compile(self.lhs.lhs)\n        rhs, rhs_params = self.process_rhs(compiler, connection)\n        params = lhs_params + rhs_params + lhs_params + rhs_params\n        return '%s < %s AND %s > -%s' % (lhs, rhs, lhs, rhs), params\n\nAbsoluteValue.register_lookup(AbsoluteValueLessThan)\n
\n

Terdapat sepasang hal penting sedang terjadi. Pertama, AbsoluteValueLessThan tidak memanggil process_lhs(). Malahan dia melewati perubahan dari lhs dikerjakan oleh AbsoluteValue dan menggunakan lhs asli. Yaitu, kami ingin mendapatkan "experiments"."change" bukan ABS("experiments"."change"). Mengacu secara langsung pada self.lhs.lhs adalah aman AbsoluteValueLessThan dapat diakses hanya dari pencarian AbsoluteValue, yaitu lhs selalu sebuah instance dari AbsoluteValue.

\n

Perhaikan juga bahwa kedua sisi menggunakan banyak waktu dalam permintaan parameter butuh untuk dikandung lhs_params dan rhs_params banyak waktu.

\n

Permintaan akhir melakukan pembalikan (27 ke -27) secara langsung di basisdata. Alasan untuk melakukan ini adalah bahwa jika self.rhs sesuatu lain daripada nilai integer polos (sebagai contoh sebuah acuan F()) kami tidak dapat melakukan perubahan dalam Python.

\n\n
\n
\n

Sebuah contoh perubahan timbal balikLink to this heading#

\n

Contoh AbsoluteValue kami obrolkan sebelumnya adalah sebuah perubahan yang berlaku pada left-hand side dari pencarian. Mungkin disana beberapa kasus dimana anda ingin perubahan diberlakukan pada kedua left-hand side and the right-hand side. Sebagai contoh, jika anda ingin menyaring kumpulan permintaan berdasarkan pada persamaan left and right-hand side kebal pada beberapa fungsi SQL.

\n

Mari kita ujikan contoh sederhana dari perubahan kasus tidak peka disini. Perubahan ini tidak sangat berguna dalam praktiknya ketika Django sudah datang dengan seikat pencarian siap pakai tidak peka, tetapi dia akan menjadi pertunjukan bagus dari perubahan timbal balik dalam sebuah cara basisdata-agnostik.

\n

Kami menentukan sebuab perubahan UpperCase` yang menggunakan fungsi SQL UPPER() untuk merubah nilai sebelum dibandingkan. Kami menentukan bilateral = True untuk mengindikasikan bahwa perubahan ini harus berlaku pada kedua lhs and rhs:

\n
Code
from django.db.models import Transform\n\nclass UpperCase(Transform):\n    lookup_name = 'upper'\n    function = 'UPPER'\n    bilateral = True\n
\n

Selanjutnya, mari kita mendaftarkannya:

\n
Code
from django.db.models import CharField, TextField\nCharField.register_lookup(UpperCase)\nTextField.register_lookup(UpperCase)\n
\n

Sekarang, kumpulan permintaan Author.objects.filter(name__upper="doe") akan membangkitkan sebuah permintaan kasus tidak peka seperti ini:

\n
Code
SELECT ... WHERE UPPER("author"."name") = UPPER('doe')\n
\n
\n
\n

Menulis penerapan cara lain untuk pencarian yang adaLink to this heading#

\n

Terkadang penjaja basisdata berbeda membutuhkan SQL berbeda untuk pekerjaan yang sama. Untuk contoh ini kami akan menulis kembali sebuah penyesuaian penerapan untuk MySQL untuk penghubung NotEqual. Dari pada <> kami akan menggunakan penghubung !=. (Catat bahwa dalam kenyataan hampir semua basisdata mendukung keduanya, termasuk semua basisdata resmi didukung oleh Django).

\n

Kami dapat merubah perilaku pada backend khusus dengan membuat subkelas dari NotEqual dengan sebuah metode as_mysql:

\n
Code
class MySQLNotEqual(NotEqual):\n    def as_mysql(self, compiler, connection, **extra_context):\n        lhs, lhs_params = self.process_lhs(compiler, connection)\n        rhs, rhs_params = self.process_rhs(compiler, connection)\n        params = lhs_params + rhs_params\n        return '%s != %s' % (lhs, rhs), params\n\nField.register_lookup(MySQLNotEqual)\n
\n

Kami dapat mendaftarkannya dengan Field. Dia memakan tempat dari kelas NotEqual asli seperti dia mempunyai lookup_name sama.

\n

Ketika menyusun sebuah permintaan, Django pertama mencari cara as_%s % connection.vendor, dan kemudian kembali ke as_sql. Nama penjaja untuk membangun backend adalah sqlite, postgresql, oracle dan mysql.

\n
\n
\n

Bagaimana Django menentuka pencarian dan merubah yang sedang digunakanLink to this heading#

\n

Dalam beberapa kasus anda mungkin berharap untuk secara dinamis merubah Transform atau Lookup dikembalikan berdasarkan pada nama dilewatkan, daripada memperbaikinya. Sebagai sebuah contoh, anda dapat mempunyai sebuah bidang yang menyimpan kordinat atau dimensi berubah-ubah dan berharap untuk mengizinkan sebuah sintaksis seperti .filter(coords__x7=4) untuk mengembalikan obyek dimana kordinat 7 mempunyai nilai 4. Untuk melakukan ini, anda akan menimpa get_lookup dengan sesuatu seperti:

\n
Code
class CoordinatesField(Field):\n    def get_lookup(self, lookup_name):\n        if lookup_name.startswith('x'):\n            try:\n                dimension = int(lookup_name[1:])\n            except ValueError:\n                pass\n            else:\n                return get_coordinate_lookup(dimension)\n        return super().get_lookup(lookup_name)\n
\n

Anda kemudian akan menentukan get_coordinate_lookup dengan benar untuk mengembalikan sebuah subkelas Lookup yang menangani nilai yang terkait dari dimension.

\n

Ada cara yang dinamai mirip dipanggil get_transform(). get_lookup() harus selalu mengembalikan sebuah subkelas Lookup, dan Lookup sebuah subkelas Transform. Itu sangat penting diingat bahwa obyek Transform dapat lebih jauh disaring, dan obyek Lookup tidak dapat.

\n

Ketika menyaring, jika hanya ada satu nama pencarian tersisa untuk diselesaikan, kami akan mencari sebuah Lookup. Jika ada banyak nama, dia akan mencari sebuah Transform. Dalam keadaan dimana hanya ada satu nama dan sebuah Lookup tidak ditemukan, kami mencari sebuah Transform dan kemudian pencarian exact pada Transform tersebut. Semua panggilan selalu berurutan diakhiri dengan sebuah Lookup. Untuk menjelaskan:

\n\n
","rootId":"custom-lookups","toc":[{"title":"Sebuah contoh pencarian sederhana","anchor":"a-simple-lookup-example","children":[]},{"title":"Contoh perubahan sederhana","anchor":"a-simple-transformer-example","children":[]},{"title":"Menulis sebuah pencarian abs__lt efisien","anchor":"writing-an-efficient-abs-lt-lookup","children":[]},{"title":"Sebuah contoh perubahan timbal balik","anchor":"a-bilateral-transformer-example","children":[]},{"title":"Menulis penerapan cara lain untuk pencarian yang ada","anchor":"writing-alternative-implementations-for-existing-lookups","children":[]},{"title":"Bagaimana Django menentuka pencarian dan merubah yang sedang digunakan","anchor":"how-django-determines-the-lookups-and-transforms-which-are-used","children":[]}],"breadcrumbs":[{"docname":"howto/index","title":"Panduan \"Bagaimana\"","url":"/id/2.2/howto/"}],"prev":{"docname":"howto/custom-model-fields","title":"Menulis bidang model penyesuaian","url":"/id/2.2/howto/custom-model-fields/"},"next":{"docname":"howto/custom-template-tags","title":"Penyesuaian etiket cetakan dan saringan","url":"/id/2.2/howto/custom-template-tags/"},"formats":{"html":"/id/2.2/howto/custom-lookups/","markdown":"/id/2.2/howto/custom-lookups.md","json":"/id/2.2/howto/custom-lookups.json"},"source":"https://github.com/django/django/blob/stable/2.2.x/docs/howto/custom-lookups.txt","official":"https://docs.djangoproject.com/id/2.2/howto/custom-lookups/","inVersions":["6.1","6.0","5.2","5.1","5.0","4.2","4.1","4.0","3.2","3.1","3.0","2.2","2.1","2.0","1.11","1.10","1.9"],"inLocales":["en","zh-hans","fr","ja","id","pt-br","ko","es","el","pl"]}