Menyimpan bidang ForeignKey dan ManyToManyField¶

Updating a ForeignKey field works exactly the same way as saving a normal field -- assign an object of the right type to the field in question. This example updates the blog attribute of an Entry instance entry, assuming appropriate instances of Entry and Blog are already saved to the database (so we can retrieve them below):

>>> from blog.models import Blog, Entry
>>> entry = Entry.objects.get(pk=1)
>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")
>>> entry.blog = cheese_blog
>>> entry.save()

Memperbaharui sebuah ManyToManyField bekerja sedikit berbeda -- gunakan metode add() pada bidang untuk menambahkan rekaman ke hubungan. Contoh ini menambahkan instance Author joe ke obyek entry:

>>> from blog.models import Author
>>> joe = Author.objects.create(name="Joe")
>>> entry.authors.add(joe)

Untuk menambahkan banyak rekaman pada ManyToManyField dalam sekali pergi, sertakan banyak argumen dalam panggilan pada add(), seperti ini:

>>> john = Author.objects.create(name="John")
>>> paul = Author.objects.create(name="Paul")
>>> george = Author.objects.create(name="George")
>>> ringo = Author.objects.create(name="Ringo")
>>> entry.authors.add(john, paul, george, ringo)

Django akan mengeluh jika anda mencoba memberikan atau menambahkan sebuah obyek dari jenis salah.

Mengambil semua obyek¶

Cara termudah untuk mengambil obyek dari sebuah tabel adalah mendapatkan semua dari mereka. Untuk melakukan ini, gunakan metode all() pada sebuah Manager:

>>> all_entries = Entry.objects.all()

Metode all() mengembalikan semua QuerySet dari semua obyek dalam basisdata.

Mengambil obyek spesifik dengan menyaring¶

QuerySet dibalikkan oleh all() menggambarkan semua obyek-obyek dalam tabel basisdata. Biasanya, meskipun, anda akan butuh memilih hanya sub kumpulan dari kumpulan lengkap dari obyek.

Untuk membuat semacam sub kumpulan, anda menyaring QuerySet awalan, menambahkan kondisi penyaringan. Dua cara paling umum untuk menyaring QuerySet adalah:

filter(**kwargs)

Mengembalikan QuerySet baru mengandung obyek-obyek yang cocok dari parameter pencarian yang diberikan.

exclude(**kwargs)

Mengembalikan QuerySet baru mengandung obyek-obyek yang tidak cocok dari parameter pencarian yang diberikan.

Parameter pencarian (**kwargs dalam penertian fungsi diatas) harus berupa dalam bentuk digambarkan dalam Field lookups dibawah.

Sebagai contoh, untuk mendapatkan QuerySet dari masukan blog dari tahun 2006, gunakan filter() seperti itu:

Entry.objects.filter(pub_date__year=2006)

Dengan kelas pengelola awalan, itu adalah sama seperti:

Entry.objects.all().filter(pub_date__year=2006)

>>> Entry.objects.filter(
...     headline__startswith='What'
... ).exclude(
...     pub_date__gte=datetime.date.today()
... ).filter(
...     pub_date__gte=datetime.date(2005, 1, 30)
... )

>>> q1 = Entry.objects.filter(headline__startswith="What")
>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())
>>> q3 = q1.filter(pub_date__gte=datetime.date.today())

>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.date.today())
>>> q = q.exclude(body_text__icontains="food")
>>> print(q)

Mengambil obyek tunggal dengan get()¶

filter() akan selalu memberikan anda QuerySet, bahkan jika hanya obyek tunggal yang cocok permintaan - dalam kasus ini, itu akan berupa QuerySet mengandung unsur tunggal.

Jika anda mengetahui hanya ada satu obyek yang cocok permintaan anda, anda dapat menggunakan metode meth:~django.db.models.query.QuerySet.get pada sebuah Manager yang mengembalikan obyek secara langsung:

>>> one_entry = Entry.objects.get(pk=1)

Anda dapat menggunakan pernyataan permintaan apapun dengan get(), seperti dengan filter() - kembali, lihat Field lookups dibawah.

