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

<sect1 id="zend.search.lucene.overview">
    <title>Обзор</title>

    <sect2 id="zend.search.lucene.introduction">
        <title>Введение</title>
        <para>
            Zend_Search_Lucene является поисковым движком общего
            назначения для полнотекстового поиска, написанным полностью на PHP 5.
            Так как он хранит индекс в файловой системе и не требует наличия
            сервера баз данных, то дает
            возможность реализовать поиск практически для всех веб-сайтов, работающих
            под управлением PHP. Zend_Search_Lucene поддерживает следующие
            возможности:
<!--
            Zend_Search_Lucene is a general purpose text search engine written entirely in PHP 5.
            Since it stores its index on the filesystem and does not require a database
            server, it can add search capabilities to almost any PHP-driven website.
            Zend_Search_Lucene supports the following features:
-->
            <itemizedlist>
                <listitem>
                    <para>
                        Ранжированный поиск — более подходящие результаты возвращаются первыми
<!--
                        Ranked searching - best results returned first
-->
                    </para>
                </listitem>
                <listitem>
                    <para>
                       Множество типов запросов: поиск фраз, поиск с шаблонами,
                       поиск по критерию близости, поиск по диапазону значений
                       и т.д.
<!--
                       Many powerful query types: phrase queries, wildcard queries,
                       proximity queries, range queries and more
-->
                        <footnote>
                           <para>
                             Сейчас поддерживается поиск по одному и нескольким
                             элементам, фразам, булевы операторы и подзапросы.
<!--
                             Term, multi term, phrase queries, boolean expressions and subqueries are supported at this time.
-->
                           </para>
                        </footnote>
                    </para>
                </listitem>
                <listitem>
                    <para>
                        Поиск по определенному полю (например: заголовок, автор,
                        содержимое)
<!--
                        Search by specific field (e.g., title, author, contents)
-->
                    </para>
                </listitem>
            </itemizedlist>
            Zend_Search_Lucene произошел от проекта Apache Lucene.
            За более подробной информацией см.
<!--
            Zend_Search_Lucene was derived from the Apache Lucene project.  For more
            information on Lucene, visit
-->
            <ulink url="http://lucene.apache.org/java/docs/"/>.
        </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.documents-and-fields">
        <title>Объекты документа и поля<!--Document and Field Objects--></title>
            <para>
                Zend_Search_Lucene оперирует с документами как с элементарными
                объектами для индексации. Документ делится на именованные поля,
                содержащие контент, по которому может производиться поиск.
<!--
                Zend_Search_Lucene operates with documents as atomic subjects for indexing.  A document is
                divided into named fields, and fields have content that can be searched.
-->
            </para>

            <para>
                Документ представлен объектом Zend_Search_Lucene_Document,
                этот объект содержит объекты Zend_Search_Lucene_Field,
                представляющие собой поля документа.
<!--
                A document is represented by the Zend_Search_Lucene_Document object, and this object contains
                Zend_Search_Lucene_Field objects that represent the fields.
-->
            </para>

            <para>
                Важно отметить, что в индекс может быть добавлена любая информация.
                Данные вашего приложения или метаданные могут сохраняться в
                полях документа и после извлекаться вместе с документом в процессе
                поиска.
<!--
                It is important to note that any kind of information can be added to the index.
                Application-specific information or metadata can be stored in the document
                fields, and later retrieved with the document during search.
-->
            </para>

            <para>
                Приложение отвественно за процесс индексации.
                Как следствие, проиндексированы могут быть данные из любых
                источников, доступных приложению. Например, это
                могут быть файловая система, база данных, форма HTML и т.д.
<!--
                It is the responsibility of your application to control the indexer.
                This means that data can be indexed from any source
                that is accessible by your application.  For example, this could be the
                filesystem, a database, an HTML form, etc.
-->
            </para>

            <para>
                Класс <code>Zend_Search_Lucene_Field</code> предоставляет
                несколько статических методов для создания полей с различными
                характеристиками.
<!--
                <code>Zend_Search_Lucene_Field</code> class provides several
                static methods to create fields with
                different characteristics:
-->
            </para>

            <programlisting language="php"><![CDATA[<?php
$doc = new Zend_Search_Lucene_Document();

// Данные поля не разбиваются на лексемы,
// но индексируются и полностью сохраняются в индексе.
// Сохраненные данные поля могут быть получены из индекса.
$doc->addField(Zend_Search_Lucene_Field::Keyword('doctype',
                                                 'autogenerated'));

// Данные поля не разбиваются на лексемы и не индексируются,
// но полностью сохраняются в индексе.
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                   time()));

