Doctrine Query Language (DQL)は複雑なオブジェクト読み取りを手助けするためのObject Query Languageです。リレーショナルデータを効率的に読み取るときに(例えばユーザーと電話番号を取得するとき)DQL(もしくは生のSQL)を使うことを常に考えるべきです。

この章ではDoctrine Query Languageの使い方の例をたくさん実演します。これらすべての例ではDefining Modelsの章で定義したスキーマを使うことを想定します。またテスト用に1つの追加モデルを定義します。

// models/Account.php

class Account extends Doctrine_Record
{
    public function setTableDefinition()
    {
        $this->hasColumn('name', 'string', 255);
        $this->hasColumn('amount', 'decimal');
    }
}

YAMLフォーマットでの同じ例は次の通りです。YAML Schema Filesの章でYAMLの詳細を読むことができます:

---
# schema.yml

# ...
Account:
  columns:
    name: string(255)
    amount: decimal

生のSQLを使う場合と比較すると、DQLは次の恩恵があります:

• 始めから結果セットの列ではなくレコード(オブジェクト)の読み取りのために設計されている
• DQLはリレーションを理解するのでSQLのjoinとjoinの条件を手動で入力する必要がない
• DQLは異なるデータベースでポータブルである
• DQLはレコード制限などとても複雑なアルゴリズムが組み込まれておりこれは開発者がオブジェクトを効率的に読み取るのを手助けする
• 条件付きの取得で一対多、多対多のリレーショナルデータを扱うときに時間を節約できる機能をサポートする

DQLの力が十分でなければ、オブジェクト投入に対してRawSql APIを使うことを考えるべきです。

既に次の構文に慣れている方もいらっしゃるでしょうx:

次のコードは決して使わないでください。 これはオブジェクト投入用に多くのSQLクエリを使います。

// test.php

// ...
$users = Doctrine_Core::getTable('User')->findAll();

foreach($users as $user) {
    echo $user->username . " has phonenumbers: \n";

    foreach($user->Phonenumbers as $phonenumber) {
        echo $phonenumber->phonenumber . "\n";
    }
}

上記と同じ内容ですがオブジェクト投入のために1つのSQLクエリのみを使うより効率的な実装です。

// test.php

// ...
$q = Doctrine_Query::create()
    ->from('User u')
    ->leftJoin('u.Phonenumbers p');

echo $q->getSqlQuery();

上記のクエリによって生成されるSQLを見てみましょう:

SELECT 
u.id AS u__id, 
u.is_active AS u__is_active, 
u.is_super_admin AS u__is_super_admin, 
u.first_name AS u__first_name, 
u.last_name AS u__last_name, 
u.username AS u__username, 
u.password AS u__password, 
u.type AS u__type, 
u.created_at AS u__created_at, 
u.updated_at AS u__updated_at, 
p.id AS p__id, 
p.user_id AS p__user_id, 
p.phonenumber AS p__phonenumber 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id

クエリを実行してデータで遊んでみましょう:

// test.php

// ...
$users = $q->execute();

foreach($users as $user) {
    echo $user->username . " has phonenumbers: \n";

    foreach($user->Phonenumbers as $phonenumber) {
        echo $phonenumber->phonenumber . "\n";
    }
}

