repo_zf1/documentation/manual/ja/module_specs/Zend_Db_Select.xml

<?xml version="1.0" encoding="UTF-8"?>
<!-- Reviewed: no -->
<!-- EN-Revision: 15207 -->
<sect1 id="zend.db.select">

    <title>Zend_Db_Select</title>

    <sect2 id="zend.db.select.introduction">

        <title>導入</title>

        <para>
            <classname>Zend_Db_Select</classname> オブジェクトは、SQL の <code>SELECT</code> 文を表すものです。
            このクラスには、クエリの各部分を追加するためのメソッドが用意されています。
            PHP のメソッドやデータをもとにクエリの各部分を指定すると、
            このクラスが正確な SQL 文を作成してくれます。クエリを作成したら、
            あとは通常の文字列と同じようにそれを用いてクエリを実行できます。
        </para>

        <para>
            <classname>Zend_Db_Select</classname> は次のような機能を提供します。
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    SQL クエリを少しずつ組み立てていくための
                    オブジェクト指向のメソッド
                </para>
            </listitem>

            <listitem>
                <para>
                    SQL クエリの一部について、データベースに依存しない抽象化
                </para>
            </listitem>

            <listitem>
                <para>
                    大半のメタデータ識別子の自動クォート処理による、
                    予約語や特殊文字を含む SQL のサポート
                </para>
            </listitem>

            <listitem>
                <para>
                    識別子や値のクォートによる、
                    SQL インジェクション攻撃対策
                </para>
            </listitem>
        </itemizedlist>

        <para>
            必ず <classname>Zend_Db_Select</classname> を使わなければならないというわけではありません。
            単純な SELECT クエリを実行するのなら、SQL クエリ全体を文字列で指定し、
            アダプタの <code>query()</code> メソッドや <code>fetchAll()</code>
            メソッドを使用したほうがずっとシンプルになるでしょう。
            <classname>Zend_Db_Select</classname> を使うと便利なのは、
            何らかの条件にもとづいて、アプリケーション内で
            SELECT クエリを動的に組み立てていく必要があるような場合です。
        </para>

    </sect2>

    <sect2 id="zend.db.select.creating">

        <title>Select オブジェクトの作成</title>

        <para>
            <classname>Zend_Db_Select</classname> オブジェクトのインスタンスを作成するには、
            <classname>Zend_Db_Adapter_Abstract</classname> オブジェクトの
            <code>select()</code> メソッドを使用します。
        </para>

        <example id="zend.db.select.creating.example-db">

            <title>データベースアダプタの select() メソッドの例</title>

            <programlisting role="php"><![CDATA[
$db = Zend_Db::factory( ...options... );
$select = $db->select();
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Db_Select</classname> オブジェクトを作成するもうひとつの方法は、
            コンストラクタの引数でデータベースアダプタを指定することです。
        </para>

        <example id="zend.db.select.creating.example-new">

            <title>新しい Select オブジェクトの作成の例</title>

            <programlisting role="php"><![CDATA[
$db = Zend_Db::factory( ...options... );
$select = new Zend_Db_Select($db);
]]></programlisting>
        </example>

    </sect2>

    <sect2 id="zend.db.select.building">

        <title>Select クエリの作成</title>

        <para>
            クエリを作成する際に、クエリの句を個別に追加していくことができます。
            <classname>Zend_Db_Select</classname> オブジェクトには、
            個々の句を追加していくメソッドが用意されています。
        </para>

        <example id="zend.db.select.building.example">

            <title>メソッドを使用して句を追加する例</title>

            <programlisting role="php"><![CDATA[
// Zend_Db_Select オブジェクトを作成します
$select = $db->select();

// FROM 句を追加します
$select->from( ...テーブルとカラムを指定します... )

// WHERE 句を追加します
$select->where( ...検索条件を指定します... )

// ORDER BY 句を追加します
$select->order( ...ソート条件を指定します... );
]]></programlisting>
        </example>

        <para>
            <classname>Zend_Db_Select</classname> オブジェクトの大半のメソッドで、便利な
            「流れるようなインターフェイス」形式を利用できます。これは、
            各メソッドが、自分自身への参照を結果として返すということです。
            つまり、その結果を使用してすぐに別のメソッドをコールできるのです。
        </para>

        <example id="zend.db.select.building.example-fluent">

            <title>流れるようなインターフェイスの使用例</title>

            <programlisting role="php"><![CDATA[
$select = $db->select()
    ->from( ...テーブルとカラムを指定します... )
    ->where( ...検索条件を指定します... )
    ->order( ...ソート条件を指定します... );
]]></programlisting>

        </example>

        <para>
            この節の例では流れるようなインターフェイスを使用しますが、
            この方式を使用せずに使用することも可能です。
            そうしなければならないこともよくあるでしょう。たとえば、
            クエリに句を追加する前にアプリケーションで何らかの処理が必要な場合などです。
        </para>

        <sect3 id="zend.db.select.building.from">

            <title>FROM 句の追加</title>

            <para>
                このクエリのテーブルを指定するために <code>from()</code>
                メソッドを使用します。テーブル名は、単純に文字列で指定することができます。
                <classname>Zend_Db_Select</classname> はテーブル名を識別子としてクォートするので、
                特殊文字を使用することもできます。
            </para>

            <example id="zend.db.select.building.from.example">

                <title>from() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT *
//   FROM "products"

$select = $db->select()
             ->from( 'products' );
]]></programlisting>

            </example>

            <para>
                テーブルの相関名 (あるいは "エイリアス" とも言われます)
                を指定することもできます。その場合は、
                単純な文字列ではなく連想配列を使用し、相関名とテーブル名の対応を指定します。
                SQL のその他の句で、この相関名を使用できるようになります。
                複数のテーブルを結合したクエリを作成する場合は、
                <classname>Zend_Db_Select</classname> はそのテーブル名に基づいた一意な相関名を作成します。
            </para>

            <example id="zend.db.select.building.from.example-cname">

                <title>テーブルの相関名を指定する例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p.*
