RDoc-3706 Vector search: Filtered queries

docs/ai-integration/vector-search/content/_vector-search-using-dynamic-query-csharp.mdx

@@ -23,7 +23,8 @@ import CodeBlock from '@theme/CodeBlock';
   * [Dynamic vector search - exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search)
   * [Quantization options](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#quantization-options)
   * [Querying vector fields and regular data in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#querying-vector-fields-and-regular-data-in-the-same-query)
-  * [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query)
+    * [How filtered vector search works](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#how-filtered-vector-search-works)   
+  * [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query)   
   * [Syntax](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#syntax)
 
 </Admonition>
@@ -1323,7 +1324,7 @@ where vector.search(TagsEmbeddedAsSingle, $queryVector, 0.85, 10)
 * You can perform a vector search and a regular search in the same query.  
   A single auto-index will be created for both search predicates.
 
-* In the following example, results will include Product documents with content similar to "italian food" in their _Name_ field and a _PricePerUnit_ above 20.
+* In the following example, results will include Product documents with content similar to "italian food" in their _Name_ field AND a _PricePerUnit_ above 20.
   The following auto-index will be generated:  
   `Auto/Products/ByPricePerUnitAndVector.search(embedding.text(Name))`.
 
@@ -1415,35 +1416,38 @@ and (vector.search(embedding.text(Name), $searchTerm, 0.75, 16))
 </TabItem>
 </Tabs>
 
-<Admonition type="info" title="">
-
-**Impact of _NumberOfCandidates_ on query results**:  
-
-* When combining a vector search with a filtering condition, the filter applies only to the documents retrieved within the `NumberOfCandidates` param limit.
-  Increasing or decreasing _NumberOfCandidates_ can affect the query results.
-  A larger _NumberOfCandidates_ increases the pool of documents considered,
-  improving the chances of finding results that match both the vector search and the filter condition.
-
-* For example, in the above query, the vector search executes with: Similarity `0.75f` and NumberOfCandidates `16`.
-  Running this query on RavenDB's sample data returns **2** documents. 
-
-* However, if you increase _NumberOfCandidates_, the query will retrieve more candidate documents before applying the filtering condition.
-  If you run the following query:
-
-<Tabs groupId='languageSyntax'>
-<TabItem value="RQL" label="RQL">
-```sql
-from "Products"
-where (PricePerUnit > $minPrice)
-// Run vector search with similarity 0.75 and NumberOfCandidates 25
-and (vector.search(embedding.text(Name), $searchTerm, 0.75, 25))
-{ "minPrice" : 35.0, "searchTerm" : "italian food" }
-```
-</TabItem>
-</Tabs>
+<Admonition type="note" title="">
+
+### How filtered vector search works    
 
-    now the query returns **4** documents instead of **2**.
+When a vector search query is combined with a filtering condition using _AND_ (e.g., `where vector.search(...) and PricePerUnit > 35`),
+RavenDB integrates the filter into the vector search process rather than running the vector search independently and discarding non-matching results afterward.  
 
+**Internal Strategies**   
+RavenDB first evaluates the filter to determine how many documents match and then dynamically selects a strategy:    
+
+* **Exact search over filtered documents:**  
+  This mode is triggered when any of the following conditions is true:    
+
+  * The filter match count is **below** the scanning threshold (default: `1024`).  
+    Can be customized via the [Indexing.Corax.VectorSearch.VectorSearchScanningThreshold](../../../server/configuration/indexing-configuration.mdx#indexingcoraxvectorsearchvectorsearchscanningthreshold) configuration key.
+  * An [Exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search) is explicitly requested.  
+  * The requested _number of candidates_ exceeds half the filter match count.  
+    Learn about the _number of candidates_ param in [The query parameters](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#the-dynamic-query-parameters).
+
+  In this mode, an exact search is performed over **only** the documents that match the filter.   
+
+* **Approximate search:**  
+  When none of the conditions above apply, RavenDB uses approximate HNSW graph traversal to find the nearest vectors to the search term.
+  The filter is then applied to the results.  
+  If the number of results that pass the filter is **less** than the requested _number of candidates_,
+  RavenDB increases the internal candidate count and continues the HNSW search.  
+  This is an iterative process that ensures that enough results matching both vector similarity and the filtering condition are found.
+
+  Note:    
+  Re-search rounds are efficient because RavenDB caches the HNSW graph's internal state (including previously computed results), 
+  avoiding redundant distance calculations for previously visited nodes.    
+
 </Admonition>
 
 ## Combining multiple vector searches in the same query

docs/ai-integration/vector-search/content/_vector-search-using-dynamic-query-nodejs.mdx

@@ -23,6 +23,7 @@ import CodeBlock from '@theme/CodeBlock';
   * [Dynamic vector search - exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search)
   * [Quantization options](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#quantization-options)
   * [Querying vector fields and regular data in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#querying-vector-fields-and-regular-data-in-the-same-query)
+    * [How filtered vector search works](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#how-filtered-vector-search-works)   
   * [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query)
   * [Syntax](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#syntax)
 
@@ -962,35 +963,38 @@ and (vector.search(embedding.text(Name), $searchTerm, 0.75, 16))
 </TabItem>
 </Tabs>
 
-<Admonition type="info" title="">
-
-**Impact of _numberOfCandidates_ on query results**:  
-
-* When combining a vector search with a filtering condition, the filter applies only to the documents retrieved within the `numberOfCandidates` param limit.
-  Increasing or decreasing _numberOfCandidates_ can affect the query results.
-  A larger _numberOfCandidates_ increases the pool of documents considered,
-  improving the chances of finding results that match both the vector search and the filter condition.
-
-* For example, in the above query, the vector search executes with: similarity `0.75` and numberOfCandidates `16`.
-  Running this query on RavenDB's sample data returns **2** documents. 
-
-* However, if you increase _numberOfCandidates_, the query will retrieve more candidate documents before applying the filtering condition.
-  If you run the following query:
-
-<Tabs groupId='languageSyntax'>
-<TabItem value="RQL" label="RQL">
-```sql
-from "Products"
-where (PricePerUnit > $minPrice)
-// Run vector search with similarity 0.75 and numberOfCandidates 25
-and (vector.search(embedding.text(Name), $searchTerm, 0.75, 25))
-{ "minPrice" : 35.0, "searchTerm" : "italian food" }
-```
-</TabItem>
-</Tabs>
+<Admonition type="note" title="">
+
+### How filtered vector search works    
 
-    now the query returns **4** documents instead of **2**.
+When a vector search query is combined with a filtering condition using _AND_ (e.g., `where vector.search(...) and PricePerUnit > 35`),
+RavenDB integrates the filter into the vector search process rather than running the vector search independently and discarding non-matching results afterward.  
 
+**Internal Strategies**   
+RavenDB first evaluates the filter to determine how many documents match and then dynamically selects a strategy:    
+
+* **Exact search over filtered documents:**  
+  This mode is triggered when any of the following conditions is true:    
+
+  * The filter match count is **below** the scanning threshold (default: `1024`).  
+    Can be customized via the [Indexing.Corax.VectorSearch.VectorSearchScanningThreshold](../../../server/configuration/indexing-configuration.mdx#indexingcoraxvectorsearchvectorsearchscanningthreshold) configuration key.
+  * An [Exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search) is explicitly requested.  
+  * The requested _number of candidates_ exceeds half the filter match count.  
+    Learn about the _number of candidates_ param in [The query parameters](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#the-dynamic-query-parameters).
+
+  In this mode, an exact search is performed over **only** the documents that match the filter.   
+
+* **Approximate search:**  
+  When none of the conditions above apply, RavenDB uses approximate HNSW graph traversal to find the nearest vectors to the search term.
+  The filter is then applied to the results.  
+  If the number of results that pass the filter is **less** than the requested _number of candidates_,
+  RavenDB increases the internal candidate count and continues the HNSW search.  
+  This is an iterative process that ensures that enough results matching both vector similarity and the filtering condition are found.
+
+  Note:    
+  Re-search rounds are efficient because RavenDB caches the HNSW graph's internal state (including previously computed results), 
+  avoiding redundant distance calculations for previously visited nodes.    
+
 </Admonition>
 
 ## Combining multiple vector searches in the same query

docs/ai-integration/vector-search/content/_vector-search-using-dynamic-query-python.mdx

@@ -23,6 +23,7 @@ import CodeBlock from '@theme/CodeBlock';
   * [Dynamic vector search - exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search)
   * [Quantization options](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#quantization-options)
   * [Querying vector fields and regular data in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#querying-vector-fields-and-regular-data-in-the-same-query)
+    * [How filtered vector search works](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#how-filtered-vector-search-works)   
   * [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query)
   * [Syntax](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#syntax)
 
@@ -820,29 +821,38 @@ and (vector.search(embedding.text(Name), $searchTerm, 0.75, 16))
 </TabItem>
 </Tabs>
 
-<Admonition type="info" title="">
-
-**Impact of _NumberOfCandidates_ on query results**:  
-
-* When combining a vector search with a filtering condition, the filter applies only to the documents retrieved within the `NumberOfCandidates` param limit.
-  Increasing or decreasing _NumberOfCandidates_ can affect the query results.
-  A larger _NumberOfCandidates_ increases the pool of documents considered,
-  improving the chances of finding results that match both the vector search and the filter condition.
-
-* For example, in the above query, the vector search executes with: Similarity `0.75` and NumberOfCandidates `16`.
-  Running this query on RavenDB's sample data returns **2** documents. 
+<Admonition type="note" title="">
+
+### How filtered vector search works    
 
-* However, if you increase _NumberOfCandidates_, the query will retrieve more candidate documents before applying the filtering condition.
-  If you run the following query:
-  ```sql
-  from "Products"
-  where (PricePerUnit > $minPrice)
-  // Run vector search with similarity 0.75 and NumberOfCandidates 25
-  and (vector.search(embedding.text(Name), $searchTerm, 0.75, 25))
-  { "minPrice" : 35.0, "searchTerm" : "italian food" }
-  ```
-  now the query returns **4** documents instead of **2**.
+When a vector search query is combined with a filtering condition using _AND_ (e.g., `where vector.search(...) and PricePerUnit > 35`),
+RavenDB integrates the filter into the vector search process rather than running the vector search independently and discarding non-matching results afterward.  
 
+**Internal Strategies**   
+RavenDB first evaluates the filter to determine how many documents match and then dynamically selects a strategy:    
+
+* **Exact search over filtered documents:**  
+  This mode is triggered when any of the following conditions is true:    
+
+  * The filter match count is **below** the scanning threshold (default: `1024`).  
+    Can be customized via the [Indexing.Corax.VectorSearch.VectorSearchScanningThreshold](../../../server/configuration/indexing-configuration.mdx#indexingcoraxvectorsearchvectorsearchscanningthreshold) configuration key.
+  * An [Exact search](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#dynamic-vector-search---exact-search) is explicitly requested.  
+  * The requested _number of candidates_ exceeds half the filter match count.  
+    Learn about the _number of candidates_ param in [The query parameters](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#the-dynamic-query-parameters).
+
+  In this mode, an exact search is performed over **only** the documents that match the filter.   
+
+* **Approximate search:**  
+  When none of the conditions above apply, RavenDB uses approximate HNSW graph traversal to find the nearest vectors to the search term.
+  The filter is then applied to the results.  
+  If the number of results that pass the filter is **less** than the requested _number of candidates_,
+  RavenDB increases the internal candidate count and continues the HNSW search.  
+  This is an iterative process that ensures that enough results matching both vector similarity and the filtering condition are found.
+
+  Note:    
+  Re-search rounds are efficient because RavenDB caches the HNSW graph's internal state (including previously computed results), 
+  avoiding redundant distance calculations for previously visited nodes.    
+
 </Admonition>
 
 ## Combining multiple vector searches in the same query

docs/ai-integration/vector-search/content/_vector-search-using-static-index-csharp.mdx

@@ -1668,11 +1668,18 @@ or vector.search(VectorFromText, $searchTerm2, 0.8)
 </TabItem>
 </Tabs>
 
-* Note:  
-You can also combine **multiple vector search statements** in a single query using logical operators.  
-An example is available in:
-[Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query).
+<Admonition type="note" title=""> 
+
+* **Multiple vector searches**:  
+  You can combine multiple vector search statements in a single query using logical operators.  
+  An example is available in:
+  [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query).
+
+* **Vector search with filtering**:  
+  You can also combine vector search with filtering conditions on regular (non-vector) fields in the same query.  
+  Learn more in [Querying vector fields and regular data in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#querying-vector-fields-and-regular-data-in-the-same-query).
 
+</Admonition>
 
 ---
 

docs/ai-integration/vector-search/content/_vector-search-using-static-index-nodejs.mdx

@@ -978,6 +978,19 @@ or vector.search(vectorFromText, $searchTerm2, 0.8)
 </TabItem>
 </Tabs>
 
+<Admonition type="note" title=""> 
+
+* **Multiple vector searches**:  
+  You can combine multiple vector search statements in a single query using logical operators.  
+  An example is available in:
+  [Combining multiple vector searches in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#combining-multiple-vector-searches-in-the-same-query).
+
+* **Vector search with filtering**:  
+  You can also combine vector search with filtering conditions on regular (non-vector) fields in the same query.  
+  Learn more in [Querying vector fields and regular data in the same query](../../../ai-integration/vector-search/vector-search-using-dynamic-query.mdx#querying-vector-fields-and-regular-data-in-the-same-query).
+
+</Admonition>
+
 ---
 
 ## Querying the static index for similar documents