DQLの文字列で二重引用符(")を使うのは非推奨です。これはMySQLの標準では使えますがDQLにおいて識別子と混同される可能性があります。代わりに値に対してプリペアードステートメントを使うことが推奨されます。これによって適切にエスケープされます。

SELECT文の構文:

SELECT
    [ALL | DISTINCT]
    <select_expr>, 
...
    [
FROM <components>
    [
WHERE <where_condition>]
    [
GROUP BY <groupby_expr>
      [ASC | DESC], 
... ]
    [
HAVING <where_condition>]
    [
ORDER BY <orderby_expr>
      [ASC | DESC], 
...]
    [
LIMIT <row_count> 
OFF
SET <offset>}]

SELECT文は1つもしくは複数のコンポーネントからデータを読み取るために使われます。
　
それぞれのselect_exprは読み取りたいカラムもしくは集約関数の値を示します。
すべてのSELECT文で少なくとも1つのselect_exprがなければなりません。

最初にサンプルのAccountレコードをinsertします:

// test.php

// ...
$account = new Account();
$account->name = 'test 1';
$account->amount = '100.00';
$account->save();

$account = new Account();
$account->name = 'test 2';
$account->amount = '200.00';
$account->save();

test.phpを実行します:

$ php test.php

次のサンプルクエリでデータのselectをテストできます:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('a.name')
    ->from('Account a');

echo $q->getSqlQuery();

上記のクエリによって生成されたSQLを見てみましょう:

SELECT 
a.id AS a__id, 
a.name AS a__name 
FROM account a

// test.php

// ...
$accounts = $q->execute();
print_r($accounts->toArray());

上記の例では次の出力が生み出されます:

$ php test.php
Array
(
    [0] => Array
        (
            [id] => 1
            [name] => test 1
            [amount] =>
        )

    [1] => Array
        (
            [id] => 2
            [name] => test 2
            [amount] =>
        )

)

アスタリスクは任意のコンポーネントからすべてのカラムをselectするために使われます。アスタリスクを使うときでも実行されるSQLクエリは実際にはそれを使いません(Doctrineはアスタリスクを適切なカラムの名前に変換することで、データベースでのパフォーマンスの向上につながります)。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('a.*')
    ->from('Account a');

echo $q->getSqlQuery();

最後のクエリの例から生成されたSQLとすぐ前に生成されたクエリで生成されたSQLを比較します:

SELECT 
a.id AS a__id, 
a.name AS a__name, 
a.amount AS a__amount 
FROM account a

アスタリスクはAccountモデルに存在する実際のすべてのカラム名に置き換えられることに留意してください。

クエリを実行して結果を検査してみましょう:

// test.php

// ...
$accounts = $q->execute();
print_r($accounts->toArray());

上記の例は次の出力を生み出します:

$ php test.php
Array
(
    [0] => Array
        (
            [id] => 1
            [name] => test 1
            [amount] => 100.00
        )

    [1] => Array
        (
            [id] => 2
            [name] => test 2
            [amount] => 200.00
        )

)

FROM句はレコードから読み取るコンポーネントを示します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username, p.*')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p')

echo $q->getSqlQuery();

getSql()への上記の呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
u.username AS u__username, 
p.id AS p__id, 
p.user_id AS p__user_id, 
p.phonenumber AS p__phonenumber 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id

WHERE句は、選択されるためにレコードが満たさなければならない条件を示します。where_conditionは選択されるそれぞれの列に対してtrueに表示する式です。WHERE句が存在しない場合ステートメントはすべての列を選択します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('a.name')
    ->from('Account a')
    ->where('a.amount > 2000');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
a.id AS a__id, 
a.name AS a__name 
FROM account a 
WHERE a.amount > 2000

WHERE句において、集約(要約)関数を除いて、DQLがサポートする任意の関数と演算子を使うことができます。HAVING句は集約関数で結果を絞るために使うことができます:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p')
    ->having('COUNT(p.id) > 3');

echo $q->getSqlQuery();

getSql()を呼び出すと次のSQLクエリが出力されます:

SELECT 
u.id AS u__id, 
u.username AS u__username 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id 
HAVING COUNT(p.id) > 3

ORDER BY句は結果のソートに使われます。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username')
    ->from('User u')
    ->orderBy('u.username');

echo $q->getSqlQuery();

上記のgetSql()を呼び出すと次のSQLクエリが出力されます:

SELECT 
u.id AS u__id, 
u.username AS u__username 
FROM user u 
ORDER BY u.username

LIMITとOFFSET句はレコードの数をrow_countに効率的に制限するために使われます。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username')
    ->from('User u')
    ->limit(20);

echo $q->getSqlQuery();

上記のgetSql()を呼び出すと次のSQLクエリが出力されます:

SELECT 
u.id AS u__id, 
u.username AS u__username 
FROM user u 
LIMIT 20

UPDATE文の構文:

UPDATE <component_name> 
SET <col_name1> = <expr1> , 
<col_name2> = <expr2> 
WHERE <where_condition> 
ORDER BY <order_by> 
LIMIT <record_count>