//   FROM "products" AS p

$select = $db->select()
             ->from( array('p' => 'products') );
]]></programlisting>

            </example>

            <para>
                RDBMS によっては、テーブル名の前にスキーマ名をつなげる方式をサポートしているものもあります。
                テーブル名として、"<code>schemaName.tableName</code>"
                のように指定することができます。この場合、
                <classname>Zend_Db_Select</classname> は各部分を個別にクォートします。
                あるいはスキーマ名とテーブル名を別々に指定することもできます。
                もし両方でスキーマ名を指定した場合は、
                テーブル名と同時に指定したもののほうが優先されます。
            </para>

            <example id="zend.db.select.building.from.example-schema">

                <title>スキーマ名の指定の例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT *
//   FROM "myschema"."products"

$select = $db->select()
             ->from( 'myschema.products' );

// あるいは

$select = $db->select()
             ->from('products', '*', 'myschema');
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.columns">

            <title>カラムの追加</title>

            <para>
                <code>from()</code> メソッドの二番目の引数で、
                対応するテーブルから取得するカラムを指定することができます。
                カラムを指定しなかった場合のデフォルトは
                "<code>*</code>" で、これは "すべてのカラム"
                を表す SQL のワイルドカードです。
            </para>

            <para>
                カラム名を指定するには、単純な文字列の配列を使用するか、
                あるいは連想配列でエイリアスとカラム名を対応させます。
                取得したいカラムがひとつだけの場合でエイリアスを使用しない場合は、
                配列ではなく単純な文字列で指定することもできます。
            </para>

            <para>
                空の配列をカラムの引数として指定すると、
                対応するテーブルからのカラムは結果セットに含まれなくなります。
                <code>join()</code> メソッドの
                <link linkend="zend.db.select.building.join.example-no-columns">コード例</link>
                を参照ください。
            </para>

            <para>
                カラム名を
                "<code>correlationName.columnName</code>"
                の形式で指定することもできます。この場合、
                <classname>Zend_Db_Select</classname> は各部分を個別にクォートします。
                カラムの correlationName (相関名) を指定しなかった場合は、
                現在の <code>from()</code> メソッドで指定したテーブルの名前を使用します。
            </para>

            <example id="zend.db.select.building.columns.example">

                <title>カラムを指定する例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'));

// 同じクエリを、相関名を指定して作成します
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('p.product_id', 'p.product_name'));

// このクエリを、カラムのひとつにエイリアスを指定して作成します
//   SELECT p."product_id" AS prodno, p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('prodno' => 'product_id', 'product_name'));
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.columns-expr">

            <title>式によるカラムの追加</title>

            <para>
                SQL クエリでは、単にテーブルのカラムを使用するだけでなく
                何らかの式をカラムとして使用することもあります。
                このような場合は、相関名をつけたりクォートを適用したりしてはいけません。
                カラム文字列に括弧が含まれている場合に、<classname>Zend_Db_Select</classname>
                はそれを式として扱います。
            </para>

            <para>
                <classname>Zend_Db_Expr</classname> 型のオブジェクトを明示的に作成し、
                文字列がカラム名と解釈されてしまうことを防ぐこともできます。
                <classname>Zend_Db_Expr</classname> は、文字列をひとつだけ含む最小限のクラスです。
                <classname>Zend_Db_Select</classname> は <code>Zend_Db_Expr</code> 型のオブジェクトを認識し、
                それを文字列に変換しますが、
                その際にクォートや相関名などの処理を適用しません。
            </para>

            <note>

                <para>
                    カラムとして使用する式に括弧が含まれている場合は、
                    カラム名で <classname>Zend_Db_Expr</classname> を指定する必要はありません。
                    <classname>Zend_Db_Select</classname> は、括弧を発見すると自動的にその文字列を式として扱います。
                    クォートや相関名の設定はされません。
                </para>

            </note>

            <example id="zend.db.select.building.columns-expr.example">

                <title>式を含むカラムの指定の例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", LOWER(product_name)
//   FROM "products" AS p
// 括弧つきの式は、暗黙のうちに
// Zend_Db_Expr として扱われます

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'LOWER(product_name)'));

// できあがるクエリは、このようになります
//   SELECT p."product_id", (p.cost * 1.08) AS cost_plus_tax
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id',
                          'cost_plus_tax' => '(p.cost * 1.08)')
                   );

