From 67cd1b6d8acd9893df9a94148559a823cc5fdb2b Mon Sep 17 00:00:00 2001
From: =?UTF-8?q?H=C3=A5vard=20Pettersen?=
 <3535158+havardpe@users.noreply.github.com>
Date: Wed, 29 Oct 2025 11:46:03 +0000
Subject: [PATCH] Document negative terms in near/onear and clarify distance
 semantics

---
 en/reference/query-language-reference.html | 54 ++++++++++++++++------
 1 file changed, 41 insertions(+), 13 deletions(-)

diff --git a/en/reference/query-language-reference.html b/en/reference/query-language-reference.html
index f4e200e1a0..736d592ce8 100644
--- a/en/reference/query-language-reference.html
+++ b/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"))