Panduan topik pada Django's database-abstraction API menggambarkan cara dimana anda dapat menggunakan permintaan Django yang membuat, mengambil, memperbaharui dan menghapus obyek tersendiri. Bagaimanapun, terkadang anda akan butuh mengambil nilai yang berasal oleh meringkas atau*mengumpulkan* kumpulan dari obyek. Topik panduan ini menggambarkan cara yang mengumpulkan nilai-nilai dapat dibangkitkan dan dikembalikan menggunakan permintaan Django.
\nSepanjang panduan ini, kami akan mengacu ke model berikut. Model-model ini digunakan untuk melacak inventaris untuk rangkaian dari toko buku daring:
\nfrom django.db import models\n\nclass Author(models.Model):\n name = models.CharField(max_length=100)\n age = models.IntegerField()\n\nclass Publisher(models.Model):\n name = models.CharField(max_length=300)\n\nclass Book(models.Model):\n name = models.CharField(max_length=300)\n pages = models.IntegerField()\n price = models.DecimalField(max_digits=10, decimal_places=2)\n rating = models.FloatField()\n authors = models.ManyToManyField(Author)\n publisher = models.ForeignKey(Publisher, on_delete=models.CASCADE)\n pubdate = models.DateField()\n\nclass Store(models.Model):\n name = models.CharField(max_length=300)\n books = models.ManyToManyField(Book)\nIn a hurry? Here's how to do common aggregate queries, assuming the models\nabove:
\n# Total number of books.\n>>> Book.objects.count()\n2452\n\n# Total number of books with publisher=BaloneyPress\n>>> Book.objects.filter(publisher__name='BaloneyPress').count()\n73\n\n# Average price across all books.\n>>> from django.db.models import Avg\n>>> Book.objects.all().aggregate(Avg('price'))\n{'price__avg': 34.35}\n\n# Max price across all books.\n>>> from django.db.models import Max\n>>> Book.objects.all().aggregate(Max('price'))\n{'price__max': Decimal('81.20')}\n\n# Difference between the highest priced book and the average price of all books.\n>>> from django.db.models import FloatField\n>>> Book.objects.aggregate(\n... price_diff=Max('price', output_field=FloatField()) - Avg('price'))\n{'price_diff': 46.85}\n\n# All the following queries involve traversing the Book<->Publisher\n# foreign key relationship backwards.\n\n# Each publisher, each with a count of books as a "num_books" attribute.\n>>> from django.db.models import Count\n>>> pubs = Publisher.objects.annotate(num_books=Count('book'))\n>>> pubs\n<QuerySet [<Publisher: BaloneyPress>, <Publisher: SalamiPress>, ...]>\n>>> pubs[0].num_books\n73\n\n# Each publisher, with a separate count of books with a rating above and below 5\n>>> from django.db.models import Q\n>>> above_5 = Count('book', filter=Q(book__rating__gt=5))\n>>> below_5 = Count('book', filter=Q(book__rating__lte=5))\n>>> pubs = Publisher.objects.annotate(below_5=below_5).annotate(above_5=above_5)\n>>> pubs[0].above_5\n23\n>>> pubs[0].below_5\n12\n\n# The top 5 publishers, in order by number of books.\n>>> pubs = Publisher.objects.annotate(num_books=Count('book')).order_by('-num_books')[:5]\n>>> pubs[0].num_books\n1323\nQuerySetLink to this heading#Django menyediakan dua cara membangkitkan pengumpulan. Cara pertama adalah membangkitkan nilai ringkasan terhadap keseluruhan QuerySet. Sebagai contoh, katakan anda ingin menghitung rata-rata harga dari semua buku tersedia untuk dijual. Sintaksis permintaan Django menyediakan sarana untuk menggambarkan kumpulan dari semua buku:
>>> Book.objects.all()\nApa kami butuhkan adalah cara menghitung ringkasan nilai terhadap obyek yang memiliki QuerySet ini. Ini diselesaikan dengan menambah sebuah klausa aggregate() kedalam QuerySet:
>>> from django.db.models import Avg\n>>> Book.objects.all().aggregate(Avg('price'))\n{'price__avg': 34.35}\nall() berulang di contoh ini, jadi ini dapat disederhanakan menjadi:
>>> Book.objects.aggregate(Avg('price'))\n{'price__avg': 34.35}\nArgumen pada klausa aggregate() menggambarkan nilai pengumpulan yang kami ingin hitung - dalam kasus ini, rata-rata dari bidang price pada model Book. Sebuah daftar dari fungsi pengumpulan yang tersedia dapat ditemukan di QuerySet reference.
aggregate() adalah klausa terminal untuk sebuah QuerySet yang, ketika dipanggil, mengembalikan sebuah kamus dari pasangan nama-nilai. Nama adalah sebuah penciri untuk nilai pengumpulan; nilai adalah pengumpulan yang dihitung. Nama adalah otomatis dibangkitkan dari nama dari bidang dan fungsi pengumpulan. Jika anda ingin manual menentukan nama untuk nilai pengumpulan, anda dapat melakukannya dengan menyediakan nama itu ketika anda menentukan klausa pengumpulan:
>>> Book.objects.aggregate(average_price=Avg('price'))\n{'average_price': 34.35}\nIf you want to generate more than one aggregate, you add another argument to\nthe aggregate() clause. So, if we also wanted to know the maximum and\nminimum price of all books, we would issue the query:
>>> from django.db.models import Avg, Max, Min\n>>> Book.objects.aggregate(Avg('price'), Max('price'), Min('price'))\n{'price__avg': 34.35, 'price__max': Decimal('81.20'), 'price__min': Decimal('12.99')}\nQuerySetLink to this heading#The second way to generate summary values is to generate an independent\nsummary for each object in a QuerySet. For example, if you are\nretrieving a list of books, you may want to know how many authors contributed\nto each book. Each Book has a many-to-many relationship with the Author; we\nwant to summarize this relationship for each book in the QuerySet.
Per-object summaries can be generated using the\nannotate() clause. When an annotate() clause is\nspecified, each object in the QuerySet will be annotated with the\nspecified values.
The syntax for these annotations is identical to that used for the\naggregate() clause. Each argument to annotate() describes\nan aggregate that is to be calculated. For example, to annotate books with the\nnumber of authors:
# Build an annotated queryset\n>>> from django.db.models import Count\n>>> q = Book.objects.annotate(Count('authors'))\n# Interrogate the first object in the queryset\n>>> q[0]\n<Book: The Definitive Guide to Django>\n>>> q[0].authors__count\n2\n# Interrogate the second object in the queryset\n>>> q[1]\n<Book: Practical Django Projects>\n>>> q[1].authors__count\n1\nSeperti aggregate(), nama untuk catatan otomatis berasal dari nama dari fungsi pengumpulan dan nama dari bidang sedang dikumpulkan. Anda dapat menimpa nama awalan ini dengan menyediakan sebuah nama lain ketika anda menentukan catatan:
>>> q = Book.objects.annotate(num_authors=Count('authors'))\n>>> q[0].num_authors\n2\n>>> q[1].num_authors\n1\nTidak seperti aggregate(), annotate() adalah bukan klausa terminal. Keluaran dari klausa annotate() adalah sebuah QuerySet; QuerySet ini dapat dirubah menggunakan apapun selain operasi QuerySet, termasuk filter(), order_by(), atau bahkan tambahan panggilan pada annotate().
Combining multiple aggregations with annotate() will yield the\nwrong results because joins are used instead of subqueries:
>>> book = Book.objects.first()\n>>> book.authors.count()\n2\n>>> book.store_set.count()\n3\n>>> q = Book.objects.annotate(Count('authors'), Count('store'))\n>>> q[0].authors__count\n6\n>>> q[0].store__count\n6\nUntuk kebanyakan pengumpulan, tidak ada jalan menghindari masalah ini, bagaimanapun, pengumpulan Count mempunai sebuah parameter distinct yang mungkin membantu:
>>> q = Book.objects.annotate(Count('authors', distinct=True), Count('store', distinct=True))\n>>> q[0].authors__count\n2\n>>> q[0].store__count\n3\nSejauh ini, kami telah berurusan dengan pengumpulan terhadap bidang yang milik ke model sedang diminta. Bagaimanapun, terkadang nilai anda ingin kumpulkan akan milik ke model yang terkait ke model anda sedang meminta.
\nKetika anda menentukan bidang untuk dikumpulkan dalam sebuah fungsi pengumpulan, Django akan mengizinkan anda menggunakan double underscore notation sama yang digunakan ketika mengacu ke bidang terkait dalam penyaring. Django akan kemudian menangani gabungan table apapun yang dibutuhkan untuk mengambil dan mengumpulkan nilai terkait.
\nSebagai contoh, untuk menemukan jangkauan harga dari buku ditawarkan disetiap toko, anda dapat menggunakan catatan:
\n>>> from django.db.models import Max, Min\n>>> Store.objects.annotate(min_price=Min('books__price'), max_price=Max('books__price'))\nIni memberitahu Django untuk mengambil model Store, gabung (melalui hubungan many-to-many) dengan model Book, dan dikumpulkan pada bidang harga dari model buku untuk menghasilkan sebuah nilai minimal dan maksimal.
Aturan sama berlaku pada klausa aggregate(). Jika anda ingin mengetahui harga terendah dan tertinggi dari buku apapun yang tersedia untuk dijual di toko apapun, anda dapat menggunakan pengumpulan:
>>> Store.objects.aggregate(min_price=Min('books__price'), max_price=Max('books__price'))\nIkatan join dapat sedalam seperti anda minta. Sebagai contoh, untuk mengeluarkan umur dari penulis termuda dari buku apapun yang tersedia untuk dijual, anda dapat menerbitkan permintaan:
\n>>> Store.objects.aggregate(youngest_age=Min('books__authors__age'))\nDalam sebuah cara mirip pada Pencarian yang menjangkau hubungan, pengumpulan dan catatan pada bidang dari model atau model yang terkait ke satu anda sedang meminta dapat menyertakan lintasan hubungan "reverse". Nama huruf kecil dari model terkait dan garis bawah ganda digunakan disini juga.
\nSebagai contoh, kami dapat meminta untuk semua penerbit, dicatat dengan masing-masing jumlah penghitung stok buku (catat bahwa kami menggunakan 'book' untuk menentukan Publisher -> Book membalikkan lompatan foreign key):
>>> from django.db.models import Avg, Count, Min, Sum\n>>> Publisher.objects.annotate(Count('book'))\n(Setiap Publisher dalam menghasilkan QuerySet akan mempunyai sebuah atribut tambahan disebut book__count.)
Kami dapat juga meminta untuk buku tertua dari setiap dari itu dikelola oleh setiap penerbit:
\n>>> Publisher.objects.aggregate(oldest_pubdate=Min('book__pubdate'))\n(Hasil kamus akan mempunyai sebuah kunci dipanggil 'oldest_pubdate'. Jika tidak ada nama lain seperti itu telah ditentukan, itu akan agak panjang 'book__pubdate__min'.)
Ini tidak berlaku hanya pada foreign key. Itu juga bekerja dengan hubungan many-to-many. Sebagai contoh, kami dapat meminta untuk setiap penulis, dicatat dengan jumlah nomor dari halaman mempertimbangkan semua buku penulis mempunyai penulis(-bersama) (catat bagaimana menggunakan 'book' untuk menentukan Author -> Book membalikkan lompatan many-to-many):
>>> Author.objects.annotate(total_pages=Sum('book__pages'))\n(Setiap Author dalam menghasilkan QuerySet akan mempunyai sebuah atribut tambahan dipanggil total_pages. Jika tidak ada nama lain itu, itu akan menjadi agak panjang book__pages__sum.)
Atau minta untuk penilaian rata-rata dari semua buku ditulis oleh penulis kami punyai pada berkas:
\n>>> Author.objects.aggregate(average_rating=Avg('book__rating'))\n(Hasil kamus akan mempunyai sebuah kunci dipanggil 'average_rating'. Jika tidak ada nama lain seperti itu telah ditentukan, itu akan agak panjang 'book__rating__avg'.)
QuerySet lainLink to this heading#filter() dan exclude()Link to this heading#Pengumpulan dapat juga ikut serta dalam penyaring. filter() (atau``exclude()``) apapun berlaku pada bidang model biasa akan mempunyai pengaruh dari membatasi obyek yang dianggap untuk pengumpulan.
Ketika digunakan dengan sebuah klausa annotate(), sebuah penyaring mempunyai pengaruh dari membatasi obyek untuk dimana sebuah catatan dihitung. Sebagai contoh, anda dapat membangkitkan daftar dari semua buku yang mempunyai sebuah judul dimulai dengan "Django"" menggunakan permintaan:
>>> from django.db.models import Avg, Count\n>>> Book.objects.filter(name__startswith="Django").annotate(num_authors=Count('authors'))\nKetika digunakan dengan sebuah klausa aggregate(), sebuah penyaring mempunyai pengaruh dari membatasi obyek untuk dimana sebuah pengumpulan dihitung. Sebagai contoh, anda dapat membangkitkan rata-rata harga dari semua buku yang mempunyai sebuah judul dimulai dengan "Django"" menggunakan permintaan:
>>> Book.objects.filter(name__startswith="Django").aggregate(Avg('price'))\nNilai dicatat dapat juga disaring. Nama lain untuk catatan dapat digunaan dalam klausa filter() dan exclude() di cara sama seperti bidang model lainnya apapun.
Sebagai contoh, untuk membangkitkan sebuah daftar buku yang mempunyai lebih dari satu penulis, anda dapat menerbitkan permintaan:
\n>>> Book.objects.annotate(num_authors=Count('authors')).filter(num_authors__gt=1)\nPermintaan ini membangkitkan sebuah kumpulan hasil keterangan, dan kemudian membangkitkan sebuah penyaring berdasarkan pada keterangan itu.
\nJika anda butuh dua keterangan dengan dua penyaring terpisah anda dapat menggunakan argumen filter dengan pengumpulan apapun. Sebagai contoh, untuk membangkitkan daftar dari penulis dengan jumlah peringkat buku tertinggi:
>>> highly_rated = Count('book', filter=Q(book__rating__gte=7))\n>>> Author.objects.annotate(num_books=Count('book'), highly_rated_books=highly_rated)\nEach Author in the result set will have the num_books and\nhighly_rated_books attributes. See also Pengumpulan bersyarat.
annotate() dan filter()Link to this heading#Ketika mengembangkan sebuah permintaan rumit yang melibatkan kedua klausa annotate() dan filter(), berikan perhatian khusus pada urutan dimana klausa diberlakukan pada QuerySet.
Ketika sebuah klausa annotate() diberlakukan pada sebuah permintaan, catatan dihitung terhadap keadaan dari permintaan sampai titik dimana catatan diminta. Impliaksi praktik dari ini adalah bahwa filter() dan annotate() bukan operasi komutatif.
Diberikan:
\nPenerbit A mempunyai dua buku dengan nilai 4 dan 5.
Penerbit B mempunyai dua buku dengan nilai 1 dan 4.
Penerbit C mempunyai satu buku dengan penilaian 1.
Ini adalah sebuah contoh dengan pengumpulan Count:
>>> a, b = Publisher.objects.annotate(num_books=Count('book', distinct=True)).filter(book__rating__gt=3.0)\n>>> a, a.num_books\n(<Publisher: A>, 2)\n>>> b, b.num_books\n(<Publisher: B>, 2)\n\n>>> a, b = Publisher.objects.filter(book__rating__gt=3.0).annotate(num_books=Count('book'))\n>>> a, a.num_books\n(<Publisher: A>, 2)\n>>> b, b.num_books\n(<Publisher: B>, 1)\nKedua permintaan mengembalikan sebuah daftar dari penerbit yang mempunyai setidaknya satu buku dengan penilaian melebihi 3.0, karenanya penerbit C tidak disertakan.
\nDalam permintaan pertama, catatan mendahului penyaring, jadi penyaring tidak mempunyai pengaruh pada catatan. distinct=True dibutuhkan untuk menghindari query bug.
Permintaan kedua menghitung jumlah buku yang mempunyai nilai melebihi 3.0 untuk setiap penerbit. Penyaring ini mendahului catatan, jadi batasan penyaring obyek dianggap ketika menghitung catatan.
\nIni adalah sebuah contoh lain dengan pengumpulan Avg:
>>> a, b = Publisher.objects.annotate(avg_rating=Avg('book__rating')).filter(book__rating__gt=3.0)\n>>> a, a.avg_rating\n(<Publisher: A>, 4.5) # (5+4)/2\n>>> b, b.avg_rating\n(<Publisher: B>, 2.5) # (1+4)/2\n\n>>> a, b = Publisher.objects.filter(book__rating__gt=3.0).annotate(avg_rating=Avg('book__rating'))\n>>> a, a.avg_rating\n(<Publisher: A>, 4.5) # (5+4)/2\n>>> b, b.avg_rating\n(<Publisher: B>, 4.0) # 4/1 (book with rating 1 excluded)\nPermintaan pertama meminta untuk rata-rata penilaian dari semua penerbit buku untuk penerbit yang mempunyai setidaknya satu buku ketika penilaian melebihi 3.0. Permintaan kedua meminta untuk rata-rata dari penilaian buku penerbit untuk hanya mereka penilaian melebihi 3.0.
\nItu adalah sangat sulit memahami bahwa ORM akan menterjemahkan queryset rumit kedalam permintaan SQL ketika dalam keraguan, periksa SQL dengan str(queryset.query) dan tulis jumlah besar percobaan.
order_by()Link to this heading#Catatan dapat digunakan sebagai dasar untuk pengurutan. Ketika anda menentukan sebuah klausa order_by(), pengumpulan anda sediakan dapat mengacu nama lain apapun ditentukan sebagai bagian dari sebuah klausa annotate() dalam permintaan.
Sebagai contoh, untuk mengurutkan QuerySet dari buku dengan jumlah dari pengarang yang memiliki bantuan pada buku, anda dapat menggunakan permintaan berikut:
>>> Book.objects.annotate(num_authors=Count('authors')).order_by('num_authors')\nvalues()Link to this heading#Biasanya, catatan dibangkitkan pada dasar per-obyek - sebuah QuerySet dicatat akan mengembalikan satu hasil untuk setiap obyek dalam QuerySet asli. Bagaimanapun, ketika sebuah klausa values() digunakan untuk membatasi kolom yang dikembalikan dalam kumpulan hasil, metode untuk menilai catatan adak sedikit berbeda. Sebagai gantinya mengembalikan sebuah hasil dicatat untuk setiap hasil dalam QuerySet asli, hasil asli dikelompokkan menurut pada perpaduan unik dari bidang-bidang ditentukan dalam klausa values(). Sebuah catatam kemudian disediakan untuk setiap kelompok unik; catatan dihitung terhadap semua anggota dari kelompok.
Untuk setiap contoh, pertimbangkan sebuah permintaan penulis yang berusaha menemukan rata-rata penilaian dari buku ditulis oleh setiap penulis.
\n>>> Author.objects.annotate(average_rating=Avg('book__rating'))\nIni akan mengembalikan satu hasil untuk setiap penulis di basisdata, diberikan keterangan dengan nilai buku rata-rata mereka.
\nBagaimanapun, hasil akan sedikit berbeda jika anda menggunakan kalusa values():
>>> Author.objects.values('name').annotate(average_rating=Avg('book__rating'))\nDalam contoh ini, penulis akan dikelompokkan berdasarkan nama, jadi anda akan hanya mendapatkan sebuah hasil dicatata untuk setiap nama penulis unik. Ini berarti jika anda mempunyai dua penulis dengan nama sama, hasil mereka akan digabung kedalam hasil tunggal di keluaran dari permintaan; rata-rata akan dihitung sebagai rata-rata terhadap buku ditulis oleh kedua penulis.
\nannotate() dan values()Link to this heading#Seperti klausa filter(), urutan dimana klausa annotate() dan values() diberlakukan pada sebuah permintaan adalah signifikan. Jika klausa values() mendahului annotated(), catatan akan dihitung menggunakan pengelomppokan digambarkan oleh klausa values().
Bagaimanapun, jika klausa annotate() mendahului klausa values(), catatan akan dibangkitkan terhadap keseluruhan kumpulan permintaan. Dalam kasus ini, klausa values() hanya membatasi bidang yang dibangkitkan pada keluaran.
Sebagai contoh, jika kami membalikkan urutan dari klausa values() dan annotate() dari contoh kami sebelumnya:
>>> Author.objects.annotate(average_rating=Avg('book__rating')).values('name', 'average_rating')\nIni akan sekarang menghasilkan hasil unik untuk setiap penulis; bagaimanapun, hanya nama penulis dan catatan average_rating akan dikembalikan dalam data keluaran.
Anda harus juga catat bahwa average_rating telah jelas disertakan dalam daftar dari nilai-nilai untuk dikembalikan. Ini dibutuhkan karena dari urutan dari klausa values() dan annotate().
Jika klausa values() mendahului klausa annotate(), setiap catatan akan otomatis ditambahkan ke kumpulan hasil. Bagaimanapun, jika klausa values() diberlakukan setelah klausa annotate(), anda butuh jelas menyertakan kolom pengumpulan.
order_by()Link to this heading#Fields that are mentioned in the order_by() part of a queryset are used\nwhen selecting the output data, even if they are not otherwise specified in the\nvalues() call. These extra fields are used to group "like" results together\nand they can make otherwise identical result rows appear to be separate. This\nshows up, particularly, when counting things.
Berdasarkan cara contoh, seharusnya anda mempunyai model seperti ini:
\nfrom django.db import models\n\nclass Item(models.Model):\n name = models.CharField(max_length=10)\n data = models.IntegerField()\nIf you want to count how many times each distinct data value appears in an\nordered queryset, you might try this:
items = Item.objects.order_by('name')\n# Warning: not quite correct!\nitems.values('data').annotate(Count('id'))\n...which will group the Item objects by their common data values and\nthen count the number of id values in each group. Except that it won't\nquite work. The ordering by name will also play a part in the grouping, so\nthis query will group by distinct (data, name) pairs, which isn't what you\nwant. Instead, you should construct this queryset:
items.values('data').annotate(Count('id')).order_by()\n...membersihkan pengurutan apapun di permintaan. Anda dapat juga mengurutkan berdasarkan, katakan, data tanpa pengaruh berbahaya apapun, sejak itu sudah bermain sebuah peran dalam permintaan.
Perilaku ini adalah sama seperti dicatat dalam dokumentasi queryset untuk distinct() dan aturan umum adalah sama: biasanya anda tidak ingin kolom tambahan bermain bagian dalam hasil, jadi bersihkan pengurutan, atau setidaknya pastikan itu terbatas hanya bidang-bidang tersebut anda juga pilih dalam sebuah panggilan values().
Anda dapat juga membangkitkan sebuah pengumpulan pada hasil dari sebuah catatan. Ketika anda menentukan sebuah klausa aggregate(), pengumpulan anda sediakan dapat mengacu setiap nama lain ditentukan sebagai bagian dari sebuah klausa annotated() dalam permintaan.
Sebagai contoh, jika anda ingin menjumlahkan angka rata-rata dari penulis per buku anda pertama membubuhi catatan kumpulan buku dengan jumlah penulis, lalu kumpulkan jumlah penulis itu, mengacu bidang membubuhi catatan
\n>>> from django.db.models import Avg, Count\n>>> Book.objects.annotate(num_authors=Count('authors')).aggregate(Avg('num_authors'))\n{'num_authors__avg': 1.66}\n