• UPDATE文はcomponent_nameの既存のレコードのカラムを新しい値で更新し影響を受けたレコードの数を返します。
• SET句は修正するカラムとそれらに渡される値を示します。
• オプションのWHERE句は更新するレコードを特定する条件を指定します。WHERE句がなければ、すべてのレコードが更新されます。
• オプションのORDER BY句はレコードが更新される順序を指定します。
• LIMIT句は更新できるレコードの数に制限をおきます。UPDATEの範囲を制限するためにLIMIT row_countを使うことができます。LIMIT句は列を変更する制限ではなく列にマッチする制限です。実際に変更されたのかに関わらずWHERE句を満たすrecord_countの列が見つかるとステートメントはすぐに停止します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->update('Account')
    ->set('amount', 'amount + 200')
    ->where('id > 200');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

UPDATE account 
SET amount = amount + 200 
WHERE id > 200

更新の実行はシンプルです。次のクエリを実行するだけです:

// test.php

// ...
$rows = $q->execute();

echo $rows;

DELETE 
FROM <component_name> 
WHERE <where_condition> 
ORDER BY <order_by> 
LIMIT <record_count>

• DELETE文はcomponent_nameからレコードを削除し削除されるレコードの数を返します。
• オプションのWHERE句は削除するレコードを特定する条件を指定します。WHERE句なしでは、すべてのレコードが削除されます。
• ORDER BY句が指定されると、指定された順序でレコードが削除されます。
• LIMIT句は削除される列の数に制限を置きます。record_countの数のレコードが削除されると同時にステートメントは停止します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->delete('Account a')
    ->where('a.id > 3');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

DELETE 
FROM account 
WHERE id > 3

DELETEクエリの実行は次の通りです:

// test.php

// ...
$rows = $q->execute();

echo $rows;

DQLのUPDATEとDELETEクエリを実行すると影響を受けた列の数が返されます。

構文:

FROM <component_reference> [[LEFT | INNER] JOIN <component_reference>] ...

FROM句はレコードを読み取るコンポーネントを示します。複数のコンポーネントを名付けると、joinを実行することになります。指定されたそれぞれのテーブルに対して、オプションとしてエイリアスを指定できます。

次のDQLクエリを考えます:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.id')
    ->from('User u');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id 
FROM user u

Userはクラス(コンポーネント)の名前でuはエイリアスです。常に短いエイリアスを使うべきです。大抵の場合これらによってクエリははるかに短くなるのと例えばキャッシュを利用するときに短いエイリアスが使われていればクエリのキャッシュされたフォームの取るスペースが少なくなるからです。

DQL JOINの構文:

JOIN <component_reference1>] [ON | WITH] <join_condition1> [INDEXBY] <map_condition1>,
[[LEFT | INNER] JOIN <component_reference2>] [ON | WITH] <join_condition2> [INDEXBY] <map_condition2>,
...
[[LEFT | INNER] JOIN <component_referenceN>] [ON | WITH] <join_conditionN> [INDEXBY] <map_conditionN>

DQLはINNER JOINとLEFT JOINをサポートします。それぞれのjoinされたコンポーネントに対して、オプションとしてエイリアスを指定できます。

デフォルトのjoinの形式はLEFT JOINです。このjoinはLEFT JOIN句もしくはシンプルな','のどちらかを使うことで示せます。なので次のクエリは等しいです:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.id, p.id')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p');

$q = Doctrine_Query::create()
    ->select('u.id, p.id')
    ->from('User u, u.Phonenumbers p');

echo $q->getSqlQuery();

推奨される形式は前者です。より冗長で読みやすく何が行われているのか理解しやすいからです。

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
p.id AS p__id 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id

JOINの条件が自動的に追加されることに注意してください。DoctrineはUserとPhonenumberは関連していることを知っているのであなたに代わって追加できるからです。

INNER JOINは共通集合を生み出します(すなわち、最初のコンポーネントのありとあらゆるレコードが2番目のコンポーネントのありとあらゆるレコードにjoinされます)。ですので例えば電話番号を1つかそれ以上持つすべてのユーザーを効率的に取得したい場合、基本的にINNER JOINが使われます。

デフォルトではDQLは主キーのjoin条件を自動追加します:

// test.php

// ...
$q = Doctrine_Query::create()
  ->select('u.id, p.id')
  ->from('User u')
  ->leftJoin('u.Phonenumbers p');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
p.id AS p__id 
FROM User u 
LEFT JOIN Phonenumbers p ON u.id = p.user_id