// このクエリを、明示的に Zend_Db_Expr を指定して作成します
//   SELECT p."product_id", p.cost * 1.08 AS cost_plus_tax
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id',
                          'cost_plus_tax' =>
                              new Zend_Db_Expr('p.cost * 1.08'))
                    );
]]></programlisting>

            </example>

            <para>
                上の例では、<classname>Zend_Db_Select</classname> は
                相関名の設定や識別子のクォートといった処理を行いません。
                あいまいさを解決するためにそのような処理が必要な場合は、
                手動で文字列を変更する必要があります。
            </para>

            <para>
                カラム名が SQL キーワードや特殊文字を含んでいる場合は、
                アダプタの <code>quoteIdentifier()</code>
                メソッドを使用して結果を操作する必要があります。
                <code>quoteIdentifier()</code> は、
                識別子に対して SQL のクォート処理を行います。
                これによりテーブルやカラムといった識別子を
                SQL のそれ以外の部分と区別できるようになります。
            </para>

            <para>
                クォート処理を直接文字列に埋め込んでしまわずに
                <code>quoteIdentifier()</code> メソッドを使用することで、
                あなたのコードをデータベースに依存しないものにすることができます。
                というのも、RDBMS によってはあまり標準的ではない文字でクォートを行うものもあるからです。
                <code>quoteIdentifier()</code> メソッドは、
                アダプタの型に応じて適切なクォート文字を使用するように設計されています。
                <code>quoteIdentifier()</code> メソッドはまた、
                識別子の名前の中に登場するクォート文字自体もエスケープします。
            </para>

            <example id="zend.db.select.building.columns-quoteid.example">

                <title>式の中のカラムをクォートする例</title>

                <programlisting role="php"><![CDATA[
// このクエリを作成する際に、式の中にある特別なカラム名 "from" をクォートします
//   SELECT p."from" + 10 AS origin
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('origin' =>
                              '(p.' . $db->quoteIdentifier('from') . ' + 10)')
                   );
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.columns-atomic">

            <title>既存の FROM あるいは JOIN テーブルへのカラムの追加</title>

            <para>
                既存の FROM や JOIN のテーブルに対して、それらのメソッドをコールした後で
                カラムを追加したくなることもあるかもしれません。
                <code>columns()</code> メソッドを使用すると、
                クエリを実行する前ならいつでも好きなときに特定のカラムを追加することができます。
                カラムは、文字列あるいは <classname>Zend_Db_Expr</classname>、
                あるいはその配列で指定します。
                このメソッドの 2 番目の引数は省略可能です。
                省略した場合は、FROM テーブルにカラムが追加されます。
                指定する場合は、既存の相関名を使用しなければなりません。
            </para>

            <example id="zend.db.select.building.columns-atomic.example">

                <title>columns() メソッドでカラムを追加する例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'), 'product_id')
             ->columns('product_name');

// 同じクエリを、相関名を指定して作成します
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->from(array('p' => 'products'), 'p.product_id')
             ->columns('product_name', 'p');
             // あるいは columns('p.product_name')]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.join">

            <title>JOIN による、クエリへの別のテーブルの追加</title>

            <para>
                有用なクエリの多くは、<code>JOIN</code>
                を使用して複数テーブルの行を結合しています。
                テーブルを <classname>Zend_Db_Select</classname> クエリに追加するには、
                <code>join()</code> メソッドを使用します。
                このメソッドの使用法は <code>from()</code>
                メソッドと似ていますが、ほとんどの場合に結合条件を指定するという点が異なります。
            </para>

            <example id="zend.db.select.building.join.example">

                <title>join() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name", l.*
//   FROM "products" AS p JOIN "line_items" AS l
//     ON p.product_id = l.product_id

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'))
             ->join(array('l' => 'line_items'),
                    'p.product_id = l.product_id');
]]></programlisting>

            </example>

            <para>
                <code>join()</code> の二番目の引数として、
                結合条件を文字列で指定します。これは、
                あるテーブルの行が別のテーブルのどの行と対応するのかを表す条件式です。
                式の中では相関名を使用することができます。
            </para>

            <note>

                <para>
                    結合条件に指定した式に関しては、クォート処理は行われません。
                    クォートする必要のあるカラム名を使用する場合は、
                    結合条件の文字列を作成する際に
                    <code>quoteIdentifier()</code> を使用しなければなりません。
                </para>

            </note>

            <para>
                <code>join()</code> の三番目の引数はカラム名を表す配列です。
                これは <code>from()</code> メソッドで使用する形式と似ています。
                デフォルトは "<code>*</code>" です。
                相関名や式、<classname>Zend_Db_Expr</classname> についての扱いは、
                <code>from()</code> メソッドにおけるカラム名の配列と同じです。
            </para>

            <para>
                テーブルからカラムを取得しない場合は、
                カラムリストに空の配列を使用します。
                これは <code>from()</code> メソッドでも同様に動作しますが、
                普通は最初のテーブルからは何らかのカラムを取得するでしょう。
                一方、連結するテーブルについてはカラムを取得しないこともありえます。
            </para>

            <example id="zend.db.select.building.join.example-no-columns">

                <title>カラムを指定しない例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p JOIN "line_items" AS l
