儲存ForeignKey和ManyToManyField欄位¶

更新ForeignKey欄位的運作方式與儲存一般欄位完全相同 – 將正確類型的物件指派給相關欄位。此範例更新Entry實例entry的blog屬性，假設Entry和Blog的適當實例已儲存到資料庫 (因此我們可以在下面擷取它們)

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

更新ManyToManyField的運作方式略有不同 – 使用欄位上的add()方法將記錄新增到關聯。此範例將Author實例joe新增至entry物件

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

若要一次將多個記錄新增至ManyToManyField，請在呼叫add()時包含多個引數，如下所示

>>> 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 會發出抱怨。

擷取所有物件¶

從表格中擷取物件的最簡單方法是擷取所有物件。若要執行此動作，請在Manager上使用all()方法

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

all()方法會傳回資料庫中所有物件的QuerySet。

使用篩選器擷取特定物件¶

QuerySet由all()傳回的描述資料庫表格中的所有物件。不過，通常您只需要選取完整物件集合的子集。

若要建立這樣的子集，請完善初始的QuerySet，新增篩選條件。完善QuerySet的兩種最常見方式為

filter(**kwargs)

傳回新的QuerySet，其中包含符合給定查找參數的物件。

exclude(**kwargs)

傳回新的QuerySet，其中包含不符合給定查找參數的物件。

查詢參數（上述函式定義中的 **kwargs）應採用下方欄位查詢中所述的格式。

例如，若要取得 2006 年的部落格文章 QuerySet，可以使用 filter()，如下所示：

Entry.objects.filter(pub_date__year=2006)

使用預設的管理器類別，效果等同於：

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)

使用 get() 擷取單一物件¶

filter() 總是會提供一個 QuerySet，即使只有一個物件符合查詢條件 - 在這種情況下，它會是一個包含單一元素的 QuerySet。

如果您知道只有一個物件符合您的查詢條件，您可以使用 get() 方法在 Manager 上，此方法會直接傳回物件。

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

您可以對 get() 使用任何查詢表達式，就像對 filter() 一樣 - 再次參閱下方的欄位查詢。

請注意，使用 get() 和使用 filter() 並搭配切片 [0] 之間存在差異。如果沒有符合查詢的結果，get() 會引發 DoesNotExist 例外。此例外是正在執行查詢的模型類別的一個屬性 - 因此在上面的程式碼中，如果沒有主鍵為 1 的 Entry 物件，Django 會引發 Entry.DoesNotExist。

同樣地，如果有多個項目符合 get() 查詢，Django 也會提出警告。在這種情況下，它會引發 MultipleObjectsReturned，這也是模型類別本身的一個屬性。

其他 QuerySet 方法¶

大多數時候，當您需要從資料庫查詢物件時，會使用 all()、get()、filter() 和 exclude()。然而，這遠非全部；請參閱QuerySet API 參考，以取得所有各種 QuerySet 方法的完整清單。

限制 QuerySet¶

使用 Python 陣列切片語法的一個子集，將您的 QuerySet 限制為特定數量的結果。這相當於 SQL 的 LIMIT 和 OFFSET 子句。

例如，這會傳回前 5 個物件（LIMIT 5）

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

這會傳回第 6 到第 10 個物件（OFFSET 5 LIMIT 5）

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

不支援負索引（例如 Entry.objects.all()[-1]）。

一般而言，切片 QuerySet 會傳回一個新的 QuerySet – 它不會評估查詢。例外情況是您使用 Python 切片語法的「step」參數。例如，這實際上會執行查詢，以傳回前 10 個物件中每隔一個物件的清單。

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

由於其運作方式可能不明確，因此禁止對切片的 queryset 進行進一步的篩選或排序。

若要檢索單一物件而非列表（例如 SELECT foo FROM bar LIMIT 1），請使用索引而非切片。例如，這會傳回資料庫中第一個 Entry，在依標題字母順序排序條目後。

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

這大致等同於

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

請注意，但是，如果沒有物件符合給定的條件，則第一個會引發 IndexError，而第二個會引發 DoesNotExist。有關詳細資訊，請參閱 get()。

欄位查詢¶

欄位查詢是您如何指定 SQL WHERE 子句的核心內容。它們被指定為 QuerySet 方法 filter()、exclude() 和 get() 的關鍵字引數。

基本查詢關鍵字引數採用 field__lookuptype=value 的形式。（這是一個雙底線）。例如

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

（大致）翻譯成以下 SQL

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

查詢中指定的欄位必須是模型欄位的名稱。但是，在 ForeignKey 的情況下，您可以指定以 _id 為後綴的欄位名稱。在這種情況下，值參數預期包含外來模型的主鍵的原始值。例如

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

