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

   1 <sect1 id="zend.search.lucene.searching">
   2     <title>Поиск по индексу<!--Searching an Index--></title>
   3
   4     <sect2 id="zend.search.lucene.searching.query_building">
   5         <title>Построение запросов<!--Building Queries--></title>
   6
   7         <para>
   8             Производить поиск по индексу можно двумя способами. Первый способ
   9             использует парсер запросов для построения запросов из строки.
  10             Второй способ дает возможность создавать свои запросы
  11             через программный интерфейс Zend_Search_Lucene.
  12 <!--
  13             There are two ways to search the index. The first method uses
  14             Query Parser to construct query from a string. The second provides
  15             the ability to create your own queries through the Zend_Search_Lucene API.
  16 -->
  17         </para>
  18
  19         <para>
  20         В случае выбора парсера запросов учтите следующее:
  21 <!--
  22         Before choosing to use the provided Query Parser, please consider
  23         the following:
  24 -->
  25
  26             <orderedlist>
  27                 <listitem>
  28                     <para>
  29                         Если вы программно генерируете  строку запроса и затем парсите
  30                         ее с помощью парсера запросов, то вам следует серьезно подумать
  31                         о построении запросов непосредственно через программный интерфейс.
  32                         Другими словами, парсер запросов предназначен для текста, вводимого
  33                         пользователем, а не генерируемого программным способом.
  34 <!--
  35                         If you are programmatically generating a query string and then parsing
  36                         it with the query parser then you should seriously consider building
  37                         your queries directly with the query API. In other words, the query
  38                         parser is designed for human-entered text, not for program-generated text.
  39 -->
  40                     </para>
  41                 </listitem>
  42                 <listitem>
  43                     <para>
  44                         Не разбитые на лексемы поля лучше добавлять непосредственно
  45                         в запросы, а не через парсер запросов. Если значения полей программно
  46                         генерируются приложением, то должны быть отдельные элементы
  47                         запроса для этого поля. Анализатор, используемый
  48                         парсером запросов, предназначен для преобразования
  49                         введенного пользователем текста в элементы запроса.
  50                         Программно генерируемые значения, такие, как даты, ключевые слова
  51                         и т.д., должны генерироваться единообразно.
  52 <!--
  53                         Untokenized fields are best added directly to queries, and not through
  54                         the query parser. If a field's values are generated programmatically
  55                         by the application, then so should query clauses for this field.
  56                         An analyzer, which the query parser uses, is designed to convert
  57                         human-entered text to terms. Program-generated values, like dates,
  58                         keywords, etc., should be consistently program-generated.
  59 -->
  60                     </para>
  61                 </listitem>
  62                 <listitem>
  63                     <para>
  64                         В форме запроса поля с основным текстом должны использовать
  65                         парсер запросов. Все остальные, такие, как периоды времени,
  66                         ключевые слова и т.д, лучше добавлять непосредственно
  67                         через программный интерфейс для запросов. Поля с ограниченным
  68                         набором значений, которые могут отображаться в виде выпадающего
  69                         списка, лучше не добавлять в строку запроса, которая
  70                         парсится, а как элемент запроса.
  71 <!--
  72                         In a query form, fields which are general text should use the query parser.
  73                         All others, such as date ranges, keywords, etc. are better added directly
  74                         through the query API. A field with a limit set of values, that can be
  75                         specified with a pull-down menu should not be added to a query string
  76                         which is subsequently parsed, but rather added as a TermQuery clause.
  77 -->
  78                     </para>
  79                 </listitem>
  80                 <listitem>
  81                     <para>
  82                         Булевы запросы позволяют объединять несколько запросов в
  83                         один. Таким образом, это является наилучшим путем
  84                         добавления дополнительных критериев пользовательского
  85                         поиска, определяемых строкой запроса.
  86 <!--
  87                         Boolean queries allow to mix several other queries into new one.
  88                         Thus it's the best way to add some additional criteria to user search, defined by
  89                         a query string.
  90 -->
  91                     </para>
  92                 </listitem>
  93             </orderedlist>
  94
  95         </para>
  96
  97         <para>
  98             Оба способа используют один и тот же метод программного интерфейса
  99             для поиска в индексе:
 100 <!--
 101             Both ways use the same API method to search through the index:
 102 -->
 103         </para>
 104
 105         <programlisting language="php"><![CDATA[<?php
 106 require_once('Zend/Search/Lucene.php');
 107
 108 $index = Zend_Search_Lucene::open('/data/my_index');
 109
 110 $index->find($query);]]>   </programlisting>
 111
 112         <para>
 113             Метод <code>Zend_Search_Lucene::find()</code> автоматически определяет
 114             тип ввода и использует парсер запросов для построения соответствующего
 115             объекта Zend_Search_Lucene_Search_Query.
 116 <!--
 117             The <code>Zend_Search_Lucene::find()</code> method determines input type automatically and
 118             uses query parser to construct appropriate Zend_Search_Lucene_Search_Query object
 119             from a string.
 120 -->
 121         </para>
 122
 123         <para>
 124             Важно отметить, что парсер запросов использует стандартный
 125             анализатор для разбиения на лексемы отдельных частей строки запроса.
 126             Таким образом, все преобразования, проделываемые с индексируемым
 127             текстом, также проделываются и с частями строки запроса.
 128 <!--
 129             It is important to note that query parser uses standard analyzer to tokenize separate parts of query string.
 130             Thus all transformations, which are done on indexed text are also done on query string entries.
 131 -->
 132         </para>
 133         <para>
 134             Это могут быть приведение к нижнему регистру для того, чтобы сделать
 135             поиск нечувствительным к регистру, удаление запрещенных слов
 136             и т.д.
 137 <!--
 138             It may be transforming to lower case to make search case-insensitive, removing stop-words, stamming and
 139             mauch more other things.
 140 -->
 141         </para>
 142         <para>
 143             В противоположность парсеру запросов, методы API не преобразовывают
 144             или фильтруют входные элементы. Таким образом, API является более
 145             подходящим для сгенерированных компьютером или не разбитых на
 146             лексемы полей.
 147 <!--
 148             As opposed to it, API method doesn't transform or filter input terms. Thus it's more suitable for
 149             computer generated or untokenized fields.
 150 -->
 151         </para>
 152
 153         <sect3 id="zend.search.lucene.searching.query_building.parsing">
 154             <title>Парсинг запроса<!--Query parsing--></title>
 155             <para>
 156                 Метод <code>Zend_Search_Lucene_Search_QueryParser::parse()</code>
 157                 может использоваться для парсинга строки запроса и
 158                 преобразования ее в объект запроса.
 159 <!--
 160                 <code>Zend_Search_Lucene_Search_QueryParser::parse()</code> method may be used to parse query string
 161                 into query object.
 162 -->
 163             </para>
 164
 165             <para>
 166                 Этот объект может использоваться в методах программного
 167                 интерфейса для объединения программно сгенерированных
 168                 запросов с введенными пользователем.
 169 <!--
 170                 This object may be used in query construction API methods to combine user entered queries with
 171                 machine generated queries.
 172 -->
 173             </para>
 174
 175             <para>
 176                 Сейчас в некоторых случаях только таким способом можно будет
 177                 производить поиск значений в полях, которые не были
 178                 разбиты на лексемы.
 179 <!--
 180                 Actually, in some cases it's only way to search for values within untokenized fields:
 181 -->
 182
 183                 <programlisting language="php"><![CDATA[<?php
 184 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
 185
 186 $pathTerm  = new Zend_Search_Lucene_Index_Term('/data/doc_dir/' . $filename, 'path');
 187 $pathQuery = new Zend_Search_Lucene_Search_Query_Term($pathTerm);
 188
 189 $query = new Zend_Search_Lucene_Search_Query_Boolean();
 190 $query->addSubquery($userQuery, true /* required */);
 191 $query->addSubquery($pathQuery, true /* required */);
 192
 193 $hits = $index->find($query);]]></programlisting>
 194             </para>
 195
 196             <para>
 197                 Метод <code>Zend_Search_Lucene_Search_QueryParser::parse()</code>
 198                 также принимает необязательный параметр, через который
 199                 указывается кодировка строки запроса.
 200 <!--
 201                 <code>Zend_Search_Lucene_Search_QueryParser::parse()</code> method also takes optional encoding parameter,
 202                 which can specify query string encoding:
 203 -->
 204             <programlisting language="php"><![CDATA[<?php
 205 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr, 'iso-8859-5');]]></programlisting>
 206             </para>
 207
 208             <para>
 209                 Если этот параметр опущен, то используется текущая локаль.
 210 <!--
 211                 If encoding is omitted, then current locale is used.
 212 -->
 213             </para>
 214
 215             <para>
 216                 Можно также указать используемую по умолчанию кодировку для
 217                 строки запроса через метод <code>Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding()</code>:
 218 <!--
 219                 It's also possible to specify default query string encoding with
 220                 <code>Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding()</code> method:
 221 -->
 222             <programlisting language="php"><![CDATA[<?php
 223 Zend_Search_Lucene_Search_QueryParser::setDefaultEncoding('iso-8859-5');
 224 ...
 225 $userQuery = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);]]></programlisting>
 226             </para>
 227
 228             <para>
 229                 <code>Zend_Search_Lucene_Search_QueryParser::getDefaultEncoding()</code>
 230                 возвращает используемую по умолчанию кодировку для строки
 231                 запроса (пустая строка означает "текущая локаль").
 232 <!--
 233                 <code>Zend_Search_Lucene_Search_QueryParser::getDefaultEncoding()</code> returns current default query
 234                 string encoding (empty string means "current locale").
 235 -->
 236             </para>
 237         </sect3>
 238     </sect2>
 239
 240     <sect2 id="zend.search.lucene.searching.results">
 241         <title>Результаты поиска<!--Search Results--></title>
 242         <para>
 243             Результат поиска является массивом объектов
 244             Zend_Search_Lucene_Search_QueryHit. Все эти объекты имеют два
 245             свойства: <varname>$hit->document</varname> - номер документа в индексе,
 246             <varname>$hit->score</varname> - ранг "хита" в результате поиска.
 247             Результат упорядочен по рангу ("хиты" с наибольшим рангом идут
 248             первыми).
 249
 250 <!--
 251             The search result is an array of Zend_Search_Lucene_Search_QueryHit objects.  Each of these has
 252             two properties: <varname>$hit->document</varname> is a document number within
 253             the index and <varname>$hit->score</varname> is a score of the hit in
 254             a search result. Result is ordered by score (top scores come first).
 255 -->
 256         </para>
 257
 258         <para>
 259             Объект Zend_Search_Lucene_Search_QueryHit также предоставляют все
 260             поля документа Zend_Search_Lucene_Document как свойства объекта. В
 261             данном примере возвращается "хит" и соответствующий ему документ
 262             имеет два поля: заголовок и автор.
 263 <!--
 264             The Zend_Search_Lucene_Search_QueryHit object also exposes each field of the Zend_Search_Lucene_Document found by
 265             the hit as a property of the hit.  In this example, a hit is returned and
 266             the corresponding document has two fields: title and author.
 267 -->
 268         </para>
 269         <programlisting language="php"><![CDATA[<?php
 270 require_once('Zend/Search/Lucene.php');
 271
 272 $index = Zend_Search_Lucene::open('/data/my_index');
 273
 274 $hits = $index->find($query);
 275
 276 foreach ($hits as $hit) {
 277     echo $hit->score;
 278     echo $hit->title;
 279     echo $hit->author;
 280 }
 281 ?>]]></programlisting>
 282
 283         <para>
 284             Сохраненные в индексе поля всегда возвращаются в кодировке UTF-8.
 285 <!--
 286             Stored fields are always returned in UTF-8 encoding.
 287 -->
 288         </para>
 289
 290         <para>
 291             Исходный объект документа Zend_Search_Lucene_Document может также
 292             быть получен из Zend_Search_Lucene_Search_QueryHit. Вы можете
 293             извлечь сохраненные в индексе части документа, используя метод
 294             <code>getDocument()</code> объекта индекса и затем получая из через
 295             метод <code>getFieldValue()</code>:
 296 <!--
 297             Optionally, the original Zend_Search_Lucene_Document object can be returned from the
 298             Zend_Search_Lucene_Search_QueryHit.
 299
 300             You can retrieve stored parts of the document by using the <code>getDocument()</code>
 301             method of the index object and then get them by
 302             <code>getFieldValue()</code> method:
 303 -->
 304         </para>
 305
 306         <programlisting language="php"><![CDATA[<?php
 307 require_once('Zend/Search/Lucene.php');
 308
 309 $index = Zend_Search_Lucene::open('/data/my_index');
 310
 311 $hits = $index->find($query);
 312 foreach ($hits as $hit) {
 313     // возвращает объект для этого "хита"
 314     echo $document = $hit->getDocument();
 315
 316     // возвращает объект Zend_Search_Lucene_Field
 317     // из Zend_Search_Lucene_Document
 318     echo $document->getField('title');
 319
 320     // возвращает строковое значение объекта Zend_Search_Lucene_Field
 321     echo $document->getFieldValue('title');
 322
 323     // делает то же самое, что и getFieldValue()
 324     echo $document->title;
 325 }
 326 ?>]]></programlisting>
 327
 328         <para>
 329         Поля, доступные через объект Zend_Search_Lucene_Document, определяются
 330         во время индексирования. Поля документа либо только индексируются, либо
 331         индексируются и сохраняются в индексе индесирующим приложением
 332         (например, LuceneIndexCreation.jar).
 333 <!--
 334         The fields available from the Zend_Search_Lucene_Document object are determined at
 335         the time of indexing.  The document fields are either indexed, or
 336         index and stored, in the document by the indexing application
 337         (e.g. LuceneIndexCreation.jar).
 338 -->
 339         </para>
 340
 341         <para>
 342         Обратите внимание, что идентификатор документа (в нашем примере — 'path')
 343         также сохраняется в индексе и должен извлекаться из него.
 344 <!--
 345         Pay attention, that document identity ('path' in our example) is also stored
 346         in the index and must be retrieved from them.
 347 -->
 348         </para>
 349
 350     </sect2>
 351
 352
 353     <sect2 id="zend.search.lucene.searching.results-scoring">
 354         <title>Ранжирование результата<!--Results Scoring--></title>
 355         <para>
 356             Zend_Search_Lucene использует тот же самый алгоритм ранжирования,
 357             что и Java Lucene. Результаты поиска по умолчанию сортируются по
 358             рангу (релевантности). "Хиты" с наибольшим рангом идут первыми, и
 359             документы, имеющие больший ранг, болльше соответствуют запросу, чем
 360             документы с меньшим рангом.
 361 <!--
 362             Zend_Search_Lucene uses the same scoring algorithms as Java Lucene.
 363             Hits in search result are ordered by score by default. Hits with greater score come first, and
 364             documents having higher scores match the query more than documents having lower scores.
 365 -->
 366         </para>
 367
 368         <para>
 369             Приблизительно говоря, документы, в которых искомый элемент или фраза
 370             встречаются чаще, будут иметь более высокий ранг.
 371 <!--
 372             Roughly speaking, search hits that contain the searched term or phrase more frequently
 373             will have a higher score.
 374 -->
 375         </para>
 376
 377         <para>
 378             Число, соответствующее рангу, может быть получено через
 379             свойство <code>score</code>:
 380 <!--
 381             Score can be retrived by <code>score</code> property of hit:
 382 -->
 383         </para>
 384
 385         <programlisting language="php"><![CDATA[<?php
 386 $hits = $index->find($query);
 387
 388 foreach ($hits as $hit) {
 389     echo $hit->id;
 390     echo $hit->score;
 391 }]]>   </programlisting>
 392
 393         <para>
 394             Для вычисления ранга используется класс Zend_Search_Lucene_Search_Similarity.
 395             За подробностями см. раздел
 396             <link linkend="zend.search.lucene.extending.scoring">Расширяемость. Алгоритмы ранжирования</link>.
 397 <!--
 398             Zend_Search_Lucene_Search_Similarity class is used to calculate score.
 399             See <link linkend="zend.search.lucene.extending.scoring">Extensibility. Scoring Algorithms</link> section for details.
 400 -->
 401         </para>
 402
 403     </sect2>
 404
 405     <sect2 id="zend.search.lucene.searching.sorting">
 406         <title>Сортировка результатов поиска<!--Search Result Sorting--></title>
 407         <para>
 408             По умолчанию результаты поиска сортируются по рангу. Вы можете
 409             изменить это поведение установкой поля (полей) для сортировки, типа
 410             сортировки и порядка сортировки.
 411 <!--
 412             Search result is sorted by score by default. You change this by setting a sort field (or fields), sort type
 413             and sort order parameters.
 414 -->
 415         </para>
 416
 417         <para>
 418             <varname>$index->find()</varname> может принимать несколько необязательных
 419             параметров:
 420 <!--
 421             <varname>$index->find()</varname> call may take several optional parameters:
 422 -->
 423             <programlisting language="php"><![CDATA[<?php
 424 $index->find($query [, $sortField [, $sortType [, $sortOrder]]] [, $sortField2 [, $sortType [, $sortOrder]]] ...);]]></programlisting>
 425         </para>
 426
 427         <para>
 428             <varname>$sortField</varname> является именем сохраненного в индексе поля
 429             для сортировки результата.
 430 <!--
 431             <varname>$sortField</varname> is a name of stored field to sort result.
 432 -->
 433         </para>
 434
 435         <para>
 436             <varname>$sortType</varname> может быть опущен или принимать значения
 437             <code>SORT_REGULAR</code> (сравнивать элементы как обычно, значение по умолчанию),
 438             <code>SORT_NUMERIC</code> (сравнивать элементы как числа),
 439             <code>SORT_STRING</code> (сравнивать элементы как строки).
 440 <!--
 441             <varname>$sortType</varname> may be omitted or take values
 442             <code>SORT_REGULAR</code> (compare items normally, default value),
 443             <code>SORT_NUMERIC</code> (compare items numerically),
 444             <code>SORT_STRING</code> (compare items as strings).
 445 -->
 446         </para>
 447
 448         <para>
 449             <varname>$sortOrder</varname> может быть опущен или принимать значения
 450             <code>SORT_ASC</code> (сортировать в порядке возрастания, значение по умолчанию),
 451             <code>SORT_DESC</code> (сортировать в порядке убывания).
 452 <!--
 453             <varname>$sortOrder</varname> may be omitted or take values
 454             <code>SORT_ASC</code> (sort in ascending order, default value),
 455             <code>SORT_DESC</code> (sort in descending order).
 456 -->
 457         </para>
 458
 459         <para>
 460 <!--
 461             Examples:
 462 -->
 463             <programlisting language="php"><![CDATA[<?php
 464 $index->find($query, 'quantity', SORT_NUMERIC, SORT_DESC);]]></programlisting>
 465             <programlisting language="php"><![CDATA[<?php
 466 $index->find($query, 'fname', SORT_STRING, 'lname', SORT_STRING);]]></programlisting>
 467             <programlisting language="php"><![CDATA[<?php
 468 $index->find($query, 'name', SORT_STRING, 'quantity', SORT_NUMERIC, SORT_DESC);]]></programlisting>
 469         </para>
 470
 471         <para>
 472             Будьте осторожны, когда используете сортировку, отличную от
 473             принятой по умолчанию. Для этого нужно полное извлечение документов
 474             из индекса, что может привести к резкому снижению
 475             производительности.
 476 <!--
 477             Please be careful when using non-default search order.
 478             It needs to retrive documents completely from an index and may drammatically slow down search performance.
 479 -->
 480         </para>
 481     </sect2>
 482
 483     <sect2 id="zend.search.lucene.searching.highlighting">
 484         <title>Подсветка результатов поиска<!--Search Results Highlighting--></title>
 485         <para>
 486             Метод
 487             <code>Zend_Search_Lucene_Search_Query::highlightMatches()</code>
 488             позволяет подсвечивать в HTML-документе элементы, присутствующие в
 489             контексте поискового запроса:
 490 <!--
 491             <code>Zend_Search_Lucene_Search_Query::highlightMatches()</code>
 492             method allows to highlight HTML document terms
 493             in context of search query:
 494 -->
 495             <programlisting language="php"><![CDATA[<?php
 496 $query = Zend_Search_Lucene_Search_QueryParser::parse($queryStr);
 497 $hits = $index->find($query);
 498 ...
 499 $highlightedHTML = $query->highlightMatches($sourceHTML);]]></programlisting>
 500         </para>
 501
 502         <para>
 503             Метод <code>highlightMatches()</code> для обработки HTML использует
 504             класс <code>Zend_Search_Lucene_Document_Html</code> (см.
 505             <link linkend="zend.search.lucene.index-creation.html-documents">раздел
 506             "HTML-документы"</link>). Поэтому этот метод предъявляет те же
 507             требования к HTML-коду, что и используемый класс.
 508 <!--
 509             <code>highlightMatches()</code> method utilizes
 510             <code>Zend_Search_Lucene_Document_Html</code> class
 511             (see <link linkend="zend.search.lucene.index-creation.html-documents">HTML
 512             documents section</link> for details)
 513             for HTML processing. So it has the same requirements for HTML source.
 514 -->
 515         </para>
 516     </sect2>
 517
 518 </sect1>
 519
 520 <!--
 521 vim:se ts=4 sw=4 et:
 522 -->