repo_zf1/documentation/manual/pt-br/module_specs/Zend_Search_Lucene-Queries.xml

<sect1 id="zend.search.lucene.queries">
  <title>Tipos de Consulta</title>

  <sect2 id="zend.search.lucene.queries.term-query">
    <title>Consulta a termo simples</title>

    <para>São indicadas para pesquisa de termos isolados.</para>

    <para>Ambos os métodos de pesquisa podem ser usados para consultas de
    termo simples.</para>

    <para>String de busca: <programlisting role="php">
    $hits = $index-&gt;find('word1');
        </programlisting></para>

    <para>ou</para>

    <para>Construção da pesquisa via API: <programlisting role="php">&lt;?php

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

?&gt;</programlisting></para>
  </sect2>

  <sect2 id="zend.search.lucene.queries.multiterm-query">
    <title>Consulta a múltiplos termos</title>

    <para>São indicadas para pesquisas em um conjunto de termos.</para>

    <para>Para cada termo pesquisado, podemos especificar o comportamento da
    busca. <itemizedlist>
        <listitem>
          <para>Termos necessários - Exibe apenas os documentos que contém o
          termo;</para>
        </listitem>

        <listitem>
          <para>Termos proibidos - Exibe os documentos que não contém o
          termo;</para>
        </listitem>

        <listitem>
          <para>Termos "neither" - Exibe os documentos contenham os termos
          necessários mas não contenham os proibidos. De qualquer forma, o
          documento pesquisado deve conter pelo menos um termo que coincida
          com a string de busca.</para>
        </listitem>
      </itemizedlist></para>

    <para>Isso implica que, se termos opcionais forem acrescentados à consulta
    com termos obrigatórios, eles irão produzir um mesmo conjuntoi de
    resultados, mas a segunda consulta irá acrescentar uma pontuação de acerto
    ("hits") para cada termo opcional, movendo-os para o topo do
    resultado.</para>

    <para>Ambos os métodos de busca podem ser usados para consultas a termos
    múltiplos.</para>

    <para>String de busca: <programlisting role="php">&lt;?php

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

?&gt;</programlisting> <itemizedlist>
        <listitem>
            <para>
                '+' especifica um termo obrigatório.
            </para>
        </listitem>

        <listitem>
            <para>
                '-' especifica um termo rejeitado.
            </para>
        </listitem>

        <listitem>
            <para>
                'campo:' especifica um campo específico para busca. Se for omitido a pesquisa utilizará o campo de conteúdo.
            </para>
        </listitem>
      </itemizedlist></para>

    <para>or</para>

    <para>Construção da pesquisa via API: <programlisting role="php">&lt;?php

    $query = new Zend_Search_Lucene_Search_Query_MultiTerm();

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

    $hits  = $index-&gt;find($query);

?&gt;</programlisting></para>

    <para>O array <code>$signs</code> pode conter informações sobre o tipo de
    termo pesquisado: <itemizedlist>
        <listitem>
            <para>
                true define um termo como necessário.
            </para>
        </listitem>

        <listitem>
            <para>
                false define um termo como proibido.
            </para>
        </listitem>

        <listitem>
            <para>
                 null define to define neither required, nor prohibited term.
            </para>
        </listitem>
      </itemizedlist></para>
  </sect2>

  <sect2 id="zend.search.lucene.queries.phrase-query">
    <title>Consulta por Frase</title>

    <para>São indicadas para pequisas em frases.</para>

    <para>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:</para>

    <para>Consultas por frase são muito flexíveis e permitem tanto a busca
    pela frase exata quanto a por fragmentos da frase. </para>

    <programlisting role="php">&lt;?php
$query1 = new Zend_Search_Lucene_Search_Query_Phrase();

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

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

// Add 'word3' at 3 relative position.
$query1-&gt;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');

