ForeignKey や ManyToManyField の保存¶

ForeignKey フィールドの更新は、通常のフィールドへの変更と同じです。すな わち、適切な型のオブジェクトを代入して保存すると、フィールドの値を更新でき ます:

>>> cheese_blog = Blog.objects.get(name="Cheddar Talk")
>>> entry.blog = cheese_blog
>>> entry.save()

ManyToManyField の更新は少し違います。リレーションにレコードを一つ追加 したい場合は add() メソッドを使います:

>> joe = Author.objects.create(name="Joe")
>> entry.authors.add(joe)

間違った型のオブジェクトを外部キーに代入したり add() したりすると Django はエラーを出します。

全てのオブジェクトの取得¶

テーブルからオブジェクトを取得する最も単純な方法は全てのオブジェクトを取得 するというものです。全オブジェクトを取得するには、マネジャの all() メソッ ドを使って下さい:

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

all() メソッドはデータベース上の全てのオブジェクトを表現するクエリセッ トを返します。

(Entry.objects がクエリセットを返すというのなら、なぜ単に Entry.objects と書かないのでしょうか？それは、ルートのクエリセットであ る Entry.objects が特別扱いされていて、値評価できないようになっているか らです。 all() メソッドは、値評価 できる クエリセットを返します。

フィルタを使ってオブジェクトを取り出す¶

マネジャによって提供される、いわゆるルートクエリセットを使えば、データベー ステーブル上の全てのオブジェクトを表せます。とはいえ、通常は全オブジェクト の集合からサブセットだけを取り出したいことでしょう。

サブセットを作成するには、フィルタ条件を追加して、初期クエリセットをリファ インする必要があります。クエリセットの洗練には、主に二つの方法があります:

filter(**kwargs)

指定した照合パラメタに一致するオブジェクトの集合を表現する、新たな クエリセットを返します。

exclude(**kwargs)

指定した照合パラメタに一致 しない オブジェクトの集合を表現する、 新たなクエリセットを返します。

照合パラメタ (上の関数定義における **kwargs) は、後述の フィールドの照合 で解説するフォーマットにせねばなりません。

例えば、 2006 年のブログエントリを表すクエリセットを取得するには、以下のよ うに filter() を使います:

Entry.objects.filter(pub_date__year=2006)

(Entry.objects.all().filter(...) のように、 all() を使わなくてもよ いことに注意して下さい。 all() を使っても問題なく動作しますが、 all() が必要となるのはルートクエリセットから全てのオブジェクトを取り出 したい場合だけです。)

>>> Entry.objects.filter(
...     headline__startswith='What'
... ).exclude(
...     pub_date__gte=datetime.now()
... ).filter(
...     pub_date__gte=datetime(2005, 1, 1)
... )

>> q1 = Entry.objects.filter(headline__startswith="What")
>> q2 = q1.exclude(pub_date__gte=datetime.now())
>> q3 = q1.filter(pub_date__gte=datetime.now())

>>> q = Entry.objects.filter(headline__startswith="What")
>>> q = q.filter(pub_date__lte=datetime.now())
>>> q = q.exclude(body_text__icontains="food")
>>> print q

クエリセットに制約を課す¶

クエリセットの返す結果を特定の個数に制限したい場合には、 Python の配列スラ イス表記を使います。これは SQL の LIMIT 節や OFFSET 節と等価です。

以下の例は、最初の 5 オブジェクトだけを返します (LIMIT 5 に相当します):

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

以下の例は、 6 番目から 10 番目までのオブジェクトを返します (OFFSET 5 LIMIT 5 に相当します):

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

一般に、クエリセットをスライスしてもクエリセットを新たに生成して返すだけで、 クエリの評価は行いません。例外はスライス表記に「ステップ (step)」パラメタを 使ったときです。以下の例では、クエリを実際に実行し、最初の 10 オブジェクト 中から 1 つおきにオブジェクトを取り出したリストを返します:

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

リストではなく 単一の オブジェクトを取得したい場合 (SELECT foo FROM bar LIMIT 1 のような場合) には、スライスではなく単純な インデクス指定を行います。以下の例はデータベースのエントリをヘッドラインに ついてアルファベット順に整列した後、最初の Entry を取得して返します:

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

これはだいたい以下と同じになります:

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

ただし、指定条件にマッチするオブジェクトがない場合、前者は IndexError, 後者は DoesNotExist を送出します。詳しくは get() のドキュメントを参 照してください。

フィールドの照合¶

フィールドの照合操作によって、 SQL の WHERE 節の中身が決まります。フィー ルドの照合を行うには、 filter(), exclude() および get() といっ たクエリセットのメソッドのキーワード引数を指定します。

基本的に、照合のキーワード引数名は field__lookuptype=value のような形 式をとります (アンダースコアは二重です)。例えば:

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

は、(大雑把にいって) 以下のような SQL 文に変換されます:

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

照合時に無効なキーワード引数が渡されると、 TypeError が送出されます。

データベース API は 2 ダース近くの照合タイプをサポートしています。詳しいリ ファレンスは フィールド照合リファレンス を参照してく ださい。ここでは、よく使う照合タイプをいくつか示します:

exact

「厳密一致」です。例えば:

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

は、以下のような SQL を生成します:

SELECT ... WHERE headline = 'Man bits dog';

照合タイプを指定しなかった場合、つまり二重アンダースコアの入ったキー ワード引数を使わないかぎり、照合条件は exact とみなされます。

例えば、以下の二つの文は同じ意味です:

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

exact はよく使われるため、便宜的にこのような仕様にしています。

iexact

大小文字を区別しない一致です。以下のクエリ:

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

は、 "Beatles Blog", "beatles blog", "BeAtlES blOG" といったタイト ルの Blog オブジェクトにマッチします。

contains

大小文字を区別する部分一致テストです。以下のクエリ:

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

は、おおざっぱにいって以下の SQL に変換されます:

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

'Today Lennon honored' には一致しますが、 'today lennon honored' には一致しないので注意してください。

大小文字を区別しない icontains もあります。

startswith, endswith

それぞれ、前方一致と後方一致です。大小文字を区別しない istartswith や iendswith もあります。

ここに挙げたのはほんの一部です。全ての照合タイプの解説は フィールド照合タイプのリファレンス を参照してくださ い。

リレーションをまたいだ照合¶

Django では、背後で自動的に SQL JOIN を処理し、照合の際にリレーションを 「追跡」する、強力でありながら直感的な手段を提供しています。リレーションを またぐには、二重アンダースコアを使ってリレーションの張られたフィールドのフィー ルド名を指定します。リレーション間のスパンは、目的のフィールドに到達するま でいくらでも連鎖させられます。

以下の例では、 name が 'Beatles Blog' であるような Blog の Entry エントリオブジェクト全てを取得します:

>>> Entry.objects.filter(blog__name__exact='Beatles Blog')

スパンは好きなだけ深く張れます。

リレーションのスパンは逆方向にも張れます。「逆方向の」リレーションを参照す るには、モデル名を小文字にした名前を使います。

以下の例では、 headline に 'Lennon' を含むような Entry を少なく とも一つ持つような全ての Blog オブジェクトを取得します:

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

複数のリレーションをまたいでフィルタを行っていて、中間のモデルにフィルタ条 件に合致する値が存在しないと、 Django はその値が空である (NULL が入って いる) だけの有意なオブジェクトとして扱います。つまり、エラーを送出しません。 例えば、以下のフィルタを考えましょう:

Blog.objects.filter(entry__author__name='Lennon')

(Author モデルは存在するものとします) entry の author を空にし ていると、 Django は author が存在しないために name を辿れませんが、 エラーは送出せず、あたかも name も空であるかのように扱います。たいてい は、この仕様で期待通りに動きますが、 isnull を使うと、少し混乱をきたし ます。すなわち:

Blog.objects.filter(entry__author__name__isnull=True)

は、 author の name が空の Blog だけでなく、 entry の author が空の Blog も返してしまうのです。後者のオブジェクトを返して 欲しくないのなら、以下のように書いてください:

Blog.objetcs.filter(entry__author__isnull=False,
        entry__author__name__isnull=True)

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

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

pk 照合ショートカット¶

利便性のために、 Django には pk という照合形式があります。 pk は primary_key を表します。

Blog モデルの例では、主キーは id フィールドなので、以下の二つの文は 等価です:

>>> Blog.objects.get(id__exact=14) # 明示的な形式
>>> Blog.objects.get(id=14) # 暗黙で __exact を表す
>>> Blog.objects.get(pk=14) # pk は暗黙で id__exact を表す

pk は __exact のクエリにしか使えないわけではありません。どのクエリ 用キーワードも pk と組み合わせてかまいません。 pk を使うと、モデル の主キーに対するクエリを表します:

# id が 1, 4 および 7 のブログエントリを取得する
>>> Blog.objects.filter(pk__in=[1,4,7])

# id > 14 の全てのブログエントリを取得する
>>> Blog.objects.filter(pk__gt=14)

pk による検索は join 越しでも行えます。 例えば、以下の二つの文は等価で す:

>>> Entry.objects.filter(blog__id__exact=3) # 明示的な形式
>>> Entry.objects.filter(blog__id=3)        # 暗黙で __exact を表す
>>> Entry.objects.filter(blog__pk=3)        # __pk は暗黙で __id__exact を表す

LIKE 文におけるパーセント記号とアンダースコアのエスケープ¶

LIKE を使う SQL 文になるようなフィールド照合メソッド (iexact, contains, icontains, startswith, istartswith, endswith, iendswith) では、 LIKE 文で使われる二つの特殊な文字、すなわちパーセ ント記号とアンダースコアを自動的にエスケープします。 (LIKE 文では、パー セント記号は任意の複数文字に対するワイルドカードを表し、アンダースコアは任 意の一文字に対するワイルドカードを表します。)

この機能によって、照合操作を直感的に行え、データベースの抽象化を守れます。 例えば、パーセント記号を含むようなエントリ全てを取得したければ、以下のよう にパーセント記号をそのまま使います:

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

Django はクオートの処理に気を配ってくれます。 SQL は以下のような感じになり ます:

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

アンダースコアについても同じようなエスケープを行います。パーセント記号とア ンダースコアはいずれも透過的に処理されます。

キャッシュとクエリセット¶

データベースへのアクセスを最小限にとどめるため、クエリセット各々にはキャッ シュがあります。効率的なコードを書く上で、キャッシュのからくりを理解してお くのは重要なことです。

クエリセットが新たに生成された時点では、キャッシュは空です。クエリセットを 最初に評価したとき (すなわち、データベースへのクエリが最初に生じたとき)、 Django はクエリ結果をクエリセットオブジェクト内のキャッシュに保存し、明示的 にリクエストした結果だけ (例えば、クエリセットに対してイテレーション操作を する場合には、結果セットの最初の要素) を返します。それ以後は、クエリセット を際利用するとキャッシュ済みの結果を返します。

このキャッシュの挙動をよく覚えておいて下さい。というのも、クエリセットを正 しく扱わないと、おもわぬところで手を噛まれるはめになるからです。例えば、以 下の例では二つのクエリセットを作成し、値を評価して、すぐにクエリセットを捨 ててしまっています:

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

そのため、全く同じデータベースクエリを二度実行し、データベースの負荷を倍加 させています。また、 Entry は二つのリクエストを処理する間にも追加された り削除されたりする可能性があるため、二つのリストには必ずしも同じデータベー スレコードが入っているとは限りません。

こうした問題を避けるには、クエリセットを保存して再利用してください:

>>> queryset = Poll.objects.all()
>>> print [p.headline for p in queryset] # クエリセットを評価します。
>>> print [p.pub_date for p in queryset] # キャッシュの値を再利用します。

一対多のリレーション¶

>>> e = Entry.objects.get(id=2)
>>> e.blog # リレーション先の Blog オブジェクトを返します。

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

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

>>> e = Entry.objects.get(id=2)
>>> print e.blog  # データベースを検索して、関連づけられた Blog を返します。
>>> print e.blog  # データベースは検索せず、キャッシュを使います。

>>> e = Entry.objects.select_related().get(id=2)
>>> print e.blog  # Doesn't hit the database; uses cached version.
>>> print e.blog  # Doesn't hit the database; uses cached version.

>>> b = Blog.objects.get(id=1)
>>> b.entry_set.all() # Blog に関連づけられた全ての Entry を返します。

# b.entry_set はクエリセットを返すマネジャです。
>>> b.entry_set.filter(headline__contains='Lennon')
>>> b.entry_set.count()

>>> b = Blog.objects.get(id=1)
>>> b.entries.all() # Blog に関連づけられた全ての Entry を返します。

# b.entries はクエリセットを返すマネジャです。
>>> b.entries.filter(headline__contains='Lennon')
>>> b.entries.count()

>>> Blog.entry_set
Traceback:
    ...
AttributeError: "Manager must be accessed via instance".

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

多対多のリレーション¶

多対多のリレーションの場合、リレーションの関係にあるモデルの一方は、互いに もう一方にアクセスするための自動 API を獲得します。この API は一対多のリレー ションにおける「逆方向の」参照のように動作します。

一対多のリレーションとの唯一の違いは、属性の名前づけ規則です。 ManyToManyField を定義した側のモデルはフィールド名をそのまま使いますが、 「反対側の」モデルでは、相手のモデルのモデル名を小文字にして、 '_set' を追加したもの (一対多のリレーションにおける逆方向の参照と同じ) になります。

例を使って説明した方が理解しやすいでしょう:

e = Entry.objects.get(id=3)
e.authors.all() # Entry の全ての Author オブジェクトを返します。
e.authors.count()
e.authors.filter(name__contains='John')

a = Author.objects.get(id=5)
a.entry_set.all() # Author の全ての Entry オブジェクトを返します。

ForeignKey と同様、 ManyToManyField には related_name パラメタ を指定できます。 上の例で、 Entry の ManyToManyField に related_name='entries' を指定していた場合、 Author インスタンスは entry_set ではなく entries という属性を持つようになります。

一対一のリレーション¶

一対一 (one-to-one) のリレーションは多対多のリレーションと非常によく似てい ます。モデルに OneToOneField を定義すると、モデ ルのインスタンスはリレーション先のオブジェクトを簡単な属性アクセスで参照で きます。

例を示します:

class EntryDetail(models.Model):
    entry = models.OneToOneField(Entry)
    details = models.TextField()

ed = EntryDetail.objects.get(id=2)
ed.entry # リレーション先の Entry オブジェクトを返します。

多対多との違いは、逆参照のクエリです。多対多の時と同様、リレーション先のモ デルはリレーション元のモデルに対するマネジャオブジェクトにアクセスできます が、このマネジャはオブジェクトの集合ではなく単一のオブジェクトを表現してい ます:

e = Entry.objects.get(id=2)
e.entrydetail # リレーション先の EntryDetail オブジェクトを返します。

逆リレーション先のオブジェクトが存在しなければ、 Django は DoesNotExist 例外を送出します。

逆参照のリレーションにインスタンスを代入すると、順参照のリレーションと同じ ようにリレーション先を変更できます:

e.entrydetail = ed

リレーションの後方参照はどうやって実現されているのか¶

他のオブジェクトリレーショナルマッパでは、双方向からリレーションを定義せね ばなりません。 Django の開発者たちはこれを DRY 則 (Don't Repeat Yourself) の侵犯だと考えたため、 Django では片方だけでリレーションを定義すればよいよ うにしています。

しかし、なぜあるモデルクラスが、自分に対してリレーションを張っているモデル クラスのことを、そのクラスがロードされる前に検知できるのでしょうか？

答えは INSTALLED_APPS 設定にあります。最初にモデルをロードした時 に、 Django は INSTALLED_APPS の全てのモデルを走査して、必要に応 じて後方参照をメモリ中に作成します。 INSTALLED_APPS の本質的な機 能の一つは、 Django にモデルドメインの全体像を知らせることなのです。

リレーション先オブジェクトを使ったクエリ¶

リレーション先のオブジェクトを照合条件に含むクエリは、通常の値のフィールド の入ったクエリと同じような規則に従います。クエリにマッチ条件として値を指定 する場合、オブジェクトのインスタンス自体か、オブジェクトの主キー値のいずれ かを使えます。

例えば、 id=5 であるようなBlog オブジェクト b に対しては、以下の三 つのクエリはすべて等価です:

Entry.objects.filter(blog=b) # オブジェクトインスタンスを使ったクエリ
Entry.objects.filter(blog=b.id) # インスタンスの id を使ったクエリ
Entry.objects.filter(blog=5) # id を直接使ったクエリ