@@ -31,42 +31,42 @@ Description
3131``vectorSearch(table='<index>', field='<vector-field>', vector='<array>', option='<key=value[,key=value]*>') ``
3232
3333All four arguments are required and must be passed by name as string
34- literals. Positional or mixed-positional calls are rejected, for example::
34+ literals. Positional arguments, or a mix of positional and named
35+ arguments, are not supported. For example, the following is invalid::
3536
36- -- invalid: positional argument
3737 FROM vectorSearch('my_vectors', field='embedding',
3838 vector='[0.1,0.2]', option='k=5') AS v
3939
40- A table alias is required. Reference projected fields through the alias
41- (``v._id ``, ``v._score ``, ``v.category ``).
40+ A table alias is required. Projected fields are referenced through the
41+ alias (``v._id ``, ``v._score ``, ``v.category ``).
4242
4343If the ``opensearch-knn `` plugin is not installed on the target cluster,
4444query execution fails with a ``vectorSearch() requires the k-NN plugin ``
45- error. ``_explain `` still works without the plugin.
45+ error. ``_explain `` continues to work without the plugin.
4646
4747Arguments
4848---------
4949
5050- ``table `` — single concrete index or alias to search. Wildcards
5151 (``* ``), comma-separated multi-index targets, ``_all ``, ``. ``, and
52- ``.. `` are rejected . The target index must have `` index.knn: true `` and
53- map the target field as ``knn_vector ``.
52+ ``.. `` are not supported . The target index must have
53+ `` index.knn: true `` and map the target field as ``knn_vector ``.
5454- ``field `` — name of the ``knn_vector `` field.
5555- ``vector `` — query vector as a JSON-style array of numbers, passed as a
5656 string (for example, ``'[0.1, 0.2, 0.3]' ``). Components must be
57- comma-separated finite numbers; semicolon , colon, or pipe separators
58- and empty components (for example, ``'[1.0,,2.0]' `` or `` '[1.0,]' ``)
59- are rejected. The vector dimension must match the `` knn_vector ``
60- mapping on the target index.
57+ comma-separated finite numbers. Semicolon , colon, and pipe separators
58+ are not supported, and empty components (for example, ``'[1.0,,2.0]' ``
59+ or `` '[1.0,]' ``) return an error. The vector dimension must match the
60+ `` knn_vector `` mapping on the target index.
6161- ``option `` — comma-separated ``key=value `` pairs. Exactly one of ``k ``,
6262 ``max_distance ``, or ``min_score `` is required. ``filter_type `` is
6363 optional.
6464
6565Supported option keys
6666---------------------
6767
68- Option keys are lower-case and case-sensitive. ``K=5 `` or `` Filter_Type=post ``
69- will be rejected with an "Unknown option key" error.
68+ Option keys are lower-case and case-sensitive. ``K=5 `` or
69+ `` Filter_Type=post `` returns an "Unknown option key" error.
7070
7171- ``k `` — top-k mode. Integer between 1 and 10000. The query returns up to
7272 ``k `` nearest neighbors.
@@ -83,8 +83,8 @@ exactly one.
8383
8484Native k-NN tuning options (for example, ``method_parameters.ef_search ``,
8585``method_parameters.nprobes ``, ``rescore.oversample_factor ``) are not
86- exposed through ``vectorSearch() `` and are rejected as unknown option
87- keys .
86+ supported through ``vectorSearch() `` and return an "Unknown option
87+ key" error .
8888
8989Syntax
9090------
@@ -190,19 +190,19 @@ Behavior depends on whether ``filter_type`` is specified:
190190 results are returned. A query with no ``WHERE `` clause is valid.
191191- **Explicit ``post`` ** — a ``WHERE `` clause is required and must be
192192 translatable to an OpenSearch filter query. If the ``WHERE `` clause is
193- missing or cannot be translated, the query fails with a descriptive
194- error. Specifying ``filter_type=post `` explicitly is useful when you
195- want the query to fail fast rather than silently fall back to in-memory
196- filtering.
193+ missing or cannot be translated, the query fails with an error.
194+ Specifying ``filter_type=post `` explicitly is useful when the query
195+ should fail with an error instead of silently falling back to
196+ in-memory filtering.
197197- **Explicit ``efficient`` ** — a ``WHERE `` clause is required and must
198198 compile to a filter shape that can be embedded under ``knn.filter ``.
199199 ``efficient `` supports simple native filters: ``term ``, ``range ``,
200200 ``wildcard ``, ``exists ``, full-text family (``match ``, ``match_phrase ``,
201201 ``match_phrase_prefix ``, ``match_bool_prefix ``, ``multi_match ``,
202202 ``query_string ``, ``simple_query_string ``), and boolean combinations of
203203 those filters. Predicates that compile to script queries (arithmetic,
204- function calls, ``CASE ``, date math), nested predicates, and unknown
205- query shapes are rejected .
204+ function calls, ``CASE ``, date math), nested predicates, and other
205+ query shapes are not supported in this mode and return an error .
206206
207207Example 4: Implicit pushdown (no ``filter_type ``)
208208-------------------------------------------------
@@ -263,13 +263,13 @@ Limitations
263263The following are not supported on ``vectorSearch() ``:
264264
265265- ``GROUP BY `` and aggregations over a ``vectorSearch() `` relation are
266- rejected with an error.
266+ not supported and return an error.
267267- An outer ``WHERE `` clause applied to a ``vectorSearch() `` subquery is
268- rejected with an error, because the predicate would be evaluated only
269- after the top-k rows have been selected by vector distance and can
270- silently yield zero rows. Place the predicate inside the subquery,
271- directly on the ``vectorSearch() `` alias, so it can participate in
272- ``WHERE `` pushdown.
268+ not supported and returns an error, because the predicate would be
269+ evaluated only after the top-k rows have been selected by vector
270+ distance and can silently yield zero rows. Place the predicate inside
271+ the subquery, directly on the ``vectorSearch() `` alias, so that it
272+ participates in ``WHERE `` pushdown.
273273- ``JOIN `` between a ``vectorSearch() `` relation and another relation is
274274 not supported.
275275- ``UNION `` / ``INTERSECT `` / ``EXCEPT `` combining a ``vectorSearch() ``
0 commit comments