filter()¶

filter(*args, **kwargs)¶

返回一個新的 QuerySet，其中包含符合給定查詢參數的物件。

查詢參數 (**kwargs) 應採用下方 欄位查詢 中描述的格式。多個參數在底層 SQL 語句中會透過 AND 連接。

如果需要執行更複雜的查詢（例如，包含 OR 語句的查詢），可以使用 Q 物件 (*args)。

exclude()¶

exclude(*args, **kwargs)¶

返回一個新的 QuerySet，其中包含不符合給定查詢參數的物件。

查詢參數 (**kwargs) 應採用下方 欄位查詢 中描述的格式。多個參數在底層 SQL 語句中會透過 AND 連接，並且整個內容會包含在 NOT() 中。

此範例排除所有 pub_date 晚於 2005-1-3 且 headline 為「Hello」 的所有條目

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3), headline="Hello")

以 SQL 術語來說，這相當於

SELECT ...
WHERE NOT (pub_date > '2005-1-3' AND headline = 'Hello')

此範例排除所有 pub_date 晚於 2005-1-3 或標題為「Hello」的所有條目

Entry.objects.exclude(pub_date__gt=datetime.date(2005, 1, 3)).exclude(headline="Hello")

以 SQL 術語來說，這相當於

SELECT ...
WHERE NOT pub_date > '2005-1-3'
AND NOT headline = 'Hello'

請注意，第二個範例更具限制性。

如果需要執行更複雜的查詢（例如，包含 OR 語句的查詢），可以使用 Q 物件 (*args)。

annotate()¶

annotate(*args, **kwargs)¶

使用提供的 查詢表達式 列表來註解 QuerySet 中的每個物件。表達式可以是簡單的值、模型上的欄位參考（或任何相關模型），或是對與 QuerySet 中的物件相關的物件計算出的彙總表達式（平均值、總和等）。

annotate() 的每個引數都是一個註解，將會新增到返回的 QuerySet 中的每個物件。

Django 提供的彙總函式在下方的 彙總函式 中描述。

使用關鍵字引數指定的註解將使用該關鍵字作為註解的別名。匿名引數將根據彙總函式的名稱和正在彙總的模型欄位產生別名。只有參考單一欄位的彙總表達式才能是匿名引數。其他所有內容都必須是關鍵字引數。

例如，如果正在操作部落格列表，您可能想確定每個部落格中有多少條目

>>> from django.db.models import Count
>>> q = Blog.objects.annotate(Count("entry"))
# The name of the first blog
>>> q[0].name
'Blogasaurus'
# The number of entries on the first blog
>>> q[0].entry__count
42

Blog 模型本身沒有定義 entry__count 屬性，但透過使用關鍵字引數來指定彙總函式，您可以控制註解的名稱

>>> q = Blog.objects.annotate(number_of_entries=Count("entry"))
# The number of entries on the first blog, using the name provided
>>> q[0].number_of_entries
42

有關彙總的深入討論，請參閱有關彙總的主題指南。

alias()¶

alias(*args, **kwargs)¶

與 annotate() 相同，但不是註解 QuerySet 中的物件，而是儲存表達式，以便稍後與其他 QuerySet 方法重複使用。當不需要表達式本身的結果，但它用於篩選、排序或作為複雜表達式的一部分時，這非常有用。不選擇未使用的值可以減少資料庫中的冗餘工作，這應該會帶來更好的效能。

例如，如果想找到具有超過 5 個條目的部落格，但對確切的條目數量不感興趣，可以這樣做

>>> from django.db.models import Count
>>> blogs = Blog.objects.alias(entries=Count("entry")).filter(entries__gt=5)

alias() 可以與 annotate()、exclude()、filter()、order_by() 和 update() 結合使用。若要將別名表達式與其他方法（例如 aggregate()）一起使用，必須將其升級為註解

Blog.objects.alias(entries=Count("entry")).annotate(
    entries=F("entries"),
).aggregate(Sum("entries"))

filter() 和 order_by() 可以直接採用表達式，但表達式的建構和使用通常不會在同一個地方進行（例如，QuerySet 方法會建立表達式，以供稍後在視圖中使用）。 alias() 允許逐步建立複雜的表達式，可能會跨越多個方法和模組，透過別名參考表達式部分，並且僅將 annotate() 用於最終結果。

order_by()¶

order_by(*fields)¶

預設情況下，QuerySet 返回的結果會按照模型 Meta 中的 ordering 選項所提供的排序元組進行排序。 您可以使用 order_by 方法來針對每個 QuerySet 覆寫此行為。

範例

Entry.objects.filter(pub_date__year=2005).order_by("-pub_date", "headline")

上述結果會先依 pub_date 遞減排序，然後再依 headline 遞增排序。"-pub_date" 前面的負號表示遞減排序。遞增排序是預設的。若要隨機排序，請使用 "?"，如下所示

Entry.objects.order_by("?")

注意：order_by('?') 查詢可能會很耗費資源且速度緩慢，取決於您使用的資料庫後端。

若要依不同模型中的欄位排序，請使用與跨模型關聯查詢時相同的語法。也就是說，欄位名稱，後面接著雙底線 (__)，接著是新模型中的欄位名稱，依此類推，您想要加入多少模型都可以。例如

Entry.objects.order_by("blog__name", "headline")

如果您嘗試依另一個模型的關聯欄位排序，Django 將會使用相關模型的預設排序，如果沒有指定 Meta.ordering，則會依相關模型的主鍵排序。例如，由於 Blog 模型沒有指定預設排序

Entry.objects.order_by("blog")

...與此相同

Entry.objects.order_by("blog__id")

如果 Blog 有 ordering = ['name']，則第一個 queryset 將與此相同

Entry.objects.order_by("blog__name")

您也可以透過呼叫表達式上的 asc() 或 desc()，依查詢表達式排序

Entry.objects.order_by(Coalesce("summary", "headline").desc())

asc() 和 desc() 具有控制如何排序 Null 值的引數 (nulls_first 和 nulls_last)。

如果您同時使用 distinct()，請謹慎依相關模型中的欄位排序。請參閱 distinct() 中的註解，了解相關模型排序如何變更預期結果。

class Event(Model):
    parent = models.ForeignKey(
        "self",
        on_delete=models.CASCADE,
        related_name="children",
    )
    date = models.DateField()


Event.objects.order_by("children__date")

無法指定排序是否應區分大小寫。關於大小寫靈敏度，Django 將會以資料庫後端通常的排序方式排序結果。

您可以使用 Lower 將欄位轉換為小寫，以實現大小寫一致的排序

Entry.objects.order_by(Lower("headline").desc())

如果您不希望任何排序應用於查詢，甚至包括預設排序，請呼叫不帶任何參數的 order_by()。

您可以透過檢查 QuerySet.ordered 屬性來判斷查詢是否已排序，如果 QuerySet 已以任何方式排序，則該屬性將為 True。

每個 order_by() 呼叫都會清除任何先前的排序。例如，此查詢將依 pub_date 排序，而不是依 headline 排序

Entry.objects.order_by("headline").order_by("pub_date")

reverse()¶

reverse()¶

使用 reverse() 方法來反轉 queryset 元素的返回順序。第二次呼叫 reverse() 會將排序恢復為正常方向。

若要檢索 queryset 中的「最後」五個項目，您可以執行此操作

my_queryset.reverse()[:5]

請注意，這與在 Python 中從序列末尾切片略有不同。上面的範例會先返回最後一個項目，然後是倒數第二個項目，依此類推。如果我們有一個 Python 序列並查看 seq[-5:]，我們會先看到倒數第五個項目。Django 不支援這種存取模式（從末尾切片），因為它無法在 SQL 中有效率地執行。

此外，請注意，reverse() 通常應該僅在具有定義排序的 QuerySet 上呼叫（例如，當針對定義預設排序的模型進行查詢時，或使用 order_by() 時）。如果未針對給定的 QuerySet 定義此類排序，則在其上呼叫 reverse() 沒有實際效果（在呼叫 reverse() 之前排序未定義，之後仍將保持未定義）。

distinct()¶

distinct(*fields)¶

返回一個新的 QuerySet，其在 SQL 查詢中使用 SELECT DISTINCT。這會消除查詢結果中的重複列。

預設情況下，QuerySet 不會消除重複的列。實際上，這很少是問題，因為諸如 Blog.objects.all() 之類的簡單查詢不會引入重複結果列的可能性。但是，如果您的查詢跨越多個表，則在評估 QuerySet 時，可能會得到重複的結果。這時您可以使用 distinct()。

