From 77bd964759c28b9b1d1988964d00edd2905c928c Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 13:28:34 +0000 Subject: [PATCH 01/10] sortby-query-param-and-sorting-strategy --- specs/composition/common/params/Composition.yml | 12 ++++++++++++ .../common/schemas/components/Composition.yml | 12 +++++++++++- 2 files changed, 23 insertions(+), 1 deletion(-) diff --git a/specs/composition/common/params/Composition.yml b/specs/composition/common/params/Composition.yml index 9ee7fee32b4..26dd7118bf3 100644 --- a/specs/composition/common/params/Composition.yml +++ b/specs/composition/common/params/Composition.yml @@ -108,3 +108,15 @@ enableABTest: default: true x-categories: - Advanced + +# ####################### +# ### Category SortBy ### +# ####################### + +sortBy: + type: string + description: | + Parameter targeting the `sortingStrategy` setting set in the Composition body. + default: '' + example: + "Price (asc)" diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index 8b0814c5934..4e70f387b33 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -14,7 +14,17 @@ composition: example: 'my lovely crafted composition that is used for X purpose' behavior: $ref: './CompositionBehavior.yml#/compositionBehavior' + sortingStrategy: + type: object + description: | + Sorting Label to indices. Up to 20 sorting strategies can be defined. + example: + { + "Price (asc)": "products-low-to-high", + "Price (desc)": "products-high-to-low", + } + required: - objectID - behavior - - name \ No newline at end of file + - name From db6e15c34d0f5c12ef78331181f306a67c9be7b1 Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 13:36:08 +0000 Subject: [PATCH 02/10] add tests --- .../requests/composition/putComposition.json | 48 +++++++++++++++++++ tests/CTS/requests/composition/search.json | 22 +++++++++ 2 files changed, 70 insertions(+) diff --git a/tests/CTS/requests/composition/putComposition.json b/tests/CTS/requests/composition/putComposition.json index 056f6eb1f55..de403e64127 100644 --- a/tests/CTS/requests/composition/putComposition.json +++ b/tests/CTS/requests/composition/putComposition.json @@ -361,5 +361,53 @@ } } } + }, + + { + "parameters": { + "compositionID": "my-compo", + "composition": { + "objectID": "my-compo", + "name": "my composition", + "sortingStrategy": { + "Price (asc)": "products-low-to-high", + "Price (desc)": "products-high-to-low" + }, + "behavior": { + "injection": { + "main": { + "source": { + "search": { + "index": "products" + } + } + } + } + } + } + }, + "request": { + "path": "/1/compositions/my-compo", + "method": "PUT", + "body": { + "objectID": "my-compo", + "name": "my composition", + "sortingStrategy": { + "Price (asc)": "products-low-to-high", + "Price (desc)": "products-high-to-low" + }, + "behavior": { + "injection": { + "main": { + "source": { + "search": { + "index": "products" + } + } + } + } + } + } + } } ] diff --git a/tests/CTS/requests/composition/search.json b/tests/CTS/requests/composition/search.json index a74b47f4067..d5b43d0cf74 100644 --- a/tests/CTS/requests/composition/search.json +++ b/tests/CTS/requests/composition/search.json @@ -79,5 +79,27 @@ } } } + }, + + { + "parameters": { + "compositionID": "foo", + "requestBody": { + "params": { + "query": "batman", + "sortBy": "Price (asc)" + } + } + }, + "request": { + "path": "/1/compositions/foo/run", + "method": "POST", + "body": { + "params": { + "query": "batman", + "sortBy": "Price (asc)" + } + } + } } ] From 9df65db980f0cdcf18fbf030211b66fd921c52fd Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 13:49:39 +0000 Subject: [PATCH 03/10] add to RunParams --- specs/composition/common/schemas/requestBodies/RunParams.yml | 2 ++ 1 file changed, 2 insertions(+) diff --git a/specs/composition/common/schemas/requestBodies/RunParams.yml b/specs/composition/common/schemas/requestBodies/RunParams.yml index 42e01f56730..8bd8722f8b2 100644 --- a/specs/composition/common/schemas/requestBodies/RunParams.yml +++ b/specs/composition/common/schemas/requestBodies/RunParams.yml @@ -61,3 +61,5 @@ params: $ref: '../../params/Composition.yml#/ruleContexts' userToken: $ref: '../../params/Search.yml#/userToken' + sortBy: + $ref: '../../params/Composition.yml#/sortBy' From ed06c32cd40cd8cf88ef5ff66fa12eecc5f97390 Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 14:03:16 +0000 Subject: [PATCH 04/10] improve description --- .../composition/common/params/Composition.yml | 10 ++++++++-- .../common/schemas/components/Composition.yml | 19 +++++++++++++------ 2 files changed, 21 insertions(+), 8 deletions(-) diff --git a/specs/composition/common/params/Composition.yml b/specs/composition/common/params/Composition.yml index 26dd7118bf3..6f2fc351dd0 100644 --- a/specs/composition/common/params/Composition.yml +++ b/specs/composition/common/params/Composition.yml @@ -116,7 +116,13 @@ enableABTest: sortBy: type: string description: | - Parameter targeting the `sortingStrategy` setting set in the Composition body. + Indicates which sorting strategy to apply for the request. + The value must match one of the labels defined in the "sortingStrategy" mapping. For example, "Price (asc)", see Upsert Composition. + At runtime, this label is used to look up the corresponding index or replica configured in "sortingStrategy", and the query is executed using that index’s in the main injection. + + In addition to "sortingStrategy", this parameter is also used to apply a matching Composition Rule that contains a condition defined to trigger on "sortBy", see Composition Rules. + + If no value is provided, no sorting strategy is applied. default: '' example: - "Price (asc)" + 'Price (asc)' diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index 4e70f387b33..bbcdcf1b909 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -17,13 +17,20 @@ composition: sortingStrategy: type: object description: | - Sorting Label to indices. Up to 20 sorting strategies can be defined. - example: - { - "Price (asc)": "products-low-to-high", - "Price (desc)": "products-high-to-low", - } + A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. + + Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected. + When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced + with the sorting strategy index it is mapped to. + Up to 20 sorting strategies can be defined. + maxItems: 20 + additionalProperties: + type: string + example: + 'Price (asc)': 'products-low-to-high' + 'Price (desc)': 'products-high-to-low' + required: - objectID - behavior From a49e490b4d7b3a5bd6058567e1bb192bd402d886 Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 15:21:25 +0000 Subject: [PATCH 05/10] try fix ruby CTS issue --- tests/CTS/requests/composition/putComposition.json | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/tests/CTS/requests/composition/putComposition.json b/tests/CTS/requests/composition/putComposition.json index de403e64127..d691cfe571e 100644 --- a/tests/CTS/requests/composition/putComposition.json +++ b/tests/CTS/requests/composition/putComposition.json @@ -370,8 +370,8 @@ "objectID": "my-compo", "name": "my composition", "sortingStrategy": { - "Price (asc)": "products-low-to-high", - "Price (desc)": "products-high-to-low" + "Price-asc": "products-low-to-high", + "Price-desc": "products-high-to-low" }, "behavior": { "injection": { @@ -393,8 +393,8 @@ "objectID": "my-compo", "name": "my composition", "sortingStrategy": { - "Price (asc)": "products-low-to-high", - "Price (desc)": "products-high-to-low" + "Price-asc": "products-low-to-high", + "Price-desc": "products-high-to-low" }, "behavior": { "injection": { From 1669888b23eedea0c1e7d691f4dd441df95c706c Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 15:39:45 +0000 Subject: [PATCH 06/10] move sortingStrategy definition to root --- .../common/schemas/components/Composition.yml | 33 ++++++++++--------- 1 file changed, 18 insertions(+), 15 deletions(-) diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index bbcdcf1b909..ed55833869d 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -15,23 +15,26 @@ composition: behavior: $ref: './CompositionBehavior.yml#/compositionBehavior' sortingStrategy: - type: object - description: | - A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. + $ref: '#/sortingStrategy' - Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected. - When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced - with the sorting strategy index it is mapped to. - - Up to 20 sorting strategies can be defined. - maxItems: 20 - additionalProperties: - type: string - example: - 'Price (asc)': 'products-low-to-high' - 'Price (desc)': 'products-high-to-low' - required: - objectID - behavior - name + +sortingStrategy: + type: object + description: | + A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. + + Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected. + When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced + with the sorting strategy index it is mapped to. + + Up to 20 sorting strategies can be defined. + maxItems: 20 + additionalProperties: + type: string + example: + 'Price (asc)': 'products-low-to-high' + 'Price (desc)': 'products-high-to-low' From fb8ca5f1e88263b3725ec9073fb0f6249669db4b Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 15:56:18 +0000 Subject: [PATCH 07/10] clarify sortingStrategy index relation --- specs/composition/common/schemas/components/Composition.yml | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index ed55833869d..1a7ef8ccb2c 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -25,9 +25,9 @@ composition: sortingStrategy: type: object description: | - A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. - + A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. The sorting indices MUST be related to the associated main targeted index in the composition. Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected. + When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced with the sorting strategy index it is mapped to. From 2b5280fa5de6f5233463da0c271b3db355523ed7 Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Thu, 27 Nov 2025 16:02:21 +0000 Subject: [PATCH 08/10] remove maxItems field --- specs/composition/common/schemas/components/Composition.yml | 1 - 1 file changed, 1 deletion(-) diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index 1a7ef8ccb2c..a0d2fc4c55a 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -32,7 +32,6 @@ sortingStrategy: with the sorting strategy index it is mapped to. Up to 20 sorting strategies can be defined. - maxItems: 20 additionalProperties: type: string example: From 81357959289d29381f27b8f15b11ee26479527ec Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Fri, 28 Nov 2025 10:09:02 +0000 Subject: [PATCH 09/10] sort alphabetically --- .../common/schemas/requestBodies/RunParams.yml | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/specs/composition/common/schemas/requestBodies/RunParams.yml b/specs/composition/common/schemas/requestBodies/RunParams.yml index 8bd8722f8b2..de773917171 100644 --- a/specs/composition/common/schemas/requestBodies/RunParams.yml +++ b/specs/composition/common/schemas/requestBodies/RunParams.yml @@ -53,13 +53,13 @@ params: $ref: '../../params/Search.yml#/page' query: $ref: '../../params/Search.yml#/query' - relevancyStrictness: - $ref: '../../params/Search.yml#/relevancyStrictness' queryLanguages: $ref: '../../params/Search.yml#/queryLanguages' + relevancyStrictness: + $ref: '../../params/Search.yml#/relevancyStrictness' ruleContexts: $ref: '../../params/Composition.yml#/ruleContexts' - userToken: - $ref: '../../params/Search.yml#/userToken' sortBy: $ref: '../../params/Composition.yml#/sortBy' + userToken: + $ref: '../../params/Search.yml#/userToken' From 09465c3070bebaf06026f9531bb2bc254951384c Mon Sep 17 00:00:00 2001 From: Ben Kalmus Date: Fri, 28 Nov 2025 11:36:00 +0000 Subject: [PATCH 10/10] comments --- specs/composition/common/params/Composition.yml | 4 ++-- specs/composition/common/schemas/components/Composition.yml | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/specs/composition/common/params/Composition.yml b/specs/composition/common/params/Composition.yml index 6f2fc351dd0..06f2b0ab491 100644 --- a/specs/composition/common/params/Composition.yml +++ b/specs/composition/common/params/Composition.yml @@ -118,11 +118,11 @@ sortBy: description: | Indicates which sorting strategy to apply for the request. The value must match one of the labels defined in the "sortingStrategy" mapping. For example, "Price (asc)", see Upsert Composition. - At runtime, this label is used to look up the corresponding index or replica configured in "sortingStrategy", and the query is executed using that index’s in the main injection. + At runtime, this label is used to look up the corresponding index or replica configured in "sortingStrategy", and the query is executed using that index instead of main's. In addition to "sortingStrategy", this parameter is also used to apply a matching Composition Rule that contains a condition defined to trigger on "sortBy", see Composition Rules. - If no value is provided, no sorting strategy is applied. + If no value is provided or an invalid value, no sorting strategy is applied. default: '' example: 'Price (asc)' diff --git a/specs/composition/common/schemas/components/Composition.yml b/specs/composition/common/schemas/components/Composition.yml index a0d2fc4c55a..2e48394b086 100644 --- a/specs/composition/common/schemas/components/Composition.yml +++ b/specs/composition/common/schemas/components/Composition.yml @@ -28,7 +28,7 @@ sortingStrategy: A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. The sorting indices MUST be related to the associated main targeted index in the composition. Each key is the label your frontend sends at runtime (for example, "Price (asc)"), and each value is the name of the index that should be queried when that label is selected. - When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main injection targeted index is replaced + When a request includes a "sortBy" parameter, the platform looks up the corresponding index in this mapping and uses it to execute the query. The main targeted index is replaced with the sorting strategy index it is mapped to. Up to 20 sorting strategies can be defined.