Merge pull request #448 from weaviate/docs/fix-bm25-and-per-property

docs: BM25 AND operator matches per-property, not cross-object

Author: g-despot

docs/weaviate/api/graphql/search-operators.md

@@ -265,7 +265,7 @@ This operator allows you to combine [BM25](#bm25) and vector search to get a "be
 | `vector`     | no       | `[float]`  | optional to supply your own vector                                          |
 | `properties` | no       | `[string]` | list of properties to limit the BM25 search to, default all text properties |
 | `fusionType` | no       | `string` | the type of hybrid fusion algorithm (available from `v1.20.0`)              |
-| `bm25SearchOperator` | no | `object` | set how many of the (bm25) query tokens must be present in the target object for it to be considered a match. (available from `v1.31.0`) |
+| `bm25SearchOperator` | no | `object` | set how many of the (bm25) query tokens must be present within a single searched property for an object to be considered a match. (available from `v1.31.0`) |
 
 * Notes:
     * `alpha` can be any number from 0 to 1, defaulting to 0.75.
@@ -435,11 +435,11 @@ To mitigate this effect, Weaviate automatically performs a search with a higher
 
 <SearchOperators/>
 
-Use `bm25SearchOperator` to set how many of the query tokens must be present in the target object for it to be considered a match in the keyword (bm25) search portion of the hybrid search. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.
+Use `bm25SearchOperator` to set how many of the query tokens must be present within a single searched property for an object to be considered a match in the keyword (bm25) search portion of the hybrid search. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.
 
-The available options are `And`, or `Or`. If `Or` is set, an additional parameter `minimumOrTokensMatch` must be specified, which defines how many of the query tokens must match for the object to be considered a match.
+The available options are `And`, or `Or`. With `And`, all of the query tokens must appear together within a single searched property; tokens spread across different properties do not match. If `Or` is set, an additional parameter `minimumOrTokensMatch` must be specified, which defines how many of the query tokens must be present within a single searched property for the object to be considered a match.
 
-If not yet, the keyword search will behave as if `Or` was set with `minimumOrTokensMatch` equal to 1.
+If not set, the keyword search behaves as if `Or` was set with a `minimumOrTokensMatch` of `1`.
 
 ## BM25
 
@@ -458,7 +458,7 @@ The `bm25` operator supports the following variables:
 | --------- | -------- | ----------- |
 | `query`   | yes      | The keyword search query. |
 | `properties` | no    | Array of properties (fields) to search in, defaulting to all properties in the collection. |
-| `searchOperator` | no | set how many of the query tokens must be present in the target object for it to be considered a match. (available from `v1.31.0`) |
+| `searchOperator` | no | set how many of the query tokens must be present within a single searched property for an object to be considered a match. (available from `v1.31.0`) |
 
 :::info Boosting properties
 Specific properties can be boosted by a factor specified as a number after the caret sign, for example `properties: ["title^3", "summary"]`.
@@ -537,11 +537,11 @@ import GraphQLFiltersBM25FilterExample from '/_includes/code/graphql.filters.bm2
 
 <SearchOperators/>
 
-Use `searchOperator` to set how many of the query tokens must be present in the target object for it to be considered a match. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.
+Use `searchOperator` to set how many of the query tokens must be present within a single searched property for an object to be considered a match. This is useful when you want to ensure that only objects with a certain number of relevant keywords are returned.
 
-The available options are `And`, or `Or`. If `Or` is set, an additional parameter `minimumOrTokensMatch` must be specified, which defines how many of the query tokens must match for the object to be considered a match.
+The available options are `And`, or `Or`. With `And`, all of the query tokens must appear together within a single searched property; tokens spread across different properties do not match. If `Or` is set, an additional parameter `minimumOrTokensMatch` must be specified, which defines how many of the query tokens must be present within a single searched property for the object to be considered a match.
 
-If not yet, the keyword search will behave as if `Or` was set with `minimumOrTokensMatch` equal to 1.
+If not set, the keyword search behaves as if `Or` was set with a `minimumOrTokensMatch` of `1`.
 
 ## ask
 

docs/weaviate/concepts/search/keyword-search.md

@@ -136,15 +136,15 @@ import SearchOperators from '/_includes/feature-notes/search-operators.mdx';
 
 <SearchOperators/>
 
-Search operators define the minimum number of query [tokens](../../search/bm25.md#set-tokenization) that must be present in the object to be returned.
+Search operators define the minimum number of query [tokens](../../search/bm25.md#set-tokenization) that must be present within a single searched property for an object to be returned.
 
 Conceptually, it works as though a filter is applied to the results of the BM25 score calculation. The available operators are:
-- `and`: All tokens must be present in the object
-- `or`: At least one token must be present in the object, with the minimum number of tokens being configurable (`minimumOrTokensMatch`)
+- `and`: All tokens must be present within a single searched property
+- `or`: At least one token must be present within a single searched property, with the minimum number of tokens being configurable (`minimumOrTokensMatch`)
 
-As an example, a BM25 query of `computer networking guide` with the `and` operator would only return objects that contain all of the tokens `computer`, `networking`, and `guide`. In contrast, the same query with the `or` operator would return objects that contain at least one of those tokens. If the `or` operator is used with a `minimumOrTokensMatch` of `2`, then at least two of the tokens must be present in the object.
+As an example, a BM25 query of `computer networking guide` with the `and` operator would only return objects where all of the tokens `computer`, `networking`, and `guide` appear together within a single searched property. If the tokens are spread across different properties — for example, `computer` in `title` and `networking` in `description` — the object does not match under `and`. In contrast, the same query with the `or` operator would return objects where at least one of those tokens appears in a searched property. If the `or` operator is used with a `minimumOrTokensMatch` of `2`, then at least two of the tokens must be present within a single searched property.
 
-If not specified, the default operator is `or`, with a `minimumOrTokensMatch` of `1`. This means that at least one token must be present in the object for it to be returned.
+If not specified, the default operator is `or`, with a `minimumOrTokensMatch` of `1`. This means that at least one token must be present in a searched property for the object to be returned.
 
 import BM25OperatorsLight from '../img/bm25_operators_light.png';
 import BM25OperatorsDark from '../img/bm25_operators_dark.png';

docs/weaviate/search/bm25.md

@@ -99,7 +99,7 @@ import SearchOperators from '/_includes/feature-notes/search-operators.mdx';
 
 <SearchOperators/>
 
-Search operators define the minimum number of query [tokens](#set-tokenization) that must be present in the object to be returned. The options are `and`, or `or` (default).
+Search operators define the minimum number of query [tokens](#set-tokenization) that must be present within a single searched property for an object to be returned. The options are `and`, or `or` (default).
 
 ### `or`
 
@@ -142,7 +142,7 @@ With the `or` operator, the search returns objects that contain at least `minimu
 
 ### `and`
 
-With the `and` operator, the search returns objects that contain all tokens in the search string.
+With the `and` operator, the search returns objects where all tokens in the search string appear together within a single searched property.
 
 <Tabs className="code" groupId="languages">
   <TabItem value="py" label="Python">

docs/weaviate/search/hybrid.md

@@ -384,7 +384,7 @@ import SearchOperators from '/_includes/feature-notes/search-operators.mdx';
 
 <SearchOperators/>
 
-Keyword (BM25) search operators define the minimum number of query [tokens](#tokenization) that must be present in the object to be returned. The options are `and`, or `or` (default).
+Keyword (BM25) search operators define the minimum number of query [tokens](#tokenization) that must be present within a single searched property for an object to be returned. The options are `and`, or `or` (default).
 
 ### `or`
 
@@ -435,7 +435,7 @@ With the `or` operator, the search returns objects that contain at least `minimu
 
 ### `and`
 
-With the `and` operator, the search returns objects that contain all tokens in the search string.
+With the `and` operator, the search returns objects where all tokens in the search string appear together within a single searched property.
 
 <Tabs className="code" groupId="languages">
   <TabItem value="py" label="Python">