Catat bahwa ada perbedaan diantara menggunakan get(), dan menggunakan filter() dengan potongan [0]. Jika tidak ada hasil yang cocok dengan permintaan, get() akan memunculkan pengecualian DoesNotExist. Pengecualian ini adalah sebuah atribut dari kelas model yang permintaan sedang dilakukan - jadi dalam kode diatas, jika tidak ada obyek Entry dengan primary key dari 1, Django akan memunculkan Entry.DoesNotExist.

Demikain pula, Django akan mengeluh jika lebih dari satu barang cocok permintaan get(). Dalam kasus ini, itu akan memunculkan MultipleObjectsReturned, yang kembali adalah sebuah atribut dari kelas model itu sendiri.

Cara QuerySet lain¶

Kebanyakan waktu anda akan gunakan all(), get(), filter() dan exclude() ketika anda butuh mencari obyek-obyek dari basisdata. Bagaimanapun, itu jauh dari semua yang ada; lihat QuerySet API Reference untuk daftar lengkap dari semua ragam metode QuerySet.

Membatasi QuerySet¶

Gunakan sub kumpulan dari sintaksis memotong-array Python untuk membatasi QuerySet anda pada nomor tertentu dari hasil. Ini adalah setara daro klausa LIMIT dan OFFSET SQL.

Sebagai contoh, ini mengembalikan 5 obyek pertama (LIMIT 5):

>>> Entry.objects.all()[:5]

Ini mengembalikan enam dari 10 obyek (OFFSET 5 LIMIT 5):

>>> Entry.objects.all()[5:10]

Pengindeksan negatif (yaitu Entry.objects.all()[-1]) tidak didukung.

Umumnya, memotong QuerySet mengembalikan QuerySet baru -- itu tidak menilai permintaan. Sebuah pengevualian jika anda menggunakan parameter "step" dari sintaksis potongan Python. Sebagai contoh, ini akan sebenarnya menjalankan permintaan untuk menjalankan daftar dari setiap detik obyek dari 10 pertama:

>>> Entry.objects.all()[:10:2]

Penyaring atau pengurut lebih lanjut dari irisan queryset dilarang karena sifat ambigu dari bagaimana itu mungkin bekerja.

To retrieve a single object rather than a list (e.g. SELECT foo FROM bar LIMIT 1), use an index instead of a slice. For example, this returns the first Entry in the database, after ordering entries alphabetically by headline:

>>> Entry.objects.order_by('headline')[0]

Ini kurang lebih setara pada:

>>> Entry.objects.order_by('headline')[0:1].get()

Catat, bagaimanapun, yang pertama dari ini akan memunculkan IndexError selagi kedua akan memunculkan DoesNotExist jika tidak ada obyek cocok dari kriteria yang diberikan. Lihat get() untuk rincian lebih.

Bidang pencarian¶

Pencarian bidang adalah bagaimana anda menentukan isi dari sebuah klausa SQL WHERE. Mereka ditentukan sebagai argumen kata kunci pada QuerySet metode metode filter(), exclude() dan get().

Argumen kata kunci pencarian dasar mengambil formulir field__lookuptype=value. (Itu adalah garis bawah ganda). Sebagai contoh:

>>> Entry.objects.filter(pub_date__lte='2006-01-01')

terjemahan (kurang lebih) ke dalam SQL berikut:

SELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';

Bidang ditentukan dalam pencarian harus berupa nama dari bidang model. meskipun ada satu pengecualian, dalam kasus dari ForeignKey anda dapat menentukan nama bidang akhiran dengan _id. Dalam kasus ini, parameter nilai diharapkan mengandung nilai mentah dari foreign primary key model. Sebagai contoh:

>>> Entry.objects.filter(blog_id=4)

Jika anda melewatkan argumen kata kunci tidak sah, fungsi pencarian akan memunculkan TypeError.

API basisdata mendukung sekitar dua lusin jenis pencarian; acuan lengkap dapat ditemukan dalam field lookup reference 1. Untuk memberikan anda selera dari apa yang tersedia, ini adalah beberapa dari pencarian lebih umum anda mungkin gunakan:

exact

Sebuah pencocokan "tepat". Sebagai contoh:

>>> Entry.objects.get(headline__exact="Cat bites dog")

