repo_zf1/documentation/manual/ru/module_specs/Zend_Search_Lucene-QueryLanguage.xml

<sect1 id="zend.search.lucene.query-language">
    <title>Язык запросов<!--Query Language--></title>

    <para>
        Java Lucene и Zend_Search_Lucene предоставляют мощный язык запросов.
<!--
        Java Lucene and Zend_Search_Lucene provide quite powerful query language.
-->
    </para>

    <para>
        Он в основном один и тот же, но имеются некоторые различия, которые
        будут описаны ниже.
<!--
        It mostly the same, but has some diffirences, which are mentioned below.
-->
    </para>

    <para>
        Полную документацию по синтаксису запросов для Java Lucene можно найти
        <ulink url="http://lucene.apache.org/java/docs/queryparsersyntax.html">здесь</ulink>.
<!--
        Full Java Lucene query language syntax documentation can be found
        <ulink url="http://lucene.apache.org/java/docs/queryparsersyntax.html">here</ulink>.
-->
    </para>

    <sect2 id="zend.search.lucene.query-language.terms">
        <title>Элементы<!--Terms--></title>

        <para>
            Запрос делится на элементы и операторы. Есть следующие типы
            элементов: одиночный элемент, фразы и подзапросы.
<!--
            A query is broken up into terms and operators. There are three types of terms: Single Terms, Phrases,
            and Subqueries.
-->
        </para>
        <para>
            Одиночный элемент – это одно слово, например: "test" или "hello".
<!--
            A Single Term is a single word such as "test" or "hello".
-->
        </para>
        <para>
            Фраза – это группа слов, окруженная двойными кавычками, например:
            "hello dolly".
<!--
            A Phrase is a group of words surrounded by double quotes such as "hello dolly".
-->
        </para>
        <para>
            Подзапрос – это запрос, окруженный скобками, например: "(hello
            dolly)".
<!--
            A Subquery is a query surrounded by parentheses such as "(hello dolly)".
-->
        </para>
        <para>
            Несколько элемнтов могут комбинироваться с булевыми операторами для
            составления более сложных запросов (см. ниже).

<!--
            Multiple terms can be combined together with Boolean operators to form a more complex query (see below).
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.fields">
        <title>Поля<!--Fields--></title>

        <para>
            Lucene поддерживает данные, хранящиеся в полях. Производя поиск,
            можно указывать поля или использовать поле по умолчанию. Имена полей
            зависят от проиндексированных данных, а используемое по умолчание
            поле определяется через текущие настройки.
<!--
            Lucene supports fielded data. When performing a search you can either specify a field, or use
            the default field. The field names depend on indexed data and default field is defined
            by current settings.
-->
        </para>
        <para>
            Первым и важным отличием от Java Lucene является то, что
            по умолчанию элементы ищутся <emphasis>по всем полям</emphasis>.
<!--
            The first and major difference from Java Lucene is that terms are searched through
            <emphasis>all fields</emphasis> by default.
-->
        </para>
        <para>
            В классе Zend_Search_Lucene есть два статических метода, которые
            позволяют работать с настройками:
<!--
            There are two static methods in Zend_Search_Lucene class, which allow to operate with this settengs:
-->
        </para>
        <programlisting language="php"><![CDATA[<?php
$defaultSearchField = Zend_Search_Lucene::getDefaultSearchField();
...
Zend_Search_Lucene::setDefaultSearchField('contents');]]></programlisting>

        <para>
            Значение <constant>NULL</constant> означает, что поиск производится по всем
            полям. Это значение настройки по умолчанию.
<!--
            <constant>NULL</constant> value means, that search is performed through all field. It's a default setting.
-->
        </para>
        <para>
            Вы можете указать поле, набирая имя поля с двоеточием ":" в конце
            и затем искомый элемент.
<!--
            You can specify field by typing the field name followed by a colon ":" and then the term you
            are looking for.
-->
        </para>
        <para>
            Для примера предположим, что индекс Lucene содержит два поля -
            'title' (заголовок) и 'text' (текст), 'text' является полем,
            используемым по умолчанию. Если вы хотите найти документ с
            заголовком "The Right Way", который содержит текст "don't go
            this way", то можете ввести:
<!--
            As an example, let's assume a Lucene index contains two fields, title and text and text is the default field.
            If you want to find the document entitled "The Right Way" which contains the text "don't go this way",
            you can enter:
-->
        </para>
        <programlisting language="querystring"><![CDATA[title:"The Right Way" AND text:go]]></programlisting>
        <para>
            или
        </para>
        <programlisting language="querystring"><![CDATA[title:"Do it right" AND go]]></programlisting>
        <para>
            Если 'text' является полем, используемым по умолчанию, то указание
            поля не требуется.
