Skip to content

Commit 0a3cbbb

Browse files
authored
feat(specs): add per-feed params to Composition run request (#7199)
1 parent f2a1ffb commit 0a3cbbb

7 files changed

Lines changed: 228 additions & 5 deletions

File tree

‎specs/composition/common/params/Composition.yml‎

Lines changed: 5 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -137,5 +137,10 @@ sortBy:
137137
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.
138138
139139
If no value is provided or an invalid value, no sorting strategy is applied.
140+
141+
For `multifeed` compositions, every feed inherits the root "sortBy" unless the feed sets its own "sortBy" in `feeds.<id>.params`.
142+
An empty string disables sorting for that feed.
143+
The response reports an invalid value in the `errors` field. This includes a value whose index is unrelated to the feed's indices.
144+
Composition Rules still match on the root "sortBy".
140145
default: ''
141146
example: 'Price (asc)'

‎specs/composition/common/schemas/components/Composition.yml‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -25,7 +25,7 @@ composition:
2525
sortingStrategy:
2626
type: object
2727
description: |
28-
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.
28+
A mapping of sorting labels to the indices (or replicas) that implement those sorting rules. When the composition is run, the API ignores a sorting index that is unrelated to the targeted indices. The response reports it in the `errors` field.
2929
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.
3030
3131
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

‎specs/composition/common/schemas/requestBodies/RunParams.yml‎

Lines changed: 98 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -64,6 +64,104 @@ params:
6464
userToken:
6565
$ref: '../../params/Search.yml#/userToken'
6666

67+
feeds:
68+
title: Run composition feeds as object
69+
type: object
70+
description: |
71+
Per-feed parameters for `multifeed` compositions. Each key is a feed ID.
72+
73+
Feed `params` take precedence over the root `params`.
74+
A feed inherits every root key it doesn't set.
75+
A feed value replaces the root value instead of combining with it.
76+
This applies to every key, including `filters`, `facetFilters`, `optionalFilters`, and `analyticsTags`.
77+
For example, `filters` must repeat the common values.
78+
An empty value such as `filters: ""` discards the root value.
79+
80+
The API validates feed `params` like the root `params`.
81+
An unsupported parameter returns a 400 error.
82+
83+
A feed ID may not exist in the composition (for example, because a rule removed it).
84+
The response reports it in the `errors` field but request still succeeds.
85+
86+
Rules match once per request, against the root `params` only.
87+
additionalProperties:
88+
title: feedRequest
89+
type: object
90+
additionalProperties: false
91+
properties:
92+
params:
93+
$ref: '#/feedParams'
94+
example:
95+
organic:
96+
params:
97+
filters: 'category:shoes'
98+
hitsPerPage: 20
99+
banner:
100+
params:
101+
hitsPerPage: 2
102+
sortBy: ''
103+
104+
feedParams:
105+
title: Run composition feed parameters as object
106+
description: Parameters for a single feed. These match the root `params` minus `injectedItems`, `getRankingInfo`, and `enableABTest`.
107+
type: object
108+
additionalProperties: false
109+
properties:
110+
analytics:
111+
$ref: '../../params/Search.yml#/analytics'
112+
analyticsTags:
113+
$ref: '../../params/Search.yml#/analyticsTags'
114+
aroundLatLng:
115+
$ref: '../../params/Search.yml#/aroundLatLng'
116+
aroundLatLngViaIP:
117+
$ref: '../../params/Search.yml#/aroundLatLngViaIP'
118+
aroundRadius:
119+
$ref: '../../params/Search.yml#/aroundRadius'
120+
aroundPrecision:
121+
$ref: '../../params/Search.yml#/aroundPrecision'
122+
clickAnalytics:
123+
$ref: '../../params/Search.yml#/clickAnalytics'
124+
enablePersonalization:
125+
$ref: '../../params/Search.yml#/enablePersonalization'
126+
enableReRanking:
127+
$ref: '../../params/Search.yml#/enableReRanking'
128+
enableRules:
129+
$ref: '../../params/Composition.yml#/enableRules'
130+
facetFilters:
131+
$ref: '../../params/Search.yml#/facetFilters'
132+
facets:
133+
$ref: '../../params/Composition.yml#/facets'
134+
filters:
135+
$ref: '../../params/Search.yml#/filters'
136+
hitsPerPage:
137+
$ref: '../../params/Search.yml#/hitsPerPage'
138+
insideBoundingBox:
139+
$ref: '../../params/Search.yml#/insideBoundingBox'
140+
insidePolygon:
141+
$ref: '../../params/Search.yml#/insidePolygon'
142+
minimumAroundRadius:
143+
$ref: '../../params/Search.yml#/minimumAroundRadius'
144+
naturalLanguages:
145+
$ref: '../../params/Search.yml#/naturalLanguages'
146+
numericFilters:
147+
$ref: '../../params/Search.yml#/numericFilters'
148+
optionalFilters:
149+
$ref: '../../params/Search.yml#/optionalFilters'
150+
page:
151+
$ref: '../../params/Search.yml#/page'
152+
query:
153+
$ref: '../../params/Search.yml#/query'
154+
queryLanguages:
155+
$ref: '../../params/Search.yml#/queryLanguages'
156+
relevancyStrictness:
157+
$ref: '../../params/Search.yml#/relevancyStrictness'
158+
ruleContexts:
159+
$ref: '../../params/Composition.yml#/ruleContexts'
160+
sortBy:
161+
$ref: '../../params/Composition.yml#/sortBy'
162+
userToken:
163+
$ref: '../../params/Search.yml#/userToken'
164+
67165
externalProvider:
68166
title: Run composition external provider parameters as object
69167
type: object

‎specs/composition/paths/compositions/updateSortingStrategy.yml‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -8,10 +8,9 @@ post:
88
description: |
99
Updates the "sortingStrategy" field of an existing composition.
1010
This endpoint lets you create a new sorting strategy mapping or replace the configured one.
11-
The provided sorting indices must be associated indices or replicas of the main targeted index.
12-
13-
This endpoint can't validate whether the sort index is related to the composition's main index.
14-
Validation fails at runtime if the index you updated isn't related.
11+
This endpoint only validates that the sorting indices exist.
12+
At runtime, the API ignores a sorting index that is unrelated to the targeted indices.
13+
The response reports it in the `errors` field.
1514
1615
The update is applied to the specified composition within the current Algolia application and returns a taskID that can be used to track the operation’s completion.
1716
parameters:

‎specs/composition/paths/search/search.yml‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -25,6 +25,8 @@ post:
2525
$ref: '../../common/schemas/requestBodies/RunParams.yml#/feedsOrder'
2626
externalProvider:
2727
$ref: '../../common/schemas/requestBodies/RunParams.yml#/externalProvider'
28+
feeds:
29+
$ref: '../../common/schemas/requestBodies/RunParams.yml#/feeds'
2830
responses:
2931
'200':
3032
description: OK

‎tests/CTS/requests/composition/search.json‎

Lines changed: 57 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -156,5 +156,62 @@
156156
}
157157
}
158158
}
159+
},
160+
{
161+
"parameters": {
162+
"compositionID": "foo",
163+
"requestBody": {
164+
"params": {
165+
"query": "shoes",
166+
"filters": "brand:acme"
167+
},
168+
"feeds": {
169+
"organic": {
170+
"params": {
171+
"filters": "brand:acme AND inStock:true",
172+
"sortBy": "Price (asc)"
173+
}
174+
},
175+
"banner": {
176+
"params": {
177+
"query": "shoes sale",
178+
"filters": ""
179+
}
180+
}
181+
},
182+
"feedsOrder": [
183+
"banner",
184+
"organic"
185+
]
186+
}
187+
},
188+
"request": {
189+
"path": "/1/compositions/foo/run",
190+
"method": "POST",
191+
"body": {
192+
"params": {
193+
"query": "shoes",
194+
"filters": "brand:acme"
195+
},
196+
"feeds": {
197+
"organic": {
198+
"params": {
199+
"filters": "brand:acme AND inStock:true",
200+
"sortBy": "Price (asc)"
201+
}
202+
},
203+
"banner": {
204+
"params": {
205+
"query": "shoes sale",
206+
"filters": ""
207+
}
208+
}
209+
},
210+
"feedsOrder": [
211+
"banner",
212+
"organic"
213+
]
214+
}
215+
}
159216
}
160217
]