Akan membangkitkan SQL bersama baris ini:

SELECT ... WHERE headline = 'Cat bites dog';

Jika anda tidak menyediakan jenis pencarian -- yaitu, jika argumen kata kunci anda tidak mengandung garis bawah ganda -- jenis pencarian dianggap tepat.

Sebagai contoh, dua pernyataan berikut adalah setara:

>>> Blog.objects.get(id__exact=14)  # Explicit form
>>> Blog.objects.get(id=14)         # __exact is implied

Ini adalah untuk kenyamanan, karena pencarian exact adalah kasus umum.

iexact

Pencocokan kasus-tidak-peka. Jadi, permintaan:

>>> Blog.objects.get(name__iexact="beatles blog")

Akan cocok Blog berjudul "Beatles Blog", "beatles blog", atau bahkan "BeAtlES blOG".

contains

Percobaan penahanan kasus-peka . Sebagai contoh:

Entry.objects.get(headline__contains='Lennon')

Kurang lebih menterjemahkan ke SQL ini:

SELECT ... WHERE headline LIKE '%Lennon%';

Catat ini akan cocok dengan judul 'Today Lennon honored' tetapi tidak 'today lennon honored'.

Ada juga versi kasus-tidak-peka, icontains.

startswith, endswith

Pencarian mulai-dengan dan berakhir-dengan, masing-masing. Ada juga versi kasus-tidak-peka dipanggil istartswith dan iendswith.

Kembali, ini hanya menggores permukaan. Acuan lengkap dapat ditemukan di field lookup reference 1.

Pencarian yang menjangkau hubungan¶

Django offers a powerful and intuitive way to "follow" relationships in lookups, taking care of the SQL JOINs for you automatically, behind the scenes. To span a relationship, use the field name of related fields across models, separated by double underscores, until you get to the field you want.

Contoh ini mengambil semua obyek Entry dengan Blog yang name adalah 'Beatles Blog':

>>> Entry.objects.filter(blog__name='Beatles Blog')

Jangkauan ini dapat sedalam anda sukai.

It works backwards, too. To refer to a "reverse" relationship, use the lowercase name of the model.

Contoh ini mengambil semua obyek Blog yang setidaknya saru Entry yang headline mengandung 'Lennon':

>>> Blog.objects.filter(entry__headline__contains='Lennon')

Jika anda menyaring terhadap banyak hubungan dan satu dari model mengengah tidak mempunyai nilai yang memenuhi kondisi penyaring, Django akan memperlakukan itu sebagai jika sebuah kosong (semua nilai adalah NULL), tetapi obyek sah disana. Semua ini berarti bahwa tidak ada kesalahan akan dimunculkan. Sebagi contoh, dalam penyaringan ini:

Blog.objects.filter(entry__authors__name='Lennon')

(jika ada model Author terkait), jika tidak ada author terkait dengan sebuah masukan, itu akan diperlakukan seperti jika tidak ada juga name terlampir, daripada memunculkan kesalahan karena dari author hilang. Biasanya ini adalah tepatnya apa anda ingin miliki terjadi. Kasus satu-satunya dimana itu mungkin membingungkan adalah jika anda menggunakan isnull. Jadi:

Blog.objects.filter(entry__authors__name__isnull=True)

akan mengembalikan obyek Blog yang mempunyai name kosong pada author dan juga itu yang mempunyai author kosong pada entry. Jika anda tidak ingin obyek terakhir itu, anda dapat menulis:

Blog.objects.filter(entry__authors__isnull=False, entry__authors__name__isnull=True)

Blog.objects.filter(entry__headline__contains='Lennon', entry__pub_date__year=2008)

Blog.objects.filter(entry__headline__contains='Lennon').filter(entry__pub_date__year=2008)

Blog.objects.exclude(
    entry__headline__contains='Lennon',
    entry__pub_date__year=2008,
)

Blog.objects.exclude(
    entry__in=Entry.objects.filter(
        headline__contains='Lennon',
        pub_date__year=2008,
    ),
)

Penyaring dapat mengacu bidang pada model¶