// Бинарное поле, данные которого не разбиваются на лексемы и не индексируются,
// но сохраняются в индексе.
$doc->addField(Zend_Search_Lucene_Field::Binary('icon',
                                                $iconData));

// Данные поля разбиваются на лексемы, индексируются
// и полностью сохраняются в индексе.
$doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                              'Document annotation text'));

// Данные поля разбиваются на лексемы и индексируются,
// но не сохраняются в индексе.
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents',
                                                  'My document content'));

?>]]></programlisting>

            <para>
                Каждый из этх методов (исключая метод <code>Zend_Search_Lucene_Field::Binary()</code>)
                имеет необязательный параметр <varname>$encoding</varname>. Через него
                указывается кодировка для входных данных.
<!--
                Each of these methods (excluding <code>Zend_Search_Lucene_Field::Binary()</code> method) has optional
                <varname>$encoding</varname> parаmeter. It specifies input data encoding.
-->
            </para>

            <para>
                Кодировка может различаться как для документов, так и для
                полей в одном документе.
<!--
                Encoding may differ for different documents as well as for different fields within one document:
-->

                <programlisting language="php"><![CDATA[<?php
$doc = new Zend_Search_Lucene_Document();
$doc->addField(Zend_Search_Lucene_Field::Text('title', $title, 'iso-8859-1'));
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $contents, 'utf-8'));
?>]]></programlisting>
            </para>

            <para>
                Если этот параметр опущен, то используется текущая локаль.
                Например:
<!--
                If encoding parameter is omitted, then current locale is used at processing time. For example:
-->
                <programlisting language="php"><![CDATA[<?php
setlocale(LC_ALL, 'de_DE.iso-8859-1');
...
$doc->addField(Zend_Search_Lucene_Field::UnStored('contents', $contents));
?>]]></programlisting>
            </para>

            <para>
                Поля всегда сохраняются и возвращаются из индекса в кодировке
                UTF-8. Преобразование в UTF-8 производится автоматически.
<!--
                Fields are always stored and returned from index in UTF-8 encoding. Conversion to UTF-8 proceeds
                automatically.
-->
            </para>

            <para>
                Анализатор текста (<link linkend="zend.search.lucene.extending.analysis">см. далее</link>)
                может также преобразовывать текст в другие кодировки. В
                настоящее время используемый по умолчанию анализатор преобразует
                текст в кодировку 'ASCII//TRANSLIT'. Имейте в виду, что такое
                преобразование может зависеть от текущей локали.
<!--
                Text analyzers (<link linkend="zend.search.lucene.extending.analysis">see below</link>) may also convert text
                to some other encodings. Actually, default analyzer converts text to 'ASCII//TRANSLIT' encoding.
                Be care with this, such translation may depend on current locale.
-->
            </para>

            <para>
                Имена полей могут быть любыми.
<!--
                Fields' names are defined only by your own choice.
-->
            </para>

            <para>
                Java Lucene по умолчанию использует для поиска поле "contents".
                Zend_Search_Lucene по умолчанию производит поиск по всем полям,
                но это поведение можно изменить. За подробностями см.
                <link linkend="zend.search.lucene.query-language.fields">Поля для поиска</link>.
<!--
                Java Lucene uses "contents" field as a default field to search.
                Zend_Search_Lucene searches through all fiels by default, but it's also possible to change this behavior.
                See <link linkend="zend.search.lucene.query-language.fields">"Default search field"</link> chapter for details.
-->
            </para>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.understanding-field-types">
        <title>Значение типов полей<!--Understanding Field Types--></title>
        <itemizedlist>
            <listitem>
                <para>
                    Поля <code>Keyword</code> полностью сохраняются и индексируются,
                    это означает, что можно не только производить поиск в них,
                    но и отображать их в результатах поиска.
                    Они не делятся на отдельные слова посредством разбиения
                    на лексемы. Нумерованные поля БД обычно преобразуются в поля Keyword
                    в Zend_Search_Lucene.
<!--
                    <code>Keyword</code> fields are stored and indexed, meaning that they can be searched as well
                    as displayed in search results. They are not split up into separate words by tokenization.
                    Enumerated database fields usually translate well to Keyword fields in Zend_Search_Lucene.
-->
                </para>
            </listitem>
            <listitem>
                <para>
                    В полях <code>UnIndexed</code> нельзя производить поиск,
                    но они возвращаются в результатах поиска. Поля timestamp,
                    ключевые поля, пути в файловой системе и другие
                    внешние идентификаторы — хорошие кандидаты для того, чтобы
                    быть полями UnIndexed.