‎tests/output/go/tests/manual/composition_oneof_test.go‎

Lines changed: 62 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -87,6 +87,68 @@ func TestInjectedItemSource_RoundTripExternalSource(t *testing.T) {
8787
require.JSONEq(t, input, string(output))
8888
}
8989

90+
func TestRequestBody_RoundTripFeeds(t *testing.T) {
91+
t.Parallel()
92+
93+
input := `{
94+
"params": {
95+
"query": "shoes",
96+
"filters": "brand:acme"
97+
},
98+
"feeds": {
99+
"organic": {
100+
"params": {
101+
"filters": "brand:acme AND inStock:true",
102+
"sortBy": "Price (asc)"
103+
}
104+
},
105+
"banner": {
106+
"params": {
107+
"query": "shoes sale",
108+
"filters": "",
109+
"sortBy": ""
110+
}
111+
}
112+
},
113+
"feedsOrder": ["banner", "organic"]
114+
}`
115+
116+
var body composition.RequestBody
117+
118+
err := json.Unmarshal([]byte(input), &body)
119+
require.NoError(t, err)
120+
121+
output, marshalErr := json.Marshal(&body)
122+
123+
require.NoError(t, marshalErr)
124+
require.NotNil(t, body.Params)
125+
require.NotNil(t, body.Params.Query)
126+
require.Equal(t, "shoes", *body.Params.Query)
127+
require.Equal(t, []string{"banner", "organic"}, body.FeedsOrder)
128+
require.NotNil(t, body.Feeds)
129+
130+
feeds := *body.Feeds
131+
organic := feeds["organic"].Params
132+
banner := feeds["banner"].Params
133+
134+
require.NotNil(t, organic)
135+
require.Nil(t, organic.Query)
136+
require.NotNil(t, organic.Filters)
137+
require.NotNil(t, organic.SortBy)
138+
require.Equal(t, "brand:acme AND inStock:true", *organic.Filters)
139+
require.Equal(t, "Price (asc)", *organic.SortBy)
140+
141+
require.NotNil(t, banner)
142+
require.NotNil(t, banner.Query)
143+
require.NotNil(t, banner.Filters)
144+
require.NotNil(t, banner.SortBy)
145+
require.Equal(t, "shoes sale", *banner.Query)
146+
require.Empty(t, *banner.Filters)
147+
require.Empty(t, *banner.SortBy)
148+
149+
require.JSONEq(t, input, string(output))
150+
}
151+
90152
func TestInjectionMainSource_UnmarshalSearchSource(t *testing.T) {
91153
t.Parallel()
92154

0 commit comments

Comments
 (0)