INDEXBYキーワードはコレクション/配列のキーなどの特定のカラムをマッピングする方法を提供します。デフォルトではDoctrineは数値のインデックス付きの配列/コレクションに複数の要素のインデックスを作成します。マッピングはゼロから始まります。このビヘイビアをオーバーライドするには下記で示されるようにINDEXBYキーワードを使う必要があります:

// test.php

// ...
$q = Doctrine_Query::create()
  ->from('User u INDEXBY u.username');

$users = $q->execute();

INDEXBYキーワードは生成されるSQLを変えません。コレクションのそれぞれのレコードのキーとして指定されたカラムでデータをハイドレイトするためにDoctrine_Queryによって内部で使われます。

これで$usersコレクションのユーザーは自身の名前を通してアクセスできます:

// test.php

// ...
echo $user['jack daniels']->id;

INDEXBYキーワードは任意のJOINに適用できます。これは任意のコンポーネントがそれぞれ独自のインデックス作成のビヘイビアを持つことができることを意味します。次のコードにおいてUsersとGroupsの両方に対して異なるインデックス作成機能を使用しています。

// test.php

// ...
$q = Doctrine_Query::create()
    ->from('User u INDEXBY u.username')
    ->innerJoin('u.Groups g INDEXBY g.name');

$users = $q->execute();

drinkers clubの作成日を出力してみましょう。

// test.php

// ...
echo $users['jack daniels']->Groups['drinkers club']->createdAt;

構文:

WHERE <where_condition>

• WHERE句は、与えられた場合、選択されるためにレコードが満たさなければならない条件を示します。
• where_conditionは選択されるそれぞれの列に対してtrueに評価される式です。
• WHERE句が存在しない場合ステートメントはすべての列を選択します。
• 集約関数の値で結果を絞るときWHERE句の代わりにHAVING句が使われます。

Doctrine_Queryオブジェクトを使用する複雑なwhere条件を構築するためにaddWhere()、andWhere()、orWhere()、whereIn()、andWhereIn()、orWhereIn()、whereNotIn(), andWhereNotIn()、orWhereNotIn()メソッドを使うことができます。

すべてのアクティブな登録ユーザーもしくは管理者を読み取る例は次の通りです:

// test.php

// ...
$q = Doctrine_Query::create()
  ->select('u.id')
  ->from('User u')
  ->where('u.type = ?', 'registered')
  ->andWhere('u.is_active = ?', 1)
  ->orWhere('u.is_super_admin = ?', 1);

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id 
FROM user u 
WHERE u.type = ?
AND u.is_active = ?
OR u.is_super_admin = ?

DQLのGROUP BY構文:

GROUP BY groupby_item {, 
groupby_item}*

DQL HAVINGの構文:

HAVING conditional_expression

GROUP BYとHAVING句は集約関数を扱うために使われます。次の集約関数がDQLで利用可能です: COUNT、MAX、MIN、AVG、SUM

アルファベット順で最初のユーザーを名前で選択する。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('MIN(a.amount)')
    ->from('Account a');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
MIN(a.amount) AS a__0 
FROM account a

すべてのアカウントの合計数を選択する。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('SUM(a.amount)')
    ->from('Account a');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
SUM(a.amount) AS a__0 
FROM account a

GROUP BY句を含まないステートメントで集約関数を使うと、すべての列でグルーピングすることになります。下記の例ではすべてのユーザーと彼らが持つ電話番号の合計数を取得します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username')
    ->addSelect('COUNT(p.id) as num_phonenumbers')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p')
    ->groupBy('u.id');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
u.username AS u__username, 
COUNT(p.id) AS p__0 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id 
GROUP BY u.id

HAVING句は集約値を使用する結果を狭めるために使われます。次の例では少なくとも2つの電話番号を持つすべてのユーザーを取得します。

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username')
    ->addSelect('COUNT(p.id) as num_phonenumbers')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p')
    ->groupBy('u.id')
    ->having('num_phonenumbers >= 2');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
u.username AS u__username, 
COUNT(p.id) AS p__0 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id 
GROUP BY u.id 
HAVING p__0 >= 2

次のコードで電話番号の数にアクセスできます:

// test.php

// ...
$users = $q->execute();

foreach($users as $user) {
    echo $user->name . ' has ' . $user->num_phonenumbers . ' phonenumbers';
}

