# Dokumentasi Django 5.2.8

# Bagaimana menulis pencarian disesuaikan

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 Acuan Pencarian API.

## Contoh pencarian

Mari kita mulai dengan pencarian penyesuaian kecil. Kami akan menulis pencarian penyesuaian `ne` yang bekerj aberlawanan terhadap `exact`. `Author.objects.filter(name__ne='Jack')` akan menterjemahkan ke SQL:

    "author"."name" <> 'Jack'

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

Ada dua langkah untuk membuatnya bekerja. Pertama kami butuh menerapkan pencarian, kemudian kami butuh memberitahu Django mengenai itu:

    from django.db.models import Lookup

    class NotEqual(Lookup):
        lookup_name = "ne"

        def as_sql(self, compiler, connection):
            lhs, lhs_params = self.process_lhs(compiler, connection)
            rhs, rhs_params = self.process_rhs(compiler, connection)
            params = lhs_params + rhs_params
            return "%s <> %s" % (lhs, rhs), params

Untuk mendaftarkan pencarian `NotEqual` kami butuh memanggil `register_lookup` pada bidang kelas kami ingin cari agar tersedia. Dalam kasus ini, pencarian masuk akal pada semua subkelas `Field`, sehingga kami mendaftarkan itu langsung dengan `Field`:

    from django.db.models import Field

    Field.register_lookup(NotEqual)

Pendaftaran pencarian dapat juga dikerjakan menggunakan pola decorator:

    from django.db.models import Field

    @Field.register_lookup
    class NotEqualLookup(Lookup): ...

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

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 `__`.

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()`.

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.

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.

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.

## Contoh transformator

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

Catatan

Contoh ini agak dibikin, tetapi dia menunjukkan jangkauan fungsionalitas yang memungkinkan dalam cara backend basisdata berdisi sendiri, tanpa menggandakan fungsionalitas yang sudah ada di Django.

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

    from django.db.models import Transform

    class AbsoluteValue(Transform):
        lookup_name = "abs"
        function = "ABS"

Selanjutnya, mari kita daftarkan sebagai `IntegerField`:

    from django.db.models import IntegerField

    IntegerField.register_lookup(AbsoluteValue)

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

    SELECT ... WHERE ABS("experiments"."change") = 27

Dengan menggunakan `Transform` instead of `Lookup` itu berarti kami dapat rantai pencarian lebih lanjut sesudahnya. Sehingga``Experiment.objects.filter(change__abs__lt=27)`` akan membangkitkan SQL berikut:

    SELECT ... WHERE ABS("experiments"."change") < 27

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

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

    SELECT ... ORDER BY ABS("experiments"."change") ASC

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

    SELECT ... DISTINCT ON ABS("experiments"."change")

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:

    from django.db.models import FloatField, Transform

    class AbsoluteValue(Transform):
        lookup_name = "abs"
        function = "ABS"

        @property
        def output_field(self):
            return FloatField()

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

## Menulis sebuah pencarian `abs__lt` efisien

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

Jadi kami ingin `Experiment.objects.filter(change__abs__lt=27)` membangkitkan SQL berikut:

    SELECT .. WHERE "experiments"."change" < 27 AND "experiments"."change" > -27

Peneprapannya adalah:

    from django.db.models import Lookup

    class AbsoluteValueLessThan(Lookup):
        lookup_name = "lt"

        def as_sql(self, compiler, connection):
            lhs, lhs_params = compiler.compile(self.lhs.lhs)
            rhs, rhs_params = self.process_rhs(compiler, connection)
            params = lhs_params + rhs_params + lhs_params + rhs_params
            return "%s < %s AND %s > -%s" % (lhs, rhs, lhs, rhs), params

    AbsoluteValue.register_lookup(AbsoluteValueLessThan)

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

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

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.

Catatan

Faktanya, kebanyakan pencarian dengan `__abs` dapat diterapkan sebagai jangkauan permintaan seperti ini, dan pada kebanyakan backend basisdata sepertinya lebih bijaksana untuk dilakukan sehingga anda dapat membuat penggunaan indeks. Bagaimanapun dengan PostgreSQL anda mungkin ingin menambahkan indeks pada `abs(change)` yang akan mengizinkan permintaan ini menjadi lebih efisien.

## Sebuah contoh perubahan timbal balik

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.

Mari kita uji perubahan peka huruf besar-kecil disini. Perubahan ini tidak berguna dalam praktiknya ketika Django datang dengan sekelompok pencarian peka huruf besar-kecil siap pakai, tetapi itu akan menjadi pertunjukkan bagus dari perubahan dua belah pihak dalam cara basisdata-agnostik.

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

    from django.db.models import Transform

    class UpperCase(Transform):
        lookup_name = "upper"
        function = "UPPER"
        bilateral = True

Selanjutnya, mari kita mendaftarkannya:

    from django.db.models import CharField, TextField

    CharField.register_lookup(UpperCase)
    TextField.register_lookup(UpperCase)

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

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

## Menulis penerapan cara lain untuk pencarian yang ada

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

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

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

    Field.register_lookup(MySQLNotEqual)

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

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

## Bagaimana Django menentuka pencarian dan merubah yang sedang digunakan

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:

    class CoordinatesField(Field):
        def get_lookup(self, lookup_name):
            if lookup_name.startswith("x"):
                try:
                    dimension = int(lookup_name.removeprefix("x"))
                except ValueError:
                    pass
                else:
                    return get_coordinate_lookup(dimension)
            return super().get_lookup(lookup_name)

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

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.

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:

- `.filter(myfield__mylookup)` akan memanggil `myfield.get_lookup('mylookup')`.

- `.filter(myfield__mytransform__mylookup)` akan memanggil `myfield.get_transform('mytransform')`, dan lalu `mytransform.get_lookup('mylookup')`.

- `.filter(myfield__mytransform)` akan memanggil pertama `myfield.get_lookup('mytransform')`, yang akan gagal, sehingga dia akan gagal kembali memanggil `myfield.get_transform('mytransform')` dan kemudian `mytransform.get_lookup('exact')`.