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

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

    <title>Zend_Db_Select</title>

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

        <title>Introduction</title>

        <para>
            The <classname>Zend_Db_Select</classname> object represents a <acronym>SQL</acronym> <acronym>SELECT</acronym>
            query statement. The class has methods for adding individual parts to the query. You can
            specify some parts of the query using <acronym>PHP</acronym> methods and data structures, and the class
            forms the correct <acronym>SQL</acronym> syntax for you. After you build a query, you can execute the query
            as if you had written it as a string.
        </para>

        <para>
            The value offered by <classname>Zend_Db_Select</classname> includes:
        </para>

        <itemizedlist>
            <listitem>
                <para>
                    Object-oriented methods for specifying <acronym>SQL</acronym> queries in a piece-by-piece manner;
                </para>
            </listitem>

            <listitem>
                <para>
                    Database-independent abstraction of some parts of the <acronym>SQL</acronym> query;
                </para>
            </listitem>

            <listitem>
                <para>
                    Automatic quoting of metadata identifiers in most cases, to support identifiers
                    containing <acronym>SQL</acronym> reserved words and special characters;
                </para>
            </listitem>

            <listitem>
                <para>
                    Quoting identifiers and values, to help reduce risk of <acronym>SQL</acronym> injection attacks.
                </para>
            </listitem>
        </itemizedlist>

        <para>
            Using <classname>Zend_Db_Select</classname> is not mandatory. For very simple SELECT
            queries, it is usually simpler to specify the entire <acronym>SQL</acronym> query as a string and execute
            it using Adapter methods like <methodname>query()</methodname> or
            <methodname>fetchAll()</methodname>. Using
            <classname>Zend_Db_Select</classname> is helpful if you need to assemble a SELECT query
            procedurally, or based on conditional logic in your application.
        </para>

    </sect2>

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

        <title>Creating a Select Object</title>

        <para>
            You can create an instance of a <classname>Zend_Db_Select</classname> object using the
            <methodname>select()</methodname> method of a <classname>Zend_Db_Adapter_Abstract</classname>
            object.
        </para>

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

            <title>Example of the database adapter's select() method</title>

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

        </example>

        <para>
            Another way to create a <classname>Zend_Db_Select</classname> object is with its
            constructor, specifying the database adapter as an argument.
        </para>

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

            <title>Example of creating a new Select object</title>

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

        </example>

    </sect2>

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

        <title>Building Select queries</title>

        <para>
            When building the query, you can add clauses of the query one by one. There is a
            separate method to add each clause to the <classname>Zend_Db_Select</classname> object.
        </para>

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

            <title>Example of the using methods to add clauses</title>

            <programlisting language="php"><![CDATA[
// Create the Zend_Db_Select object
$select = $db->select();

// Add a FROM clause
$select->from( ...specify table and columns... )

// Add a WHERE clause
$select->where( ...specify search criteria... )

// Add an ORDER BY clause
$select->order( ...specify sorting criteria... );
]]></programlisting>

        </example>

        <para>
            You also can use most methods of the <classname>Zend_Db_Select</classname> object with a
            convenient fluent interface. A fluent interface means that each method returns a
            reference to the object on which it was called, so you can immediately call another
            method.
        </para>

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

            <title>Example of the using the fluent interface</title>

            <programlisting language="php"><![CDATA[
$select = $db->select()
    ->from( ...specify table and columns... )
    ->where( ...specify search criteria... )
    ->order( ...specify sorting criteria... );
]]></programlisting>

        </example>

        <para>
            The examples in this section show usage of the fluent interface, but you can use the
            non-fluent interface in all cases. It is often necessary to use the non-fluent
            interface, for example, if your application needs to perform some logic before adding a
            clause to a query.
        </para>

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

            <title>Adding a FROM clause</title>

            <para>
                Specify the table for this query using the <methodname>from()</methodname> method.
                You can specify the table name as a simple string.
                <classname>Zend_Db_Select</classname> applies identifier quoting around the table
                name, so you can use special characters.
            </para>

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

                <title>Example of the from() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT *
//   FROM "products"

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

            </example>

            <para>
                You can also specify the correlation name (sometimes called the "table alias") for
                a table. Instead of a simple string, use an associative array mapping the
                correlation name to the table name. In other clauses of the <acronym>SQL</acronym> query, use this
                correlation name. If your query joins more than one table,
                <classname>Zend_Db_Select</classname> generates unique correlation names based on
                the table names, for any tables for which you don't specify the correlation name.
            </para>

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

                <title>Example of specifying a table correlation name</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT p.*
//   FROM "products" AS p

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

            </example>

            <para>
                Some <acronym>RDBMS</acronym> brands support a leading schema specifier for a table. You can specify
                the table name as "<code>schemaName.tableName</code>", where
                <classname>Zend_Db_Select</classname> quotes each part individually, or you may
                specify the schema name separately. A schema name specified in the table name takes
                precedence over a schema provided separately in the event that both are provided.
            </para>

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

                <title>Example of specifying a schema name</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT *
//   FROM "myschema"."products"

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

// or

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

            </example>

        </sect3>

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

            <title>Adding Columns</title>

            <para>
                In the second argument of the <methodname>from()</methodname> method, you can
                specify the columns to select from the respective table. If you specify no columns,
                the default is "<code>*</code>", the <acronym>SQL</acronym> wildcard for "all columns".
            </para>

            <para>
                You can list the columns in a simple array of strings, or as an associative mapping
                of column alias to column name. If you only have one column to query, and you don't
                need to specify a column alias, you can list it as a plain string instead of an
                array.
            </para>

            <para>
                If you give an empty array as the columns argument, no columns from the respective
                table are included in the result set. See a
                <link linkend="zend.db.select.building.join.example-no-columns">code example</link>
                under the section on the <methodname>join()</methodname> method.
            </para>

            <para>
                You can specify the column name as "<code>correlationName.columnName</code>".
                <classname>Zend_Db_Select</classname> quotes each part individually. If you don't
                specify a correlation name for a column, it uses the correlation name for the table
                named in the current <methodname>from()</methodname> method.
            </para>

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

                <title>Examples of specifying columns</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

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

// Build the same query, specifying correlation names:
//   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'));

// Build this query with an alias for one column:
//   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>Adding Expression Columns</title>

            <para>
                Columns in <acronym>SQL</acronym> queries are sometimes expressions, not simply column names from a
                table. Expressions should not have correlation names or quoting applied. If your
                column string contains parentheses, <classname>Zend_Db_Select</classname> recognizes
                it as an expression.
            </para>

            <para>
                You also can create an object of type <classname>Zend_Db_Expr</classname>
                explicitly, to prevent a string from being treated as a column name.
                <classname>Zend_Db_Expr</classname> is a minimal class that contains a single
                string. <classname>Zend_Db_Select</classname> recognizes objects of type
                <classname>Zend_Db_Expr</classname> and converts them back to string, but does not
                apply any alterations, such as quoting or correlation names.
            </para>

            <note>

                <para>
                    Using <classname>Zend_Db_Expr</classname> for column names is not necessary if
                    your column expression contains parentheses;
                    <classname>Zend_Db_Select</classname> recognizes parentheses and treats the
                    string as an expression, skipping quoting and correlation names.
                </para>

            </note>

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

                <title>Examples of specifying columns containing expressions</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT p."product_id", LOWER(product_name)
//   FROM "products" AS p
// An expression with parentheses implicitly becomes
// a Zend_Db_Expr.

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

// Build this query:
//   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)')
                   );