おそらく最も複雑機能であるDQLパーサーはLIMIT句パーサーです。DQL LIMIT句パーサーはLIMITデータベースポータビリティを考慮するだけでなく複雑なクエリ分析とサブクエリを使用することで列の代わりにレコードの数を制限できる機能を持ちます。

最初の20ユーザーと関連する電話番号を読み取ります:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.username, p.phonenumber')
    ->from('User u')
    ->leftJoin('u.Phonenumbers p')
    ->limit(20);

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id, 
u.username AS u__username, 
p.id AS p__id, 
p.phonenumber AS p__phonenumber 
FROM user u 
LEFT JOIN phonenumber p ON u.id = p.user_id

変化する可能性があるモデルを扱うが、クエリを簡単に更新できるようにする必要があるとき、クエリを定義する簡単な方法を見つける必要があります。例えば1つのフィールドを変更して何も壊れていないことを確認するためにアプリケーションのすべてのクエリを追跡する必要がある状況を想像してください。

名前付きクエリはこの状況を解決する素晴らしく効率的な方法です。これによってDoctrine_Queriesを作成しこれらを書き直すこと無く再利用できるようになります。

名前付きクエリのサポートはDoctrine_Query_Registryのサポートの上で構築されます。Doctrine_Query_Registryはクエリを登録して名前をつけるためのクラスです。これはアプリケーションクエリの編成を手助けしこれに沿ってとても便利な機能を提供します。

レジストリオブジェクトのadd()メソッドを使用してこのクエリは追加されます。これは2つのパラメータ、クエリの名前と実際のDQLクエリを受け取ります。

// test.php

// ...
$r = Doctrine_Manager::getInstance()->getQueryRegistry();

$r->add('User/all', 'FROM User u');

$userTable = Doctrine_Core::getTable('User');

// すべてのユーザーを見つける
$users = $userTable->find('all');

このサポートを簡略化するために、Doctrine_TableはDoctrine_Query_Registryへのアクセサをサポートします。

QL_statement ::= select_statement | update_statement | delete_statement
select_statement ::= select_clause from_clause [where_clause] [groupby_clause]
[having_clause] [orderby_clause]
update_statement ::= update_clause [where_clause]
delete_statement ::= delete_clause [where_clause]
from_clause ::=
FROM identification_variable_declaration
{, {identification_variable_declaration | collection_member_declaration}}*
identification_variable_declaration ::= range_variable_declaration { join | fetch_join }*
range_variable_declaration ::= abstract_schema_name [AS ] identification_variable
join ::= join_spec join_association_path_expression [AS ] identification_variable
fetch_join ::= join_specFETCH join_association_path_expression
association_path_expression ::=
collection_valued_path_expression | single_valued_association_path_expression
join_spec::= [LEFT [OUTER ] |INNER ]JOIN
join_association_path_expression ::= join_collection_valued_path_expression |
join_single_valued_association_path_expression
join_collection_valued_path_expression::=
identification_variable.collection_valued_association_field
join_single_valued_association_path_expression::=
identification_variable.single_valued_association_field
collection_member_declaration ::=
IN ( collection_valued_path_expression) [AS ] identification_variable
single_valued_path_expression ::=
state_field_path_expression | single_valued_association_path_expression
state_field_path_expression ::=
{identification_variable | single_valued_association_path_expression}.state_field
single_valued_association_path_expression ::=
identification_variable.{single_valued_association_field.}* single_valued_association_field
collection_valued_path_expression ::=
identification_variable.{single_valued_association_field.}*collection_valued_association_field
state_field ::= {embedded_class_state_field.}*simple_state_field
update_clause ::=UPDATE abstract_schema_name [[AS ] identification_variable]
SET update_item {, update_item}*
update_item ::= [identification_variable.]{state_field | single_valued_association_field} =
new_value
new_value ::=
simple_arithmetic_expression |
string_primary |
datetime_primary |