如果您傳遞無效的關鍵字引數，查詢函式會引發 TypeError。

資料庫 API 支援大約二十多種查詢類型；完整的參考可以在欄位查詢參考中找到。為了讓您了解可用的內容，以下是一些您可能會更常用到的查詢：

exact

「完全」符合。例如

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

會產生類似以下的 SQL

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

如果您沒有提供查詢類型，也就是說，如果您的關鍵字引數不包含雙底線，則會假定查詢類型為 exact。

例如，以下兩個語句是等效的

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

這是為了方便起見，因為 exact 查詢是常見的情況。

iexact

不區分大小寫的匹配。因此，查詢

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

將匹配標題為 "Beatles Blog"、"beatles blog" 甚至是 "BeAtlES blOG" 的 Blog。

contains

區分大小寫的包含測試。例如

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

大致翻譯成以下 SQL

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

請注意，這會匹配標題 'Today Lennon honored'，但不會匹配 'today lennon honored'。

還有一個不區分大小寫的版本，icontains。

startswith、endswith

分別為開頭和結尾搜尋。還有不區分大小寫的版本，分別稱為 istartswith 和 iendswith。

同樣，這只是冰山一角。完整的參考可以在欄位查詢參考中找到。

跨越關係的查詢¶

Django 提供了一種強大且直觀的方式來「追蹤」查詢中的關係，在幕後自動處理 SQL JOIN。要跨越關係，請使用模型之間相關欄位的欄位名稱，以雙底線分隔，直到到達您想要的欄位為止。

此範例檢索所有 Blog 的 name 為 'Beatles Blog' 的 Entry 物件。

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

這種跨越可以像您希望的那樣深入。

它也可以反向運作。雖然它 可以 自訂，但預設情況下，您可以使用模型的小寫名稱來參考查詢中的「反向」關係。

此範例檢索所有具有至少一個 headline 包含 'Lennon' 的 Entry 的 Blog 物件。

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

如果您正在跨多個關係篩選，並且其中一個中間模型沒有符合篩選條件的值，Django 會將其視為存在一個空（所有值都是 NULL），但有效的物件。這表示不會引發任何錯誤。例如，在這個篩選器中

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

（如果存在相關的 Author 模型），如果沒有與條目關聯的 author，則會將其視為沒有附加的 name，而不是因為遺失的 author 而引發錯誤。通常這正是您想要發生的事情。唯一可能令人困惑的情況是，如果您使用 isnull。因此

Blog.objects.filter(entry__authors__name__isnull=True)

將傳回在 author 上具有空 name 的 Blog 物件，以及在 entry 上具有空 author 的物件。如果您不想要後面的那些物件，您可以寫成

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
)

>>> from datetime import date
>>> beatles = Blog.objects.create(name="Beatles Blog")
>>> pop = Blog.objects.create(name="Pop Music Blog")
>>> Entry.objects.create(
...     blog=beatles,
...     headline="New Lennon Biography",
...     pub_date=date(2008, 6, 1),
... )
<Entry: New Lennon Biography>
>>> Entry.objects.create(
...     blog=beatles,
...     headline="New Lennon Biography in Paperback",
...     pub_date=date(2009, 6, 1),
... )
<Entry: New Lennon Biography in Paperback>
>>> Entry.objects.create(
...     blog=pop,
...     headline="Best Albums of 2008",
...     pub_date=date(2008, 12, 15),
... )
<Entry: Best Albums of 2008>
>>> Entry.objects.create(
...     blog=pop,
...     headline="Lennon Would Have Loved Hip Hop",
...     pub_date=date(2020, 4, 1),
... )
<Entry: Lennon Would Have Loved Hip Hop>
>>> Blog.objects.filter(
...     entry__headline__contains="Lennon",
...     entry__pub_date__year=2008,
... )
<QuerySet [<Blog: Beatles Blog>]>
>>> Blog.objects.filter(
...     entry__headline__contains="Lennon",
... ).filter(
...     entry__pub_date__year=2008,
... )
<QuerySet [<Blog: Beatles Blog>, <Blog: Beatles Blog>, <Blog: Pop Music Blog]>

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

篩選器可以參照模型上的欄位¶

到目前為止給出的範例中，我們建構的篩選器是將模型欄位的值與常數進行比較。但是，如果您想將模型欄位的值與同一模型上的另一個欄位進行比較呢？

Django 提供了 F 表達式 來允許這種比較。F() 的實例在查詢中充當模型欄位的參考。然後，這些參考可以用於查詢篩選器中，以比較同一模型實例上兩個不同欄位的值。

