documentation/manual/en/module_specs/Zend_Db_Select.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.db.select">
   4     <title>Zend_Db_Select</title>
   5
   6     <sect2 id="zend.db.select.introduction">
   7         <title>Introduction</title>
   8
   9         <para>
  10             The <classname>Zend_Db_Select</classname> object represents a <acronym>SQL</acronym>
  11             <acronym>SELECT</acronym> query statement. The class has methods for adding individual
  12             parts to the query. You can specify some parts of the query using <acronym>PHP</acronym>
  13             methods and data structures, and the class forms the correct <acronym>SQL</acronym>
  14             syntax for you. After you build a query, you can execute the query as if you had written
  15             it as a string.
  16         </para>
  17
  18         <para>
  19             The value offered by <classname>Zend_Db_Select</classname> includes:
  20         </para>
  21
  22         <itemizedlist>
  23             <listitem>
  24                 <para>
  25                     Object-oriented methods for specifying <acronym>SQL</acronym> queries in a
  26                     piece-by-piece manner;
  27                 </para>
  28             </listitem>
  29
  30             <listitem>
  31                 <para>
  32                     Database-independent abstraction of some parts of the <acronym>SQL</acronym>
  33                     query;
  34                 </para>
  35             </listitem>
  36
  37             <listitem>
  38                 <para>
  39                     Automatic quoting of metadata identifiers in most cases, to support identifiers
  40                     containing <acronym>SQL</acronym> reserved words and special characters;
  41                 </para>
  42             </listitem>
  43
  44             <listitem>
  45                 <para>
  46                     Quoting identifiers and values, to help reduce risk of <acronym>SQL</acronym>
  47                     injection attacks.
  48                 </para>
  49             </listitem>
  50         </itemizedlist>
  51
  52         <para>
  53             Using <classname>Zend_Db_Select</classname> is not mandatory. For very simple
  54             <acronym>SELECT</acronym> queries, it is usually simpler to specify the entire
  55             <acronym>SQL</acronym> query as a string and execute it using Adapter methods like
  56             <methodname>query()</methodname> or <methodname>fetchAll()</methodname>. Using
  57             <classname>Zend_Db_Select</classname> is helpful if you need to assemble a
  58             <acronym>SELECT</acronym> query procedurally, or based on conditional logic in your
  59             application.
  60         </para>
  61     </sect2>
  62
  63     <sect2 id="zend.db.select.creating">
  64         <title>Creating a Select Object</title>
  65
  66         <para>
  67             You can create an instance of a <classname>Zend_Db_Select</classname> object using the
  68             <methodname>select()</methodname> method of a
  69             <classname>Zend_Db_Adapter_Abstract</classname> object.
  70         </para>
  71
  72         <example id="zend.db.select.creating.example-db">
  73             <title>Example of the database adapter's select() method</title>
  74
  75             <programlisting language="php"><![CDATA[
  76 $db = Zend_Db::factory( ...options... );
  77 $select = $db->select();
  78 ]]></programlisting>
  79         </example>
  80
  81         <para>
  82             Another way to create a <classname>Zend_Db_Select</classname> object is with its
  83             constructor, specifying the database adapter as an argument.
  84         </para>
  85
  86         <example id="zend.db.select.creating.example-new">
  87             <title>Example of creating a new Select object</title>
  88
  89             <programlisting language="php"><![CDATA[
  90 $db = Zend_Db::factory( ...options... );
  91 $select = new Zend_Db_Select($db);
  92 ]]></programlisting>
  93         </example>
  94     </sect2>
  95
  96     <sect2 id="zend.db.select.building">
  97         <title>Building Select queries</title>
  98
  99         <para>
 100             When building the query, you can add clauses of the query one by one. There is a
 101             separate method to add each clause to the <classname>Zend_Db_Select</classname> object.
 102         </para>
 103
 104         <example id="zend.db.select.building.example">
 105             <title>Example of the using methods to add clauses</title>
 106
 107             <programlisting language="php"><![CDATA[
 108 // Create the Zend_Db_Select object
 109 $select = $db->select();
 110
 111 // Add a FROM clause
 112 $select->from( ...specify table and columns... )
 113
 114 // Add a WHERE clause
 115 $select->where( ...specify search criteria... )
 116
 117 // Add an ORDER BY clause
 118 $select->order( ...specify sorting criteria... );
 119 ]]></programlisting>
 120         </example>
 121
 122         <para>
 123             You also can use most methods of the <classname>Zend_Db_Select</classname> object with a
 124             convenient fluent interface. A fluent interface means that each method returns a
 125             reference to the object on which it was called, so you can immediately call another
 126             method.
 127         </para>
 128
 129         <example id="zend.db.select.building.example-fluent">
 130             <title>Example of the using the fluent interface</title>
 131
 132             <programlisting language="php"><![CDATA[
 133 $select = $db->select()
 134     ->from( ...specify table and columns... )
 135     ->where( ...specify search criteria... )
 136     ->order( ...specify sorting criteria... );
 137 ]]></programlisting>
 138         </example>
 139
 140         <para>
 141             The examples in this section show usage of the fluent interface, but you can use the
 142             non-fluent interface in all cases. It is often necessary to use the non-fluent
 143             interface, for example, if your application needs to perform some logic before adding a
 144             clause to a query.
 145         </para>
 146
 147         <sect3 id="zend.db.select.building.from">
 148             <title>Adding a FROM clause</title>
 149
 150             <para>
 151                 Specify the table for this query using the <methodname>from()</methodname> method.
 152                 You can specify the table name as a simple string.
 153                 <classname>Zend_Db_Select</classname> applies identifier quoting around the table
 154                 name, so you can use special characters.
 155             </para>
 156
 157             <example id="zend.db.select.building.from.example">
 158                 <title>Example of the from() method</title>
 159
 160                 <programlisting language="php"><![CDATA[
 161 // Build this query:
 162 //   SELECT *
 163 //   FROM "products"
 164
 165 $select = $db->select()
 166              ->from( 'products' );
 167 ]]></programlisting>
 168             </example>
 169
 170             <para>
 171                 You can also specify the correlation name (sometimes called the "table alias") for
 172                 a table. Instead of a simple string, use an associative array mapping the
 173                 correlation name to the table name. In other clauses of the <acronym>SQL</acronym>
 174                 query, use this correlation name. If your query joins more than one table,
 175                 <classname>Zend_Db_Select</classname> generates unique correlation names based on
 176                 the table names, for any tables for which you don't specify the correlation name.
 177             </para>
 178
 179             <example id="zend.db.select.building.from.example-cname">
 180                 <title>Example of specifying a table correlation name</title>
 181
 182                 <programlisting language="php"><![CDATA[
 183 // Build this query:
 184 //   SELECT p.*
 185 //   FROM "products" AS p
 186
 187 $select = $db->select()
 188              ->from( array('p' => 'products') );
 189 ]]></programlisting>
 190             </example>
 191
 192             <para>
 193                 Some <acronym>RDBMS</acronym> brands support a leading schema specifier for a table.
 194                 You can specify the table name as "<command>schemaName.tableName</command>", where
 195                 <classname>Zend_Db_Select</classname> quotes each part individually, or you may
 196                 specify the schema name separately. A schema name specified in the table name takes
 197                 precedence over a schema provided separately in the event that both are provided.
 198             </para>
 199
 200             <example id="zend.db.select.building.from.example-schema">
 201                 <title>Example of specifying a schema name</title>
 202
 203                 <programlisting language="php"><![CDATA[
 204 // Build this query:
 205 //   SELECT *
 206 //   FROM "myschema"."products"
 207
 208 $select = $db->select()
 209              ->from( 'myschema.products' );
 210
 211 // or
 212
 213 $select = $db->select()
 214              ->from('products', '*', 'myschema');
 215 ]]></programlisting>
 216             </example>
 217         </sect3>
 218
 219         <sect3 id="zend.db.select.building.columns">
 220             <title>Adding Columns</title>
 221
 222             <para>
 223                 In the second argument of the <methodname>from()</methodname> method, you can
 224                 specify the columns to select from the respective table. If you specify no columns,
 225                 the default is "<emphasis>*</emphasis>", the <acronym>SQL</acronym> wildcard for
 226                 "all columns".
 227             </para>
 228
 229             <para>
 230                 You can list the columns in a simple array of strings, or as an associative mapping
 231                 of column alias to column name. If you only have one column to query, and you don't
 232                 need to specify a column alias, you can list it as a plain string instead of an
 233                 array.
 234             </para>
 235
 236             <para>
 237                 If you give an empty array as the columns argument, no columns from the respective
 238                 table are included in the result set. See a
 239                 <link linkend="zend.db.select.building.join.example-no-columns">code example</link>
 240                 under the section on the <methodname>join()</methodname> method.
 241             </para>
 242
 243             <para>
 244                 You can specify the column name as "<command>correlationName.columnName</command>".
 245                 <classname>Zend_Db_Select</classname> quotes each part individually. If you don't
 246                 specify a correlation name for a column, it uses the correlation name for the table
 247                 named in the current <methodname>from()</methodname> method.
 248             </para>
 249
 250             <example id="zend.db.select.building.columns.example">
 251                 <title>Examples of specifying columns</title>
 252
 253                 <programlisting language="php"><![CDATA[
 254 // Build this query:
 255 //   SELECT p."product_id", p."product_name"
 256 //   FROM "products" AS p
 257
 258 $select = $db->select()
 259              ->from(array('p' => 'products'),
 260                     array('product_id', 'product_name'));
 261
 262 // Build the same query, specifying correlation names:
 263 //   SELECT p."product_id", p."product_name"
 264 //   FROM "products" AS p
 265
 266 $select = $db->select()
 267              ->from(array('p' => 'products'),
 268                     array('p.product_id', 'p.product_name'));
 269
 270 // Build this query with an alias for one column:
 271 //   SELECT p."product_id" AS prodno, p."product_name"
 272 //   FROM "products" AS p
 273
 274 $select = $db->select()
 275              ->from(array('p' => 'products'),
 276                     array('prodno' => 'product_id', 'product_name'));
 277 ]]></programlisting>
 278             </example>
 279         </sect3>
 280
 281         <sect3 id="zend.db.select.building.columns-expr">
 282             <title>Adding Expression Columns</title>
 283
 284             <para>
 285                 Columns in <acronym>SQL</acronym> queries are sometimes expressions, not simply
 286                 column names from a table. Expressions should not have correlation names or quoting
 287                 applied. If your column string contains parentheses,
 288                 <classname>Zend_Db_Select</classname> recognizes it as an expression.
 289             </para>
 290
 291             <para>
 292                 You also can create an object of type <classname>Zend_Db_Expr</classname>
 293                 explicitly, to prevent a string from being treated as a column name.
 294                 <classname>Zend_Db_Expr</classname> is a minimal class that contains a single
 295                 string. <classname>Zend_Db_Select</classname> recognizes objects of type
 296                 <classname>Zend_Db_Expr</classname> and converts them back to string, but does not
 297                 apply any alterations, such as quoting or correlation names.
 298             </para>
 299
 300             <note>
 301                 <para>
 302                     Using <classname>Zend_Db_Expr</classname> for column names is not necessary if
 303                     your column expression contains parentheses;
 304                     <classname>Zend_Db_Select</classname> recognizes parentheses and treats the
 305                     string as an expression, skipping quoting and correlation names.
 306                 </para>
 307             </note>
 308
 309             <example id="zend.db.select.building.columns-expr.example">
 310                 <title>Examples of specifying columns containing expressions</title>
 311
 312                 <programlisting language="php"><![CDATA[
 313 // Build this query:
 314 //   SELECT p."product_id", LOWER(product_name)
 315 //   FROM "products" AS p
 316 // An expression with parentheses implicitly becomes
 317 // a Zend_Db_Expr.
 318
 319 $select = $db->select()
 320              ->from(array('p' => 'products'),
 321                     array('product_id', 'LOWER(product_name)'));
 322
 323 // Build this query:
 324 //   SELECT p."product_id", (p.cost * 1.08) AS cost_plus_tax
 325 //   FROM "products" AS p
 326
 327 $select = $db->select()
 328              ->from(array('p' => 'products'),
 329                     array('product_id',
 330                           'cost_plus_tax' => '(p.cost * 1.08)')
 331                    );
 332
 333 // Build this query using Zend_Db_Expr explicitly:
 334 //   SELECT p."product_id", p.cost * 1.08 AS cost_plus_tax
 335 //   FROM "products" AS p
 336
 337 $select = $db->select()
 338              ->from(array('p' => 'products'),
 339                     array('product_id',
 340                           'cost_plus_tax' =>
 341                               new Zend_Db_Expr('p.cost * 1.08'))
 342                     );
 343 ]]></programlisting>
 344             </example>
 345
 346             <para>
 347                 In the cases above, <classname>Zend_Db_Select</classname> does not alter the string
 348                 to apply correlation names or identifier quoting. If those changes are necessary to
 349                 resolve ambiguity, you must make the changes manually in the string.
 350             </para>
 351
 352             <para>
 353                 If your column names are <acronym>SQL</acronym> keywords or contain special
 354                 characters, you should use the Adapter's <methodname>quoteIdentifier()</methodname>
 355                 method and interpolate the result into the string. The
 356                 <methodname>quoteIdentifier()</methodname> method uses <acronym>SQL</acronym>
 357                 quoting to delimit the identifier, which makes it clear that it is an identifier for
 358                 a table or a column, and not any other part of <acronym>SQL</acronym> syntax.
 359             </para>
 360
 361             <para>
 362                 Your code is more database-independent if you use the
 363                 <methodname>quoteIdentifier()</methodname> method instead of typing quotes literally
 364                 in your string, because some <acronym>RDBMS</acronym> brands use nonstandard symbols
 365                 for quoting identifiers. The <methodname>quoteIdentifier()</methodname> method is
 366                 designed to use the appropriate quoting symbols based on the adapter type. The
 367                 <methodname>quoteIdentifier()</methodname> method also escapes any quote characters
 368                 that appear within the identifier name itself.
 369             </para>
 370
 371             <example id="zend.db.select.building.columns-quoteid.example">
 372                 <title>Examples of quoting columns in an expression</title>
 373
 374                 <programlisting language="php"><![CDATA[
 375 // Build this query,
 376 // quoting the special column name "from" in the expression:
 377 //   SELECT p."from" + 10 AS origin
 378 //   FROM "products" AS p
 379
 380 $select = $db->select()
 381              ->from(array('p' => 'products'),
 382                     array('origin' =>
 383                               '(p.' . $db->quoteIdentifier('from') . ' + 10)')
 384                    );
 385 ]]></programlisting>
 386             </example>
 387         </sect3>
 388
 389         <sect3 id="zend.db.select.building.columns-atomic">
 390             <title>Adding columns to an existing FROM or JOIN table</title>
 391
 392             <para>
 393                 There may be cases where you wish to add columns to an existing
 394                 <acronym>FROM</acronym> or <acronym>JOIN</acronym> table after those methods have
 395                 been called. The <methodname>columns()</methodname> method allows you to add
 396                 specific columns at any point before the query is executed. You can supply the
 397                 columns as either a string or <classname>Zend_Db_Expr</classname> or as an array of
 398                 these elements. The second argument to this method can be omitted, implying that the
 399                 columns are to be added to the <acronym>FROM</acronym> table, otherwise an existing
 400                 correlation name must be used.
 401             </para>
 402
 403             <example id="zend.db.select.building.columns-atomic.example">
 404                 <title>Examples of adding columns with the columns() method</title>
 405
 406                 <programlisting language="php"><![CDATA[
 407 // Build this query:
 408 //   SELECT p."product_id", p."product_name"
 409 //   FROM "products" AS p
 410
 411 $select = $db->select()
 412              ->from(array('p' => 'products'), 'product_id')
 413              ->columns('product_name');
 414
 415 // Build the same query, specifying correlation names:
 416 //   SELECT p."product_id", p."product_name"
 417 //   FROM "products" AS p
 418
 419 $select = $db->select()
 420              ->from(array('p' => 'products'), 'p.product_id')
 421              ->columns('product_name', 'p');
 422              // Alternatively use columns('p.product_name')
 423 ]]></programlisting>
 424             </example>
 425         </sect3>
 426
 427         <sect3 id="zend.db.select.building.join">
 428             <title>Adding Another Table to the Query with JOIN</title>
 429
 430             <para>
 431                 Many useful queries involve using a <acronym>JOIN</acronym> to combine rows from
 432                 multiple tables. You can add tables to a <classname>Zend_Db_Select</classname> query
 433                 using the <methodname>join()</methodname> method. Using this method is similar to
 434                 the <methodname>from()</methodname> method, except you can also specify a join
 435                 condition in most cases.
 436             </para>
 437
 438             <example id="zend.db.select.building.join.example">
 439                 <title>Example of the join() method</title>
 440
 441                 <programlisting language="php"><![CDATA[
 442 // Build this query:
 443 //   SELECT p."product_id", p."product_name", l.*
 444 //   FROM "products" AS p JOIN "line_items" AS l
 445 //     ON p.product_id = l.product_id
 446
 447 $select = $db->select()
 448              ->from(array('p' => 'products'),
 449                     array('product_id', 'product_name'))
 450              ->join(array('l' => 'line_items'),
 451                     'p.product_id = l.product_id');
 452 ]]></programlisting>
 453             </example>
 454
 455             <para>
 456                 The second argument to <methodname>join()</methodname> is a string that is the join
 457                 condition. This is an expression that declares the criteria by which rows in one
 458                 table match rows in the other table. You can use correlation names in this
 459                 expression.
 460             </para>
 461
 462             <note>
 463                 <para>
 464                     No quoting is applied to the expression you specify for the join condition; if
 465                     you have column names that need to be quoted, you must use
 466                     <methodname>quoteIdentifier()</methodname> as you form the string for the join
 467                     condition.
 468                 </para>
 469             </note>
 470
 471             <para>
 472                 The third argument to <methodname>join()</methodname> is an array of column names,
 473                 like that used in the <methodname>from()</methodname> method. It defaults to
 474                 "<emphasis>*</emphasis>", supports correlation names, expressions, and
 475                 <classname>Zend_Db_Expr</classname> in the same way as the array of column names in
 476                 the <methodname>from()</methodname> method.
 477             </para>
 478
 479             <para>
 480                 To select no columns from a table, use an empty array for the list of columns. This
 481                 usage works in the <methodname>from()</methodname> method too, but typically you
 482                 want some columns from the primary table in your queries, whereas you might want no
 483                 columns from a joined table.
 484             </para>
 485
 486             <example id="zend.db.select.building.join.example-no-columns">
 487                 <title>Example of specifying no columns</title>
 488
 489                 <programlisting language="php"><![CDATA[
 490 // Build this query:
 491 //   SELECT p."product_id", p."product_name"
 492 //   FROM "products" AS p JOIN "line_items" AS l
 493 //     ON p.product_id = l.product_id
 494
 495 $select = $db->select()
 496              ->from(array('p' => 'products'),
 497                     array('product_id', 'product_name'))
 498              ->join(array('l' => 'line_items'),
 499                     'p.product_id = l.product_id',
 500                     array() ); // empty list of columns
 501 ]]></programlisting>
 502
 503                 <para>
 504                     Note the empty <methodname>array()</methodname> in the above example in place of
 505                     a list of columns from the joined table.
 506                 </para>
 507             </example>
 508
 509             <para>
 510                 <acronym>SQL</acronym> has several types of joins. See the list below for the
 511                 methods to support different join types in <classname>Zend_Db_Select</classname>.
 512             </para>
 513
 514             <itemizedlist>
 515                 <listitem>
 516                     <para>
 517                         <command>INNER JOIN</command> with the
 518                         <methodname>join(table, join, [columns])</methodname> or
 519                         <methodname>joinInner(table, join, [columns])</methodname> methods.
 520                     </para>
 521
 522                     <para>
 523                         This may be the most common type of join. Rows from each table are compared
 524                         using the join condition you specify. The result set includes only the rows
 525                         that satisfy the join condition. The result set can be empty if no rows
 526                         satisfy this condition.
 527                     </para>
 528
 529                     <para>
 530                         All <acronym>RDBMS</acronym> brands support this join type.
 531                     </para>
 532                 </listitem>
 533
 534                 <listitem>
 535                     <para>
 536                         <command>LEFT JOIN</command> with the
 537                         <methodname>joinLeft(table, condition, [columns])</methodname> method.
 538                     </para>
 539
 540                     <para>
 541                         All rows from the left operand table are included, matching rows from the
 542                         right operand table included, and the columns from the right operand table
 543                         are filled with <constant>NULL</constant> if no row exists matching the left
 544                         table.
 545                     </para>
 546
 547                     <para>
 548                         All <acronym>RDBMS</acronym> brands support this join type.
 549                     </para>
 550                 </listitem>
 551
 552                 <listitem>
 553                     <para>
 554                         <command>RIGHT JOIN</command> with the
 555                         <methodname>joinRight(table, condition, [columns])</methodname> method.
 556                     </para>
 557
 558                     <para>
 559                         Right outer join is the complement of left outer join. All rows from the
 560                         right operand table are included, matching rows from the left operand table
 561                         included, and the columns from the left operand table are filled with
 562                         <constant>NULL</constant>'s if no row exists matching the right table.
 563                     </para>
 564
 565                     <para>
 566                         Some <acronym>RDBMS</acronym> brands don't support this join type, but in
 567                         general any right join can be represented as a left join by reversing the
 568                         order of the tables.
 569                     </para>
 570                 </listitem>
 571
 572                 <listitem>
 573                     <para>
 574                         <command>FULL JOIN</command> with the
 575                         <methodname>joinFull(table, condition, [columns])</methodname> method.
 576                     </para>
 577
 578                     <para>
 579                         A full outer join is like combining a left outer join and a right outer
 580                         join. All rows from both tables are included, paired with each other on the
 581                         same row of the result set if they satisfy the join condition, and
 582                         otherwise paired with <constant>NULL</constant>'s in place of columns from
 583                         the other table.
 584                     </para>
 585
 586                     <para>
 587                         Some <acronym>RDBMS</acronym> brands don't support this join type.
 588                     </para>
 589                 </listitem>
 590
 591                 <listitem>
 592                     <para>
 593                         <command>CROSS JOIN</command> with the
 594                         <methodname>joinCross(table, [columns])</methodname> method.
 595                     </para>
 596
 597                     <para>
 598                         A cross join is a Cartesian product. Every row in the first table is
 599                         matched to every row in the second table. Therefore the number of rows in
 600                         the result set is equal to the product of the number of rows in each table.
 601                         You can filter the result set using conditions in a <acronym>WHERE</acronym>
 602                         clause; in this way a cross join is similar to the old
 603                         <acronym>SQL</acronym>-89 join syntax.
 604                     </para>
 605
 606                     <para>
 607                         The <methodname>joinCross()</methodname> method has no parameter to specify
 608                         the join condition. Some <acronym>RDBMS</acronym> brands don't support this
 609                         join type.
 610                     </para>
 611                 </listitem>
 612
 613                 <listitem>
 614                     <para>
 615                         <command>NATURAL JOIN</command> with the
 616                         <methodname>joinNatural(table, [columns])</methodname> method.
 617                     </para>
 618
 619                     <para>
 620                         A natural join compares any columns that appear with the same name in
 621                         both tables. The comparison is equality of all the columns; comparing the
 622                         columns using inequality is not a natural join. Only natural inner joins
 623                         are supported by this <acronym>API</acronym>, even though
 624                         <acronym>SQL</acronym> permits natural outer joins as well.
 625                     </para>
 626
 627                     <para>
 628                         The <methodname>joinNatural()</methodname> method has no parameter to
 629                         specify the join condition.
 630                     </para>
 631                 </listitem>
 632             </itemizedlist>
 633
 634             <para>
 635                 In addition to these join methods, you can simplify your queries by using the
 636                 JoinUsing methods. Instead of supplying a full condition to your join, you simply
 637                 pass the column name on which to join and the <classname>Zend_Db_Select</classname>
 638                 object completes the condition for you.
 639             </para>
 640
 641             <example id="zend.db.select.building.joinusing.example">
 642                 <title>Example of the joinUsing() method</title>
 643
 644                 <programlisting language="php"><![CDATA[
 645 // Build this query:
 646 //   SELECT *
 647 //   FROM "table1"
 648 //   JOIN "table2"
 649 //   ON "table1".column1 = "table2".column1
 650 //   WHERE column2 = 'foo'
 651
 652 $select = $db->select()
 653              ->from('table1')
 654              ->joinUsing('table2', 'column1')
 655              ->where('column2 = ?', 'foo');
 656 ]]></programlisting>
 657             </example>
 658
 659             <para>
 660                 Each of the applicable join methods in the <classname>Zend_Db_Select</classname>
 661                 component has a corresponding 'using' method.
 662             </para>
 663
 664             <itemizedlist>
 665                 <listitem>
 666                     <para>
 667                         <methodname>joinUsing(table, join, [columns])</methodname> and
 668                         <methodname>joinInnerUsing(table, join, [columns])</methodname>
 669                     </para>
 670                 </listitem>
 671
 672                 <listitem>
 673                     <para>
 674                         <methodname>joinLeftUsing(table, join, [columns])</methodname>
 675                     </para>
 676                 </listitem>
 677
 678                 <listitem>
 679                     <para>
 680                         <methodname>joinRightUsing(table, join, [columns])</methodname>
 681                     </para>
 682                 </listitem>
 683
 684                 <listitem>
 685                     <para>
 686                         <methodname>joinFullUsing(table, join, [columns])</methodname>
 687                     </para>
 688                 </listitem>
 689             </itemizedlist>
 690         </sect3>
 691
 692         <sect3 id="zend.db.select.building.where">
 693             <title>Adding a WHERE Clause</title>
 694
 695             <para>
 696                 You can specify criteria for restricting rows of the result set using the
 697                 <methodname>where()</methodname> method. The first argument of this method is a
 698                 <acronym>SQL</acronym> expression, and this expression is used in a
 699                 <acronym>SQL</acronym> <acronym>WHERE</acronym> clause in the query.
 700             </para>
 701
 702             <example id="zend.db.select.building.where.example">
 703                 <title>Example of the where() method</title>
 704
 705                 <programlisting language="php"><![CDATA[
 706 // Build this query:
 707 //   SELECT product_id, product_name, price
 708 //   FROM "products"
 709 //   WHERE price > 100.00
 710
 711 $select = $db->select()
 712              ->from('products',
 713                     array('product_id', 'product_name', 'price'))
 714              ->where('price > 100.00');
 715 ]]></programlisting>
 716             </example>
 717
 718             <note>
 719                 <para>
 720                     No quoting is applied to expressions given to the
 721                     <methodname>where()</methodname> or <methodname>orWhere()</methodname> methods.
 722                     If you have column names that need to be quoted, you must use
 723                     <methodname>quoteIdentifier()</methodname> as you form the string for the
 724                     condition.
 725                 </para>
 726             </note>
 727
 728             <para>
 729                 The second argument to the <methodname>where()</methodname> method is optional. It
 730                 is a value to substitute into the expression. <classname>Zend_Db_Select</classname>
 731                 quotes the value and substitutes it for a question-mark ("<emphasis>?</emphasis>")
 732                 symbol in the expression.
 733             </para>
 734
 735             <example id="zend.db.select.building.where.example-param">
 736                 <title>Example of a parameter in the where() method</title>
 737
 738                 <programlisting language="php"><![CDATA[
 739 // Build this query:
 740 //   SELECT product_id, product_name, price
 741 //   FROM "products"
 742 //   WHERE (price > 100.00)
 743
 744 $minimumPrice = 100;
 745
 746 $select = $db->select()
 747              ->from('products',
 748                     array('product_id', 'product_name', 'price'))
 749              ->where('price > ?', $minimumPrice);
 750 ]]></programlisting>
 751             </example>
 752
 753             <para>
 754                 You can pass an array as the second parameter to the
 755                 <methodname>where()</methodname> method when using the <acronym>SQL</acronym> IN
 756                 operator.
 757             </para>
 758
 759             <example id="zend.db.select.building.where.example-array">
 760                 <title>Example of an array parameter in the where() method</title>
 761
 762                 <programlisting language="php"><![CDATA[
 763 // Build this query:
 764 //   SELECT product_id, product_name, price
 765 //   FROM "products"
 766 //   WHERE (product_id IN (1, 2, 3))
 767
 768 $productIds = array(1, 2, 3);
 769
 770 $select = $db->select()
 771              ->from('products',
 772                     array('product_id', 'product_name', 'price'))
 773              ->where('product_id IN (?)', $productIds);
 774 ]]></programlisting>
 775             </example>
 776
 777             <para>
 778                 You can invoke the <methodname>where()</methodname> method multiple times on the
 779                 same <classname>Zend_Db_Select</classname> object. The resulting query combines the
 780                 multiple terms together using <acronym>AND</acronym> between them.
 781             </para>
 782
 783             <example id="zend.db.select.building.where.example-and">
 784                 <title>Example of multiple where() methods</title>
 785
 786                 <programlisting language="php"><![CDATA[
 787 // Build this query:
 788 //   SELECT product_id, product_name, price
 789 //   FROM "products"
 790 //   WHERE (price > 100.00)
 791 //     AND (price < 500.00)
 792
 793 $minimumPrice = 100;
 794 $maximumPrice = 500;
 795
 796 $select = $db->select()
 797              ->from('products',
 798                     array('product_id', 'product_name', 'price'))
 799              ->where('price > ?', $minimumPrice)
 800              ->where('price < ?', $maximumPrice);
 801 ]]></programlisting>
 802             </example>
 803
 804             <para>
 805                 If you need to combine terms together using <acronym>OR</acronym>, use the
 806                 <methodname>orWhere()</methodname> method. This method is used in the same way as
 807                 the <methodname>where()</methodname> method, except that the term specified is
 808                 preceded by <acronym>OR</acronym>, instead of <acronym>AND</acronym>.
 809             </para>
 810
 811             <example id="zend.db.select.building.where.example-or">
 812                 <title>Example of the orWhere() method</title>
 813
 814                 <programlisting language="php"><![CDATA[
 815 // Build this query:
 816 //   SELECT product_id, product_name, price
 817 //   FROM "products"
 818 //   WHERE (price < 100.00)
 819 //     OR (price > 500.00)
 820
 821 $minimumPrice = 100;
 822 $maximumPrice = 500;
 823
 824 $select = $db->select()
 825              ->from('products',
 826                     array('product_id', 'product_name', 'price'))
 827              ->where('price < ?', $minimumPrice)
 828              ->orWhere('price > ?', $maximumPrice);
 829 ]]></programlisting>
 830             </example>
 831
 832             <para>
 833                 <classname>Zend_Db_Select</classname> automatically puts parentheses around each
 834                 expression you specify using the <methodname>where()</methodname> or
 835                 <methodname>orWhere()</methodname> methods. This helps to ensure that Boolean
 836                 operator precedence does not cause unexpected results.
 837             </para>
 838
 839             <example id="zend.db.select.building.where.example-parens">
 840                 <title>Example of parenthesizing Boolean expressions</title>
 841
 842                 <programlisting language="php"><![CDATA[
 843 // Build this query:
 844 //   SELECT product_id, product_name, price
 845 //   FROM "products"
 846 //   WHERE (price < 100.00 OR price > 500.00)
 847 //     AND (product_name = 'Apple')
 848
 849 $minimumPrice = 100;
 850 $maximumPrice = 500;
 851 $prod = 'Apple';
 852
 853 $select = $db->select()
 854              ->from('products',
 855                     array('product_id', 'product_name', 'price'))
 856              ->where("price < $minimumPrice OR price > $maximumPrice")
 857              ->where('product_name = ?', $prod);
 858 ]]></programlisting>
 859             </example>
 860
 861             <para>
 862                 In the example above, the results would be quite different without the parentheses,
 863                 because <acronym>AND</acronym> has higher precedence than <acronym>OR</acronym>.
 864                 <classname>Zend_Db_Select</classname> applies the parentheses so the effect is that
 865                 each expression in successive calls to the <methodname>where()</methodname> bind
 866                 more tightly than the <acronym>AND</acronym> that combines the expressions.
 867             </para>
 868         </sect3>
 869
 870         <sect3 id="zend.db.select.building.group">
 871             <title>Adding a GROUP BY Clause</title>
 872
 873             <para>
 874                 In <acronym>SQL</acronym>, the <command>GROUP BY</command> clause allows you to
 875                 reduce the rows of a query result set to one row per unique value found in the
 876                 columns named in the <command>GROUP BY</command> clause.
 877             </para>
 878
 879             <para>
 880                 In <classname>Zend_Db_Select</classname>, you can specify the columns to use for
 881                 calculating the groups of rows using the <methodname>group()</methodname> method.
 882                 The argument to this method is a column or an array of columns to use in the
 883                 <command>GROUP BY</command> clause.
 884             </para>
 885
 886             <example id="zend.db.select.building.group.example">
 887                 <title>Example of the group() method</title>
 888
 889                 <programlisting language="php"><![CDATA[
 890 // Build this query:
 891 //   SELECT p."product_id", COUNT(*) AS line_items_per_product
 892 //   FROM "products" AS p JOIN "line_items" AS l
 893 //     ON p.product_id = l.product_id
 894 //   GROUP BY p.product_id
 895
 896 $select = $db->select()
 897              ->from(array('p' => 'products'),
 898                     array('product_id'))
 899              ->join(array('l' => 'line_items'),
 900                     'p.product_id = l.product_id',
 901                     array('line_items_per_product' => 'COUNT(*)'))
 902              ->group('p.product_id');
 903 ]]></programlisting>
 904             </example>
 905
 906             <para>
 907                 Like the columns array in the <methodname>from()</methodname> method, you can use
 908                 correlation names in the column name strings, and the column is quoted as an
 909                 identifier unless the string contains parentheses or is an object of type
 910                 <classname>Zend_Db_Expr</classname>.
 911             </para>
 912         </sect3>
 913
 914         <sect3 id="zend.db.select.building.having">
 915             <title>Adding a HAVING Clause</title>
 916
 917             <para>
 918                 In <acronym>SQL</acronym>, the <constant>HAVING</constant> clause applies a
 919                 restriction condition on groups of rows. This is similar to how a
 920                 <constant>WHERE</constant> clause applies a restriction condition on rows. But the
 921                 two clauses are different because <constant>WHERE</constant> conditions are applied
 922                 before groups are defined, whereas <constant>HAVING</constant> conditions are
 923                 applied after groups are defined.
 924             </para>
 925
 926             <para>
 927                 In <classname>Zend_Db_Select</classname>, you can specify conditions for restricting
 928                 groups using the <methodname>having()</methodname> method. Its usage is similar to
 929                 that of the <methodname>where()</methodname> method. The first argument is a string
 930                 containing a <acronym>SQL</acronym> expression. The optional second argument is a
 931                 value that is used to replace a positional parameter placeholder in the
 932                 <acronym>SQL</acronym> expression. Expressions given in multiple invocations of the
 933                 <methodname>having()</methodname> method are combined using the Boolean
 934                 <acronym>AND</acronym> operator, or the <acronym>OR</acronym> operator if you
 935                 use the <methodname>orHaving()</methodname> method.
 936             </para>
 937
 938             <example id="zend.db.select.building.having.example">
 939                 <title>Example of the having() method</title>
 940
 941                 <programlisting language="php"><![CDATA[
 942 // Build this query:
 943 //   SELECT p."product_id", COUNT(*) AS line_items_per_product
 944 //   FROM "products" AS p JOIN "line_items" AS l
 945 //     ON p.product_id = l.product_id
 946 //   GROUP BY p.product_id
 947 //   HAVING line_items_per_product > 10
 948
 949 $select = $db->select()
 950              ->from(array('p' => 'products'),
 951                     array('product_id'))
 952              ->join(array('l' => 'line_items'),
 953                     'p.product_id = l.product_id',
 954                     array('line_items_per_product' => 'COUNT(*)'))
 955              ->group('p.product_id')
 956              ->having('line_items_per_product > 10');
 957 ]]></programlisting>
 958             </example>
 959
 960             <note>
 961                 <para>
 962                     No quoting is applied to expressions given to the
 963                     <methodname>having()</methodname> or <methodname>orHaving()</methodname>
 964                     methods. If you have column names that need to be quoted, you must use
 965                     <methodname>quoteIdentifier()</methodname> as you form the string for the
 966                     condition.
 967                 </para>
 968             </note>
 969         </sect3>
 970
 971         <sect3 id="zend.db.select.building.order">
 972             <title>Adding an ORDER BY Clause</title>
 973
 974             <para>
 975                 In <acronym>SQL</acronym>, the <acronym>ORDER</acronym> BY clause specifies one or
 976                 more columns or expressions by which the result set of a query is sorted. If
 977                 multiple columns are listed, the secondary columns are used to resolve ties; the
 978                 sort order is determined by the secondary columns if the preceding columns contain
 979                 identical values. The default sorting is from least value to greatest value. You can
 980                 also sort by greatest value to least value for a given column in the list by
 981                 specifying the keyword <constant>DESC</constant> after that column.
 982             </para>
 983
 984             <para>
 985                 In <classname>Zend_Db_Select</classname>, you can use the
 986                 <methodname>order()</methodname> method to specify a column or an array of columns
 987                 by which to sort. Each element of the array is a string naming a column. Optionally
 988                 with the <constant>ASC</constant> <constant>DESC</constant> keyword following it,
 989                 separated by a space.
 990             </para>
 991
 992             <para>
 993                 Like in the <methodname>from()</methodname> and <methodname>group()</methodname>
 994                 methods, column names are quoted as identifiers, unless they contain parentheses or
 995                 are an object of type <classname>Zend_Db_Expr</classname>.
 996             </para>
 997
 998             <example id="zend.db.select.building.order.example">
 999                 <title>Example of the order() method</title>