Dalam contoh yang diberikan sejauh ini, kami telah membangun berkas-berkas penyaring yang membandingkan nilai dari bidang model dengan ketetapan. Tetapi apa jika anda ingin membandingkan nilai dai bidang model dengan bidang lain pada model sama?

Django menyediakan F expressions untuk mengizinkan perbandingan. Instance dari F() bertindak sebagai sebuah acuan pada model dalam permintaan. Acuan ini kemudian dapat digunakan dalam penyaring permintaan untuk membandingkan nilai-nilai dari dua bidang berbeda pada instance model sama.

Sebagai contoh, untuk menemukan daftar dari semua masukan blog yang telah mempunyai komentar lebih dari pingback, kami membangun obyek F() untuk mengacu jumlah pingback, dan menggunakan obyek F() itu dalam permintaan:

>>> from django.db.models import F
>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks'))

Django mendukung penggunaan aritmatika penambahan, pengurangan, perkalian, pembagian modulus, dan power dengan obyek F(), kedua dengan ketetapan dan dengan obyek F() lain. Untuk menemukan semua masukan blog dengan lebih dari dua kali sebanyak komentar seperti pingback, kami merubah permintaan:

>>> Entry.objects.filter(number_of_comments__gt=F('number_of_pingbacks') * 2)

Untuk menemukan semua masukan dimana penilaian dari masukan sedikit dari penjumlahan hitungan pingback dan hitungan komentar, kami akan menerbitkan permintaan:

>>> Entry.objects.filter(rating__lt=F('number_of_comments') + F('number_of_pingbacks'))

Anda dapat juga menggunakan pernyataan garis bawah untuk menjangkau hubungan dalam sebuah obyek F(). Sebuah obyek F() dengan garis bawah ganda akan memperkenalkan join apapun dibutuhkan untuk mengakses obyek terkait. Sebagai contoh, untuk mengambil semua masukan dimana nama penulis sama seperti nama blog, kami dapat menerbitkan permintaan:

>>> Entry.objects.filter(authors__name=F('blog__name'))

Untuk bidang-bidang tanggal dan tanggal/waktu, anda dapat menambah atau mengurangi obyek timedelta. Berikut akan mengembalikan semua masukan yang telah diubah lebih dari 3 hari setelah mereka diterbitkan.

>>> from datetime import timedelta
>>> Entry.objects.filter(mod_date__gt=F('pub_date') + timedelta(days=3))

