Skip to content
This repository was archived by the owner on Mar 21, 2024. It is now read-only.

Commit 8827a3a

Browse files
gmourierKerollmopsbidoubiwa
authored
Facet Search API (#246)
* Init specification * Adjust spec files to PR number * Fix content-type open-api * Remove fix content-type * Add the telemetry * Update text/0246-facet-search-api.md Co-authored-by: cvermand <[email protected]> * Update text/0034-telemetry-policies.md --------- Co-authored-by: Clément Renault <[email protected]> Co-authored-by: cvermand <[email protected]>
1 parent c08f67e commit 8827a3a

File tree

4 files changed

+360
-8
lines changed

4 files changed

+360
-8
lines changed

‎open-api.yaml‎

Lines changed: 113 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -176,6 +176,21 @@ components:
176176
_geoDistance:
177177
type: number
178178
description: 'Using _geoPoint({lat}, {lng}) built-in sort rule at search leads the engine to return a _geoDistance within the search results. This field represents the distance in meters of the document from the specified _geoPoint.'
179+
facetHit:
180+
type: object
181+
additionalProperties: true
182+
examples:
183+
- value: Romance
184+
count: 25
185+
description: FacetHit object represents a matched facet value for a facet search.
186+
properties:
187+
value:
188+
type: string
189+
description: The facet value being matched.
190+
additionalProperties: true
191+
count:
192+
type: integer
193+
description: The number of document containing the matched facet value.
179194
documentId:
180195
oneOf:
181196
- type: number
@@ -306,6 +321,27 @@ components:
306321
- hits
307322
- processingTimeMs
308323
- query
324+
facetSearchResponse:
325+
type: object
326+
additionalProperties: false
327+
title: ''
328+
properties:
329+
facetHits:
330+
type: array
331+
description: Array of facet hits
332+
items:
333+
$ref: '#/components/schemas/facetHit'
334+
facetQuery:
335+
type: string
336+
description: Facet query originating the response.
337+
example: ninja
338+
processingTimeMs:
339+
type: integer
340+
description: Processing time of the facet search query.
341+
required:
342+
- facetHits
343+
- facetQuery
344+
- processingTimeMs
309345
task:
310346
type: object
311347
description: |
@@ -762,7 +798,37 @@ components:
762798
attributesToHighlight:
763799
- overview
764800
showMatchesPosition: true
765-
wordsMatchingStrategy: all
801+
matchingStrategy: all
802+
facetSearchQuery:
803+
type: object
804+
additionalProperties: false
805+
properties:
806+
facetName:
807+
type: string
808+
required: true
809+
description: Query string.
810+
example: '"genres"'
811+
facetQuery:
812+
type: string
813+
description:
814+
default: '""'
815+
example: '"Horror"'
816+
q:
817+
type: string
818+
description: 'Additional search parameter. If additional search parameters are set, the method will return facet values that both: - Match the face query - Are contained in the records matching the additional search parameters'
819+
default: '""'
820+
example: '"Back to the future"'
821+
matchingStrategy:
822+
type: string
823+
description: 'Additional search parameter. If additional search parameters are set, the method will return facet values that both: - Match the face query - Are contained in the records matching the additional search parameters'
824+
default: 'last'
825+
filter:
826+
$ref: '#/components/schemas/filter'
827+
examples:
828+
Example:
829+
value:
830+
facetName: genres
831+
facetQuery: Romance
766832
error:
767833
title: error
768834
type: object
@@ -1315,11 +1381,13 @@ tags:
13151381
[Learn more about documents](https://docs.meilisearch.com/learn/core_concepts/documents.html).
13161382
- name: Search
13171383
description: |
1318-
Meilisearch exposes 3 routes to perform searches:
1384+
Meilisearch exposes 3 routes to perform document searches:
13191385
* A POST route: this is the preferred route when using API authentication, as it allows [preflight request](https://developer.mozilla.org/en-US/docs/Glossary/Preflight_request) caching and better performances.
13201386
* A GET route: the usage of this route is discouraged, unless you have good reason to do otherwise (specific caching abilities for example).
13211387
Other than the differences mentioned above, the two routes are strictly equivalent.
13221388
* A POST multi-search route allowing to perform multiple search queries in a single HTTP request.
1389+
Meilisearch exposes 1 route to perform facet searches:
1390+
* A POST facet-search route allowing to perform a facet search query on a facet in a single HTTP request.
13231391
- name: Tasks
13241392
description: |
13251393
The `tasks` route gives information about the progress of the [asynchronous operations](https://docs.meilisearch.com/learn/advanced/asynchronous_operations.html).
@@ -2182,6 +2250,48 @@ paths:
21822250
- $ref: '#/components/parameters/Content-Type'
21832251
parameters:
21842252
- $ref: '#/components/parameters/indexUid'
2253+
'/indexes/{indexUid}/facet-search':
2254+
post:
2255+
operationId: indexes.documents.facet.search
2256+
summary: Facet Search
2257+
description: |
2258+
Search for facet values matching a specific query for a facet. When many values exist for a facet, users need to be able to discover non-show values they can select in order to refine their faceted search.
2259+
tags:
2260+
- Search
2261+
- Facet
2262+
security:
2263+
- apiKey: []
2264+
requestBody:
2265+
required: true
2266+
content:
2267+
application/json:
2268+
schema:
2269+
$ref: '#/components/schemas/facetSearchQuery'
2270+
responses:
2271+
'200':
2272+
description: Ok
2273+
content:
2274+
application/json:
2275+
schema:
2276+
$ref: '#/components/schemas/facetSearchResponse'
2277+
examples:
2278+
Example:
2279+
value:
2280+
facetHits:
2281+
- value: Romance
2282+
count: 25
2283+
- value: Romantic
2284+
count: 3
2285+
facetQuery: Rom
2286+
processingTimeMs: 0
2287+
'401':
2288+
$ref: '#/components/responses/401'
2289+
'404':
2290+
description: Not Found
2291+
parameters:
2292+
- $ref: '#/components/parameters/Content-Type'
2293+
parameters:
2294+
- $ref: '#/components/parameters/indexUid'
21852295
'/indexes/{indexUid}/settings':
21862296
get:
21872297
operationId: indexes.settings.get
@@ -3430,7 +3540,7 @@ paths:
34303540
attributesToHighlight:
34313541
- overview
34323542
showMatchesPosition: true
3433-
wordsMatchingStrategy: all
3543+
matchingStrategy: all
34343544
responses:
34353545
'200':
34363546
description: Ok

‎text/0034-telemetry-policies.md‎

Lines changed: 23 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -40,6 +40,7 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
4040
| Launched | Occurs when MeiliSearch is launched the first time. |
4141
| Documents Searched POST | Aggregated event on all received requests via the `POST` - `indexes/:indexUid/search` route during one hour or until a batch size reaches `500Kb`. |
4242
| Documents Searched GET | Aggregated event on all received requests via the `GET` - `/indexes/:indexUid/search` route during one hour or until a batch size reaches `500Kb`. |
43+
| Facet Searched POST | Aggregated event on all received requests via the `POST` - `/indexes/:indexUid/facet-search` route during one hour or until a batch size reaches `500Kb`. |
4344
| Documents Searched by Multi-Search POST | Aggregated event on all received requests via the `POST`- `/multi-search` route during one hour or until a batch size reaches `500Kb`. |
4445
| Documents Added | Aggregated event on all received requests via the `POST` - `/indexes/:indexUid/documents` route during one hour or until a batch size reaches `500Kb`. |
4546
| Documents Updated | Aggregated event on all received requests via the `PUT` - `/indexes/:indexUid/documents` route during one hour or until a batch size reaches `500Kb`. |
@@ -111,11 +112,11 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
111112
| `stats.database_size` | Database size. Expressed in `Bytes` | 2621440 | Every hour |
112113
| `stats.indexes_number` | Number of indexes | 2 | Every hour |
113114
| `start_since_days` | Number of days since instance was launched | 365 | Every hour |
114-
| `user_agent` | User-agent header encountered during one or more API calls | ["Meilisearch Ruby (v2.1)", "Ruby (3.0)"] | `Documents Searched POST`, `Documents Searched GET`, `Index Created`, `Index Updated`, `Documents Added`, `Documents Updated`, `Documents Deleted`, `Settings Updated`, `Ranking Rules Updated`, `SortableAttributes Updated`, `FilterableAttributes Updated`, `SearchableAttributes Updated`, `TypoTolerance Updated`, `Pagination Updated`, `Faceting Updated`, `DistinctAttribute Updated`, `DisplayedAttributes Updated`, `StopWords Updated`, `Synonyms Updated`, `Dump Created`, `Tasks Seen`, `Stats Seen`, `Health Seen`, `Version Seen`, `Documents Searched by Multi-Search POST` |
115-
| `requests.99th_response_time` | Highest latency from among the fastest 99% of successful search requests | 57ms | `Documents Searched POST`, `Documents Searched GET`|
116-
| `requests.total_succeeded` | Total number of successful requests in this batch | 3456 | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` |
117-
| `requests.total_failed` | Total number of failed requests in this batch | 24 | `Documents Searched POST`, `Documents Searched GET`, `Documents Searched by Multi-Search POST` |
118-
| `requests.total_received` | Total number of received requests in this batch | 3480 | `Documents Searched POST`, `Documents Searched GET`, `Documents Deleted`, `Documents Fetched GET`, `Documents Fetched POST`, `Health Seen`, `Tasks Seen`, `Documents Searched by Multi-Search POST` |
115+
| `user_agent` | User-agent header encountered during one or more API calls | ["Meilisearch Ruby (v2.1)", "Ruby (3.0)"] | `Documents Searched POST`, `Documents Searched GET`, `Index Created`, `Index Updated`, `Documents Added`, `Documents Updated`, `Documents Deleted`, `Settings Updated`, `Ranking Rules Updated`, `SortableAttributes Updated`, `FilterableAttributes Updated`, `SearchableAttributes Updated`, `TypoTolerance Updated`, `Pagination Updated`, `Faceting Updated`, `DistinctAttribute Updated`, `DisplayedAttributes Updated`, `StopWords Updated`, `Synonyms Updated`, `Dump Created`, `Tasks Seen`, `Stats Seen`, `Health Seen`, `Version Seen`, `Documents Searched by Multi-Search POST`, `Facet Searched POST` |
116+
| `requests.99th_response_time` | Highest latency from among the fastest 99% of successful search requests | 57ms | `Documents Searched POST`, `Documents Searched GET`, `Facet Searched POST`|
117+
| `requests.total_succeeded` | Total number of successful requests in this batch | 3456 | `Documents Searched POST`, `Documents Searched GET`, `Facet Searched POST`, `Documents Searched by Multi-Search POST` |
118+
| `requests.total_failed` | Total number of failed requests in this batch | 24 | `Documents Searched POST`, `Documents Searched GET`, `Facet Searched POST`, `Documents Searched by Multi-Search POST` |
119+
| `requests.total_received` | Total number of received requests in this batch | 3480 | `Documents Searched POST`, `Documents Searched GET`, `Facet Searched POST`, `Documents Deleted`, `Documents Fetched GET`, `Documents Fetched POST`, `Health Seen`, `Tasks Seen`, `Documents Searched by Multi-Search POST` |
119120
| `sort.with_geoPoint` | `true` if the sort rule `_geoPoint` was used in this batch, otherwise `false` | true | `Documents Searched POST`, `Documents Searched GET` |
120121
| `sort.avg_criteria_number` | Average number of sort criteria among all requests containing the `sort` parameter in this batch | 2 | `Documents Searched POST`, `Documents Searched GET` |
121122
| `filter.with_geoRadius` | `true` if the filter rule `_geoRadius` was used in this batch, otherwise `false` | false | `Documents Searched POST`, `Documents Searched GET` |
@@ -186,6 +187,8 @@ The collected data is sent to [Segment](https://segment.com/). Segment is a plat
186187
| `per_batch` | `true` if `POST /indexes/:indexUid/documents/delete-batch` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` |
187188
| `per_filter`| `true` if `POST /indexes/:indexUid/documents/delete` endpoint was used in this batch, otherwise `false` | false | `Documents Fetched GET`, `Documents Fetched POST`, `Documents Deleted` |
188189
| `clear_all` | `true` if `DELETE /indexes/:indexUid/documents` endpoint was used in this batch, otherwise `false` | false | `Documents Deleted` |
190+
| `facets.total_distinct_facet_count` | The total number of distinct facets queried for the aggregated event | `3` | `Facet Searched POST` |
191+
| `facets.additional_search_parameters_provided` | Were additional search parameters provided for the aggregated event | `true` | `Facet Searched POST` |
189192

190193
----
191194

@@ -316,6 +319,21 @@ This property allows us to gather essential information to better understand on
316319
| facets.avg_facets_number | The average number of facets among all the requests containing the `facets` parameter in the aggregated event. `"facets": []` equals to `0` while not sending `facets` does not influence the average in the aggregated event. | `10` |
317320
| matching_strategy.most_used_strategy | Most used word matching strategy among all search requests in the aggregated event. `last` / `all` | `last` |
318321

322+
---
323+
#### `Facet Searched POST`
324+
325+
> The Facet Searched event is sent once an hour or when a batch reaches the maximum size of `500kb`. The event's properties are averaged over all requests on `POST` - `/indexes/:indexUid/facet-search`.
326+
327+
| Property name | Description | Example |
328+
|---------------|-------------|---------|
329+
| user_agent | Represents all the user-agents encountered on this endpoint in the aggregated event.| `["Meilisearch Ruby (v2.1)", "Ruby (3.0)"]` |
330+
| requests.99th_response_time | Highest latency from among the fastest 99% of successful search requests. | `57ms` |
331+
| requests.total_succeeded | The total number of succeeded search requests in the aggregated event. | `3456` |
332+
| requests.total_failed | The total number of failed search requests in the aggregated event. | `24` |
333+
| requests.total_received | The total number of received search requests in the aggregated event. | `3480` |
334+
| facets.total_distinct_facet_count | The total number of distinct facets queried for the aggregated event. | `3` |
335+
| facets.additional_search_parameters_provided | Were additional search parameters provided for the aggregated event. | `true` |
336+
319337
---
320338

321339
#### `Documents Searched by Multi-Search POST`

‎text/0061-error-format-and-definitions.md‎

Lines changed: 74 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1810,6 +1810,80 @@ HTTP Code: `400 Bad Request`
18101810

18111811
---
18121812

1813+
## missing_facet_search_facet_name
1814+
1815+
`Synchronous`
1816+
1817+
### Context
1818+
1819+
This error occurs if `facetName` isn't specified when making a facet search call.
1820+
1821+
### Error Definition
1822+
1823+
HTTP Code: `400 Bad Request`
1824+
1825+
```json
1826+
{
1827+
"message": "`:deserr_helper`",
1828+
"code": "missing_facet_search_facet_name",
1829+
"type": "invalid_request",
1830+
"link": "https://docs.meilisearch.com/errors#missing_facet_search_facet_name"
1831+
}
1832+
```
1833+
1834+
---
1835+
1836+
## invalid_facet_search_facet_name
1837+
1838+
`Synchronous`
1839+
1840+
### Context
1841+
1842+
This errors occurs when the provided value for `facetName`:
1843+
1844+
- Is not a string
1845+
- Is not defined in the `filterableAttributes` index setting
1846+
1847+
### Error Definition
1848+
1849+
HTTP Code: `400 Bad Request`
1850+
1851+
```json
1852+
{
1853+
"message": "`:deserr_helper`",
1854+
"code": "invalid_facet_search_facet_name",
1855+
"type": "invalid_request",
1856+
"link": "https://docs.meilisearch.com/errors#invalid_facet_search_facet_name"
1857+
}
1858+
```
1859+
1860+
---
1861+
1862+
## invalid_facet_search_facet_query
1863+
1864+
`Synchronous`
1865+
1866+
### Context
1867+
1868+
This errors occurs when the provided value for `facetQuery`:
1869+
1870+
- Is not a string or null
1871+
1872+
### Error Definition
1873+
1874+
HTTP Code: `400 Bad Request`
1875+
1876+
```json
1877+
{
1878+
"message": "`:deserr_helper`",
1879+
"code": "invalid_facet_search_facet_query",
1880+
"type": "invalid_request",
1881+
"link": "https://docs.meilisearch.com/errors#invalid_facet_search_facet_query"
1882+
}
1883+
```
1884+
1885+
---
1886+
18131887
## invalid_document_geo_field
18141888

18151889
`Asynchronous`

0 commit comments

Comments
 (0)