<!--
                    <code>UnIndexed</code> fields are not searchable, but they are returned with search hits.  Database
                    timestamps, primary keys, file system paths, and other external identifiers are good
                    candidates for UnIndexed fields.
-->
                </para>
            </listitem>
            <listitem>
                <para>
                    Поля <code>Binary</code> не разбиваются на лексемы и не индексируются,
                    но сохраняются для возвращения в результатах поиска.
                    Они могут использоваться для хранения любых данных,
                    закодированных в виде бинарной строки — как, например,
                    иконки.
<!--
                    <code>Binary</code> fields are not tokenized or indexed, but are stored for retrieval with search hits.
                    They can be used to store any data encoded as a binary string, such as an image icon.
-->
                </para>
            </listitem>
            <listitem>
                <para>
                    Поля <code>Text</code> сохраняются, разбиваются на лексемы
                    и индексируются. Текстовые поля подходят для хранения
                    такой информации, как темы и заголовки — в них нужно не
                    только искать, но и возвращать с результатами поиска.
<!--
                    <code>Text</code> fields are stored, indexed, and tokenized.
                    Text fields are appropriate for storing
                    information like subjects and titles that need to be searchable
                    as well as returned with search results.
-->
                </para>
            </listitem>
            <listitem>
                <para>
                    Поля <code>UnStored</code> разбиваются на лексемы и индексируются, но
                    не сохраняются в индексе. Тексты большого объема лучше
                    индексировать, используя этот тип поля.
                    Хранение таких данных создает индекс, который занимает много места
                    на диске, поэтому если нужно искать в данных, но не выводить их, то
                    используйте поле UnStored. Поля UnStored полезны,
                    когда используется индекс Zend_Search_Lucene в
                    комбинации с реляционной БД. Вы можете индексировать большие
                    поля данных для поиска с помощью UnStored и извлекать их
                    из реляционной БД, используя отдельные поля как
                    идентификаторы.
<!--
                    <code>UnStored</code> fields are tokenized and indexed, but not stored in the index. Large amounts of
                    text are best indexed using this type of field. Storing data creates a larger index on
                    disk, so if you need to search but not redisplay the data, use an UnStored field.
                    UnStored fields are practical when using a Zend_Search_Lucene index in
                    combination with a relational database. You can index large data fields with UnStored
                    fields for searching, and retrieve them from your relational database by using a separate
                    fields as an identifier.
-->
               </para>

                <table>
                    <title>Типы Zend_Search_Lucene_Field<!--Zend_Search_Lucene_Field Types--></title>
                    <tgroup cols="5">
                        <thead>
                            <row>
                                <entry>Тип поля</entry>
                                <entry>Сохраняется</entry>
                                <entry>Индексируется</entry>
                                <entry>Разбивается на лексемы</entry>
                                <entry>Бинарное</entry>
                            </row>
                        </thead>
                        <tbody>
                            <row>
                                <entry>Keyword</entry>
                                <entry>Да</entry>
                                <entry>Да</entry>
                                <entry>Нет</entry>
                                <entry>Нет</entry>
                            </row>
                            <row>
                                <entry>UnIndexed</entry>
                                <entry>Да</entry>
                                <entry>Нет</entry>
                                <entry>Нет</entry>
                                <entry>Нет</entry>
                            </row>
                            <row>
                                <entry>Binary</entry>
                                <entry>Да</entry>
                                <entry>Нет</entry>
                                <entry>Нет</entry>
                                <entry>Да</entry>
                            </row>
                            <row>
                                <entry>Text</entry>
                                <entry>Да</entry>
                                <entry>Да</entry>
                                <entry>Да</entry>
                                <entry>Нет</entry>
                            </row>
                            <row>
                                <entry>UnStored</entry>
                                <entry>Нет</entry>
                                <entry>Да</entry>
                                <entry>Да</entry>
                                <entry>Нет</entry>
                            </row>
                        </tbody>
                    </tgroup>
                </table>
           </listitem>
       </itemizedlist>
    </sect2>

    <sect2 id="zend.search.lucene.index-creation.html-documents">
        <title>HTML-документы<!--HTML documents--></title>
        <para>
            Zend_Search_Lucene предоставляет возможность парсинга HTML.
            Документы могут создаваться непосредственно из HTML-файла или
            строки.
<!--
            Zend_Search_Lucene offers HTML parsing feature. Documents can be
            created directly from HTML file or string:
