エレメントクエリ

エレメントクエリを利用して、テンプレートや PHP コード内でエレメント（エントリ、カテゴリ、アセットなど）を取得できます。

エレメントクエリの働きは、3つのステップで成り立ちます。

エレメントクエリの作成。 取得しようとしているエレメントタイプに基づく「ファクトリファンクション」を呼び出すことによって、これを行います。例えば、エントリを取得したい場合、新しいエントリクエリを返す craft.entries() を呼び出します。
いくつかのパラメータをセット。 デフォルトでは、エレメントクエリは指定されたタイプのすべてのエレメントを返すように設定されています。クエリのパラメータを設定することで、エレメントを絞り込むことができます。
クエリの実行。 クエリパラメータを指定したら、Craft がエレメントを取得して結果を得る準備ができています。複数のエレメント、または、1つだけ必要なのかに応じて .all() か .one() を呼び出すことで、それを実行できます。

典型的なエレメントクエリは、次のようになります。

Twig
PHP

{# 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() ファンクションでそれを実行します。

Twig
PHP

{% set entries = craft.entries()
    .section('news')
    .limit(10)
    .all() %}

# `one()`

単一のエレメントだけを取得したい場合、all() の代わりに one() を呼び出します。エレメント、または、マッチするエレメントが存在しない場合は null のいずれかを返します。

Twig
PHP

{% set entry = craft.entries()
    .section('news')
    .slug('hello-world')
    .one() %}

# `exists()`

エレメントクエリにマッチするいずれかのエレメントが存在するかを確認したい場合、true または false を返す、exists() を呼び出します。

Twig
PHP

{% set exists = craft.entries()
    .section('news')
    .slug('hello-world')
    .exists() %}

# `count()`

エレメントクエリにマッチするエレメントの数を知りたい場合、count() を呼び出します。

Twig
PHP

{% set count = craft.entries()
    .section('news')
    .count() %}

count() を呼び出す際、limit および offset パラメータは無視されます。

# `ids()`

マッチするエレメント ID のリストが必要な場合、ids() を呼び出します。

Twig
PHP

{% set entryIds = craft.entries()
    .section('news')
    .ids() %}

# 高度なエレメントクエリ

エレメントクエリは、専門的なクエリビルダー (opens new window)です。そのため、craft\db\Query (opens new window) によって提供されるものとほとんど同じメソッドをサポートしています。

# 選択

# 結合

# 条件

# クエリの実行

エレメントクエリをカスタマイズする際、getRawSql() (opens new window) を呼び出すことで、クエリによって実行される完全な SQL を取得できます。そのため、何を修正すればよいかの良いアイデアを得られるでしょう。

{{ dump(query.getRawSql()) }}

← 画像変換エレメントの Eager-Loading →

エレメントクエリ

# エレメントクエリの実行

# all()

# one()

# exists()

# count()

# ids()

# 高度なエレメントクエリ

# 選択

# 結合

# 条件

# クエリの実行

Was this page helpful?

# `all()`

# `one()`

# `exists()`

# `count()`

# `ids()`