僅在 PostgreSQL 上，您可以傳遞位置引數 (*fields) 來指定 DISTINCT 應用的欄位名稱。這會轉換為 SELECT DISTINCT ON SQL 查詢。以下是差異。對於普通的 distinct() 呼叫，資料庫在確定哪些列不同時，會比較每一列中的每個欄位。對於具有指定欄位名稱的 distinct() 呼叫，資料庫僅會比較指定的欄位名稱。

範例（第一個之後的範例僅適用於 PostgreSQL）

>>> Author.objects.distinct()
[...]

>>> Entry.objects.order_by("pub_date").distinct("pub_date")
[...]

>>> Entry.objects.order_by("blog").distinct("blog")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author", "pub_date")
[...]

>>> Entry.objects.order_by("blog__name", "mod_date").distinct("blog__name", "mod_date")
[...]

>>> Entry.objects.order_by("author", "pub_date").distinct("author")
[...]

Entry.objects.order_by("blog").distinct("blog")

values()¶

values(*fields, **expressions)¶

返回一個 QuerySet，當作為可迭代物件使用時，該物件會返回字典而非模型實例。

每個字典都代表一個物件，其鍵對應於模型物件的屬性名稱。

此範例比較了 values() 的字典與一般的模型物件

# This list contains a Blog object.
>>> Blog.objects.filter(name__startswith="Beatles")
<QuerySet [<Blog: Beatles Blog>]>

# This list contains a dictionary.
>>> Blog.objects.filter(name__startswith="Beatles").values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>

values() 方法接受可選的位置參數，*fields，用於指定應限制 SELECT 的欄位名稱。如果您指定了欄位，則每個字典將僅包含您指定的欄位的欄位鍵/值。如果您沒有指定欄位，則每個字典將包含資料庫表格中每個欄位的鍵和值。

範例

>>> Blog.objects.values()
<QuerySet [{'id': 1, 'name': 'Beatles Blog', 'tagline': 'All the latest Beatles news.'}]>
>>> Blog.objects.values("id", "name")
<QuerySet [{'id': 1, 'name': 'Beatles Blog'}]>

values() 方法還接受可選的關鍵字引數，**expressions，這些引數會傳遞到 annotate()

>>> from django.db.models.functions import Lower
>>> Blog.objects.values(lower_name=Lower("name"))
<QuerySet [{'lower_name': 'beatles blog'}]>

您可以在排序中使用內建和 自訂查詢。例如

>>> from django.db.models import CharField
>>> from django.db.models.functions import Lower
>>> CharField.register_lookup(Lower)
>>> Blog.objects.values("name__lower")
<QuerySet [{'name__lower': 'beatles blog'}]>

在 values() 子句中的聚合會在同一個 values() 子句中的其他參數之前應用。如果您需要依另一個值分組，請將其添加到較早的 values() 子句中。例如

>>> from django.db.models import Count
>>> Blog.objects.values("entry__authors", entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 20}, {'entry__authors': 1, 'entries': 13}]>
>>> Blog.objects.values("entry__authors").annotate(entries=Count("entry"))
<QuerySet [{'entry__authors': 1, 'entries': 33}]>

一些值得一提的細微之處

• 如果您有一個名為 foo 的欄位，該欄位是一個 ForeignKey，則預設的 values() 呼叫將返回一個名為 foo_id 的字典鍵，因為這是儲存實際值的隱藏模型屬性的名稱（foo 屬性參照相關的模型）。當您呼叫 values() 並傳入欄位名稱時，您可以傳入 foo 或 foo_id，您將會得到相同的結果（字典鍵將與您傳入的欄位名稱相符）。

  例如

  >>> Entry.objects.values()
  <QuerySet [{'blog_id': 1, 'headline': 'First Entry', ...}, ...]>
  
  >>> Entry.objects.values("blog")
  <QuerySet [{'blog': 1}, ...]>
  
  >>> Entry.objects.values("blog_id")
  <QuerySet [{'blog_id': 1}, ...]>
  

• 當將 values() 與 distinct() 一起使用時，請注意排序可能會影響結果。請參閱 distinct() 中的註解以了解詳細資訊。

• 如果您在 extra() 呼叫之後使用 values() 子句，則 extra() 中的 select 參數所定義的任何欄位都必須明確包含在 values() 呼叫中。在 values() 呼叫之後進行的任何 extra() 呼叫都將忽略其額外選取的欄位。

• 在 values() 之後呼叫 only() 和 defer() 是沒有意義的，因此這樣做會引發 TypeError。

• 結合轉換和聚合需要使用兩個 annotate() 呼叫，可以是明確的或是作為 values() 的關鍵字引數。如上所述，如果轉換已在相關欄位類型上註冊，則可以省略第一個 annotate()，因此以下範例是等效的

  >>> from django.db.models import CharField, Count
  >>> from django.db.models.functions import Lower
  >>> CharField.register_lookup(Lower)
  >>> Blog.objects.values("entry__authors__name__lower").annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.values(entry__authors__name__lower=Lower("entry__authors__name")).annotate(
  ...     entries=Count("entry")
  ... )
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  >>> Blog.objects.annotate(entry__authors__name__lower=Lower("entry__authors__name")).values(
  ...     "entry__authors__name__lower"
  ... ).annotate(entries=Count("entry"))
  <QuerySet [{'entry__authors__name__lower': 'test author', 'entries': 33}]>
  

當您知道您只需要少量可用欄位的值，並且不需要模型實例物件的功能時，此方法很有用。僅選取您需要使用的欄位會更有效率。

最後，請注意，您可以在 values() 呼叫之後呼叫 filter()、order_by() 等，這表示這兩個呼叫是相同的

Blog.objects.values().order_by("id")
Blog.objects.order_by("id").values()

建立 Django 的人們偏好先放置所有影響 SQL 的方法，然後（可選地）放置任何影響輸出的方法（例如 values()），但這其實並不重要。這是您展現個性的機會。

您也可以透過 OneToOneField、ForeignKey 和 ManyToManyField 屬性參照相關模型上的欄位，這些模型具有反向關係

>>> Blog.objects.values("name", "entry__headline")
<QuerySet [{'name': 'My blog', 'entry__headline': 'An entry'},
     {'name': 'My blog', 'entry__headline': 'Another entry'}, ...]>

values_list()¶

values_list(*fields, flat=False, named=False)¶

這與 values() 相似，不同之處在於，它在迭代時會返回元組，而不是返回字典。每個元組都包含從傳入 values_list() 呼叫的個別欄位或表達式中的值 — 因此第一個項目是第一個欄位，依此類推。例如

>>> Entry.objects.values_list("id", "headline")
<QuerySet [(1, 'First entry'), ...]>
>>> from django.db.models.functions import Lower
>>> Entry.objects.values_list("id", Lower("headline"))
<QuerySet [(1, 'first entry'), ...]>

如果您只傳入單個欄位，您還可以傳入 flat 參數。如果 True，則表示返回的結果是單個值，而不是 1 元組。範例應該會使差異更清楚

>>> Entry.objects.values_list("id").order_by("id")
<QuerySet[(1,), (2,), (3,), ...]>

>>> Entry.objects.values_list("id", flat=True).order_by("id")
<QuerySet [1, 2, 3, ...]>

當有多個欄位時傳入 flat 會產生錯誤。

您可以傳入 named=True 以將結果作為 namedtuple() 取得

>>> Entry.objects.values_list("id", "headline", named=True)
<QuerySet [Row(id=1, headline='First entry'), ...]>

使用具名元組 (named tuple) 可能會讓結果更易讀，但會因為將結果轉換為具名元組而產生些微的效能損失。

如果沒有傳遞任何值給 values_list()，它將會依照模型宣告的順序回傳所有欄位。

一個常見的需求是取得特定模型實例的特定欄位值。要達成此目的，可以使用 values_list() 接著呼叫 get()。

>>> Entry.objects.values_list("headline", flat=True).get(pk=1)
'First entry'

values() 和 values_list() 都是為了特定使用情境而設計的優化：在不需建立模型實例的負擔下，取得資料的子集。當處理多對多關係和其他多值關係（例如反向外鍵的一對多關係）時，這個隱喻就會失效，因為「一列對應一個物件」的假設不成立。

例如，請注意在跨 ManyToManyField 查詢時的行為

>>> Author.objects.values_list("name", "entry__headline")
<QuerySet [('Noam Chomsky', 'Impressions of Gaza'),
 ('George Orwell', 'Why Socialists Do Not Believe in Fun'),
 ('George Orwell', 'In Defence of English Cooking'),
 ('Don Quixote', None)]>

有多個條目的作者會出現多次，而沒有任何條目的作者的條目標題則會是 None。