<!--
            If "text" is the default field, the field indicator is not required.
-->
        </para>

        <para>
            Важно: поле действительно только для того элемента, фразы или
            подзапроса, перед которым он непосредственно стоит. Таким образом,
            запрос
<!--
            Note: The field is only valid for the term, phrase or subquery that it directly precedes,
            so the query
-->
            <programlisting language="querystring"><![CDATA[title:Do it right]]></programlisting>
            будет искать в поле 'title' только "Do". Поиск "it" и "right" будет
            производиться в полях, используемых по умолчанию, если установлены
            поля по умолчанию, или по всем полям, если вместо поля по умолчанию
            установлено <constant>NULL</constant>.
<!--
            Will only find "Do" in the title field. It will find "it" and "right" in the default field,
            if default field is set, or in tha all indexed fields, if default field is set to <constant>NULL</constant>.
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.modifiers">
        <title>Модификаторы элементов<!--Term Modifiers--></title>

        <para>
            Lucene поддерживает модификацию элементов запроса для предоставления
            широкого диапазона опций поиска.
<!--
            Lucene supports modifying query terms to provide a wide range of searching options.
-->
        </para>
        <para>
            Zend_Search_Lucene сейчас поддерживает модификатор "~" только для
            фраз
<!--
            Zend_Search_Lucene supports "~" modifier only for phrases now
-->
            <footnote>
                <para>
                    "~" по отношению к элементам используется для нечеткого
                    поиска, но запросы для нечеткого поиска еще не
                    поддерживаются.
<!--
                    "~" for terms is used for fuzzy search, but fuzzy search queries are not supported yet.
-->
                </para>
            </footnote>.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.proximity-search">
        <title>Поиск по критерию близости<!--Proximity Searches--></title>

        <para>
            Lucene поддерживает поиск слов, находящихся в пределах определенного
            расстояния друг от друга. Для того, чтобы производить поиск по
            критерию близости, используйте тильду "~" в конце фразы. Например,
            для того, чтобы найти в документе "Zend" и "Framework" в пределах
            10 слов, используйте следующий запрос:
<!--
            Lucene supports finding words are a within a specific distance away. To do a proximity search
            use the tilde, "~", symbol at the end of a Phrase. For example to search for a "Zend" and
            "Framework" within 10 words of each other in a document use the search:
-->
            <programlisting language="querystring"><![CDATA["Zend Framework"~10]]></programlisting>
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.boosting">
        <title>Усиление элемента<!--Boosting a Term--></title>

        <para>
            Java Lucene и Zend_Search_Lucene предоставляют уровень релевантности
            соответствующих запросу документов, основыванный на количестве
            найденных элементов. Для того, чтобы усилить элемент, используйте
            знак вставки "^" с коэффициентом усиления после этого элемента. Чем
            больше коэффициент усиления, то тем более релевантным будет элемент.
<!--
            Java Lucene and Zend_Search_Lucene provide the relevance level of matching documents based
            on the terms found. To boost a term use the caret, "^", symbol with a boost factor (a number)
            at the end of the term you are searching. The higher the boost factor, the more relevant
            the term will be.
-->
        </para>
        <para>
            Усиление элементов позволяет управлять релевантностью документа.
            Например, если вы ищете
<!--
            Boosting allows you to control the relevance of a document by boosting its term. For example,
            if you are searching for
-->
            <programlisting language="querystring"><![CDATA[PHP framework]]></programlisting>
            и хотите, чтобы элемент 'PHP' был более релевантным, то усильте
            его, используя символ ^ с коэффициентом усиления после этого
            элемента:
<!--
            and you want the term "PHP" to be more relevant boost it using the ^ symbol along with the
            boost factor next to the term. You would type:
-->
            <programlisting language="querystring"><![CDATA[PHP^4 framework]]></programlisting>
            Это сделает более релевантными те документы, в которых встречается
            элемент 'PHP'. Вы можете также усиливать фразы и подзапросы, как в
            примере ниже:

<!--
            This will make documents with the term PHP appear more relevant. You can also boost Phrase
            Terms  and subqueries as in the example:
-->
            <programlisting language="querystring"><![CDATA["PHP framework"^4 "Zend Framework"]]></programlisting>
            По умолчанию коэффициент усиления равен 1. Несмотря на то, что
            коэффициент усиления должен быть положительным числом, он может быть
            меньше 1 (например, 0.2).