//     ON p.product_id = l.product_id

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'))
             ->join(array('l' => 'line_items'),
                    'p.product_id = l.product_id',
                    array() ); // 空のカラムリスト
]]></programlisting>

                <para>
                    上の例で、連結したテーブルのカラム一覧の場所に
                    空の配列 <code>array()</code> を指定していることに注意しましょう。
                </para>

            </example>

            <para>
                SQL の結合にはいくつかの形式があります。
                以下に、<classname>Zend_Db_Select</classname> がサポートする結合の形式をまとめます。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <code>join(table, join, [columns])</code> メソッドあるいは
                        <code>joinInner(table, join, [columns])</code> メソッドによる
                        <command>INNER JOIN</command>
                    </para>

                    <para>
                        これはもっとも一般的な結合形式です。各テーブルの行を、
                        指定した結合条件に基づいて比較します。
                        結果セットには、その結合条件を満たす行のみが含まれます。
                        条件を満たす行がない場合は、結果セットが空になることもあります。
                    </para>

                    <para>
                        すべての RDBMS が、この結合形式に対応しています。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinLeft(table, condition, [columns])</code> メソッドによる
                        <command>LEFT JOIN</command>
                    </para>

                    <para>
                        左側のテーブルのすべての行と
                        右側のテーブルの条件にマッチする行が含まれます。
                        右側のテーブルからのカラムのうち、
                        左側のテーブルに対応する行がないものについては
                        NULL で埋められます。
                    </para>

                    <para>
                        すべての RDBMS が、この結合形式に対応しています。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinRight(table, condition, [columns])</code> メソッドによる
                        <command>RIGHT JOIN</command>
                    </para>

                    <para>
                        右外部結合は、左外部結合を補完するものです。
                        右側のテーブルのすべての行と
                        左側のテーブルの条件にマッチする行が含まれます。
                        左側のテーブルからのカラムのうち、
                        右側のテーブルに対応する行がないものについては
                        NULL で埋められます。
                    </para>

                    <para>
                        RDBMS によっては、この結合形式に対応していないものもあります。
                        しかし、一般に右外部結合は、
                        テーブルの順番を入れ替えれば左外部結合として表すことが可能です。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinFull(table, condition, [columns])</code> メソッドによる
                        <command>FULL JOIN</command>
                    </para>

                    <para>
                        完全外部結合は、左外部結合と右外部結合を組み合わせたようなものです。
                        両側のテーブルのすべての行が含まれます。
                        結合条件を満たす組み合わせがあった場合はそれらが同一行にまとめられ、
                        それ以外の場合は、対応するデータがないカラムについては NULL で埋められます。
                    </para>

                    <para>
                        RDBMS によっては、この結合形式に対応していないものもあります。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinCross(table, [columns])</code> メソッドによる
                        <command>CROSS JOIN</command>
                    </para>

                    <para>
                        クロス結合とは、デカルト積のことです。
                        最初のテーブルの各行に対して、
                        二番目のテーブルのすべての行がマッチします。
                        つまり、結果セットの行数は、
                        ふたつのテーブルの行数の積と等しくなります。
                        結果セットをフィルタリングするには、WHERE
                        句で条件を指定します。
                        この方法によるクロス結合は、昔の SQL-89
                        の結合構文と似ています。
                    </para>

                    <para>
                        <code>joinCross()</code> メソッドには、
                        結合条件を指定するパラメータがありません。
                        RDBMS によっては、この結合形式に対応していないものもあります。
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinNatural(table, [columns])</code> メソッドによる
                        <command>NATURAL JOIN</command>
                    </para>

                    <para>
                        自然結合は、両方のテーブルに同じ名前で登場するカラムを比較します。
                        比較はすべてのカラムに対して行われます。
                        この API でサポートしているのは、自然内部結合のみです。
                        SQL で自然外部結合がサポートされていたとしても、使用できません。
                    </para>

                    <para>
                        <code>joinNatural()</code> メソッドには、
                        結合条件を指定するパラメータはありません。
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                これらの結合メソッドに加え、クエリを単純にするために
                JoinUsing メソッドを使用することができます。完全な結合条件を渡すかわりに、
                単純に結合するカラム名の配列を渡してやれば
                <classname>Zend_Db_Select</classname> オブジェクトが結合条件を作成してくれます。
            </para>

            <example id="zend.db.select.building.joinusing.example">

                <title>joinUsing() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT *
//   FROM "table1"
//   JOIN "table2"
//   ON "table1".column1 = "table2".column1
//   WHERE column2 = 'foo'

$select = $db->select()
             ->from('table1')
             ->joinUsing('table2', 'column1')
             ->where('column2 = ?', 'foo');]]></programlisting>

            </example>

            <para>
                <classname>Zend_Db_Select</classname> の結合メソッドには、
                それぞれ対応する 'using' メソッドがあります。
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <code>joinUsing(table, join, [columns])</code> および
                        <code>joinInnerUsing(table, join, [columns])</code>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinLeftUsing(table, join, [columns])</code>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinRightUsing(table, join, [columns])</code>
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <code>joinFullUsing(table, join, [columns])</code>
                    </para>
                </listitem>
            </itemizedlist>

        </sect3>

        <sect3 id="zend.db.select.building.where">

            <title>WHERE 句の追加</title>

            <para>
                結果セットの行を制限するための条件を指定するには
                <code>where()</code> メソッドを使用します。
                このメソッドの最初の引数は SQL の式で、これをクエリの
                SQL で <code>WHERE</code> 句として使用します。
            </para>

            <example id="zend.db.select.building.where.example">

                <title>where() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT product_id, product_name, price