類似地，當查詢反向外鍵時，沒有任何作者的條目會顯示 None。

>>> Entry.objects.values_list("authors")
<QuerySet [('Noam Chomsky',), ('George Orwell',), (None,)]>

dates()¶

dates(field, kind, order='ASC')¶

回傳一個 QuerySet，它會評估為 datetime.date 物件的列表，表示 QuerySet 內容中特定類型的所有可用日期。

field 應該是您模型的 DateField 的名稱。kind 應該是 "year"、"month"、"week" 或 "day" 其中之一。結果列表中的每個 datetime.date 物件都會被「截斷」為給定的 type。

• "year" 回傳該欄位所有相異的年份值的列表。

• "month" 回傳該欄位所有相異的年/月值的列表。

• "week" 回傳該欄位所有相異的年/週值的列表。所有日期都會是星期一。

• "day" 回傳該欄位所有相異的年/月/日值的列表。

order，預設為 'ASC'，應該是 'ASC' 或 'DESC'。這指定如何排序結果。

範例

>>> Entry.objects.dates("pub_date", "year")
[datetime.date(2005, 1, 1)]
>>> Entry.objects.dates("pub_date", "month")
[datetime.date(2005, 2, 1), datetime.date(2005, 3, 1)]
>>> Entry.objects.dates("pub_date", "week")
[datetime.date(2005, 2, 14), datetime.date(2005, 3, 14)]
>>> Entry.objects.dates("pub_date", "day")
[datetime.date(2005, 2, 20), datetime.date(2005, 3, 20)]
>>> Entry.objects.dates("pub_date", "day", order="DESC")
[datetime.date(2005, 3, 20), datetime.date(2005, 2, 20)]
>>> Entry.objects.filter(headline__contains="Lennon").dates("pub_date", "day")
[datetime.date(2005, 3, 20)]

datetimes()¶

datetimes(field_name, kind, order='ASC', tzinfo=None)¶

回傳一個 QuerySet，它會評估為 datetime.datetime 物件的列表，表示 QuerySet 內容中特定類型的所有可用日期。

field_name 應該是您模型的 DateTimeField 的名稱。

kind 應該是 "year"、"month"、"week"、"day"、"hour"、"minute" 或 "second" 其中之一。結果列表中的每個 datetime.datetime 物件都會被「截斷」為給定的 type。

order，預設為 'ASC'，應該是 'ASC' 或 'DESC'。這指定如何排序結果。

tzinfo 定義在截斷之前將日期時間轉換成的時區。實際上，給定的日期時間會根據使用的時區而有不同的表示。此參數必須是 datetime.tzinfo 物件。如果它是 None，Django 會使用目前時區。當 USE_TZ 為 False 時，它沒有任何作用。

none()¶

none()¶

呼叫 none() 將會建立一個永遠不會回傳任何物件的 queryset，並且在存取結果時不會執行任何查詢。qs.none() queryset 是 EmptyQuerySet 的實例。

範例

>>> Entry.objects.none()
<QuerySet []>
>>> from django.db.models.query import EmptyQuerySet
>>> isinstance(Entry.objects.none(), EmptyQuerySet)
True

all()¶

all()¶

回傳目前 QuerySet（或 QuerySet 子類別）的副本。這在您可能想要傳入模型管理員或 QuerySet 並對結果執行進一步篩選的情況下很有用。在任一物件上呼叫 all() 之後，您肯定會有一個 QuerySet 可以使用。

當 QuerySet 被評估時，它通常會快取其結果。如果資料庫中的資料可能在 QuerySet 被評估之後發生變更，您可以藉由在先前評估過的 QuerySet 上呼叫 all() 來取得相同查詢的更新結果。

union()¶

union(*other_qs, all=False)¶

使用 SQL 的 UNION 運算子來合併兩個或多個 QuerySet 的結果。例如

>>> qs1.union(qs2, qs3)

UNION 運算子預設只會選取相異的值。若要允許重複的值，請使用 all=True 引數。

union()、intersection() 和 difference() 會回傳第一個 QuerySet 類型的模型實例，即使引數是其他模型的 QuerySet 也是如此。只要所有 QuerySet 中的 SELECT 清單相同（至少類型相同，名稱不重要，只要類型順序相同），傳遞不同的模型就可以運作。在這種情況下，您必須在套用至結果 QuerySet 的 QuerySet 方法中使用第一個 QuerySet 的欄位名稱。例如：

>>> qs1 = Author.objects.values_list("name")
>>> qs2 = Entry.objects.values_list("headline")
>>> qs1.union(qs2).order_by("name")

此外，只允許在結果 QuerySet 上使用 LIMIT、OFFSET、COUNT(*)、ORDER BY，以及指定欄位（即切片、count()、exists()、order_by() 和 values()/values_list()）。此外，資料庫對組合查詢中允許的操作有所限制。例如，大多數資料庫不允許在組合查詢中使用 LIMIT 或 OFFSET。

intersection()¶

intersection(*other_qs)¶

使用 SQL 的 INTERSECT 運算子來回傳兩個或多個 QuerySet 的共用元素。例如：

>>> qs1.intersection(qs2, qs3)

有關一些限制，請參閱 union()。

difference()¶

difference(*other_qs)¶

使用 SQL 的 EXCEPT 運算子，只保留存在於 QuerySet 中，但不存在於其他 QuerySet 中的元素。例如：

>>> qs1.difference(qs2, qs3)

有關一些限制，請參閱 union()。

select_related()¶

select_related(*fields)¶

回傳一個 QuerySet，它將「追蹤」外鍵關係，在執行查詢時選取額外的相關物件資料。這是一個效能提升器，會產生一個更複雜的查詢，但這表示後續使用外鍵關係時不需要資料庫查詢。

以下範例說明了普通查詢和 select_related() 查詢之間的差異。以下是標準查詢：

# Hits the database.
e = Entry.objects.get(id=5)

# Hits the database again to get the related Blog object.
b = e.blog

以下是 select_related 查詢：

# Hits the database.
e = Entry.objects.select_related("blog").get(id=5)

# Doesn't hit the database, because e.blog has been prepopulated
# in the previous query.
b = e.blog

您可以將 select_related() 與任何物件的查詢集一起使用：

from django.utils import timezone

# Find all the blogs with entries scheduled to be published in the future.
blogs = set()

for e in Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog"):
    # Without select_related(), this would make a database query for each
    # loop iteration in order to fetch the related blog for each entry.
    blogs.add(e.blog)

filter() 和 select_related() 鏈接的順序並不重要。這些查詢集是等效的：

Entry.objects.filter(pub_date__gt=timezone.now()).select_related("blog")
Entry.objects.select_related("blog").filter(pub_date__gt=timezone.now())

您可以按照與查詢外鍵類似的方式追蹤外鍵。如果您有以下模型：

from django.db import models


class City(models.Model):
    # ...
    pass


class Person(models.Model):
    # ...
    hometown = models.ForeignKey(
        City,
        on_delete=models.SET_NULL,
        blank=True,
        null=True,
    )


class Book(models.Model):
    # ...
    author = models.ForeignKey(Person, on_delete=models.CASCADE)

…則呼叫 Book.objects.select_related('author__hometown').get(id=4) 將快取相關的 Person *和* 相關的 City。

# Hits the database with joins to the author and hometown tables.
b = Book.objects.select_related("author__hometown").get(id=4)
p = b.author  # Doesn't hit the database.
c = p.hometown  # Doesn't hit the database.

# Without select_related()...
b = Book.objects.get(id=4)  # Hits the database.
p = b.author  # Hits the database.
c = p.hometown  # Hits the database.

您可以在傳遞給 select_related() 的欄位列表中參考任何 ForeignKey 或 OneToOneField 關係。

您也可以在傳遞給 select_related 的欄位列表中參考 OneToOneField 的反向方向 — 也就是說，您可以將 OneToOneField 回溯到定義欄位的物件。請勿指定欄位名稱，而是使用相關物件上欄位的 related_name。

在某些情況下，您可能希望呼叫 select_related() 時帶入許多相關物件，或者您不知道所有關係。在這些情況下，您可以呼叫不帶引數的 select_related()。這將追蹤它可以找到的所有非空外鍵 — 必須指定可空外鍵。在大多數情況下，不建議這樣做，因為這樣做可能會使底層查詢更複雜，並回傳比實際需要更多的資料。

如果您需要清除過去在 QuerySet 上呼叫 select_related 所加入的相關欄位清單，您可以傳遞 None 作為參數：

>>> without_relations = queryset.select_related(None)

