12.4. Query Types
Prev | Chapter 12. Zend_Search | Next

## 12.4. Query Types

### 12.4.1. Term Query

Term queries are intended for a searching for a single term.

Both of a search method can be used for term queries.

Query string:

        $hits = $index->find('word1');

or

Query construction by API:

    <?php

        $term  = new Zend_Search_Lucene_Index_Term('word1');
        $query = new Zend_Search_Lucene_Search_Query_Term($term);
        $hits  = $index->find($query);

    ?>

### 12.4.2. Multi-Term Query

Multi term queries are intended for a searching for a set of terms.

Each term in a set can be defined as required, prohibited or neither required, nor prohibited (optional).

- required which means that documents which do not match this term will not match the query;

- prohibited which means that documents which do match this term will not match the query;

- neither, in which case matched documents are neither prohibited from nor required to match the term. However, a document must match at least 1 term to match the query.

It means, that if optional terms are added to a query with required terms, then they will have the same result set, but second query will have hits, which match optional terms, moved to the top of result set.

Both of a search method can be used for multi term queries.

Query string:

    <?php

    $hits = $index->find('+word1 author:word2 -word3');

    ?>

- '+' is used to define required term.
- '-' is used to define prohibited term.
- 'field:' prefix is used to indicate document field for a search. If it's omitted, then 'contents' is used.

or

Query construction by API:

    <?php

        $query = new Zend_Search_Lucene_Search_Query_MultiTerm();

        $query->addTerm(new Zend_Search_Lucene_Index_Term('word1'), true);
        $query->addTerm(new Zend_Search_Lucene_Index_Term('word2'), null);
        $query->addTerm(new Zend_Search_Lucene_Index_Term('word3'), false);

        $hits  = $index->find($query);

    ?>

`$signs` array contains an information about term type:

- true is used to define required term.
- false is used to define prohibited term.
- null is used to define neither required, nor prohibited term.

### 12.4.3. Phrase Query

Phrase Queries are intended for a searching for a phrases.

Phrase Queries are very flexible and allow to search exact phrases as well as sloppy phrases. Exact phrases can also contain gaps or terms in the same places. (It can be generated by Analyser for different purposes. Ex. term can be duplicated to increase term weight or several synonyms can be placed into one position). According to this phrase queries can be constructed only by API now:

    <?php
    $query1 = new Zend_Search_Lucene_Search_Query_Phrase();

    // Add 'word1' at 0 relative position.
    $query1->addTerm(new Zend_Search_Lucene_Index_Term('word1'));

    // Add 'word2' at 1 relative position.
    $query1->addTerm(new Zend_Search_Lucene_Index_Term('word2'));

    // Add 'word3' at 3 relative position.
    $query1->addTerm(new Zend_Search_Lucene_Index_Term('word3'), 3);

    ...

    $query2 = new Zend_Search_Lucene_Search_Query_Phrase(
                    array('word1', 'word2', 'word3'), array(0,1,3));

    ...

    // Query without a gap.
    $query3 = new Zend_Search_Lucene_Search_Query_Phrase(
                    array('word1', 'word2', 'word3'));

    ...

    $query4 = new Zend_Search_Lucene_Search_Query_Phrase(
                    array('word1', 'word2'), array(0,1), 'annotation');

    ?>

Phrase query can be constructed by one step with a class constructor or step by step with a `Zend_Search_Lucene_Search_Query_Phrase::addTerm()` method.

Zend_Search_Lucene_Search_Query_Phrase class constructor takes three optional arguments:

    Zend_Search_Lucene_Search_Query_Phrase([array $terms[, array $offsets[, string $field]]]);

`$terms` is an array of strings, which contains a set of phrase terms. If it's omitted or equal to null, then empty query is constructed.

`$offsets` is an array of integers, which contains offsets of terms in a phrase. If it's omitted or equal to null, then terms positions are supposed as `array(0, 1, 2, 3, ...)`.

`$field` is a string, which indicates searched document field. If it's omitted or equal to null, then default field is searched. This version of Zend_Search_Lucene treates 'contents' field as a default, but it's planned to change this behavior to "any field" in next versions.

Thus:

    $query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'));

will search for 'zend framework' phrase.

    <$query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'download'), array(0, 2));

will search for 'zend ????? download' phrase and match 'zend platform download', 'zend studio download', 'zend core download', 'zend framework download' and so on.

    $query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'), null, 'title');

will search for 'zend framework' phrase in a 'title' field.

`Zend_Search_Lucene_Search_Query_Phrase::addTerm()` method takes two arguments. Required `Zend_Search_Lucene_Index_Term` object and optional position:

    Zend_Search_Lucene_Search_Query_Phrase::addTerm(Zend_Search_Lucene_Index_Term $term[, integer $position]);

`$term` describes next term in a phrase. It must indicate the same field as previous terms. Otherwise an exception will be thrown.

`$position` indicates term position.

Thus:

    $query = new Zend_Search_Lucene_Search_Query_Phrase();
    $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'));
    $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'));

will search for 'zend framework' phrase.

    $query = new Zend_Search_Lucene_Search_Query_Phrase();
    $query->addTerm(new Zend_Search_Lucene_Index_Term('zend'), 0);
    $query->addTerm(new Zend_Search_Lucene_Index_Term('framework'), 2);

will search for 'zend ????? download' phrase and match 'zend platform download', 'zend studio download', 'zend core download', 'zend framework download' and so on.

    $query = new Zend_Search_Lucene_Search_Query_Phrase();
    $query->addTerm(new Zend_Search_Lucene_Index_Term('zend', 'title'));
    $query->addTerm(new Zend_Search_Lucene_Index_Term('framework', 'title'));

will search for 'zend framework' phrase in a 'title' field.

Sloop factor sets the number of other words permitted between words in query phrase. If zero, then this is an exact phrase search. For larger values this works like a WITHIN or NEAR operator.

The slop is in fact an edit-distance, where the units correspond to moves of terms in the query phrase out of position. For example, to switch the order of two words requires two moves (the first move places the words atop one another), so to permit re-orderings of phrases, the slop must be at least two.

More exact matches are scored higher than sloppier matches, thus search results are sorted by exactness. The slop is zero by default, requiring exact matches.

Sloop factor can be assigned after query creation:

    <?php

    // Query without a gap.
    $query = new Zend_Search_Lucene_Search_Query_Phrase(array('word1', 'word2'));

    // Search for 'word1 word2', 'word1 ... word2'
    $query->setSlop(1);
    $hits1 = $index->find($query);

    // Search for 'word1 word2', 'word1 ... word2',
    // 'word1 ... ... word2', 'word2 word1'
    $query->setSlop(2);
    $hits2 = $index->find($query);

    ?>

Prev | Up | Next
12.3. Searching an Index | Home | 12.5. Character set.