//   FROM "products"
//   WHERE price > 100.00

$select = $db->select()
             ->from('products',
                    array('product_id', 'product_name', 'price'))
             ->where('price > 100.00');]]></programlisting>

            </example>

            <note>

                <para>
                    <code>where()</code> メソッドや <code>orWhere()</code>
                    メソッドで指定する式にはクォート処理は行われません。
                    クォートする必要のあるカラム名を使用する場合は、
                    条件の文字列を作成する際に
                    <code>quoteIdentifier()</code> を使用しなければなりません。
                </para>

            </note>

            <para>
                <code>where()</code> メソッドの二番目の引数はオプションです。
                これは式を置き換える値となります。
                <classname>Zend_Db_Select</classname> は値をクォートし、式の中の
                クエスチョンマーク ("<code>?</code>") をその値で置き換えます。
            </para>

            <para>
                このメソッドはパラメータをひとつだけ受け取ります。
                複数の値を置換する必要がある場合は、文字列を自分でフォーマットし、
                値の挿入やクォートを自分で行う必要があります。
            </para>

            <example id="zend.db.select.building.where.example-param">

                <title>where() メソッドでのパラメータの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT product_id, product_name, price
//   FROM "products"
//   WHERE (price > 100.00)

$minimumPrice = 100;

$select = $db->select()
             ->from('products',
                    array('product_id', 'product_name', 'price'))
             ->where('price > ?', $minimumPrice);
]]></programlisting>

            </example>

            <para>
                <classname>Zend_Db_Select</classname> オブジェクト上で、<code>where()</code>
                メソッドを複数回実行することもできます。その結果のクエリは、
                指定した条件を <code>AND</code> でひとつにまとめたものとなります。
            </para>

            <example id="zend.db.select.building.where.example-and">

                <title>複数の where() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT product_id, product_name, price
//   FROM "products"
//   WHERE (price > 100.00)
//     AND (price < 500.00)

$minimumPrice = 100;
$maximumPrice = 500;

$select = $db->select()
             ->from('products',
                    array('product_id', 'product_name', 'price'))
             ->where('price > ?', $minimumPrice)
             ->where('price < ?', $maximumPrice);
]]></programlisting>

            </example>

            <para>
                複数の条件を <code>OR</code> で連結したい場合は、
                <code>orWhere()</code> メソッドを使用します。
                このメソッドの使用法は <code>where()</code>
                メソッドとほとんど同じですが、条件の前には
                <code>AND</code> ではなく <code>OR</code>
                がつくことになります。
            </para>

            <example id="zend.db.select.building.where.example-or">

                <title>orWhere() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT product_id, product_name, price
//   FROM "products"
//   WHERE (price < 100.00)
//     OR (price > 500.00)

$minimumPrice = 100;
$maximumPrice = 500;

$select = $db->select()
             ->from('products',
                    array('product_id', 'product_name', 'price'))
             ->where('price < ?', $minimumPrice)
             ->orWhere('price > ?', $maximumPrice);
]]></programlisting>

            </example>

            <para>
                <classname>Zend_Db_Select</classname> は、<code>where()</code> メソッドや
                <code>orWhere()</code> メソッドで指定した式の両側に
                自動的に括弧をつけます。これにより、
                論理演算子が予期せぬ結果を引き起こすことを防ぎます。
            </para>

            <example id="zend.db.select.building.where.example-parens">

                <title>論理式を括弧で囲む例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT product_id, product_name, price
//   FROM "products"
//   WHERE (price < 100.00 OR price > 500.00)
//     AND (product_name = 'Apple')

$minimumPrice = 100;
$maximumPrice = 500;
$prod = 'Apple';

$select = $db->select()
             ->from('products',
                    array('product_id', 'product_name', 'price'))
             ->where("price < $minimumPrice OR price > $maximumPrice")
             ->where('product_name = ?', $prod);
]]></programlisting>

            </example>

            <para>
                上の例では、括弧がなければ結果はまったく異なるものとなります。
                なぜなら、<code>AND</code> のほうが <code>OR</code>
                よりも優先順位が高いからです。<classname>Zend_Db_Select</classname>
                は括弧をつけるので、それぞれの <code>where()</code>
                で指定された式の結合度が <code>AND</code>
                より高くなります。
            </para>

        </sect3>

        <sect3 id="zend.db.select.building.group">

            <title>GROUP BY 句の追加</title>

            <para>
                SQL で <code>GROUP BY</code> 句を使用すると、
                結果セットの行数を減らすことができます。
                <code>GROUP BY</code> 句で指定したカラムの一意な値ごとに、
                結果が一行にまとめられます。
            </para>

            <para>
                <classname>Zend_Db_Select</classname> では、行のグループ化を行うためのカラムを
                <code>group()</code> メソッドで指定します。
                このメソッドへの引数は、<code>GROUP BY</code>
                句で使用するカラムあるいは複数カラムの配列となります。
            </para>

            <example id="zend.db.select.building.group.example">

                <title>group() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", COUNT(*) AS line_items_per_product
