From 75f242db439ee40fb39566cf4dd8b202fc84db92 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 2 Oct 2024 17:52:53 +0200 Subject: [PATCH 1/4] add facetsByIndex and new federation option to /multi-search --- reference/api/multi_search.mdx | 43 ++++++++++++++++++++++++++++++++++ 1 file changed, 43 insertions(+) diff --git a/reference/api/multi_search.mdx b/reference/api/multi_search.mdx index f7565e363..4f37f5189 100644 --- a/reference/api/multi_search.mdx +++ b/reference/api/multi_search.mdx @@ -34,9 +34,50 @@ Use `federation` to receive a single list with all search results from all speci | :--------------------------------------------------------------------------- | :--------------- | :------------ | :-------------------------------------------------- | | **[`offset`](/reference/api/search#offset)** | Integer | `0` | Number of documents to skip | | **[`limit`](/reference/api/search#limit)** | Integer | `20` | Maximum number of documents returned | +| **[`facetsByIndex`](/#facetsbyindex)** | Object of arrays | `null` | Display facet information for the specified facets | If `federation` is missing or `null`, Meilisearch returns a list of multiple search result objects, with each item from the list corresponding to a search query in the request. +##### `facetsByIndex` + +`facetsByIndex` must be an object. Its keys must correspond to indexes in your in Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list: + +```json +"facetsByIndex": { + "INDEX_A": ["ATTRIBUTE_X", "ATTRIBUTE_Y"], + "INDEX_B": ["ATTRIBUTE_Z"] +} +``` + +When you specify `facetsByIndex`, multi-search responses include an extra `facetsByIndex` field. The response's `facetsByIndex` is an object with one field for each queried index: + +```json +"facetsByIndex": { + "INDEX_A": { + "distribution": { + "ATTRIBUTE_X": { + "KEY": 10, + "KEY": 5, + … + }, + "ATTRIBUTE_Y": { + "KEY": 1, + … + } + }, + "stats": { + "KEY": { + "min": 0, + "max": 1 + } + } + }, + "INDEX_B": { + … + } +} +``` + ##### Merge algorithm for federated searches Federated search's merged results are returned in decreasing ranking score. To obtain the final list of results, Meilisearch compares with the following procedure: @@ -99,6 +140,8 @@ These options are not compatible with federated searches. `federationOptions` must be an object. It accepts the following parameters: - `weight`: serves as a multiplicative factor to ranking scores of search results in this specific query. If < `1.0`, the hits from this query are less likely to appear in the final results list. If > `1.0`, the hits from this query are more likely to appear in the final results list. Must be a positive floating-point number. Defaults to `1.0` +- `mergeFacets`: when `mergeFacets` is present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of `facetsByIndex`, the response includes two extra fields: `facetDistribution` and `facetStats`. `mergeFacets` must be an object, which may optionally contain the following fields: + - `maxValuesPerFacet`: must be an integer. When specified, indicates the maximum number of returned values for a single facet. If not specified, Meilisearch uses the value assigned to the `maxValuesPerFacet` index setting ### Response From aeaf54c1d6954fcfd4e85cd760fb229fb4e463da Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Thu, 3 Oct 2024 16:25:13 +0200 Subject: [PATCH 2/4] fix inaccuracies --- reference/api/multi_search.mdx | 72 ++++++++++++++++++++++++---------- 1 file changed, 51 insertions(+), 21 deletions(-) diff --git a/reference/api/multi_search.mdx b/reference/api/multi_search.mdx index 4f37f5189..6978a5ab0 100644 --- a/reference/api/multi_search.mdx +++ b/reference/api/multi_search.mdx @@ -34,13 +34,14 @@ Use `federation` to receive a single list with all search results from all speci | :--------------------------------------------------------------------------- | :--------------- | :------------ | :-------------------------------------------------- | | **[`offset`](/reference/api/search#offset)** | Integer | `0` | Number of documents to skip | | **[`limit`](/reference/api/search#limit)** | Integer | `20` | Maximum number of documents returned | -| **[`facetsByIndex`](/#facetsbyindex)** | Object of arrays | `null` | Display facet information for the specified facets | +| **[`facetsByIndex`](/#facetsbyindex)** | Object of arrays | `null` | Display facet information for the specified indexes | +| **[`mergeFacets`](/#mergefacets)** | Object | `null` | Display facet information for the specified indexes | If `federation` is missing or `null`, Meilisearch returns a list of multiple search result objects, with each item from the list corresponding to a search query in the request. ##### `facetsByIndex` -`facetsByIndex` must be an object. Its keys must correspond to indexes in your in Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list: +`facetsByIndex` must be an object. Its keys must correspond to indexes in your Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list: ```json "facetsByIndex": { @@ -52,28 +53,59 @@ If `federation` is missing or `null`, Meilisearch returns a list of multiple sea When you specify `facetsByIndex`, multi-search responses include an extra `facetsByIndex` field. The response's `facetsByIndex` is an object with one field for each queried index: ```json -"facetsByIndex": { - "INDEX_A": { - "distribution": { - "ATTRIBUTE_X": { - "KEY": 10, - "KEY": 5, - … +{ + "hits" [ … ], + … + "facetsByIndex": { + "INDEX_A": { + "distribution": { + "ATTRIBUTE_X": { + "KEY": , + "KEY": , + … + }, + "ATTRIBUTE_Y": { + "KEY": , + … + } }, - "ATTRIBUTE_Y": { - "KEY": 1, - … + "stats": { + "KEY": { + "min": , + "max": + } } }, - "stats": { - "KEY": { - "min": 0, - "max": 1 - } + "INDEX_B": { + … + } + } +} +``` + +##### `mergeFacets` + +`mergeFacets` must be an object and may contain the following fields: + +- `maxValuesPerFacet`: must be an integer. When specified, indicates the maximum number of returned values for a single facet. Defaults to the value assigned to [the `maxValuesPerFacet` index setting](/reference/api/settings#faceting) + +When both `facetsByIndex` and `mergeFacets` are present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of `facetsByIndex`, the response includes two extra fields: `facetDistribution` and `facetStats`: + +```json +{ + "hits": [ … ], + … + "facetFederation": { + "ATTRIBUTE": { + "VALUE": , + "VALUE": } }, - "INDEX_B": { - … + "facetStats": { + "ATTRIBUTE": { + "min": , + "max": + } } } ``` @@ -140,8 +172,6 @@ These options are not compatible with federated searches. `federationOptions` must be an object. It accepts the following parameters: - `weight`: serves as a multiplicative factor to ranking scores of search results in this specific query. If < `1.0`, the hits from this query are less likely to appear in the final results list. If > `1.0`, the hits from this query are more likely to appear in the final results list. Must be a positive floating-point number. Defaults to `1.0` -- `mergeFacets`: when `mergeFacets` is present and not null, facet information included in multi-search responses is merged across all queried indexes. Instead of `facetsByIndex`, the response includes two extra fields: `facetDistribution` and `facetStats`. `mergeFacets` must be an object, which may optionally contain the following fields: - - `maxValuesPerFacet`: must be an integer. When specified, indicates the maximum number of returned values for a single facet. If not specified, Meilisearch uses the value assigned to the `maxValuesPerFacet` index setting ### Response From 921aa37bd938ff3e9ab0ef44f3e2dae9a9d926aa Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Mon, 7 Oct 2024 18:41:18 +0200 Subject: [PATCH 3/4] add new error codes --- reference/errors/error_codes.mdx | 28 ++++++++++++++++++++++++++++ 1 file changed, 28 insertions(+) diff --git a/reference/errors/error_codes.mdx b/reference/errors/error_codes.mdx index ae5076c9f..cf3cb53ee 100644 --- a/reference/errors/error_codes.mdx +++ b/reference/errors/error_codes.mdx @@ -213,6 +213,34 @@ A multi-search query contains a negative value for `federated.weight`. Two or more queries in a multi-search request have incompatible results. +## `invalid_multi_search_facets` + +`federation.facetsByIndex.` contains a value that is not in the filterable attributes list. + +## `invalid_multi_search_sort_facet_values_by` + +`federation.mergeFacets.sortFacetValuesBy` is not a string or doesn’t have one of the allowed values. + +## `invalid_multi_search_query_facets` + +A query in the queries array contains `facets` when federation is present and non-`null`. + +## `invalid_multi_search_merge_facets` + +`federation.mergeFacets` is not an object or contains unexpected fields. + +## `invalid_multi_search_max_values_per_facet` + +`federation.mergeFacets.maxValuesPerFacet` is not a positive integer. + +## `invalid_multi_search_facet_order` + +Two or more indexes have a different `faceting.sortFacetValuesBy` for the same requested facet. + +## `invalid_multi_search_facets_by_index` + +`facetsByIndex` is not an object or contains unknown fields. + ## `invalid_search_attributes_to_crop` The [`attributesToCrop`](/reference/api/search#attributes-to-crop) parameter is invalid. It should be an array of strings, a string, or set to `null`. From 7682b62365cdb78792630331a471b7f1052d2c05 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Tue, 8 Oct 2024 12:30:26 +0200 Subject: [PATCH 4/4] Update reference/api/multi_search.mdx Co-authored-by: Louis Dureuil --- reference/api/multi_search.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/reference/api/multi_search.mdx b/reference/api/multi_search.mdx index 6978a5ab0..a5731c48f 100644 --- a/reference/api/multi_search.mdx +++ b/reference/api/multi_search.mdx @@ -41,7 +41,7 @@ If `federation` is missing or `null`, Meilisearch returns a list of multiple sea ##### `facetsByIndex` -`facetsByIndex` must be an object. Its keys must correspond to indexes in your Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list: +`facetsByIndex` must be an object. Its keys must correspond to indexes in your Meilisearch project. Each key must be associated with an array of attributes in the filterable attributes list of that index: ```json "facetsByIndex": {