鏈接 select_related 呼叫的方式與其他方法類似 — 也就是說，select_related('foo', 'bar') 等效於 select_related('foo').select_related('bar')。

prefetch_related()¶

prefetch_related(*lookups)¶

回傳一個 QuerySet，它將在單一批次中自動擷取每個指定查詢的相關物件。

這與 select_related 的目的相似，兩者都旨在阻止因存取相關物件而導致的資料庫查詢泛濫，但策略卻截然不同。

select_related 的運作方式是建立 SQL 聯結，並在 SELECT 陳述式中包含相關物件的欄位。因此，select_related 在同一個資料庫查詢中取得相關物件。然而，為了避免在「多對」關係上聯結會導致更大的結果集，select_related 僅限於單值關係 — 外鍵和一對一。

另一方面，prefetch_related 為每個關係執行單獨的查詢，並在 Python 中進行「聯結」。這使其能夠預取多對多、多對一和 GenericRelation 物件，而這些物件無法使用 select_related 來完成，此外還支援 select_related 所支援的外鍵和一對一關係。它還支援預取 GenericForeignKey，但是，每個 ContentType 的查詢集必須在 GenericPrefetch 的 querysets 參數中提供。

例如，假設您有以下模型：

from django.db import models


class Topping(models.Model):
    name = models.CharField(max_length=30)


class Pizza(models.Model):
    name = models.CharField(max_length=50)
    toppings = models.ManyToManyField(Topping)

    def __str__(self):
        return "%s (%s)" % (
            self.name,
            ", ".join(topping.name for topping in self.toppings.all()),
        )

並執行：

>>> Pizza.objects.all()
["Hawaiian (ham, pineapple)", "Seafood (prawns, smoked salmon)"...

這樣做的問題是，每次 Pizza.__str__() 要求 self.toppings.all() 時，它都必須查詢資料庫，因此 Pizza.objects.all() 將對 Pizza QuerySet 中的 **每個** 項目在 Toppings 資料表上執行查詢。

我們可以使用 prefetch_related 將查詢減少到只有兩個：

>>> Pizza.objects.prefetch_related("toppings")

這表示每個 Pizza 都有一個 self.toppings.all()；現在每次呼叫 self.toppings.all() 時，它都會在單一查詢中填入的預取 QuerySet 快取中找到項目，而不必去資料庫尋找項目。

也就是說，所有相關的配料都會在單次查詢中取得，並用來建立具有預先填入相關結果快取的 QuerySets；這些 QuerySets 接著會用於 self.toppings.all() 的呼叫中。

prefetch_related() 中的額外查詢會在 QuerySet 開始評估且主要查詢執行後執行。

請注意，在主要查詢執行和額外查詢之間，沒有機制可以防止另一個資料庫查詢修改項目，這可能會產生不一致的結果。例如，如果在主要查詢執行後刪除 Pizza，則其配料將不會在額外查詢中傳回，並且看起來就像披薩沒有配料一樣。

>>> Pizza.objects.prefetch_related("toppings")
#  "Hawaiian" Pizza was deleted in another shell.
<QuerySet [<Pizza: Hawaiian ()>, <Pizza: Seafood (prawns, smoked salmon)>]>

如果您有一個模型實例的可迭代物件，您可以使用 prefetch_related_objects() 函式來預先取得這些實例的相關屬性。

請注意，主要 QuerySet 和所有指定的相關物件的結果快取將會完全載入記憶體中。這會改變 QuerySets 的典型行為，它們通常會避免在需要之前將所有物件載入記憶體中，即使是在資料庫中執行查詢之後。

>>> pizzas = Pizza.objects.prefetch_related("toppings")
>>> [list(pizza.toppings.filter(spicy=True)) for pizza in pizzas]

您也可以使用一般的聯結語法來處理相關欄位的相關欄位。假設我們在上面的範例中加入一個額外的模型：

class Restaurant(models.Model):
    pizzas = models.ManyToManyField(Pizza, related_name="restaurants")
    best_pizza = models.ForeignKey(
        Pizza, related_name="championed_by", on_delete=models.CASCADE
    )

以下都是合法的：

>>> Restaurant.objects.prefetch_related("pizzas__toppings")

這將預先取得屬於餐廳的所有披薩，以及屬於這些披薩的所有配料。這將導致總共 3 個資料庫查詢 - 一個用於餐廳，一個用於披薩，一個用於配料。

>>> Restaurant.objects.prefetch_related("best_pizza__toppings")

這將擷取每間餐廳最好的披薩以及最好的披薩的所有配料。這將在 3 個資料庫查詢中完成 - 一個用於餐廳，一個用於「最好的披薩」，一個用於配料。

也可以使用 select_related 來擷取 best_pizza 關係，以將查詢計數減少到 2 個。

>>> Restaurant.objects.select_related("best_pizza").prefetch_related("best_pizza__toppings")

由於預先擷取是在主要查詢（包括 select_related 所需的聯結）之後執行，因此它可以偵測到 best_pizza 物件已擷取，並且會跳過再次擷取它們。

串連 prefetch_related 呼叫將會累加預先取得的查找。要清除任何 prefetch_related 行為，請將 None 作為參數傳遞。

>>> non_prefetched = qs.prefetch_related(None)

使用 prefetch_related 時要注意的一個差異是，查詢所建立的物件可以在與它們相關的不同物件之間共用，也就是說，單一的 Python 模型實例可以出現在傳回的物件樹狀結構中的多個點。這通常會發生在外部索引鍵關係中。通常，此行為不會有問題，實際上會節省記憶體和 CPU 時間。

雖然 prefetch_related 支援預先取得 GenericForeignKey 關係，但查詢的數量將取決於資料。由於 GenericForeignKey 可以參考多個資料表中的資料，因此需要每個參考資料表一個查詢，而不是所有項目一個查詢。如果相關的列尚未擷取，則可能會在 ContentType 資料表上進行額外查詢。

在大多數情況下，prefetch_related 將使用使用 'IN' 運算子的 SQL 查詢來實作。這表示對於大型 QuerySet，可能會產生大型 'IN' 子句，這可能會在資料庫解析或執行 SQL 查詢時產生效能問題。始終針對您的使用案例進行效能分析！

如果您使用 iterator() 來執行查詢，則只有在提供 chunk_size 的值時才會觀察到 prefetch_related() 呼叫。

您可以使用 Prefetch 物件來進一步控制預先擷取操作。

在其最簡單的形式中，Prefetch 等效於傳統的基於字串的查找。

>>> from django.db.models import Prefetch
>>> Restaurant.objects.prefetch_related(Prefetch("pizzas__toppings"))

您可以提供具有可選 queryset 引數的自訂查詢集。這可用於變更查詢集的預設排序。

>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.order_by("name"))
... )

或者在適用時呼叫 select_related() 以進一步減少查詢數量。

>>> Pizza.objects.prefetch_related(
...     Prefetch("restaurants", queryset=Restaurant.objects.select_related("best_pizza"))
... )

您也可以使用可選的 to_attr 引數將預先取得的結果指派給自訂屬性。結果將直接儲存在列表中。

這允許使用不同的 QuerySet 多次預先取得相同的關係；例如：

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", to_attr="menu"),
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
... )

使用自訂 to_attr 建立的查找仍然可以像往常一樣透過其他查找來遍歷。

>>> vegetarian_pizzas = Pizza.objects.filter(vegetarian=True)
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=vegetarian_pizzas, to_attr="vegetarian_menu"),
...     "vegetarian_menu__toppings",
... )

當過濾預先擷取的結果時，建議使用 to_attr，因為它比將過濾的結果儲存在相關管理器的快取中更不含糊。

>>> queryset = Pizza.objects.filter(vegetarian=True)
>>>
>>> # Recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset, to_attr="vegetarian_pizzas")
... )
>>> vegetarian_pizzas = restaurants[0].vegetarian_pizzas
>>>
>>> # Not recommended:
>>> restaurants = Restaurant.objects.prefetch_related(
...     Prefetch("pizzas", queryset=queryset),
... )
>>> vegetarian_pizzas = restaurants[0].pizzas.all()

自訂預先擷取也適用於單一相關關係，例如正向 ForeignKey 或 OneToOneField。通常，您會想要針對這些關係使用 select_related()，但在許多情況下，使用自訂 QuerySet 進行預先擷取會很有用。

• 您想要使用對相關模型執行進一步預先擷取的 QuerySet。

• 您只想預先取得相關物件的子集。

• 您想要使用效能最佳化技術，例如 延遲欄位。

  >>> queryset = Pizza.objects.only("name")
  >>>
  >>> restaurants = Restaurant.objects.prefetch_related(
  ...     Prefetch("best_pizza", queryset=queryset)
  ... )
  