-->
            <programlisting language="php"><![CDATA[<?php
$doc = Zend_Search_Lucene_Document_Html::loadHTMLFile($filename);
$index->addDocument($doc);
...
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$index->addDocument($doc);
?>]]></programlisting>
        </para>

        <para>
            Класс <code>Zend_Search_Lucene_Document_Html</code> использует
            методы <code>DOMDocument::loadHTML()</code> и
            <code>DOMDocument::loadHTMLFile()</code> для парсинга исходного
            HTML-кода, поэтому HTML не обязательно должен быть правильно
            сформированным или быть XHTML. С другой стороны, он чувствителен к
            кодировке, указанной в теге "meta http-equiv" заголовка.
<!--
            <code>Zend_Search_Lucene_Document_Html</code> class uses
            <code>DOMDocument::loadHTML()</code> and
            <code>DOMDocument::loadHTMLFile()</code> methods to parse source
            HTML, so it doesn't need HTML to be well formed or
            to be XHTML. From the other side it's sensitive to encoding
            mentioned in "meta http-equiv" header tag.
-->
        </para>

        <para>
            Класс <code>Zend_Search_Lucene_Document_Html</code> распознает
            заголовок, тело документа и его мета-теги.
<!--
            <code>Zend_Search_Lucene_Document_Html</code> class recognizes
            document title, body and document header meta tags.
-->
        </para>

        <para>
            Поле 'title' будет содержать значение из /html/head/title. Оно
            сохраняется в индексе, разбивается на лексемы и его содержимое
            доступно для поиска.
<!--
            'title' field is actually /html/head/title value. It's stored
            within index, tokenized and available for search through.
-->
        </para>

        <para>
            Поле 'body' будет содержать тело документа. Оно не включает в себя
            скрипты, комментарии и атрибуты тегов.
<!--
            'body' field is actually body content. It doesn't include scripts,
            comments and tags' attributes.
-->
        </para>

        <para>
            Методы <code>loadHTML()</code> и <code>loadHTMLFile()</code> класса
            <code>Zend_Search_Lucene_Document_Html</code> также имеют второй
            необязательный аргумент. Если он установлен в true, то содержимое
            тела документа сохраняется в индексе и может быть получено из
            индекса. По умолчанию тело документа разбивается на лексемы и
            индексируется, но не сохраняется в индексе.
<!--
            <code>loadHTML()</code> and <code>loadHTMLFile()</code> methods of
            <code>Zend_Search_Lucene_Document_Html</code> class
            also have second optional argument. If it's set to true, then body
            content is also stored within index and can
            be retrieved from index. Body is only tokenized and indexed, but
            not stored by default.
-->
        </para>

        <para>
            К мета-тегам заголовка документа создаются дополнительные поля. При
            этом имя поля берется из атрибута 'name', содержимое поля - из
            атрибута 'content', это содержимое разбивается на лексемы,
            индексируется и сохраняется в индексе, и, таким образом, документы
            можно будет искать по их мета-тегам - например, по ключевым словам
            (keywords).
<!--
            Document header meta tags produce additional document fields.
            Field name is taken from 'name' attribute,
            'content' attribute gives field value, which is tokenized, indexed
            and stored, so documents may be searched by their meta tags
            (for example, by keywords).
-->
        </para>

        <para>
            К сгенерированным документам можно добавлять любые другие поля.
<!--
            Parsed documents may be extended by user with any other field:
-->
            <programlisting language="php"><![CDATA[<?php
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                   time()));
$doc->addField(Zend_Search_Lucene_Field::UnIndexed('created',
                                                   time()));
$doc->addField(Zend_Search_Lucene_Field::Text('annotation',
                                              'Document annotation text'));
$index->addDocument($doc);
?>]]></programlisting>
        </para>

        <para>
            Линки из исходного документа не добавляются в генерируемый документ,
            но могут быть получены через методы
            <code>Zend_Search_Lucene_Document_Html::getLinks()</code> и
            <code>Zend_Search_Lucene_Document_Html::getHeaderLinks()</code>:
<!--
            Document links are not included into generated document, but may be
            retrieved with
            <code>Zend_Search_Lucene_Document_Html::getLinks()</code> and
            <code>Zend_Search_Lucene_Document_Html::getHeaderLinks()</code>
            methods:
-->
            <programlisting language="php"><![CDATA[<?php
$doc = Zend_Search_Lucene_Document_Html::loadHTML($htmlString);
$linksArray = $doc->getLinks();
$headerLinksArray = $doc->getHeaderLinks();
?>]]></programlisting>
        </para>
    </sect2>

</sect1>