boolean_primary |
enum_primary
simple_entity_expression |
NULL
delete_clause ::=DELETE FROM abstract_schema_name [[AS ] identification_variable]
select_clause ::=SELECT [DISTINCT ] select_expression {, select_expression}*
select_expression ::=
single_valued_path_expression |
aggregate_expression |
identification_variable |
OBJECT( identification_variable) |
constructor_expression
constructor_expression ::=
NEW constructor_name( constructor_item {, constructor_item}*)
constructor_item ::= single_valued_path_expression | aggregate_expression
aggregate_expression ::=
{AVG |MAX |MIN |SUM }( [DISTINCT ] state_field_path_expression) |
COUNT ( [DISTINCT ] identification_variable | state_field_path_expression |
single_valued_association_path_expression)
where_clause ::=WHERE conditional_expression
groupby_clause ::=GROUP BY groupby_item {, groupby_item}*
groupby_item ::= single_valued_path_expression | identification_variable
having_clause ::=HAVING conditional_expression
orderby_clause ::=ORDER BY orderby_item {, orderby_item}*
orderby_item ::= state_field_path_expression [ASC |DESC ]
subquery ::= simple_select_clause subquery_from_clause [where_clause]
[groupby_clause] [having_clause]
subquery_from_clause ::=
FROM subselect_identification_variable_declaration
{, subselect_identification_variable_declaration}*
subselect_identification_variable_declaration ::=
identification_variable_declaration |
association_path_expression [AS ] identification_variable |
collection_member_declaration
simple_select_clause ::=SELECT [DISTINCT ] simple_select_expression
simple_select_expression::=
single_valued_path_expression |
aggregate_expression |
identification_variable
conditional_expression ::= conditional_term | conditional_expressionOR conditional_term
conditional_term ::= conditional_factor | conditional_termAND conditional_factor
conditional_factor ::= [NOT ] conditional_primary
conditional_primary ::= simple_cond_expression |( conditional_expression)
simple_cond_expression ::=
comparison_expression |
between_expression |
like_expression |
in_expression |
null_comparison_expression |
empty_collection_comparison_expression |

collection_member_expression |
exists_expression
between_expression ::=
arithmetic_expression [NOT ]BETWEEN
arithmetic_expressionAND arithmetic_expression |
string_expression [NOT ]BETWEEN string_expressionAND string_expression |
datetime_expression [NOT ]BETWEEN
datetime_expressionAND datetime_expression
in_expression ::=
state_field_path_expression [NOT ]IN ( in_item {, in_item}* | subquery)
in_item ::= literal | input_parameter
like_expression ::=
string_expression [NOT ]LIKE pattern_value [ESCAPE escape_character]
null_comparison_expression ::=
{single_valued_path_expression | input_parameter}IS [NOT ] NULL
empty_collection_comparison_expression ::=
collection_valued_path_expressionIS [NOT] EMPTY
collection_member_expression ::= entity_expression
[NOT ]MEMBER [OF ] collection_valued_path_expression
exists_expression::= [NOT ]EXISTS (subquery)
all_or_any_expression ::= {ALL |ANY |SOME } (subquery)
comparison_expression ::=
string_expression comparison_operator {string_expression | all_or_any_expression} |
boolean_expression {= |<> } {boolean_expression | all_or_any_expression} |
enum_expression {= |<> } {enum_expression | all_or_any_expression} |
datetime_expression comparison_operator
{datetime_expression | all_or_any_expression} |
entity_expression {= |<> } {entity_expression | all_or_any_expression} |
arithmetic_expression comparison_operator
{arithmetic_expression | all_or_any_expression}
comparison_operator ::== |> |>= |< |<= |<>
arithmetic_expression ::= simple_arithmetic_expression | (subquery)
simple_arithmetic_expression ::=
arithmetic_term | simple_arithmetic_expression {+ |- } arithmetic_term
arithmetic_term ::= arithmetic_factor | arithmetic_term {* |/ } arithmetic_factor
arithmetic_factor ::= [{+ |- }] arithmetic_primary
arithmetic_primary ::=
state_field_path_expression |
numeric_literal |
(simple_arithmetic_expression) |
input_parameter |
functions_returning_numerics |
aggregate_expression
string_expression ::= string_primary | (subquery)
string_primary ::=
state_field_path_expression |
string_literal |
input_parameter |
functions_returning_strings |
aggregate_expression