當使用多個資料庫時，Prefetch 將會遵守您選擇的資料庫。如果內部查詢未指定資料庫，它將會使用外部查詢所選取的資料庫。以下所有內容都是有效的：

>>> # Both inner and outer queries will use the 'replica' database
>>> Restaurant.objects.prefetch_related("pizzas__toppings").using("replica")
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings"),
... ).using("replica")
>>>
>>> # Inner will use the 'replica' database; outer will use 'default' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... )
>>>
>>> # Inner will use 'replica' database; outer will use 'cold-storage' database
>>> Restaurant.objects.prefetch_related(
...     Prefetch("pizzas__toppings", queryset=Toppings.objects.using("replica")),
... ).using("cold-storage")

>>> prefetch_related("pizzas__toppings", "pizzas")

>>> prefetch_related("pizzas__toppings", Prefetch("pizzas", queryset=Pizza.objects.all()))

>>> prefetch_related("pizza_list__toppings", Prefetch("pizzas", to_attr="pizza_list"))

extra()¶

extra(select=None, where=None, params=None, tables=None, order_by=None, select_params=None)¶

有時，Django 查詢語法本身無法輕易表達複雜的 WHERE 子句。對於這些極端情況，Django 提供了 extra() QuerySet 修飾符，這是一個將特定子句注入 QuerySet 所產生 SQL 中的鉤子。

>>> qs.extra(
...     select={"val": "select col from sometable where othercol = %s"},
...     select_params=(someparam,),
... )

>>> qs.annotate(val=RawSQL("select col from sometable where othercol = %s", (someparam,)))

SELECT col FROM sometable WHERE othercol = '%s'  # unsafe!

根據定義，這些額外的查詢可能無法移植到不同的資料庫引擎（因為您正在明確編寫 SQL 程式碼）並違反了 DRY 原則，因此您應盡可能避免使用它們。

指定 params、select、where 或 tables 中的一項或多項。這些參數都不是必要的，但您至少應使用其中一個。

• select

  select 參數可讓您在 SELECT 子句中放入額外的欄位。它應該是一個字典，將屬性名稱對應到用於計算該屬性的 SQL 子句。

  範例

  Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  

  因此，每個 Entry 物件都會有一個額外的屬性 is_recent，這是一個布林值，表示項目的 pub_date 是否大於 2006 年 1 月 1 日。

  Django 會將指定的 SQL 片段直接插入 SELECT 陳述式中，因此上述範例產生的 SQL 會類似於

  SELECT blog_entry.*, (pub_date > '2006-01-01') AS is_recent
  FROM blog_entry;
  

  下一個範例更進階；它會執行子查詢，為每個產生的 Blog 物件提供一個 entry_count 屬性，這是一個相關 Entry 物件的整數計數

  Blog.objects.extra(
      select={
          "entry_count": "SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id"
      },
  )
  

  在這個特定案例中，我們利用了查詢的 FROM 子句中已經包含 blog_blog 表格這一事實。

  上述範例產生的 SQL 會是

  SELECT blog_blog.*, (SELECT COUNT(*) FROM blog_entry WHERE blog_entry.blog_id = blog_blog.id) AS entry_count
  FROM blog_blog;
  

  請注意，大多數資料庫引擎在子查詢周圍所需的括號在 Django 的 select 子句中不是必要的。

  在某些罕見情況下，您可能希望將參數傳遞到 extra(select=...) 中的 SQL 片段。為此，請使用 select_params 參數。

  例如，這會起作用

  Blog.objects.extra(
      select={"a": "%s", "b": "%s"},
      select_params=("one", "two"),
  )
  

  如果您需要在選取字串中使用文字 %s，請使用序列 %%s。

• where / tables

  您可以使用 where 定義明確的 SQL WHERE 子句（可能是為了執行非明確的聯結）。您可以使用 tables 手動將表格新增至 SQL FROM 子句。

  where 和 tables 都採用字串列表。所有 where 參數都會與任何其他搜尋條件「AND」在一起。

  範例

  Entry.objects.extra(where=["foo='a' OR bar = 'a'", "baz = 'a'"])
  

  ...大致轉換為以下 SQL

  SELECT * FROM blog_entry WHERE (foo='a' OR bar='a') AND (baz='a')
  

  如果您指定查詢中已經使用的表格，請小心使用 tables 參數。當您透過 tables 參數新增額外表格時，Django 會假設您想要額外包含該表格一次（如果它已經被包含）。這會產生問題，因為表格名稱會被賦予別名。如果一個表格在 SQL 陳述式中出現多次，則第二次和後續出現的表格必須使用別名，以便資料庫可以區分它們。如果您在額外的 where 參數中引用您新增的額外表格，這將導致錯誤。

  通常，您只會新增查詢中尚未出現的額外表格。但是，如果發生上述情況，則有幾種解決方案。首先，看看是否可以在不包含額外表格的情況下進行，並使用查詢中已有的表格。如果無法做到這一點，請將您的 extra() 呼叫放在 queryset 建構的最前面，以便您的表格是第一個使用的表格。最後，如果所有方法都失敗了，請查看產生的查詢，並重寫您的 where 新增內容，以使用賦予您額外表格的別名。每次您以相同方式建構 queryset 時，別名都會相同，因此您可以依賴別名名稱而不變更。

• order_by

  如果您需要使用您透過 extra() 包含的一些新欄位或表格來排序產生的 queryset，請使用 extra() 的 order_by 參數，並傳入字串序列。這些字串應該是模型欄位（如 queryset 上正常的 order_by() 方法），格式為 table_name.column_name，或您在 extra() 的 select 參數中指定的欄位別名。

  例如

  q = Entry.objects.extra(select={"is_recent": "pub_date > '2006-01-01'"})
  q = q.extra(order_by=["-is_recent"])
  

  這會將 is_recent 為 true 的所有項目排序到結果集的前面（在降序排序中，True 會排在 False 之前）。

  順帶一提，這表示您可以多次呼叫 extra()，並且它的行為會如您預期（每次都新增新的限制）。

• params

  上述描述的 where 參數可能會使用標準 Python 資料庫字串預留位置 — '%s' 表示資料庫引擎應自動加上引號的參數。params 參數是要替換的任何額外參數的列表。

  範例

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

  請始終使用 params 而不是將值直接嵌入 where 中，因為 params 會確保值根據您的特定後端正確加上引號。例如，引號會被正確地跳脫。

  不良範例

  Entry.objects.extra(where=["headline='Lennon'"])
  

  良好範例

  Entry.objects.extra(where=["headline=%s"], params=["Lennon"])
  

defer()¶

defer(*fields)¶

在某些複雜的資料模型情境中，您的模型可能包含許多欄位，其中一些欄位可能包含大量資料（例如，文字欄位），或需要大量的處理才能將其轉換為 Python 物件。如果您在某些情況下使用 queryset 的結果，而您不確定在最初獲取資料時是否需要這些特定欄位，您可以告知 Django 不要從資料庫中檢索它們。

這是透過將要延遲載入的欄位名稱傳遞給 defer() 來完成的。

Entry.objects.defer("headline", "body")

具有延遲載入欄位的 queryset 仍將回傳模型實例。如果您存取該欄位（一次一個，而不是一次全部延遲載入的欄位），則每個延遲載入的欄位都會從資料庫中檢索。

您可以多次呼叫 defer()。每次呼叫都會將新欄位添加到延遲載入的集合中。

# Defers both the body and headline fields.
Entry.objects.defer("body").filter(rating=5).defer("headline")

將欄位添加到延遲載入集合的順序並不重要。使用已延遲載入的欄位名稱呼叫 defer() 是無害的（該欄位仍將被延遲載入）。

您可以使用標準的雙底線表示法來分隔相關欄位，以延遲載入相關模型中的欄位（如果相關模型是透過 select_related() 載入）。

Blog.objects.select_related().defer("entry__headline", "entry__body")

如果您想清除延遲載入的欄位集合，請將 None 作為參數傳遞給 defer()。

# Load all fields immediately.
my_queryset.defer(None)

即使您要求延遲載入，模型中的某些欄位也不會被延遲載入。您永遠無法延遲載入主鍵。如果您正在使用 select_related() 來檢索相關模型，則不應延遲載入從主模型連線到相關模型的欄位，否則會導致錯誤。

同樣地，呼叫 defer() （或其對應的 only()）包含聚合中的引數（例如，使用 annotate() 的結果）是沒有意義的：這樣做會引發例外。聚合的值將始終被提取到結果的 queryset 中。