<!--
            By default, the boost factor is 1. Although the boost factor must be positive,
            it can be less than 1 (e.g. 0.2)
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.boolean">
        <title>Булевы операторы<!--Boolean Operators--></title>

        <para>
            Булевы операторы позволяют комбинировать элементы через логические
            операторы. Lucene поддерживает AND, "+", OR, NOT и "-" как булевы
            операторы. Java Lucene требует, чтобы все булевы операторы были в
            верхнем регистре, Zend_Search_Lucene этого не требует.
<!--
            Boolean operators allow terms to be combined through logic operators.
            Lucene supports AND, "+", OR, NOT and "-" as Boolean operators.
            Java Lucene needs boolean operators t obe ALL CAPS. Zend_Search_Lucene doesn't.
-->
        </para>

        <para>
            Операторы AND, OR, NOT и "+", "-" определяют два различных стиля
            построения запросов. В отличие от Java Lucene, Zend_Search_Lucene не
            позволяет смешивать оба стиля.
<!--
            AND, OR, and NOT operators and "+", "-" defines two styles to construct boolean queries.
            As opposed to Java Lucene Zend_Search_Lucene doesn't allow to mix these two styles.
-->
        </para>
        <para>
            Если используется стиль AND/OR/NOT, то операторы AND/OR должны
            находиться между всеми элементами запроса. Перед любым элементом
            может также находиться оператор NOT. Оператор AND имеет более
            высокий приоритет, чем OR. Этим Zend_Search_Lucene отличается от
            Java Lucene.
<!--
            If AND/OR/NOT style is used, then AND/OR operator must be present between all query terms.
            Each term may also be preceded by NOT operator. AND operator has higher precedence than OR.
            It differs from Java Lucene behavior.
-->
        </para>

        <sect3 id="zend.search.lucene.query-language.boolean.and">
            <title>AND</title>
            <para>
                Оператор AND означает, что документ должен соответствовать всем
                элементам в "группе AND".
<!--
                The AND operator means, that all terms in "AND group" must match document.
-->
            </para>
            <para>
                Для поиск документов, содержащих "PHP framework" м "Zend
                Framework" используется запрос:
<!--
                To search for documents that contain "PHP framework" and "Zend Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA["PHP framework" AND "Zend Framework"]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.or">
            <title>OR</title>
            <para>
                Оператор OR делит запрос на несколько необязательных частей.
<!--
                The OR operator devides query into several optional parts.
-->
            </para>
            <para>
                Для поиска документов, содержащих "PHP framework" или "Zend
                Framework" используется запрос:
<!--
                To search for documents that contain "PHP framework" or "Zend Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA["PHP framework" OR "Zend Framework"]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.not">
            <title>NOT</title>
            <para>
                Оператор NOT исключает документы, содержащие элемент после NOT.
                Но "группа AND", содержащая только элементы с оператором NOT,
                даст пустой результат вместо всего набора проиндексированных
                документов.
<!--
                The NOT operator excludes documents that contain the term after NOT. But "AND group", which contains
                only terms with NOT operator, gives empty result instead of full set indexed documents.
-->
            </para>
            <para>
                Для поиска документов, содержащих "PHP framework", но без "Zend
                Framework", используется запрос:
<!--
                To search for documents that contain "PHP framework" but not "Zend Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA["PHP framework" AND NOT "Zend Framework"]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.other-form">
            <title>Операторы &amp;&amp;, ||, и !<!--&amp;&amp;, ||, and ! operators--></title>
            <para>
                Операторы &amp;&amp;, ||, и ! могут использоваться вместо AND,
                OR и NOT.
<!--
                &amp;&amp;, ||, and ! may be used instead of AND, OR, and NOT operators.
-->
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.plus">
            <title>+</title>
            <para>
                "+" означает, что документ должен соответствовать элементу,
                находящемуся после "+".
<!--
                The "+" or required operator requires that the term after the "+" symbol must match the document.
-->
            </para>
            <para>
                Для поиска документов, которые должны содержать "Zend" и могут
                содержать "Framework", используется запрос:
<!--
                To search for documents that must contain "Zend" and may contain "Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA[+Zend Framework]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.minus">
            <title>-</title>
            <para>
                "-" исключает документы, соответствующие элементу находящемуся
                после него.
<!--
                The "-" or prohibit operator excludes documents that matches the term after the "-" symbol.
-->
            </para>
            <para>
                Для поиска документов, содержащих "PHP framework",
                но без "Zend Framework", используется запрос:
<!--
                To search for documents that contain "PHP framework" but not "Zend Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA["PHP framework" -"Zend Framework"]]></programlisting>
            </para>
        </sect3>

        <sect3 id="zend.search.lucene.query-language.boolean.no-operator">
            <title>Отсутствие оператора<!--no operator--></title>
            <para>
                Если не не указан оператор, то поведение определяется
                используемым по умолчанию булевым оператором.
