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

   1 <sect1 id="zend.search.lucene.query-api">
   2     <title>API для построения запросов<!--Query Construction API--></title>
   3
   4     <para>
   5         В дополнение к автоматическому парсингу запросов есть возможность
   6         строить запросы через API.
   7 <!--
   8         In addition to parsing query automatically it's also possible to constract them through API.
   9 -->
  10     </para>
  11
  12     <para>
  13         Пользовательские запросы могут быть объединены с запросами, созданными
  14         через API. Используйте парсер запросов для построения запроса из строки.
  15 <!--
  16         User query can be combined with queries created through API. Use query parser to construct query from a string:
  17 -->
  18         <programlisting language="php"><![CDATA[<?php
  19 $query = Zend_Search_Lucene_Search_QueryParser::parse($queryString);]]></programlisting>
  20     </para>
  21
  22
  23     <sect2 id="zend.search.lucene.queries.exceptions">
  24         <title>Исключения, бросаемые парсером запросов<!--Query Parser Exceptions--></title>
  25         <para>
  26         Парсер запросов может генерировать два типа исключений:
  27 <!--
  28         Query parser may generate two types of exceptions.
  29 -->
  30         <itemizedlist>
  31             <listitem>
  32                 <para>
  33                     <code>Zend_Search_Lucene_Exception</code> бросается, если
  34                     ошибка произошла в самом парсере запросов.
  35 <!--
  36                     <code>Zend_Search_Lucene_Exception</code> is thrown if something wrong in a query parser itself.
  37 -->
  38                 </para>
  39             </listitem>
  40             <listitem>
  41                 <para>
  42                     <code>Zend_Search_Lucene_Search_QueryParserException</code>
  43                     бросается в случае ошибки синтаксиса запроса.
  44 <!--
  45                     <code>Zend_Search_Lucene_Search_QueryParserException</code> is thrown in tha case of
  46                     query syntax exception.
  47 -->
  48                 </para>
  49             </listitem>
  50         </itemizedlist>
  51         Будет хорошей идеей отлавливать запросы
  52         Zend_Search_Lucene_Search_QueryParserException и выводить
  53         соответствующее сообщение.
  54 <!--
  55         Thus that's good idea to catch Zend_Search_Lucene_Search_QueryParserException and make appropriate message:
  56 -->
  57         <programlisting language="php"><![CDATA[<?php
  58 try {
  59     $query = Zend_Search_Lucene_Search_QueryParser::parse($queryString);
  60 } catch (Zend_Search_Lucene_Search_QueryParserException $e) {
  61     echo "Query syntax error: " . $e->getMessage() . "\n";
  62 }]]></programlisting>
  63         </para>
  64
  65         <para>
  66             Тот же самый подход может (и должен) применяться для метода
  67             find() объекта Zend_Search_Lucene.
  68 <!--
  69             The same technique may (and should) be used for find() method of Zend_Search_Lucene object.
  70 -->
  71         </para>
  72     </sect2>
  73
  74     <sect2 id="zend.search.lucene.queries.term-query">
  75             <title>Простой запрос (запрос по одному ключевому слову)<!--Term Query--></title>
  76         <para>
  77         Простые запросы предназначены для поиска по одному элементу.
  78 <!--
  79         Term queries are intended for a searching for a single term.
  80 -->
  81         </para>
  82
  83         <para>
  84         Строка запроса:
  85 <!--
  86         Query string:
  87 -->
  88         </para>
  89         <programlisting language="querystring"><![CDATA[word1]]>
  90         </programlisting>
  91
  92         <para>или</para>
  93
  94         <para>
  95         Построение запроса через API:
  96 <!--
  97         Query construction by API:
  98 -->
  99         </para>
 100         <programlisting language="php"><![CDATA[<?php
 101 $term  = new Zend_Search_Lucene_Index_Term('word1', 'field1');
 102 $query = new Zend_Search_Lucene_Search_Query_Term($term);
 103 $hits  = $index->find($query);]]></programlisting>
 104
 105         <para>
 106             Параметр, задающий поле для поиска ('field1'), является
 107             опциональным. Zend_Search_Lucene производит поиск по всем
 108             полям, если поля для поиска не заданы.
 109 <!--
 110             Term field is optional. Zend_Search_Lucene searches through all fields if field is not specified:
 111 -->
 112             <programlisting language="php"><![CDATA[<?php
 113 $term  = new Zend_Search_Lucene_Index_Term('word1');  // Search 'word1' through all indexed fields
 114 $query = new Zend_Search_Lucene_Search_Query_Term($term);
 115 $hits  = $index->find($query);]]></programlisting>
 116         </para>
 117
 118     </sect2>
 119
 120     <sect2 id="zend.search.lucene.queries.multiterm-query">
 121         <title>Составной запрос (запрос по нескольким ключевым словам)<!--Multi-Term Query--></title>
 122         <para>
 123             Составные запросы предназначены для поиска по набору элементов.
 124 <!--
 125             Multi term queries are intended for a searching for a set of terms.
 126 -->
 127         </para>
 128
 129         <para>
 130             Каждый элемент в наборе может быть определен как "обязательный",
 131             "необязательный" или "запрещенный".
 132 <!--
 133             Each term in a set can be defined as required, prohibited or neither
 134             required, nor prohibited (optional).
 135 -->
 136
 137             <itemizedlist>
 138                 <listitem>
 139                     <para>
 140                         "обязательный" элемент означает, что документы, которые не соответствуют
 141                         данному элементу, не соответствуют всему запросу;
 142 <!--
 143                         required which means that documents which do not match this term
 144                         will not match the query;
 145 -->
 146                     </para>
 147                 </listitem>
 148                 <listitem>
 149                     <para>
 150                         "запрещенный" элемент означает, что документы, соответствующие
 151                         данному элементу, не соответствуют всему запросу;
 152 <!--
 153                         prohibited which means that documents which do match this term
 154                         will not match the query;
 155 -->
 156                     </para>
 157                 </listitem>
 158                 <listitem>
 159                     <para>
 160                          в случае "необязательного" элемента
 161                          документы не обязательно должны соответствовать
 162                          (или не иметь соответствия) элементу. Тем не менее,
 163                          документ должен соответствовать хотя бы одному элементу, чтобы
 164                          соответствовать запросу.
 165 <!--
 166                         neither, in which case matched documents are neither prohibited from
 167                         nor required to match the term. However, a document must match at least
 168                         1 term to match the query.
 169 -->
 170                     </para>
 171                 </listitem>
 172             </itemizedlist>
 173         </para>
 174
 175         <para>
 176             Это значит, что если необязательные элементы добавлены в запрос с
 177             обязательными, то они будут иметь одинаковый набор
 178             результатов, но в случае второго запроса хиты, соответствующие
 179             необязательным элементам, будут перемещены в верх списка
 180             результатов запроса.
 181 <!--
 182             It means, that if optional terms are added to a query with required terms,
 183             then they will have the same result set, but second query will have hits,
 184             which match optional terms, moved to the top of result set.
 185 -->
 186         </para>
 187
 188         <para>
 189             Для составных запросов могут использоваться оба метода поиска.
 190
 191 <!--
 192             Both of a search method can be used for multi term queries.
 193 -->
 194         </para>
 195
 196         <para>
 197             Запрос в виде строки:
 198 <!--
 199             Query string:
 200 -->
 201         </para>
 202         <programlisting language="querystring"><![CDATA[+word1 author:word2 -word3]]></programlisting>
 203
 204         <itemizedlist>
 205             <listitem>
 206                 <para>
 207                     '+' используется для определения обязательного элемента
 208                     <!--is used to define required term.-->
 209                 </para>
 210             </listitem>
 211             <listitem>
 212                 <para>
 213                     '-' используется для определения запрещенного элемента
 214                     <!--is used to define prohibited term.-->
 215                 </para>
 216             </listitem>
 217             <listitem>
 218                 <para>
 219                     Приставка 'field:' используется, чтобы указать поле документа
 220                     для поиска. Если она опущена, то используется поле 'contents'.
 221 <!--
 222                     'field:' prefix is used to indicate document field for a search.
 223                     If it's omitted, then 'contents' is used.
 224 -->
 225                 </para>
 226             </listitem>
 227         </itemizedlist>
 228
 229         <para>или</para>
 230
 231         <para>
 232         Построение запроса через программный интерфейс:
 233 <!--
 234         Query construction by API:
 235 -->
 236         </para>
 237         <programlisting language="php"><![CDATA[<?php
 238 $query = new Zend_Search_Lucene_Search_Query_MultiTerm();
 239
 240 $query->addTerm(new Zend_Search_Lucene_Index_Term('word1'), true);
 241 $query->addTerm(new Zend_Search_Lucene_Index_Term('word2'), null);
 242 $query->addTerm(new Zend_Search_Lucene_Index_Term('word3'), false);
 243
 244 $hits  = $index->find($query);]]></programlisting>
 245
 246         <para>
 247             Массив <varname>$signs</varname> содержит информацию о типах элементов:
 248 <!--
 249             <varname>$signs</varname> array contains an information about term type:
 250 -->
 251             <itemizedlist>
 252                 <listitem>
 253                     <para>
 254                         <constant>TRUE</constant> используется для определения обязательных элементов.
 255 <!--
 256                         true is used to define required term.
 257 -->
 258                     </para>
 259                 </listitem>
 260
 261                 <listitem>
 262                     <para>
 263                         <constant>FALSE</constant> используется для определения запрещенных элементов.
 264 <!--
 265                         false is used to define prohibited term.
 266 -->
 267                     </para>
 268                 </listitem>
 269                 <listitem>
 270                     <para>
 271                         <constant>NULL</constant> используется для определения необязательных
 272                         элементов.
 273 <!--
 274                         null is used to define neither required,
 275                         nor prohibited term.
 276 -->
 277                     </para>
 278                 </listitem>
 279             </itemizedlist>
 280         </para>
 281     </sect2>
 282
 283     <sect2 id="zend.search.lucene.queries.phrase-query">
 284         <title>Фразовый запрос<!--Phrase Query--></title>
 285         <para>
 286             Фразовые запросы предназначены для поиска по фразам.
 287 <!--
 288             Phrase Queries are intended for a searching for a phrases.
 289 -->
 290         </para>
 291
 292         <para>
 293             Фразовые запросы являются очень гибкими и позволяют искать как
 294             точные фразы, так и неточные.
 295 <!--
 296             Phrase Queries are very flexible and allow to search exact phrases as well as sloppy phrases.
 297 -->
 298         </para>
 299
 300         <para>
 301             Фразы могут содержать пропуски или несколько
 302             слов в одной и той же позиции. (Это может быть сгенерировано анализатором
 303             для различных целей. Например, элементы могут повторяться для
 304             повышения "веса" или в одной позиции могут быть размещены несколько
 305             синонимов). В соответствии с этим фразовые запросы
 306             могут строиться только через программный интерфейс:
 307 <!--
 308             Phrases can also contain gaps or terms in the same places.
 309             (It can be generated by Analyser for different
 310             purposes. Ex. term can be duplicated to increase term
 311             weight or several synonyms can be placed into one position).
 312             According to this phrase queries can be constructed only by API now:
 313 -->
 314         </para>
 315
 316         <programlisting language="php"><![CDATA[<?php
 317 $query1 = new Zend_Search_Lucene_Search_Query_Phrase();
 318
 319 // Добавление 'word1' в относительную позицию 0.
 320 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word1'));
 321
 322 // Добавление 'word2' в относительную позицию 1.
 323 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word2'));
 324
 325 // Добавление 'word3' в относительную позицию 3.
 326 $query1->addTerm(new Zend_Search_Lucene_Index_Term('word3'), 3);
 327
 328 ...
 329
 330 $query2 = new Zend_Search_Lucene_Search_Query_Phrase(
 331                 array('word1', 'word2', 'word3'), array(0,1,3));
 332
 333 ...
 334
 335 // Запрос без промежутков.
 336 $query3 = new Zend_Search_Lucene_Search_Query_Phrase(
 337                 array('word1', 'word2', 'word3'));
 338
 339 ...
 340
 341 $query4 = new Zend_Search_Lucene_Search_Query_Phrase(
 342                 array('word1', 'word2'), array(0,1), 'annotation');]]></programlisting>
 343
 344         <para>
 345             Фразовый запрос может строиться сразу с помощью конструктора класса
 346             или пошагово с помощью метода
 347             <code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code>.
 348 <!--
 349             Phrase query can be constructed by one step with a class constructor or step by step with a
 350             <code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code> method.
 351 -->
 352         </para>
 353
 354         <para>
 355             Конструктор класса <code>Zend_Search_Lucene_Search_Query_Phrase</code>
 356             принимает три необязательных параметра:
 357 <!--
 358             Zend_Search_Lucene_Search_Query_Phrase class constructor takes
 359             three optional arguments:
 360 -->
 361         </para>
 362
 363         <programlisting language="php"><![CDATA[<?php
 364 Zend_Search_Lucene_Search_Query_Phrase([array $terms[, array $offsets[, string $field]]]);]]></programlisting>
 365
 366         <para>
 367             <varname>$terms</varname> является массивом строк, который содержит набор
 368             элементов фразы. Если он опущен или равен <constant>NULL</constant>,
 369             то строится пустой запрос.
 370 <!--
 371             <varname>$terms</varname> is an array of strings, which contains a set of phrase terms.
 372             If it's omitted or equal to null, then empty query is constructed.
 373 -->
 374         </para>
 375
 376         <para>
 377             <varname>$offsets</varname> является массивом целочисленных значений,
 378             который содержит смещения элементов во фразе. Если он опущен или равен
 379             <constant>NULL</constant>, то позиции элементов предполагаются как
 380             <code>array(0, 1, 2, 3, ...)</code>.
 381 <!--
 382             <varname>$offsets</varname> is an array of integers, which contains offsets of terms in a phrase.
 383             If it's omitted or equal to null, then terms positions are supposed as <code>array(0, 1, 2, 3, ...)</code>.
 384 -->
 385         </para>
 386
 387         <para>
 388             <varname>$field</varname> является строкой, которая указывает поле
 389             документа, в котором производится поиск. Если он опущен или равен
 390             <constant>NULL</constant>, то поиск производится в поле по умолчанию.
 391             Данная версия Zend_Search_Lucene трактует поле 'contents'
 392             как поле, выбираемое по умолчанию, но в следующих версиях
 393             планируется добавить возможность указания любого поля,
 394             как выбираемого по умолчанию.
 395 <!--
 396             <varname>$field</varname> is a string, which indicates searched document field.
 397             If it's omitted or equal to null, then default field is searched.
 398             This version of Zend_Search_Lucene treates 'contents' field as a default, but it's planned to change this
 399             behavior to "any field" in next versions.
 400 -->
 401         </para>
 402
 403         <para>
 404             Таким образом:
 405 <!--
 406             Thus:
 407 -->
 408         </para>
 409         <programlisting language="php"><![CDATA[<?php
 410 $query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'));]]></programlisting>
 411         <para>
 412             будет искать фразу 'zend framework'.
 413 <!--
 414             will search for 'zend framework' phrase.
 415 -->
 416         </para>
 417
 418         <programlisting language="php"><![CDATA[<?php
 419 $query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'download'), array(0, 2));]]></programlisting>
 420         <para>
 421             будет искать фразу 'zend ????? download', такой запрос соответствует фразам
 422             'zend platform download', 'zend studio download',
 423             'zend core download', 'zend framework download' и т.д.
 424 <!--
 425             will search for 'zend ????? download' phrase and match 'zend platform download', 'zend studio download',
 426             'zend core download', 'zend framework download' and so on.
 427 -->
 428         </para>
 429
 430         <programlisting language="php"><![CDATA[<?php
 431 $query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'), null, 'title');]]></programlisting>
 432
 433         <para>
 434             будет искать фразу 'zend framework' в поле 'title'.
 435 <!--
 436             will search for 'zend framework' phrase in a 'title' field.
 437 -->
 438         </para>
 439
 440         <para>
 441             Метод <code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code>
 442             принимает два аргумента — объект элемента
 443             <code>Zend_Search_Lucene_Index_Term</code> в качестве обязательного
 444             параметра и позицию элемента в качестве необязательного:
 445 <!--
 446             <code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code> method
 447             takes two arguments.
 448             Required <code>Zend_Search_Lucene_Index_Term</code> object and optional position:
 449 -->
 450         </para>
 451         <programlisting language="php"><![CDATA[<?php
 452 Zend_Search_Lucene_Search_Query_Phrase::addTerm(Zend_Search_Lucene_Index_Term $term[, integer $position]);]]></programlisting>
 453
 454         <para>
 455             <varname>$term</varname> описывает следующий элемент во фразе. Он должен
 456             указывать на то же самое поле, что и предыдущие элементы,
 457             иначе будет сгенерировано исключение.
 458 <!--
 459             <varname>$term</varname> describes next term in a phrase. It must indicate
 460             the same field as previous terms.
 461             Otherwise an exception will be thrown.
 462 -->
 463         </para>
 464
 465         <para>
 466             <varname>$position</varname> указывает позицию элемента.
 467 <!--
 468             <varname>$position</varname> indicates term position.
 469 -->
 470         </para>
 471
 472         <para>
 473 <!--
 474             Thus:
 475 -->
 476         </para>
 477         <programlisting language="php"><![CDATA[<?php
 478 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 479 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'));
 480 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'));]]></programlisting>
 481         <para>
 482             будет искать фразу 'zend framework'.
 483 <!--
 484             will search for 'zend framework' phrase.
 485 -->
 486         </para>
 487
 488         <programlisting language="php"><![CDATA[<?php
 489 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 490 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'), 0);
 491 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'), 2);]]></programlisting>
 492         <para>
 493             будет искать фразу 'zend ????? download', такой запрос соответствует фразам
 494             'zend platform download', 'zend studio download',
 495             'zend core download', 'zend framework download' и т.д.
 496 <!--
 497             will search for 'zend ????? download' phrase and match 'zend platform download', 'zend studio download',
 498             'zend core download', 'zend framework download' and so on.
 499 -->
 500         </para>
 501         <programlisting language="php"><![CDATA[<?php
 502 $query = new Zend_Search_Lucene_Search_Query_Phrase();
 503 $query->addTerm(new Zend_Search_Lucene_Index_Term('zend', 'title'));
 504 $query->addTerm(new Zend_Search_Lucene_Index_Term('framework', 'title'));]]></programlisting>
 505         <para>
 506             будет искать фразу 'zend framework' в поле 'title'.
 507 <!--
 508             will search for 'zend framework' phrase in a 'title' field.
 509 -->
 510         </para>
 511
 512         <para>
 513             Коэффициент расстояния устанавливает допустимое количество других слов,
 514             находящихся между словами во фразе запроса. Если он равен нулю, то
 515             ищется точная фраза. При бОльших значениях это будет работать как
 516             оператор WITHIN или NEAR
 517 <!--
 518             Sloop factor sets the number of other words permitted between words in query phrase. If zero,
 519             then this is an exact phrase search.  For larger values this works like a WITHIN or NEAR operator.
 520 -->
 521         </para>
 522
 523         <para>
 524             По сути, это управляемое расстояние, где единицы соответствуют
 525             перемене мест элементов относительно их позиции во фразе поиска.
 526             Например, для переключения порядка двух слов требуются две перемены мест
 527             (первое перемещение помещает слова друг над другом). Поэтому
 528             для того, чтобы разрешить изменение порядка фраз, коэффициент
 529             расстояния должен быть равен, как минимум, двум.
 530 <!--
 531             The slop is in fact an edit-distance, where the units correspond to
 532             moves of terms in the query phrase
 533             out of position.  For example, to switch the order of two words
 534             requires two moves (the first move places
 535             the words atop one another), so to permit re-orderings of phrases,
 536             the slop must be at least two.
 537 -->
 538         </para>
 539
 540         <para>
 541             Более точные соответствия имеют бОльшую релевантность, чем менее точные,
 542             таким образом, результаты сортируются по точности. По умолчанию
 543             коэффициент расстояния равен нулю, что означает точное соответствие.
 544 <!--
 545             More exact matches are scored higher than sloppier matches, thus search
 546             results are sorted by exactness.
 547             The slop is zero by default, requiring exact matches.
 548 -->
 549         </para>
 550
 551         <para>
 552             Коэффициент расстояния может быть указан после создания запроса:
 553 <!--
 554             Sloop factor can be assigned after query creation:
 555 -->
 556         </para>
 557
 558         <programlisting language="php"><![CDATA[<?php
 559 // Запрос без пропусков.
 560 $query = new Zend_Search_Lucene_Search_Query_Phrase(array('word1', 'word2'));
 561
 562 // Поиск 'word1 word2', 'word1 ... word2'
 563 $query->setSlop(1);
 564 $hits1 = $index->find($query);
 565
 566 // Поиск 'word1 word2', 'word1 ... word2',
 567 // 'word1 ... ... word2', 'word2 word1'
 568 $query->setSlop(2);
 569 $hits2 = $index->find($query);]]></programlisting>
 570
 571     </sect2>
 572 </sect1>
 573
 574 <!--
 575 vim:se ts=4 sw=4 et:
 576 -->