Obyek F() mendukung tindakan bitwise dengan .bitand()`, .bitor(), .bitrightshift(), dan .bitleftshift(). Sebagai contoh:

>>> F('somefield').bitand(16)

Jalan pintas pencarian pk¶

Untuk kemudahan, Django menyediakan jalan pintas pencarian pk, yang berdiri untuk "primary key".

Dalam contoh model Blog, primary key adalah bidang id, jadi pernyataan ini adalah setara:

>>> Blog.objects.get(id__exact=14) # Explicit form
>>> Blog.objects.get(id=14) # __exact is implied
>>> Blog.objects.get(pk=14) # pk implies id__exact

Penggunaan pk tidak terbatas pada permintaan __exact -- apapun istilah permintaan dapat dipadukan dengan pk untuk melakukan sebuah permintaan pada primary key pada model:

# Get blogs entries with id 1, 4 and 7
>>> Blog.objects.filter(pk__in=[1,4,7])

# Get all blog entries with id > 14
>>> Blog.objects.filter(pk__gt=14)

Pencarian pk juga bekerja liintas join. Sebagai contoh, tiga pernyataan ini adalah setara:

>>> Entry.objects.filter(blog__id__exact=3) # Explicit form
>>> Entry.objects.filter(blog__id=3)        # __exact is implied
>>> Entry.objects.filter(blog__pk=3)        # __pk implies __id__exact

Meloloskan tanda persen dan garis bawah dalam pernyataan LIKE¶

Pencarian bidang yang menyerupai pernyataan SQL LIKE (iexact, contains, icontains, startswith, istartswith, endswith dan iendswith) akan otomatis meloloskan dua karakter khusus digunakan dalam pernyataan LIKE -- tanda persen dan garis bawah. (Dalam sebuah pernyataan Like, tanda persen menandakan wildcard banyak-karakter dan garis bawah menandakan wildcard karakter-tunggal.)

This means things should work intuitively, so the abstraction doesn't leak. For example, to retrieve all the entries that contain a percent sign, use the percent sign as any other character:

>>> Entry.objects.filter(headline__contains='%')

Django menangani dari pengutipan untuk anda; menghasilkan SQL akan mencari sesuatu seperti ini:

SELECT ... WHERE headline LIKE '%\%%';

Sama seperti garis bawah. Kedua tanda persen dan garis bawag ditangani untuk anda secara transparan.

Cache dan QuerySet¶

Setiap QuerySet mengandung sebuah tembolok untuk meminimalkan akses basisdata. Pahami bagaimana dia bekerja akan mengizinkan anda menulis kode paling efisien.

Dalam QuerySet baru dibuat, cache kosong. Pertama kali sebuah QuerySet dinilai -- dan, karena itu, sebuah permintaan basisdata terjadi -- Django menyimpan hasil permintaan dalam cache QuerySet dan mengembalikan hasil yang telah secara jelas diminta (sebagai contoh, unsur selanjutnya, jika ada QuerySet sedang diulang). Penilaian selanjutnya dari QuerySet menggunakan hasil ter cache.

Jaga perilaku cache ini dalam pikiran, karena itu mungkin mengigit anda jika anda tidak menggunakan QuerySet anda dengan benar. Sebagai contoh, berikut akan membuat dua QuerySet, nilai mereka, dan lemparkan mereka:

>>> print([e.headline for e in Entry.objects.all()])
>>> print([e.pub_date for e in Entry.objects.all()])

Itu berarti permintaan absisdata sama akan dijalankan dua kali, berhasil menggandakan muatan basisdata anda. Juga, ada kemungkinan dua daftar mungkin tidak meneyrtakan rekaman basisdata sama, karena Entry telah ditambahkan atau dihapus dalam pembagian kedua diantara dua permintaan.

Untuk menghindati masalah, simpan QuerySet dan gunakan itu:

>>> queryset = Entry.objects.all()
>>> print([p.headline for p in queryset]) # Evaluate the query set.
>>> print([p.pub_date for p in queryset]) # Re-use the cache from the evaluation.

>>> queryset = Entry.objects.all()
>>> print(queryset[5]) # Queries the database
>>> print(queryset[5]) # Queries the database again

>>> queryset = Entry.objects.all()
>>> [entry for entry in queryset] # Queries the database
>>> print(queryset[5]) # Uses cache
>>> print(queryset[5]) # Uses cache

>>> [entry for entry in queryset]
>>> bool(queryset)
>>> entry in queryset
>>> list(queryset)

Hubungan satu-ke-banyak¶

>>> e = Entry.objects.get(id=2)
>>> e.blog # Returns the related Blog object.

>>> e = Entry.objects.get(id=2)
>>> e.blog = some_blog
>>> e.save()

>>> e = Entry.objects.get(id=2)
>>> e.blog = None
>>> e.save() # "UPDATE blog_entry SET blog_id = NULL ...;"

>>> e = Entry.objects.get(id=2)
>>> print(e.blog)  # Hits the database to retrieve the associated Blog.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> e = Entry.objects.select_related().get(id=2)
>>> print(e.blog)  # Doesn't hit the database; uses cached version.
>>> print(e.blog)  # Doesn't hit the database; uses cached version.

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.all() # Returns all Entry objects related to Blog.

# b.entry_set is a Manager that returns QuerySets.
>>> b.entry_set.filter(headline__contains='Lennon')
>>> b.entry_set.count()

>>> b = Blog.objects.get(id=1)
>>> b.entries.all() # Returns all Entry objects related to Blog.

# b.entries is a Manager that returns QuerySets.
>>> b.entries.filter(headline__contains='Lennon')
>>> b.entries.count()

from django.db import models

class Entry(models.Model):
    #...
    objects = models.Manager()  # Default Manager
    entries = EntryManager()    # Custom Manager

b = Blog.objects.get(id=1)
b.entry_set(manager='entries').all()

b.entry_set(manager='entries').is_published()

b = Blog.objects.get(id=1)
b.entry_set.set([e1, e2])

Hubungan banyak-ke-banyak¶

Both ends of a many-to-many relationship get automatic API access to the other end. The API works similar to a "backward" one-to-many relationship, above.

One difference is in the attribute naming: The model that defines the ManyToManyField uses the attribute name of that field itself, whereas the "reverse" model uses the lowercased model name of the original model, plus '_set' (just like reverse one-to-many relationships).

Sebuah contoh membuatnya mudah untuk dipahami:

e = Entry.objects.get(id=3)
e.authors.all() # Returns all Author objects for this Entry.
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Returns all Entry objects for this Author.

Seeprti ForeignKey, ManyToManyField dapat menentukan related_name. Dalam contoh diatas, jika ManyToManyField di Entry telah menentukan related_name='entries', kemudian setiap instance Author akan memiliki sebuah atribut entries daripada entry_set.

Another difference from one-to-many relationships is that in addition to model instances, the add(), set(), and remove() methods on many-to-many relationships accept primary key values. For example, if e1 and e2 are Entry instances, then these set() calls work identically:

a = Author.objects.get(id=5)
a.entry_set.set([e1, e2])
a.entry_set.set([e1.pk, e2.pk])

Hubungan satu-ke-satu¶

One-to-one relationships are very similar to many-to-one relationships. If you define a OneToOneField on your model, instances of that model will have access to the related object via an attribute of the model.

Sebagai contoh:

class EntryDetail(models.Model):
    entry = models.OneToOneField(Entry, on_delete=models.CASCADE)
    details = models.TextField()

ed = EntryDetail.objects.get(id=2)
ed.entry # Returns the related Entry object.

Perbedaan datang dalam permintaan "reverse". Model terkait dalam hubungan one-to-one juga mempunyai akses ke obyek Manager, tetapi Manager itu mewakili obyek tunggal, daripada sebuah kumpulan obyek-obyek:

e = Entry.objects.get(id=2)
e.entrydetail # returns the related EntryDetail object

Jika tidak ada obyek diberikan ke hubungan ini, Django akan memunculkan pengecualian DoesNotExist.

Instance-instance dapat diberikan ke hubungan balikan dalam cara sama seperti anda akan memberikan meneruskan hubungan:

e.entrydetail = ed

Bagaimana hubungan kebelakang dimungkinkan?¶

Pemeta hubungan-obyek lainnya membutuhkan anda menentukan hubungan pada kedua sisi. Pengembang Django percaya ini adalah pelanggaran dari prinsip DRY (Don't Repeat Yourself), jadi Django hanya membutuhkan anda menentukan hubungan pada satu akhiran.

Tetapi bagaimana ini mungkin, memberikan itu kelas model yang tidak mengetahui mana kelas-kelas model lain terkait ke itu sampai kelas-kelas model lain tersebut dimuat?

Jawaban terletak di app registry. Ketika Django mulai, itu mengimpor setiap aplikasi terdaftar di INSTALLED_APPS, dan kemudian modul models didalam setiap aplikasi. Kapanpun sebuah kelas model dibuat, Django menambahkan hubungan-kebelakang ke setiap model terkait. Jika model terkait belum diimpor, Django menjaga jalur dari hubungan dan menambahkan mereka ketika model terkait akhirnya diimpor.

Untuk alasan ini, itu adalah khususnya penting bahwa semua model anda sedang gunakan ditentukan dalam aplikasi terdaftar dalam INSTALLED_APPS. Sebaliknya, hubungan kebelakang mungkin tidak bekerja dengan benar.

Meminta terhadap obyek terkait¶

Permintaan melibatkan obyek-obyek terkait mengikuti aturan sama seperti permintaan melibatkan bidang-bidang nilai biasa. Ketika menentukan nilai untuk permintaan untuk pencocokan, anda mungkin menggunakan salah satu instance obyek itu sendiri, atau nilai primary key untuk obyek.

Sebagai contoh, jika anda mempunyai sebuah obyek Blog b dengan id=5, tiga permintaan berikut akan mirip:

Entry.objects.filter(blog=b) # Query using object instance
Entry.objects.filter(blog=b.id) # Query using id from instance
Entry.objects.filter(blog=5) # Query using id directly