// Build this query using Zend_Db_Expr explicitly:
//   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>
                In the cases above, <classname>Zend_Db_Select</classname> does not alter the string
                to apply correlation names or identifier quoting. If those changes are necessary to
                resolve ambiguity, you must make the changes manually in the string.
            </para>

            <para>
                If your column names are <acronym>SQL</acronym> keywords or contain special characters, you should use
                the Adapter's <methodname>quoteIdentifier()</methodname> method and interpolate the result into
                the string. The <methodname>quoteIdentifier()</methodname> method uses <acronym>SQL</acronym> quoting to delimit
                the identifier, which makes it clear that it is an identifier for a table or a
                column, and not any other part of <acronym>SQL</acronym> syntax.
            </para>

            <para>
                Your code is more database-independent if you use the
                <methodname>quoteIdentifier()</methodname> method instead of typing quotes literally in your
                string, because some <acronym>RDBMS</acronym> brands use nonstandard symbols for quoting identifiers.
                The <methodname>quoteIdentifier()</methodname> method is designed to use the appropriate
                quoting symbols based on the adapter type. The <methodname>quoteIdentifier()</methodname>
                method also escapes any quote characters that appear within the identifier name
                itself.
            </para>

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

                <title>Examples of quoting columns in an expression</title>

                <programlisting language="php"><![CDATA[
// Build this query,
// quoting the special column name "from" in the expression:
//   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>Adding columns to an existing FROM or JOIN table</title>

            <para>
                There may be cases where you wish to add columns to an existing FROM or JOIN table
                after those methods have been called. The <methodname>columns()</methodname> method allows you
                to add specific columns at any point before the query is executed. You can supply
                the columns as either a string or <classname>Zend_Db_Expr</classname> or as an array
                of these elements. The second argument to this method can be omitted, implying that
                the columns are to be added to the FROM table, otherwise an existing correlation
                name must be used.
            </para>

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

                <title>Examples of adding columns with the columns() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT p."product_id", p."product_name"
//   FROM "products" AS p

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

// Build the same query, specifying correlation names:
//   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');
             // Alternatively use columns('p.product_name')
]]></programlisting>

            </example>

        </sect3>

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

            <title>Adding Another Table to the Query with JOIN</title>

            <para>
                Many useful queries involve using a <acronym>JOIN</acronym> to combine rows from multiple
                tables. You can add tables to a <classname>Zend_Db_Select</classname> query using
                the <methodname>join()</methodname> method. Using this method is similar to the
                <methodname>from()</methodname> method, except you can also specify a join condition in most
                cases.
            </para>

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

                <title>Example of the join() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                The second argument to <methodname>join()</methodname> is a string that is the join condition.
                This is an expression that declares the criteria by which rows in one table match
                rows in the other table. You can use correlation names in this expression.
            </para>

            <note>

                <para>
                    No quoting is applied to the expression you specify for the join condition; if
                    you have column names that need to be quoted, you must use
                    <methodname>quoteIdentifier()</methodname> as you form the string for the join condition.
                </para>

            </note>

            <para>
                The third argument to <methodname>join()</methodname> is an array of column names, like that
                used in the <methodname>from()</methodname> method. It defaults to "<code>*</code>", supports
                correlation names, expressions, and <classname>Zend_Db_Expr</classname> in the same
                way as the array of column names in the <methodname>from()</methodname> method.
            </para>

            <para>
                To select no columns from a table, use an empty array for the list of columns. This
                usage works in the <methodname>from()</methodname> method too, but typically you want some
                columns from the primary table in your queries, whereas you might want no columns
                from a joined table.
            </para>

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

                <title>Example of specifying no columns</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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() ); // empty list of columns
]]></programlisting>

                <para>
                    Note the empty <methodname>array()</methodname> in the above example in place of a list of
                    columns from the joined table.
                </para>

            </example>

            <para>
                <acronym>SQL</acronym> has several types of joins. See the list below for the methods to support
                different join types in <classname>Zend_Db_Select</classname>.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <command>INNER JOIN</command> with the
                        <methodname>join(table, join, [columns])</methodname> or
                        <methodname>joinInner(table, join, [columns])</methodname> methods.
                    </para>

                    <para>
                        This may be the most common type of join. Rows from each table are compared
                        using the join condition you specify. The result set includes only the rows
                        that satisfy the join condition. The result set can be empty if no rows
                        satisfy this condition.
                    </para>

                    <para>
                        All <acronym>RDBMS</acronym> brands support this join type.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <command>LEFT JOIN</command> with the
                        <methodname>joinLeft(table, condition, [columns])</methodname> method.
                    </para>

                    <para>
                        All rows from the left operand table are included, matching rows from the
                        right operand table included, and the columns from the right operand table
                        are filled with NULLs if no row exists matching the left table.
                    </para>

                    <para>
                        All <acronym>RDBMS</acronym> brands support this join type.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <command>RIGHT JOIN</command> with the
                        <methodname>joinRight(table, condition, [columns])</methodname> method.
                    </para>

                    <para>
                        Right outer join is the complement of left outer join. All rows from the
                        right operand table are included, matching rows from the left operand table
                        included, and the columns from the left operand table are filled with NULLs
                        if no row exists matching the right table.
                    </para>

                    <para>
                        Some <acronym>RDBMS</acronym> brands don't support this join type, but in general any right
                        join can be represented as a left join by reversing the order of the
                        tables.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <command>FULL JOIN</command> with the
                        <methodname>joinFull(table, condition, [columns])</methodname> method.
                    </para>

                    <para>
                        A full outer join is like combining a left outer join and a right outer
                        join. All rows from both tables are included, paired with each other on the
                        same row of the result set if they satisfy the join condition, and
                        otherwise paired with NULLs in place of columns from the other table.
                    </para>

                    <para>
                        Some <acronym>RDBMS</acronym> brands don't support this join type.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <command>CROSS JOIN</command> with the
                        <methodname>joinCross(table, [columns])</methodname> method.
                    </para>

                    <para>
                        A cross join is a Cartesian product. Every row in the first table is
                        matched to every row in the second table. Therefore the number of rows in
                        the result set is equal to the product of the number of rows in each table.
                        You can filter the result set using conditions in a WHERE clause; in this
                        way a cross join is similar to the old <acronym>SQL</acronym>-89 join syntax.
                    </para>

                    <para>
                        The <methodname>joinCross()</methodname> method has no parameter to specify the join
                        condition. Some <acronym>RDBMS</acronym> brands don't support this join type.
                    </para>
                </listitem>

                <listitem>
                    <para>
                        <command>NATURAL JOIN</command> with the
                        <methodname>joinNatural(table, [columns])</methodname> method.
                    </para>

                    <para>
                        A natural join compares any column(s) that appear with the same name in
                        both tables. The comparison is equality of all the column(s); comparing the
                        columns using inequality is not a natural join. Only natural inner joins
                        are supported by this <acronym>API</acronym>, even though <acronym>SQL</acronym> permits natural outer joins as
                        well.
                    </para>

                    <para>
                        The <methodname>joinNatural()</methodname> method has no parameter to specify the join
                        condition.
                    </para>
                </listitem>
            </itemizedlist>

            <para>
                In addition to these join methods, you can simplify your queries by using the
                JoinUsing methods. Instead of supplying a full condition to your join, you simply
                pass the column name on which to join and the <classname>Zend_Db_Select</classname>
                object completes the condition for you.
            </para>

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

                <title>Example of the joinUsing() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                Each of the applicable join methods in the <classname>Zend_Db_Select</classname>
                component has a corresponding 'using' method.
            </para>

            <itemizedlist>
                <listitem>
                    <para>
                        <methodname>joinUsing(table, join, [columns])</methodname> and
                        <methodname>joinInnerUsing(table, join, [columns])</methodname>
                    </para>
                </listitem>

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

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

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

        </sect3>

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

            <title>Adding a WHERE Clause</title>

            <para>
                You can specify criteria for restricting rows of the result set using the
                <methodname>where()</methodname> method. The first argument of this method is a <acronym>SQL</acronym> expression,
                and this expression is used in a <acronym>SQL</acronym> <acronym>WHERE</acronym> clause in the query.
            </para>

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

                <title>Example of the where() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                    No quoting is applied to expressions given to the <methodname>where()</methodname> or
                    <methodname>orWhere()</methodname> methods. If you have column names that need to be
                    quoted, you must use <methodname>quoteIdentifier()</methodname> as you form the string for
                    the condition.
                </para>

            </note>

            <para>
                The second argument to the <methodname>where()</methodname> method is optional. It is a value
                to substitute into the expression. <classname>Zend_Db_Select</classname> quotes the
                value and substitutes it for a question-mark ("<code>?</code>") symbol in the
                expression.
            </para>

            <para>
                This method accepts only one parameter. If you have an expression into which you
                need to substitute multiple variables, you must format the string manually,
                interpolating variables and performing quoting yourself.
            </para>

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

                <title>Example of a parameter in the where() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                You can invoke the <methodname>where()</methodname> method multiple times on the same
                <classname>Zend_Db_Select</classname> object. The resulting query combines the
                multiple terms together using <acronym>AND</acronym> between them.
            </para>

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

                <title>Example of multiple where() methods</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                If you need to combine terms together using <acronym>OR</acronym>, use the
                <methodname>orWhere()</methodname> method. This method is used in the same way as the
                <methodname>where()</methodname> method, except that the term specified is preceded by
                <acronym>OR</acronym>, instead of <acronym>AND</acronym>.
            </para>

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

                <title>Example of the orWhere() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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> automatically puts parentheses around each
                expression you specify using the <methodname>where()</methodname> or <methodname>orWhere()</methodname>
                methods. This helps to ensure that Boolean operator precedence does not cause
                unexpected results.
            </para>

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

                <title>Example of parenthesizing Boolean expressions</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                In the example above, the results would be quite different without the parentheses,
                because <acronym>AND</acronym> has higher precedence than <acronym>OR</acronym>.
                <classname>Zend_Db_Select</classname> applies the parentheses so the effect is that
                each expression in successive calls to the <methodname>where()</methodname> bind more tightly
                than the <acronym>AND</acronym> that combines the expressions.
            </para>

        </sect3>

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

            <title>Adding a GROUP BY Clause</title>

            <para>
                In <acronym>SQL</acronym>, the <command>GROUP BY</command> clause allows you to reduce the rows of a query
                result set to one row per unique value found in the column(s) named in the
                <command>GROUP BY</command> clause.
            </para>

            <para>
                In <classname>Zend_Db_Select</classname>, you can specify the column(s) to use for
                calculating the groups of rows using the <methodname>group()</methodname> method. The argument
                to this method is a column or an array of columns to use in the
                <command>GROUP BY</command> clause.
            </para>

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

                <title>Example of the group() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                Like the columns array in the <methodname>from()</methodname> method, you can use correlation
                names in the column name strings, and the column is quoted as an identifier unless
                the string contains parentheses or is an object of type
                <classname>Zend_Db_Expr</classname>.
            </para>

        </sect3>

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

            <title>Adding a HAVING Clause</title>

            <para>
                In <acronym>SQL</acronym>, the <constant>HAVING</constant> clause applies a restriction condition on groups of
                rows. This is similar to how a <constant>WHERE</constant> clause applies a restriction
                condition on rows. But the two clauses are different because <constant>WHERE</constant>
                conditions are applied before groups are defined, whereas <constant>HAVING</constant>
                conditions are applied after groups are defined.
            </para>

            <para>
                In <classname>Zend_Db_Select</classname>, you can specify conditions for restricting
                groups using the <methodname>having()</methodname> method. Its usage is similar to that of the
                <methodname>where()</methodname> method. The first argument is a string containing a <acronym>SQL</acronym>
                expression. The optional second argument is a value that is used to replace a
                positional parameter placeholder in the <acronym>SQL</acronym> expression. Expressions given in
                multiple invocations of the <methodname>having()</methodname> method are combined using the
                Boolean <constant>AND</constant> operator, or the <code>OR</code> operator if you use the
                <methodname>orHaving()</methodname> method.
            </para>

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

                <title>Example of the having() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                    No quoting is applied to expressions given to the <methodname>having()</methodname> or
                    <methodname>orHaving()</methodname> methods. If you have column names that need to be
                    quoted, you must use <methodname>quoteIdentifier()</methodname> as you form the string for
                    the condition.
                </para>

            </note>

        </sect3>

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

            <title>Adding an ORDER BY Clause</title>

            <para>
                In <acronym>SQL</acronym>, the <code>ORDER BY</code> clause specifies one or more columns or
                expressions by which the result set of a query is sorted. If multiple columns are
                listed, the secondary columns are used to resolve ties; the sort order is
                determined by the secondary columns if the preceding columns contain identical
                values. The default sorting is from least value to greatest value. You can also
                sort by greatest value to least value for a given column in the list by specifying
                the keyword <constant>DESC</constant> after that column.
            </para>

            <para>
                In <classname>Zend_Db_Select</classname>, you can use the <methodname>order()</methodname>
                method to specify a column or an array of columns by which to sort. Each element of
                the array is a string naming a column. Optionally with the <constant>ASC</constant>
                <constant>DESC</constant> keyword following it, separated by a space.
            </para>

            <para>
                Like in the <methodname>from()</methodname> and <methodname>group()</methodname> methods, column names are
                quoted as identifiers, unless they contain parentheses or are an object of
                type <classname>Zend_Db_Expr</classname>.
            </para>

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

                <title>Example of the order() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>Adding a LIMIT Clause</title>

            <para>
                Some <acronym>RDBMS</acronym> brands extend <acronym>SQL</acronym> with a query clause known as the <constant>LIMIT</constant>
                clause. This clause reduces the number of rows in the result set to at most a
                number you specify. You can also specify to skip a number of rows before starting
                to output. This feature makes it easy to take a subset of a result set, for example
                when displaying query results on progressive pages of output.
            </para>

            <para>
                In <classname>Zend_Db_Select</classname>, you can use the <methodname>limit()</methodname>
                method to specify the count of rows and the number of rows to skip. The first
                argument to this method is the desired count of rows. The second argument is the
                number of rows to skip.
            </para>

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

                <title>Example of the limit() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>
                    The <constant>LIMIT</constant> syntax is not supported by all <acronym>RDBMS</acronym> brands. Some <acronym>RDBMS</acronym>
                    require different syntax to support similar functionality. Each
                    <classname>Zend_Db_Adapter_Abstract</classname> class includes a method to
                    produce <acronym>SQL</acronym> appropriate for that <acronym>RDBMS</acronym>.
                </para>

            </note>

            <para>
                Use the <methodname>limitPage()</methodname> method for an alternative way to specify row count
                and offset. This method allows you to limit the result set to one of a series of
                fixed-length subsets of rows from the query's total result set. In other words, you
                specify the length of a "page" of results, and the ordinal number of the single
                page of results you want the query to return. The page number is the first argument
                of the <methodname>limitPage()</methodname> method, and the page length is the second argument.
                Both arguments are required; they have no default values.
            </para>

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

                <title>Example of the limitPage() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>Adding the DISTINCT Query Modifier</title>

            <para>
                The <methodname>distinct()</methodname> method enables you to add the <constant>DISTINCT</constant>
                keyword to your <acronym>SQL</acronym> query.
            </para>

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

                <title>Example of the distinct() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>Adding the FOR UPDATE Query Modifier</title>

            <para>
                The <methodname>forUpdate()</methodname> method enables you to add the <code>FOR UPDATE</code>
                modifier to your <acronym>SQL</acronym> query.
            </para>

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

                <title>Example of forUpdate() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   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>Executing Select Queries</title>

        <para>
            This section describes how to execute the query represented by a
            <classname>Zend_Db_Select</classname> object.
        </para>

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

            <title>Executing Select Queries from the Db Adapter</title>

            <para>
                You can execute the query represented by the <classname>Zend_Db_Select</classname>
                object by passing it as the first argument to the <methodname>query()</methodname> method of a
                <classname>Zend_Db_Adapter_Abstract</classname> object. Use the
                <classname>Zend_Db_Select</classname> objects instead of a string query.
            </para>

            <para>
                The <methodname>query()</methodname> method returns an object of type
                <classname>Zend_Db_Statement</classname> or <acronym>PDO</acronym>Statement, depending on the adapter
                type.
            </para>

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

                <title>Example using the Db adapter's query() method</title>

                <programlisting language="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>Executing Select Queries from the Object</title>

            <para>
                As an alternative to using the <methodname>query()</methodname> method of the adapter object,
                you can use the <methodname>query()</methodname> method of the
                <classname>Zend_Db_Select</classname> object. Both methods return an object of type
                <classname>Zend_Db_Statement</classname> or <acronym>PDO</acronym>Statement, depending on the adapter
                type.
            </para>

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

                <title>Example using the Select object's query method</title>

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

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

            </example>

        </sect3>

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

            <title>Converting a Select Object to a SQL String</title>

            <para>
                If you need access to a string representation of the <acronym>SQL</acronym> query corresponding to the
                <classname>Zend_Db_Select</classname> object, use the <methodname>__toString()</methodname>
                method.
            </para>

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

                <title>Example of the __toString() method</title>

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

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