class CommonlyUsedModel(models.Model):
    f1 = models.CharField(max_length=10)

    class Meta:
        managed = False
        db_table = "app_largetable"


class ManagedModel(models.Model):
    f1 = models.CharField(max_length=10)
    f2 = models.CharField(max_length=10)

    class Meta:
        db_table = "app_largetable"


# Two equivalent QuerySets:
CommonlyUsedModel.objects.all()
ManagedModel.objects.defer("f2")

only()¶

only(*fields)¶

only() 方法本質上與 defer() 相反。只有傳遞到此方法且未指定為延遲載入的欄位，會在評估 queryset 時立即載入。

如果您有一個模型，其中幾乎所有欄位都需要延遲載入，則使用 only() 指定補充的欄位集合可以使程式碼更簡單。

假設您有一個模型，其中包含欄位 name、age 和 biography。以下兩個 queryset 在延遲載入的欄位方面是相同的。

Person.objects.defer("age", "biography")
Person.objects.only("name")

當您呼叫 only() 時，它會取代要立即載入的欄位集合。此方法的名稱是助記符：只有這些欄位會立即載入；其餘的則會延遲載入。因此，連續呼叫 only() 只會考慮最後的欄位。

# This will defer all fields except the headline.
Entry.objects.only("body", "rating").only("headline")

由於 defer() 的作用是累加的（將欄位新增到延遲載入清單），因此您可以結合呼叫 only() 和 defer()，而事情將會按照邏輯運作。

# Final result is that everything except "headline" is deferred.
Entry.objects.only("headline", "body").defer("body")

# Final result loads headline immediately.
Entry.objects.defer("body").only("headline", "body")

在 defer() 文件中注意事項中的所有警告也適用於 only()。請謹慎使用它，並僅在用盡其他選項後才使用。

使用 only() 並省略使用 select_related() 請求的欄位也是錯誤的。另一方面，呼叫不帶任何引數的 only() 將會回傳 queryset 提取的每個欄位（包括註釋）。

與 defer() 一樣，您無法從非同步程式碼存取未載入的欄位並期望它們載入。相反地，您會收到一個 SynchronousOnlyOperation 例外。請確保您可能存取的所有欄位都在您的 only() 呼叫中。

using()¶

using(alias)¶

如果您使用多個資料庫，此方法用於控制 QuerySet 將針對哪個資料庫進行評估。此方法唯一接受的引數是資料庫的別名，如 DATABASES 中所定義。

例如

# queries the database with the 'default' alias.
>>> Entry.objects.all()

# queries the database with the 'backup' alias
>>> Entry.objects.using("backup")

select_for_update()¶

select_for_update(nowait=False, skip_locked=False, of=(), no_key=False)¶

返回一個查詢集（queryset），它會在事務結束前鎖定資料列，並在支援的資料庫上產生一個 SELECT ... FOR UPDATE SQL 語句。

例如

from django.db import transaction

entries = Entry.objects.select_for_update().filter(author=request.user)
with transaction.atomic():
    for entry in entries:
        ...

當查詢集被評估時（在此例中為 for entry in entries），所有匹配的條目將被鎖定直到事務區塊結束，這表示其他事務將無法變更或取得它們的鎖。

通常，如果另一個事務已經取得其中一個選定資料列的鎖，則查詢將會被阻塞，直到鎖被釋放。如果這不是您想要的行為，請呼叫 select_for_update(nowait=True)。這會使呼叫變成非阻塞。如果衝突的鎖已被另一個事務取得，則在評估查詢集時會引發 DatabaseError。您也可以使用 select_for_update(skip_locked=True) 來忽略被鎖定的資料列。nowait 和 skip_locked 是互斥的，嘗試同時啟用這兩個選項來呼叫 select_for_update() 將會導致 ValueError。

預設情況下，select_for_update() 會鎖定查詢所選取的所有資料列。例如，除了查詢集模型的資料列之外，在 select_related() 中指定的相關物件的資料列也會被鎖定。如果不希望這樣，請使用與 select_related() 相同的欄位語法，在 select_for_update(of=(...)) 中指定您想要鎖定的相關物件。使用值 'self' 來參照查詢集的模型。

Restaurant.objects.select_for_update(of=("self", "place_ptr"))

僅在 PostgreSQL 上，您可以傳遞 no_key=True 以取得較弱的鎖定，這仍然允許在鎖定生效時建立僅參考鎖定資料列的資料列（例如，透過外鍵）。PostgreSQL 文件中有更多關於資料列層級鎖定模式的詳細資訊。

您無法在可為空的關係上使用 select_for_update()

>>> Person.objects.select_related("hometown").select_for_update()
Traceback (most recent call last):
...
django.db.utils.NotSupportedError: FOR UPDATE cannot be applied to the nullable side of an outer join

為了避免此限制，如果您不在意空物件，您可以排除它們

>>> Person.objects.select_related("hometown").select_for_update().exclude(hometown=None)
<QuerySet [<Person: ...)>, ...]>

postgresql、oracle 和 mysql 資料庫後端支援 select_for_update()。但是，MariaDB 僅支援 nowait 引數，MariaDB 10.6+ 也支援 skip_locked 引數，而 MySQL 支援 nowait、skip_locked 和 of 引數。no_key 引數僅在 PostgreSQL 上支援。

將 nowait=True、skip_locked=True、no_key=True 或 of 傳遞給 select_for_update()，使用不支援這些選項的資料庫後端（例如 MySQL）會引發 NotSupportedError。這可防止程式碼意外地被阻塞。

在支援 SELECT ... FOR UPDATE 的後端上，在自動提交模式下評估具有 select_for_update() 的查詢集會發生 TransactionManagementError 錯誤，因為在這種情況下資料列不會被鎖定。如果允許，這將導致資料損毀，並且很容易因呼叫預期在事務之外運行的程式碼而導致。

在不支援 SELECT ... FOR UPDATE 的後端（例如 SQLite）上使用 select_for_update() 將不會有任何作用。SELECT ... FOR UPDATE 不會被新增到查詢中，並且如果在自動提交模式下使用 select_for_update() 也不會引發錯誤。

raw()¶

raw(raw_query, params=(), translations=None, using=None)¶

採用原始 SQL 查詢，執行它並返回一個 django.db.models.query.RawQuerySet 實例。這個 RawQuerySet 實例可以像普通的 QuerySet 一樣被迭代以提供物件實例。

有關更多資訊，請參閱執行原始 SQL 查詢。

AND (&)¶

結合兩個 QuerySet，使用 SQL 的 AND 運算子，其方式類似於串聯篩選器。

以下是等效的

Model.objects.filter(x=1) & Model.objects.filter(y=2)
Model.objects.filter(x=1).filter(y=2)

SQL 等效語法

SELECT ... WHERE x=1 AND y=2

OR (|)¶

結合兩個 QuerySet，使用 SQL 的 OR 運算子。

以下是等效的

Model.objects.filter(x=1) | Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) | Q(y=2))

SQL 等效語法

SELECT ... WHERE x=1 OR y=2

| 不是可交換的運算，因為可能會產生不同（但等效）的查詢。

XOR (^)¶

結合兩個 QuerySet，使用 SQL 的 XOR 運算子。XOR 表達式匹配由奇數個運算元匹配的行。

以下是等效的

Model.objects.filter(x=1) ^ Model.objects.filter(y=2)
from django.db.models import Q

Model.objects.filter(Q(x=1) ^ Q(y=2))

SQL 等效語法

SELECT ... WHERE x=1 XOR y=2

(x OR y OR ... OR z) AND
1=MOD(
    (CASE WHEN x THEN 1 ELSE 0 END) +
    (CASE WHEN y THEN 1 ELSE 0 END) +
    ...
    (CASE WHEN z THEN 1 ELSE 0 END),
    2
)

get()¶

get(*args, **kwargs)¶

aget(*args, **kwargs)¶

異步版本： aget()

返回符合給定查找參數的物件，其格式應如欄位查找中所述。您應該使用保證唯一的查找，例如主鍵或唯一約束中的欄位。例如

Entry.objects.get(id=1)
Entry.objects.get(Q(blog=blog) & Q(entry_number=1))

如果您預期查詢集已經返回一行，您可以使用不帶任何參數的 get() 來返回該行的物件

Entry.objects.filter(pk=1).get()

如果 get() 沒有找到任何物件，它會引發 Model.DoesNotExist 例外

Entry.objects.get(id=-999)  # raises Entry.DoesNotExist

如果 get() 找到多個物件，它會引發 Model.MultipleObjectsReturned 例外

Entry.objects.get(name="A Duplicated Name")  # raises Entry.MultipleObjectsReturned

