---
title: "クエリを作成する"
version: 4.0
locale: ja
source: https://docs.djangoproject.com/ja/4.0/topics/db/queries/
canonical: https://djangodocs.dev/ja/4.0/topics/db/queries/
---
# クエリを作成する

一度 [データモデル](/ja/4.0/topics/db/models/) を作成すれば、Django はデータオブジェクトの作成、取得、更新および削除を行えるようにデータベースを抽象化した API を自動的に提供します。本ドキュメントではこの API をどのように用いるかを説明します。多様なモデル探索オプション全てに関する詳細については [データモデルの項目](/ja/4.0/ref/models/) を参照ください。

Throughout this guide (and in the reference), we'll refer to the following
models, which comprise a blog application:

```python
from datetime import date

from django.db import models

class Blog(models.Model):
    name = models.CharField(max_length=100)
    tagline = models.TextField()

    def __str__(self):
        return self.name

class Author(models.Model):
    name = models.CharField(max_length=200)
    email = models.EmailField()

    def __str__(self):
        return self.name

class Entry(models.Model):
    blog = models.ForeignKey(Blog, on_delete=models.CASCADE)
    headline = models.CharField(max_length=255)
    body_text = models.TextField()
    pub_date = models.DateField()
    mod_date = models.DateField(default=date.today)
    authors = models.ManyToManyField(Author)
    number_of_comments = models.IntegerField(default=0)
    number_of_pingbacks = models.IntegerField(default=0)
    rating = models.IntegerField(default=5)

    def __str__(self):
        return self.headline
```

## オブジェクトを作成する

データベースのテーブル上のデータを Python オブジェクトに対応付けるため、 Django は直観的なシステムを利用しています: 1 つのモデルクラスが 1 つのデータベーステーブルに対応し、そのモデルクラスの 1 インスタンスが対応するデータベーステーブルの特定のレコードに対応します。

オブジェクトを生成するためには、作成するモデルのクラスにキーワード引数を渡してインスタンス化し、そのデータをデータベースに保存するために [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) を呼び出します。

モデル定義が `mysite/blog/models.py` というファイル内に存在すると仮定すると、利用例は以下のようになります:

```
>>> from blog.models import Blog
>>> b = Blog(name='Beatles Blog', tagline='All the latest Beatles news.')
>>> b.save()
```

この例では内部で `INSERT` SQL 文が処理されます。明示的に [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) を呼ぶまで Django はデータベースを操作しません。

[`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) メソッドは値を返しません。

> **See also**
>
> [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) はここには記述されていない多数の高度なオプションを持ちます。詳細については [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) の項目を参照してください。
>
> オブジェクトの作成と保存を一つの処理で行うには、 [`create()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.create) メソッドを利用してください。

## オブジェクトに対する変更を保存する

既にデータベース上に存在する 1 つのオブジェクトに対する変更を保存するには、 [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) を利用します。

既にデータベースに保存されている `Blog` のインスタンスとして `b5` が与えられたとして、次の例ではその name を変更してデータベースのレコードを更新します:

```
>>> b5.name = 'New name'
>>> b5.save()
```

この例では内部で `UPDATE` SQL 文が処理されます。明示的に [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) が呼ばれるまで Django はデータベースを操作しません。

### `ForeignKey` と `ManyToManyField` フィールドを扱う

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

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

[`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) に対する更新は通常のフィールド更新とは少々異なっています -- リレーションのためレコードを追加するには [`add()`](/ja/4.0/ref/models/relations/#django.db.models.fields.related.RelatedManager.add) メソッドを対象となるフィールドに対して用います。以下の例では entry オブジェクトに Author のインスタンス joe を追加します。

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

[`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) に対して複数のレコードを一度に追加するには、[`add()`](/ja/4.0/ref/models/relations/#django.db.models.fields.related.RelatedManager.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`](/ja/4.0/topics/db/managers/#django.db.models.Manager) から [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を作ります。

[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) はデータベース上のオブジェクトの集合を表しています。多数の *フィルター* を持つことができます。フィルターは与えられたパラメータに基づいてクエリの検索結果を絞り込みます。SQL 文においては、 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) は `SELECT` 句、フィルターは `WHERE` や `LIMIT` のような絞り込みに用いる句に対応しています。

