ルックアップAPIリファレンス
このドキュメントには、ルックアップのAPIリファレンス、データベースクエリのWHERE句を構築するためのDjangoAPIが含まれています。 ルックアップを使用する方法については、クエリの作成を参照してください。 新しいルックアップを作成する方法については、カスタムルックアップを参照してください。
ルックアップAPIには、ルックアップを登録する RegisterLookupMixin クラスと、ルックアップとして登録できるようにクラスが実装する必要のあるメソッドのセットである Query Expression API の2つのコンポーネントがあります。
Djangoには、クエリ式APIに続く2つの基本クラスがあり、そこからすべてのDjango組み込みルックアップが派生します。
ルックアップ式は、次の3つの部分で構成されます。
- フィールド部分（例：
Book.objects.filter(author__best_friends__first_name...）; - パーツを変換します（省略できます）（例：
__lower__first3chars__reversed）; - ルックアップ（例：
__icontains）。省略した場合、デフォルトで__exactになります。
登録API
Djangoは RegisterLookupMixin を使用して、クラスにルックアップを登録するためのインターフェイスを提供します。 2つの顕著な例は、すべてのモデルフィールドの基本クラスである Field と、すべてのDjangoトランスフォームの基本クラスである Transform です。
- class lookups.RegisterLookupMixin
クラスにルックアップAPIを実装するミックスイン。
- classmethod register_lookup(lookup, lookup_name=None)
クラスに新しいルックアップを登録します。 たとえば、
DateField.register_lookup(YearExact)は、DateFieldでYearExactルックアップを登録します。 同じ名前ですでに存在するルックアップをオーバーライドします。lookup_nameは、提供されている場合はこのルックアップに使用され、提供されていない場合はlookup.lookup_nameが使用されます。
- get_lookup(lookup_name)
クラスに登録されている
lookup_nameという名前の Lookup を返します。 デフォルトの実装は、すべての親クラスを再帰的に調べ、lookup_nameという名前のルックアップが登録されているかどうかを確認し、最初の一致を返します。
- get_lookups()
Lookup クラスにマップされたクラスに登録されている各ルックアップ名の辞書を返します。
- get_transform(transform_name)
transform_nameという名前の Transform を返します。 デフォルトの実装は、すべての親クラスを再帰的に調べて、transform_nameという名前の登録済み変換があるかどうかを確認し、最初の一致を返します。
クラスをルックアップにするには、クエリ式API に従う必要があります。 Lookup と Transform は当然このAPIに従います。
クエリ式API
クエリ式APIは、クラスがクエリ式で使用できるように定義するメソッドの一般的なセットであり、SQL式に変換されます。 直接フィールド参照、集計、および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（）を参照してください。
- 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()メソッドによって返されるクラスのタイプを定義します。 フィールドインスタンスである必要があります。
Transformリファレンス
- class Transform
Transformは、フィールド変換を実装するためのジェネリッククラスです。 顕著な例は、DateFieldをIntegerFieldに変換する__yearです。ルックアップ式で
Transformを使用するための表記は、<expression>__<transformation>です（例：date__year）。このクラスは、クエリ式API に従います。これは、
<expression>__<transform1>__<transform2>を使用できることを意味します。 これは、1つの引数のみを受け入れる特殊な Func（）式です。 フィルタの右側で使用することも、注釈として直接使用することもできます。- bilateral
この変換を
lhsとrhsの両方に適用する必要があるかどうかを示すブール値。 二国間変換は、ルックアップ式に表示されるのと同じ順序でrhsに適用されます。 デフォルトでは、Falseに設定されています。 使用例については、カスタムルックアップを参照してください。
- lhs
左側-変換されているもの。 クエリ式API に従う必要があります。
- lookup_name
ルックアップの名前。クエリ式の解析でルックアップを識別するために使用されます。 文字列
"__"を含めることはできません。
- output_field
この変換が出力するクラスを定義します。 フィールドインスタンスである必要があります。 デフォルトでは、
lhs.output_fieldと同じです。
Lookupリファレンス
- class Lookup
Lookupは、ルックアップを実装するためのジェネリッククラスです。 ルックアップは、左側が lhs のクエリ式です。 右側、 rhs ;lookup_name。式でルックアップを使用するための表記法は
<lhs>__<lookup_name>=<rhs>です。このクラスはクエリ式として機能しますが、構造に
=<rhs>があるため、ルックアップは常にルックアップ式の終わりである必要があります。- lhs
左側-調べているもの。 オブジェクトは、クエリ式API に従う必要があります。
- rhs
右側-
lhsが比較されているもの。 これは、プレーンな値、またはSQLにコンパイルされるもの、通常はF()オブジェクトまたはQuerySetの場合があります。
- lookup_name
このルックアップの名前。クエリ式の解析でルックアップを識別するために使用されます。 文字列
"__"を含めることはできません。
- 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（）と同じように動作します。