<!--
                If no operator is used, then behavior is defined by "default boolean operator".
-->
            </para>

            <para>
                По умолчанию таким оператором является <code>OR</code>.
<!--
                It's <code>OR</code> by default.
-->
            </para>

            <para>
                Это означает, что данный элемент является необязательным. Он
                может как присутствовать, так и не присутствовать в документе,
                но документы с этим элементом имеют более высокий ранг.
<!--
                That means, that term is optional. It may be or may not be presented within document, but documents with this term
                will have higher score.
-->
            </para>

            <para>
                Для поиска документов, которые должны содержать "PHP framework"
                и могут содержать "Zend Framework", используется запрос:
<!--
                To search for documents that requires "PHP framework" and may contain "Zend Framework" use the query:
-->
                <programlisting language="querystring"><![CDATA[+"PHP framework" "Zend Framework"]]></programlisting>
            </para>

            <para>
                Используемые по умолчанию булевы операторы могут быть
                установлены или получены с помощью методов
                <code>Zend_Search_Lucene_Search_QueryParser::setDefaultOperator($operator)</code>
                и <code>Zend_Search_Lucene_Search_QueryParser::getDefaultOperator()</code>.
<!--
                Default boolean operator may be set or retrieved with
                <code>Zend_Search_Lucene_Search_QueryParser::setDefaultOperator($operator)</code> and
                <code>Zend_Search_Lucene_Search_QueryParser::getDefaultOperator()</code> methods.
-->
            </para>
            <para>
                Эти методы работают с константами <code>Zend_Search_Lucene_Search_QueryParser::B_AND</code> и <code>Zend_Search_Lucene_Search_QueryParser::B_OR</code>.
<!--
                These methods operate with
                <code>Zend_Search_Lucene_Search_QueryParser::B_AND</code> and
                <code>Zend_Search_Lucene_Search_QueryParser::B_OR</code> constants.
-->
            </para>

        </sect3>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.grouping">
        <title>Групирование<!--Grouping--></title>

        <para>
            Java Lucene и Zend_Search_Lucene поддерживают использование
            скобок для группирования условий в подзапросы. Это может быть
            полезным, если вы хотите контролировать булеву логику для запросов
            или смешивать различные стили запросов:
<!--
            Java Lucene and Zend_Search_Lucene support using parentheses to group clauses to form sub queries. This can be
            useful if you want to control the boolean logic for a query or mix different boolean query styles:
-->
            <programlisting language="querystring"><![CDATA[+(framework OR library) +php]]></programlisting>
            Zend_Search_Lucene поддердивает подзапросы на любой уровни
            вложенности.
<!--
            Zend_Search_Lucene supports subqueries of any level.
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.field-grouping">
        <title>Группирование полей<!--Field Grouping--></title>

        <para>
            Lucene поддерживает использование скобок для группирования
            нескольких условий применительно к одному полю.
<!--
            Lucene supports using parentheses to group multiple clauses to a single field.
-->
        </para>
        <para>
            Для поиска заголовка, содержащего слово "return" и фразу "pink
            panther" используйте запрос:
<!--
            To search for a title that contains both the word "return" and the phrase "pink panther" use the query:
-->
            <programlisting language="querystring"><![CDATA[title:(+return +"pink panther")]]></programlisting>
            Zend_Search_Lucene поддердивает подзапросы любого уровня
            вложенности.
<!--
            Zend_Search_Lucene supports subqueries of any level.
-->
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.query-language.escaping">
        <title>Экранирование специальных символов<!--Escaping Special Characters--></title>

        <para>
            Lucene поддерживает экранирование тех специальных символов, которые
            являются частью синтаксиса запросов. Список специальных символов:
<!--
            Lucene supports escaping special characters that are part of the query syntax. The current list special
            characters are:
-->
        </para>
        <para>
            + - &amp;&amp; || ! ( ) { } [ ] ^ " ~ * ? : \
        </para>
        <para>
            + и - внутри элемента обрабатываются как обычные символы.
<!--
            + and - inside single terms are treated as common characters.
-->
        </para>
        <para>
            Для того, чтобы экранировать эти символы, используйте \ перед
            символом. Например, для поиска (1+1):2 используйте запрос:
<!--
            To escape these character use the \ before the character. For example to search for (1+1):2 use the query:
-->
            <programlisting language="querystring"><![CDATA[\(1\+1\)\:2]]></programlisting>
        </para>
    </sect2>

</sect1>