//   FROM "products" AS p JOIN "line_items" AS l
//     ON p.product_id = l.product_id
//   GROUP BY p.product_id

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id'))
             ->join(array('l' => 'line_items'),
                    'p.product_id = l.product_id',
                    array('line_items_per_product' => 'COUNT(*)'))
             ->group('p.product_id');
]]></programlisting>

            </example>

            <para>
                <code>from()</code> メソッドでのカラムの配列と同様、
                カラム名には相関名を使用することができます。また、
                カラム名は識別子としてクォートされます。
                ただし、文字列に括弧が含まれたり
                <classname>Zend_Db_Expr</classname> 型のオブジェクトを指定したりした場合は別です。
            </para>

        </sect3>

        <sect3 id="zend.db.select.building.having">

            <title>HAVING 句の追加</title>

            <para>
                SQL で <code>HAVING</code> 句を使用すると、
                グループ化した行に制約を適用します。これは、
                <code>WHERE</code> 句が行に対して制約を適用するのと同じです。
                しかし、これらには相違点があります。
                <code>WHERE</code> 条件はグループ化の前に適用されますが、
                <code>HAVING</code> 条件はグループ化された後に適用されます。
            </para>

            <para>
                <classname>Zend_Db_Select</classname> では、グループに対する制約を指定するには
                <code>having()</code> メソッドを使用します。
                このメソッドの使用法は <code>where()</code> メソッドと似ています。
                最初の引数が SQL の式を含む文字列です。二番目の引数はオプションで、
                SQL 式の中のパラメータプレースホルダを置き換える値となります。
                <code>having()</code> を複数回実行すると、それらの条件が
                論理演算子 <code>AND</code> で連結されます。
                <code>orHaving()</code> メソッドを使用した場合は、論理演算子
                <code>OR</code> で連結されます。
            </para>

            <example id="zend.db.select.building.having.example">

                <title>having() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", COUNT(*) AS line_items_per_product
//   FROM "products" AS p JOIN "line_items" AS l
//     ON p.product_id = l.product_id
//   GROUP BY p.product_id
//   HAVING line_items_per_product > 10

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id'))
             ->join(array('l' => 'line_items'),
                    'p.product_id = l.product_id',
                    array('line_items_per_product' => 'COUNT(*)'))
             ->group('p.product_id')
             ->having('line_items_per_product > 10');
]]></programlisting>

            </example>

            <note>

                <para>
                    <code>having()</code> メソッドや <code>orHaving()</code>
                    メソッドで指定する式にはクォート処理は行われません。
                    クォートする必要のあるカラム名を使用する場合は、
                    条件の文字列を作成する際に
                    <code>quoteIdentifier()</code> を使用しなければなりません。
                </para>

            </note>

        </sect3>

        <sect3 id="zend.db.select.building.order">

            <title>ORDER BY 句の追加</title>

            <para>
                SQL の <code>ORDER BY</code> 句では、
                クエリの結果セットの並べ替えの基準となるカラムや式を指定します。
                複数のカラムを指定すると、最初のカラムの値が同じだった場合に
                二番目のカラムを用いて並べ替えを行います。
                デフォルトでは、小さいほうから大きいほうに向かって並べ替えます。
                逆に大きいほうから小さいほうに向かって並べ替えるには、
                カラムリストの中のそのカラム名の後に、キーワード
                <code>DESC</code> を指定します。
            </para>

            <para>
                <classname>Zend_Db_Select</classname> では、<code>order()</code> メソッドを使用して
                並べ替えの基準となるカラムあるいはカラムの配列を指定します。
                配列の各要素はカラム名を表す文字列です。オプションとして、
                スペースをはさんでキーワード
                <code>ASC</code> や <code>DESC</code> を続けます。
            </para>

            <para>
                <code>from()</code> メソッドや <code>group()</code>
                メソッドと同様、カラム名は識別子としてクォートされます。
                ただし、文字列に括弧が含まれたり
                <classname>Zend_Db_Expr</classname> 型のオブジェクトを指定したりした場合は別です。
            </para>

            <example id="zend.db.select.building.order.example">

                <title>order() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", COUNT(*) AS line_items_per_product
//   FROM "products" AS p JOIN "line_items" AS l
//     ON p.product_id = l.product_id
//   GROUP BY p.product_id
//   ORDER BY "line_items_per_product" DESC, "product_id"

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id'))
             ->join(array('l' => 'line_items'),
                    'p.product_id = l.product_id',
                    array('line_items_per_product' => 'COUNT(*)'))
             ->group('p.product_id')
             ->order(array('line_items_per_product DESC',
                           'product_id'));
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.limit">

            <title>LIMIT 句の追加</title>

            <para>
                RDBMS によっては、SQL を拡張して、いわゆる
                <code>LIMIT</code> 句を使用できるようにしているものもあります。
                これは、結果セットの行数を、最大でも指定した数までに制限します。
                また、出力を始める前に読み飛ばす行数を指定することもできます。
                この機能を使用すると、結果セットの一部だけを取得することが簡単になります。
                たとえば、クエリの結果をページに分けて出力する場合などに便利です。
            </para>

            <para>
                <classname>Zend_Db_Select</classname> では、<code>limit()</code>
                メソッドを使用して結果の行数および読み飛ばしの行数を指定します。
                このメソッドの最初の引数は取得したい行数、
                そして二番目の引数は読み飛ばす行数となります。
            </para>

            <example id="zend.db.select.building.limit.example">

                <title>limit() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p
