lucene-java-3.5.0/lucene/src/java/org/apache/lucene/search/spans/package.html

   1 <!doctype html public "-//w3c//dtd html 4.0 transitional//en">
   2 <!--
   3  Licensed to the Apache Software Foundation (ASF) under one or more
   4  contributor license agreements.  See the NOTICE file distributed with
   5  this work for additional information regarding copyright ownership.
   6  The ASF licenses this file to You under the Apache License, Version 2.0
   7  (the "License"); you may not use this file except in compliance with
   8  the License.  You may obtain a copy of the License at
   9
  10      http://www.apache.org/licenses/LICENSE-2.0
  11
  12  Unless required by applicable law or agreed to in writing, software
  13  distributed under the License is distributed on an "AS IS" BASIS,
  14  WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  15  See the License for the specific language governing permissions and
  16  limitations under the License.
  17 -->
  18 <html>
  19 <head></head>
  20 <body>
  21 The calculus of spans.
  22
  23 <p>A span is a <code>&lt;doc,startPosition,endPosition&gt;</code> tuple.</p>
  24
  25 <p>The following span query operators are implemented:
  26
  27 <ul>
  28
  29 <li>A <a href="SpanTermQuery.html">SpanTermQuery</a> matches all spans
  30 containing a particular <a href="../../index/Term.html">Term</a>.</li>
  31
  32 <li> A <a href="SpanNearQuery.html">SpanNearQuery</a> matches spans
  33 which occur near one another, and can be used to implement things like
  34 phrase search (when constructed from <a
  35 href="SpanTermQuery.html">SpanTermQueries</a>) and inter-phrase
  36 proximity (when constructed from other <a
  37 href="SpanNearQuery.html">SpanNearQueries</a>).</li>
  38
  39 <li>A <a href="SpanOrQuery.html">SpanOrQuery</a> merges spans from a
  40 number of other <a href="SpanQuery.html">SpanQueries</a>.</li>
  41
  42 <li>A <a href="SpanNotQuery.html">SpanNotQuery</a> removes spans
  43 matching one <a href="SpanQuery.html">SpanQuery</a> which overlap
  44 another.  This can be used, e.g., to implement within-paragraph
  45 search.</li>
  46
  47 <li>A <a href="SpanFirstQuery.html">SpanFirstQuery</a> matches spans
  48 matching <code>q</code> whose end position is less than
  49 <code>n</code>.  This can be used to constrain matches to the first
  50 part of the document.</li>
  51
  52 </ul>
  53
  54 In all cases, output spans are minimally inclusive.  In other words, a
  55 span formed by matching a span in x and y starts at the lesser of the
  56 two starts and ends at the greater of the two ends.
  57 </p>
  58
  59 <p>For example, a span query which matches "John Kerry" within ten
  60 words of "George Bush" within the first 100 words of the document
  61 could be constructed with:
  62 <pre class="prettyprint">
  63 SpanQuery john   = new SpanTermQuery(new Term("content", "john"));
  64 SpanQuery kerry  = new SpanTermQuery(new Term("content", "kerry"));
  65 SpanQuery george = new SpanTermQuery(new Term("content", "george"));
  66 SpanQuery bush   = new SpanTermQuery(new Term("content", "bush"));
  67
  68 SpanQuery johnKerry =
  69    new SpanNearQuery(new SpanQuery[] {john, kerry}, 0, true);
  70
  71 SpanQuery georgeBush =
  72    new SpanNearQuery(new SpanQuery[] {george, bush}, 0, true);
  73
  74 SpanQuery johnKerryNearGeorgeBush =
  75    new SpanNearQuery(new SpanQuery[] {johnKerry, georgeBush}, 10, false);
  76
  77 SpanQuery johnKerryNearGeorgeBushAtStart =
  78    new SpanFirstQuery(johnKerryNearGeorgeBush, 100);
  79 </pre>
  80
  81 <p>Span queries may be freely intermixed with other Lucene queries.
  82 So, for example, the above query can be restricted to documents which
  83 also use the word "iraq" with:
  84
  85 <pre class="prettyprint">
  86 Query query = new BooleanQuery();
  87 query.add(johnKerryNearGeorgeBushAtStart, true, false);
  88 query.add(new TermQuery("content", "iraq"), true, false);
  89 </pre>
  90
  91 </body>
  92 </html>