documentation/manual/en/module_specs/Zend_Search_Lucene-Queries.xml

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.search.lucene.query-api">
   4     <title>Query Construction API</title>
   5
   6     <para>
   7         In addition to parsing a string query automatically it's also possible to construct them
   8         with the query <acronym>API</acronym>.
   9     </para>
  10
  11     <para>
  12         User queries can be combined with queries created through the query <acronym>API</acronym>.
  13         Simply use the query parser to construct a query from a string:
  14     </para>
  15
  16     <programlisting language="php"><![CDATA[
  17 $query = Zend_Search_Lucene_Search_QueryParser::parse($queryString);
  18 ]]></programlisting>
  19
  20     <sect2 id="zend.search.lucene.queries.exceptions">
  21         <title>Query Parser Exceptions</title>
  22
  23         <para>
  24             The query parser may generate two types of exceptions:
  25
  26             <itemizedlist>
  27                 <listitem>
  28                     <para>
  29                         <classname>Zend_Search_Lucene_Exception</classname> is thrown if something
  30                         goes wrong in the query parser itself.
  31                     </para>
  32                 </listitem>
  33
  34                 <listitem>
  35                     <para>
  36                         <classname>Zend_Search_Lucene_Search_QueryParserException</classname> is
  37                         thrown when there is an error in the query syntax.
  38                     </para>
  39                 </listitem>
  40             </itemizedlist>
  41
  42             It's a good idea to catch
  43             <classname>Zend_Search_Lucene_Search_QueryParserException</classname>s and handle them
  44             appropriately:
  45         </para>
  46
  47         <programlisting language="php"><![CDATA[
  48 try {
  49     $query = Zend_Search_Lucene_Search_QueryParser::parse($queryString);
  50 } catch (Zend_Search_Lucene_Search_QueryParserException $e) {
  51     echo "Query syntax error: " . $e->getMessage() . "\n";
  52 }
  53 ]]></programlisting>
  54
  55         <para>
  56             The same technique should be used for the find() method of a
  57             <classname>Zend_Search_Lucene</classname> object.
  58         </para>
  59
  60         <para>
  61             Starting in 1.5, query parsing exceptions are suppressed by default. If query doesn't
  62             conform query language, then it's tokenized using current default analyzer and all
  63             tokenized terms are used for searching. Use
  64             <methodname>Zend_Search_Lucene_Search_QueryParser::dontSuppressQueryParsingExceptions()</methodname>
  65             method to turn exceptions on.
  66             <methodname>Zend_Search_Lucene_Search_QueryParser::suppressQueryParsingExceptions()</methodname>
  67             and
  68             <methodname>Zend_Search_Lucene_Search_QueryParser::queryParsingExceptionsSuppressed()</methodname>
  69             methods are also intended to manage exceptions handling behavior.
  70         </para>
  71     </sect2>
  72
  73     <sect2 id="zend.search.lucene.queries.term-query">
  74         <title>Term Query</title>
  75
  76         <para>
  77             Term queries can be used for searching with a single term.
  78         </para>
  79
  80         <para>
  81             Query string:
  82         </para>
  83
  84         <programlisting language="querystring"><![CDATA[
  85 word1
  86 ]]></programlisting>
  87
  88         <para>or</para>
  89
  90         <para>
  91             Query construction by <acronym>API</acronym>:
  92         </para>
  93
  94         <programlisting language="php"><![CDATA[
  95 $term  = new Zend_Search_Lucene_Index_Term('word1', 'field1');
  96 $query = new Zend_Search_Lucene_Search_Query_Term($term);
  97 $hits  = $index->find($query);
  98 ]]></programlisting>
  99
 100         <para>
 101             The term field is optional. <classname>Zend_Search_Lucene</classname> searches through
 102             all indexed fields in each document if the field is not specified:
 103         </para>
 104
 105         <programlisting language="php"><![CDATA[
 106 // Search for 'word1' in all indexed fields
 107 $term  = new Zend_Search_Lucene_Index_Term('word1');
 108 $query = new Zend_Search_Lucene_Search_Query_Term($term);
 109 $hits  = $index->find($query);
 110 ]]></programlisting>
 111     </sect2>
 112
 113     <sect2 id="zend.search.lucene.queries.multiterm-query">
 114         <title>Multi-Term Query</title>
 115
 116         <para>
 117             Multi-term queries can be used for searching with a set of terms.
 118         </para>
 119
 120         <para>
 121             Each term in a set can be defined as <emphasis>required</emphasis>,
 122             <emphasis>prohibited</emphasis>, or <emphasis>neither</emphasis>.
 123
 124             <itemizedlist>
 125                 <listitem>
 126                     <para>
 127                         <emphasis>required</emphasis> means that documents not matching this term
 128                         will not match the query;
 129                     </para>
 130                 </listitem>
 131
 132                 <listitem>
 133                     <para>
 134                         <emphasis>prohibited</emphasis> means that documents matching this term will
 135                         not match the query;
 136                     </para>
 137                 </listitem>
 138
 139                 <listitem>
 140                     <para>
 141                         <emphasis>neither</emphasis>, in which case matched documents are neither
 142                         prohibited from, nor required to, match the term. A document must match at
 143                         least 1 term, however, to match the query.
 144                     </para>
 145                 </listitem>
 146             </itemizedlist>
 147         </para>
 148
 149         <para>
 150             If optional terms are added to a query with required terms, both queries will have the
 151             same result set but the optional terms may affect the score of the matched documents.
 152         </para>
 153
 154         <para>
 155             Both search methods can be used for multi-term queries.
 156         </para>
 157
 158         <para>
 159             Query string:
 160         </para>
 161
 162         <programlisting language="querystring"><![CDATA[
 163 +word1 author:word2 -word3
 164 ]]></programlisting>
 165
 166         <itemizedlist>
 167             <listitem><para>'+' is used to define a required term.</para></listitem>
 168             <listitem><para>'-' is used to define a prohibited term.</para></listitem>
 169
 170             <listitem>
 171                 <para>
 172                     'field:' prefix is used to indicate a document field for a search.
 173                     If it's omitted, then all fields are searched.
 174                 </para>
 175             </listitem>
 176         </itemizedlist>
 177
 178         <para>or</para>
 179
 180         <para>
 181             Query construction by <acronym>API</acronym>:
 182         </para>
 183
 184         <programlisting language="php"><![CDATA[
 185 $query = new Zend_Search_Lucene_Search_Query_MultiTerm();
 186
 187 $query->addTerm(new Zend_Search_Lucene_Index_Term('word1'), true);
 188 $query->addTerm(new Zend_Search_Lucene_Index_Term('word2', 'author'),
 189                 null);
 190 $query->addTerm(new Zend_Search_Lucene_Index_Term('word3'), false);
 191
 192 $hits  = $index->find($query);
 193 ]]></programlisting>
 194
 195         <para>
 196             It's also possible to specify terms list within MultiTerm query constructor:
 197         </para>
 198
 199         <programlisting language="php"><![CDATA[
 200 $terms = array(new Zend_Search_Lucene_Index_Term('word1'),
 201                new Zend_Search_Lucene_Index_Term('word2', 'author'),
 202                new Zend_Search_Lucene_Index_Term('word3'));
 203 $signs = array(true, null, false);
 204
 205 $query = new Zend_Search_Lucene_Search_Query_MultiTerm($terms, $signs);
 206
 207 $hits  = $index->find($query);
 208 ]]></programlisting>
 209
 210         <para>
 211             The <varname>$signs</varname> array contains information about the term type:
 212
 213             <itemizedlist>
 214                 <listitem>
 215                     <para>
 216                         <constant>TRUE</constant> is used to define required term.
 217                     </para>
 218                 </listitem>
 219
 220                 <listitem>
 221                     <para>
 222                         <constant>FALSE</constant> is used to define prohibited term.
 223                     </para>
 224                 </listitem>
 225
 226                 <listitem>
 227                     <para>
 228                         <constant>NULL</constant> is used to define a term that is neither required
 229                         nor prohibited.
 230                     </para>
 231                 </listitem>
 232             </itemizedlist>
 233         </para>
 234     </sect2>
 235
 236     <sect2 id="zend.search.lucene.queries.boolean-query">
 237         <title>Boolean Query</title>
 238
 239         <para>
 240             Boolean queries allow to construct query using other queries and boolean operators.
 241         </para>
 242
 243         <para>
 244             Each subquery in a set can be defined as <emphasis>required</emphasis>,
 245             <emphasis>prohibited</emphasis>, or <emphasis>optional</emphasis>.
 246
 247             <itemizedlist>
 248                 <listitem>
 249                     <para>
 250                         <emphasis>required</emphasis> means that documents not matching this
 251                         subquery will not match the query;
 252                     </para>
 253                 </listitem>
 254
 255                 <listitem>
 256                     <para>
 257                         <emphasis>prohibited</emphasis> means that documents matching this subquery
 258                         will not match the query;
 259                     </para>
 260                 </listitem>
 261
 262                 <listitem>
 263                     <para>
 264                         <emphasis>optional</emphasis>, in which case matched documents are neither
 265                         prohibited from, nor required to, match the subquery. A document must match
 266                         at least 1 subquery, however, to match the query.
 267                     </para>
 268                 </listitem>
 269             </itemizedlist>
 270         </para>
 271
 272         <para>
 273             If optional subqueries are added to a query with required subqueries, both queries will
 274             have the same result set but the optional subqueries may affect the score of the matched
 275             documents.
 276         </para>
 277
 278         <para>
 279             Both search methods can be used for boolean queries.
 280         </para>
 281
 282         <para>
 283             Query string:
 284         </para>
 285
 286         <programlisting language="querystring"><![CDATA[
 287 +(word1 word2 word3) (author:word4 author:word5) -(word6)
 288 ]]></programlisting>
 289
 290         <itemizedlist>
 291             <listitem>
 292                 <para>
 293                     '+' is used to define a required subquery.
 294                 </para>
 295             </listitem>
 296
 297             <listitem>
 298                 <para>
 299                     '-' is used to define a prohibited subquery.
 300                 </para>
 301             </listitem>
 302
 303             <listitem>
 304                 <para>
 305                     'field:' prefix is used to indicate a document field for a search.
 306                     If it's omitted, then all fields are searched.
 307                 </para>
 308             </listitem>
 309         </itemizedlist>
 310
 311         <para>or</para>
 312
 313         <para>
 314             Query construction by <acronym>API</acronym>:
 315         </para>
 316
 317         <programlisting language="php"><![CDATA[
 318 $query = new Zend_Search_Lucene_Search_Query_Boolean();
 319
 320 $subquery1 = new Zend_Search_Lucene_Search_Query_MultiTerm();
 321 $subquery1->addTerm(new Zend_Search_Lucene_Index_Term('word1'));
 322 $subquery1->addTerm(new Zend_Search_Lucene_Index_Term('word2'));
 323 $subquery1->addTerm(new Zend_Search_Lucene_Index_Term('word3'));
 324
 325 $subquery2 = new Zend_Search_Lucene_Search_Query_MultiTerm();
 326 $subquery2->addTerm(new Zend_Search_Lucene_Index_Term('word4', 'author'));
 327 $subquery2->addTerm(new Zend_Search_Lucene_Index_Term('word5', 'author'));
 328
 329 $term6 = new Zend_Search_Lucene_Index_Term('word6');
 330 $subquery3 = new Zend_Search_Lucene_Search_Query_Term($term6);
 331
 332 $query->addSubquery($subquery1, true  /* required */);
 333 $query->addSubquery($subquery2, null  /* optional */);
 334 $query->addSubquery($subquery3, false /* prohibited */);
 335
 336 $hits  = $index->find($query);
 337 ]]></programlisting>
 338
 339         <para>
 340             It's also possible to specify subqueries list within Boolean query constructor:
 341         </para>
 342
 343         <programlisting language="php"><![CDATA[
 344 ...
 345 $subqueries = array($subquery1, $subquery2, $subquery3);
 346 $signs = array(true, null, false);
 347
 348 $query = new Zend_Search_Lucene_Search_Query_Boolean($subqueries, $signs);
 349
 350 $hits  = $index->find($query);
 351 ]]></programlisting>
 352
 353         <para>
 354             The <varname>$signs</varname> array contains information about the subquery type:
 355
 356             <itemizedlist>
 357                 <listitem>
 358                     <para>
 359                         <constant>TRUE</constant> is used to define required subquery.
 360                     </para>
 361                 </listitem>
 362
 363                 <listitem>
 364                     <para>
 365                         <constant>FALSE</constant> is used to define prohibited subquery.
 366                     </para>
 367                 </listitem>
 368
 369                 <listitem>
 370                     <para>
 371                         <constant>NULL</constant> is used to define a subquery that is neither
 372                         required nor prohibited.
 373                     </para>
 374                 </listitem>
 375             </itemizedlist>
 376         </para>
 377
 378         <para>
 379             Each query which uses boolean operators can be rewritten using signs notation and
 380             constructed using <acronym>API</acronym>. For example:
 381         </para>
 382
 383         <programlisting language="querystring"><![CDATA[
 384 word1 AND (word2 AND word3 AND NOT word4) OR word5
 385 ]]></programlisting>
 386
 387         <para>
 388             is equivalent to
 389         </para>
 390
 391         <programlisting language="querystring"><![CDATA[
 392 (+(word1) +(+word2 +word3 -word4)) (word5)
 393 ]]></programlisting>
 394     </sect2>
 395
 396     <sect2 id="zend.search.lucene.queries.wildcard">
 397         <title>Wildcard Query</title>
 398
 399         <para>
 400             Wildcard queries can be used to search for documents containing strings matching
 401             specified patterns.
 402         </para>
 403
 404         <para>
 405             The '?' symbol is used as a single character wildcard.
 406         </para>
 407
 408         <para>
 409             The '*' symbol is used as a multiple character wildcard.
 410         </para>
 411
 412         <para>
 413             Query string:
 414         </para>
 415
 416         <programlisting language="querystring"><![CDATA[
 417 field1:test*
 418 ]]></programlisting>
 419
 420         <para>or</para>
 421
 422         <para>
 423             Query construction by <acronym>API</acronym>:
 424         </para>
 425
 426         <programlisting language="php"><![CDATA[
 427 $pattern = new Zend_Search_Lucene_Index_Term('test*', 'field1');
 428 $query = new Zend_Search_Lucene_Search_Query_Wildcard($pattern);
 429 $hits  = $index->find($query);
 430 ]]></programlisting>
 431
 432         <para>
 433             The term field is optional. <classname>Zend_Search_Lucene</classname> searches through
 434             all fields on each document if a field is not specified:
 435         </para>
 436
 437         <programlisting language="php"><![CDATA[
 438 $pattern = new Zend_Search_Lucene_Index_Term('test*');
 439 $query = new Zend_Search_Lucene_Search_Query_Wildcard($pattern);
 440 $hits  = $index->find($query);
 441 ]]></programlisting>
 442     </sect2>
 443
 444     <sect2 id="zend.search.lucene.queries.fuzzy">
 445         <title>Fuzzy Query</title>
 446
 447         <para>
 448             Fuzzy queries can be used to search for documents containing strings matching terms
 449             similar to specified term.
 450         </para>
 451
 452         <para>
 453             Query string:
 454         </para>
 455
 456         <programlisting language="querystring"><![CDATA[
 457 field1:test~
 458 ]]></programlisting>
 459
 460         <para>
 461             This query matches documents containing 'test' 'text' 'best' words and others.
 462         </para>
 463
 464         <para>or</para>
 465
 466         <para>
 467             Query construction by <acronym>API</acronym>:
 468         </para>
 469
 470         <programlisting language="php"><![CDATA[
 471 $term = new Zend_Search_Lucene_Index_Term('test', 'field1');
 472 $query = new Zend_Search_Lucene_Search_Query_Fuzzy($term);
 473 $hits  = $index->find($query);
 474 ]]></programlisting>
 475
 476         <para>
 477             Optional similarity can be specified after "~" sign.
 478         </para>
 479
 480         <para>
 481             Query string:
 482         </para>
 483
 484         <programlisting language="querystring"><![CDATA[
 485 field1:test~0.4
 486 ]]></programlisting>
 487
 488         <para>or</para>
 489
 490         <para>
 491             Query construction by <acronym>API</acronym>:
 492         </para>
 493
 494         <programlisting language="php"><![CDATA[
 495 $term = new Zend_Search_Lucene_Index_Term('test', 'field1');
 496 $query = new Zend_Search_Lucene_Search_Query_Fuzzy($term, 0.4);
 497 $hits  = $index->find($query);
 498 ]]></programlisting>
 499
 500         <para>
 501             The term field is optional. <classname>Zend_Search_Lucene</classname> searches through
 502             all fields on each document if a field is not specified:
 503         </para>
 504
 505         <programlisting language="php"><![CDATA[
 506 $term = new Zend_Search_Lucene_Index_Term('test');
 507 $query = new Zend_Search_Lucene_Search_Query_Fuzzy($term);
 508 $hits  = $index->find($query);
 509 ]]></programlisting>
 510     </sect2>
 511
 512     <sect2 id="zend.search.lucene.queries.phrase-query">
 513         <title>Phrase Query</title>
 514
 515         <para>
 516             Phrase Queries can be used to search for a phrase within documents.
 517         </para>
 518
 519         <para>
 520             Phrase Queries are very flexible and allow the user or developer to search for exact
 521             phrases as well as 'sloppy' phrases.
 522         </para>
 523
 524         <para>
 525             Phrases can also contain gaps or terms in the same places; they can be generated by
 526             the analyzer for different purposes. For example, a term can be duplicated to increase
 527             the term its weight, or several synonyms can be placed into a single position.
 528         </para>
 529
 530         <programlisting language="php"><![CDATA[
 531 $query1 = new Zend_Search_Lucene_Search_Query_Phrase();
 532
 533 // Add 'word1' at 0 relative position.
 534 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word1'));
 535
 536 // Add 'word2' at 1 relative position.
 537 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word2'));
 538
 539 // Add 'word3' at 3 relative position.
 540 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word3'), 3);
 541
 542 ...
 543
 544 $query2 = new Zend_Search_Lucene_Search_Query_Phrase(
 545                 array('word1', 'word2', 'word3'), array(0,1,3));
 546
 547 ...
 548
 549 // Query without a gap.
 550 $query3 = new Zend_Search_Lucene_Search_Query_Phrase(
 551                 array('word1', 'word2', 'word3'));
 552
 553 ...
 554
 555 $query4 = new Zend_Search_Lucene_Search_Query_Phrase(
 556                 array('word1', 'word2'), array(0,1), 'annotation');
 557 ]]></programlisting>
 558
 559         <para>
 560             A phrase query can be constructed in one step with a class constructor or step by step
 561             with <methodname>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</methodname> method
 562             calls.
 563         </para>
 564
 565         <para>
 566             <classname>Zend_Search_Lucene_Search_Query_Phrase</classname> class constructor takes
 567             three optional arguments:
 568         </para>
 569
 570         <programlisting language="php"><![CDATA[
 571 Zend_Search_Lucene_Search_Query_Phrase(
 572     [array $terms[, array $offsets[, string $field]]]
 573 );
 574 ]]></programlisting>
 575
 576         <para>
 577             The <varname>$terms</varname> parameter is an array of strings that contains a set of
 578             phrase terms. If it's omitted or equal to <constant>NULL</constant>, then an empty query
 579             is constructed.
 580         </para>
 581
 582         <para>
 583             The <varname>$offsets</varname> parameter is an array of integers that contains offsets
 584             of terms in a phrase. If it's omitted or equal to <constant>NULL</constant>, then the
 585             terms' positions are assumed to be sequential with no gaps.
 586         </para>
 587
 588         <para>
 589             The <varname>$field</varname> parameter is a string that indicates the document field
 590             to search. If it's omitted or equal to <constant>NULL</constant>, then the default field
 591             is searched.
 592         </para>
 593
 594         <para>
 595             Thus:
 596         </para>
 597
 598         <programlisting language="php"><![CDATA[
 599 $query =
 600     new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'));
 601 ]]></programlisting>
 602
 603         <para>
 604             will search for the phrase 'zend framework' in all fields.
 605         </para>
 606
 607         <programlisting language="php"><![CDATA[
 608 $query = new Zend_Search_Lucene_Search_Query_Phrase(
 609                  array('zend', 'download'), array(0, 2)
 610              );
 611 ]]></programlisting>
 612
 613         <para>
 614             will search for the phrase 'zend ????? download' and match 'zend platform download',
 615             'zend studio download', 'zend core download', 'zend framework download', and so on.
 616         </para>
 617
 618         <programlisting language="php"><![CDATA[
 619 $query = new Zend_Search_Lucene_Search_Query_Phrase(
 620                  array('zend', 'framework'), null, 'title'
 621              );
 622 ]]></programlisting>
 623
 624         <para>
 625             will search for the phrase 'zend framework' in the 'title' field.
 626         </para>
 627
 628         <para>
 629             <methodname>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</methodname> takes two
 630             arguments, a required <classname>Zend_Search_Lucene_Index_Term</classname> object and an
 631             optional position:
 632         </para>
 633
 634         <programlisting language="php"><![CDATA[
 635 Zend_Search_Lucene_Search_Query_Phrase::addTerm(
 636     Zend_Search_Lucene_Index_Term $term[, integer $position]
 637 );
 638 ]]></programlisting>
 639
 640         <para>
 641             The <varname>$term</varname> parameter describes the next term in the phrase. It must
 642             indicate the same field as previous terms, or an exception will be thrown.
 643         </para>
 644
 645         <para>
 646             The <varname>$position</varname> parameter indicates the term position in the phrase.
 647         </para>
 648
 649         <para>
 650             Thus:
 651         </para>
 652
 653         <programlisting language="php"><![CDATA[
 654 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 655 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'));
 656 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'));
 657 ]]></programlisting>
 658
 659         <para>
 660             will search for the phrase 'zend framework'.
 661         </para>
 662
 663         <programlisting language="php"><![CDATA[
 664 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 665 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'), 0);
 666 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'), 2);
 667 ]]></programlisting>
 668
 669         <para>
 670             will search for the phrase 'zend ????? download' and match 'zend platform download',
 671             'zend studio download', 'zend core download', 'zend framework download', and so on.
 672         </para>
 673
 674         <programlisting language="php"><![CDATA[
 675 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 676 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend', 'title'));
 677 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework', 'title'));
 678 ]]></programlisting>
 679
 680         <para>
 681             will search for the phrase 'zend framework' in the 'title' field.
 682         </para>
 683
 684         <para>
 685             The slop factor sets the number of other words permitted between specified words in the
 686             query phrase. If set to zero, then the corresponding query is an exact phrase search.
 687             For larger values this works like the WITHIN or NEAR operators.
 688         </para>
 689
 690         <para>
 691             The slop factor is in fact an edit distance, where the edits correspond to moving terms
 692             in the query phrase. For example, to switch the order of two words requires two moves
 693             (the first move places the words atop one another), so to permit re-orderings of
 694             phrases, the slop factor must be at least two.
 695         </para>
 696
 697         <para>
 698             More exact matches are scored higher than sloppier matches; thus, search results are
 699             sorted by exactness. The slop is zero by default, requiring exact matches.
 700         </para>
 701
 702         <para>
 703             The slop factor can be assigned after query creation:
 704         </para>
 705
 706         <programlisting language="php"><![CDATA[
 707 // Query without a gap.
 708 $query =
 709     new Zend_Search_Lucene_Search_Query_Phrase(array('word1', 'word2'));
 710
 711 // Search for 'word1 word2', 'word1 ... word2'
 712 $query->setSlop(1);
 713 $hits1 = $index->find($query);
 714
 715 // Search for 'word1 word2', 'word1 ... word2',
 716 // 'word1 ... ... word2', 'word2 word1'
 717 $query->setSlop(2);
 718 $hits2 = $index->find($query);
 719 ]]></programlisting>
 720     </sect2>
 721
 722     <sect2 id="zend.search.lucene.queries.range">
 723         <title>Range Query</title>
 724
 725         <para>
 726             <link linkend="zend.search.lucene.query-language.range">Range queries</link> are
 727             intended for searching terms within specified interval.
 728         </para>
 729
 730         <para>
 731             Query string:
 732         </para>
 733
 734         <programlisting language="querystring"><![CDATA[
 735 mod_date:[20020101 TO 20030101]
 736 title:{Aida TO Carmen}
 737 ]]></programlisting>
 738
 739         <para>or</para>
 740
 741         <para>
 742             Query construction by <acronym>API</acronym>:
 743         </para>
 744
 745         <programlisting language="php"><![CDATA[
 746 $from = new Zend_Search_Lucene_Index_Term('20020101', 'mod_date');
 747 $to   = new Zend_Search_Lucene_Index_Term('20030101', 'mod_date');
 748 $query = new Zend_Search_Lucene_Search_Query_Range(
 749                  $from, $to, true // inclusive
 750              );
 751 $hits  = $index->find($query);
 752 ]]></programlisting>
 753
 754         <para>
 755             Term fields are optional. <classname>Zend_Search_Lucene</classname> searches through all
 756             fields if the field is not specified:
 757         </para>
 758
 759         <programlisting language="php"><![CDATA[
 760 $from = new Zend_Search_Lucene_Index_Term('Aida');
 761 $to   = new Zend_Search_Lucene_Index_Term('Carmen');
 762 $query = new Zend_Search_Lucene_Search_Query_Range(
 763                  $from, $to, false // non-inclusive
 764              );
 765 $hits  = $index->find($query);
 766 ]]></programlisting>
 767
 768         <para>
 769             Either (but not both) of the boundary terms may be set to <constant>NULL</constant>.
 770             <classname>Zend_Search_Lucene</classname> searches from the beginning or
 771             up to the end of the dictionary for the specified field(s) in this case:
 772         </para>
 773
 774         <programlisting language="php"><![CDATA[
 775 // searches for ['20020101' TO ...]
 776 $from = new Zend_Search_Lucene_Index_Term('20020101', 'mod_date');
 777 $query = new Zend_Search_Lucene_Search_Query_Range(
 778                  $from, null, true // inclusive
 779              );
 780 $hits  = $index->find($query);
 781 ]]></programlisting>
 782     </sect2>
 783 </sect1>
 784 <!--
 785 vim:se ts=4 sw=4 et:
 786 -->