From 1fe0653267810d2200dc4d071da0326ee168ea4b Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Wed, 28 May 2025 18:29:41 +0200 Subject: [PATCH 1/8] search endpoint fixes --- .../_global/search/_types/highlighting.ts | 6 ++- specification/_types/Errors.ts | 2 +- specification/_types/Retriever.ts | 11 +++- .../_types/query_dsl/WeightedTokensQuery.ts | 4 +- specification/_types/query_dsl/fulltext.ts | 51 +++++++++++++++++++ specification/_types/query_dsl/geo.ts | 2 +- specification/_types/query_dsl/specialized.ts | 3 +- 7 files changed, 71 insertions(+), 8 deletions(-) diff --git a/specification/_global/search/_types/highlighting.ts b/specification/_global/search/_types/highlighting.ts index fe50c6e69f..001310b999 100644 --- a/specification/_global/search/_types/highlighting.ts +++ b/specification/_global/search/_types/highlighting.ts @@ -17,7 +17,7 @@ * under the License. */ -import { Dictionary } from '@spec_utils/Dictionary' +import { Dictionary, SingleKeyDictionary } from '@spec_utils/Dictionary' import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { Field, Fields } from '@_types/common' import { integer } from '@_types/Numeric' @@ -151,7 +151,9 @@ export class HighlightBase { export class Highlight extends HighlightBase { encoder?: HighlighterEncoder - fields: Dictionary + fields: + | SingleKeyDictionary + | SingleKeyDictionary[] } export enum HighlighterEncoder { diff --git a/specification/_types/Errors.ts b/specification/_types/Errors.ts index 750a305525..6275b4ae27 100644 --- a/specification/_types/Errors.ts +++ b/specification/_types/Errors.ts @@ -38,7 +38,7 @@ export class ErrorCause /** * A human-readable explanation of the error, in English. */ - reason?: string + reason?: string | null /** * The server stack trace. Present only if the `error_trace=true` parameter was sent with the request. */ diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index 520640b30a..7c6f16f033 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -18,6 +18,7 @@ */ import { FieldCollapse } from '@global/search/_types/FieldCollapse' +import { Rescore } from '@global/search/_types/rescoring' import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' import { float, integer } from '@_types/Numeric' @@ -39,6 +40,8 @@ export class RetrieverContainer { text_similarity_reranker?: TextSimilarityReranker /** A retriever that replaces the functionality of a rule query. */ rule?: RuleRetriever + /** A retriever that re-scores only the results produced by its child retriever. */ + rescorer?: RescorerRetriever } export class RetrieverBase { @@ -48,6 +51,12 @@ export class RetrieverBase { min_score?: float } +export class RescorerRetriever extends RetrieverBase { + /** Inner retriever. */ + retriever: RetrieverContainer + rescore: Rescore | Rescore[] +} + export class StandardRetriever extends RetrieverBase { /** Defines a query to retrieve a set of top documents. */ query?: QueryContainer @@ -105,7 +114,7 @@ export class TextSimilarityReranker extends RetrieverBase { export class RuleRetriever extends RetrieverBase { /** The ruleset IDs containing the rules this retriever is evaluating against. */ - ruleset_ids: Id[] + ruleset_ids: Id | Id[] /** The match criteria that will determine if a rule in the provided rulesets should be applied. */ match_criteria: UserDefinedValue /** The retriever whose results rules should be applied to. */ diff --git a/specification/_types/query_dsl/WeightedTokensQuery.ts b/specification/_types/query_dsl/WeightedTokensQuery.ts index 1dabf656a4..3943d399a9 100644 --- a/specification/_types/query_dsl/WeightedTokensQuery.ts +++ b/specification/_types/query_dsl/WeightedTokensQuery.ts @@ -17,7 +17,7 @@ * under the License. */ -import { Dictionary } from '@spec_utils/Dictionary' +import { SingleKeyDictionary } from '@spec_utils/Dictionary' import { float } from '@_types/Numeric' import { QueryBase } from './abstractions' import { TokenPruningConfig } from './TokenPruningConfig' @@ -27,7 +27,7 @@ import { TokenPruningConfig } from './TokenPruningConfig' */ export class WeightedTokensQuery extends QueryBase { /** The tokens representing this query */ - tokens: Dictionary + tokens: SingleKeyDictionary[] /** Token pruning configurations */ pruning_config?: TokenPruningConfig } diff --git a/specification/_types/query_dsl/fulltext.ts b/specification/_types/query_dsl/fulltext.ts index a03ff6ed38..061b6b8566 100644 --- a/specification/_types/query_dsl/fulltext.ts +++ b/specification/_types/query_dsl/fulltext.ts @@ -103,6 +103,8 @@ export class IntervalsContainer { * Matches terms that start with a specified set of characters. */ prefix?: IntervalsPrefix + range?: IntervalsRange + regexp?: IntervalsRegexp /** * Matches terms using a wildcard pattern. */ @@ -232,6 +234,52 @@ export class IntervalsPrefix { use_field?: Field } +export class IntervalsRange { + /** + * Analyzer used to analyze the `prefix`. + * @doc_id analysis + */ + analyzer?: string + /** + * Lower term, either gte or gt must be provided. + */ + gte?: string + /** + * Lower term, either gte or gt must be provided. + */ + gt?: string + /** + * Upper term, either lte or lt must be provided. + */ + lte?: string + /** + * Upper term, either lte or lt must be provided. + */ + lt?: string + /** + * If specified, match intervals from this field rather than the top-level field. + * The `prefix` is normalized using the search analyzer from this field, unless `analyzer` is specified separately. + */ + use_field?: Field +} + +export class IntervalsRegexp { + /** + * Analyzer used to analyze the `prefix`. + * @doc_id analysis + */ + analyzer?: string + /** + * Regex pattern. + */ + pattern: string + /** + * If specified, match intervals from this field rather than the top-level field. + * The `prefix` is normalized using the search analyzer from this field, unless `analyzer` is specified separately. + */ + use_field?: Field +} + /** * @variants container * @ext_doc_id query-dsl-intervals-query @@ -259,6 +307,9 @@ export class IntervalsQuery extends QueryBase { * Matches terms that start with a specified set of characters. */ prefix?: IntervalsPrefix + range?: IntervalsRange + regexp?: IntervalsRegexp + /** * Matches terms using a wildcard pattern. */ diff --git a/specification/_types/query_dsl/geo.ts b/specification/_types/query_dsl/geo.ts index d73e6327e3..01a2fa5f37 100644 --- a/specification/_types/query_dsl/geo.ts +++ b/specification/_types/query_dsl/geo.ts @@ -97,7 +97,7 @@ export class GeoDistanceQuery /** @variants container */ export class GeoGridQuery extends QueryBase { - geogrid?: GeoTile + geotile?: GeoTile geohash?: GeoHash geohex?: GeoHexCell } diff --git a/specification/_types/query_dsl/specialized.ts b/specification/_types/query_dsl/specialized.ts index 081f8a7b75..72291277f1 100644 --- a/specification/_types/query_dsl/specialized.ts +++ b/specification/_types/query_dsl/specialized.ts @@ -400,6 +400,7 @@ export class ShapeFieldQuery { */ export class RuleQuery extends QueryBase { organic: QueryContainer - ruleset_ids: Id[] + ruleset_ids?: Id | Id[] + ruleset_id?: string match_criteria: UserDefinedValue } From 18f654fc4ad612b90796241efeae3fd4ec991ab5 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 5 Jun 2025 12:44:33 +0200 Subject: [PATCH 2/8] revert breaking changes --- specification/_global/search/_types/highlighting.ts | 6 ++---- specification/_types/query_dsl/WeightedTokensQuery.ts | 4 ++-- 2 files changed, 4 insertions(+), 6 deletions(-) diff --git a/specification/_global/search/_types/highlighting.ts b/specification/_global/search/_types/highlighting.ts index 001310b999..fe50c6e69f 100644 --- a/specification/_global/search/_types/highlighting.ts +++ b/specification/_global/search/_types/highlighting.ts @@ -17,7 +17,7 @@ * under the License. */ -import { Dictionary, SingleKeyDictionary } from '@spec_utils/Dictionary' +import { Dictionary } from '@spec_utils/Dictionary' import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { Field, Fields } from '@_types/common' import { integer } from '@_types/Numeric' @@ -151,9 +151,7 @@ export class HighlightBase { export class Highlight extends HighlightBase { encoder?: HighlighterEncoder - fields: - | SingleKeyDictionary - | SingleKeyDictionary[] + fields: Dictionary } export enum HighlighterEncoder { diff --git a/specification/_types/query_dsl/WeightedTokensQuery.ts b/specification/_types/query_dsl/WeightedTokensQuery.ts index 3943d399a9..1dabf656a4 100644 --- a/specification/_types/query_dsl/WeightedTokensQuery.ts +++ b/specification/_types/query_dsl/WeightedTokensQuery.ts @@ -17,7 +17,7 @@ * under the License. */ -import { SingleKeyDictionary } from '@spec_utils/Dictionary' +import { Dictionary } from '@spec_utils/Dictionary' import { float } from '@_types/Numeric' import { QueryBase } from './abstractions' import { TokenPruningConfig } from './TokenPruningConfig' @@ -27,7 +27,7 @@ import { TokenPruningConfig } from './TokenPruningConfig' */ export class WeightedTokensQuery extends QueryBase { /** The tokens representing this query */ - tokens: SingleKeyDictionary[] + tokens: Dictionary /** Token pruning configurations */ pruning_config?: TokenPruningConfig } From 39ee48bdf1e43c56ab5117773cb2122b707bac10 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 5 Jun 2025 14:54:21 +0200 Subject: [PATCH 3/8] added linear and pinned retriever --- specification/_types/Retriever.ts | 39 +++++++++++++++++++++++++++++++ 1 file changed, 39 insertions(+) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index 7c6f16f033..948a438285 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -42,6 +42,13 @@ export class RetrieverContainer { rule?: RuleRetriever /** A retriever that re-scores only the results produced by its child retriever. */ rescorer?: RescorerRetriever + /** A retriever that supports the combination of different retrievers through a weighted linear combination. */ + linear?: LinearRetriever + /** + * A pinned retriever applies pinned documents to the underlying retriever. + * This retriever will rewrite to a PinnedQueryBuilder. + */ + pinned?: PinnedRetriever } export class RetrieverBase { @@ -49,6 +56,8 @@ export class RetrieverBase { filter?: QueryContainer | QueryContainer[] /** Minimum _score for matching documents. Documents with a lower _score are not included in the top documents. */ min_score?: float + /** Retriever name. */ + _name?: string } export class RescorerRetriever extends RetrieverBase { @@ -57,6 +66,36 @@ export class RescorerRetriever extends RetrieverBase { rescore: Rescore | Rescore[] } +export class LinearRetriever extends RetrieverBase { + /** Inner retrievers. */ + retrievers?: InnerRetriever[] + rank_window_size: integer +} + +export class PinnedRetriever extends RetrieverBase { + /** Inner retriever. */ + retriever: RetrieverContainer + ids?: string[] + docs?: SpecifiedDocument[] + rank_window_size: integer +} + +export class InnerRetriever { + retriever: RetrieverContainer + weight: float + normalizer: ScoreNormalizer +} + +export enum ScoreNormalizer { + none, + minmax +} + +export class SpecifiedDocument { + index?: string + id: string +} + export class StandardRetriever extends RetrieverBase { /** Defines a query to retrieve a set of top documents. */ query?: QueryContainer From d72b1b32aac5e3b84810a917cf0ef719e1bfb5e9 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 5 Jun 2025 15:04:33 +0200 Subject: [PATCH 4/8] prettier? --- specification/_types/Retriever.ts | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index 84d705984a..de228b08bd 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -16,12 +16,12 @@ * specific language governing permissions and limitations * under the License. */ +import { FieldCollapse } from '@global/search/_types/FieldCollapse' import { Rescore } from '@global/search/_types/rescoring' +import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' import { float, integer } from '@_types/Numeric' import { Sort, SortResults } from '@_types/sort' -import { FieldCollapse } from '@global/search/_types/FieldCollapse' -import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { Id } from './common' import { QueryContainer } from './query_dsl/abstractions' From 7b6fbc6caeabc9381ac76ad9c83bd804231345b8 Mon Sep 17 00:00:00 2001 From: Quentin Pradet Date: Thu, 5 Jun 2025 17:21:08 +0400 Subject: [PATCH 5/8] Run prettier --- specification/_types/Retriever.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index de228b08bd..e7fd6d8d0e 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -16,12 +16,12 @@ * specific language governing permissions and limitations * under the License. */ -import { FieldCollapse } from '@global/search/_types/FieldCollapse' -import { Rescore } from '@global/search/_types/rescoring' -import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' import { float, integer } from '@_types/Numeric' import { Sort, SortResults } from '@_types/sort' +import { FieldCollapse } from '@global/search/_types/FieldCollapse' +import { Rescore } from '@global/search/_types/rescoring' +import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { Id } from './common' import { QueryContainer } from './query_dsl/abstractions' From 84536c358af071503ebffc0d1ed58a4846b3f3ea Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 5 Jun 2025 16:03:00 +0200 Subject: [PATCH 6/8] use alias types --- specification/_types/Retriever.ts | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index e7fd6d8d0e..e30773f17a 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -22,7 +22,7 @@ import { Sort, SortResults } from '@_types/sort' import { FieldCollapse } from '@global/search/_types/FieldCollapse' import { Rescore } from '@global/search/_types/rescoring' import { UserDefinedValue } from '@spec_utils/UserDefinedValue' -import { Id } from './common' +import {Id, IndexName} from './common' import { QueryContainer } from './query_dsl/abstractions' /** @@ -91,8 +91,8 @@ export enum ScoreNormalizer { } export class SpecifiedDocument { - index?: string - id: string + index?: IndexName + id: Id } export class StandardRetriever extends RetrieverBase { From 9bbc86861b0326dad64557237c4b061785fff3d8 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Thu, 5 Jun 2025 16:07:44 +0200 Subject: [PATCH 7/8] pretty --- specification/_types/Retriever.ts | 196 +++++++++++++++--------------- 1 file changed, 98 insertions(+), 98 deletions(-) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index e30773f17a..5f451578f6 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -16,147 +16,147 @@ * specific language governing permissions and limitations * under the License. */ -import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' -import { float, integer } from '@_types/Numeric' -import { Sort, SortResults } from '@_types/sort' import { FieldCollapse } from '@global/search/_types/FieldCollapse' import { Rescore } from '@global/search/_types/rescoring' import { UserDefinedValue } from '@spec_utils/UserDefinedValue' -import {Id, IndexName} from './common' +import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' +import { float, integer } from '@_types/Numeric' +import { Sort, SortResults } from '@_types/sort' +import { Id, IndexName } from './common' import { QueryContainer } from './query_dsl/abstractions' /** * @variants container */ export class RetrieverContainer { - /** A retriever that replaces the functionality of a traditional query. */ - standard?: StandardRetriever - /** A retriever that replaces the functionality of a knn search. */ - knn?: KnnRetriever - /** A retriever that produces top documents from reciprocal rank fusion (RRF). */ - rrf?: RRFRetriever - /** A retriever that reranks the top documents based on a reranking model using the InferenceAPI */ - text_similarity_reranker?: TextSimilarityReranker - /** A retriever that replaces the functionality of a rule query. */ - rule?: RuleRetriever - /** A retriever that re-scores only the results produced by its child retriever. */ - rescorer?: RescorerRetriever - /** A retriever that supports the combination of different retrievers through a weighted linear combination. */ - linear?: LinearRetriever - /** - * A pinned retriever applies pinned documents to the underlying retriever. - * This retriever will rewrite to a PinnedQueryBuilder. - */ - pinned?: PinnedRetriever + /** A retriever that replaces the functionality of a traditional query. */ + standard?: StandardRetriever + /** A retriever that replaces the functionality of a knn search. */ + knn?: KnnRetriever + /** A retriever that produces top documents from reciprocal rank fusion (RRF). */ + rrf?: RRFRetriever + /** A retriever that reranks the top documents based on a reranking model using the InferenceAPI */ + text_similarity_reranker?: TextSimilarityReranker + /** A retriever that replaces the functionality of a rule query. */ + rule?: RuleRetriever + /** A retriever that re-scores only the results produced by its child retriever. */ + rescorer?: RescorerRetriever + /** A retriever that supports the combination of different retrievers through a weighted linear combination. */ + linear?: LinearRetriever + /** + * A pinned retriever applies pinned documents to the underlying retriever. + * This retriever will rewrite to a PinnedQueryBuilder. + */ + pinned?: PinnedRetriever } export class RetrieverBase { - /** Query to filter the documents that can match. */ - filter?: QueryContainer | QueryContainer[] - /** Minimum _score for matching documents. Documents with a lower _score are not included in the top documents. */ - min_score?: float - /** Retriever name. */ - _name?: string + /** Query to filter the documents that can match. */ + filter?: QueryContainer | QueryContainer[] + /** Minimum _score for matching documents. Documents with a lower _score are not included in the top documents. */ + min_score?: float + /** Retriever name. */ + _name?: string } export class RescorerRetriever extends RetrieverBase { - /** Inner retriever. */ - retriever: RetrieverContainer - rescore: Rescore | Rescore[] + /** Inner retriever. */ + retriever: RetrieverContainer + rescore: Rescore | Rescore[] } export class LinearRetriever extends RetrieverBase { - /** Inner retrievers. */ - retrievers?: InnerRetriever[] - rank_window_size: integer + /** Inner retrievers. */ + retrievers?: InnerRetriever[] + rank_window_size: integer } export class PinnedRetriever extends RetrieverBase { - /** Inner retriever. */ - retriever: RetrieverContainer - ids?: string[] - docs?: SpecifiedDocument[] - rank_window_size: integer + /** Inner retriever. */ + retriever: RetrieverContainer + ids?: string[] + docs?: SpecifiedDocument[] + rank_window_size: integer } export class InnerRetriever { - retriever: RetrieverContainer - weight: float - normalizer: ScoreNormalizer + retriever: RetrieverContainer + weight: float + normalizer: ScoreNormalizer } export enum ScoreNormalizer { - none, - minmax + none, + minmax } export class SpecifiedDocument { - index?: IndexName - id: Id + index?: IndexName + id: Id } export class StandardRetriever extends RetrieverBase { - /** Defines a query to retrieve a set of top documents. */ - query?: QueryContainer - /** Defines a search after object parameter used for pagination. */ - search_after?: SortResults - /** Maximum number of documents to collect for each shard. */ - terminate_after?: integer - /** A sort object that that specifies the order of matching documents. */ - sort?: Sort - /** Collapses the top documents by a specified key into a single top document per key. */ - collapse?: FieldCollapse + /** Defines a query to retrieve a set of top documents. */ + query?: QueryContainer + /** Defines a search after object parameter used for pagination. */ + search_after?: SortResults + /** Maximum number of documents to collect for each shard. */ + terminate_after?: integer + /** A sort object that that specifies the order of matching documents. */ + sort?: Sort + /** Collapses the top documents by a specified key into a single top document per key. */ + collapse?: FieldCollapse } export class KnnRetriever extends RetrieverBase { - /** The name of the vector field to search against. */ - field: string - /** Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both. */ - query_vector?: QueryVector - /** Defines a model to build a query vector. */ - query_vector_builder?: QueryVectorBuilder - /** Number of nearest neighbors to return as top hits. */ - k: integer - /** Number of nearest neighbor candidates to consider per shard. */ - num_candidates: integer - /** The minimum similarity required for a document to be considered a match. */ - similarity?: float - /** Apply oversampling and rescoring to quantized vectors - * @availability stack since=8.18.0 - * @availability serverless - */ - rescore_vector?: RescoreVector + /** The name of the vector field to search against. */ + field: string + /** Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both. */ + query_vector?: QueryVector + /** Defines a model to build a query vector. */ + query_vector_builder?: QueryVectorBuilder + /** Number of nearest neighbors to return as top hits. */ + k: integer + /** Number of nearest neighbor candidates to consider per shard. */ + num_candidates: integer + /** The minimum similarity required for a document to be considered a match. */ + similarity?: float + /** Apply oversampling and rescoring to quantized vectors + * @availability stack since=8.18.0 + * @availability serverless + */ + rescore_vector?: RescoreVector } export class RRFRetriever extends RetrieverBase { - /** A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. */ - retrievers: RetrieverContainer[] - /** This value determines how much influence documents in individual result sets per query have over the final ranked result set. */ - rank_constant?: integer - /** This value determines the size of the individual result sets per query. */ - rank_window_size?: integer + /** A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. */ + retrievers: RetrieverContainer[] + /** This value determines how much influence documents in individual result sets per query have over the final ranked result set. */ + rank_constant?: integer + /** This value determines the size of the individual result sets per query. */ + rank_window_size?: integer } export class TextSimilarityReranker extends RetrieverBase { - /** The nested retriever which will produce the first-level results, that will later be used for reranking. */ - retriever: RetrieverContainer - /** This value determines how many documents we will consider from the nested retriever. */ - rank_window_size?: integer - /** Unique identifier of the inference endpoint created using the inference API. */ - inference_id?: string - /** The text snippet used as the basis for similarity comparison */ - inference_text?: string - /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text */ - field?: string + /** The nested retriever which will produce the first-level results, that will later be used for reranking. */ + retriever: RetrieverContainer + /** This value determines how many documents we will consider from the nested retriever. */ + rank_window_size?: integer + /** Unique identifier of the inference endpoint created using the inference API. */ + inference_id?: string + /** The text snippet used as the basis for similarity comparison */ + inference_text?: string + /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text */ + field?: string } export class RuleRetriever extends RetrieverBase { - /** The ruleset IDs containing the rules this retriever is evaluating against. */ - ruleset_ids: Id | Id[] - /** The match criteria that will determine if a rule in the provided rulesets should be applied. */ - match_criteria: UserDefinedValue - /** The retriever whose results rules should be applied to. */ - retriever: RetrieverContainer - /** This value determines the size of the individual result set. */ - rank_window_size?: integer + /** The ruleset IDs containing the rules this retriever is evaluating against. */ + ruleset_ids: Id | Id[] + /** The match criteria that will determine if a rule in the provided rulesets should be applied. */ + match_criteria: UserDefinedValue + /** The retriever whose results rules should be applied to. */ + retriever: RetrieverContainer + /** This value determines the size of the individual result set. */ + rank_window_size?: integer } From f03d45bcad4a7e98f089e82a36602c908aa1dfc3 Mon Sep 17 00:00:00 2001 From: Laura Trotta Date: Fri, 6 Jun 2025 10:37:53 +0200 Subject: [PATCH 8/8] pretty! --- specification/_types/Retriever.ts | 194 +++++++++++++++--------------- 1 file changed, 97 insertions(+), 97 deletions(-) diff --git a/specification/_types/Retriever.ts b/specification/_types/Retriever.ts index 5f451578f6..dc742ca4b8 100644 --- a/specification/_types/Retriever.ts +++ b/specification/_types/Retriever.ts @@ -16,12 +16,12 @@ * specific language governing permissions and limitations * under the License. */ -import { FieldCollapse } from '@global/search/_types/FieldCollapse' -import { Rescore } from '@global/search/_types/rescoring' -import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { QueryVector, QueryVectorBuilder, RescoreVector } from '@_types/Knn' import { float, integer } from '@_types/Numeric' import { Sort, SortResults } from '@_types/sort' +import { FieldCollapse } from '@global/search/_types/FieldCollapse' +import { Rescore } from '@global/search/_types/rescoring' +import { UserDefinedValue } from '@spec_utils/UserDefinedValue' import { Id, IndexName } from './common' import { QueryContainer } from './query_dsl/abstractions' @@ -29,134 +29,134 @@ import { QueryContainer } from './query_dsl/abstractions' * @variants container */ export class RetrieverContainer { - /** A retriever that replaces the functionality of a traditional query. */ - standard?: StandardRetriever - /** A retriever that replaces the functionality of a knn search. */ - knn?: KnnRetriever - /** A retriever that produces top documents from reciprocal rank fusion (RRF). */ - rrf?: RRFRetriever - /** A retriever that reranks the top documents based on a reranking model using the InferenceAPI */ - text_similarity_reranker?: TextSimilarityReranker - /** A retriever that replaces the functionality of a rule query. */ - rule?: RuleRetriever - /** A retriever that re-scores only the results produced by its child retriever. */ - rescorer?: RescorerRetriever - /** A retriever that supports the combination of different retrievers through a weighted linear combination. */ - linear?: LinearRetriever - /** - * A pinned retriever applies pinned documents to the underlying retriever. - * This retriever will rewrite to a PinnedQueryBuilder. - */ - pinned?: PinnedRetriever + /** A retriever that replaces the functionality of a traditional query. */ + standard?: StandardRetriever + /** A retriever that replaces the functionality of a knn search. */ + knn?: KnnRetriever + /** A retriever that produces top documents from reciprocal rank fusion (RRF). */ + rrf?: RRFRetriever + /** A retriever that reranks the top documents based on a reranking model using the InferenceAPI */ + text_similarity_reranker?: TextSimilarityReranker + /** A retriever that replaces the functionality of a rule query. */ + rule?: RuleRetriever + /** A retriever that re-scores only the results produced by its child retriever. */ + rescorer?: RescorerRetriever + /** A retriever that supports the combination of different retrievers through a weighted linear combination. */ + linear?: LinearRetriever + /** + * A pinned retriever applies pinned documents to the underlying retriever. + * This retriever will rewrite to a PinnedQueryBuilder. + */ + pinned?: PinnedRetriever } export class RetrieverBase { - /** Query to filter the documents that can match. */ - filter?: QueryContainer | QueryContainer[] - /** Minimum _score for matching documents. Documents with a lower _score are not included in the top documents. */ - min_score?: float - /** Retriever name. */ - _name?: string + /** Query to filter the documents that can match. */ + filter?: QueryContainer | QueryContainer[] + /** Minimum _score for matching documents. Documents with a lower _score are not included in the top documents. */ + min_score?: float + /** Retriever name. */ + _name?: string } export class RescorerRetriever extends RetrieverBase { - /** Inner retriever. */ - retriever: RetrieverContainer - rescore: Rescore | Rescore[] + /** Inner retriever. */ + retriever: RetrieverContainer + rescore: Rescore | Rescore[] } export class LinearRetriever extends RetrieverBase { - /** Inner retrievers. */ - retrievers?: InnerRetriever[] - rank_window_size: integer + /** Inner retrievers. */ + retrievers?: InnerRetriever[] + rank_window_size: integer } export class PinnedRetriever extends RetrieverBase { - /** Inner retriever. */ - retriever: RetrieverContainer - ids?: string[] - docs?: SpecifiedDocument[] - rank_window_size: integer + /** Inner retriever. */ + retriever: RetrieverContainer + ids?: string[] + docs?: SpecifiedDocument[] + rank_window_size: integer } export class InnerRetriever { - retriever: RetrieverContainer - weight: float - normalizer: ScoreNormalizer + retriever: RetrieverContainer + weight: float + normalizer: ScoreNormalizer } export enum ScoreNormalizer { - none, - minmax + none, + minmax } export class SpecifiedDocument { - index?: IndexName - id: Id + index?: IndexName + id: Id } export class StandardRetriever extends RetrieverBase { - /** Defines a query to retrieve a set of top documents. */ - query?: QueryContainer - /** Defines a search after object parameter used for pagination. */ - search_after?: SortResults - /** Maximum number of documents to collect for each shard. */ - terminate_after?: integer - /** A sort object that that specifies the order of matching documents. */ - sort?: Sort - /** Collapses the top documents by a specified key into a single top document per key. */ - collapse?: FieldCollapse + /** Defines a query to retrieve a set of top documents. */ + query?: QueryContainer + /** Defines a search after object parameter used for pagination. */ + search_after?: SortResults + /** Maximum number of documents to collect for each shard. */ + terminate_after?: integer + /** A sort object that that specifies the order of matching documents. */ + sort?: Sort + /** Collapses the top documents by a specified key into a single top document per key. */ + collapse?: FieldCollapse } export class KnnRetriever extends RetrieverBase { - /** The name of the vector field to search against. */ - field: string - /** Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both. */ - query_vector?: QueryVector - /** Defines a model to build a query vector. */ - query_vector_builder?: QueryVectorBuilder - /** Number of nearest neighbors to return as top hits. */ - k: integer - /** Number of nearest neighbor candidates to consider per shard. */ - num_candidates: integer - /** The minimum similarity required for a document to be considered a match. */ - similarity?: float - /** Apply oversampling and rescoring to quantized vectors - * @availability stack since=8.18.0 - * @availability serverless - */ - rescore_vector?: RescoreVector + /** The name of the vector field to search against. */ + field: string + /** Query vector. Must have the same number of dimensions as the vector field you are searching against. You must provide a query_vector_builder or query_vector, but not both. */ + query_vector?: QueryVector + /** Defines a model to build a query vector. */ + query_vector_builder?: QueryVectorBuilder + /** Number of nearest neighbors to return as top hits. */ + k: integer + /** Number of nearest neighbor candidates to consider per shard. */ + num_candidates: integer + /** The minimum similarity required for a document to be considered a match. */ + similarity?: float + /** Apply oversampling and rescoring to quantized vectors + * @availability stack since=8.18.0 + * @availability serverless + */ + rescore_vector?: RescoreVector } export class RRFRetriever extends RetrieverBase { - /** A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. */ - retrievers: RetrieverContainer[] - /** This value determines how much influence documents in individual result sets per query have over the final ranked result set. */ - rank_constant?: integer - /** This value determines the size of the individual result sets per query. */ - rank_window_size?: integer + /** A list of child retrievers to specify which sets of returned top documents will have the RRF formula applied to them. */ + retrievers: RetrieverContainer[] + /** This value determines how much influence documents in individual result sets per query have over the final ranked result set. */ + rank_constant?: integer + /** This value determines the size of the individual result sets per query. */ + rank_window_size?: integer } export class TextSimilarityReranker extends RetrieverBase { - /** The nested retriever which will produce the first-level results, that will later be used for reranking. */ - retriever: RetrieverContainer - /** This value determines how many documents we will consider from the nested retriever. */ - rank_window_size?: integer - /** Unique identifier of the inference endpoint created using the inference API. */ - inference_id?: string - /** The text snippet used as the basis for similarity comparison */ - inference_text?: string - /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text */ - field?: string + /** The nested retriever which will produce the first-level results, that will later be used for reranking. */ + retriever: RetrieverContainer + /** This value determines how many documents we will consider from the nested retriever. */ + rank_window_size?: integer + /** Unique identifier of the inference endpoint created using the inference API. */ + inference_id?: string + /** The text snippet used as the basis for similarity comparison */ + inference_text?: string + /** The document field to be used for text similarity comparisons. This field should contain the text that will be evaluated against the inference_text */ + field?: string } export class RuleRetriever extends RetrieverBase { - /** The ruleset IDs containing the rules this retriever is evaluating against. */ - ruleset_ids: Id | Id[] - /** The match criteria that will determine if a rule in the provided rulesets should be applied. */ - match_criteria: UserDefinedValue - /** The retriever whose results rules should be applied to. */ - retriever: RetrieverContainer - /** This value determines the size of the individual result set. */ - rank_window_size?: integer + /** The ruleset IDs containing the rules this retriever is evaluating against. */ + ruleset_ids: Id | Id[] + /** The match criteria that will determine if a rule in the provided rulesets should be applied. */ + match_criteria: UserDefinedValue + /** The retriever whose results rules should be applied to. */ + retriever: RetrieverContainer + /** This value determines the size of the individual result set. */ + rank_window_size?: integer }