モデルの [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) を用いることで [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を取得します。各モデルは少なくとも一つの [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) を持ち、デフォルトでは [`objects`](/ja/4.0/ref/models/class/#django.db.models.Model.objects) という名前を持ちます。以下のようにモデルクラスから直接アクセスしてください。

```
>>> Blog.objects
<django.db.models.manager.Manager object at ...>
>>> b = Blog(name='Foo', tagline='Bar')
>>> b.objects
Traceback:
    ...
AttributeError: "Manager isn't accessible via Blog instances."
```

> **Note**
>
> `Manager` はモデルのインスタンスでなく、モデルのクラスを経由してのみアクセスでき、それは "テーブル水準" の処理と "レコード水準" の処理とで責任を明確に分離するためです。

[`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) はモデルの `QuerySet` の主な取得元になります。たとえば、 `Blog.objects.all()` はデータベース内の `Blog` オブジェクト全てを含んだ [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を返します。

### すべてのオブジェクトを取得する

テーブルからオブジェクトを取得する方法で最も簡単なのは、すべてのオブジェクトを取得することです。それには [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) に対して [`all()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.all) メソッドを呼びます。

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

[`all()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.all) メソッドは、データベース内のすべてのオブジェクトを含んだ [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を返します。

### フィルタを用いて特定のオブジェクトを取得する

[`all()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.all) が返す [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) には、データベーステーブルのすべてのオブジェクトが含まれています。しかし、ふつう必要になるのはオブジェクト全体の集合ではなく、その部分集合でしょう。

そのような部分集合を作るには、条件フィルタを追加して最初の [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を絞り込みます。 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を絞り込む代表的な方法として次の2つのものがあります。

**`filter(**kwargs)`**

  与えられた検索パラメータにマッチする新しい [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を返します。

**`exclude(**kwargs)`**

  与えられた検索パラメータにマッチ *しない* 新しい [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を返します。

検索パラメータ (上の関数定義における `**kwargs` ) は、以下の [Field lookups](#field-lookups) で説明するフォーマットに従わなければなりません。

たとえば、2006年以降のブログエントリーの [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を取得するには、 [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) を次のように使用します。

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

デフォルトの manager クラスの場合、これは次のコードと等価です。

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

#### フィルターのチェーン

絞り込みを行った [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) の結果自体も [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) です。そのため、複数の絞り込みをチェーンすることが可能です。たとえば、次のように書くことができます。

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

これはデータベース内のすべてのエントリーを含む [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) をとり、フィルターを追加し、除外フィルターを追加し、さらにもう1つのフィルターを追加しています。最終的な結果は、"What" で始まるヘッドラインを持ち、2005年1月30日から今日までに公開されたすべてのエントリーを含んだ [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) となります。

#### フィルターを適用した `QuerySet` はユニーク

[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) に対して絞り込みを適用するごとに、前の [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) から独立した完全に新しい [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) が作られます。絞り込みごとに独立した [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) が作られるため、保存したり何度も再利用したりできます。

実装例:

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

これら3つの `QuerySets` は独立しています。1番目は基本の [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) で、"What" で始まるヘッドラインを持つ全てのエントリーを含みます。2番めは1番目の部分集合で、 `pub_date` が今日または未来の日付であるレコードを除外する追加条件を持ちます。3番目も1番目の部分集合で、 `pub_date` が今日または未来の日付であるレコードだけを選択する追加条件を持ちます。1番目の [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) (`q1`) は、絞り込みの過程において何ら影響を受けません。

#### `QuerySet` は遅延評価される

`QuerySets` は遅延評価されます。 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を作る行為はいかなるデータベース操作も引き起こしません。たとえあなたが 1 日中フィルターのスタックを積み上げたとしても、[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) が *評価される* までは、Django は実際にはクエリを実行しません。次の例を見てください。

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

この例ではデータベースに3回アクセスしているように見えますが、実際にアクセスしているのは、最終行 (`print(q)`) での1回だけです。一般に、 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) の結果は、明示的に要求するまでデータベースから取得されません。取得するように要求した時点で、 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) は *評価* され、データベースへのアクセスが発生します。評価が起こる正確なタイミングの詳細については、 [When QuerySets are evaluated](/ja/4.0/ref/models/querysets/#when-querysets-are-evaluated) を参照してください。

### `get()` を用いて1つのオブジェクトを取得する

[`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) は、たとえクエリーにマッチしたのが1つのオブジェクトだけだったとしても、常に [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を返します。この場合、 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) には1つの要素だけが含まれることになります。

クエリーにマッチするのは1つのオブジェクトだけだと分かっている場合、  [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) の [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) メソッドを呼べば、そのオブジェクトが直接返されます。

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

[`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) と同じように、 [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) には任意のクエリー表現が使用できます。 繰り返しますが、詳しくはあとで説明する [Field lookups](#field-lookups) を見てください。

[`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) と [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) を `[0]` でスライスすることには、次のような違いがあることに注意してください。クエリにマッチする結果が存在しない場合、 [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) は `DoesNotExist` 例外を起こします。この例外はクエリーが実行されるモデルクラスの属性です。たとえば上のコードでは、1というプライマリーキーを持つ `Entry` オブジェクトがなければ、Django は `Entry.DoesNotExist` 例外を起こします。

同様に [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) のクエリーが2つ以上のアイテムにマッチした場合にも、Djangoは文句を言います。この場合には、やはり同じクエリのモデルクラスの属性の [`MultipleObjectsReturned`](/ja/4.0/ref/exceptions/#django.core.exceptions.MultipleObjectsReturned) 例外が起こります。

### その他の `QuerySet` メソッド

データベースからオブジェクトを検索する必要がある大抵の場合は、 [`all()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.all), [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get), [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) および [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) のいずれかを使うことになるでしょう。しかしこれらのメソッドだけでは不十分な場合は、さまざまな [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) メソッドの全リストが掲載されている [QuerySet API Reference](/ja/4.0/ref/models/querysets/#queryset-api) を参照してください。

### `QuerySet` の要素数を制限する

Python のリストスライスのサブセットを使うことで [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.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`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) をスライスしたとしても、新しい [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) が返り、クエリーの評価は行われません。例外は、Python のリストスライス構文の "step" パラメーターを使用した場合です。たとえば、次のコードは実際にクエリを実行し、最初の10個のオブジェクトから一つおきにとったオブジェクトのリストを返します。

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

Further filtering or ordering of a sliced queryset is prohibited due to the
ambiguous nature of how that might work.

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

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

上の例は次のコードとほとんど同じです。

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

ただし、与えられた条件を満たすオブジェクトが存在しない場合に、前者は `IndexError` を起こすのに対して、後者は `DoesNotExist` を起こすことに注意してください。詳細については [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) を参照してください。

### フィールドルックアップ

フィールドルックアップは、SQL の `WHERE` 句の内容を指定する手段です。 [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) メソッド、 [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) 、 [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) および [`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get) にキーワード引数として指定します。

基本のルックアップキーワード引数は `field__lookuptype=value` という形を取ります (2文字連続するアンダースコアです)。たとえば、

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

というコードは、(だいたい) 次の SQL 文に変換されます。

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

> **動作のしくみ**
>
> Python には任意の name-value 形式の引数をとる関数を定義する能力があり、name と value の値を実行時に評価します。詳しい情報については、公式の Python チュートリアルを参照してください。

ルックアップに指定するフィールドはモデルが持つフィールド名でなければなりません。ただし1つだけ例外があり、 [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) の場合にはフィールド名の末尾に `_id` を付けた名前を指定することができます。その場合、value  パラメータには外部モデルのプライマリーキーの生の値を書くことが期待されます。

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

無効なキーワード引数を指定すると、ルックアップ関数は `TypeError` を起こします。

データベース API は約30個のルックアップタイプをサポートしており、完全なガイドは [field lookup reference](/ja/4.0/ref/models/querysets/#field-lookups) で見ることができます。ルックアップを使って何ができるのかがよく分かるように、以下によく使う一般的なルックアップをいくつか挙げます。

**[`exact`](/ja/4.0/ref/models/querysets/#std-fieldlookup-exact)**

  完全な ("exact") マッチを行います。たとえば、

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

  は次のような SQL を生成します。

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

  ルックアップタイプを指定しなかった場合、つまりキーワード引数がダブルアンダースコアを含まない場合、ルックアップタイプは `exact` が指定されたものとみなされます。

  たとえば、次の2つの文は等価です。

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

  `exact` ルックアップが最もよく使われるため、利便性のためにこのようになっています。

**[`iexact`](/ja/4.0/ref/models/querysets/#std-fieldlookup-iexact)**

  case-insensitive  なマッチを行います。したがって、次のクエリ

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

  は `"Beatles Blog"` 、 `"beatles blog"` 、あるいは `"BeAtlES blOG"` というタイトルを持つ `Blog` にもマッチします。

**[`contains`](/ja/4.0/ref/models/querysets/#std-fieldlookup-contains)**

  case-sensitive な部分一致テストを行います。たとえば、

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

  はだいたい次のような SQL に変換されます。

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

  この例では、ヘッドライン `'Today Lennon honored'` にはマッチしても `'today lennon honored'` にはマッチしないことに注意してください。

  case-insensitive バージョンの [`icontains`](/ja/4.0/ref/models/querysets/#std-fieldlookup-icontains) もあります。

**[`startswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-startswith) と [`endswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-endswith)**

  それぞれ starts-with と ends-with 検索を行います。case-insensitive バージョン [`istartswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-istartswith) と [`iendswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-iendswith) もあります。

繰り返しになりますが、以上はルックアップの表面をさらったに過ぎません。完全なリファレンスは [field lookup reference](/ja/4.0/ref/models/querysets/#field-lookups) を参照してください。

### リレーションを横断するルックアップ

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

次の例は、`name` に `'Beatles Blog'` を持つ `Blog` のすべての `Entry` オブジェクトを取得します。

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

この横断は好きなだけ深くすることができます。

It works backwards, too. While it [`can be customized`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey.related_query_name), by default you refer to a "reverse"
relationship in a lookup using the lowercase name of the model.

次の例は、 少なくとも1つの `headline` が `'Lennon'` を含む `Entry` を持つ、すべての `Blog` オブジェクトを取得します。

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

複数のリレーションにまたがってフィルタリングをしていて、仲介するどれかが条件に合致しない場合、Django は空 (すべての値が `NULL`) だけど有効なオブジェクトとして扱います これが意味するのは、エラーが投げられないと言うことです。例えば、以下のフィルタでは:

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

(関係づけられた `Author` モデルがあった場合で) entry に関係づけられた `author` がない場合、 `name` がなかったかのように扱われ、`author` がないという理由でエラーを投げることはありません。通常、これは必要とされる動作です。もし混乱するとしたら、[`isnull`](/ja/4.0/ref/models/querysets/#std-fieldlookup-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)
```

#### 複数の値を持つリレーションの横断

When spanning a [`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) or a reverse
[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) (such as from `Blog` to `Entry`),
filtering on multiple attributes raises the question of whether to require each
attribute to coincide in the same related object. We might seek blogs that have
an entry from 2008 with *“Lennon”* in its headline, or we might seek blogs that
merely have any entry from 2008 as well as some newer or older entry with
*“Lennon”* in its headline.

To select all blogs containing at least one entry from 2008 having *"Lennon"*
in its headline (the same entry satisfying both conditions), we would write:

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

Otherwise, to perform a more permissive query selecting any blogs with merely
*some* entry with *"Lennon"* in its headline and *some* entry from 2008, we
would write:

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

Suppose there is only one blog that has both entries containing *"Lennon"* and
entries from 2008, but that none of the entries from 2008 contained *"Lennon"*.
The first query would not return any blogs, but the second query would return
that one blog. (This is because the entries selected by the second filter may
or may not be the same as the entries in the first filter. We are filtering the
`Blog` items with each filter statement, not the `Entry` items.) In short,
if each condition needs to match the same related object, then each should be
contained in a single [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) call.

> **Note**
>
> As the second (more permissive) query chains multiple filters, it performs
> multiple joins to the primary model, potentially yielding duplicates.
>
> ```
> >>> 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]>
> ```

> **Note**
>
> The behavior of [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) for queries
> that span multi-value relationships, as described above, is not implemented
> equivalently for [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude). Instead,
> the conditions in a single [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude)
> call will not necessarily refer to the same item.
>
> For example, the following query would exclude blogs that contain *both*
> entries with *"Lennon"* in the headline *and* entries published in 2008:
>
> ```
> Blog.objects.exclude(
>     entry__headline__contains='Lennon',
>     entry__pub_date__year=2008,
> )
> ```
>
> However, unlike the behavior when using
> [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter), this will not limit blogs
> based on entries that satisfy both conditions. In order to do that, i.e.
> to select all blogs that do not contain entries published with *"Lennon"*
> that were published in 2008, you need to make two queries:
>
> ```
> Blog.objects.exclude(
>     entry__in=Entry.objects.filter(
>         headline__contains='Lennon',
>         pub_date__year=2008,
>     ),
> )
> ```

### フィルターはモデルのフィールドを参照できる

今まで見てきた例では、モデルのフィールドの値を定数と比較するフィルタを作ってきました。しかし、もしモデルのフィールドの値を、同じモデルの他のフィールドと比較したい時にはどうすればいいのでしょう？

そのような比較を行うために、Django は [`F 式`](/ja/4.0/ref/models/expressions/#django.db.models.F) を用意しています。 `F()` のインスタンスは、クエリの中でモデルのフィールドへの参照として振る舞います。したがって、この参照をクエリの中で使うことで、同じモデルのインスタンスの異なる2つのフィールドの値を比較することができます。

たとえば、pingback の数よりコメントの数が多いすべてのブログエントリーのリストを検索するには、pingback の数を参照する `F()` オブジェクトを作り、その `F()` オブジェクトをクエリの中で次のように使います。

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

Django supports the use of addition, subtraction, multiplication,
division, modulo, and power arithmetic with `F()` objects, both with constants
and with other `F()` objects. To find all the blog entries with more than
*twice* as many comments as pingbacks, we modify the query:

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

To find all the entries where the rating of the entry is less than the
sum of the pingback count and comment count, we would issue the
query:

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

You can also use the double underscore notation to span relationships in
an `F()` object. An `F()` object with a double underscore will introduce
any joins needed to access the related object. For example, to retrieve all
the entries where the author's name is the same as the blog name, we could
issue the query:

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

For date and date/time fields, you can add or subtract a
[`timedelta`](https://docs.python.org/3/library/datetime.html#datetime.timedelta) object. The following would return all entries
that were modified more than 3 days after they were published:

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

The `F()` objects support bitwise operations by `.bitand()`, `.bitor()`,
`.bitxor()`, `.bitrightshift()`, and `.bitleftshift()`. For example:

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

> **Oracle**
>
> Oracle doesn't support bitwise XOR operation.

### Expressions can reference transforms

> **New in Django 3.2**

Django supports using transforms in expressions.

For example, to find all `Entry` objects published in the same year as they
were last modified:

```
>>> Entry.objects.filter(pub_date__year=F('mod_date__year'))
```

To find the earliest year an entry was published, we can issue the query:

```
>>> Entry.objects.aggregate(first_published_year=Min('pub_date__year'))
```

This example finds the value of the highest rated entry and the total number
of comments on all entries for each year:

```
>>> 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` ルックアップショートカットを用意しています。pk とは "primary key" を表します。

プライマリーキーが `id` フィールドである `Blog` モデルの例では、次の3つの文はすべて等価です。

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

The use of `pk` isn't limited to `__exact` queries -- any query term
can be combined with `pk` to perform a query on the primary key of a model:

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

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

`pk` lookups also work across joins. For example, these three statements are
equivalent:

```
>>> 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` 文の中ではパーセント記号とアンダースコアがエスケープされる

The field lookups that equate to `LIKE` SQL statements (`iexact`,
`contains`, `icontains`, `startswith`, `istartswith`, `endswith`
and `iendswith`) will automatically escape the two special characters used in
`LIKE` statements -- the percent sign and the underscore. (In a `LIKE`
statement, the percent sign signifies a multiple-character wildcard and the
underscore signifies a single-character wildcard.)

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

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

Django takes care of the quoting for you; the resulting SQL will look something
like this:

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

Same goes for underscores. Both percentage signs and underscores are handled
for you transparently.

### キャッシングと `QuerySet`

それぞれの [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) には、データベースへのアクセスを最小にするために内部にキャッシュがあります。キャッシュのしくみを理解すれば、最も効率の良いコードが書けるようになります。

In a newly created [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet), the cache is
empty. The first time a [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) is evaluated
-- and, hence, a database query happens -- Django saves the query results in
the [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet)’s cache and returns the results
that have been explicitly requested (e.g., the next element, if the
[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) is being iterated over). Subsequent
evaluations of the [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) reuse the cached
results.

Keep this caching behavior in mind, because it may bite you if you don't use
your [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet)s correctly. For example, the
following will create two [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet)s, evaluate
them, and throw them away:

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

That means the same database query will be executed twice, effectively doubling
your database load. Also, there's a possibility the two lists may not include
the same database records, because an `Entry` may have been added or deleted
in the split second between the two requests.

To avoid this problem, save the [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) and
reuse it:

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

#### `QuerySet` がキャッシュされない場合

Querysets do not always cache their results.  When evaluating only *part* of
the queryset, the cache is checked, but if it is not populated then the items
returned by the subsequent query are not cached. Specifically, this means that
[limiting the queryset](#limiting-querysets) using an array slice or an
index will not populate the cache.

For example, repeatedly getting a certain index in a queryset object will query
the database each time:

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

However, if the entire queryset has already been evaluated, the cache will be
checked instead:

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

Here are some examples of other actions that will result in the entire queryset
being evaluated and therefore populate the cache:

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

> **Note**
>
> Simply printing the queryset will not populate the cache. This is because
> the call to `__repr__()` only returns a slice of the entire queryset.

## Querying `JSONField`

Lookups implementation is different in [`JSONField`](/ja/4.0/ref/models/fields/#django.db.models.JSONField),
mainly due to the existence of key transformations. To demonstrate, we will use
the following example model:

```
from django.db import models

class Dog(models.Model):
    name = models.CharField(max_length=200)
    data = models.JSONField(null=True)

    def __str__(self):
        return self.name
```

### Storing and querying for `None`

As with other fields, storing `None` as the field's value will store it as
SQL `NULL`. While not recommended, it is possible to store JSON scalar
`null` instead of SQL `NULL` by using [`Value('null')`](/ja/4.0/ref/models/expressions/#django.db.models.Value).

Whichever of the values is stored, when retrieved from the database, the Python
representation of the JSON scalar `null` is the same as SQL `NULL`, i.e.
`None`. Therefore, it can be hard to distinguish between them.

This only applies to `None` as the top-level value of the field. If `None`
is inside a [`list`](https://docs.python.org/3/library/stdtypes.html#list) or [`dict`](https://docs.python.org/3/library/stdtypes.html#dict), it will always be interpreted
as JSON `null`.

When querying, `None` value will always be interpreted as JSON `null`. To
query for SQL `NULL`, use [`isnull`](/ja/4.0/ref/models/querysets/#std-fieldlookup-isnull):

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

Unless you are sure you wish to work with SQL `NULL` values, consider setting
`null=False` and providing a suitable default for empty values, such as
`default=dict`.

> **Note**
>
> Storing JSON scalar `null` does not violate [`null=False`](/ja/4.0/ref/models/fields/#django.db.models.Field.null).

### Key, index, and path transforms

To query based on a given dictionary key, use that key as the lookup name:

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

Multiple keys can be chained together to form a path lookup:

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

If the key is an integer, it will be interpreted as an index transform in an
array:

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

If the key you wish to query by clashes with the name of another lookup, use
the [`contains`](#std-fieldlookup-jsonfield.contains) lookup instead.

To query for missing keys, use the `isnull` lookup:

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

> **Note**
>
> The lookup examples given above implicitly use the [`exact`](/ja/4.0/ref/models/querysets/#std-fieldlookup-exact) lookup.
> Key, index, and path transforms can also be chained with:
> [`icontains`](/ja/4.0/ref/models/querysets/#std-fieldlookup-icontains), [`endswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-endswith), [`iendswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-iendswith),
> [`iexact`](/ja/4.0/ref/models/querysets/#std-fieldlookup-iexact), [`regex`](/ja/4.0/ref/models/querysets/#std-fieldlookup-regex), [`iregex`](/ja/4.0/ref/models/querysets/#std-fieldlookup-iregex), [`startswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-startswith),
> [`istartswith`](/ja/4.0/ref/models/querysets/#std-fieldlookup-istartswith), [`lt`](/ja/4.0/ref/models/querysets/#std-fieldlookup-lt), [`lte`](/ja/4.0/ref/models/querysets/#std-fieldlookup-lte), [`gt`](/ja/4.0/ref/models/querysets/#std-fieldlookup-gt), and
> [`gte`](/ja/4.0/ref/models/querysets/#std-fieldlookup-gte), as well as with [Containment and key lookups](#containment-and-key-lookups).

> **Note**
>
> Due to the way in which key-path queries work,
> [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) and
> [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter) are not guaranteed to
> produce exhaustive sets. If you want to include objects that do not have
> the path, add the `isnull` lookup.

> **Warning**
>
> Since any string could be a key in a JSON object, any lookup other than
> those listed below will be interpreted as a key lookup. No errors are
> raised. Be extra careful for typing mistakes, and always check your queries
> work as you intend.

> **MariaDB and Oracle users**
>
> Using [`order_by()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.order_by) on key, index, or
> path transforms will sort the objects using the string representation of
> the values. This is because MariaDB and Oracle Database do not provide a
> function that converts JSON values into their equivalent SQL values.

> **Oracle users**
>
> On Oracle Database, using `None` as the lookup value in an
> [`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude) query will return objects
> that do not have `null` as the value at the given path, including objects
> that do not have the path. On other database backends, the query will
> return objects that have the path and the value is not `null`.

> **PostgreSQL users**
>
> On PostgreSQL, if only one key or index is used, the SQL operator `->` is
> used. If multiple operators are used then the `#>` operator is used.

> **SQLite users**
>
> On SQLite, `"true"`, `"false"`, and `"null"` string values will
> always be interpreted as `True`, `False`, and JSON `null`
> respectively.

### Containment and key lookups

#### `contains`

The [`contains`](/ja/4.0/ref/models/querysets/#std-fieldlookup-contains) lookup is overridden on `JSONField`. The returned
objects are those where the given `dict` of key-value pairs are all
contained in the top-level of the field. For example:

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

> **Oracle and SQLite**
>
> `contains` is not supported on Oracle and SQLite.

#### `contained_by`

This is the inverse of the [`contains`](#std-fieldlookup-jsonfield.contains) lookup - the
objects returned will be those where the key-value pairs on the object are a
subset of those in the value passed. For example:

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

> **Oracle and SQLite**
>
> `contained_by` is not supported on Oracle and SQLite.

#### `has_key`

Returns objects where the given key is in the top-level of the data. For
example:

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

#### `has_keys`

Returns objects where all of the given keys are in the top-level of the data.
For example:

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

#### `has_any_keys`

Returns objects where any of the given keys are in the top-level of the data.
For example:

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

## `Q` オブジェクトを用いた複雑な検索

Keyword argument queries -- in [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter),
etc. -- are "AND"ed together. If you need to execute more complex queries (for
example, queries with `OR` statements), you can use [`Q objects`](/ja/4.0/ref/models/querysets/#django.db.models.Q).

A [`Q object`](/ja/4.0/ref/models/querysets/#django.db.models.Q) (`django.db.models.Q`) is an object
used to encapsulate a collection of keyword arguments. These keyword arguments
are specified as in "Field lookups" above.

たとえば、次の `Q` オブジェクトは、1つの `LIKE` クエリをカプセル化しています。

```
from django.db.models import Q
Q(question__startswith='What')
```

`Q` オブジェクトは `&` や `|` 演算子を使って結合することができます。2つの `Q` オブジェクトに演算子が作用すると、1つの新しい `Q` オブジェクトが生まれます。

たとえば、次の文は2つの `"question__startswith"` の "OR" を表す、1つの `Q` オブジェクトを生み出します。

```
Q(question__startswith='Who') | Q(question__startswith='What')
```

このコードは次の SQL の `WHERE` 句と同等です。

```
WHERE question LIKE 'Who%' OR question LIKE 'What%'
```

You can compose statements of arbitrary complexity by combining `Q` objects
with the `&` and `|` operators and use parenthetical grouping. Also, `Q`
objects can be negated using the `~` operator, allowing for combined lookups
that combine both a normal query and a negated (`NOT`) query:

```
Q(question__startswith='Who') | ~Q(pub_date__year=2005)
```

Each lookup function that takes keyword-arguments
(e.g. [`filter()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.filter),
[`exclude()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.exclude),
[`get()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.get)) can also be passed one or more
`Q` objects as positional (not-named) arguments. If you provide multiple
`Q` object arguments to a lookup function, the arguments will be "AND"ed
together. For example:

```
Poll.objects.get(
    Q(question__startswith='Who'),
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))
)
```

... roughly translates into the SQL:

```sql
SELECT * from polls WHERE question LIKE 'Who%'
    AND (pub_date = '2005-05-02' OR pub_date = '2005-05-06')
```

Lookup functions can mix the use of `Q` objects and keyword arguments. All
arguments provided to a lookup function (be they keyword arguments or `Q`
objects) are "AND"ed together. However, if a `Q` object is provided, it must
precede the definition of any keyword arguments. For example:

```
Poll.objects.get(
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6)),
    question__startswith='Who',
)
```

... would be a valid query, equivalent to the previous example; but:

```
# INVALID QUERY
Poll.objects.get(
    question__startswith='Who',
    Q(pub_date=date(2005, 5, 2)) | Q(pub_date=date(2005, 5, 6))
)
```

... would not be valid.

> **See also**
>
> The [OR lookups examples](https://github.com/django/django/blob/stable/4.0.x/tests/or_lookups/tests.py) in Django's
> unit tests show some possible uses of `Q`.

## オブジェクトを比較する

To compare two model instances, use the standard Python comparison operator,
the double equals sign: `==`. Behind the scenes, that compares the primary
key values of two models.

上記の例の `Entry` を使用すると、以下の 2 つの命令文は同一となります:

```
>>> some_entry == other_entry
>>> some_entry.id == other_entry.id
```

モデルのプライマリキーが `id` 以外の場合でも問題ありません。どのフィールドが使われていようとも、比較には常にプライマリキーが使われます。例えば、モデルのプライマリキーが `name` の場合、以下の 2 つの命令文は同一となります:

```
>>> some_obj == other_obj
>>> some_obj.name == other_obj.name
```

## オブジェクトを削除する

削除のメソッドは、便利なことに [`delete()`](/ja/4.0/ref/models/instances/#django.db.models.Model.delete) という名前がつけられています。このメソッドはオブジェクトを即座に削除して、削除したオブジェクトの数とオブジェクトのタイプごとの削除数を表すディクショナリを返します。例えば:

```
>>> e.delete()
(1, {'blog.Entry': 1})
```

オブジェクトを一括で削除することもできます。すべての [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) は [`delete()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.delete) メソッドを持っており、その [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) のすべてのメンバーを削除します。

例えば、以下は `pub_date` が 2005 年のすべての `Entry` オブジェクトを削除します:

```
>>> Entry.objects.filter(pub_date__year=2005).delete()
(5, {'webapp.Entry': 5})
```

注意してほしいのは、この処理は可能な場合には純粋に SQL で実行され、個別のオブジェクトインスタンスの `delete()` メソッドはプロセス中に呼ぶ必要はないということです。モデルクラスで独自の `delete()` メソッドを定義していて確実に呼び出されるようにしたい場合、[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) で一括の [`delete()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.delete) を使用するのではなく、そのモデルのインスタンスを "手動で" 削除する必要があります (例えば、[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) を繰り返し処理し、各オブジェクトで個別に `delete()` を呼び出します)。

Django がオブジェクトを削除するとき、デフォルトでは SQL の制限 `ON DELETE CASCADE` の動作をエミュレートします -- 言い換えると、削除するオブジェクトを指している外部キーを持つすべてのオブジェクトは、ともに削除されることになります。例えば:

```
b = Blog.objects.get(pk=1)
# This will delete the Blog and all of its Entry objects.
b.delete()
```

このカスケードの動作は、[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) に対する [`on_delete`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey.on_delete) 属性によってカスタマイズできます。

[`delete()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.delete) は、[`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) で露出していない唯一の [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) のメソッドです。これは、`Entry.objects.delete()` を誤ってリクエストして *すべての* entry を削除してしまうことを防ぐ安全上の仕組みです。すべてのオブジェクトを削除 *したい* 場合、明示的に完全なクエリセットをリクエストする必要があります:

```
Entry.objects.all().delete()
```

## モデルのインスタンスを複製する

Although there is no built-in method for copying model instances, it is
possible to easily create new instance with all fields' values copied. In the
simplest case, you can set `pk` to `None` and
[`_state.adding`](/ja/4.0/ref/models/instances/#django.db.models.Model._state) to `True`. Using our
blog example:

```
blog = Blog(name='My blog', tagline='Blogging is easy')
blog.save() # blog.pk == 1

blog.pk = None
blog._state.adding = True
blog.save() # blog.pk == 2
```

継承を使用している場合、物事は少し複雑になります。`Blog` のサブクラスを考えると:

```
class ThemeBlog(Blog):
    theme = models.CharField(max_length=200)

django_blog = ThemeBlog(name='Django', tagline='Django is easy', theme='python')
django_blog.save() # django_blog.pk == 3
```

Due to how inheritance works, you have to set both `pk` and `id` to
`None`, and `_state.adding` to `True`:

```
django_blog.pk = None
django_blog.id = None
django_blog._state.adding = True
django_blog.save() # django_blog.pk == 4
```

この処理では、モデルのデータベーステーブルの一部ではないリレーションは複製しません。例えば、`Entry` は `Author` への `ManyToManyField` を持ちます。entry の複製後、新しい entry に対して多対多のリレーションをセットする必要があります:

```
entry = Entry.objects.all()[0] # some previous entry
old_authors = entry.authors.all()
entry.pk = None
entry._state.adding = True
entry.save()
entry.authors.set(old_authors)
```

`OneToOneField` については、1 対 1 のユニーク制限への違反を避けるため、関係オブジェクトを複製して新しいオブジェクトのフィールドに割り当てる必要があります。例えば、`entry` が上記のようにすでに複製されているものとすると:

```
detail = EntryDetail.objects.all()[0]
detail.pk = None
detail._state.adding = True
detail.entry = entry
detail.save()
```

## 複数のオブジェクトを一括で更新する

[`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) のすべてのオブジェクトに、特定の値をセットしたい場合があります。[`update()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.update) を使えば実現できます。例えば:

```
# Update all the headlines with pub_date in 2007.
Entry.objects.filter(pub_date__year=2007).update(headline='Everything is the same')
```

このメソッドを使ってセットできるのは非リレーションのフィールドと [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) フィールドだけです。非リレーションのフィールドを更新するには、定数として新しい値を渡してください。[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) フィールドを更新するには、関係づけたい新しいモデルインスタンスを新しい値にセットしてください。例えば:

```
>>> b = Blog.objects.get(pk=1)

# Change every Entry so that it belongs to this Blog.
>>> Entry.objects.all().update(blog=b)
```

`update()` は即座に適用され、クエリに一致した行数を返します (行のいくつかはすでに新しい値を持っていることがあるので、更新された行の数と一致するとは限りません)。更新する [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) の唯一の制限は、1 つのデータベーステーブル (モデルのメインテーブル) にしかアクセスできないことです。関係フィールドでフィルタすることもできますが、モデルのメインテーブルのカラムしか更新できません。例えば:

```
>>> b = Blog.objects.get(pk=1)

# Update all the headlines belonging to this Blog.
>>> Entry.objects.filter(blog=b).update(headline='Everything is the same')
```

Be aware that the `update()` method is converted directly to an SQL
statement. It is a bulk operation for direct updates. It doesn't run any
[`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) methods on your models, or emit the
`pre_save` or `post_save` signals (which are a consequence of calling
[`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save)), or honor the
[`auto_now`](/ja/4.0/ref/models/fields/#django.db.models.DateField.auto_now) field option.
If you want to save every item in a [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet)
and make sure that the [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) method is called on
each instance, you don't need any special function to handle that. Loop over
them and call [`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save):

```
for item in my_queryset:
    item.save()
```

更新の呼び出しでは、[`F 式`](/ja/4.0/ref/models/expressions/#django.db.models.F) を使ってモデル内の別のフィールドの値に基づいてフィールドを更新することもできます。これは、現在値に基づいてカウンタを増加させる場合に特に有用です。例えば、ブログの各 entry のpingback カウントを増加させるには:

```
>>> Entry.objects.all().update(number_of_pingbacks=F('number_of_pingbacks') + 1)
```

しかし、filter および exclude 節での `F()` オブジェクトとは異なり、更新で `F()` オブジェクトを使うときには join を導入することはできません -- できるのは、更新されるモデルに関係付いたフィールドを参照することだけです。 `F()` オブジェクトで join の導入を試みた場合、`FieldError` が投げられます:

```
# This will raise a FieldError
>>> Entry.objects.update(headline=F('blog__name'))
```

## 関係オブジェクト

モデルでリレーションシップを定義した場合 (例えば [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey)、[`OneToOneField`](/ja/4.0/ref/models/fields/#django.db.models.OneToOneField)、[`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) の 3 つです)、そのモデルのインスタンスは便利な関係オブジェクトにアクセスするための便利な API を持ちます。

このページで最初に提示したモデルを使うと、例えば、`Entry` オブジェクト `e` は、`blog` 属性 (`e.blog`) にアクセスすることで、関連付けられた `Blog` オブジェクトを得ることができます。

(Behind the scenes, this functionality is implemented by Python
[descriptors](https://docs.python.org/3/howto/descriptor.html). This shouldn't really matter to
you, but we point it out here for the curious.)

リレーションシップの "他の" 側面のために、Django は API アクセサも提供します -- 関係を定義するモデルに対する関係モデルからのリンクです。例えば、`Blog` オブジェクト `b` は、`entry_set` の属性 (```b.entry_set.all()`) を通じて、すべての関係 ``Entry``` オブジェクトのリストへにアクセスできます。

このセクションのすべての例で使われたサンプルの `Blog`、`Author`、`Entry` モデルは、このページの最初で定義したものです。

### 1 対多のリレーションシップ

#### Forward

If a model has a [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey), instances of that model
will have access to the related (foreign) object via an attribute of the model.

実装例:

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

外部キーの属性を使って、取得と格納ができます。想像されている通り、[`save()`](/ja/4.0/ref/models/instances/#django.db.models.Model.save) を呼び出すまで、外部キーへの変更はデータベースに保存されません。

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

[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) フィールドに `null=True` がセットされている場合 (これは `NULL` を許可することを意味します)、`None` を割り当ててリレーションを削除できます。例えば:

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

1対多リレーションシップへの将来のアクセスは、最初に関係オブジェクトにアクセスしたときにキャッシュ化されています。同じオブジェクトインスタンスでの外部キーへの引き続きのアクセスはキャッシュ化されます。例えば:

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

[`select_related()`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet.select_related) [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) メソッドは、事前にすべての 1 対多リレーションシップのキャッシュを再帰的に作成する点に注意してください。例えば:

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

#### リレーションシップ "反対向き” を理解する

モデルが [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) を持つ場合、外部キーのモデルのインスタンスは最初のモデルのインスタンスを返す [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) にアクセスできます。デフォルトでは、この [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) は `FOO_set` と名付けられており、`FOO` には元のモデル名が小文字で入ります。この [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) は `QuerySets` を返し、上述の "オブジェクトを取り出す" セクションで説明したようにフィルタおよび操作が可能です。

実装例:

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

[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) 定義内の [`related_name`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey.related_name) パラメータをセットして `FOO_set` の名前をオーバーライドできます。例えば、`Entry` モデルが `blog = ForeignKey(Blog, on_delete=models.CASCADE, related_name='entries')` と変更されていたら、上記のコード例は以下のようになります:

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

#### 独自のリバースマネージャーを使用する

デフォルトでは、反対向きのリレーションシップに使われる [`RelatedManager`](/ja/4.0/ref/models/relations/#django.db.models.fields.related.RelatedManager) はモデルに対する [default manager](/ja/4.0/topics/db/managers/#manager-names) のサブクラスです。与えられたクエリに対して別のマネージャーを指定したい場合、以下のシンタックスを使うことができます:

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

`EntryManager` が、`get_queryset()` メソッドでデフォルトのフィルタ動作をした場合、`all()` の呼び出しに適用されます。

Specifying a custom reverse manager also enables you to call its custom
methods:

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

#### 関係オブジェクトを処理する他のメソッド

上述の "オブジェクトを取り出す" で定義した [`QuerySet`](/ja/4.0/ref/models/querysets/#django.db.models.query.QuerySet) メソッドに加えて、[`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey) [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) は関係オブジェクトのセットを処理するために使われる他のメソッドを持っています。それぞれの概略は以下の通りです。完全な詳細は [related objects reference](/ja/4.0/ref/models/relations/) で確認できます。

**`add(obj1, obj2, ...)`**

  関係オブジェクトのセットに、指定したモデルオブジェクトを追加します。

**`create(**kwargs)`**

  新しいオブジェクトを作成、保存して、関係オブジェクトのセットに格納します。新しく作成したオブジェクトを返します。

**`remove(obj1, obj2, ...)`**

  関係オブジェクトのセットから、指定したモデルオブジェクトを削除します。

**`clear()`**

  関係オブジェクトのセットからすべてのオブジェクトを削除します。

**`set(objs)`**

  関係オブジェクトのセットを置き換えます。

関係セットのメンバーを割り当てるには、オブジェクトインスタンスのイテラブルとともに `set()` メソッドを使ってください。 例えば、`e1` と `e2` が `Entry` のインスタンスだとして:

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

`clear()` メソッドが有効な場合、既存のオブジェクトは、イテラブル (この場合はリスト) 内のすべてのオブジェクトがセットに追加される前に `entry_set` から削除されます。`clear()` メソッドが *無効* な場合、イテラブル内のすべてのオブジェクトは既存の要素を削除することなく追加されます。

このセクションで説明した "反対向きの" 操作は、すべて即座にデータベースに反映されます。すべての追加、作成、削除の操作は自動的にデータベースに保存されます。

### 多対多 (many-to-many) 関係

多対多リレーションシップの両方の側で、もう片方に対する自動的な API アクセスを使えます。API は、上述の "反対方向の" 1 対多リレーションシップと似た形で動作します。

One difference is in the attribute naming: The model that defines the
[`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) uses the attribute name of that
field itself, whereas the "reverse" model uses the lowercased model name of the
original model, plus `'_set'` (just like reverse one-to-many relationships).

An example makes this easier to understand:

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

Like [`ForeignKey`](/ja/4.0/ref/models/fields/#django.db.models.ForeignKey),
[`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) can specify
[`related_name`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField.related_name). In the above example,
if the [`ManyToManyField`](/ja/4.0/ref/models/fields/#django.db.models.ManyToManyField) in `Entry` had specified
`related_name='entries'`, then each `Author` instance would have an
`entries` attribute instead of `entry_set`.

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

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

### 一対一 (one-to-one) 関係

One-to-one relationships are very similar to many-to-one relationships. If you
define a [`OneToOneField`](/ja/4.0/ref/models/fields/#django.db.models.OneToOneField) on your model, instances of
that model will have access to the related object via an attribute of the
model.

例:

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

The difference comes in "reverse" queries. The related model in a one-to-one
relationship also has access to a [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) object, but
that [`Manager`](/ja/4.0/topics/db/managers/#django.db.models.Manager) represents a single object, rather than
a collection of objects:

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

If no object has been assigned to this relationship, Django will raise
a `DoesNotExist` exception.

Instances can be assigned to the reverse relationship in the same way as
you would assign the forward relationship:

```
e.entrydetail = ed
```

### How are the backward relationships possible?

他のオブジェクトリレーショナルマッパでは、リレーションシップを両サイドで定義する必要があります。Django の開発陣はこれは DRY (Don't Repeat Yourself) の原則に反していると考えており、Django では片側でリレーションシップを定義する必要があるだけとなりました。

しかし、どのようにして実現しているのでしょうか? モデルクラスは、他のどのモデルクラスと関係しているのか、関係先のモデルクラスが読み込まれるまで分からないはずです。

その答えは [`app registry`](/ja/4.0/ref/applications/#django.apps.apps) にあります。Django は開始する際、[`INSTALLED_APPS`](/ja/4.0/ref/settings/#std-setting-INSTALLED_APPS) に定義された各アプリケーションと、各アプリケーション内の `model` モジュールをインポートします。新しいモデルクラスが作成されるときは毎回、 Django はすべての関係モデルに対して背後関係を追加します。関係モデルがまだインポートされていなかった場合、Django はこのリレーションシップを追跡し、関係モデルが最終的にインポートされた段階で追加します。

この理由により、[`INSTALLED_APPS`](/ja/4.0/ref/settings/#std-setting-INSTALLED_APPS) にリストアップするアプリケーション内に、使おうとしているモデルをすべて定義することが特に重要となります。そうしないと、背後関係がうまく動作しなくなります。

### 関係オブジェクトを横断したクエリ

関係オブジェクトを含むクエリは、通常の値フィールドを含むクエリと同じルールに従います。クエリにマッチするための値を指定する際、オブジェクトインスタンス自体かオブジェクトのプライマリキー値のどちらかを使用します。

例えば、`id=5` の Blog オブジェクト `b` がある場合、以下の 3 つのクエリは同一となります:

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

## 素の SQL にフォールバックする

Django のデータベースマッパが扱うには複雑すぎる SQL クエリを記述する必要がある場合、手書きで SQL を書くことができます。Django には、素の SQL クエリを記述するための方法がいくつかあります; [素の SQL 文の実行](/ja/4.0/topics/db/sql/) を参照してください。

最後に、覚えておいてほしい重要な点は、Django のデータベースレイヤはあなたのデータベースに対する単なるインターフェースでしかないということです。あなたは、他のツール、プログラミング言語、データベースフレームワークなどを通じてデータベースを操作することもできます; データベースに関して Django 特有のことは何もありません。