---
title: "ルックアップ API リファレンス"
version: 6.0
locale: ja
source: https://docs.djangoproject.com/ja/6.0/ref/models/lookups/
canonical: https://djangodocs.dev/ja/6.0/ref/models/lookups/
---
# ルックアップ API リファレンス

このドキュメントには、データベースクエリの `WHERE` 句を構築するための Django API であるルックアップの API リファレンスがあります。ルックアップの *使い方* については [クエリを作成する](/ja/6.0/topics/db/queries/) を、新しいルックアップの *作り方* については [カスタムのルックアップを書く](/ja/6.0/howto/custom-lookups/) を参照してください。

ルックアップAPIには2つのコンポーネントがあります。ルックアップを登録する [`RegisterLookupMixin`](#django.db.models.lookups.RegisterLookupMixin) クラスと、ルックアップとして登録するためにクラスが実装しなければならないメソッドのセットである [クエリ式 API](#query-expression) です。

Django には、クエリ式 API に従う 2 つの基本クラスがあり、すべての Django 組み込みルックアップはここから派生しています:

- [`Lookup`](#django.db.models.Lookup): フィールドをルックアップします (例えば `field_name__exact` の `exact`)
- [`Transform`](#django.db.models.Transform): フィールドをトランスフォーム（変換）します。

ルックアップ式は3つの部分で構成されています:

- フィールド部分（例: `Book.objects.filter(author__best_friends__first_name...` ）;
- トランスフォーム（変換）部分（省略可） (`lower__first3chars__reversed` など);
- ルックアップ部分 (`__icontains` など)。省略した場合のデフォルトは `__exact` です。

## 登録API

Django は [`RegisterLookupMixin`](#django.db.models.lookups.RegisterLookupMixin) を使って、自分自身やそのインスタンスにルックアップを登録するインターフェイスをクラスに与えます。代表的な例は [`Field`](/ja/6.0/ref/models/fields/#django.db.models.Field) で、これはすべてのモデルフィールドの基底クラスです。 [`Transform`](#django.db.models.Transform) もその一つで、これはすべての Django トランスフォームの基底クラスです。

#### `class lookups.RegisterLookupMixin`

クラスのルックアップ API を実装するミックスインです。

#### `classmethod register_lookup(lookup, lookup_name=None)`

クラスまたはクラスのインスタンスに新しいルックアップを登録します。たとえば、次のようにします:

```
DateField.register_lookup(YearExact)
User._meta.get_field("date_joined").register_lookup(MonthExact)
```

このコードは `DateField` の `YearExact` ルックアップと `User.date_joined` の `MonthExact` ルックアップを登録します（ [フィールドアクセス API](/ja/6.0/ref/models/meta/#model-meta-field-api) を使用して単一のフィールドインスタンスを取得できます）。このルックアップは既に存在する同じ名前のルックアップを上書きします。フィールドインスタンスに登録されたルックアップはクラスに登録されたルックアップよりも優先されます。 `lookup.lookup_name` が指定された場合は `lookup_name` が使用され、指定されなかった場合は `lookup.lookup_name` が使用されます。

#### `get_lookup(lookup_name)`

クラスまたはクラスインスタンスに登録されている `lookup_name` という名前の [`Lookup`](#django.db.models.Lookup) を、呼び出しに応じて返します。デフォルトの実装では、全ての親クラスを再帰的にルックアップし、 `lookup_name` という名前のルックアップが登録されているかどうかをチェックし、最初にマッチしたものを返します。インスタンスのルックアップは同じ `Lookup_name` を持つクラスのルックアップを上書きします。

#### `get_lookups()`

[`Lookup`](#django.db.models.Lookup) クラスにマップされたクラスまたはクラスインスタンスに登録されているルックアップ名の辞書を返します。

#### `get_transform(transform_name)`

クラスまたはクラスインスタンスに登録されている `transform_name` という [`Transform`](#django.db.models.Transform) を返します。デフォルトの実装では、すべての親クラスを再帰的に検索し、 `transform_name` という名前のトランスフォームが登録されているかどうかを調べ、最初にマッチしたものを返します。

クラスがルックアップであるためには、 [クエリ式 API](#query-expression) に従わなければなりません。 [`Lookup`](#django.db.models.Lookup) と [`Transform`](#django.db.models.Transform) は当然この API に従います。

## クエリ式 API

クエリ式 API はクラスがクエリ式で使用できるように定義するメソッドの共通セットで、クラス自身を SQL 式に変換します。フィールドの直接参照、集計（Aggregation）、 `Transform` はこのAPIに従う例です。あるクラスが以下のメソッドを実装している場合、そのクラスはクエリ式APIに従っていると言えます:

#### `as_sql(compiler, connection)`

式の SQL フラグメントを生成します。タプル `(sql, params)` を返します。`sql` は SQL 文字列で、`params` はクエリパラメータのリストまたはタプルです。 `compiler` は `SQLCompiler` オブジェクトで、他の式をコンパイルするための `compile()` メソッドを持っています。 `connection` はクエリの実行に使用する接続です。

`expression.as_sql()` の呼び出しは通常正しくありません。 代わりに `compiler.compile(expression)` を使用する必要があります。 `compiler.compile()` メソッドは式のベンダ固有のメソッドの呼び出しを行います。

`as_vendorname()` メソッドやサブクラスがSQL文字列の生成を上書きするためにデータを提供する必要がありそうな場合は、このメソッドにカスタムキーワード引数を定義できます。たとえば、 [`Func.as_sql()`](/ja/6.0/ref/models/expressions/#django.db.models.Func.as_sql) を参照してください。

#### `as_vendorname(compiler, connection)`

`as_sql()` メソッドと同じように動作します。式が `compiler.compile()` によってコンパイルされると、Django はまず `as_vendorname()` を呼び出そうとします。ここで `vendorname` はクエリを実行するバックエンドのベンダ名です。 `vendorname` は Django の組み込みバックエンドでは `postgresql` 、 `oracle` 、 `sqlite` 、 `mysql` のいずれかです。

#### `get_lookup(lookup_name)`

ルックアップ名 `lookup_name` を返さなければなりません。インスタンスンスでは `self.output_field.get_lookup(lookup_name)` を返します。

#### `get_transform(transform_name)`

ルックアップ名 `transform_name` を返さなければなりません。インスタンスンスでは `self.output_field.get_transform(transform_name)` を返します。

#### `output_field`

`get_lookup()` メソッドが返すクラスの型を定義します。これは [`Field`](/ja/6.0/ref/models/fields/#django.db.models.Field) インスタンスでなければなりません。

## `Transform` リファレンス

#### `class Transform`

`Transform` はフィールドの変換を実装するための汎用クラスです。主な例は `DateField` を `IntegerField` に変換する `__year` です。

ルックアップ式で `Transform` を使用する場合の表記は `<expression>__<transformation>` (例 `date__year`) です。

This class follows the [Query Expression API](#query-expression),
which implies that you can use
`<expression>__<transform1>__<transform2>`. It's a specialized
[Func() expression](/ja/6.0/ref/models/expressions/#func-expressions) that only accepts one argument.
It can also be used on the right hand side of a filter or directly as an
annotation.

#### `bilateral`

このトランスフォームを `lhs` と `rhs` の両方に適用するかどうかを示すブール値です。両者の変換は `rhs` に対して、ルックアップ式に現れる順番で適用されます。デフォルトでは `False` に設定されています。たとえば、 [カスタムのルックアップを書く](/ja/6.0/howto/custom-lookups/) を参照してください。

#### `lhs`

左辺 - 変換されるもの。これは [クエリ式API](#query-expression) に従わなければなりません。

#### `lookup_name`

クエリ式のパース時に使用するルックアップ名です。文字列 `"__"` を含むことはできません。

#### `output_field`

このトランスフォームが出力するクラスを定義します。これは [`Field`](/ja/6.0/ref/models/fields/#django.db.models.Field) インスタンスでなければなりません。デフォルトでは `lhs.output_field` と同じです。

## `Lookup` リファレンス

#### `class Lookup`

ルックアップ `Lookup` はルックアップを実装するための汎用クラスです。ルックアップは左辺 [`lhs`](#django.db.models.Lookup.lhs); 右辺 [`rhs`](#django.db.models.Lookup.rhs); `lookup_name` を持つクエリ式で、 `lhs in rhs` や `lhs > rhs` のように `lhs` と `rhs` をブール値で比較します。

式の中でルックアップを使用するための主な記法は `<lhs>__<lookup_name>=<rhs>` です。ルックアップは下記のように `QuerySet` フィルタの中で直接使うこともできます:

```
Book.objects.filter(LessThan(F("word_count"), 7500))
```

...下記のように、アノテーションでも使用できます:

```
Book.objects.annotate(is_short_story=LessThan(F("word_count"), 7500))
```

#### `lhs`

左辺 - ルックアップされる対象。オブジェクトは通常 [クエリ式API](#query-expression) に従います。プレーンな値の場合もあります。

#### `rhs`

右辺 - `lhs` と比較されるもの。これは単なる値であったり、SQL にコンパイルされるものであったり、一般的には `F()` オブジェクトや `QuerySet` であったりします。

#### `lookup_name`

このルックアップの名前で、クエリ式をパースする際に識別するために使用します。文字列 `"__"` を含むことはできません。

#### `prepare_rhs`

デフォルトは `True` です。 [`rhs`](#django.db.models.Lookup.rhs) がプレーンな値の場合、 [`prepare_rhs`](#django.db.models.Lookup.prepare_rhs) はクエリのパラメータとして使用するために、その値を準備するかどうかを決定します。そのために、 `lhs.output_field.get_prep_value()` が定義されていれば呼び出され、そうでなければ `rhs` は [`Value()`](/ja/6.0/ref/models/expressions/#django.db.models.Value) でラップされます。

#### `process_lhs(compiler, connection, lhs=None)`

`compiler.compile(lhs)` が返すタプル `(lhs_string, lhs_params)` を返します。このメソッドをオーバーライドすることで、 `lhs` の処理方法を調整できます。

`compiler` は `SQLCompiler` オブジェクトで、 `lhs` をコンパイルする際に `compiler.compile(lhs)` のように使用します。 `connection` はベンダ固有の SQL をコンパイルする際に使用します。 `lhs` が `None` でない場合は、 `self.lhs` の代わりに `lhs` を使用します。

#### `process_rhs(compiler, connection)`

右辺については [`process_lhs()`](#django.db.models.Lookup.process_lhs) と同じように扱います。