例如，要尋找所有評論數多於引用數的網誌文章列表，我們建構一個 F() 物件來參考引用數，並在查詢中使用該 F() 物件。

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

Django 支援使用加法、減法、乘法、除法、模數和冪算術與 F() 物件，包括使用常數和其他 F() 物件。要尋找所有評論數是引用數兩倍以上的網誌文章，我們修改查詢。

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

要尋找所有文章的評分低於引用數和評論數總和的文章，我們發出以下查詢。

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

您也可以使用雙底線表示法來跨越 F() 物件中的關係。帶有雙底線的 F() 物件將引入任何存取相關物件所需的聯結。例如，要檢索所有作者姓名與網誌名稱相同的文章，我們可以發出以下查詢。

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

對於日期和日期/時間欄位，您可以新增或減去 timedelta 物件。以下內容會傳回所有在發布後 3 天以上修改的文章。

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

F() 物件透過 .bitand()、.bitor()、.bitxor()、.bitrightshift() 和 .bitleftshift() 支援位元運算。例如

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

表達式可以參照轉換¶

Django 支援在表達式中使用轉換。

例如，要尋找所有發布年份與上次修改年份相同的 Entry 物件。

>>> from django.db.models import F
>>> Entry.objects.filter(pub_date__year=F("mod_date__year"))

要尋找文章最早發布的年份，我們可以發出以下查詢。

>>> from django.db.models import Min
>>> Entry.objects.aggregate(first_published_year=Min("pub_date__year"))

此範例尋找每個年份的最高評分文章值和所有文章的評論總數。

>>> from django.db.models import OuterRef, Subquery, Sum
>>> Entry.objects.values("pub_date__year").annotate(
...     top_rating=Subquery(
...         Entry.objects.filter(
...             pub_date__year=OuterRef("pub_date__year"),
...         )
...         .order_by("-rating")
...         .values("rating")[:1]
...     ),
...     total_comments=Sum("number_of_comments"),
... )

pk 查找快捷方式¶

為方便起見，Django 提供了 pk 查找快捷方式，代表「主鍵」。

在範例 Blog 模型中，主鍵是 id 欄位，因此以下三個陳述式是等效的。

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

pk 的使用不僅限於 __exact 查詢 — 任何查詢條件都可以與 pk 組合，以在模型的主鍵上執行查詢。

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

pk 查找也適用於聯結。例如，以下三個陳述式是等效的。

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

在 LIKE 陳述式中逸出百分比符號和底線¶

等效於 LIKE SQL 陳述式 (iexact、contains、icontains、startswith、istartswith、endswith 和 iendswith) 的欄位查找會自動逸出在 LIKE 陳述式中使用的兩個特殊字元 — 百分比符號和底線。（在 LIKE 陳述式中，百分比符號表示多字元萬用字元，而底線表示單字元萬用字元。）

這表示事情應該直覺地運作，因此抽象不會洩漏。例如，要檢索所有包含百分比符號的文章，請像其他字元一樣使用百分比符號。

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

Django 會為您處理引號問題；產生的 SQL 看起來會像這樣。

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

底線也是如此。百分比符號和底線都會為您透明地處理。

快取和 QuerySet¶

每個 QuerySet 都包含一個快取，以最大程度地減少資料庫存取。了解它的運作方式將使您可以編寫最有效率的程式碼。

在新建的 QuerySet 中，快取是空的。第一次評估 QuerySet 時 — 因此，發生資料庫查詢時 — Django 會將查詢結果儲存在 QuerySet 的快取中，並傳回明確要求的結果（例如，如果 QuerySet 正在被迭代，則為下一個元素）。後續對 QuerySet 的評估會重複使用快取的結果。

請記住這種快取行為，因為如果您不正確地使用 QuerySet，它可能會讓您失望。例如，以下程式碼會建立兩個 QuerySet、評估它們，然後將它們丟棄。

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

這表示相同的資料庫查詢將執行兩次，實際上使您的資料庫負載加倍。此外，這兩個列表可能不包含相同的資料庫記錄，因為在兩個請求之間的瞬間，可能已新增或刪除 Entry。

為了避免此問題，請儲存 QuerySet 並重複使用它。

>>> queryset = Entry.objects.all()
>>> print([p.headline for p in queryset])  # Evaluate the query set.
>>> print([p.pub_date for p in queryset])  # Reuse 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)

查詢迭代¶

遍歷查詢的預設方式（使用 for）會在幕後產生一個阻塞式的資料庫查詢，因為 Django 會在迭代時載入結果。為了修正此問題，您可以切換到 async for