1000
1001                 <programlisting language="php"><![CDATA[
1002 // Build this query:
1003 //   SELECT p."product_id", COUNT(*) AS line_items_per_product
1004 //   FROM "products" AS p JOIN "line_items" AS l
1005 //     ON p.product_id = l.product_id
1006 //   GROUP BY p.product_id
1007 //   ORDER BY "line_items_per_product" DESC, "product_id"
1008
1009 $select = $db->select()
1010              ->from(array('p' => 'products'),
1011                     array('product_id'))
1012              ->join(array('l' => 'line_items'),
1013                     'p.product_id = l.product_id',
1014                     array('line_items_per_product' => 'COUNT(*)'))
1015              ->group('p.product_id')
1016              ->order(array('line_items_per_product DESC',
1017                            'product_id'));
1018 ]]></programlisting>
1019             </example>
1020         </sect3>
1021
1022         <sect3 id="zend.db.select.building.limit">
1023             <title>Adding a LIMIT Clause</title>
1024
1025             <para>
1026                 Some <acronym>RDBMS</acronym> brands extend <acronym>SQL</acronym> with a query
1027                 clause known as the <constant>LIMIT</constant> clause. This clause reduces the
1028                 number of rows in the result set to at most a number you specify. You can also
1029                 specify to skip a number of rows before starting to output. This feature makes it
1030                 easy to take a subset of a result set, for example when displaying query results on
1031                 progressive pages of output.
1032             </para>
1033
1034             <para>
1035                 In <classname>Zend_Db_Select</classname>, you can use the
1036                 <methodname>limit()</methodname> method to specify the count of rows and the number
1037                 of rows to skip. The <emphasis>first</emphasis> argument to this method is the
1038                 desired count of rows. The <emphasis>second</emphasis> argument is the number of
1039                 rows to skip.
1040             </para>
1041
1042             <example id="zend.db.select.building.limit.example">
1043                 <title>Example of the limit() method</title>
1044
1045                 <programlisting language="php"><![CDATA[
1046 // Build this query:
1047 //   SELECT p."product_id", p."product_name"
1048 //   FROM "products" AS p
1049 //   LIMIT 10, 20
1050 // Equivalent to:
1051 //   SELECT p."product_id", p."product_name"
1052 //   FROM "products" AS p
1053 //   LIMIT 20 OFFSET 10
1054
1055 $select = $db->select()
1056              ->from(array('p' => 'products'),
1057                     array('product_id', 'product_name'))
1058              ->limit(20, 10);
1059 ]]></programlisting>
1060             </example>
1061
1062             <note>
1063                 <para>
1064                     The <constant>LIMIT</constant> syntax is not supported by all
1065                     <acronym>RDBMS</acronym> brands. Some <acronym>RDBMS</acronym> require different
1066                     syntax to support similar functionality. Each
1067                     <classname>Zend_Db_Adapter_Abstract</classname> class includes a method to
1068                     produce <acronym>SQL</acronym> appropriate for that <acronym>RDBMS</acronym>.
1069                 </para>
1070             </note>
1071
1072             <para>
1073                 Use the <methodname>limitPage()</methodname> method for an alternative way to
1074                 specify row count and offset. This method allows you to limit the result set to one
1075                 of a series of fixed-length subsets of rows from the query's total result set. In
1076                 other words, you specify the length of a "page" of results, and the ordinal number
1077                 of the single page of results you want the query to return. The page number is the
1078                 first argument of the <methodname>limitPage()</methodname> method, and the page
1079                 length is the second argument. Both arguments are required; they have no default
1080                 values.
1081             </para>
1082
1083             <example id="zend.db.select.building.limit.example2">
1084                 <title>Example of the limitPage() method</title>
1085
1086                 <programlisting language="php"><![CDATA[
1087 // Build this query:
1088 //   SELECT p."product_id", p."product_name"
1089 //   FROM "products" AS p
1090 //   LIMIT 10, 20
1091
1092 $select = $db->select()
1093              ->from(array('p' => 'products'),
1094                     array('product_id', 'product_name'))
1095              ->limitPage(2, 10);
1096 ]]></programlisting>
1097             </example>
1098         </sect3>
1099
1100         <sect3 id="zend.db.select.building.distinct">
1101             <title>Adding the DISTINCT Query Modifier</title>
1102
1103             <para>
1104                 The <methodname>distinct()</methodname> method enables you to add the
1105                 <constant>DISTINCT</constant> keyword to your <acronym>SQL</acronym> query.
1106             </para>
1107
1108             <example id="zend.db.select.building.distinct.example">
1109                 <title>Example of the distinct() method</title>
1110
1111                 <programlisting language="php"><![CDATA[
1112 // Build this query:
1113 //   SELECT DISTINCT p."product_name"
1114 //   FROM "products" AS p
1115
1116 $select = $db->select()
1117              ->distinct()
1118              ->from(array('p' => 'products'), 'product_name');
1119 ]]></programlisting>
1120             </example>
1121         </sect3>
1122
1123         <sect3 id="zend.db.select.building.for-update">
1124             <title>Adding the FOR UPDATE Query Modifier</title>
1125
1126             <para>
1127                 The <methodname>forUpdate()</methodname> method enables you to add the
1128                 <acronym>FOR</acronym> <acronym>UPDATE</acronym> modifier to your
1129                 <acronym>SQL</acronym> query.
1130             </para>
1131
1132             <example id="zend.db.select.building.for-update.example">
1133                 <title>Example of forUpdate() method</title>
1134
1135                 <programlisting language="php"><![CDATA[
1136 // Build this query:
1137 //   SELECT FOR UPDATE p.*
1138 //   FROM "products" AS p
1139
1140 $select = $db->select()
1141              ->forUpdate()
1142              ->from(array('p' => 'products'));
1143 ]]></programlisting>
1144             </example>
1145         </sect3>
1146
1147         <sect3 id="zend.db.select.building.union">
1148             <title>Building a UNION Query</title>
1149
1150             <para>
1151                 You can build union queries with <classname>Zend_Db_Select</classname> by passing an
1152                 array of <classname>Zend_Db_Select</classname> or <acronym>SQL</acronym> Query
1153                 strings into the <methodname>union()</methodname> method. As second parameter you
1154                 can pass the <constant>Zend_Db_Select::SQL_UNION</constant> or
1155                 <constant>Zend_Db_Select::SQL_UNION_ALL</constant> constants to specify which type
1156                 of union you want to perform.
1157             </para>
1158
1159             <example id="zend.db.select.building.union.example">
1160                 <title>Example of union() method</title>
1161
1162                 <programlisting language="php"><![CDATA[
1163 $sql1 = $db->select();
1164 $sql2 = "SELECT ...";
1165
1166 $select = $db->select()
1167     ->union(array($sql1, $sql2))
1168     ->order("id");
1169 ]]></programlisting>
1170             </example>
1171         </sect3>
1172     </sect2>
1173
1174     <sect2 id="zend.db.select.execute">
1175         <title>Executing Select Queries</title>
1176
1177         <para>
1178             This section describes how to execute the query represented by a
1179             <classname>Zend_Db_Select</classname> object.
1180         </para>
1181
1182         <sect3 id="zend.db.select.execute.query-adapter">
1183             <title>Executing Select Queries from the Db Adapter</title>
1184
1185             <para>
1186                 You can execute the query represented by the <classname>Zend_Db_Select</classname>
1187                 object by passing it as the first argument to the <methodname>query()</methodname>
1188                 method of a <classname>Zend_Db_Adapter_Abstract</classname> object. Use the
1189                 <classname>Zend_Db_Select</classname> objects instead of a string query.
1190             </para>
1191
1192             <para>
1193                 The <methodname>query()</methodname> method returns an object of type
1194                 <classname>Zend_Db_Statement</classname> or PDOStatement, depending on the adapter
1195                 type.
1196             </para>
1197
1198             <example id="zend.db.select.execute.query-adapter.example">
1199                 <title>Example using the Db adapter's query() method</title>
1200
1201                 <programlisting language="php"><![CDATA[
1202 $select = $db->select()
1203              ->from('products');
1204
1205 $stmt = $db->query($select);
1206 $result = $stmt->fetchAll();
1207 ]]></programlisting>
1208             </example>
1209         </sect3>
1210
1211         <sect3 id="zend.db.select.execute.query-select">
1212             <title>Executing Select Queries from the Object</title>
1213
1214             <para>
1215                 As an alternative to using the <methodname>query()</methodname> method of the
1216                 adapter object, you can use the <methodname>query()</methodname> method of the
1217                 <classname>Zend_Db_Select</classname> object. Both methods return an object of type
1218                 <classname>Zend_Db_Statement</classname> or PDOStatement, depending on the adapter
1219                 type.
1220             </para>
1221
1222             <example id="zend.db.select.execute.query-select.example">
1223                 <title>Example using the Select object's query method</title>
1224
1225                 <programlisting language="php"><![CDATA[
1226 $select = $db->select()
1227              ->from('products');
1228
1229 $stmt = $select->query();
1230 $result = $stmt->fetchAll();
1231 ]]></programlisting>
1232             </example>
1233         </sect3>
1234
1235         <sect3 id="zend.db.select.execute.tostring">
1236             <title>Converting a Select Object to a SQL String</title>
1237
1238             <para>
1239                 If you need access to a string representation of the <acronym>SQL</acronym> query
1240                 corresponding to the <classname>Zend_Db_Select</classname> object, use the
1241                 <methodname>__toString()</methodname> method.
1242             </para>
1243
1244             <example id="zend.db.select.execute.tostring.example">
1245                 <title>Example of the __toString() method</title>
1246
1247                 <programlisting language="php"><![CDATA[
1248 $select = $db->select()
1249              ->from('products');
1250
1251 $sql = $select->__toString();
1252 echo "$sql\n";
1253
1254 // The output is the string:
1255 //   SELECT * FROM "products"
1256 ]]></programlisting>
1257             </example>
1258         </sect3>
1259     </sect2>
1260
1261     <sect2 id="zend.db.select.other">
1262         <title>Other methods</title>
1263
1264         <para>
1265             This section describes other methods of the <classname>Zend_Db_Select</classname> class
1266             that are not covered above: <methodname>getPart()</methodname> and
1267             <methodname>reset()</methodname>.
1268         </para>
1269
1270         <sect3 id="zend.db.select.other.get-part">
1271             <title>Retrieving Parts of the Select Object</title>
1272
1273             <para>
1274                 The <methodname>getPart()</methodname> method returns a representation of one part
1275                 of your <acronym>SQL</acronym> query. For example, you can use this method to return
1276                 the array of expressions for the <constant>WHERE</constant> clause, or the array of
1277                 columns (or column expressions) that are in the <constant>SELECT</constant> list, or
1278                 the values of the count and offset for the <constant>LIMIT</constant> clause.
1279             </para>
1280
1281             <para>
1282                 The return value is not a string containing a fragment of <acronym>SQL</acronym>
1283                 syntax. The return value is an internal representation, which is typically an array
1284                 structure containing values and expressions. Each part of the query has a different
1285                 structure.
1286             </para>
1287
1288             <para>
1289                 The single argument to the <methodname>getPart()</methodname> method is a string
1290                 that identifies which part of the Select query to return. For example, the string
1291                 <command>'from'</command> identifies the part of the Select object that stores
1292                 information about the tables in the <constant>FROM</constant> clause, including
1293                 joined tables.
1294             </para>
1295
1296             <para>
1297                 The <classname>Zend_Db_Select</classname> class defines constants you can use for
1298                 parts of the <acronym>SQL</acronym> query. You can use these constant definitions,
1299                 or you can the literal strings.
1300             </para>
1301
1302             <table id="zend.db.select.other.get-part.table">
1303                 <title>Constants used by getPart() and reset()</title>
1304
1305                 <tgroup cols="2">
1306                     <thead>
1307                         <row>
1308                             <entry>Constant</entry>
1309                             <entry>String value</entry>
1310                         </row>
1311                     </thead>
1312
1313                     <tbody>
1314                         <row>
1315                             <entry><constant>Zend_Db_Select::DISTINCT</constant></entry>
1316                             <entry><command>'distinct'</command></entry>
1317                         </row>
1318
1319                         <row>
1320                             <entry><constant>Zend_Db_Select::FOR_UPDATE</constant></entry>
1321                             <entry><command>'forupdate'</command></entry>
1322                         </row>
1323
1324                         <row>
1325                             <entry><constant>Zend_Db_Select::COLUMNS</constant></entry>
1326                             <entry><command>'columns'</command></entry>
1327                         </row>
1328
1329                         <row>
1330                             <entry><constant>Zend_Db_Select::FROM</constant></entry>
1331                             <entry><command>'from'</command></entry>
1332                         </row>
1333
1334                         <row>
1335                             <entry><constant>Zend_Db_Select::WHERE</constant></entry>
1336                             <entry><command>'where'</command></entry>
1337                         </row>
1338
1339                         <row>
1340                             <entry><constant>Zend_Db_Select::GROUP</constant></entry>
1341                             <entry><command>'group'</command></entry>
1342                         </row>
1343
1344                         <row>
1345                             <entry><constant>Zend_Db_Select::HAVING</constant></entry>
1346                             <entry><command>'having'</command></entry>
1347                         </row>
1348
1349                         <row>
1350                             <entry><constant>Zend_Db_Select::ORDER</constant></entry>
1351                             <entry><command>'order'</command></entry>
1352                         </row>
1353
1354                         <row>
1355                             <entry><constant>Zend_Db_Select::LIMIT_COUNT</constant></entry>
1356                             <entry><command>'limitcount'</command></entry>
1357                         </row>
1358
1359                         <row>
1360                             <entry><constant>Zend_Db_Select::LIMIT_OFFSET</constant></entry>
1361                             <entry><command>'limitoffset'</command></entry>
1362                         </row>
1363                     </tbody>
1364                 </tgroup>
1365             </table>
1366
1367             <example id="zend.db.select.other.get-part.example">
1368                 <title>Example of the getPart() method</title>
1369
1370                 <programlisting language="php"><![CDATA[
1371 $select = $db->select()
1372              ->from('products')
1373              ->order('product_id');
1374
1375 // You can use a string literal to specify the part
1376 $orderData = $select->getPart( 'order' );
1377
1378 // You can use a constant to specify the same part
1379 $orderData = $select->getPart( Zend_Db_Select::ORDER );
1380
1381 // The return value may be an array structure, not a string.
1382 // Each part has a different structure.
1383 print_r( $orderData );
1384 ]]></programlisting>
1385             </example>
1386         </sect3>
1387
1388         <sect3 id="zend.db.select.other.reset">
1389             <title>Resetting Parts of the Select Object</title>
1390
1391             <para>
1392                 The <methodname>reset()</methodname> method enables you to clear one specified part
1393                 of the <acronym>SQL</acronym> query, or else clear all parts of the
1394                 <acronym>SQL</acronym> query if you omit the argument.
1395             </para>
1396
1397             <para>
1398                 The single argument is optional. You can specify the part of the query to clear,
1399                 using the same strings you used in the argument to the
1400                 <methodname>getPart()</methodname> method. The part of the query you specify is
1401                 reset to a default state.
1402             </para>
1403
1404             <para>
1405                 If you omit the parameter, <methodname>reset()</methodname> changes all parts of the
1406                 query to their default state. This makes the <classname>Zend_Db_Select</classname>
1407                 object equivalent to a new object, as though you had just instantiated it.
1408             </para>
1409
1410             <example id="zend.db.select.other.reset.example">
1411                 <title>Example of the reset() method</title>
1412
1413                 <programlisting language="php"><![CDATA[
1414 // Build this query:
1415 //   SELECT p.*
1416 //   FROM "products" AS p
1417 //   ORDER BY "product_name"
1418
1419 $select = $db->select()
1420              ->from(array('p' => 'products')
1421              ->order('product_name');
1422
1423 // Changed requirement, instead order by a different columns:
1424 //   SELECT p.*
1425 //   FROM "products" AS p
1426 //   ORDER BY "product_id"
1427
1428 // Clear one part so we can redefine it
1429 $select->reset( Zend_Db_Select::ORDER );
1430
1431 // And specify a different column
1432 $select->order('product_id');
1433
1434 // Clear all parts of the query
1435 $select->reset();
1436 ]]></programlisting>
1437             </example>
1438         </sect3>
1439
1440     </sect2>
1441 </sect1>
1442 <!--
1443 vim:se ts=4 sw=4 et:
1444 -->