From 75f242db439ee40fb39566cf4dd8b202fc84db92 Mon Sep 17 00:00:00 2001 From: gui machiavelli Date: Wed, 2 Oct 2024 17:52:53 +0200 Subject: [PATCH 1/2] 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/2] 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