async for entry in Authors.objects.filter(name__startswith="A"):
    ...

請注意，您也不能執行其他可能會遍歷查詢集的操作，例如將 list() 包裹在它周圍以強制其評估（如果需要，您可以在 comprehension 中使用 async for）。

由於像 filter() 和 exclude() 這樣的 QuerySet 方法實際上不會執行查詢 - 它們會在遍歷時設定要執行的查詢集 - 因此您可以自由地在非同步程式碼中使用這些方法。若要了解哪些方法可以繼續像這樣使用，以及哪些方法具有非同步版本，請閱讀下一節。

QuerySet 和管理員方法¶

管理員和查詢集上的一些方法（例如 get() 和 first()）會強制執行查詢集並且會阻塞。有些方法（例如 filter() 和 exclude()）不會強制執行，因此可以安全地從非同步程式碼中執行。但是您應該如何分辨差異呢？

雖然您可以四處查看是否有以 a 作為前綴的方法（例如，我們有 aget() 但沒有 afilter()），但有一個更合乎邏輯的方法 - 在 QuerySet 參考中查找它是哪種類型的方法。

在那裡，您會發現 QuerySets 上的方法分為兩個部分

• 返回新查詢集的方法：這些是非阻塞的方法，並且沒有非同步版本。您可以在任何情況下自由使用這些方法，但在使用 defer() 和 only() 之前，請閱讀相關說明。

• 不返回查詢集的方法：這些是阻塞的方法，並且具有非同步版本 - 每個非同步方法的名稱都在其文件中註明，但我們的標準模式是新增 a 前綴。

使用這種區別，您可以找出何時需要使用非同步版本，以及何時不需要。例如，以下是一個有效的非同步查詢

user = await User.objects.filter(username=my_input).afirst()

filter() 返回一個查詢集，因此可以安全地在非同步環境中繼續串聯它，而 first() 會評估並返回一個模型實例 - 因此，我們變更為 afirst()，並在整個表達式的前面使用 await，以便以非同步友善的方式呼叫它。

交易¶

目前，非同步查詢和更新不支援交易。您會發現嘗試使用交易會引發 SynchronousOnlyOperation。

如果您想要使用交易，我們建議您在單獨的同步函數中撰寫 ORM 程式碼，然後使用 sync_to_async 呼叫它 - 請參閱 非同步支援 以取得更多資訊。

儲存和查詢 None¶

與其他欄位一樣，將 None 儲存為欄位的值會將其儲存為 SQL NULL。雖然不建議這麼做，但可以使用 Value(None, JSONField()) 來儲存 JSON 純量 null 而不是 SQL NULL。

無論儲存哪個值，從資料庫擷取時，JSON 純量 null 的 Python 表示方式與 SQL NULL 相同，即 None。因此，可能很難區分它們。

這僅適用於 None 作為欄位的最上層值。如果 None 在 list 或 dict 內，它將始終被解讀為 JSON null。

在查詢時，None 值將始終被解讀為 JSON null。若要查詢 SQL NULL，請使用 isnull

>>> Dog.objects.create(name="Max", data=None)  # SQL NULL.
<Dog: Max>
>>> Dog.objects.create(name="Archie", data=Value(None, JSONField()))  # JSON null.
<Dog: Archie>
>>> Dog.objects.filter(data=None)
<QuerySet [<Dog: Archie>]>
>>> Dog.objects.filter(data=Value(None, JSONField()))
<QuerySet [<Dog: Archie>]>
>>> Dog.objects.filter(data__isnull=True)
<QuerySet [<Dog: Max>]>
>>> Dog.objects.filter(data__isnull=False)
<QuerySet [<Dog: Archie>]>

除非您確定要處理 SQL NULL 值，否則請考慮設定 null=False，並為空值提供合適的預設值，例如 default=dict。

鍵、索引和路徑轉換¶

若要根據給定的字典鍵進行查詢，請使用該鍵作為查詢名稱

>>> Dog.objects.create(
...     name="Rufus",
...     data={
...         "breed": "labrador",
...         "owner": {
...             "name": "Bob",
...             "other_pets": [
...                 {
...                     "name": "Fishy",
...                 }
...             ],
...         },
...     },
... )
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": None})
<Dog: Meg>
>>> Dog.objects.filter(data__breed="collie")
<QuerySet [<Dog: Meg>]>

可以將多個鍵串聯在一起以形成路徑查詢

>>> Dog.objects.filter(data__owner__name="Bob")
<QuerySet [<Dog: Rufus>]>