這兩個例外類別都是模型類別的屬性，並且特定於該模型。如果您想處理來自不同模型的多次 get() 調用的此類例外，可以使用它們的通用基底類別。例如，您可以使用 django.core.exceptions.ObjectDoesNotExist 來處理來自多個模型的 DoesNotExist 例外

from django.core.exceptions import ObjectDoesNotExist

try:
    blog = Blog.objects.get(id=1)
    entry = Entry.objects.get(blog=blog, entry_number=1)
except ObjectDoesNotExist:
    print("Either the blog or entry doesn't exist.")

create()¶

create(**kwargs)¶

acreate(**kwargs)¶

異步版本： acreate()

一種方便的方法，可以一步完成物件的建立和儲存。因此

p = Person.objects.create(first_name="Bruce", last_name="Springsteen")

和

p = Person(first_name="Bruce", last_name="Springsteen")
p.save(force_insert=True)

是等效的。

force_insert 參數在其他地方有記載，但它所表示的只是始終會建立新物件。通常您無需擔心這一點。但是，如果您的模型包含您設定的手動主鍵值，並且該值已存在於資料庫中，則呼叫 create() 將會失敗並出現 IntegrityError，因為主鍵必須是唯一的。如果您使用的是手動主鍵，請準備好處理例外。

get_or_create()¶

get_or_create(defaults=None, **kwargs)¶

aget_or_create(defaults=None, **kwargs)¶

異步版本： aget_or_create()

一種方便的方法，用於查找具有給定 kwargs 的物件（如果您的模型對所有欄位都有預設值，則可能為空），並在必要時建立一個。

返回一個 (object, created) 的元組，其中 object 是檢索或建立的物件，而 created 是一個布林值，用於指定是否建立了新物件。

這旨在防止在並行發出請求時建立重複的物件，並且作為樣板程式碼的捷徑。例如

try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
except Person.DoesNotExist:
    obj = Person(first_name="John", last_name="Lennon", birthday=date(1940, 10, 9))
    obj.save()

在這裡，對於併發請求，可能會多次嘗試使用相同的參數儲存 Person。為了避免這種競爭條件，可以使用 get_or_create() 重寫上面的範例，如下所示

obj, created = Person.objects.get_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"birthday": date(1940, 10, 9)},
)

傳遞給 get_or_create() 的任何關鍵字引數 — 除了一個名為 defaults 的可選引數 — 將在 get() 呼叫中使用。如果找到物件，get_or_create() 會返回該物件和 False 的元組。

您可以透過鏈式使用 filter() 和使用 Q 物件，為檢索的物件指定更複雜的條件。例如，要檢索 Robert 或 Bob Marley（如果存在），否則建立後者

from django.db.models import Q

obj, created = Person.objects.filter(
    Q(first_name="Bob") | Q(first_name="Robert"),
).get_or_create(last_name="Marley", defaults={"first_name": "Bob"})

如果找到多個物件，get_or_create() 會引發 MultipleObjectsReturned。如果未找到物件，get_or_create() 會實例化並儲存一個新物件，返回新物件和 True 的元組。將根據以下演算法大致建立新物件

params = {k: v for k, v in kwargs.items() if "__" not in k}
params.update({k: v() if callable(v) else v for k, v in defaults.items()})
obj = self.model(**params)
obj.save()

換句話說，這表示從任何不包含雙底線（表示非精確查找）的非 'defaults' 關鍵字引數開始。然後加入 defaults 的內容，在必要時覆蓋任何索引鍵，並將結果用作模型類別的關鍵字引數。如果 defaults 中有任何可調用物件，則評估它們。如上所述，這是一個簡化的演算法，其中包含了所有相關詳細資訊。內部實作比這有更多的錯誤檢查，並處理一些額外的邊緣條件；如果您有興趣，請閱讀程式碼。

如果您有名為 defaults 的欄位，並且想要在 get_or_create() 中將其用作精確查找，請使用 'defaults__exact'，如下所示

Foo.objects.get_or_create(defaults__exact="bar", defaults={"defaults": "baz"})

當您使用手動指定的 Primary Key 時，get_or_create() 方法的錯誤行為與 create() 類似。如果需要建立物件，而該鍵已存在於資料庫中，則會引發 IntegrityError。

最後，關於在 Django 視圖中使用 get_or_create() 的一點說明。請務必僅在 POST 請求中使用它，除非您有充分的理由不這樣做。GET 請求不應對資料產生任何影響。相反地，當頁面的請求對您的資料產生副作用時，請使用 POST。如需更多資訊，請參閱 HTTP 規範中的 安全方法。

class Chapter(models.Model):
    title = models.CharField(max_length=255, unique=True)


class Book(models.Model):
    title = models.CharField(max_length=256)
    chapters = models.ManyToManyField(Chapter)

>>> book = Book.objects.create(title="Ulysses")
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, True)
>>> book.chapters.get_or_create(title="Telemachus")
(<Chapter: Telemachus>, False)
>>> Chapter.objects.create(title="Chapter 1")
<Chapter: Chapter 1>
>>> book.chapters.get_or_create(title="Chapter 1")
# Raises IntegrityError

update_or_create()¶

update_or_create(defaults=None, create_defaults=None, **kwargs)¶

aupdate_or_create(defaults=None, create_defaults=None, **kwargs)¶

非同步版本: aupdate_or_create()

這是一個方便的方法，可以使用給定的 kwargs 更新物件，必要時建立一個新物件。create_defaults 和 defaults 都是 (欄位, 值) 配對的字典。 create_defaults 和 defaults 中的值都可以是可呼叫的物件。defaults 用於更新物件，而 create_defaults 用於建立操作。如果沒有提供 create_defaults，則會將 defaults 用於建立操作。

傳回一個 (object, created) 元組，其中 object 是已建立或更新的物件，而 created 是一個布林值，指定是否建立了新的物件。

update_or_create 方法會嘗試根據給定的 kwargs 從資料庫中提取物件。如果找到匹配項，它會更新 defaults 字典中傳入的欄位。

這是一個程式碼樣板的快捷方式。例如：

defaults = {"first_name": "Bob"}
create_defaults = {"first_name": "Bob", "birthday": date(1940, 10, 9)}
try:
    obj = Person.objects.get(first_name="John", last_name="Lennon")
    for key, value in defaults.items():
        setattr(obj, key, value)
    obj.save()
except Person.DoesNotExist:
    new_values = {"first_name": "John", "last_name": "Lennon"}
    new_values.update(create_defaults)
    obj = Person(**new_values)
    obj.save()

當模型中的欄位數量增加時，這種模式會變得相當笨拙。上面的範例可以使用 update_or_create() 像這樣重寫：

obj, created = Person.objects.update_or_create(
    first_name="John",
    last_name="Lennon",
    defaults={"first_name": "Bob"},
    create_defaults={"first_name": "Bob", "birthday": date(1940, 10, 9)},
)

有關 kwargs 中傳遞的名稱如何解析的詳細說明，請參閱 get_or_create()。

如上文在 get_or_create() 中所述，此方法容易發生競爭條件，如果未在資料庫層級強制執行唯一性，可能會導致同時插入多個列。

與 get_or_create() 和 create() 一樣，如果您使用的是手動指定的 Primary Key，且需要建立物件，但該鍵已存在於資料庫中，則會引發 IntegrityError。

bulk_create()¶

bulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)¶

abulk_create(objs, batch_size=None, ignore_conflicts=False, update_conflicts=False, update_fields=None, unique_fields=None)¶

非同步版本: abulk_create()

此方法以有效的方式將提供的物件清單插入到資料庫中（通常只有 1 個查詢，無論有多少個物件），並將建立的物件以清單形式傳回，順序與提供的順序相同。

>>> objs = Entry.objects.bulk_create(
...     [
...         Entry(headline="This is a test"),
...         Entry(headline="This is only a test"),
...     ]
... )

不過，這有一些注意事項：

• 不會呼叫模型的 save() 方法，也不會傳送 pre_save 和 post_save 訊號。

• 它不適用於多表格繼承情境中的子模型。

• 如果模型的主要鍵是 AutoField 且 ignore_conflicts 為 False，則只能在某些資料庫（目前為 PostgreSQL、MariaDB 和 SQLite 3.35+）上檢索主要鍵屬性。在其他資料庫上，則不會設定。

• 它不適用於多對多關係。

• 它會將 objs 轉換為清單，如果 objs 是生成器，則會完全評估 objs。轉換允許檢查所有物件，以便可以先插入任何具有手動設定主要鍵的物件。如果您想分批插入物件而不一次評估整個生成器，則只要物件沒有任何手動設定的主要鍵，就可以使用此技術。

  from itertools import islice
  
  batch_size = 100
  objs = (Entry(headline="Test %s" % i) for i in range(1000))
  while True:
      batch = list(islice(objs, batch_size))
      if not batch:
          break
      Entry.objects.bulk_create(batch, batch_size)
  