?&gt;</programlisting>

    <para>A pesquisa por frase pode ser construida de uma única vez com um
    construtor de classe ou passo a passo com o método
    <code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code>.</para>

    <para>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</para>

    <para>O construtor da classe Zend_Search_Lucene_Search_Query_Phrase aceita
    três argumentos opcionais: <programlisting role="php">Zend_Search_Lucene_Search_Query_Phrase([array $terms[, array $offsets[, string $field]]]);</programlisting></para>

    <para><code>$terms</code> é um array de strings, contendo um conjunto de
    termos de frase. Se omitido ou igualado a um valor nulo, resulta na
    construção de um objeto consulta vazio.</para>

    <para><code>$offsets</code> é um array de inteiros, contendo deslocamentos
    de termos em uma frase. Se omitido ou igualado a um valor nulo fará com
    que as posições dos termos no array fiquem na forma <code>array(0, 1, 2,
    3, ...)</code>.</para>

    <para><code>$field</code> é uma string, que indica o campo do documento
    que será pesquisado. Se for omitido ou igualado a um valor nulo,
    restringirá a pesquisa ao campo "default". Esta versão do
    Zend_Search_Lucene trata os campos 'contents' como defaults, mas
    planejamos alterar este comportamento em versões futuras para considerar
    qualquer campo.</para>

    <para>Dess modo: <programlisting role="php">$query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'));</programlisting>
    irá pesquisar pela frase "zend framework". <programlisting role="php">&lt;$query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'download'), array(0, 2));</programlisting>
    irá pesquisar pela frase 'zend ????? download' e retornar 'zend platform
    download', 'zend studio download', 'zend core download', 'zend framework
    download' e por aí vai. <programlisting role="php">$query = new Zend_Search_Lucene_Search_Query_Phrase(array('zend', 'framework'), null, 'title');</programlisting>
    irá pesquisar pela frase 'zend framework' em um campo 'title'.</para>

    <para><code>Zend_Search_Lucene_Search_Query_Phrase::addTerm()</code>
    possui dois argumentos. O objeto
    <code>Zend_Search_Lucene_Index_Term</code> é requerido mas a posição é
    opcional: <programlisting role="php">Zend_Search_Lucene_Search_Query_Phrase::addTerm(Zend_Search_Lucene_Index_Term $term[, integer $position]);</programlisting></para>

    <para><code>$term</code> descreve o próximo termo na frase. Ele deve
    indicar o mesmo campo que os termos anteriores, senão, uma irá disparar
    uma exceção.</para>

    <para><code>$position</code> indica a posição do termo.</para>

    <para>Desse modo: <programlisting role="php">$query = new Zend_Search_Lucene_Search_Query_Phrase();
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('zend'));
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('framework'));</programlisting>
    irá pesquisar pela frase 'zend framework'. <programlisting role="php">$query = new Zend_Search_Lucene_Search_Query_Phrase();
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('zend'), 0);
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('framework'), 2);</programlisting>
    irá pesquisar pela frase 'zend ????? download' e retornar 'zend platform
    download', 'zend studio download', 'zend core download', 'zend framework
    download' e por aí vai. <programlisting role="php">$query = new Zend_Search_Lucene_Search_Query_Phrase();
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('zend', 'title'));
$query-&gt;addTerm(new Zend_Search_Lucene_Index_Term('framework', 'title'));</programlisting>
    irá pesquisar pela frase 'zend framework' em um campo 'title'.</para>

    <para>O fator de aproximação ("Sloop factor") determina o número de
    palavras permitidas entre as palavras da frase pesquisada. Se for zero,
    então a busca será pela frase exata. Para valores maiores ele funciona bem
    com os operadores WITHIN ou NEAR. </para>

    <para>Ele é de fato uma medida de distância, onde as unidades correspondem
    aos deslocamentos dos termos na frase consultada. Por exemplo, para
    alterar a ordem de duas palavras são necessários dois movimentos (o
    primeiro move uma palavra para a frente da outra), então para permitir a
    reordenação de uma frase, o fator deve ser de pelo menos duas
    unidades.</para>

    <para>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.</para>

    <para>Comparações mais exatas exatas possuem pontuações mais altas que o
    fator de aproximação, dessa forma os resultados são ordenados por
    exatidão. O fator de aproximação será zero por padrão, determinando
    comparações exatas.</para>

    <para>O fator de aproximação pode ser estabelecido após a criação da
    consulta:</para>

    <programlisting role="php">&lt;?php

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

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

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

?&gt;</programlisting>
  </sect2>
</sect1>
<!--
vim:se ts=4 sw=4 et:
-->