Merge pull request #4206 from vespa-engine/havardpe/document-near-with-negative-terms-and-fix-old-errors

Document negative terms in near/onear and clarify distance semantics

Author: kkraune

en/reference/query-language-reference.html

@@ -248,24 +248,39 @@ <h2 id="where">where</h2>
     <th>near</th>
     <td>
       <p id="near">
-        <code>near()</code> matches if all argument terms occur close to each other in the same document.
+        <code>near()</code> matches if all argument terms occur within the specified distance,
+        in any order. Negative terms (prefixed with <code>!</code>) exclude matches where those terms
+        appear within the exclusion distance.
       </p>
+<pre>
+where field contains near("a", "b", "c")
+where field contains ({distance: 5}near("web", "search"))
+where field contains near("sql", "database", !"nosql")
+</pre>
       <table class="table">
         <thead>
         <tr>
           <th>Annotation</th>
-          <th>Effect</th>
+          <th>Default</th>
+          <th>Description</th>
         </tr>
         </thead>
         <tbody>
         <tr>
           <td><a href="#distance">distance</a></td>
-          <td>Tune closeness using <code>distance</code>.</td>
+          <td>2</td>
+          <td>Maximum position difference for terms to match.</td>
+        </tr>
+        <tr>
+          <td>exclusionDistance</td>
+          <td>(distance+1)/2</td>
+          <td>Exclusion zone size around negative terms.</td>
         </tr>
         </tbody>
       </table>
       <p>
-	For multi-value fields, setting <a href="schema-reference.html#rank-element-gap">element-gap</a> for the field in the rank profile enables distance calculation between adjacent elements.
+        Negative terms must come after all positive terms.
+        For multi-value fields, setting <a href="schema-reference.html#rank-element-gap">element-gap</a> for the field in the rank profile enables distance calculation between adjacent elements.
       </p>
     </td>
   </tr>
@@ -275,26 +290,38 @@ <h2 id="where">where</h2>
     <td>
       <p id="onear">
         <code>onear()</code> (ordered near) is like <code>near()</code>,
-        but also requires the terms in the document having the same order
-        as given in the function (i.e. it is a phrase allowing other words interleaved).
-        With distance 1, <code>onear()</code> has the same semantics as <code>phrase()</code>.
+        but requires terms to appear in the same order as specified in the query.
+        With distance set to (number of terms - 1), <code>onear()</code> is equivalent to <code>phrase()</code>.
       </p>
-      <table class="table"> <!-- ToDo: Assuming near and onear support the same annotations -->
+<pre>
+where field contains onear("web", "search", "engine")
+where field contains ({distance: 5}onear("neural", "network"))
+where field contains onear("java", "tutorial", !"script")
+</pre>
+      <table class="table">
         <thead>
         <tr>
           <th>Annotation</th>
-          <th>Effect</th>
+          <th>Default</th>
+          <th>Description</th>
         </tr>
         </thead>
         <tbody>
         <tr>
           <td><a href="#distance">distance</a></td>
-          <td>Tune closeness using <code>distance</code>.</td>
+          <td>2</td>
+          <td>Maximum position difference for terms to match.</td>
+        </tr>
+        <tr>
+          <td>exclusionDistance</td>
+          <td>(distance+1)/2</td>
+          <td>Exclusion zone size around negative terms.</td>
         </tr>
         </tbody>
       </table>
       <p>
-	For multi-value fields, setting <a href="schema-reference.html#rank-element-gap">element-gap</a> for the field in the rank profile enables distance calculation between adjacent elements.
+        Negative terms must come after all positive terms.
+        For multi-value fields, setting <a href="schema-reference.html#rank-element-gap">element-gap</a> for the field in the rank profile enables distance calculation between adjacent elements.
       </p>
     </td>
   </tr>
@@ -1704,9 +1731,10 @@ <h2 id="annotations">Annotations</h2>
     <td>int</td>
     <td>
       <p id="distance">
-      The <em>distance</em>-annotation sets the maximum position difference to count as a match,
+      The <em>distance</em> annotation sets the maximum position difference to count as a match,
       see <a href="#near">near</a> / <a href="#onear">onear</a>.
-      The default distance is 2, meaning match if the words have up to one separating word.
+      All matching terms must fit within positions [P, P+distance] where P is the first term's position.
+      Default is 2.
       </p>
 <pre>
 where text contains ({distance: 5}near("a", "b"))