//   LIMIT 10, 20

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'))
             ->limit(10, 20);
]]></programlisting>

            </example>

            <note>

                <para>
                    <code>LIMIT</code> 構文は、すべての RDBMS
                    でサポートされているわけではありません。RDBMS によっては、
                    似た機能を別の構文でサポートしているものもあります。
                    各 <classname>Zend_Db_Adapter_Abstract</classname> クラスには、
                    その RDBMS に対応した適切な SQL を作成するメソッドが用意されています。
                </para>

            </note>

            <para>
                一方、<code>limitPage()</code> メソッドを用いることによっても行数とオフセットを指定できます。
                このメソッドは、クエリの結果セット全体から特定の箇所の連続した行のみを取得するものです。
                つまり、結果の「ページ」を指定することで、
                そのページに該当する部分の結果のみを取得するというわけです。
                <code>limitPage()</code> メソッドの最初の引数にページ数、
                2 番目の引数にページあたりの行数を指定します。
                どちらの引数も必須で、デフォルト値はありません。
            </para>

            <example id="zend.db.select.building.limit.example2">

                <title>limitPage() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p
//   LIMIT 10, 20

$select = $db->select()
             ->from(array('p' => 'products'),
                    array('product_id', 'product_name'))
             ->limitPage(2, 10);
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.distinct">

            <title>クエリ修飾子 DISTINCT の追加</title>

            <para>
                <code>distinct()</code> メソッドを使用すると、SQL クエリに
                <code>DISTINCT</code> キーワードを追加することができます。
            </para>

            <example id="zend.db.select.building.distinct.example">

                <title>distinct() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT DISTINCT p."product_name"
//   FROM "products" AS p

$select = $db->select()
             ->distinct()
             ->from(array('p' => 'products'), 'product_name');
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.building.for-update">

            <title>クエリ修飾子 FOR UPDATE の追加</title>

            <para>
                <code>forUpdate()</code> メソッドを使用すると、SQL クエリに
                <code>FOR UPDATE</code> 修飾子を追加することができます。
            </para>

            <example id="zend.db.select.building.for-update.example">

                <title>forUpdate() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT FOR UPDATE p.*
//   FROM "products" AS p

$select = $db->select()
             ->forUpdate()
             ->from(array('p' => 'products'));
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.select.execute">

        <title>Select クエリの実行</title>

        <para>
            この節では、<classname>Zend_Db_Select</classname> オブジェクトが表すクエリを実行する方法を説明します。
        </para>

        <sect3 id="zend.db.select.execute.query-adapter">

            <title>Db アダプタからの Select クエリの実行</title>

            <para>
                <classname>Zend_Db_Select</classname> オブジェクトが表すクエリを実行するには、それを
                <classname>Zend_Db_Adapter_Abstract</classname> オブジェクトの <code>query()</code>
                メソッドの最初の引数として渡します。すると、
                文字列のクエリのかわりに <classname>Zend_Db_Select</classname> オブジェクトを使用するようになります。
            </para>

            <para>
                <code>query()</code> メソッドは、アダプタの型によって
                <classname>Zend_Db_Statement</classname> あるいは PDOStatement
                型のオブジェクトを返します。
            </para>

            <example id="zend.db.select.execute.query-adapter.example">

                <title>Db アダプタの query() メソッドの使用例</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('products');

$stmt = $db->query($select);
$result = $stmt->fetchAll();
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.execute.query-select">

            <title>オブジェクトからの Select クエリの実行</title>

            <para>
                アダプタオブジェクトの <code>query()</code>
                メソッドを使用する以外の方法としては、<classname>Zend_Db_Select</classname>
                オブジェクトの <code>query()</code>
                メソッドを使用するものがあります。
                どちらのメソッドも、アダプタの型によって
                <classname>Zend_Db_Statement</classname> あるいは PDOStatement
                型のオブジェクトを返します。
            </para>

            <example id="zend.db.select.execute.query-select.example">

                <title>Select オブジェクトの query メソッドの使用例</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('products');

$stmt = $select->query();
$result = $stmt->fetchAll();
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.execute.tostring">

            <title>Select オブジェクトから SQL 文字列への変換</title>

            <para>
                <classname>Zend_Db_Select</classname> オブジェクトに対応する
                SQL クエリ文字列にアクセスしたい場合は、
                <code>__toString()</code> メソッドを使用します。
            </para>

            <example id="zend.db.select.execute.tostring.example">

                <title>__toString() メソッドの例</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('products');

$sql = $select->__toString();
echo "$sql\n";