batch_size 參數控制在單一查詢中建立多少個物件。預設是在一個批次中建立所有物件，除了 SQLite，其預設值是每個查詢最多使用 999 個變數。

在支援它的資料庫（除了 Oracle 之外的所有資料庫）上，將 ignore_conflicts 參數設定為 True 會告知資料庫忽略插入任何違反約束（例如重複的唯一值）的列時發生的失敗。

在支援它的資料庫（除了 Oracle 之外的所有資料庫）上，將 update_conflicts 參數設定為 True，會告知資料庫在列插入因衝突而失敗時更新 update_fields。在 PostgreSQL 和 SQLite 上，除了 update_fields 之外，還必須提供可能發生衝突的 unique_fields 清單。

啟用 ignore_conflicts 參數會停用在每個模型實例上設定主要鍵（如果資料庫通常支援）。

bulk_update()¶

bulk_update(objs, fields, batch_size=None)¶

abulk_update(objs, fields, batch_size=None)¶

非同步版本：abulk_update()

此方法有效率地更新提供的模型實例上指定的欄位，通常使用一個查詢，並回傳更新的物件數量。

>>> objs = [
...     Entry.objects.create(headline="Entry 1"),
...     Entry.objects.create(headline="Entry 2"),
... ]
>>> objs[0].headline = "This is entry 1"
>>> objs[1].headline = "This is entry 2"
>>> Entry.objects.bulk_update(objs, ["headline"])
2

QuerySet.update() 用於儲存變更，因此這比迭代模型列表並對每個模型呼叫 save() 更有效率，但有一些注意事項：

• 您無法更新模型的主鍵。

• 不會呼叫每個模型的 save() 方法，且不會發送 pre_save 和 post_save 訊號。

• 如果更新大量行中的大量欄位，產生的 SQL 可能會非常龐大。透過指定合適的 batch_size 來避免這種情況。

• 更新在多表格繼承祖先上定義的欄位將為每個祖先產生額外的查詢。

• 當個別批次包含重複項時，只有該批次中的第一個實例會導致更新。

• 函數回傳的更新物件數量可能少於傳入的物件數量。這可能是因為傳入的重複物件在同一個批次中更新，或是競爭條件導致物件不再存在於資料庫中。

batch_size 參數控制在單一查詢中儲存多少物件。預設值是一次更新所有物件，但 SQLite 和 Oracle 對查詢中使用的變數數量有限制。

count()¶

count()¶

acount()¶

非同步版本：acount()

回傳一個整數，表示資料庫中符合 QuerySet 的物件數量。

範例

# Returns the total number of entries in the database.
Entry.objects.count()

# Returns the number of entries whose headline contains 'Lennon'
Entry.objects.filter(headline__contains="Lennon").count()

count() 呼叫會在幕後執行 SELECT COUNT(*)，因此您應該始終使用 count()，而不是將所有記錄載入到 Python 物件中並在結果上呼叫 len() (除非您無論如何都需要將物件載入到記憶體中，在這種情況下，len() 會更快)。

請注意，如果您想要取得 QuerySet 中的項目數量，並且也從中檢索模型實例 (例如，透過迭代它)，使用 len(queryset) 可能會更有效率，它不會像 count() 一樣導致額外的資料庫查詢。

如果 queryset 已完全檢索，count() 將使用該長度，而不是執行額外的資料庫查詢。

in_bulk()¶

in_bulk(id_list=None, *, field_name='pk')¶

ain_bulk(id_list=None, *, field_name='pk')¶

非同步版本：ain_bulk()

接受欄位值列表 (id_list) 和這些值的 field_name，並回傳一個字典，將每個值對應到具有指定欄位值的物件實例。 in_bulk 永遠不會引發 django.core.exceptions.ObjectDoesNotExist 例外；也就是說，任何不符合任何實例的 id_list 值都會被簡單地忽略。如果未提供 id_list，則會回傳 queryset 中的所有物件。field_name 必須是唯一欄位或不同欄位 (如果 distinct() 中只指定一個欄位)。field_name 預設為主鍵。

範例

>>> Blog.objects.in_bulk([1])
{1: <Blog: Beatles Blog>}
>>> Blog.objects.in_bulk([1, 2])
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>}
>>> Blog.objects.in_bulk([])
{}
>>> Blog.objects.in_bulk()
{1: <Blog: Beatles Blog>, 2: <Blog: Cheddar Talk>, 3: <Blog: Django Weblog>}
>>> Blog.objects.in_bulk(["beatles_blog"], field_name="slug")
{'beatles_blog': <Blog: Beatles Blog>}
>>> Blog.objects.distinct("name").in_bulk(field_name="name")
{'Beatles Blog': <Blog: Beatles Blog>, 'Cheddar Talk': <Blog: Cheddar Talk>, 'Django Weblog': <Blog: Django Weblog>}

如果您傳遞一個空列表給 in_bulk()，您將得到一個空字典。

iterator()¶

iterator(chunk_size=None)¶

aiterator(chunk_size=None)¶

非同步版本：aiterator()

評估 QuerySet (透過執行查詢) 並回傳結果上的迭代器 (請參閱 PEP 234)，如果您呼叫其非同步版本 aiterator，則回傳非同步迭代器 (請參閱 PEP 492)。

QuerySet 通常會在內部快取其結果，以便重複評估不會導致額外的查詢。 相反地，iterator() 將直接讀取結果，而不在 QuerySet 層級進行任何快取 (在內部，預設迭代器呼叫 iterator() 並快取回傳值)。 對於只須存取一次的大量物件的 QuerySet 而言，這可以帶來更好的效能和顯著的記憶體減少。

請注意，在已評估的 QuerySet 上使用 iterator() 將強制它再次評估，重複查詢。

只要指定 chunk_size，iterator() 就與之前呼叫的 prefetch_related() 相容。較大的值將需要較少的查詢來完成預取，但會犧牲較多的記憶體使用量。

在某些資料庫 (例如 Oracle、SQLite) 中，SQL IN 子句中的最大項數可能有限制。 因此，應使用低於此限制的值。(特別是，當跨兩個或多個關聯進行預取時，chunk_size 應該足夠小，以便每個預取關聯的預期結果數量仍然低於限制。)

只要 QuerySet 不預取任何相關物件，不為 chunk_size 提供值將導致 Django 使用 2000 的隱式預設值。

根據資料庫後端，查詢結果將會一次全部載入，或是使用伺服器端游標從資料庫串流。

latest()¶

latest(*fields)¶

alatest(*fields)¶

非同步版本： alatest()

根據給定的欄位，傳回資料表中最新的物件。

此範例根據 pub_date 欄位傳回資料表中最新的 Entry

Entry.objects.latest("pub_date")

您也可以根據多個欄位選擇最新物件。 例如，若要選取當兩個條目具有相同的 pub_date 時，expire_date 最早的 Entry

Entry.objects.latest("pub_date", "-expire_date")

'-expire_date' 中的負號表示以遞減順序排序 expire_date。由於 latest() 取得最後一個結果，因此會選取 expire_date 最早的 Entry。

如果您的模型的 Meta 指定了 get_latest_by，您可以省略 earliest() 或 latest() 的任何引數。預設會使用 get_latest_by 中指定的欄位。

與 get() 一樣，如果沒有具有給定參數的物件，earliest() 和 latest() 會引發 DoesNotExist。

請注意，earliest() 和 latest() 的存在純粹是為了方便和可讀性。

Entry.objects.filter(pub_date__isnull=False).latest("pub_date")

earliest()¶

earliest(*fields)¶

aearliest(*fields)¶

非同步版本： aearliest()

其他方面與 latest() 類似，只是方向改變。

first()¶

first()¶

afirst()¶

非同步版本： afirst()

傳回 Queryset 比對的第一個物件，如果沒有符合的物件，則傳回 None。如果 QuerySet 沒有定義排序，則會依主鍵自動排序 queryset。這可能會影響彙總結果，如與 order_by() 的互動中所述。

範例

p = Article.objects.order_by("title", "pub_date").first()

請注意，first() 是一個方便的方法，以下程式碼範例與上述範例等效

try:
    p = Article.objects.order_by("title", "pub_date")[0]
except IndexError:
    p = None

last()¶

last()¶

alast()¶

非同步版本： alast()

與 first() 的工作方式類似，但會傳回 queryset 中的最後一個物件。