如果鍵是整數，則會將其解讀為陣列中的索引轉換

>>> Dog.objects.filter(data__owner__other_pets__0__name="Fishy")
<QuerySet [<Dog: Rufus>]>

如果您要查詢的鍵與另一個查詢的名稱衝突，請改用 contains 查詢。

若要查詢遺失的鍵，請使用 isnull 查詢

>>> Dog.objects.create(name="Shep", data={"breed": "collie"})
<Dog: Shep>
>>> Dog.objects.filter(data__owner__isnull=True)
<QuerySet [<Dog: Shep>]>

包含和鍵查詢¶

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.create(name="Fred", data={})
<Dog: Fred>
>>> Dog.objects.filter(data__contains={"owner": "Bob"})
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>
>>> Dog.objects.filter(data__contains={"breed": "collie"})
<QuerySet [<Dog: Meg>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador", "owner": "Bob"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.create(name="Fred", data={})
<Dog: Fred>
>>> Dog.objects.filter(data__contained_by={"breed": "collie", "owner": "Bob"})
<QuerySet [<Dog: Meg>, <Dog: Fred>]>
>>> Dog.objects.filter(data__contained_by={"breed": "collie"})
<QuerySet [<Dog: Fred>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_key="owner")
<QuerySet [<Dog: Meg>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"breed": "collie", "owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_keys=["breed", "owner"])
<QuerySet [<Dog: Meg>]>

>>> Dog.objects.create(name="Rufus", data={"breed": "labrador"})
<Dog: Rufus>
>>> Dog.objects.create(name="Meg", data={"owner": "Bob"})
<Dog: Meg>
>>> Dog.objects.filter(data__has_any_keys=["owner", "breed"])
<QuerySet [<Dog: Rufus>, <Dog: Meg>]>

一對多關係¶

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

from django.db.models import Prefetch

prefetch_manager = Prefetch("entry_set", queryset=Entry.entries.all())
Blog.objects.prefetch_related(prefetch_manager)

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

多對多關係¶

多對多關係的兩端都可以自動 API 存取另一端。API 的運作方式與上述「反向」一對多關係類似。

一個差異在於屬性命名：定義 ManyToManyField 的模型使用該欄位本身的屬性名稱，而「反向」模型則使用原始模型的小寫模型名稱，加上 '_set'（就像反向一對多關係一樣）。

一個範例可以讓這更容易理解

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.

與 ForeignKey 類似，ManyToManyField 可以指定 related_name。在上面的範例中，如果 Entry 中的 ManyToManyField 指定了 related_name='entries'，則每個 Author 實例都會有一個 entries 屬性，而不是 entry_set。

與一對多關係的另一個差異是，除了模型實例外，多對多關係的 add()、set() 和 remove() 方法還接受主索引鍵值。例如，如果 e1 和 e2 是 Entry 實例，則這些 set() 呼叫的工作方式相同

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

一對一關係¶

一對一關係與多對一關係非常相似。如果您在模型上定義 OneToOneField，則該模型的實例將透過模型的屬性存取相關物件。

例如

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.

差異在於「反向」查詢。一對一關係中的相關模型也可以存取 Manager 物件，但該 Manager 代表的是單一物件，而不是物件的集合

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

如果沒有物件被指定給此關係，Django 會引發 DoesNotExist 例外。

可以像指定正向關係一樣，將實例指定給反向關係

e.entrydetail = ed

反向關係是如何實現的？¶

其他物件關聯對應器要求您在兩側都定義關係。Django 開發人員認為這違反了 DRY（不要重複自己）原則，因此 Django 只要求您在一端定義關係。

但是，鑑於模型類別在載入其他模型類別之前不知道哪些其他模型類別與其相關聯，這怎麼可能呢？

答案在於app registry。當 Django 啟動時，它會匯入所有在 INSTALLED_APPS 中列出的應用程式，然後匯入每個應用程式內的 models 模組。每當建立新的模型類別時，Django 會將反向關係加入到任何相關的模型中。如果相關的模型尚未匯入，Django 會追蹤這些關係，並在相關模型最終匯入時加入它們。

因此，特別重要的是，您正在使用的所有模型都必須定義在 INSTALLED_APPS 中列出的應用程式中。否則，反向關係可能無法正常運作。

對相關物件的查詢¶

涉及相關物件的查詢遵循與涉及一般數值欄位的查詢相同的規則。在指定要比對的查詢值時，您可以使用物件實例本身，或物件的主鍵值。

例如，如果您有一個 Blog 物件 b，其 id=5，則以下三個查詢將是相同的

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