// 出力は、次のような文字列になります
//   SELECT * FROM "products"
]]></programlisting>

            </example>

        </sect3>

    </sect2>

    <sect2 id="zend.db.select.other">

        <title>その他のメソッド</title>

        <para>
            この節では、これまでにあげてこなかった <classname>Zend_Db_Select</classname>
            クラスのメソッドである <code>getPart()</code> および
            <code>reset()</code> について説明します。
        </para>

        <sect3 id="zend.db.select.other.get-part">

            <title>Select オブジェクトの一部の取得</title>

            <para>
                <code>getPart()</code> メソッドは、SQL クエリの一部を返します。
                たとえば、このメソッドを使用すると、
                <code>WHERE</code> 句の式を表す配列や
                <code>SELECT</code> するカラム (あるいは式) の配列、または
                <code>LIMIT</code> 句のカウントやオフセットを取得することができます。
            </para>

            <para>
                返り値は、SQL の一部を抜き取った文字列ではありません。
                オブジェクトでの内部表現で、通常は値と式を含む配列となります。
                クエリの各部分によって、その構造は異なります。
            </para>

            <para>
                <code>getPart()</code> メソッドの引数はひとつで、
                Select クエリのどの部分を返すのかをここで指定します。
                たとえば、文字列 <code>'from'</code> を指定すると、
                Select オブジェクトが <code>FROM</code>
                句として保持しているテーブルの情報を返します。
                ここには結合している他のテーブルも含まれます。
            </para>

            <para>
                <classname>Zend_Db_Select</classname> クラスでは、SQL クエリの各部分を指定するための定数を定義しています。
                これらの定数、あるいはリテラル文字列のいずれかで指定することができます。
            </para>

            <table id="zend.db.select.other.get-part.table">

                <title>getPart() および reset() で使用する定数</title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>定数</entry>
                            <entry>文字列値</entry>
                        </row>
                    </thead>

                    <tbody>
                        <row>
                            <entry><classname>Zend_Db_Select::DISTINCT</classname></entry>
                            <entry><code>'distinct'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::FOR_UPDATE</classname></entry>
                            <entry><code>'forupdate'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::COLUMNS</classname></entry>
                            <entry><code>'columns'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::FROM</classname></entry>
                            <entry><code>'from'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::WHERE</classname></entry>
                            <entry><code>'where'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::GROUP</classname></entry>
                            <entry><code>'group'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::HAVING</classname></entry>
                            <entry><code>'having'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::ORDER</classname></entry>
                            <entry><code>'order'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::LIMIT_COUNT</classname></entry>
                            <entry><code>'limitcount'</code></entry>
                        </row>

                        <row>
                            <entry><classname>Zend_Db_Select::LIMIT_OFFSET</classname></entry>
                            <entry><code>'limitoffset'</code></entry>
                        </row>
                    </tbody>
                </tgroup>
            </table>

            <example id="zend.db.select.other.get-part.example">

                <title>getPart() メソッドの例</title>

                <programlisting role="php"><![CDATA[
$select = $db->select()
             ->from('products')
             ->order('product_id');

// 文字列リテラルを使用して指定することができます
$orderData = $select->getPart( 'order' );

// 同じことを、定数を用いて指定することもできます
$orderData = $select->getPart( Zend_Db_Select::ORDER );

// 返り値は、文字列ではなく配列となります。
// 各部分が異なる構造になっています。
print_r( $orderData );
]]></programlisting>

            </example>

        </sect3>

        <sect3 id="zend.db.select.other.reset">

            <title>Select オブジェクトの一部のリセット</title>

            <para>
                <code>reset()</code> メソッドを使用すると、
                SQL クエリの指定した部分のみを消去することができます。
                引数を省略した場合は、すべての部分を消去します。
            </para>

            <para>
                引数はひとつで、これは省略可能です。
                消去したい SQL の部分を、<code>getPart()</code>
                メソッドの引数と同じ文字列で指定します。
                クエリの指定した部分が、デフォルトの状態に戻ります。
            </para>

            <para>
                パラメータを省略すると、<code>reset()</code>
                はクエリのすべての部分をデフォルトの状態に戻します。
                これにより、<classname>Zend_Db_Select</classname> オブジェクトは初期状態と同等になります。
                つまり、最初にインスタンスを作成したときと同じ状態ということです。
            </para>

            <example id="zend.db.select.other.reset.example">

                <title>reset() メソッドの例</title>

                <programlisting role="php"><![CDATA[
// できあがるクエリは、このようになります
//   SELECT p.*
//   FROM "products" AS p
//   ORDER BY "product_name"

$select = $db->select()
             ->from(array('p' => 'products')
             ->order('product_name');

// 条件を変更し、別のカラムで並べ替えます
//   SELECT p.*
//   FROM "products" AS p
//   ORDER BY "product_id"

// 再定義するため、いちどこの部分を消去します
$select->reset( Zend_Db_Select::ORDER );

// そして異なるカラムを指定します
$select->order('product_id');

// クエリ全体を消去します
$select->reset();
]]></programlisting>

            </example>

        </sect3>

    </sect2>

</sect1>
<!--
vim:se ts=4 sw=4 et:
-->