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

   1 <?xml version="1.0" encoding="UTF-8"?>
   2 <!-- Reviewed: no -->
   3 <sect1 id="zend.search.lucene.searching">
   4     <title>Searching an Index</title>
   5
   6     <sect2 id="zend.search.lucene.searching.query_building">
   7         <title>Building Queries</title>
   8
   9         <para>
  10             There are two ways to search the index. The first method uses
  11             query parser to construct a query from a string. The second is
  12             to programmatically create your own queries through the
  13             <classname>Zend_Search_Lucene</classname> <acronym>API</acronym>.
  14         </para>
  15
  16         <para>
  17         Before choosing to use the provided query parser, please consider
  18         the following:
  19
  20             <orderedlist>
  21                 <listitem>
  22                     <para>
  23                         If you are programmatically creating a query string and then parsing
  24                         it with the query parser then you should consider building your queries
  25                         directly with the query <acronym>API</acronym>. Generally speaking, the
  26                         query parser is designed for human-entered text, not for program-generated
  27                         text.
  28                     </para>
  29                 </listitem>
  30
  31                 <listitem>
  32                     <para>
  33                         Untokenized fields are best added directly to queries and not through
  34                         the query parser. If a field's values are generated programmatically
  35                         by the application, then the query clauses for this field should also
  36                         be constructed programmatically.
  37                         An analyzer, which the query parser uses, is designed to convert
  38                         human-entered text to terms. Program-generated values, like dates,
  39                         keywords, etc., should be added with the query <acronym>API</acronym>.
  40                     </para>
  41                 </listitem>
  42
  43                 <listitem>
  44                     <para>
  45                         In a query form, fields that are general text should use the query parser.
  46                         All others, such as date ranges, keywords, etc., are better added directly
  47                         through the query <acronym>API</acronym>. A field with a limited set of
  48                         values that can be specified with a pull-down menu should not be added to a
  49                         query string that is subsequently parsed but instead should be added as a
  50                         TermQuery clause.
  51                     </para>
  52                 </listitem>
  53
  54                 <listitem>
  55                     <para>
  56                         Boolean queries allow the programmer to logically combine two or more
  57                         queries into new one. Thus it's the best way to add additional criteria to a
  58                         search defined by a query string.
  59                     </para>
  60                 </listitem>
  61             </orderedlist>
  62         </para>
  63
  64         <para>
  65             Both ways use the same <acronym>API</acronym> method to search through the index:
  66         </para>
  67
  68         <programlisting language="php"><![CDATA[
  69 $index = Zend_Search_Lucene::open('/data/my_index');
  70
  71 $index->find($query);
  72 ]]></programlisting>
  73
  74         <para>
  75             The <methodname>Zend_Search_Lucene::find()</methodname> method determines the input type
  76             automatically and uses the query parser to construct an appropriate
  77             <classname>Zend_Search_Lucene_Search_Query</classname> object from an input of type
  78             string.
  79         </para>
  80
  81         <para>
  82             It is important to note that the query parser uses the standard analyzer to tokenize
  83             separate parts of query string. Thus all transformations which are applied to indexed
  84             text are also applied to query strings.
  85         </para>
  86
  87         <para>
  88             The standard analyzer may transform the query string to lower case for
  89             case-insensitivity, remove stop-words, and stem among other transformations.
  90         </para>
  91
  92         <para>
  93             The <acronym>API</acronym> method doesn't transform or filter input terms in any way.
  94             It's therefore more suitable for computer generated or untokenized fields.
  95         </para>
  96
  97         <sect3 id="zend.search.lucene.searching.query_building.parsing">
  98             <title>Query Parsing</title>
  99
 100             <para>
 101                 <methodname>Zend_Search_Lucene_Search_QueryParser::parse()</methodname> method may
 102                 be used to parse query strings into query objects.
 103             </para>
 104
 105             <para>
 106                 This query object may be used in query construction <acronym>API</acronym> methods
 107                 to combine user entered queries with programmatically generated queries.
 108             </para>
 109
 110             <para>
 111                 Actually, in some cases it's the only way to search for values within untokenized
 112                 fields:
 113             </para>
 114
 115             <programlisting language="php"><![CDATA[
 116 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
 117
 118 $pathTerm  = new Zend_Search_Lucene_Index_Term(
 119                      '/data/doc_dir/' . $filename, 'path'
 120                  );
 121 $pathQuery = new Zend_Search_Lucene_Search_Query_Term($pathTerm);
 122
 123 $query = new Zend_Search_Lucene_Search_Query_Boolean();
 124 $query->addSubquery($userQuery, true /* required */);
 125 $query->addSubquery($pathQuery, true /* required */);
 126
 127 $hits = $index->find($query);
 128 ]]></programlisting>
 129
 130             <para>
 131                 <methodname>Zend_Search_Lucene_Search_QueryParser::parse()</methodname> method also
 132                 takes an optional encoding parameter, which can specify query string encoding:
 133             </para>
 134
 135             <programlisting language="php"><![CDATA[
 136 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr,
 137                                                           'iso-8859-5');
 138 ]]></programlisting>
 139
 140             <para>
 141                 If the encoding parameter is omitted, then current locale is used.
 142             </para>
 143
 144             <para>
 145                 It's also possible to specify the default query string encoding with
 146                 <methodname>Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding()</methodname>
 147                 method:
 148             </para>
 149
 150             <programlisting language="php"><![CDATA[
 151 Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding('iso-8859-5');
 152 ...
 153 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
 154 ]]></programlisting>
 155
 156             <para>
 157                 <methodname>Zend_Search_Lucene_Search_QueryParser::getDefaultEncoding()</methodname>
 158                 returns the current default query string encoding (the empty string means "current
 159                 locale").
 160             </para>
 161         </sect3>
 162     </sect2>
 163
 164     <sect2 id="zend.search.lucene.searching.results">
 165         <title>Search Results</title>
 166
 167         <para>
 168             The search result is an array of
 169             <classname>Zend_Search_Lucene_Search_QueryHit</classname> objects. Each of these has two
 170             properties: <code>$hit->id</code> is a document number within the index and
 171             <code>$hit->score</code> is a score of the hit in a search result. The results are
 172             ordered by score (descending from highest score).
 173         </para>
 174
 175         <para>
 176             The <classname>Zend_Search_Lucene_Search_QueryHit</classname> object also exposes each
 177             field of the <classname>Zend_Search_Lucene_Document</classname> found in the search as a
 178             property of the hit. In the following example, a hit is returned with two fields from
 179             the corresponding document: title and author.
 180         </para>
 181
 182         <programlisting language="php"><![CDATA[
 183 $index = Zend_Search_Lucene::open('/data/my_index');
 184
 185 $hits = $index->find($query);
 186
 187 foreach ($hits as $hit) {
 188     echo $hit->score;
 189     echo $hit->title;
 190     echo $hit->author;
 191 }
 192 ]]></programlisting>
 193
 194         <para>
 195             Stored fields are always returned in UTF-8 encoding.
 196         </para>
 197
 198         <para>
 199             Optionally, the original <classname>Zend_Search_Lucene_Document</classname> object can
 200             be returned from the <classname>Zend_Search_Lucene_Search_QueryHit</classname>.
 201             You can retrieve stored parts of the document by using the
 202             <methodname>getDocument()</methodname> method of the index object and then get them by
 203             <methodname>getFieldValue()</methodname> method:
 204         </para>
 205
 206         <programlisting language="php"><![CDATA[
 207 $index = Zend_Search_Lucene::open('/data/my_index');
 208
 209 $hits = $index->find($query);
 210 foreach ($hits as $hit) {
 211     // return Zend_Search_Lucene_Document object for this hit
 212     echo $document = $hit->getDocument();
 213
 214     // return a Zend_Search_Lucene_Field object
 215     // from the Zend_Search_Lucene_Document
 216     echo $document->getField('title');
 217
 218     // return the string value of the Zend_Search_Lucene_Field object
 219     echo $document->getFieldValue('title');
 220
 221     // same as getFieldValue()
 222     echo $document->title;
 223 }
 224 ]]></programlisting>
 225
 226         <para>
 227             The fields available from the <classname>Zend_Search_Lucene_Document</classname> object
 228             are determined at the time of indexing. The document fields are either indexed, or
 229             index and stored, in the document by the indexing application
 230             (e.g. LuceneIndexCreation.jar).
 231         </para>
 232
 233         <para>
 234             Note that the document identity ('path' in our example) is also stored
 235             in the index and must be retrieved from it.
 236         </para>
 237     </sect2>
 238
 239     <sect2 id="zend.search.lucene.searching.results-limiting">
 240         <title>Limiting the Result Set</title>
 241
 242         <para>
 243             The most computationally expensive part of searching is score calculation. It may take
 244             several seconds for large result sets (tens of thousands of hits).
 245         </para>
 246
 247         <para>
 248             <classname>Zend_Search_Lucene</classname> gives the possibility to limit result set size
 249             with <methodname>getResultSetLimit()</methodname> and
 250             <methodname>setResultSetLimit()</methodname> methods:
 251         </para>
 252
 253         <programlisting language="php"><![CDATA[
 254 $currentResultSetLimit = Zend_Search_Lucene::getResultSetLimit();
 255
 256 Zend_Search_Lucene::setResultSetLimit($newLimit);
 257 ]]></programlisting>
 258
 259         <para>
 260             The default value of 0 means 'no limit'.
 261         </para>
 262
 263         <para>
 264             It doesn't give the 'best N' results, but only the 'first N'
 265
 266             <footnote>
 267                 <para>
 268                     Returned hits are still ordered by score or by the specified order, if given.
 269                 </para>
 270             </footnote>.
 271         </para>
 272     </sect2>
 273
 274     <sect2 id="zend.search.lucene.searching.results-scoring">
 275         <title>Results Scoring</title>
 276
 277         <para>
 278             <classname>Zend_Search_Lucene</classname> uses the same scoring algorithms as Java
 279             Lucene. All hits in the search result are ordered by score by default. Hits with greater
 280             score come first, and documents having higher scores should match the query more
 281             precisely than documents having lower scores.
 282         </para>
 283
 284         <para>
 285             Roughly speaking, search hits that contain the searched term or phrase more frequently
 286             will have a higher score.
 287         </para>
 288
 289         <para>
 290             A hit's score can be retrieved by accessing the <code>score</code> property of the hit:
 291         </para>
 292
 293         <programlisting language="php"><![CDATA[
 294 $hits = $index->find($query);
 295
 296 foreach ($hits as $hit) {
 297     echo $hit->id;
 298     echo $hit->score;
 299 }
 300 ]]></programlisting>
 301
 302         <para>
 303             The <classname>Zend_Search_Lucene_Search_Similarity</classname> class is used to
 304             calculate the score for each hit. See <link
 305                 linkend="zend.search.lucene.extending.scoring">Extensibility. Scoring
 306                 Algorithms</link> section for details.
 307         </para>
 308     </sect2>
 309
 310     <sect2 id="zend.search.lucene.searching.sorting">
 311         <title>Search Result Sorting</title>
 312
 313         <para>
 314             By default, the search results are ordered by score. The programmer can change this
 315             behavior by setting a sort field (or a list of fields), sort type and sort order
 316             parameters.
 317         </para>
 318
 319         <para>
 320             <code>$index->find()</code> call may take several optional parameters:
 321         </para>
 322
 323         <programlisting language="php"><![CDATA[
 324 $index->find($query [, $sortField [, $sortType [, $sortOrder]]]
 325                     [, $sortField2 [, $sortType [, $sortOrder]]]
 326              ...);
 327 ]]></programlisting>
 328
 329         <para>
 330              A name of stored field by which to sort result should be passed as the
 331              <varname>$sortField</varname> parameter.
 332         </para>
 333
 334         <para>
 335             <varname>$sortType</varname> may be omitted or take the following enumerated values:
 336             <constant>SORT_REGULAR</constant> (compare items normally- default value),
 337             <constant>SORT_NUMERIC</constant> (compare items numerically),
 338             <constant>SORT_STRING</constant> (compare items as strings).
 339         </para>
 340
 341         <para>
 342             <varname>$sortOrder</varname> may be omitted or take the following enumerated values:
 343             <constant>SORT_ASC</constant> (sort in ascending order- default value),
 344             <constant>SORT_DESC</constant> (sort in descending order).
 345         </para>
 346
 347         <para>
 348             Examples:
 349         </para>
 350
 351         <programlisting language="php"><![CDATA[
 352 $index->find($query, 'quantity', SORT_NUMERIC, SORT_DESC);
 353 ]]></programlisting>
 354
 355         <programlisting language="php"><![CDATA[
 356 $index->find($query, 'fname', SORT_STRING, 'lname', SORT_STRING);
 357 ]]></programlisting>
 358
 359         <programlisting language="php"><![CDATA[
 360 $index->find($query, 'name', SORT_STRING, 'quantity', SORT_NUMERIC, SORT_DESC);
 361 ]]></programlisting>
 362
 363         <para>
 364             Please use caution when using a non-default search order; the query needs to retrieve
 365             documents completely from an index, which may dramatically reduce search performance.
 366         </para>
 367     </sect2>
 368
 369     <sect2 id="zend.search.lucene.searching.highlighting">
 370         <title>Search Results Highlighting</title>
 371
 372         <para>
 373             <classname>Zend_Search_Lucene</classname> provides two options for search results
 374             highlighting.
 375         </para>
 376
 377         <para>
 378             The first one is utilizing <classname>Zend_Search_Lucene_Document_Html</classname> class
 379             (see <link linkend="zend.search.lucene.index-creation.html-documents">HTML documents
 380                 section</link> for details) using the following methods:
 381         </para>
 382
 383         <programlisting language="php"><![CDATA[
 384 /**
 385  * Highlight text with specified color
 386  *
 387  * @param string|array $words
 388  * @param string $colour
 389  * @return string
 390  */
 391 public function highlight($words, $colour = '#66ffff');
 392 ]]></programlisting>
 393
 394         <programlisting language="php"><![CDATA[
 395 /**
 396  * Highlight text using specified View helper or callback function.
 397  *
 398  * @param string|array $words  Words to highlight. Words could be organized
 399                                using the array or string.
 400  * @param callback $callback   Callback method, used to transform
 401                                (highlighting) text.
 402  * @param array    $params     Array of additionall callback parameters passed
 403                                through into it (first non-optional parameter
 404                                is an HTML fragment for highlighting)
 405  * @return string
 406  * @throws Zend_Search_Lucene_Exception
 407  */
 408 public function highlightExtended($words, $callback, $params = array())
 409 ]]></programlisting>
 410
 411         <para>
 412             To customize highlighting behavior use <methodname>highlightExtended()</methodname>
 413             method with specified callback, which takes one or more parameters
 414
 415             <footnote>
 416                 <para>
 417                     The first is an <acronym>HTML</acronym> fragment for highlighting and others are
 418                     callback behavior dependent. Returned value is a highlighted
 419                     <acronym>HTML</acronym> fragment.
 420                 </para>
 421             </footnote>
 422             , or extend <classname>Zend_Search_Lucene_Document_Html</classname> class and redefine
 423             <methodname>applyColour($stringToHighlight, $colour)</methodname> method used as a
 424             default highlighting callback.
 425
 426             <footnote>
 427                 <para>
 428                     In both cases returned <acronym>HTML</acronym> is automatically transformed into
 429                     valid <acronym>XHTML</acronym>.
 430                 </para>
 431             </footnote>
 432         </para>
 433
 434         <para>
 435             <link linkend="zend.view.helpers">View helpers</link> also can be used as callbacks in
 436             context of view script:
 437         </para>
 438
 439         <programlisting language="php"><![CDATA[
 440 $doc->highlightExtended('word1 word2 word3...', array($this, 'myViewHelper'));
 441 ]]></programlisting>
 442
 443         <para>
 444             The result of highlighting operation is retrieved by
 445             <code>Zend_Search_Lucene_Document_Html->getHTML()</code> method.
 446         </para>
 447
 448         <note>
 449             <para>
 450                 Highlighting is performed in terms of current analyzer. So all forms of the word(s)
 451                 recognized by analyzer are highlighted.
 452             </para>
 453
 454             <para>
 455                 E.g. if current analyzer is case insensitive and we request to highlight 'text'
 456                 word, then 'text', 'Text', 'TEXT' and other case combinations will be highlighted.
 457             </para>
 458
 459             <para>
 460                 In the same way, if current analyzer supports stemming and we request to highlight
 461                 'indexed', then 'index', 'indexing', 'indices' and other word forms will be
 462                 highlighted.
 463             </para>
 464
 465             <para>
 466                 On the other hand, if word is skipped by current analyzer (e.g. if short words
 467                 filter is applied to the analyzer), then nothing will be highlighted.
 468             </para>
 469         </note>
 470
 471         <para>
 472             The second option is to use
 473             <code>Zend_Search_Lucene_Search_Query->highlightMatches(string $inputHTML[,
 474                 $defaultEncoding = 'UTF-8'[,
 475                 Zend_Search_Lucene_Search_Highlighter_Interface $highlighter]])</code> method:
 476         </para>
 477
 478         <programlisting language="php"><![CDATA[
 479 $query = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
 480 $highlightedHTML = $query->highlightMatches($sourceHTML);
 481 ]]></programlisting>
 482
 483         <para>
 484             Optional second parameter is a default <acronym>HTML</acronym> document encoding. It's
 485             used if encoding is not specified using Content-type HTTP-EQUIV meta tag.
 486         </para>
 487
 488         <para>
 489             Optional third parameter is a highlighter object which has to implement
 490             <classname>Zend_Search_Lucene_Search_Highlighter_Interface</classname> interface:
 491         </para>
 492
 493         <programlisting language="php"><![CDATA[
 494 interface Zend_Search_Lucene_Search_Highlighter_Interface
 495 {
 496     /**
 497      * Set document for highlighting.
 498      *
 499      * @param Zend_Search_Lucene_Document_Html $document
 500      */
 501     public function setDocument(Zend_Search_Lucene_Document_Html $document);
 502
 503     /**
 504      * Get document for highlighting.
 505      *
 506      * @return Zend_Search_Lucene_Document_Html $document
 507      */
 508     public function getDocument();
 509
 510     /**
 511      * Highlight specified words (method is invoked once per subquery)
 512      *
 513      * @param string|array $words  Words to highlight. They could be
 514                                    organized using the array or string.
 515      */
 516     public function highlight($words);
 517 }
 518 ]]></programlisting>
 519
 520         <para>
 521             Where <classname>Zend_Search_Lucene_Document_Html</classname> object is an object
 522             constructed from the source <acronym>HTML</acronym> provided to the
 523             <classname>Zend_Search_Lucene_Search_Query->highlightMatches()</classname> method.
 524         </para>
 525
 526         <para>
 527             If <varname>$highlighter</varname> parameter is omitted, then
 528             <classname>Zend_Search_Lucene_Search_Highlighter_Default</classname> object is
 529             instantiated and used.
 530         </para>
 531
 532         <para>
 533             Highlighter <methodname>highlight()</methodname> method is invoked once per subquery, so
 534             it has an ability to differentiate highlighting for them.
 535         </para>
 536
 537         <para>
 538             Actually, default highlighter does this walking through predefined color table. So you
 539             can implement your own highlighter or just extend the default and redefine color table.
 540         </para>
 541
 542         <para>
 543             <code>Zend_Search_Lucene_Search_Query->htmlFragmentHighlightMatches()</code> has similar
 544             behavior. The only difference is that it takes as an input and returns
 545             <acronym>HTML</acronym> fragment without &lt;>HTML>, &lt;HEAD>, &lt;BODY> tags.
 546             Nevertheless, fragment is automatically transformed to valid <acronym>XHTML</acronym>.
 547         </para>
 548     </sect2>
 549 </sect1>