Sekali anda telah membuat data models 1 anda, Django otomatis memberikan anda pemisahan API yang membuat anda membuat, mengambil, memperbaharui dan menghapus obyek. Dokumen ini menjelaskan bagaimana menggunakan API ini. mengacu pada data model reference 2 untuk rincian penuh dari beragam pilihan pencarian model.
\nThroughout this guide (and in the reference), we'll refer to the following\nmodels, which comprise a blog application:
\nfrom datetime import date\n\nfrom django.db import models\n\n\nclass Blog(models.Model):\n name = models.CharField(max_length=100)\n tagline = models.TextField()\n\n def __str__(self):\n return self.name\n\n\nclass Author(models.Model):\n name = models.CharField(max_length=200)\n email = models.EmailField()\n\n def __str__(self):\n return self.name\n\n\nclass Entry(models.Model):\n blog = models.ForeignKey(Blog, on_delete=models.CASCADE)\n headline = models.CharField(max_length=255)\n body_text = models.TextField()\n pub_date = models.DateField()\n mod_date = models.DateField(default=date.today)\n authors = models.ManyToManyField(Author)\n number_of_comments = models.IntegerField(default=0)\n number_of_pingbacks = models.IntegerField(default=0)\n rating = models.IntegerField(default=5)\n\n def __str__(self):\n return self.headline\nUntuk mewakili data tabel-basisdata dalam obyek Python, Django menggunakan sistem intuitif: Sebuah kelas model mewakili sebuah tabel basisdata, dan sebuah instance dari kelas itu mewakili rekaman tertentu dalam tabel basisdata.
\nUntuk membuat sebuah obyek, instansiasi itu menggunakan argumen katakunci pada kelas model, kemudian memanggil save() untuk menyimpan itu ke basisdata.
Dengan asumsi model berada di berkas models.py di dalam aplikasi Django blog, ini adalah sebuah contoh:
>>> from blog.models import Blog\n>>> b = Blog(name="Beatles Blog", tagline="All the latest Beatles news.")\n>>> b.save()\nIni melakukan pernyataan SQL INSERT dibelakang layar. Django tidak mengenai basisdata sampai anda secara jelas memanggil save().
Cara save() tidak mempunyai nilai kembalian.
Untuk menyimpan perubahan ke sebuah obyek yang sudah ada di basisdata gunakan save().
Given a Blog instance b5 that has already been saved to the database,\nthis example changes its name and updates its record in the database:
>>> b5.name = "New name"\n>>> b5.save()\nIni melakukan pernyataan SQL UPDATE dibelakang layar. Django tidak mengenai basisdata sampai anda secara jelas memanggil save().
ForeignKey dan ManyToManyFieldLink to this heading#Updating a ForeignKey field works exactly the same\nway as saving a normal field -- assign an object of the right type to the field\nin question. This example updates the blog attribute of an Entry\ninstance entry, assuming appropriate instances of Entry and Blog\nare already saved to the database (so we can retrieve them below):
>>> from blog.models import Blog, Entry\n>>> entry = Entry.objects.get(pk=1)\n>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")\n>>> entry.blog = cheese_blog\n>>> entry.save()\nUpdating a ManyToManyField works a little\ndifferently -- use the\nadd() method on the field\nto add a record to the relation. This example adds the Author instance\njoe to the entry object:
>>> from blog.models import Author\n>>> joe = Author.objects.create(name="Joe")\n>>> entry.authors.add(joe)\nTo add multiple records to a ManyToManyField in one\ngo, include multiple arguments in the call to\nadd(), like this:
>>> john = Author.objects.create(name="John")\n>>> paul = Author.objects.create(name="Paul")\n>>> george = Author.objects.create(name="George")\n>>> ringo = Author.objects.create(name="Ringo")\n>>> entry.authors.add(john, paul, george, ringo)\nDjango akan mengeluh jika anda mencoba memberikan atau menambahkan sebuah obyek dari jenis salah.
\nUntuk mengambil obyek-obyek dari basisdata anda, bangun sebuah QuerySet melalui Manager pada kelas model anda.
Sebuah QuerySet mewakili sebuah kumpulan dari ibyek-obyek dari basisdata anda. itu dapat memiliki nol, satu atau banyak penyaring. Penyaring mempersempit hasil permintaan berdasarkan pada parameter yang diberikan. Dalam istilah SQL, QuerySet menyamakan pada pernyataan SELECT, dan penyaring membatasi klausa seperti WHERE atau LIMIT.
You get a QuerySet by using your model's\nManager. Each model has at least one\nManager, and it's called\nobjects by default. Access it directly via the\nmodel class, like so:
>>> Blog.objects\n<django.db.models.manager.Manager object at ...>\n>>> b = Blog(name="Foo", tagline="Bar")\n>>> b.objects\nTraceback:\n ...\nAttributeError: "Manager isn't accessible via Blog instances."\nThe Manager is the main source of querysets for\na model. For example, Blog.objects.all() returns a\nQuerySet that contains all Blog objects in\nthe database.
The simplest way to retrieve objects from a table is to get all of them. To do\nthis, use the all() method on a\nManager:
>>> all_entries = Entry.objects.all()\nMetode all() mengembalikan semua QuerySet dari semua obyek dalam basisdata.
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)\nDengan kelas pengelola awalan, itu adalah sama seperti:
\nEntry.objects.all().filter(pub_date__year=2006)\nThe result of refining a QuerySet is itself a\nQuerySet, so it's possible to chain\nrefinements together. For example:
>>> Entry.objects.filter(headline__startswith="What").exclude(\n... pub_date__gte=datetime.date.today()\n... ).filter(pub_date__gte=datetime.date(2005, 1, 30))\nIni mengambil awal QuerySet dari semua masukan dalam basisdata, tambah sebuah penyaring, kemudian sebuah pengecualian, kemudian penyaring lain. Hasil akhir adalah sebuah QuerySet mengandung semua masukan dengan judul yang mulai dengan "What", yang diterbitkan diantara 30 Januari 2005, dan hari saat ini.
QuerySet adalah unikLink to this heading#Setiap kali anda menyaring sebuah QuerySet, anda mendapatkan QuerySet merek-baru yaitu tidak ada cara mengikat ke QuerySet sebelumnya. Setiap penyaringan membuat QuerySet terpisah dan berbeda yang dapat disimpan, digunakan dan digunakan kembali.
Example:
\n>>> q1 = Entry.objects.filter(headline__startswith="What")\n>>> q2 = q1.exclude(pub_date__gte=datetime.date.today())\n>>> q3 = q1.filter(pub_date__gte=datetime.date.today())\nThese three querysets are separate. The first is a base\nQuerySet containing all entries that contain a\nheadline starting with "What". The second is a subset of the first, with an\nadditional criteria that excludes records whose pub_date is today or in the\nfuture. The third is a subset of the first, with an additional criteria that\nselects only the records whose pub_date is today or in the future. The\ninitial QuerySet (q1) is unaffected by the\nrefinement process.
QuerySet adalah lazyLink to this heading#QuerySet objects are lazy -- the act of creating a\nQuerySet doesn't involve any database\nactivity. You can stack filters together all day long, and Django won't\nactually run the query until the QuerySet is\nevaluated. Take a look at this example:
>>> q = Entry.objects.filter(headline__startswith="What")\n>>> q = q.filter(pub_date__lte=datetime.date.today())\n>>> q = q.exclude(body_text__icontains="food")\n>>> print(q)\nMeskipun ini terlihat mengenai basisdata tiga kali, sebenarnya itu mengenai basisdata hanya sekali, pada baris terakhir (print(q)). Secara umum, hasil dari QuerySet tidak diambil dari basisdata sampai anda "meminta" untuk mereka. Ketika anda melakukan, QuerySet dinilai dengan mengakses basisdata. Untuk rincian lebih pada sebenarnya ketika penilaian mengambil tempat, lihat Ketika QuerySet dinilai.
get()Link to this heading#filter() akan selalu memberikan anda QuerySet, bahkan jika hanya obyek tunggal yang cocok permintaan - dalam kasus ini, itu akan berupa QuerySet mengandung unsur tunggal.
If you know there is only one object that matches your query, you can use the\nget() method on a\nManager which returns the object directly:
>>> one_entry = Entry.objects.get(pk=1)\nAnda 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.
QuerySet lainLink to this heading#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.
QuerySetLink to this heading#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.
For example, this returns the first 5 objects (LIMIT 5):
>>> Entry.objects.all()[:5]\nThis returns the sixth through tenth objects (OFFSET 5 LIMIT 5):
>>> Entry.objects.all()[5:10]\nPengindeksan negatif (yaitu Entry.objects.all()[-1]) tidak didukung.
Generally, slicing a QuerySet returns a new\nQuerySet -- it doesn't evaluate the query. An\nexception is if you use the "step" parameter of Python slice syntax. For\nexample, this would actually execute the query in order to return a list of\nevery second object of the first 10:
>>> Entry.objects.all()[:10:2]\nPenyaring atau pengurut lebih lanjut dari irisan queryset dilarang karena sifat ambigu dari bagaimana itu mungkin bekerja.
\nTo retrieve a single object rather than a list\n(e.g. SELECT foo FROM bar LIMIT 1), use an index instead of a slice. For\nexample, this returns the first Entry in the database, after ordering\nentries alphabetically by headline:
>>> Entry.objects.order_by("headline")[0]\nThis is roughly equivalent to:
\n>>> Entry.objects.order_by("headline")[0:1].get()\nCatat, 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.
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().
Basic lookups keyword arguments take the form field__lookuptype=value.\n(That's a double-underscore). For example:
>>> Entry.objects.filter(pub_date__lte="2006-01-01")\nterjemahan (kurang lebih) ke dalam SQL berikut:
\nSELECT * FROM blog_entry WHERE pub_date <= '2006-01-01';\nBidang 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)\nJika 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:
\nexactAn "exact" match. For example:
\n>>> Entry.objects.get(headline__exact="Cat bites dog")\nAkan membangkitkan SQL bersama baris ini:
\nSELECT ... WHERE headline = 'Cat bites dog';\nJika anda tidak menyediakan jenis pencarian -- yaitu, jika argumen kata kunci anda tidak mengandung garis bawah ganda -- jenis pencarian dianggap tepat.
For example, the following two statements are equivalent:
\n>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\nIni adalah untuk kenyamanan, karena pencarian exact adalah kasus umum.
iexactA case-insensitive match. So, the query:
\n>>> Blog.objects.get(name__iexact="beatles blog")\nAkan cocok Blog berjudul "Beatles Blog", "beatles blog", atau bahkan "BeAtlES blOG".
containsPercobaan penahanan kasus-peka . Sebagai contoh:
\nEntry.objects.get(headline__contains="Lennon")\nKurang lebih menterjemahkan ke SQL ini:
\nSELECT ... WHERE headline LIKE '%Lennon%';\nCatat ini akan cocok dengan judul 'Today Lennon honored' tetapi tidak 'today lennon honored'.
Ada juga versi kasus-tidak-peka, icontains.
startswith, endswithPencarian 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.
\nDjango offers a powerful and intuitive way to "follow" relationships in\nlookups, taking care of the SQL JOINs for you automatically, behind the\nscenes. To span a relationship, use the field name of related fields\nacross models, separated by double underscores, until you get to the field you\nwant.
This example retrieves all Entry objects with a Blog whose name\nis 'Beatles Blog':
>>> Entry.objects.filter(blog__name="Beatles Blog")\nJangkauan ini dapat sedalam anda sukai.
\nItu bekerja kebelakang, juga. Selagi itu can be customized, secara awalan anda mengacu pada hubungan "reverse" dalam pencarian menggunakan nama huruf kecil dari model.
This example retrieves all Blog objects which have at least one Entry\nwhose headline contains 'Lennon':
>>> Blog.objects.filter(entry__headline__contains="Lennon")\nJika 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")\n(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)\nakan 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)\nWhen spanning a ManyToManyField or a reverse\nForeignKey (such as from Blog to Entry),\nfiltering on multiple attributes raises the question of whether to require each\nattribute to coincide in the same related object. We might seek blogs that have\nan entry from 2008 with “Lennon” in its headline, or we might seek blogs that\nmerely have any entry from 2008 as well as some newer or older entry with\n“Lennon” in its headline.
To select all blogs containing at least one entry from 2008 having "Lennon"\nin its headline (the same entry satisfying both conditions), we would write:
\nBlog.objects.filter(entry__headline__contains="Lennon", entry__pub_date__year=2008)\nOtherwise, to perform a more permissive query selecting any blogs with merely\nsome entry with "Lennon" in its headline and some entry from 2008, we\nwould write:
\nBlog.objects.filter(entry__headline__contains="Lennon").filter(\n entry__pub_date__year=2008\n)\nSuppose there is only one blog that has both entries containing "Lennon" and\nentries from 2008, but that none of the entries from 2008 contained "Lennon".\nThe first query would not return any blogs, but the second query would return\nthat one blog. (This is because the entries selected by the second filter may\nor may not be the same as the entries in the first filter. We are filtering the\nBlog items with each filter statement, not the Entry items.) In short,\nif each condition needs to match the same related object, then each should be\ncontained in a single filter() call.
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?
\nDjango 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.
For example, to find a list of all blog entries that have had more comments\nthan pingbacks, we construct an F() object to reference the pingback count,\nand use that F() object in the query:
>>> from django.db.models import F\n>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks"))\nDjango supports the use of addition, subtraction, multiplication, division,\nmodulo, and power arithmetic with F() objects, both with constants and with\nother F() objects. To find all the blog entries with more than twice as\nmany comments as pingbacks, we modify the query:
>>> Entry.objects.filter(number_of_comments__gt=F("number_of_pingbacks") * 2)\nTo find all the entries where the rating of the entry is less than the\nsum of the pingback count and comment count, we would issue the\nquery:
\n>>> Entry.objects.filter(rating__lt=F("number_of_comments") + F("number_of_pingbacks"))\nYou can also use the double underscore notation to span relationships in\nan F() object. An F() object with a double underscore will introduce\nany joins needed to access the related object. For example, to retrieve all\nthe entries where the author's name is the same as the blog name, we could\nissue the query:
>>> Entry.objects.filter(authors__name=F("blog__name"))\nFor date and date/time fields, you can add or subtract a\ntimedelta object. The following would return all entries\nthat were modified more than 3 days after they were published:
>>> from datetime import timedelta\n>>> Entry.objects.filter(mod_date__gt=F("pub_date") + timedelta(days=3))\nThe F() objects support bitwise operations by .bitand(), .bitor(),\n.bitxor(), .bitrightshift(), and .bitleftshift(). For example:
>>> F("somefield").bitand(16)\nDjango supports using transforms in expressions.
\nFor example, to find all Entry objects published in the same year as they\nwere last modified:
>>> from django.db.models import F\n>>> Entry.objects.filter(pub_date__year=F("mod_date__year"))\nTo find the earliest year an entry was published, we can issue the query:
\n>>> from django.db.models import Min\n>>> Entry.objects.aggregate(first_published_year=Min("pub_date__year"))\nThis example finds the value of the highest rated entry and the total number\nof comments on all entries for each year:
\n>>> from django.db.models import OuterRef, Subquery, Sum\n>>> Entry.objects.values("pub_date__year").annotate(\n... top_rating=Subquery(\n... Entry.objects.filter(\n... pub_date__year=OuterRef("pub_date__year"),\n... )\n... .order_by("-rating")\n... .values("rating")[:1]\n... ),\n... total_comments=Sum("number_of_comments"),\n... )\npkLink to this heading#Untuk kemudahan, Django menyediakan jalan pintas pencarian pk, yang berdiri untuk "primary key".
In the example Blog model, the primary key is the id field, so these\nthree statements are equivalent:
>>> Blog.objects.get(id__exact=14) # Explicit form\n>>> Blog.objects.get(id=14) # __exact is implied\n>>> Blog.objects.get(pk=14) # pk implies id__exact\nThe use of pk isn't limited to __exact queries -- any query term\ncan be combined with pk to perform a query on the primary key of a model:
# Get blogs entries with id 1, 4 and 7\n>>> Blog.objects.filter(pk__in=[1, 4, 7])\n\n# Get all blog entries with id > 14\n>>> Blog.objects.filter(pk__gt=14)\npk lookups also work across joins. For example, these three statements are\nequivalent:
>>> Entry.objects.filter(blog__id__exact=3) # Explicit form\n>>> Entry.objects.filter(blog__id=3) # __exact is implied\n>>> Entry.objects.filter(blog__pk=3) # __pk implies __id__exact\nLIKELink to this heading#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.\nFor example, to retrieve all the entries that contain a percent sign, use the\npercent sign as any other character:
\n>>> Entry.objects.filter(headline__contains="%")\nDjango menangani dari pengutipan untuk anda; menghasilkan SQL akan mencari sesuatu seperti ini:
\nSELECT ... WHERE headline LIKE '%\\%%';\nSama seperti garis bawah. Kedua tanda persen dan garis bawag ditangani untuk anda secara transparan.
\nQuerySetLink to this heading#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.
Keep this caching behavior in mind, because it may bite you if you don't use\nyour QuerySets correctly. For example, the\nfollowing will create two QuerySets, evaluate\nthem, and throw them away:
>>> print([e.headline for e in Entry.objects.all()])\n>>> print([e.pub_date for e in Entry.objects.all()])\nItu 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.
To avoid this problem, save the QuerySet and\nreuse it:
>>> queryset = Entry.objects.all()\n>>> print([p.headline for p in queryset]) # Evaluate the query set.\n>>> print([p.pub_date for p in queryset]) # Reuse the cache from the evaluation.\nQuerySet tidak di cacheLink to this heading#Querysets do not always cache their results. When evaluating only part of\nthe queryset, the cache is checked, but if it is not populated then the items\nreturned by the subsequent query are not cached. Specifically, this means that\nlimiting the queryset using an array slice or an\nindex will not populate the cache.
\nFor example, repeatedly getting a certain index in a queryset object will query\nthe database each time:
\n>>> queryset = Entry.objects.all()\n>>> print(queryset[5]) # Queries the database\n>>> print(queryset[5]) # Queries the database again\nHowever, if the entire queryset has already been evaluated, the cache will be\nchecked instead:
\n>>> queryset = Entry.objects.all()\n>>> [entry for entry in queryset] # Queries the database\n>>> print(queryset[5]) # Uses cache\n>>> print(queryset[5]) # Uses cache\nHere are some examples of other actions that will result in the entire queryset\nbeing evaluated and therefore populate the cache:
\n>>> [entry for entry in queryset]\n>>> bool(queryset)\n>>> entry in queryset\n>>> list(queryset)\nIf you are writing asynchronous views or code, you cannot use the ORM for\nqueries in quite the way we have described above, as you cannot call blocking\nsynchronous code from asynchronous code - it will block up the event loop\n(or, more likely, Django will notice and raise a SynchronousOnlyOperation\nto stop that from happening).
Fortunately, you can do many queries using Django's asynchronous query APIs.\nEvery method that might block - such as get() or delete() - has an\nasynchronous variant (aget() or adelete()), and when you iterate over\nresults, you can use asynchronous iteration (async for) instead.
The default way of iterating over a query - with for - will result in a\nblocking database query behind the scenes as Django loads the results at\niteration time. To fix this, you can swap to async for:
async for entry in Authors.objects.filter(name__startswith="A"):\n ...\nBe aware that you also can't do other things that might iterate over the\nqueryset, such as wrapping list() around it to force its evaluation (you\ncan use async for in a comprehension, if you want it).
Because QuerySet methods like filter() and exclude() do not\nactually run the query - they set up the queryset to run when it's iterated\nover - you can use those freely in asynchronous code. For a guide to which\nmethods can keep being used like this, and which have asynchronous versions,\nread the next section.
QuerySet and manager methodsLink to this heading#Some methods on managers and querysets - like get() and first() - force\nexecution of the queryset and are blocking. Some, like filter() and\nexclude(), don't force execution and so are safe to run from asynchronous\ncode. But how are you supposed to tell the difference?
While you could poke around and see if there is an a-prefixed version of\nthe method (for example, we have aget() but not afilter()), there is a\nmore logical way - look up what kind of method it is in the\nQuerySet reference.
In there, you'll find the methods on QuerySets grouped into two sections:
\nMethods that return new querysets: These are the non-blocking ones,\nand don't have asynchronous versions. You're free to use these in any\nsituation, though read the notes on defer() and only() before you use\nthem.
Methods that do not return querysets: These are the blocking ones, and\nhave asynchronous versions - the asynchronous name for each is noted in its\ndocumentation, though our standard pattern is to add an a prefix.
Using this distinction, you can work out when you need to use asynchronous\nversions, and when you don't. For example, here's a valid asynchronous query:
\nuser = await User.objects.filter(username=my_input).afirst()\nfilter() returns a queryset, and so it's fine to keep chaining it inside an\nasynchronous environment, whereas first() evaluates and returns a model\ninstance - thus, we change to afirst(), and use await at the front of\nthe whole expression in order to call it in an asynchronous-friendly way.
Transactions are not currently supported with asynchronous queries and\nupdates. You will find that trying to use one raises\nSynchronousOnlyOperation.
If you wish to use a transaction, we suggest you write your ORM code inside a\nseparate, synchronous function and then call that using sync_to_async - see\nDukungan asinkronus for more.
JSONFieldLink to this heading#Lookups implementation is different in JSONField,\nmainly due to the existence of key transformations. To demonstrate, we will use\nthe following example model:
from django.db import models\n\n\nclass Dog(models.Model):\n name = models.CharField(max_length=200)\n data = models.JSONField(null=True)\n\n def __str__(self):\n return self.name\nNoneLink to this heading#As with other fields, storing None as the field's value will store it as\nSQL NULL. While not recommended, it is possible to store JSON scalar\nnull instead of SQL NULL by using Value(None, JSONField()).
Whichever of the values is stored, when retrieved from the database, the Python\nrepresentation of the JSON scalar null is the same as SQL NULL, i.e.\nNone. Therefore, it can be hard to distinguish between them.
This only applies to None as the top-level value of the field. If None\nis inside a list or dict, it will always be interpreted\nas JSON null.
When querying, None value will always be interpreted as JSON null. To\nquery for SQL NULL, use isnull:
>>> Dog.objects.create(name="Max", data=None) # SQL NULL.\n<Dog: Max>\n>>> Dog.objects.create(name="Archie", data=Value(None, JSONField())) # JSON null.\n<Dog: Archie>\n>>> Dog.objects.filter(data=None)\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data=Value(None, JSONField()))\n<QuerySet [<Dog: Archie>]>\n>>> Dog.objects.filter(data__isnull=True)\n<QuerySet [<Dog: Max>]>\n>>> Dog.objects.filter(data__isnull=False)\n<QuerySet [<Dog: Archie>]>\nUnless you are sure you wish to work with SQL NULL values, consider setting\nnull=False and providing a suitable default for empty values, such as\ndefault=dict.
To query based on a given dictionary key, use that key as the lookup name:
\n>>> Dog.objects.create(\n... name="Rufus",\n... data={\n... "breed": "labrador",\n... "owner": {\n... "name": "Bob",\n... "other_pets": [\n... {\n... "name": "Fishy",\n... }\n... ],\n... },\n... },\n... )\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": None})\n<Dog: Meg>\n>>> Dog.objects.filter(data__breed="collie")\n<QuerySet [<Dog: Meg>]>\nMultiple keys can be chained together to form a path lookup:
\n>>> Dog.objects.filter(data__owner__name="Bob")\n<QuerySet [<Dog: Rufus>]>\nIf the key is an integer, it will be interpreted as an index transform in an\narray:
\n>>> Dog.objects.filter(data__owner__other_pets__0__name="Fishy")\n<QuerySet [<Dog: Rufus>]>\nIf the key is a negative integer, it cannot be used in a filter keyword\ndirectly, but you can still use dictionary unpacking to use it in a query:
\n>>> Dog.objects.filter(**{"data__owner__other_pets__-1__name": "Fishy"})\n<QuerySet [<Dog: Rufus>]>\nIf the key you wish to query by clashes with the name of another lookup, use\nthe contains lookup instead.
To query for missing keys, use the isnull lookup:
>>> Dog.objects.create(name="Shep", data={"breed": "collie"})\n<Dog: Shep>\n>>> Dog.objects.filter(data__owner__isnull=True)\n<QuerySet [<Dog: Shep>]>\nKT() expressionsLink to this heading#Represents the text value of a key, index, or path transform of\nJSONField. You can use the double underscore\nnotation in lookup to chain dictionary key and index transforms.
Sebagai contoh:
\n>>> from django.db.models.fields.json import KT\n>>> Dog.objects.create(\n... name="Shep",\n... data={\n... "owner": {"name": "Bob"},\n... "breed": ["collie", "lhasa apso"],\n... },\n... )\n<Dog: Shep>\n>>> Dog.objects.annotate(\n... first_breed=KT("data__breed__1"), owner_name=KT("data__owner__name")\n... ).filter(first_breed__startswith="lhasa", owner_name="Bob")\n<QuerySet [<Dog: Shep>]>\ncontainsLink to this heading#The contains lookup is overridden on JSONField. The returned\nobjects are those where the given dict of key-value pairs are all\ncontained in the top-level of the field. For example:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contains={"owner": "Bob"})\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"breed": "collie"})\n<QuerySet [<Dog: Meg>]>\n>>> Dog.objects.filter(data__contains={"tricks": ["dance"]})\n<QuerySet [<Dog: Merry>]>\ncontained_byLink to this heading#This is the inverse of the contains lookup - the\nobjects returned will be those where the key-value pairs on the object are a\nsubset of those in the value passed. For example:
>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.create(name="Fred", data={})\n<Dog: Fred>\n>>> Dog.objects.create(\n... name="Merry", data={"breed": "pekingese", "tricks": ["fetch", "dance"]}\n... )\n>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})\n<QuerySet [<Dog: Meg>, <Dog: Fred>]>\n>>> Dog.objects.filter(data__contained_by={"breed": "collie"})\n<QuerySet [<Dog: Fred>]>\n>>> Dog.objects.filter(\n... data__contained_by={"breed": "pekingese", "tricks": ["dance", "fetch", "hug"]}\n... )\n<QuerySet [<Dog: Merry>, <Dog: Fred>]>\nhas_keyLink to this heading#Returns objects where the given key is in the top-level of the data. For\nexample:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_key="owner")\n<QuerySet [<Dog: Meg>]>\nhas_keysLink to this heading#Returns objects where all of the given keys are in the top-level of the data.\nFor example:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_keys=["breed", "owner"])\n<QuerySet [<Dog: Meg>]>\nhas_any_keysLink to this heading#Returns objects where any of the given keys are in the top-level of the data.\nFor example:
\n>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})\n<Dog: Rufus>\n>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})\n<Dog: Meg>\n>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])\n<QuerySet [<Dog: Rufus>, <Dog: Meg>]>\nQLink to this heading#Permintaan argumen katakunci -- dalam filter(), dll. -- adalah "AND" bersama-sama. Jika anda buth menjalankan permintaan lebih rumit (sebagai contoh, permintaan dengan pernyataan OR), anda dapat menggunakan Q objects.
Q object (django.db.models.Q) adalah sebuah obyek digunakan untuk membungkus koleksi dari argumen katakunci. Argumen katakunci ini ditentukan seperti dalam "Pencarian bidang" diatas.
Sebagai contoh, obyek Q ini membungkus permintaan LIKE tunggal:
from django.db.models import Q\n\nQ(question__startswith="What")\nQ objects can be combined using the &, |, and ^ operators. When\nan operator is used on two Q objects, it yields a new Q object.
Sebagai contoh, pernyataan ini menghasilkan obyek Q tunggal yang mewakili "OR" atau dua permintaan "question__startswith"
Q(question__startswith="Who") | Q(question__startswith="What")\nThis is equivalent to the following SQL WHERE clause:
WHERE question LIKE 'Who%' OR question LIKE 'What%'\nYou can compose statements of arbitrary complexity by combining Q objects\nwith the &, |, and ^ operators and use parenthetical grouping.\nAlso, Q objects can be negated using the ~ operator, allowing for\ncombined lookups that combine both a normal query and a negated (NOT)\nquery:
Q(question__startswith="Who") | ~Q(pub_date__year=2005)\nSetiap fungsi pencarian yang mengambil argumen-kata kunci (sebagai contoh filter(), exclude(), get()) dapat juga melewatkan satu atau lebih obyek Q sebagai argumen (tidak-dinamai) kedudukan. Jika anda menyediakan banyak argumen obyek Q pada fungsi pencarian, argumen akan di "AND"kan bersama-sama. Sebagai contoh:
Poll.objects.get(\n Q(question__startswith="Who"),\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n... kurang lebih diterjemahkan kedalam SQL:
\nSELECT * from polls WHERE question LIKE 'Who%'\n AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')\nFungsi pencarian dapat mencampurkan penggunaan obyek Q dan argumen kata kunci. Semua argumen disediakan untuk fungsi pencarian (menjadi mereka argumen kata kunci atau obyek Q) di "AND"kan bersama-sama. Bagaimanapun, jika obyek Q disediakan, dia harus mendahului pengertian dari argumen kata kunci apapun. Sebagai contoh:
Poll.objects.get(\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n question__startswith="Who",\n)\n... akan menjadi permintaan sah, sama pada contoh sebelumnya; tetapi:
\n# INVALID QUERY\nPoll.objects.get(\n question__startswith="Who",\n Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),\n)\n... tidak akan menjadi sah.
\n\nTo compare two model instances, use the standard Python comparison operator,\nthe double equals sign: ==. Behind the scenes, that compares the primary\nkey values of two models.
Using the Entry example above, the following two statements are equivalent:
>>> some_entry == other_entry\n>>> some_entry.id == other_entry.id\nIf a model's primary key isn't called id, no problem. Comparisons will\nalways use the primary key, whatever it's called. For example, if a model's\nprimary key field is called name, these two statements are equivalent:
>>> some_obj == other_obj\n>>> some_obj.name == other_obj.name\nThe delete method, conveniently, is named\ndelete(). This method immediately deletes the\nobject and returns the number of objects deleted and a dictionary with\nthe number of deletions per object type. Example:
>>> e.delete()\n(1, {'blog.Entry': 1})\nAnda dapat juga menghapus obyek dalam jumlah besar. Setiap QuerySet mempunyai sebuah delete() method, yang menghapus semua anggota dari QuerySet tersebut.
For example, this deletes all Entry objects with a pub_date year of\n2005:
>>> Entry.objects.filter(pub_date__year=2005).delete()\n(5, {'webapp.Entry': 5})\nIngat bahwa ini akan, ketika memungkinkan, akan dijalankan murni dalam SQL, dan juga cara delete() dari instance tidak akan perlu dipanggil selama pengolahan. Jika anda telah menyediakan cara delete() disesuaikan pada sebuah kelas model dan ingin memastikan bahwa dia dipanggil, anda akan butuh "secara manual" menghapus instance dari model tersebut (sebagai contoh, dengan perulangan terhadap QuerySet dan memanggil delete() pada setiap obyek secara tersendiri) daripada menggunakan dalam jumlah besar cara delete() dari sebuah QuerySet.
Ketika DJANGO menghapus sebuah obyek, secara awal dia meniru kebiasaan batasan SQL ON DELETE CASCADE -- dalam kata lain, obyek apapun yang mempunyai foreign key menunjuk pada obyek yang akan dihapus akan dihapus bersama dengannya. Sebagai contoh:
b = Blog.objects.get(pk=1)\n# This will delete the Blog and all of its Entry objects.\nb.delete()\nKebiasaan turunan ini dapat di sesuaikan melalui argumen on_delete ke ForeignKey.
Catat bahwa delete() adalah hanya cara QuerySet yang tidak ditunjukkan pada Manager itu sendiri. Ini adalah mekanisme aman untuk mencegah anda dari kecelakaan permintaan Entry.objects.delete(), dan menghapus semua masukan. Jika anda ingin melakukan menghapus semua obyek, kemudian anda harus secara jelas meminta kumpulan permintaan lengkap:
Entry.objects.all().delete()\nAlthough there is no built-in method for copying model instances, it is\npossible to easily create new instance with all fields' values copied. In the\nsimplest case, you can set pk to None and\n_state.adding to True. Using our\nblog example:
blog = Blog(name="My blog", tagline="Blogging is easy")\nblog.save() # blog.pk == 1\n\nblog.pk = None\nblog._state.adding = True\nblog.save() # blog.pk == 2\nHal-hal dapat lebih rumit jika anda menggunakan warisan. Pertimbangkan subkelas dari Blog:
class ThemeBlog(Blog):\n theme = models.CharField(max_length=200)\n\n\ndjango_blog = ThemeBlog(name="Django", tagline="Django is easy", theme="python")\ndjango_blog.save() # django_blog.pk == 3\nDue to how inheritance works, you have to set both pk and id to\nNone, and _state.adding to True:
django_blog.pk = None\ndjango_blog.id = None\ndjango_blog._state.adding = True\ndjango_blog.save() # django_blog.pk == 4\nPengolahan ini tidak menyalin hubungan yang bukan bagian dari tabel basisdata model. Sebagai contoh, Entry mempunyai ManyToManyField terhadap Author. Setelah menggandakan sebuah masukan, anda harus menyetel hubungan many-to-many untuk masukan baru:
entry = Entry.objects.all()[0] # some previous entry\nold_authors = entry.authors.all()\nentry.pk = None\nentry._state.adding = True\nentry.save()\nentry.authors.set(old_authors)\nUntuk OneToOneField, anda harus menggandakan obyek terkait dan memberikan itu ke bidang obyek baru untuk menghindari melanggar batasan untuk one-to-one. Sebagai contoh, menganggap entry sudah digandakan seperti diatas:
detail = EntryDetail.objects.all()[0]\ndetail.pk = None\ndetail._state.adding = True\ndetail.entry = entry\ndetail.save()\nNote that it is not possible to copy instances of models with deferred fields\nusing this pattern unless values are assigned to them:
\n>>> blog = Blog.objects.defer("name")[0]\n>>> blog.pk = None\n>>> blog._state.adding = True\n>>> blog.save()\nTraceback (most recent call last):\n ...\nAttributeError: Cannot retrieve deferred field 'name' from an unsaved model.\n>>> blog.name = "Another Blog"\n>>> blog.save()\nTerkadang anda ingin menyetel sebuah bidang ke nilai tertentu untuk semua obyek dalam QuerySet. Anda dapat melakukan ini dengan cara update(). Sebagai contoh:
# Update all the headlines with pub_date in 2007.\nEntry.objects.filter(pub_date__year=2007).update(headline="Everything is the same")\nYou can only set non-relation fields and ForeignKey\nfields using this method. To update a non-relation field, provide the new value\nas a constant. To update ForeignKey fields, set the\nnew value to be the new model instance you want to point to. For example:
>>> b = Blog.objects.get(pk=1)\n\n# Change every Entry so that it belongs to this Blog.\n>>> Entry.objects.update(blog=b)\nThe update() method is applied instantly and returns the number of rows\nmatched by the query (which may not be equal to the number of rows updated if\nsome rows already have the new value). The only restriction on the\nQuerySet being updated is that it can only\naccess one database table: the model's main table. You can filter based on\nrelated fields, but you can only update columns in the model's main\ntable. Example:
>>> b = Blog.objects.get(pk=1)\n\n# Update all the headlines belonging to this Blog.\n>>> Entry.objects.filter(blog=b).update(headline="Everything is the same")\nBe aware that the update() method is converted directly to an SQL\nstatement. It is a bulk operation for direct updates. It doesn't run any\nsave() methods on your models, or emit the\npre_save or post_save signals (which are a consequence of calling\nsave()), or honor the\nauto_now field option.\nIf you want to save every item in a QuerySet\nand make sure that the save() method is called on\neach instance, you don't need any special function to handle that. Loop over\nthem and call save():
for item in my_queryset:\n item.save()\nCalls to update can also use F expressions to\nupdate one field based on the value of another field in the model. This is\nespecially useful for incrementing counters based upon their current value. For\nexample, to increment the pingback count for every entry in the blog:
>>> Entry.objects.update(number_of_pingbacks=F("number_of_pingbacks") + 1)\nHowever, unlike F() objects in filter and exclude clauses, you can't\nintroduce joins when you use F() objects in an update -- you can only\nreference fields local to the model being updated. If you attempt to introduce\na join with an F() object, a FieldError will be raised:
# This will raise a FieldError\n>>> Entry.objects.update(headline=F("blog__name"))\nJika anda menemukan anda sendiri butuh menulis permintaan SQL yang terlalu rumit untuk pemetaan-basisdata Django untuk ditangani, anda dapat kembali menulis SQL dengan tangan. Django mempunyai sepasang pilihan untuk menulis permintaan SQL mentah; lihat Melakukan permintaan SQL mentah.
\nAkhirnya, itu penting dicatat bahwa lapisan basisdata Django hanya antarmuka ke basisdata anda. Anda dapat mengakses basisdata anda melalui alat-alat lain, bahasa pemrograman atau kerangka basisdata; tidak ada spesifik-Django tentang basisdata anda.
\n