// The output is the string:
//   SELECT * FROM "products"
]]></programlisting>

            </example>

        </sect3>

    </sect2>

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

        <title>Other methods</title>

        <para>
            This section describes other methods of the <classname>Zend_Db_Select</classname> class
            that are not covered above: <methodname>getPart()</methodname> and <methodname>reset()</methodname>.
        </para>

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

            <title>Retrieving Parts of the Select Object</title>

            <para>
                The <methodname>getPart()</methodname> method returns a representation of one part of your <acronym>SQL</acronym>
                query. For example, you can use this method to return the array of expressions for
                the <constant>WHERE</constant> clause, or the array of columns (or column expressions) that
                are in the <constant>SELECT</constant> list, or the values of the count and offset for the
                <constant>LIMIT</constant> clause.
            </para>

            <para>
                The return value is not a string containing a fragment of <acronym>SQL</acronym> syntax. The return
                value is an internal representation, which is typically an array structure
                containing values and expressions. Each part of the query has a different
                structure.
            </para>

            <para>
                The single argument to the <methodname>getPart()</methodname> method is a string that
                identifies which part of the Select query to return. For example, the string
                <code>'from'</code> identifies the part of the Select object that stores
                information about the tables in the <constant>FROM</constant> clause, including joined
                tables.
            </para>

            <para>
                The <classname>Zend_Db_Select</classname> class defines constants you can use for
                parts of the <acronym>SQL</acronym> query. You can use these constant definitions, or you can the
                literal strings.
            </para>

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

                <title>Constants used by getPart() and reset()</title>

                <tgroup cols="2">
                    <thead>
                        <row>
                            <entry>Constant</entry>
                            <entry>String value</entry>
                        </row>
                    </thead>

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

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

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

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

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

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

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

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

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

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

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

                <title>Example of the getPart() method</title>

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