datetime_expression ::= datetime_primary | (subquery)
datetime_primary ::=
state_field_path_expression |
input_parameter |
functions_returning_datetime |
aggregate_expression
boolean_expression ::= boolean_primary | (subquery)
boolean_primary ::=
state_field_path_expression |
boolean_literal |
input_parameter |
enum_expression ::= enum_primary | (subquery)
enum_primary ::=
state_field_path_expression |
enum_literal |
input_parameter |
entity_expression ::=
single_valued_association_path_expression | simple_entity_expression
simple_entity_expression ::=
identification_variable |
input_parameter
functions_returning_numerics::=
LENGTH( string_primary) |
LOCATE( string_primary, string_primary[, simple_arithmetic_expression]) |
ABS( simple_arithmetic_expression) |
SQRT( simple_arithmetic_expression) |
MOD( simple_arithmetic_expression, simple_arithmetic_expression) |
SIZE( collection_valued_path_expression)
functions_returning_datetime ::=
  CURRENT_DATE |
  CURRENT_TIME |
  CURRENT_TIMESTAMP
functions_returning_strings ::=
CONCAT( string_primary, string_primary) |
SUBSTRING( string_primary,
simple_arithmetic_expression, simple_arithmetic_expression)|
TRIM( [[trim_specification] [trim_character]FROM ] string_primary) |
LOWER( string_primary) |
UPPER( string_primary)
trim_specification ::=LEADING | TRAILING | BOTH

Doctrineはモデルに存在する任意のカラムでレコードを見つけることを可能にするDoctrineモデル用のマジックファインダー(magic finder)を提供します。ユーザーの名前でユーザーを見つけたり、グループの名前でグループを見つけるために役立ちます。通常これはDoctrine_Queryインスタンスを書き再利用できるようにこれをどこかに保存することが必要です。このようなシンプルな状況にはもはや必要ありません。

ファインダーメソッドの基本パターンは次の通りです: findBy%s($value)もしくはfindOneBy%s($value)です。%sはカラム名もしくはリレーションのエイリアスです。カラムの名前の場合探す値を提供しなければなりません。リレーションのエイリアスを指定する場合、見つけるリレーションクラスのインスタンスを渡すか、実際の主キーの値を渡すことができます。

最初に扱うUserTableインスタンスを読み取りましょう:

// test.php

// ...
$userTable = Doctrine_Core::getTable('User');

find()メソッドを利用して主キーでUserレコードを簡単に見つけられます:

// test.php

// ...
$user = $userTable->find(1);

ユーザー名で1人のユーザーを見つけたい場合は次のようにマジックファインダーを使うことができます:

// test.php

// ...
$user = $userTable->findOneByUsername('jonwage');

レコード間のリレーションを利用してレコードでユーザーを見つけることができます。Userは複数のPhonenumbersを持つのでfindBy**()メソッドにUserインスタンスを渡すことでこれらのPhonenumberを見つけることができます:

// test.php

// ...
$phonenumberTable = Doctrine::getTable('Phonenumber');

$phonenumbers = $phonenumberTable->findByUser($user);

マジックファインダーはもう少し複雑な検索を可能にします。複数のプロパティによってレコードを検索するためにメソッド名でAndとOrキーワードを使うことができます。

$user = $userTable->findOneByUsernameAndPassword('jonwage', md5('changeme'));

条件を混ぜることもできます。

$users = $userTable->findByIsAdminAndIsModeratorOrIsSuperAdmin(true, true, true);

Doctrine_Queryオブジェクトはクエリの問題をデバッグするための手助けになる機能を少々提供します:

ときにDoctrine_Queryオブジェクトに対して完全なSQL文字列を見たいことがあります:

// test.php

// ...
$q = Doctrine_Query::create()
    ->select('u.id')
    ->from('User u')
    ->orderBy('u.username');

echo $q->getSqlQuery();

getSql()への呼び出しは次のSQLクエリを出力します:

SELECT 
u.id AS u__id 
FROM user u 
ORDER BY u.username

上記のDoctrine_Query::getSql()メソッドによって返されるSQLはトークンをパラメータに置き換えません。これはPDOのジョブでクエリを実行するとき置き換えが実行されるPDOにパラメータを渡します。Doctrine_Query::getParams()メソッドでパラメータの配列を読み取ることができます。

Doctrine_Queryインスタンス用のパラメータの配列を取得します:

// test.php

// ...
print_r($q->getParams());

Doctrine Query Languageはこれまでのところ最も高度で役に立つDoctrineの機能です。これによってRDBMSのリレーションからとても複雑なデータを簡単にかつ効率的に選択できます！

これでDoctrineの主要なコンポーネントの使い方を見たのでComponent Overviewの章に移りすべてを鳥の目で見ることにします。