[GENERIC] Zend_Translate:
[zend.git] / documentation / manual / en / tutorials / lucene-intro.xml
blob75687fd7092850c71bb2e6fb0e21c1a13ef74806
1 <?xml version="1.0" encoding="UTF-8"?>
2 <!-- Reviewed: no -->
3 <sect1 id="learning.lucene.intro">
4     <title>Zend_Search_Lucene Introduction</title>
6     <para>
7         The <classname>Zend_Search_Lucene</classname> component is intended to provide a
8         ready-for-use full-text search solution. It doesn't require any <acronym>PHP</acronym>
9         extensions<footnote><para>Though some <acronym>UTF-8</acronym> processing functionality
10                 requires the <emphasis>mbstring</emphasis> extension to be turned
11                 on</para></footnote> or additional software to be installed, and can be used
12         immediately after Zend Framework installation.
13     </para>
15     <para>
16         <classname>Zend_Search_Lucene</classname> is a pure <acronym>PHP</acronym> port of the
17         popular open source full-text search engine known as Apache Lucene. See <ulink
18             url="http://lucene.apache.org">http://lucene.apache.org/</ulink> for the details.
19     </para>
21     <para>
22         Information must be indexed to be available for searching.
23         <classname>Zend_Search_Lucene</classname> and Java Lucene use a document concept known as an
24         "atomic indexing item."
25     </para>
27     <para>
28         Each document is a set of fields: &lt;name, value&gt; pairs where name and value are
29         <acronym>UTF-8</acronym> strings<footnote><para>Binary strings are also allowed to be used
30                 as field values</para></footnote>. Any subset of the document fields may be marked
31         as "indexed" to include field data in the text indexing process.
32     </para>
34     <para>
35         Field values may or may not be tokenized while indexing. If a field is not tokenized, then
36         the field value is stored as one term; otherwise, the current analyzer is used for
37         tokenization.
38     </para>
40     <para>
41         Several analyzers are provided within the <classname>Zend_Search_Lucene</classname> package.
42         The default analyzer works with <acronym>ASCII</acronym> text (since the
43         <acronym>UTF-8</acronym> analyzer needs the <emphasis>mbstring</emphasis> extension to be
44         turned on). It is case insensitive, and it skips numbers. Use other analyzers or create your
45         own analyzer if you need to change this behavior.
46     </para>
48     <note>
49         <title>Using analyzers during indexing and searching</title>
51         <para>
52             Important note! Search queries are also tokenized using the "current analyzer", so the
53             same analyzer must be set as the default during both the indexing and searching process.
54             This will guarantee that source and searched text will be transformed into terms in the
55             same way.
56         </para>
57     </note>
59     <para>
60         Field values are optionally stored within an index. This allows the original field data to
61         be retrieved from the index while searching. This is the only way to associate search
62         results with the original data (internal document IDs may be changed after index
63         optimization or auto-optimization).
64     </para>
66     <para>
67         The thing that should be remembered is that a Lucene index is not a database. It doesn't
68         provide index backup mechanisms except backup of the file system directory. It doesn't
69         provide transactional mechanisms though concurrent index update as well as concurrent update
70         and read are supported. It doesn't compare with databases in data retrieving speed.
71     </para>
73     <para>
74         So it's good idea:
75     </para>
77     <itemizedlist>
78         <listitem>
79             <para>
80                 <emphasis>Not</emphasis> to use Lucene index as a storage since it may dramatically
81                 decrease search hit retrieving performance. Store only unique document identifiers
82                 (doc paths, <acronym>URL</acronym>s, database unique IDs) and associated data within
83                 an index. E.g. title, annotation, category, language info, avatar. (Note: a field
84                 may be included in indexing, but not stored, or stored, but not indexed).
85             </para>
86         </listitem>
88         <listitem>
89             <para>
90                 To write functionality that can rebuild an index completely if it's corrupted for
91                 any reason.
92             </para>
93         </listitem>
94     </itemizedlist>
96     <para>
97         Individual documents in the index may have completely different sets of fields. The same
98         fields in different documents don't need to have the same attributes. E.g. a field may be
99         indexed for one document and skipped from indexing for another. The same applies for
100         storing, tokenizing, or treating field value as a binary string.
101     </para>
102 </sect1>