// You can use a string literal to specify the part
$orderData = $select->getPart( 'order' );

// You can use a constant to specify the same part
$orderData = $select->getPart( Zend_Db_Select::ORDER );

// The return value may be an array structure, not a string.
// Each part has a different structure.
print_r( $orderData );
]]></programlisting>

            </example>

        </sect3>

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

            <title>Resetting Parts of the Select Object</title>

            <para>
                The <methodname>reset()</methodname> method enables you to clear one specified part of the <acronym>SQL</acronym>
                query, or else clear all parts of the <acronym>SQL</acronym> query if you omit the argument.
            </para>

            <para>
                The single argument is optional. You can specify the part of the query to clear,
                using the same strings you used in the argument to the <methodname>getPart()</methodname>
                method. The part of the query you specify is reset to a default state.
            </para>

            <para>
                If you omit the parameter, <methodname>reset()</methodname> changes all parts of the query to
                their default state. This makes the <classname>Zend_Db_Select</classname> object
                equivalent to a new object, as though you had just instantiated it.
            </para>

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

                <title>Example of the reset() method</title>

                <programlisting language="php"><![CDATA[
// Build this query:
//   SELECT p.*
//   FROM "products" AS p
//   ORDER BY "product_name"

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

// Changed requirement, instead order by a different columns:
//   SELECT p.*
//   FROM "products" AS p
//   ORDER BY "product_id"

// Clear one part so we can redefine it
$select->reset( Zend_Db_Select::ORDER );

// And specify a different column
$select->order('product_id');

// Clear all parts of the query
$select->reset();
]]></programlisting>

            </example>

        </sect3>

    </sect2>

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