エレメントクエリ
エレメントクエリを利用して、テンプレートや PHP コード内でエレメント(エントリ、カテゴリ、アセットなど)を取得できます。
エレメントクエリの働きは、3つのステップで成り立ちます。
- エレメントクエリの作成。 取得しようとしているエレメントタイプに基づく「ファクトリファンクション」を呼び出すことによって、これを行います。例えば、エントリを取得したい場合、新しいエントリクエリを返す
craft.entries()
を呼び出します。 - いくつかのパラメータをセット。 デフォルトでは、エレメントクエリは指定されたタイプのすべてのエレメントを返すように設定されています。クエリのパラメータを設定することで、エレメントを絞り込むことができます。
- クエリの実行。 クエリパラメータを指定したら、Craft がエレメントを取得して結果を得る準備ができています。複数のエレメント、または、1つだけ必要なのかに応じて
.all()
か.one()
を呼び出すことで、それを実行できます。
典型的なエレメントクエリは、次のようになります。
{# Create an entry query and set some parameters on it #}
{% set entryQuery = craft.entries()
.section('news')
.orderBy('postDate desc')
.limit(10) %}
{# Execute the query and get the results #}
{% set entries = entryQuery.all() %}
それぞれのタイプのエレメントは、エレメントクエリを作成するための独自のファンクションを持っていて、それぞれ独自のパラメータをセットできます。それらがどんな働きをするかの詳細については、個々のエレメントクエリのページを参照してください。
ほとんどのカスタムフィールドは、フィールドハンドルの名前に基づいて、エレメントクエリのパラメータもサポートしています。
# エレメントクエリの実行
クエリのパラメータを定義したら、必要とするものに応じて、それを実行するために利用可能な複数のファンクションがあります。
# all()
ほとんどの場合、照会しているエレメントの取得だけを望んでいます。all()
ファンクションでそれを実行します。
# one()
単一のエレメントだけを取得したい場合、all()
の代わりに one()
を呼び出します。エレメント、または、マッチするエレメントが存在しない場合は null
のいずれかを返します。
# exists()
エレメントクエリにマッチするいずれかのエレメントが存在するかを確認したい場合、true
または false
を返す、exists()
を呼び出します。
# count()
エレメントクエリにマッチするエレメントの数を知りたい場合、count()
を呼び出します。
count()
を呼び出す際、limit
および offset
パラメータは無視されます。
# ids()
マッチするエレメント ID のリストが必要な場合、ids()
を呼び出します。
# 高度なエレメントクエリ
エレメントクエリは、専門的なクエリビルダー (opens new window)です。そのため、craft\db\Query (opens new window) によって提供されるものとほとんど同じメソッドをサポートしています。
# 選択
- select() (opens new window)
- addSelect() (opens new window)
- distinct() (opens new window)
- groupBy() (opens new window)
# 結合
# 条件
- where() (opens new window)
- andWhere() (opens new window)
- orWhere() (opens new window)
- filterWhere() (opens new window)
- andFilterWhere() (opens new window)
- orFilterWhere() (opens new window)
# クエリの実行
- all() (opens new window)
- one() (opens new window)
- nth() (opens new window)
- exists() (opens new window)
- count() (opens new window)
- column() (opens new window)
- scalar() (opens new window)
- sum() (opens new window)
- average() (opens new window)
- min() (opens new window)
- max() (opens new window)
エレメントクエリをカスタマイズする際、getRawSql() (opens new window) を呼び出すことで、クエリによって実行される完全な SQL を取得できます。そのため、何を修正すればよいかの良いアイデアを得られるでしょう。
{{ dump(query.getRawSql()) }}