diff --git a/package.json b/package.json
index e1c0a74aa5..020cfff872 100644
--- a/package.json
+++ b/package.json
@@ -24,7 +24,7 @@
"scripts:test": "yarn workspace scripts test",
"specs:fix": "eslint --ext=yml specs/$0 --fix",
"specs:lint": "eslint --ext=yml specs/$0",
- "website": "yarn cli build specs all -s && cd website && yarn start",
+ "website": "yarn cli build specs all -d -s && cd website && yarn start",
"website:build": "bash scripts/website/build.sh"
},
"devDependencies": {
diff --git a/specs/common/parameters.yml b/specs/common/parameters.yml
index d23b99b8f7..3ab64d7a28 100644
--- a/specs/common/parameters.yml
+++ b/specs/common/parameters.yml
@@ -2,16 +2,16 @@
IndexName:
name: indexName
in: path
- description: Index on which to perform the request.
+ description: Name of the index on which to perform the operation.
required: true
schema:
type: string
- example: myIndexName
+ example: YourIndexName
ObjectID:
name: objectID
in: path
- description: Unique record (object) identifier.
+ description: Unique record identifier.
required: true
schema:
type: string
@@ -21,7 +21,7 @@ ObjectID:
Index:
in: query
name: index
- description: Index name to target.
+ description: Index name.
required: true
schema:
type: string
@@ -30,33 +30,34 @@ Index:
StartDate:
in: query
name: startDate
- description: Start date (a string in the format `YYYY-MM-DD`) of the period to analyze.
+ description: Start date (`YYYY-MM-DD`) of the period to analyze.
schema:
type: string
+ format: date
example: 2022-09-19
- pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
EndDate:
in: query
name: endDate
- description: End date (a string in the format `YYYY-MM-DD`) of the period to analyze.
+ description: End date (`YYYY-MM-DD`) of the period to analyze.
schema:
type: string
+ format: date
example: 2023-01-21
- pattern: ^\d{4}-(0[1-9]|1[0-2])-(0[1-9]|[12][0-9]|3[01])$
ForwardToReplicas:
in: query
name: forwardToReplicas
- description: Indicates whether changed index settings are forwarded to the replica indices.
+ description: Whether changes are applied to replica indices.
schema:
type: boolean
Page:
in: query
name: page
- description: >
- Returns the requested page number. The page size is determined by the `hitsPerPage` parameter. You can see the number of available pages in the `nbPages` response attribute. When `page` is null, the API response is not paginated.
+ description: |
+ Requested page of the API response.
+ If `null`, the API response is not paginated.
schema:
type: integer
minimum: 0
@@ -66,8 +67,9 @@ Page:
PageDefault0:
in: query
name: page
- description: >
- Returns the requested page number (the first page is 0). Page size is set by `hitsPerPage`. When null, there's no pagination.
+ description: |
+ Requested page of the API response.
+ If `null`, the API response is not paginated.
schema:
type: integer
nullable: true
@@ -77,7 +79,7 @@ PageDefault0:
HitsPerPage:
in: query
name: hitsPerPage
- description: Maximum number of hits per page.
+ description: Number of hits per page.
schema:
type: integer
default: 100
@@ -85,15 +87,16 @@ HitsPerPage:
Offset:
in: query
name: offset
- description: Position of the starting record. Used for paging. 0 is the first record.
+ description: Position of the first item to return.
schema:
type: integer
default: 0
+ minimum: 0
Limit:
in: query
name: limit
- description: Number of records to return (page size).
+ description: Number of items to return.
schema:
type: integer
default: 10
@@ -101,8 +104,12 @@ Limit:
# misc
objectID:
type: string
- description: Unique object identifier.
- example: 'product-1'
+ description: Unique record identifier.
+
+ruleID:
+ title: objectID
+ type: string
+ description: Unique identifier of a rule object.
id:
type: string
@@ -112,7 +119,7 @@ id:
indexName:
type: string
example: products
- description: Algolia index name.
+ description: Index name.
hitsPerPage:
type: integer
@@ -123,13 +130,13 @@ hitsPerPage:
query:
type: string
- description: Full-text query.
+ description: Search query.
default: ''
page:
type: integer
minimum: 0
- description: Requested page (the first page is page 0).
+ description: Requested page of the API response.
trackedSearchCount:
type: integer
diff --git a/specs/common/responses/common.yml b/specs/common/responses/common.yml
index cd4019396a..091942d01e 100644
--- a/specs/common/responses/common.yml
+++ b/specs/common/responses/common.yml
@@ -2,22 +2,24 @@ taskID:
type: integer
format: int64
example: 1514562690001
- description: >
+ description: |
Unique identifier of a task.
- A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the `task` operation and this `taskID`.
+ A successful API response means that a task was added to a queue. It might not run immediately. You can check the task's progress with the [`task` operation](#tag/Indices/operation/getTask) and this `taskID`.
objectIDs:
type: array
items:
type: string
- example: ['record-1','record-2']
- description: Unique object (record) identifiers.
+ example:
+ - record-1
+ - record-2
+ description: Unique record identifiers.
createdAt:
type: string
- example: '2023-07-04T12:49:15Z'
- description: Timestamp of creation in [ISO-8601](https://wikipedia.org/wiki/ISO_8601) format.
+ example: 2023-07-04T12:49:15Z
+ description: Timestamp of creation in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
createdAtTimestamp:
type: integer
@@ -27,10 +29,10 @@ createdAtTimestamp:
updatedAt:
type: string
- example: '2023-07-04T12:49:15Z'
+ example: 2023-07-04T12:49:15Z
description: Timestamp of the last update in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
deletedAt:
type: string
- example: '2023-06-27T14:42:38.831Z'
+ example: 2023-06-27T14:42:38.831Z
description: Timestamp of deletion in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
diff --git a/specs/common/schemas/HighlightResult.yml b/specs/common/schemas/HighlightResult.yml
index 64763ce4af..55936e33ef 100644
--- a/specs/common/schemas/HighlightResult.yml
+++ b/specs/common/schemas/HighlightResult.yml
@@ -1,6 +1,6 @@
highlightResultOption:
type: object
- description: Show highlighted section and words matched on a query.
+ description: Surround words that match the query with HTML tags for highlighting.
additionalProperties: false
properties:
value:
@@ -9,7 +9,7 @@ highlightResultOption:
$ref: '#/matchLevel'
matchedWords:
type: array
- description: List of words from the query that matched the object.
+ description: List of matched words from the search query.
example: ['action']
items:
type: string
@@ -23,23 +23,24 @@ highlightResultOption:
highlightedValue:
type: string
- description: Markup text with `facetQuery` matches highlighted.
+ description: Highlighted attribute value, including HTML tags.
example: 'George Clooney'
matchLevel:
type: string
- description: Indicates how well the attribute matched the search query.
+ description: Whether the whole query string matches or only a part.
enum: [none, partial, full]
highlightResultOptionMap:
type: object
- description: Show highlighted section and words matched on a query.
+ description: Surround words that match the query with HTML tags for highlighting.
additionalProperties:
+ x-additionalPropertiesName: attribute
$ref: '#/highlightResultOption'
highlightResultOptionArray:
type: array
- description: Show highlighted section and words matched on a query.
+ description: Surround words that match the query with HTML tags for highlighting.
items:
$ref: '#/highlightResultOption'
@@ -51,6 +52,7 @@ highlightResult:
highlightResultMap:
type: object
- description: Show highlighted section and words matched on a query.
+ description: Surround words that match the query with HTML tags for highlighting.
additionalProperties:
+ x-additionalPropertiesName: attribute
$ref: '#/highlightResult'
diff --git a/specs/common/schemas/IndexSettings.yml b/specs/common/schemas/IndexSettings.yml
index 0f5c4d93d4..4e50012d03 100644
--- a/specs/common/schemas/IndexSettings.yml
+++ b/specs/common/schemas/IndexSettings.yml
@@ -1,33 +1,103 @@
indexSettings:
- description: Algolia index settings.
+ description: Index settings.
allOf:
- $ref: '#/baseIndexSettings'
- $ref: '#/indexSettingsAsSearchParams'
baseIndexSettings:
type: object
+ title: Index settings.
additionalProperties: false
properties:
+ attributesForFaceting:
+ type: array
+ items:
+ type: string
+ example:
+ - author
+ - filterOnly(isbn)
+ - searchable(edition)
+ - afterDistinct(category)
+ - afterDistinct(searchable(publisher))
+ description: |
+ Attributes used for [faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/).
+
+ Facets are ways to categorize search results based on attributes.
+ Facets can be used to let user filter search results.
+ By default, no attribute is used for faceting.
+
+ **Modifiers**
+
+
+ filterOnly("ATTRIBUTE")- Allows using this attribute as a filter, but doesn't evalue the facet values.
+ searchable("ATTRIBUTE")- Allows searching for facet values.
+ afterDistinct("ATTRIBUTE")-
+
+ Evaluates the facet count _after_ deduplication with `distinct`.
+ This ensures accurate facet counts.
+ You can apply this modifier to searchable facets: `afterDistinct(searchable(ATTRIBUTE))`.
+
+
+
+
+ Without modifiers, the attribute is used as a regular facet.
+ default: []
+ x-categories:
+ - Faceting
replicas:
type: array
items:
type: string
- example: [virtual(prod_products_price_asc),dev_products_replica]
- description: Creates [replicas](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/), which are copies of a primary index with the same records but different settings.
+ example: [virtual(prod_products_price_asc), dev_products_replica]
+ description: |
+ Creates [replica indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/).
+
+ Replicas are copies of a primary index with the same records but different settings, synonyms, or rules.
+ If you want to offer a different ranking or sorting of your search results, you'll use replica indices.
+ All index operations on a primary index are automatically forwarded to its replicas.
+ To add a replica index, you must provide the complete set of replicas to this parameter.
+ If you omit a replica from this list, the replica turns into a regular, standalone index that will no longer by synced with the primary index.
+
+ **Modifier**
+
+
+ virtual("REPLICA")-
+
+ Create a virtual replica,
+ Virtual replicas don't increase the number of records and are optimized for [Relevant sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/relevant-sort/).
+
+
+
+
+ Without modifier, a standard replica is created, which duplicates your record count and is used for strict, or [exhaustive sorting](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/exhaustive-sort/).
default: []
x-categories:
- Ranking
paginationLimitedTo:
type: integer
- example: 20
- description: Maximum number of hits accessible through pagination.
+ example: 100
+ description: |
+ Maximum number of search results that can be obtained through pagination.
+
+ Higher pagination limits might slow down your search.
+ For pagination limits above 1,000, the sorting of results beyond the 1,000th hit can't be guaranteed.
default: 1000
+ maximum: 20000
unretrievableAttributes:
type: array
items:
type: string
- example: [popularity]
- description: Attributes that can't be retrieved at query time.
+ example:
+ - total_sales
+ description: |
+ Attributes that can't be retrieved at query time.
+
+ This can be useful if you want to use an attribute for ranking or to [restrict access](https://www.algolia.com/doc/guides/security/api-keys/how-to/user-restricted-access-to-data/),
+ but don't want to include it in the search results.
default: []
x-categories:
- Attributes
@@ -35,17 +105,27 @@ baseIndexSettings:
type: array
items:
type: string
- example: ['wheel','1X2BCD']
- description: Words for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
+ example:
+ - wheel
+ - 1X2BCD
+ description: |
+ Words for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
+ This also turns off [word splitting and concatenation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/splitting-and-concatenation/) for the specified words.
default: []
x-categories:
- Typos
attributesToTransliterate:
- description: Attributes in your index to which [Japanese transliteration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#japanese-transliteration-and-type-ahead) applies. This will ensure that words indexed in Katakana or Kanji can also be searched in Hiragana.
+ description: |
+ Attributes, for which you want to support [Japanese transliteration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#japanese-transliteration-and-type-ahead).
+
+ Transliteration supports searching in any of the Japanese writing systems.
+ To support transliteration, you must set the indexing language to Japanese.
type: array
items:
type: string
- example: ['name','description']
+ example:
+ - name
+ - description
x-categories:
- Languages
camelCaseAttributes:
@@ -53,14 +133,25 @@ baseIndexSettings:
items:
type: string
example: ['description']
- description: Attributes on which to split [camel case](https://wikipedia.org/wiki/Camel_case) words.
+ description: Attributes for which to split [camel case](https://wikipedia.org/wiki/Camel_case) words.
default: []
x-categories:
- Languages
decompoundedAttributes:
type: object
- example: {de: ['name']}
- description: Attributes in your index to which [word segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) (decompounding) applies.
+ example:
+ de:
+ - name
+ description: |
+ Searchable attributes to which Algolia should apply [word segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) (decompounding).
+
+ Compound words are formed by combining two or more individual words,
+ and are particularly prevalent in Germanic languages—for example, "firefighter".
+ With decompounding, the individual components are indexed separately.
+
+ You can specify different lists for different languages.
+ Decompounding is supported for these languages:
+ Dutch (`nl`), German (`de`), Finnish (`fi`), Danish (`da`), Swedish (`sv`), and Norwegian (`no`).
default: {}
x-categories:
- Languages
@@ -68,8 +159,16 @@ baseIndexSettings:
type: array
items:
type: string
- example: ['ja']
- description: Set the languages of your index, for language-specific processing steps such as [tokenization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/tokenization/) and [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
+ example:
+ - ja
+ description: |
+ [ISO code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for a language for language-specific processing steps, such as word detection and dictionary settings.
+
+ **You should always specify an indexing language.**
+ If you don't specify an indexing language, the search engine uses all [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/),
+ or the languages you specified with the `ignorePlurals` or `removeStopWords` parameters.
+ This can lead to unexpected search results.
+ For more information, see [Language-specific configuration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/).
default: []
x-categories:
- Languages
@@ -77,17 +176,17 @@ baseIndexSettings:
type: array
items:
type: string
- example: ['sku']
- description: Attributes for which you want to turn off [prefix matching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#adjusting-prefix-search).
+ example:
+ - sku
+ description: Searchable attributes for which you want to turn off [prefix matching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#adjusting-prefix-search).
default: []
x-categories:
- Query strategy
allowCompressionOfIntegerArray:
type: boolean
- description: >
- Incidates whether the engine compresses arrays with exclusively non-negative integers.
-
- When enabled, the compressed arrays may be reordered.
+ description: |
+ Whether arrays with exclusively non-negative integers should be compressed for better performance.
+ If true, the compressed arrays may be reordered.
default: false
x-categories:
- Performance
@@ -95,15 +194,42 @@ baseIndexSettings:
type: array
items:
type: string
- description: Numeric attributes that can be used as [numerical filters](https://www.algolia.com/doc/guides/managing-results/rules/detecting-intent/how-to/applying-a-custom-filter-for-a-specific-query/#numerical-filters).
- example: ['quantity','popularity']
+ description: |
+ Numeric attributes that can be used as [numerical filters](https://www.algolia.com/doc/guides/managing-results/rules/detecting-intent/how-to/applying-a-custom-filter-for-a-specific-query/#numerical-filters).
+
+ By default, all numeric attributes are available as numerical filters.
+ For faster indexing, reduce the number of numeric attributes.
+
+ If you want to turn off filtering for all numeric attributes, specifiy an attribute that doesn't exist in your index, such as `NO_NUMERIC_FILTERING`.
+
+ **Modifier**
+
+
+ equalOnly("ATTRIBUTE")-
+
+ Support only filtering based on equality comparisons `=` and `!=`.
+
+
+
+
+ Without modifier, all numeric comparisons are supported.
+ example:
+ - equalOnly(quantity)
+ - popularity
default: []
x-categories:
- Performance
separatorsToIndex:
type: string
example: +#
- description: Controls which separators are added to an Algolia index as part of [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/#what-does-normalization-mean). Separators are all non-letter characters except spaces and currency characters, such as $€£¥.
+ description: |
+ Controls which separators are indexed.
+
+ Separators are all non-letter characters except spaces and currency characters, such as $€£¥.
+ By default, separator characters aren't indexed.
+ With `separatorsToIndex`, Algolia treats separator characters as separate words.
+ For example, a search for `C#` would report two matches.
default: ''
x-categories:
- Typos
@@ -111,19 +237,46 @@ baseIndexSettings:
type: array
items:
type: string
- example: ['title,alternative_title','author','unordered(text)','emails.personal']
- description: >
- [Attributes used for searching](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/), including determining [if matches at the beginning of a word are important (ordered) or not (unordered)](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/how-to/configuring-searchable-attributes-the-right-way/#understanding-word-position).
+ example:
+ - title,alternative_title
+ - author
+ - unordered(text)
+ - emails.personal
+ description: |
+ Attributes used for searching.
+
+ By default, all attributes are searchable and the [Attribute](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#attribute) ranking criterion is turned off.
+ With a non-empty list, Algolia only returns results with matches in the selected attributes.
+ In addition, the Attribute ranking criterion is turned on: matches in attributes that are higher in the list of `searchableAttributes` rank first.
+ To make matches in two attributes rank equally, include them in a comma-separated string, such as `"title,alternate_title"`.
+ Attributes with the same priority are always unordered.
+
+ For more information, see [Searchable attributes](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/setting-searchable-attributes/).
+
+ **Modifier**
+
+
+ unordered("ATTRIBUTE")-
+ Ignore the position of a match within the attribute.
+
+
+
+ Without modifier, matches at the beginning of an attribute rank higer than matches at the end.
default: []
x-categories:
- Attributes
userData:
$ref: '#/userData'
customNormalization:
- description: A list of characters and their normalized replacements to override Algolia's default [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
+ description: |
+ Characters and their normalized replacements.
+ This overrides Algolia's default [normalization](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
type: object
- example: >
- {default: {'ä': 'ae', 'ü': 'ue'}}
+ example:
+ default:
+ ä: ae
+ ü: ue
additionalProperties:
type: object
additionalProperties:
@@ -131,30 +284,38 @@ baseIndexSettings:
x-categories:
- Languages
attributeForDistinct:
- description: Name of the deduplication attribute to be used with Algolia's [_distinct_ feature](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature).
- example: 'url'
+ description: |
+ Attribute that should be used to establish groups of results.
+
+ All records with the same value for this attribute are considered a group.
+ You can combine `attributeForDistinct` with the `distinct` search parameter to control
+ how many items per group are included in the search results.
+
+ If you want to use the same attribute also for faceting, use the `afterDistinct` modifier of the `attributesForFaceting` setting.
+ This applies faceting _after_ deduplication, which will result in accurate facet counts.
+ example: url
type: string
indexSettingsAsSearchParams:
type: object
additionalProperties: false
properties:
- attributesForFaceting:
- type: array
- items:
- type: string
- example: ['author','filterOnly(isbn)','searchable(edition)','afterDistinct(category)','afterDistinct(searchable(publisher))']
- description: >
- Attributes used for [faceting](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/) and the [modifiers](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting/#modifiers) that can be applied: `filterOnly`, `searchable`, and `afterDistinct`.
- default: []
- x-categories:
- - Faceting
attributesToRetrieve:
type: array
items:
type: string
- example: ['author','title','content']
- description: Attributes to include in the API response. To reduce the size of your response, you can retrieve only some of the attributes. By default, the response includes all attributes.
+ example:
+ - author
+ - title
+ - content
+ description: |
+ Attributes to include in the API response.
+
+ To reduce the size of your response, you can retrieve only some of the attributes.
+
+ - `*` retrieves all attributes, except attributes included in the `customRanking` and `unretrievableAttributes` settings.
+ - To retrieve all attributes except a specific one, prefix the attribute with a dash and combine it with the `*`: `["*", "-ATTRIBUTE"]`.
+ - The `objectID` attribute is always included.
default: ['*']
x-categories:
- Attributes
@@ -162,7 +323,26 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Determines the order in which Algolia [returns your results](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/).
+ description: |
+ Determines the order in which Algolia returns your results.
+
+ By default, each entry corresponds to a [ranking criteria](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/).
+ The tie-breaking algorithm sequentially applies each criterion in the order they're specified.
+ If you configure a replica index for [sorting by an attribute](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/how-to/sort-by-attribute/),
+ you put the sorting attribute at the top of the list.
+
+ **Modifiers**
+
+
+ asc("ATTRIBUTE")- Sort the index by the values of an attribute, in ascending order.
+ desc("ATTRIBUTE")- Sort the index by the values of an attribute, in descending order.
+
+
+ Before you modify the default setting,
+ you should test your changes in the dashboard,
+ and by [A/B testing](https://www.algolia.com/doc/guides/ab-testing/what-is-ab-testing/).
default:
- typo
- geo
@@ -178,16 +358,39 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['desc(popularity)','asc(price)']
- description: >
- Specifies the [Custom ranking criterion](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/). Use the `asc` and `desc` modifiers to specify the ranking order: ascending or descending.
+ example:
+ - desc(popularity)
+ - asc(price)
+ description: |
+ Attributes to use as [custom ranking](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/).
+
+ The custom ranking attributes decide which items are shown first if the other ranking criteria are equal.
+
+ Records with missing values for your selected custom ranking attributes are always sorted last.
+ Boolean attributes are sorted based on their alphabetical order.
+
+ **Modifiers**
+
+
+ asc("ATTRIBUTE")- Sort the index by the values of an attribute, in ascending order.
+ desc("ATTRIBUTE")- Sort the index by the values of an attribute, in descending order.
+
+
+ If you use two or more custom ranking attributes, [reduce the precision](https://www.algolia.com/doc/guides/managing-results/must-do/custom-ranking/how-to/controlling-custom-ranking-metrics-precision/) of your first attributes,
+ or the other attributes will never be applied.
default: []
x-categories:
- Ranking
relevancyStrictness:
type: integer
example: 90
- description: Relevancy threshold below which less relevant results aren't included in the results.
+ description: |
+ Relevancy threshold below which less relevant results aren't included in the results.
+
+ You can only set `relevancyStrictness` on [virtual replica indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/in-depth/replicas/#what-are-virtual-replicas).
+ Use this setting to strike a balance between the relevance and number of returned results.
default: 100
x-categories:
- Ranking
@@ -195,29 +398,46 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['author','title','content']
- description: Attributes to highlight. Strings that match the search query in the attributes are highlighted by surrounding them with HTML tags (`highlightPreTag` and `highlightPostTag`).
+ example: [author, title, conten, content]
+ description: |
+ Attributes to highlight.
+
+ By default, all searchable attributes are highlighted.
+ Use `*` to highlight all attributes or use an empty array `[]` to turn off highlighting.
+
+ With highlighting, strings that match the search query are surrounded by HTML tags defined by `highlightPreTag` and `highlightPostTag`.
+ You can use this to visually highlight matching parts of a search query in your UI.
+
+ For more information, see [Highlighting and snippeting](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/highlighting-snippeting/js/).
x-categories:
- Highlighting and Snippeting
attributesToSnippet:
type: array
items:
type: string
- example: ['content:80','description']
- description: >
- Attributes to _snippet_. 'Snippeting' is shortening the attribute to a certain number of words. If not specified, the attribute is shortened to the 10 words around the matching string but you can specify the number. For example: `body:20`.
+ example:
+ - content:80
+ - description
+ description: |
+ Attributes for which to enable snippets.
+
+ Snippets provide additional context to matched words.
+ If you enable snippets, they include 10 words, including the matched word.
+ The matched word will also be wrapped by HTML tags for highlighting.
+ You can adjust the number of words with the following notation: `ATTRIBUTE:NUMBER`,
+ where `NUMBER` is the number of words to be extracted.
default: []
x-categories:
- Highlighting and Snippeting
highlightPreTag:
type: string
- description: HTML string to insert before the highlighted parts in all highlight and snippet results.
+ description: HTML tag to insert before the highlighted parts in all highlighted results and snippets.
default:
x-categories:
- Highlighting and Snippeting
highlightPostTag:
type: string
- description: HTML string to insert after the highlighted parts in all highlight and snippet results.
+ description: HTML tag to insert after the highlighted parts in all highlighted results and snippets.
default:
x-categories:
- Highlighting and Snippeting
@@ -229,7 +449,9 @@ indexSettingsAsSearchParams:
- Highlighting and Snippeting
restrictHighlightAndSnippetArrays:
type: boolean
- description: Restrict highlighting and snippeting to items that matched the query.
+ description: |
+ Whether to restrict highlighting and snippeting to items that at least partially matched the search query.
+ By default, all items are highlighted and snippeted.
default: false
x-categories:
- Highlighting and Snippeting
@@ -237,13 +459,13 @@ indexSettingsAsSearchParams:
$ref: '#/hitsPerPage'
minWordSizefor1Typo:
type: integer
- description: Minimum number of characters a word in the query string must contain to accept matches with [one typo](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
+ description: Minimum number of characters a word in the search query must contain to accept matches with [one typo](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
default: 4
x-categories:
- Typos
minWordSizefor2Typos:
type: integer
- description: Minimum number of characters a word in the query string must contain to accept matches with [two typos](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
+ description: Minimum number of characters a word in the search query must contain to accept matches with [two typos](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/in-depth/configuring-typo-tolerance/#configuring-word-length-for-typos).
default: 8
x-categories:
- Typos
@@ -251,7 +473,11 @@ indexSettingsAsSearchParams:
$ref: '#/typoTolerance'
allowTyposOnNumericTokens:
type: boolean
- description: Whether to allow typos on numbers ("numeric tokens") in the query string.
+ description: |
+ Whether to allow typos on numbers in the search query.
+
+ Turn off this setting to reduce the number of irrelevant matches
+ when searching in large sets of similar numbers.
default: true
x-categories:
- Typos
@@ -259,8 +485,18 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['sku']
- description: Attributes for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
+ example:
+ - sku
+ description: |
+ Attributes for which you want to turn off [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/).
+
+ Returning only exact matches can help when:
+
+ - [Searching in hyphenated attributes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/how-to/how-to-search-in-hyphenated-attributes/).
+ - Reducing the number of matches when you have too many.
+ This can happen with attributes that are long blocks of text, such as product descriptions.
+
+ Consider alternatives such as `disableTypoToleranceOnWords` or adding synonyms if your attributes have intentional unusual spellings that might look like typos.
default: []
x-categories:
- Typos
@@ -271,7 +507,12 @@ indexSettingsAsSearchParams:
keepDiacriticsOnCharacters:
type: string
example: øé
- description: Characters that the engine shouldn't automatically [normalize](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/).
+ description: |
+ Characters for which diacritics should be preserved.
+
+ By default, Algolia removes diacritics from letters.
+ For example, `é` becomes `e`. If this causes issues in your search,
+ you can specify characters that should keep their diacritics.
default: ''
x-categories:
- Languages
@@ -279,27 +520,43 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['es']
- description: Sets your user's search language. This adjusts language-specific settings and features such as `ignorePlurals`, `removeStopWords`, and [CJK](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/#normalization-for-logogram-based-languages-cjk) word detection.
+ example:
+ - es
+ description: |
+ [ISO code](https://en.wikipedia.org/wiki/List_of_ISO_639_language_codes) for language-specific settings such as plurals, stop words, and word-detection dictionaries.
+
+ This setting sets a default list of languages used by the `removeStopWords` and `ignorePlurals` settings.
+ This setting also sets a dictionary for word detection in the logogram-based [CJK](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/normalization/#normalization-for-logogram-based-languages-cjk) languages.
+ To support this, you must place the CJK language **first**.
+
+
+ **You should always specify a query language.**
+ If you don't specify an indexing language, the search engine uses all [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/),
+ or the languages you specified with the `ignorePlurals` or `removeStopWords` parameters.
+ This can lead to unexpected search results.
+ For more information, see [Language-specific configuration](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/).
default: []
x-categories:
- Languages
decompoundQuery:
type: boolean
- description: >
- [Splits compound words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#splitting-compound-words) into their component word parts in the query.
+ description: |
+ Whether to split compound words into their building blocks.
+
+ For more information, see [Word segmentation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/language-specific-configurations/#splitting-compound-words).
+ Word segmentation is supported for these languages: German, Dutch, Finnish, Swedish, and Norwegian.
default: true
x-categories:
- Languages
enableRules:
type: boolean
- description: Incidates whether [Rules](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/) are enabled.
+ description: Whether to enable rules.
default: true
x-categories:
- Rules
enablePersonalization:
type: boolean
- description: Incidates whether [Personalization](https://www.algolia.com/doc/guides/personalization/what-is-personalization/) is enabled.
+ description: Whether to enable Personalization.
default: false
x-categories:
- Personalization
@@ -313,7 +570,10 @@ indexSettingsAsSearchParams:
$ref: '#/semanticSearch'
advancedSyntax:
type: boolean
- description: Enables the [advanced query syntax](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/#advanced-syntax).
+ description: |
+ Whether to support phrase matching and excluding words from search queries.
+
+ Use the `advancedSyntaxFeatures` parameter to control which feature is supported.
default: false
x-categories:
- Query strategy
@@ -321,8 +581,27 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['blue','iphone case']
- description: Words which should be considered [optional](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words) when found in a query.
+ example:
+ - blue
+ - iphone case
+ description: |
+ Words that should be considered optional when found in the query.
+
+ By default, records must match all words in the search query to be included in the search results.
+ Adding optional words can help to increase the number of search results by running an additional search query that doesn't include the optional words.
+ For example, if the search query is "action video" and "video" is an optional word,
+ the search engine runs two queries. One for "action video" and one for "action".
+ Records that match all words are ranked higher.
+
+ For a search query with 4 or more words **and** all its words are optional,
+ the number of matched words required for a record to be included in the search results increases for every 1,000 records:
+
+ - If `optionalWords` has less than 10 words, the required number of matched words increases by 1:
+ results 1 to 1,000 require 1 matched word, results 1,001 to 2000 need 2 matched words.
+ - If `optionalWords` has 10 or more words, the number of required matched words increases by the number of optional words dividied by 5 (rounded down).
+ For example, with 18 optional words: results 1 to 1,000 require 1 matched word, results 1,001 to 2000 need 4 matched words.
+
+ For more information, see [Optional words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/#creating-a-list-of-optional-words).
default: []
x-categories:
- Query strategy
@@ -330,8 +609,15 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- example: ['description']
- description: Attributes for which you want to [turn off the exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).
+ example:
+ - description
+ description: |
+ Searchable attributes for which you want to [turn off the Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).
+
+ This can be useful for attributes with long values, where the likelyhood of an exact match is high,
+ such as product descriptions.
+ Turning off the Exact ranking criterion for these attributes favors exact matching on other attributes.
+ This reduces the impact of individual attributes with a lot of content on ranking.
default: []
x-categories:
- Query strategy
@@ -341,7 +627,25 @@ indexSettingsAsSearchParams:
type: array
items:
$ref: '#/alternativesAsExact'
- description: Alternatives that should be considered an exact match by [the exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes).
+ description: |
+ Alternatives of query words that should be considered as exact matches by the Exact ranking criterion.
+
+
+ ignorePlurals-
+
+ Plurals and similar declensions added by the `ignorePlurals` setting are considered exact matches.
+
+
+ singleWordSynonym-
+ Single-word synonyms, such as "NY/NYC" are considered exact matches.
+
+ multiWordsSynonym-
+ Multi-word synonyms, such as "NY/New York" are considered exact matches.
+
+
.
default: [ignorePlurals, singleWordSynonym]
x-categories:
- Query strategy
@@ -349,7 +653,27 @@ indexSettingsAsSearchParams:
type: array
items:
$ref: '#/advancedSyntaxFeatures'
- description: Allows you to specify which advanced syntax features are active when `advancedSyntax` is enabled.
+ description: |
+ Advanced search syntax features you want to support.
+
+
+ exactPhrase-
+
+ Phrases in quotes must match exactly.
+ For example, `sparkly blue "iPhone case"` only returns records with the exact string "iPhone case".
+
+
+ excludeWords-
+
+ Query words prefixed with a `-` must not occur in a record.
+ For example, `search -engine` matches records that contain "search" but not "engine".
+
+
+
+
+ This setting only has an effect if `advancedSyntax` is true.
default: [exactPhrase, excludeWords]
x-categories:
- Query strategy
@@ -357,7 +681,16 @@ indexSettingsAsSearchParams:
$ref: '#/distinct'
replaceSynonymsInHighlight:
type: boolean
- description: Whether to highlight and snippet the original word that matches the synonym or the synonym itself.
+ description: |
+ Whether to replace a highlighted word with the matched synonym.
+
+ By default, the original words are highlighted even if a synonym matches.
+ For example, with `home` as a synonym for `house` and a search for `home`,
+ records matching either "home" or "house" are included in the search results,
+ and either "home" or "house" are highlighted.
+
+ With `replaceSynonymsInHighlight` set to `true`, a search for `home` still matches the same records,
+ but all occurences of "house" are replaced by "home" in the highlighted response.
default: false
x-categories:
- Highlighting and Snippeting
@@ -365,7 +698,13 @@ indexSettingsAsSearchParams:
type: integer
minimum: 1
maximum: 7
- description: Precision of the [proximity ranking criterion](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#proximity).
+ description: |
+ Minimum proximity score for two matching words.
+
+ This adjusts the [Proximity ranking criterion](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#proximity)
+ by equally scoring matches that are farther apart.
+
+ For example, if `minProximity` is 2, neighboring matches and matches with one word between them would have the same score.
default: 1
x-categories:
- Advanced
@@ -373,8 +712,18 @@ indexSettingsAsSearchParams:
type: array
items:
type: string
- description: Attributes to include in the API response for search and browse queries.
- default: []
+ description: |
+ Properties to include in the API response of `search` and `browse` requests.
+
+ By default, all response properties are included.
+ To reduce the response size, you can select, which attributes should be included.
+
+ You can't exclude these properties:
+ `message`, `warning`, `cursor`, `serverUsed`, `indexUsed`,
+ `abTestVariantID`, `parsedQuery`, or any property triggered by the `getRankingInfo` parameter.
+
+ Don't exclude properties that you might need in your search UI.
+ default: ['*']
x-categories:
- Advanced
maxFacetHits:
@@ -383,17 +732,37 @@ indexSettingsAsSearchParams:
type: integer
description: Maximum number of facet values to return for each facet.
default: 100
+ maximum: 1000
x-categories:
- Faceting
sortFacetValuesBy:
type: string
- description: Controls how facet values are fetched.
+ description: |
+ Order in which to retrieve facet values.
+
+
+ count-
+ Facet values are retrieved by decreasing count.
+ The count is the number of matching records containing this facet value.
+
+ alpha- Retrieve facet values alphabetically.
+
+
+ This setting doesn't influence how facet values are displayed in your UI (see `renderingContent`).
+ For more information, see [facet value display](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/facet-display/js/).
default: count
x-categories:
- Faceting
attributeCriteriaComputedByMinProximity:
type: boolean
- description: When the [Attribute criterion is ranked above Proximity](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#attribute-and-proximity-combinations) in your ranking formula, Proximity is used to select which searchable attribute is matched in the Attribute ranking stage.
+ description: |
+ Whether the best matching attribute should be determined by minimum proximity.
+
+ This setting only affects ranking if the Attribute ranking criterion comes before Proximity in the `ranking` setting.
+ If true, the best matching attribute is selected based on the minimum proximity of multiple matches.
+ Otherwise, the best matching attribute is determined by the order in the `searchableAttributes` setting.
default: false
x-categories:
- Advanced
@@ -401,7 +770,10 @@ indexSettingsAsSearchParams:
$ref: '#/renderingContent'
enableReRanking:
type: boolean
- description: Indicates whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/).
+ description: |
+ Whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/).
+
+ This setting only has an effect if you activated Dynamic Re-Ranking for this index in the Algolia dashboard.
default: true
x-categories:
- Filtering
@@ -410,14 +782,16 @@ indexSettingsAsSearchParams:
maxFacetHits:
type: integer
- description: Maximum number of facet hits to return when [searching for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
+ description: Maximum number of facet values to return when [searching for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
maximum: 100
default: 10
x-categories:
- Advanced
reRankingApplyFilter:
- description: When [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/) is enabled, only records that match these filters will be affected by Dynamic Re-Ranking.
+ description: |
+ Restrict [Dynamic Re-ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/) to records that match these filters.
+ nullable: true
oneOf:
- $ref: './SearchParams.yml#/listOfSearchFilters'
- type: string
@@ -435,41 +809,104 @@ hitsPerPage:
- Pagination
userData:
- example: {'settingID': 'f2a7b51e3503acc6a39b3784ffb84300','pluginVersion': '1.6.0'}
- description: Lets you store custom data in your indices.
+ example:
+ settingID: f2a7b51e3503acc6a39b3784ffb84300
+ pluginVersion: 1.6.0
+ description: |
+ An object with custom data.
+
+ You can store up to 32 kB as custom data.
default: {}
x-categories:
- Advanced
queryType:
type: string
- enum: [prefixLast, prefixAll, prefixNone]
- description: Determines how query words are [interpreted as prefixes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/prefix-searching/).
+ enum:
+ - prefixLast
+ - prefixAll
+ - prefixNone
+ description: |
+ Determines if and how query words are interpreted as prefixes.
+
+ By default, only the last query word is treated as prefix (`prefixLast`).
+ To turn off prefix search, use `prefixNone`.
+ Avoid `prefixAll`, which treats all query words as prefixes.
+ This might lead to counterintuitive results and makes your search slower.
+
+ For more information, see [Prefix searching](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/prefix-searching/).
default: prefixLast
x-categories:
- Query strategy
mode:
type: string
- enum: ['neuralSearch', 'keywordSearch']
- description: Search mode the index will use to query for results.
+ enum:
+ - neuralSearch
+ - keywordSearch
+ description: |
+ Search mode the index will use to query for results.
+
+ This setting only applies to indices, for which Algolia enabled NeuralSearch for you.
default: keywordSearch
x-categories:
- Query strategy
removeWordsIfNoResults:
type: string
- enum: [none, lastWords, firstWords, allOptional]
+ enum:
+ - none
+ - lastWords
+ - firstWords
+ - allOptional
example: firstWords
- description: Strategy to [remove words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/in-depth/why-use-remove-words-if-no-results/) from the query when it doesn't match any hits.
+ description: |
+ Strategy for removing words from the query when it doesn't return any results.
+ This helps to avoid returning empty search results.
+
+
+ none- No words are removed when a query doesn't return results.
+ lastWords- Treat the last (then second to last, then third to last) word as optional, until there are results or at most 5 words have been removed.
+ firstWords- Treat the first (then second, then third) word as optional, until there are results or at most 5 words have been removed.
+ allOptional- Treat all words as optional.
+
+
+ For more information, see [Remove words to improve results](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/empty-or-insufficient-results/in-depth/why-use-remove-words-if-no-results/).
default: none
x-categories:
- Query strategy
exactOnSingleWordQuery:
type: string
- enum: [attribute, none, word]
- description: Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes) is computed when the query contains only one word.
+ enum:
+ - attribute
+ - none
+ - word
+ description: |
+ Determines how the [Exact ranking criterion](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/override-search-engine-defaults/in-depth/adjust-exact-settings/#turn-off-exact-for-some-attributes) is computed when the search query has only one word.
+
+
+ attribute-
+ The Exact ranking criterion is 1 if the query word and attribute value are the same.
+ For example, a search for "road" will match the value "road", but not "road trip".
+
+ none-
+ The Exact ranking criterion is ignored on single-word searches.
+
+ word-
+ The Exact ranking criterion is 1 if the query word is found in the attribute value.
+ The query word must have at least 3 characters and must not be a stop word.
+
+
+
+ If `exactOnSingleWordQuery` is `word`, only exact matches will be highlighted, partial and prefix matches won't.
default: attribute
x-categories:
- Query strategy
@@ -487,11 +924,27 @@ advancedSyntaxFeatures:
- Query strategy
distinct:
- description: Enables [deduplication or grouping of results (Algolia's _distinct_ feature](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature)).
+ description: |
+ Determines how many records of a group are included in the search results.
+
+ Records with the same value for the `attributeForDistinct` attribute are considered a group.
+ The `distinct` setting controls how many members of the group are returned.
+ This is useful for [deduplication and grouping](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/#introducing-algolias-distinct-feature).
+
+ The `distinct` setting is ignored if `attributeForDistinct` is not set.
example: 1
oneOf:
- type: boolean
+ description: Whether deduplication is turned on. If true, only one member of a group is shown in the search results.
- type: integer
+ description: |
+ Number of members of a group of records to include in the search results.
+
+ - Don't use `distinct > 1` for records that might be [promoted by rules](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/promote-hits/).
+ The number of hits won't be correct and faceting won't work as expected.
+ - With `distinct > 1`, the `hitsPerPage` parameter controls the number of returned groups.
+ For example, with `hitsPerPage: 10` and `distinct: 2`, up to 20 records are returned.
+ Likewise, the `nbHits` response attribute contains the number of returned groups.
minimum: 0
maximum: 4
default: 0
@@ -499,58 +952,77 @@ distinct:
- Advanced
typoTolerance:
- description: Controls whether [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/) is enabled and how it is applied.
+ description: |
+ Whether [typo tolerance](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/typo-tolerance/) is enabled and how it is applied.
+
+ If typo tolerance is true, `min`, or `strict`, [word splitting and concetenation](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/splitting-and-concatenation/) is also active.
oneOf:
- type: boolean
default: true
+ description: Whether typo tolerance is active. If true, matches with typos are included in the search results and rank after exact matches.
- $ref: '#/typoToleranceEnum'
x-categories:
- Typos
typoToleranceEnum:
type: string
+ title: typo tolerance
+ description: |
+ - `min`. Return matches with the lowest number of typos.
+ For example, if you have matches without typos, only include those.
+ But if there are no matches without typos (with 1 typo), include matches with 1 typo (2 typos).
+ - `strict`. Return matches with the two lowest numbers of typos.
+ With `strict`, the Typo ranking criterion is applied first in the `ranking` setting.
enum: [min, strict]
ignorePlurals:
- description: >
- Treats singular, plurals, and other forms of declensions as matching terms.
-
- `ignorePlurals` is used in conjunction with the `queryLanguages` setting.
-
- _list_: language ISO codes for which ignoring plurals should be enabled. This list will override any values that you may have set in `queryLanguages`.
- _true_: enables the ignore plurals feature, where singulars and plurals are considered equivalent ("foot" = "feet"). The languages supported here are either [every language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) (this is the default) or those set by `queryLanguages`.
- _false_: turns off the ignore plurals feature, so that singulars and plurals aren't considered to be the same ("foot" will not find "feet").
- example: ['ca','es']
+ description: |
+ Treat singular, plurals, and other forms of declensions as equivalent.
+ You should only use this feature for the languages used in your index.
+ example: ['ca', 'es']
oneOf:
- type: array
items:
type: string
+ description: |
+ ISO code for languages for which this feature should be active.
+ This overrides languages you set with `queryLanguages`.
- type: boolean
+ description: |
+ If true, `ignorePlurals` is active for all languages included in `queryLanguages`, or for all supported languages, if `queryLanguges` is empty.
+ If false, singulars, plurals, and other declensions won't be considered equivalent.
default: false
x-categories:
- Languages
removeStopWords:
- description: >
- Removes stop (common) words from the query before executing it.
+ description: |
+ Removes stop words from the search query.
- `removeStopWords` is used in conjunction with the `queryLanguages` setting.
+ Stop words are common words like articles, conjunctions, prepositions, or pronouns that have little or no meaning on their own.
+ In English, "the", "a", or "and" are stop words.
- _list_: language ISO codes for which stop words should be enabled. This list will override any values that you may have set in `queryLanguages`.
- _true_: enables the stop words feature, ensuring that stop words are removed from consideration in a search. The languages supported here are either [every language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) (this is the default) or those set by `queryLanguages`.
- _false_: turns off the stop words feature, allowing stop words to be taken into account in a search.
- example: ['ca','es']
+ You should only use this feature for the languages used in your index.
+ example: ['ca', 'es']
oneOf:
- type: array
items:
type: string
+ description: ISO code for languages for which stop words should be removed. This overrides languages you set in `queryLanguges`.
- type: boolean
default: false
+ description: |
+ If true, stop words are removed for all languages you included in `queryLanguages`, or for all supported languages, if `queryLanguages` is empty.
+ If false, stop words are not removed.
x-categories:
- Languages
renderingContent:
- description: Extra content for the search UI, for example, to control the [ordering and display of facets](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/merchandising-facets/#merchandise-facets-and-their-values-in-the-manual-editor). You can set a default value and dynamically override it with [Rules](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/).
+ description: |
+ Extra data that can be used in the search UI.
+
+ You can use this to control aspects of your search UI, such as, the order of facet names and values
+ without changing your frontend code.
type: object
additionalProperties: false
properties:
@@ -560,7 +1032,7 @@ renderingContent:
- Advanced
facetOrdering:
- description: Defines the ordering of facets (widgets).
+ description: Order of facet names and facet values in your UI.
type: object
additionalProperties: false
properties:
@@ -570,7 +1042,7 @@ facetOrdering:
$ref: '#/values'
facets:
- description: Ordering of facets (widgets).
+ description: Order of facet names.
type: object
additionalProperties: false
properties:
@@ -578,9 +1050,10 @@ facets:
$ref: '#/order'
values:
- description: Ordering of facet values within an individual facet.
+ description: Order of facet values. One object for each facet.
type: object
additionalProperties:
+ x-additionalPropertiesName: facet
$ref: '#/value'
value:
@@ -593,29 +1066,43 @@ value:
$ref: '#/sortRemainingBy'
order:
- description: Pinned order of facet lists.
+ description: |
+ Explicit order of facets or facet values.
+
+ This setting lets you always show specific facets or facet values at the top of the list.
type: array
items:
type: string
sortRemainingBy:
- description: >
- How to display the remaining items:
-
- - `count`: facet count (descending).
- - `alpha`: alphabetical (ascending).
- - `hidden`: show only pinned values.
+ description: |
+ Order of facet values that aren't explicitly positioned with the `order` setting.
+
+
+ count-
+ Order remaining facet values by decreasing count.
+ The count is the number of matching records containing this facet value.
+
+ alpha- Sort facet values alphabetically.
+ hidden- Don't show facet values that aren't explicitly positioned.
+
.
type: string
enum: [count, alpha, hidden]
semanticSearch:
type: object
- description: >
+ description: |
Settings for the semantic search part of NeuralSearch.
- Only used when `mode` is _neuralSearch_.
+ Only used when `mode` is `neuralSearch`.
properties:
eventSources:
- description: Indices from which to collect click and conversion events. If null, the current index and replica group will be used as the event source.
+ description: |
+ Indices from which to collect click and conversion events.
+
+ If null, the current index and all its replicas are used.
nullable: true
type: array
items:
diff --git a/specs/common/schemas/SearchParams.yml b/specs/common/schemas/SearchParams.yml
index a3fe5efd30..c377ce8d05 100644
--- a/specs/common/schemas/SearchParams.yml
+++ b/specs/common/schemas/SearchParams.yml
@@ -4,6 +4,7 @@ searchParams:
- $ref: '#/searchParamsObject'
searchParamsObject:
+ title: Search parameters as object
allOf:
- $ref: '#/baseSearchParams'
- $ref: '../../common/schemas/IndexSettings.yml#/indexSettingsAsSearchParams'
@@ -26,8 +27,20 @@ baseSearchParamsWithoutQuery:
properties:
similarQuery:
type: string
- description: Overrides the query parameter and performs a more generic search.
+ description: |
+ Keywords to be used instead of the search query to conduct a more broader search.
+
+ Using the `similarQuery` parameter changes other settings:
+
+ - `queryType` is set to `prefixNone`.
+ - `removeStopWords` is set to true.
+ - `words` is set as the first ranking criterion.
+ - All remaining words are treated as `optionalWords`.
+
+ Since the `similarQuery` is supposed to do a broad search, they usually return many results.
+ Combine it with `filters` to narrow down the list of results.
default: ''
+ example: 'comedy drama crime Macy Buscemi'
x-categories:
- Search
filters:
@@ -42,12 +55,12 @@ baseSearchParamsWithoutQuery:
$ref: '#/tagFilters'
sumOrFiltersScores:
type: boolean
- description: >
- Determines how to calculate [filter scores](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/filter-scoring/#accumulating-scores-with-sumorfiltersscores).
-
- If `false`, maximum score is kept.
+ description: |
+ Whether to sum all filter scores.
- If `true`, score is summed.
+ If true, all filter scores are summed.
+ Otherwise, the maximum filter score is kept.
+ For more information, see [filter scores](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/in-depth/filter-scoring/#accumulating-scores-with-sumorfiltersscores).
default: false
x-categories:
- Filtering
@@ -55,8 +68,8 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- example: ['title','author']
- description: Restricts a query to only look at a subset of your [searchable attributes](https://www.algolia.com/doc/guides/managing-results/must-do/searchable-attributes/).
+ example: [title, author]
+ description: Restricts a search to a subset of your searchable attributes.
default: []
x-categories:
- Filtering
@@ -64,14 +77,23 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: Returns [facets](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#contextual-facet-values-and-counts), their facet values, and the number of matching facet values.
+ description: |
+ Facets for which to retrieve facet values that match the search criteria and the number of matching facet values.
+
+ To retrieve all facets, use the wildcard character `*`.
+ For more information, see [facets](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#contextual-facet-values-and-counts).
default: []
+ example: ['*']
x-categories:
- Faceting
facetingAfterDistinct:
type: boolean
- description: >
- Forces faceting to be applied after [de-duplication](https://www.algolia.com/doc/guides/managing-results/refine-results/grouping/) (with the distinct feature). Alternatively, the `afterDistinct` [modifier](https://www.algolia.com/doc/api-reference/api-parameters/attributesForFaceting/#modifiers) of `attributesForFaceting` allows for more granular control.
+ description: |
+ Whether faceting should be applied after deduplication with `distinct`.
+
+ This leads to accurate facet counts when using faceting in combination with `distinct`.
+ It's usually better to use `afterDistinct` modifiers in the `attributesForFaceting` setting,
+ as `facetingAfterDistinct` only computes correct facet counts if all records have the same facet values for the `attributeForDistinct`.
default: false
x-categories:
- Faceting
@@ -79,18 +101,12 @@ baseSearchParamsWithoutQuery:
$ref: '#/page'
offset:
type: integer
- description: >
- Specifies the offset of the first hit to return.
-
- > **Note**: Using `page` and `hitsPerPage` is the recommended method for [paging results](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/). However, you can use `offset` and `length` to implement [an alternative approach to paging](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/#retrieving-a-subset-of-records-with-offset-and-length).
+ description: Position of the first hit to retrieve.
x-categories:
- Pagination
length:
type: integer
- description: >
- Sets the number of hits to retrieve (for use with `offset`).
-
- > **Note**: Using `page` and `hitsPerPage` is the recommended method for [paging results](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/). However, you can use `offset` and `length` to implement [an alternative approach to paging](https://www.algolia.com/doc/guides/building-search-ui/ui-and-ux-patterns/pagination/js/#retrieving-a-subset-of-records-with-offset-and-length).
+ description: Number of hits to retrieve (used in combination with `offset`).
minimum: 1
maximum: 1000
x-categories:
@@ -105,7 +121,7 @@ baseSearchParamsWithoutQuery:
$ref: '#/aroundPrecision'
minimumAroundRadius:
type: integer
- description: Minimum radius (in meters) used for a geographical search when `aroundRadius` isn't set.
+ description: Minimum radius (in meters) for a search around a location when `aroundRadius` isn't set.
minimum: 1
x-categories:
- Geo-Search
@@ -117,7 +133,12 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: Changes the default values of parameters that work best for a natural language query, such as `ignorePlurals`, `removeStopWords`, `removeWordsIfNoResults`, `analyticsTags`, and `ruleContexts`. These parameters work well together when the query consists of fuller natural language strings instead of keywords, for example when processing voice search queries.
+ description: |
+ ISO language codes that adjust settings that are useful for processing natural language queries (as opposed to keyword searches):
+
+ - Sets `removeStopWords` and `ignorePlurals` to the list of provided languages.
+ - Sets `removeWordsIfNoResults` to `allOptional`.
+ - Adds a `natural_language` attribute to `ruleContexts` and `analyticsTags`.
default: []
x-categories:
- Languages
@@ -125,47 +146,52 @@ baseSearchParamsWithoutQuery:
type: array
items:
type: string
- description: Assigns [rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#whats-a-context) to search queries.
+ description: |
+ Assigns a rule context to the search query.
+
+ [Rule contexts](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#whats-a-context) are strings that you can use to trigger matching rules.
default: []
+ example: [mobile]
x-categories:
- Rules
personalizationImpact:
type: integer
- description: Defines how much [Personalization affects results](https://www.algolia.com/doc/guides/personalization/personalizing-results/in-depth/configuring-personalization/#understanding-personalization-impact).
+ description: |
+ Impact that Personalization should have on this search.
+
+ The higher this value is, the more Personalization determines the ranking compared to other factors.
+ For more information, see [Understanding Personalization impact](https://www.algolia.com/doc/guides/personalization/personalizing-results/in-depth/configuring-personalization/#understanding-personalization-impact).
default: 100
+ minimum: 0
+ maximum: 100
x-categories:
- Personalization
userToken:
$ref: '#/userToken'
getRankingInfo:
type: boolean
- description: Incidates whether the search response includes [detailed ranking information](https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/in-depth/understanding-the-api-response/#ranking-information).
+ description: Whether the search response should include detailed ranking information.
default: false
x-categories:
- Advanced
- explain:
- type: array
- items:
- type: string
- description: Enriches the API's response with information about how the query was processed.
- default: []
- x-categories:
- - Advanced
synonyms:
type: boolean
- description: Whether to take into account an index's synonyms for a particular search.
+ description: Whether to take into account an index's synonyms for this search.
default: true
x-categories:
- Advanced
clickAnalytics:
type: boolean
- description: Indicates whether a query ID parameter is included in the search response. This is required for [tracking click and conversion events](https://www.algolia.com/doc/guides/sending-events/concepts/event-types/#events-related-to-algolia-requests).
+ description: |
+ Whether to include a `queryID` attribute in the response.
+
+ The query ID is a unique identifier for a search query and is required for tracking [click and conversion events](https://www.algolia.com/guides/sending-events/getting-started/).
default: false
x-categories:
- Analytics
analytics:
type: boolean
- description: Indicates whether this query will be included in [analytics](https://www.algolia.com/doc/guides/search-analytics/guides/exclude-queries/).
+ description: Whether this search will be included in Analytics.
default: true
x-categories:
- Analytics
@@ -179,19 +205,20 @@ baseSearchParamsWithoutQuery:
- Analytics
percentileComputation:
type: boolean
- description: Whether to include or exclude a query from the processing-time percentile computation.
+ description: Whether to include this search when calculating processing-time percentiles.
default: true
x-categories:
- Advanced
enableABTest:
type: boolean
- description: Incidates whether this search will be considered in A/B testing.
+ description: Whether to enable A/B testing for this search.
default: true
x-categories:
- Advanced
searchParamsString:
type: object
+ title: Search parameters as query string
additionalProperties: false
x-discriminator-fields:
- params
@@ -207,62 +234,91 @@ paramsAsString:
userToken:
type: string
- description: Associates a [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) with the current search.
- example: '123456'
+ description: |
+ Unique pseudonymous or anonymous user identifier.
+
+ This helps with analytics and click and conversion events.
+ For more information, see [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/).
+ example: test-user-123
x-categories:
- Personalization
query:
type: string
- description: Text to search for in an index.
+ description: Search query.
default: ''
x-categories:
- Search
page:
type: integer
- description: Page to retrieve (the first page is `0`, not `1`).
+ description: Page of search results to retrieve.
default: 0
+ minimum: 0
x-categories:
- Pagination
aroundRadius:
- description: >
- [Maximum radius](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#increase-the-search-radius) for a geographical search (in meters).
+ description: |
+ Maximum radius for a search around a central location.
+
+ This parameter works in combination with the `aroundLatLng` and `aroundLatLngViaIP` parameters.
+ By default, the search radius is determined automatically from the density of hits around the central location.
+ The search radius is small if there are many hits close to the central coordinates.
oneOf:
- type: integer
minimum: 1
+ description: Maximum search radius around a central location in meters.
- $ref: '#/aroundRadiusAll'
x-categories:
- Geo-Search
aroundPrecision:
- description: Precision of a geographical search (in meters), to [group results that are more or less the same distance from a central point](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/in-depth/geo-ranking-precision/).
+ description: |
+ Precision of a coordinate-based search in meters to group results with similar distances.
+
+ The Geo ranking criterion considers all matches within the same range of distances to be equal.
oneOf:
- type: integer
default: 10
+ description: |
+ Distance in meters to group results by similar distances.
+
+ For example, if you set `aroundPrecision` to 100, records wihin 100 meters to the central coordinate are considered to have the same distance,
+ as are records between 100 and 199 meters.
- $ref: '#/aroundPrecisionFromValue'
x-categories:
- Geo-Search
aroundPrecisionFromValue:
- description: Precision of a geographical search (in meters), to [group results that are more or less the same distance from a central point](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/in-depth/geo-ranking-precision/).
+ title: range objects
type: array
items:
type: object
+ description: Range object with lower and upper values in meters to define custom ranges.
properties:
from:
type: integer
+ description: Lower boundary of a range in meters. The Geo ranking criterion considers all records within the range to be equal.
+ example: 20
value:
type: integer
+ description: Upper boundary of a range in meters. The Geo ranking criterion considers all records within the range to be equal.
aroundRadiusAll:
+ title: all
type: string
+ description: Return all records with a valid `_geoloc` attribute. Don't filter by distance.
enum: [all]
aroundLatLng:
type: string
- description: Search for entries [around a central location](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filter-around-a-central-point), enabling a geographical search within a circular area.
+ description: |
+ Coordinates for the center of a circle, expressed as a comma-separated string of latitude and longitude.
+
+ Only records included within circle around this central location are included in the results.
+ The radius of the circle is determined by the `aroundRadius` and `minimumAroundRadius` settings.
+ This parameter is ignored if you also specify `insidePolygon` or `insideBoundingBox`.
example: '40.71,-74.01'
default: ''
x-categories:
@@ -270,7 +326,7 @@ aroundLatLng:
aroundLatLngViaIP:
type: boolean
- description: Search for entries around a location. The location is automatically computed from the requester's IP address.
+ description: Whether to obtain the coordinates from the request's IP address.
default: false
x-categories:
- Geo-Search
@@ -280,10 +336,20 @@ insideBoundingBox:
items:
type: array
items:
+ minItems: 4
+ maxItems: 4
type: number
format: double
- description: Search inside a [rectangular area](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas) (in geographical coordinates).
- example: [[47.3165, 4.9665, 47.3424, 5.0201], [40.9234, 2.1185, 38.6430, 1.9916]]
+ description: |
+ Coordinates for a rectangular area in which to search.
+
+ Each bounding box is defined by the two opposite points of its diagonal, and expressed as latitude and longitude pair:
+ `[p1 lat, p1 long, p2 lat, p2 long]`.
+ Provide multiple bounding boxes as nested arrays.
+ For more information, see [rectangular area](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).
+ example:
+ - [47.3165, 4.9665, 47.3424, 5.0201]
+ - [40.9234, 2.1185, 38.6430, 1.9916]
x-categories:
- Geo-Search
@@ -292,16 +358,27 @@ insidePolygon:
items:
type: array
items:
+ minItems: 6
+ maxItems: 20000
type: number
format: double
- description: Search inside a [polygon](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas) (in geographical coordinates).
- example: [[47.3165, 4.9665, 47.3424, 5.0201, 47.32, 4.9], [40.9234, 2.1185, 38.6430, 1.9916, 39.2587, 2.0104]]
+ description: |
+ Coordinates of a polygon in which to search.
+
+ Polygons are defined by 3 to 10,000 points. Each point is represented by its latitude and longitude.
+ Provide multiple polygons as nested arrays.
+ For more information, see [filtering inside polygons](https://www.algolia.com/doc/guides/managing-results/refine-results/geolocation/#filtering-inside-rectangular-or-polygonal-areas).
+ This parameter is ignored, if you also specify `insideBoundingBox`.
+ example:
+ - [47.3165, 4.9665, 47.3424, 5.0201, 47.32, 4.9]
+ - [40.9234, 2.1185, 38.6430, 1.9916, 39.2587, 2.0104]
x-categories:
- Geo-Search
# There is duplicated logic here because we want to keep a correct description
# and using `$ref` override everything.
searchFiltersArrayString:
+ title: search filter array
type: array
items:
type: string
@@ -313,22 +390,54 @@ mixedSearchFilters:
listOfSearchFilters:
type: array
+ title: search filters
items:
$ref: '#/mixedSearchFilters'
filters:
type: string
- description: >
- [Filter](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/) the query with numeric, facet, or tag filters.
+ description: |
+ Filter the search so that only records with matching values are included in the results.
+
+ These filters are supported:
+
+ - **Numeric filters.** ` `, where `` is one of `<`, `<=`, `=`, `!=`, `>`, `>=`.
+ - **Ranges.** `: TO ` where `` and `` are the lower and upper limits of the range (inclusive).
+ - **Facet filters.** `:` where `` is a facet attribute (case-sensitive) and `` a facet value.
+ - **Tag filters.** `_tags:` or just `` (case-sensitive).
+ - **Boolean filters.** `: true | false`.
+
+ You can combine filters with `AND`, `OR`, and `NOT` operators with the following restrictions:
+
+ - You can only combine filters of the same type with `OR`.
+ **Not supported:** `facet:value OR num > 3`.
+ - You can't use `NOT` with combinations of filters.
+ **Not supported:** `NOT(facet:value OR facet:value)`
+ - You can't combine conjunctions (`AND`) with `OR`.
+ **Not supported:** `facet:value OR (facet:value AND facet:value)`
+
+ Use quotes around your filters, if the facet attribute name or facet value has spaces, keywords (`OR`, `AND`, `NOT`), or quotes.
+ If a facet attribute is an array, the filter matches if it matches at least one element of the array.
+
+ For more information, see [Filters](https://www.algolia.com/doc/guides/managing-results/refine-results/filtering/).
example: '(category:Book OR category:Ebook) AND _tags:published'
default: ''
x-categories:
- Filtering
facetFilters:
- description: >
- [Filter hits by facet value](https://www.algolia.com/doc/api-reference/api-parameters/facetFilters/).
- example: ['category:Book','author:John Doe']
+ description: |
+ Filter the search by facet values, so that only records with the same facet values are retrieved.
+
+ **Prefer using the `filters` parameter, which supports all filter types and combinations with boolean operators.**
+
+ - `[filter1, filter2]` is interpreted as `filter1 AND filter2`.
+ - `[[filter1, filter2], filter3]` is interpreted as `filter1 OR filter2 AND filter3`.
+ - `facet:-value` is interpreted as `NOT facet:value`.
+
+ While it's best to avoid attributes that start with a `-`, you can still filter them by escaping with a backslash:
+ `facet:\-value`.
+ example: [['category:Book', 'category:-Movie'], 'author:John Doe']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -336,9 +445,15 @@ facetFilters:
- Filtering
tagFilters:
- description: >
- [Filter hits by tags](https://www.algolia.com/doc/api-reference/api-parameters/tagFilters/).
- example: [['Book','Movie'],'SciFi']
+ description: |
+ Filter the search by values of the special `_tags` attribute.
+
+ **Prefer using the `filters` parameter, which supports all filter types and combinations with boolean operators.**
+
+ Different from regular facets, `_tags` can only be used for filtering (including or excluding records).
+ You won't get a facet count.
+ The same combination and escaping rules apply as for `facetFilters`.
+ example: [['Book', 'Movie'], 'SciFi']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -346,9 +461,15 @@ tagFilters:
- Filtering
numericFilters:
- description: >
- [Filter on numeric attributes](https://www.algolia.com/doc/api-reference/api-parameters/numericFilters/).
- example: [['inStock = 1','deliveryDate < 1441755506'],'price < 1000']
+ description: |
+ Filter by numeric facets.
+
+ **Prefer using the `filters` parameter, which supports all filter types and combinations with boolean operators.**
+
+ You can use numeric comparison operators: `<`, `<=`, `=`, `!=`, `>`, `>=`. Comparsions are precise up to 3 decimals.
+ You can also provide ranges: `facet: TO `. The range includes the lower and upper boundaries.
+ The same combination rules apply as for `facetFilters`.
+ example: [['inStock = 1', 'deliveryDate < 1441755506'], 'price < 1000']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
@@ -357,10 +478,17 @@ numericFilters:
optionalFilters:
description: |
- Create filters to boost or demote records.
-
- Records that match the filter are ranked higher for positive and lower for negative optional filters. In contrast to regular filters, records that don't match the optional filter are still included in the results, only their ranking is affected.
- example: ['category:Book','author:John Doe']
+ Filters to promote or demote records in the search results.
+
+ Optional filters work like facet filters, but they don't exclude records from the search results.
+ Records that match the optional filter rank before records that don't match.
+ If you're using a negative filter `facet:-value`, matching records rank after records that don't match.
+
+ - Optional filters don't work on virtual replicas.
+ - Optional filters are applied _after_ sort-by attributes.
+ - Optional filters don't work with numeric attributes.
+
+ example: ['category:Book', 'author:John Doe']
oneOf:
- $ref: '#/listOfSearchFilters'
- type: string
diff --git a/specs/common/schemas/SnippetResult.yml b/specs/common/schemas/SnippetResult.yml
index b05074f861..fad934d77e 100644
--- a/specs/common/schemas/SnippetResult.yml
+++ b/specs/common/schemas/SnippetResult.yml
@@ -1,6 +1,6 @@
snippetResultOption:
type: object
- description: Snippeted attributes show parts of the matched attributes. Only returned when attributesToSnippet is non-empty.
+ description: Snippets that show the context around a matching search query.
additionalProperties: false
properties:
value:
@@ -13,13 +13,14 @@ snippetResultOption:
snippetResultOptionMap:
type: object
- description: Snippeted attributes show parts of the matched attributes. Only returned when attributesToSnippet is non-empty.
+ description: Snippets that show the context around a matching search query.
additionalProperties:
+ x-additionalPropertiesName: attribute
$ref: '#/snippetResultOption'
snippetResultOptionArray:
type: array
- description: Snippeted attributes show parts of the matched attributes. Only returned when attributesToSnippet is non-empty.
+ description: Snippets that show the context around a matching search query.
items:
$ref: '#/snippetResultOption'
@@ -31,6 +32,7 @@ snippetResult:
snippetResultMap:
type: object
- description: Snippeted attributes show parts of the matched attributes. Only returned when attributesToSnippet is non-empty.
+ description: Snippets that show the context around a matching search query.
additionalProperties:
+ x-additionalPropertiesName: attribute
$ref: '#/snippetResult'
diff --git a/specs/search/common/enums.yml b/specs/search/common/enums.yml
index 78e44425e9..2493379792 100644
--- a/specs/search/common/enums.yml
+++ b/specs/search/common/enums.yml
@@ -1,15 +1,17 @@
searchStrategy:
type: string
enum: [none, stopIfEnoughMatches]
- description: >
- - `none`: executes all queries.
- - `stopIfEnoughMatches`: executes queries one by one, stopping further query execution as soon as a query matches at least the `hitsPerPage` number of results.
+ description: |
+ Strategy for multiple search queries:
+
+ - `none`. Run all queries.
+ - `stopIfEnoughMatches`. Run the queries one by one, stopping as soon as a query matches at least the `hitsPerPage` number of results.
operationType:
type: string
enum: [move, copy]
example: copy
- description: Operation to perform (_move_ or _copy_).
+ description: Operation to perform on the index.
scopeType:
type: string
@@ -24,7 +26,7 @@ dictionaryEntryState:
type: string
enum: [enabled, disabled]
default: enabled
- description: Indicates whether a dictionary entry is active (`enabled`) or inactive (`disabled`).
+ description: Whether a dictionary entry is active.
logType:
type: string
@@ -34,4 +36,4 @@ logType:
taskStatus:
type: string
enum: [published, notPublished]
- description: _published_ if the task has been processed, _notPublished_ otherwise.
+ description: Task status, `published` if the task is completed, `notPublished` otherwise.
diff --git a/specs/search/common/parameters.yml b/specs/search/common/parameters.yml
index 85d5dacbc0..6cd63fa10a 100644
--- a/specs/search/common/parameters.yml
+++ b/specs/search/common/parameters.yml
@@ -11,7 +11,7 @@ HitsPerPage:
# headers
UserIDInHeader:
name: X-Algolia-User-ID
- description: userID to assign.
+ description: User ID to assign.
in: header
required: true
schema:
@@ -21,7 +21,7 @@ UserIDInHeader:
# path
UserIDInPath:
name: userID
- description: userID to assign.
+ description: User ID to assign.
in: path
required: true
schema:
@@ -32,5 +32,5 @@ UserIDInPath:
userID:
type: string
pattern: '^[a-zA-Z0-9 \-*.]+$'
- description: userID of the user.
+ description: User ID.
example: user1
diff --git a/specs/search/common/schemas/BrowseParams.yml b/specs/search/common/schemas/BrowseParams.yml
index fc1cfb6cd0..6ef8cc476f 100644
--- a/specs/search/common/schemas/BrowseParams.yml
+++ b/specs/search/common/schemas/BrowseParams.yml
@@ -14,10 +14,9 @@ cursor:
properties:
cursor:
type: string
- description: >
- Cursor indicating the location to resume browsing from. Must match the value returned by the previous call.
+ description: |
+ Cursor to get the next page of the response.
- Pass this value to the subsequent browse call to get the next page of results.
-
- When the end of the index has been reached, `cursor` is absent from the response.
+ The parameter must match the value returned in the response of a previous request.
+ The last page of the response does not return a `cursor` attribute.
example: jMDY3M2MwM2QwMWUxMmQwYWI0ZTN
diff --git a/specs/search/common/schemas/Hit.yml b/specs/search/common/schemas/Hit.yml
index f48cd48e73..9f284c8821 100644
--- a/specs/search/common/schemas/Hit.yml
+++ b/specs/search/common/schemas/Hit.yml
@@ -1,6 +1,9 @@
hit:
type: object
- description: A single hit.
+ description: |
+ Search result.
+
+ A hit is a record from your index, augmented with special attributes for highlighting, snippeting, and ranking.
x-is-generic: true
additionalProperties: true
required:
@@ -23,19 +26,24 @@ _distinctSeqID:
rankingInfo:
type: object
+ description: Object with detailed information about the record's ranking.
additionalProperties: false
properties:
filters:
type: integer
- description: This field is reserved for advanced usage.
+ minimum: 0
+ description: Whether a filter matched the query.
firstMatchedWord:
type: integer
- description: Position of the most important matched attribute in the attributes to index list.
+ minimum: 0
+ description: Position of the first matched word in the best matching attribute of the record.
geoDistance:
type: integer
+ minimum: 0
description: Distance between the geo location in the search query and the best matching geo location in the record, divided by the geo precision (in meters).
geoPrecision:
type: integer
+ minimum: 1
description: Precision used when computing the geo distance, in meters.
matchedGeoLocation:
$ref: '#/matchedGeoLocation'
@@ -43,25 +51,29 @@ rankingInfo:
$ref: '#/personalization'
nbExactWords:
type: integer
+ minimum: 0
description: Number of exactly matched words.
nbTypos:
type: integer
+ minimum: 0
description: Number of typos encountered when matching the record.
promoted:
type: boolean
- description: Present and set to true if a Rule promoted the hit.
+ description: Whether the record was promoted by a rule.
proximityDistance:
type: integer
- description: When the query contains more than one word, the sum of the distances between matched words (in meters).
+ minimum: 0
+ description: Number of words between multiple matches in the query plus 1. For single word queries, `proximityDistance` is 0.
userScore:
type: integer
- description: Custom ranking for the object, expressed as a single integer value.
+ description: Overall ranking of the record, expressed as a single integer. This attribute is internal.
words:
type: integer
- description: Number of matched words, including prefixes and typos.
+ minimum: 1
+ description: Number of matched words.
promotedByReRanking:
type: boolean
- description: Wether the record are promoted by the re-ranking strategy.
+ description: Whether the record is re-ranked.
required:
- promoted
- nbTypos
diff --git a/specs/search/common/schemas/SearchForFacetValuesResponse.yml b/specs/search/common/schemas/SearchForFacetValuesResponse.yml
index a995b3196f..d21e13252c 100644
--- a/specs/search/common/schemas/SearchForFacetValuesResponse.yml
+++ b/specs/search/common/schemas/SearchForFacetValuesResponse.yml
@@ -5,10 +5,11 @@ searchForFacetValuesResponse:
- facetHits
- exhaustiveFacetsCount
x-discriminator-fields:
- - facetHits
+ - facetHits
properties:
facetHits:
type: array
+ description: Matching facet values.
items:
type: object
title: facetHits
@@ -25,7 +26,7 @@ searchForFacetValuesResponse:
highlighted:
$ref: '../../../common/schemas/HighlightResult.yml#/highlightedValue'
count:
- description: Number of records containing this facet value. This takes into account the extra search parameters specified in the query. Like for a regular search query, the [counts may not be exhaustive](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).
+ description: Number of records with this facet value. [The count may be approximated](https://support.algolia.com/hc/en-us/articles/4406975248145-Why-are-my-facet-and-hit-counts-not-accurate-).
type: integer
exhaustiveFacetsCount:
$ref: 'SearchResponse.yml#/exhaustiveFacetsCount'
diff --git a/specs/search/common/schemas/SearchQuery.yml b/specs/search/common/schemas/SearchQuery.yml
index c1960b04d8..630dc8fe82 100644
--- a/specs/search/common/schemas/SearchQuery.yml
+++ b/specs/search/common/schemas/SearchQuery.yml
@@ -58,7 +58,7 @@ searchTypeFacet:
type: string
enum: [facet]
default: facet
- description: >
+ description: |
- `default`: perform a search query
- `facet` [searches for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
@@ -66,6 +66,6 @@ searchTypeDefault:
type: string
enum: [default]
default: default
- description: >
+ description: |
- `default`: perform a search query
- `facet` [searches for facet values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values).
diff --git a/specs/search/common/schemas/SearchResponse.yml b/specs/search/common/schemas/SearchResponse.yml
index 01af5f300f..96dcdbe8e1 100644
--- a/specs/search/common/schemas/SearchResponse.yml
+++ b/specs/search/common/schemas/SearchResponse.yml
@@ -10,14 +10,18 @@ searchHits:
properties:
hits:
type: array
+ description: |
+ Search results (hits).
+
+ Hits are records from your index that match the search criteria, augmented with additional attributes, such as, for highlighting.
items:
$ref: 'Hit.yml#/hit'
query:
- $ref: '../../../common/schemas/SearchParams.yml#/query'
+ $ref: '../../../common/schemas/SearchParams.yml#/query'
params:
type: string
description: URL-encoded string of all search parameters.
- example: query=a&hitsPerPage=20
+ example: query=a&hitsPerPage=20
required:
- hits
- query
@@ -47,7 +51,7 @@ baseSearchResponse:
pattern: ^(-?\d+(\.\d+)?),\s*(-?\d+(\.\d+)?)$
automaticRadius:
type: string
- description: Automatically-computed radius.
+ description: Distance from a central coordinate provided by `aroundLatLng`.
exhaustive:
type: object
title: exhaustive
@@ -87,10 +91,12 @@ baseSearchResponse:
title: facets
type: object
additionalProperties:
+ x-additionalPropertiesName: facet
type: object
additionalProperties:
+ x-additionalPropertiesName: facet count
type: integer
- description: Mapping of each facet name to the corresponding facet counts.
+ description: Facet counts.
example:
category:
food: 1
@@ -157,7 +163,7 @@ baseSearchResponse:
redirect:
title: redirect
type: object
- description: >
+ description: |
[Redirect results to a URL](https://www.algolia.com/doc/guides/managing-results/rules/merchandising-and-promoting/how-to/redirects/).
properties:
index:
@@ -174,7 +180,7 @@ baseSearchResponse:
type: string
description: Host name of the server that processed the request.
example: 'c2-uk-3.algolia.net'
- userData:
+ userData:
$ref: '../../../common/schemas/IndexSettings.yml#/userData'
queryID:
type: string
@@ -183,12 +189,12 @@ baseSearchResponse:
nbHits:
type: integer
- description: Number of hits the search query matched.
+ description: Number of results (hits).
example: 20
nbPages:
type: integer
- description: Number of pages of results for the current query.
+ description: Number of pages of results.
example: 1
exhaustiveFacetsCount:
diff --git a/specs/search/helpers/generateSecuredApiKey.yml b/specs/search/helpers/generateSecuredApiKey.yml
index e99718a815..d989b33be5 100644
--- a/specs/search/helpers/generateSecuredApiKey.yml
+++ b/specs/search/helpers/generateSecuredApiKey.yml
@@ -4,24 +4,31 @@ method:
tags:
- Api Keys
operationId: generateSecuredApiKey
- summary: Generate a secured API key without any calls to Algolia's servers.
- description:
- Generate a secured API key without any calls to Algolia's servers.
+ summary: Create secured API keys.
+ description: |
+ Generates a secured API key without any calls to Algolia's servers.
- When you need to restrict the scope of an API key, generate a secured API key on your server, without any calls to Algolia.
- You can't generate secured API keys from your Admin API key or from other secured API keys.
- When you generate a secured API key, you can define several restrictions, such as how long the key is valid for and which indexes it can access. The more restrictions you set, the longer the key will be. If the key is longer than 500 characters, you may have problems using it on some networks.
- If you want to limit the number of requests that can be made with a secured API key, you must also rate-limit the key that you use to generate it. You can create a rate-limited key in the Algolia dashboard or use the Add API key or Update API key methods of an API client.
+ Secured API keys are API keys that you generate on your server without any API request to Algolia.
+ Secured API keys help in environments where you can't easily update the client-side code, such as mobile apps,
+ or when you need to restrict access to a part of your index for every user.
+
+ When your users start searching, instead of using the Search API key, they request a short-lived secured API key from your server.
+ On your server, you use this method to create a secured API key, with any restrictions you'd like, such as filters, index access restrictions,
+ or expiration times. The API key gets longer the more restrictions you add.
+ Your users then use the secured API key to search with Algolia.
+
+ You can't create secured API keys from other secured API keys or from your Admin API key.
+ The generated API key can have the same restrictions as the parent API key, or be more restrictive.
parameters:
- in: query
name: apiKey
- description: The search-only API key that the secured API key will inherit its restrictions from.
+ description: API key from which the secured API key will inherit its restrictions.
required: true
schema:
type: string
- in: query
name: restrictions
- description: The options to add to the secured API key.
+ description: Restrictions to add to the API key.
required: true
schema:
$ref: '#/securedAPIKeyRestrictions'
@@ -43,29 +50,40 @@ securedAPIKeyRestrictions:
$ref: '../../common/schemas/SearchParams.yml#/searchParamsObject'
filters:
type: string
- description: >
- Filters that apply to every search made with the secured API key. You can add extra filters at search time with the filters query parameter.
-
- For example, if you set the filter group:admin on your generated API key, and you add groups:press OR groups:visitors with the filters query parameter, your final search filter is equivalent to groups:admin AND (groups:press OR groups:visitors).
+ description: |
+ Filters that apply to every search made with the secured API key.
+ Extra filters added at search time will be combined with `AND`.
+ For example, if you set `group:admin` as fixed filter on your generated API key,
+ and add `groups:visitors` to the search query, the complete set of filters will be `group:admin AND groups:visitors`.
validUntil:
type: integer
format: int64
- description: Unix timestamp used to set the expiration date of the API key.
+ description: Timestamp in [Unix epoch time](https://en.wikipedia.org/wiki/Unix_time) when the API key should expire.
restrictIndices:
type: array
items:
type: string
- description: Index names that can be queried.
+ description: |
+ Index names or patterns that this API key can access.
+ By default, an API key can access all indices in the same application.
+
+ You can use leading and trailing wildcard characters (`*`):
+
+ - `dev_*` matches all indices starting with "dev_".
+ - `*_dev` matches all indices ending with "_dev".
+ - `*_products_*` matches all indices containing "_products_".
restrictSources:
type: string
- description: >
- IPv4 network allowed to use the generated key. Use this to protect against API key leaking and reuse.
+ description: |
+ IP network that are allowed to use this key.
- You can only provide a single source, but you can specify a range of IPs (for example, 192.168.1.0/24).
+ You can only add a single source, but you can provide a range of IP addresses.
+ Use this to protect against API key leaking and reuse.
+ example: '192.168.1.0/24'
userToken:
type: string
- description: >
- Unique user IP address.
+ description: |
+ Pseudonymous user identifier to restrict usage of this API key to specific users.
- This can be useful when you want to impose a rate limit on specific users. By default, rate limits are set based on the IP address. This can become an issue when several users search from the same IP address. To avoid this, you can set a unique userToken for each user when generating their API key. This lets you restrict each user to a maximum number of API calls per hour, even if they share their IP with another user.
- Specifying the userToken in a secured API key is also a good security practice as it ensures users don't change it. Many features like Analytics, Personalization, and Dynamic Re-ranking rely on the authenticity of user identifiers. Setting the userToken at the API key level ensures that downstream services work as expected and prevents abuse.
+ By default, rate limits are set based on IP addresses. This can be an issue if many users search from the same IP address.
+ To avoid this, add a user token to each generated API key.
diff --git a/specs/search/helpers/waitForApiKey.yml b/specs/search/helpers/waitForApiKey.yml
index 34b20f2d09..e21725d3f8 100644
--- a/specs/search/helpers/waitForApiKey.yml
+++ b/specs/search/helpers/waitForApiKey.yml
@@ -4,24 +4,24 @@ method:
tags:
- Api Keys
operationId: waitForApiKey
- summary: Wait for an API key to be added, deleted, or updated.
- description: description
+ summary: Wait for an API key operation.
+ description: Waits for an API key to be added, updated, or deleted.
parameters:
- in: query
name: operation
- description: The `operation` that was done on a `key`.
+ description: Whether the API key was created, updated, or deleted.
required: true
schema:
$ref: '#/apiKeyOperation'
- in: query
name: key
- description: The `key` that has been added, deleted or updated.
+ description: API key to wait for.
required: true
schema:
type: string
- in: query
name: apiKey
- description: Used to compare fields of the getApiKey response on an `update` operation, to check if the `key` has been updated.
+ description: Used to compare fields of the `getApiKey` response on an `update` operation, to check if the `key` has been updated.
required: false
schema:
$ref: '../paths/keys/common/schemas.yml#/apiKey'
diff --git a/specs/search/paths/advanced/getLogs.yml b/specs/search/paths/advanced/getLogs.yml
index 323ee304af..aed17207bf 100644
--- a/specs/search/paths/advanced/getLogs.yml
+++ b/specs/search/paths/advanced/getLogs.yml
@@ -4,19 +4,17 @@ get:
operationId: getLogs
x-acl:
- logs
- description: >
+ description: |
The request must be authenticated by an API key with the [`logs` ACL](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
- Logs are held for the last seven days. There's also a logging limit of 1,000 API calls per server.
-
- This request counts towards your [operations quota](https://support.algolia.com/hc/en-us/articles/4406981829777-How-does-Algolia-count-records-and-operations-) but doesn't appear in the logs itself.
-
- > **Note**: To fetch the logs for a Distributed Search Network (DSN) cluster, target the [DSN's endpoint](https://www.algolia.com/doc/guides/scaling/distributed-search-network-dsn/#accessing-dsn-servers).
- summary: Return the latest log entries.
+ - Logs are held for the last seven days.
+ - Up to 1,000 API requests per server are logged.
+ - This request counts towards your [operations quota](https://support.algolia.com/hc/en-us/articles/4406981829777-How-does-Algolia-count-records-and-operations-) but doesn't appear in the logs itself.
+ summary: Retrieve log entries.
parameters:
- name: offset
in: query
- description: First log entry to retrieve. Sorted by decreasing date with 0 being the most recent.
+ description: First log entry to retrieve. The most recent entries are listed first.
schema:
type: integer
default: 0
@@ -29,14 +27,18 @@ get:
maximum: 1000
- name: indexName
in: query
- description: Index for which log entries should be retrieved. When omitted, log entries are retrieved for all indices.
- example: 'products'
+ description: |
+ Index for which to retrieve log entries.
+ By default, log entries are retrieved for all indices.
+ example: products
schema:
type: string
nullable: true
- name: type
in: query
- description: Type of log entries to retrieve. When omitted, all log entries are retrieved.
+ description: |
+ Type of log entries to retrieve.
+ By default, all log entries are retrieved.
schema:
$ref: '../../common/enums.yml#/logType'
responses:
@@ -59,64 +61,70 @@ get:
properties:
timestamp:
type: string
- description: Timestamp in [ISO 8601](https://wikipedia.org/wiki/ISO_8601) format.
- example: '2023-03-08T12:34:56Z'
+ description: Timestamp of the API request in ISO 8601 format.
+ example: 2023-03-08T12:34:56Z
method:
type: string
- description: HTTP method of the performed request.
- example: 'GET'
+ description: HTTP method of the request.
+ example: GET
answer_code:
type: string
- description: HTTP response code.
+ description: HTTP status code of the response.
example: '200'
query_body:
type: string
- description: Request body. Truncated after 1,000 characters.
- example: '\n{\n \"requests\": [\n {\n \"indexName\": \"best_buy\",\n \"params\": \"query=&hitsPerPage=10&page=0&attributesToRetrieve=*&highlightPreTag=%3Cais-highlight-0000000000%3E&highlightPostTag=%3C%2Fais-highlight-0000000000%3E&getRankingInfo=1&facets=%5B%22brand%22%2C%22categories%22%2C%22free_shipping%22%2C%22type%22%5D&tagFilters=\"\n }\n ]\n}\n'
+ maxLength: 1000
+ description: Request body.
+ example: '{\n \"requests\": [\n {\n \"indexName\": \"best_buy\",\n \"params\": \"query=&hitsPerPage=10&page=0&attributesToRetrieve=*&highlightPreTag=%3Cais-highlight-0000000000%3E&highlightPostTag=%3C%2Fais-highlight-0000000000%3E&getRankingInfo=1&facets=%5B%22brand%22%2C%22categories%22%2C%22free_shipping%22%2C%22type%22%5D&tagFilters=\"\n }\n ]\n}\n'
answer:
type: string
- description: Answer body. Truncated after 1,000 characters.
- example: >
+ maxLength: 1000
+ description: Response body.
+ example: |
'n{\n \"results\": [\n {\n \"hits\": [\n {\n \"name\": \"Amazon - Fire TV Stick\",\n \"description\": \"Amazon Fire TV Stick connects to your TV's HDMI port. Just grab and go to enjoy Netflix, Prime Instant Video, Hulu Plus, YouTube.com, music, and much more.\",\n \"brand\": \"Amazon\",\n \"categories\": [\n \"TV & Home Theater\",\n \"Streaming Media Players\"\n ],\n \"hierarchicalCategories\": {\n \"lvl0\": \"TV & Home Theater\",\n \"lvl1\": \"TV & Home Theater > Streaming Media Players\"\n },\n \"type\": \"Streaming media plyr\",\n \"price\": 39.99,\n \"price_range\": \"1 - 50\",\n \"image\": \"https:\/\/cdn-demo.algolia.com\/bestbuy\/9999119_sb.jpg\",\n \"url\": \"http:\/\/www.bestbuy.com\/site\/amazon-fire-tv-stick\/9999119.p?id=1219460752591&skuId=9999119&cmp=RMX&ky=1uWSHMdQqBeVJB9cXgEke60s5EjfS6M1W\",\n \"free_shipping\": false,\n \"popularity\": 9843,\n \"rating\": 4,\n \"objectID\": \"9999119\"\n'
url:
type: string
- description: Request URL.
- example: '/1/indexes'
+ format: uri
+ description: URL of the API endpoint.
+ example: /1/indexes
ip:
type: string
+ format: ipv4
description: IP address of the client that performed the request.
- example: '127.0.0.1'
+ example: 93.184.216.34
query_headers:
type: string
- description: Request headers (API key is obfuscated).
- example: 'User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5\nHost: localhost.algolia.com:8080\nAccept: */*\nContent-Type: application/json; charset=utf-8\nX-Algolia-API-Key: 20f***************************\nX-Algolia-Application-Id: MyApplicationID\n'
+ description: Request headers (API keys are obfuscated).
+ example: 'User-Agent: curl/7.24.0 (x86_64-apple-darwin12.0) libcurl/7.24.0 OpenSSL/0.9.8x zlib/1.2.5\nHost: example.com\nAccept: */*\nContent-Type: application/json; charset=utf-8\nX-Algolia-API-Key: 20f***************************\nX-Algolia-Application-Id: MyApplicationID\n'
sha1:
type: string
description: SHA1 signature of the log entry.
- example: '26c53bd7e38ca71f4741b71994cd94a600b7ac68'
+ example: 26c53bd7e38ca71f4741b71994cd94a600b7ac68
nb_api_calls:
type: string
- description: Number of API calls.
+ description: Number of API requests.
example: '1'
processing_time_ms:
type: string
- description: Processing time for the query. Doesn't include network time.
+ description: |
+ Processing time for the query in milliseconds.
+ This doesn't include latency due to the network.
example: '2'
index:
type: string
description: Index targeted by the query.
- example: 'best_buy'
+ example: products
query_params:
type: string
description: Query parameters sent with the request.
example: 'query=georgia&attributesToRetrieve=name,city,country'
query_nb_hits:
type: string
- description: Number of hits returned for the query.
+ description: Number of search results (hits) returned for the query.
example: '1'
inner_queries:
type: array
- description: Performed queries for the given request.
+ description: Queries performed for the given request.
items:
type: object
title: logQuery
@@ -124,15 +132,15 @@ get:
index_name:
type: string
description: Index targeted by the query.
- example: 'best_buy'
+ example: products
user_token:
type: string
- description: User identifier.
- example: '93.189.166.128'
+ description: A user identifier.
+ example: 93.189.166.128
query_id:
type: string
description: Unique query identifier.
- example: '313453231'
+ example: 96f59a3145dd9bd8963dc223950507c8
required:
- timestamp
- method
diff --git a/specs/search/paths/advanced/getTask.yml b/specs/search/paths/advanced/getTask.yml
index 8451854770..5d68282dd6 100644
--- a/specs/search/paths/advanced/getTask.yml
+++ b/specs/search/paths/advanced/getTask.yml
@@ -4,8 +4,15 @@ get:
operationId: getTask
x-acl:
- addObject
- description: Some operations, such as copying an index, will respond with a `taskID` value. Use this value here to check the status of that task.
- summary: Check a task's status.
+ description: |
+ Checks the status of a given task.
+
+ Indexing tasks are asynchronous.
+ When you add, update, or delete records or indices,
+ a task is created on a queue and completed depending on the load on the server.
+
+ The indexing tasks' responses include a task ID that you can use to check the status.
+ summary: Check task status.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- name: taskID
diff --git a/specs/search/paths/dictionaries/batchDictionaryEntries.yml b/specs/search/paths/dictionaries/batchDictionaryEntries.yml
index e0cd7c3cc0..774d4df061 100644
--- a/specs/search/paths/dictionaries/batchDictionaryEntries.yml
+++ b/specs/search/paths/dictionaries/batchDictionaryEntries.yml
@@ -4,8 +4,8 @@ post:
operationId: batchDictionaryEntries
x-acl:
- editSettings
- description: Add or remove a batch of dictionary entries.
- summary: Batch dictionary entries.
+ description: Adds or deletes multiple entries from your plurals, segmentation, or stop word dictionaries.
+ summary: Add or delete dictionary entries.
parameters:
- $ref: 'common/parameters.yml#/DictionaryName'
requestBody:
@@ -14,8 +14,7 @@ post:
application/json:
schema:
title: batchDictionaryEntriesParams
- description: >
- `batchDictionaryEntries` parameters.
+ description: Request body for updating dictionary entries.
type: object
required:
- requests
@@ -24,10 +23,10 @@ post:
clearExistingDictionaryEntries:
type: boolean
default: false
- description: Incidates whether to replace all custom entries in the dictionary with the ones sent with this request.
+ description: Whether to replace all custom entries in the dictionary with the ones sent with this request.
requests:
type: array
- description: Operations to batch.
+ description: List of additions and deletions to your dictionaries.
items:
title: batchDictionaryEntriesRequest
type: object
diff --git a/specs/search/paths/dictionaries/common/parameters.yml b/specs/search/paths/dictionaries/common/parameters.yml
index 267628e7fd..5d55dafe1b 100644
--- a/specs/search/paths/dictionaries/common/parameters.yml
+++ b/specs/search/paths/dictionaries/common/parameters.yml
@@ -2,7 +2,7 @@
DictionaryName:
in: path
name: dictionaryName
- description: Dictionary to search in.
+ description: Dictionary type in which to search.
required: true
schema:
$ref: '#/dictionaryType'
@@ -13,13 +13,12 @@ dictionaryType:
# misc
language:
- description: >
- [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
- example: 'en'
+ description: ISO code of a [supported language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+ example: en
type: string
standardEntries:
- description: >
+ description: |
Key-value pairs of [supported language ISO codes](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and boolean values.
additionalProperties: false
properties:
@@ -32,9 +31,10 @@ standardEntries:
standardEntry:
description: Key-value pair of a language ISO code and a boolean value.
- example: >
- {'fr': false}
+ example:
+ fr: false
type: object
nullable: true
additionalProperties:
+ x-additionalPropertiesName: language
type: boolean
diff --git a/specs/search/paths/dictionaries/common/schemas/Languages.yml b/specs/search/paths/dictionaries/common/schemas/Languages.yml
index cfa8350b29..10b00cc0e3 100644
--- a/specs/search/paths/dictionaries/common/schemas/Languages.yml
+++ b/specs/search/paths/dictionaries/common/schemas/Languages.yml
@@ -18,11 +18,8 @@ dictionaryLanguage:
type: object
additionalProperties: false
nullable: true
- description: Custom entries for a dictionary.
+ description: Dictionary type. If `null`, this dictionary type isn't supported for the language.
properties:
nbCustomEntries:
- description: >
- If `0`, the dictionary hasn't been customized and only contains standard entries provided by Algolia.
-
- If `null`, that feature isn't available or isn't supported for that language.
+ description: Number of custom dictionary entries.
type: integer
diff --git a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
index 1243706610..bb6992211a 100644
--- a/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
+++ b/specs/search/paths/dictionaries/common/schemas/SearchDictionaryEntriesResponse.yml
@@ -4,7 +4,7 @@ searchDictionaryEntriesResponse:
properties:
hits:
type: array
- description: The dictionary entries returned by the search.
+ description: Dictionary entries matching the search criteria.
items:
$ref: '#/dictionaryEntry'
page:
@@ -13,6 +13,11 @@ searchDictionaryEntriesResponse:
$ref: '../../../../common/schemas/SearchResponse.yml#/nbHits'
nbPages:
$ref: '../../../../common/schemas/SearchResponse.yml#/nbPages'
+ required:
+ - hits
+ - page
+ - nbHits
+ - nbPages
dictionaryEntry:
type: object
@@ -24,43 +29,28 @@ dictionaryEntry:
properties:
objectID:
type: string
- description: Unique identifier for a dictionary object.
- example: 'under'
+ description: Unique identifier for the dictionary entry.
+ example: 828afd405e1f4fe950b6b98c2c43c032
language:
type: string
- description: >
- [Supported language ISO code](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
- example: 'de'
+ description: ISO code of a [supported language](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/).
+ example: de
word:
type: string
- description: >
- Dictionary entry word. Usage depends on the type of dictionary entry.
-
- **`stopwordEntry`**
-
- The stop word you want to add or update. If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
-
- **`compoundEntry`**
-
- When `decomposition` is empty: adds `word` as a compound atom.
- For example, atom “kino” decomposes the query “kopfkino” into "kopf" and "kino".
-
- When `decomposition` isn't empty: creates a decomposition exception.
- For example, when decomposition is set to the ["hund", "hutte"] exception, "hundehutte" decomposes into “hund” and “hutte”, discarding the linking "e".
- example: 'down'
+ description: Matching dictionary word for `stopwords` and `compounds` dictionaries.
+ example: the
words:
type: array
- description: >
- Compound dictionary [word declensions](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/).
-
- If the entry already exists in Algolia's standard dictionary, you can override its behavior by adding it to the custom dictionary and setting its `state` to `disabled`.
- example: ['cheval','chevaux']
+ description: Matching words in the `plurals` dictionary including declensions.
+ example:
+ - cheval
+ - cheveaux
items:
type: string
decomposition:
type: array
- description: For compound entries, governs the behavior of the `word` parameter.
- example: ['kopf','schmerz','tablette']
+ description: Invividual components of a compound word in the `compounds` dictionary.
+ example: [kopf, schmerz, tablette]
items:
type: string
state:
diff --git a/specs/search/paths/dictionaries/dictionarySettings.yml b/specs/search/paths/dictionaries/dictionarySettings.yml
index e9b2ab4bc8..2f190ca0f8 100644
--- a/specs/search/paths/dictionaries/dictionarySettings.yml
+++ b/specs/search/paths/dictionaries/dictionarySettings.yml
@@ -4,8 +4,8 @@ get:
operationId: getDictionarySettings
x-acl:
- settings
- description: Get the languages for which [stop words are turned off](#tag/Dictionaries/operation/setDictionarySettings).
- summary: Get stop word settings.
+ summary: Retrieve dictionary settings.
+ description: Retrieves the languages for which standard dictionary entries are turned off.
responses:
'200':
description: OK
@@ -35,8 +35,8 @@ put:
operationId: setDictionarySettings
x-acl:
- editSettings
- description: Set stop word settings for a specific language.
- summary: Set stop word settings.
+ description: Turns standard stop word dictionary entries on or off for a given language.
+ summary: Update dictionary settings.
requestBody:
required: true
content:
@@ -45,7 +45,8 @@ put:
title: dictionarySettingsParams
type: object
additionalProperties: false
- description: Enable or turn off the built-in Algolia stop words for a specific language.
+ description: |
+ Turn on or off the built-in Algolia stop words for a specific language.
required:
- disableStandardEntries
properties:
diff --git a/specs/search/paths/dictionaries/getDictionaryLanguages.yml b/specs/search/paths/dictionaries/getDictionaryLanguages.yml
index a9c67d24f8..45bb73384e 100644
--- a/specs/search/paths/dictionaries/getDictionaryLanguages.yml
+++ b/specs/search/paths/dictionaries/getDictionaryLanguages.yml
@@ -4,8 +4,12 @@ get:
operationId: getDictionaryLanguages
x-acl:
- settings
- description: Lists Algolia's [supported languages](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/) and any customizations applied to each language's [stop word](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plural](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compound)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) features.
+ description: |
+ Lists supported languages with their supported dictionary types and number of custom entries.
summary: List available languages.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/in-depth/supported-languages/
+ description: Supported languages.
responses:
'200':
description: OK
@@ -15,6 +19,7 @@ get:
title: getDictionaryLanguagesResponse
type: object
additionalProperties:
+ x-additionalPropertiesName: language
$ref: 'common/schemas/Languages.yml#/languages'
'400':
$ref: '../../../common/responses/BadRequest.yml'
diff --git a/specs/search/paths/dictionaries/searchDictionaryEntries.yml b/specs/search/paths/dictionaries/searchDictionaryEntries.yml
index 162020631b..dde3123b98 100644
--- a/specs/search/paths/dictionaries/searchDictionaryEntries.yml
+++ b/specs/search/paths/dictionaries/searchDictionaryEntries.yml
@@ -6,7 +6,7 @@ post:
x-cacheable: true
x-acl:
- settings
- description: Search for standard and [custom](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/) entries in the [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), or [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/) dictionaries.
+ description: Searches for standard and custom dictionary entries.
summary: Search dictionary entries.
parameters:
- $ref: 'common/parameters.yml#/DictionaryName'
@@ -16,8 +16,7 @@ post:
application/json:
schema:
title: searchDictionaryEntriesParams
- description: >
- `searchDictionaryEntries` parameters.
+ description: Search parameter.
type: object
required:
- query
@@ -33,7 +32,11 @@ post:
$ref: 'common/parameters.yml#/language'
responses:
'200':
- $ref: '../../../common/responses/UpdatedAt.yml'
+ description: OK
+ content:
+ application/json:
+ schema:
+ $ref: './common/schemas/SearchDictionaryEntriesResponse.yml#/searchDictionaryEntriesResponse'
'400':
$ref: '../../../common/responses/BadRequest.yml'
'402':
diff --git a/specs/search/paths/keys/common/schemas.yml b/specs/search/paths/keys/common/schemas.yml
index adef0cad75..1ba2e16da2 100644
--- a/specs/search/paths/keys/common/schemas.yml
+++ b/specs/search/paths/keys/common/schemas.yml
@@ -5,76 +5,86 @@ apiKey:
properties:
acl:
type: array
- description: >
- [Permissions](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl) associated with the key.
- example: ['search','addObject']
+ description: |
+ Permissions that determine the type of API requests this key can make.
+ The required ACL is listed in each endpoint's reference.
+ For more information, see [access control list](https://www.algolia.com/doc/guides/security/api-keys/#access-control-list-acl).
+ example:
+ - search
+ - addObject
default: []
items:
$ref: '#/acl'
description:
type: string
- description: Description of an API key for you and your team members.
- example: 'Browse-restricted key'
+ description: Description of an API key to help you identify this API key.
+ example: Used for indexing by the CLI
default: ''
indexes:
type: array
- description: >
- Restricts this API key to a list of indices or index patterns. If the list is empty, all indices are allowed.
+ description: |
+ Index names or patterns that this API key can access.
+ By default, an API key can access all indices in the same application.
- Specify either an exact index name or a pattern with a leading or trailing wildcard character (or both). For example:
+ You can use leading and trailing wildcard characters (`*`):
- - `dev_*` matches all indices starting with "dev_"
- - `*_dev` matches all indices ending with "_dev"
+ - `dev_*` matches all indices starting with "dev_".
+ - `*_dev` matches all indices ending with "_dev".
- `*_products_*` matches all indices containing "_products_".
- example: ['dev_*','prod_products']
+ example:
+ - dev_*
+ - prod_en_products
default: []
items:
type: string
maxHitsPerQuery:
type: integer
- description: >
- Maximum number of hits this API key can retrieve in one query. If zero, no limit is enforced.
-
- > **Note**: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.
+ description: |
+ Maximum number of results this API key can retrieve in one query.
+ By default, there's no limit.
default: 0
maxQueriesPerIPPerHour:
type: integer
- description: >
- Maximum number of API calls per hour allowed from a given IP address or [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/).
-
- Each time an API call is performed with this key, a check is performed. If there were more than the specified number of calls within the last hour, the API returns an error with the status code `429` (Too Many Requests).
+ description: |
+ Maximum number of API requests allowed per IP address or [user token](https://www.algolia.com/doc/guides/sending-events/concepts/usertoken/) per hour.
-
- > **Note**: Use this parameter to protect you from third-party attempts to retrieve your entire content by massively querying the index.
+ If this limit is reached, the API returns an error with status code `429`.
+ By default, there's no limit.
default: 0
queryParameters:
type: string
- description: >
- Force some [query parameters](https://www.algolia.com/doc/api-reference/api-parameters/) to be applied for each query made with this API key.
-
- It's a URL-encoded query string.
- example: 'typoTolerance%3Dstrict%26ignorePlurals%3Dfalse%26filters%3Drights%3Apublic'
+ description: |
+ Query parameters to add when making API requests with this API key.
+
+ To restrict this API key to specific IP addresses, add the `restrictSources` parameter.
+ You can only add a single source, but you can provide a range of IP addresses.
+
+ Creating an API key fails if the request is made from an IP address that's outside the restricted range.
+ example: 'typoTolerance=strict&restrictSources=192.168.1.0/24'
default: ''
referers:
type: array
- description: >
- Restrict this API key to specific [referrers](https://www.algolia.com/doc/guides/security/api-keys/in-depth/api-key-restrictions/#http-referrers). If empty, all referrers are allowed.
+ description: |
+ Allowed HTTP referrers for this API key.
+
+ By default, all referrers are allowed.
+ You can use leading and trailing wildcard characters (`*`):
- For example:
+ - `https://algolia.com/*` allows all referrers starting with "https://algolia.com/"
+ - `*.algolia.com` allows all referrers ending with ".algolia.com"
+ - `*algolia.com*` allows all referrers in the domain "algolia.com".
- - `https://algolia.com/*` matches all referrers starting with "https://algolia.com/"
- - `*.algolia.com` matches all referrers ending with ".algolia.com"
- - `*algolia.com*` allows everything in the domain "algolia.com".
+ Like all HTTP headers, referrers can be spoofed. Don't rely on them to secure your data.
+ For more information, see [HTTP referrer restrictions](https://www.algolia.com/doc/guides/security/security-best-practices/#http-referrers-restrictions).
example: ['*algolia.com*']
default: []
items:
type: string
validity:
type: integer
- description: >
- Validity duration of a key (in seconds). The key will automatically be removed after this time has expired. The default value of 0 never expires.
-
- Short-lived API keys are useful to grant temporary access to your data. For example, in mobile apps, you can't [control when users update your app](https://www.algolia.com/doc/guides/security/security-best-practices/#use-secured-api-keys-in-mobile-apps). So instead of encoding keys into your app as you would for a web app, you should dynamically fetch them from your mobile app's backend.
+ description: |
+ Duration (in seconds) after which the API key expires.
+ By default, API keys don't expire.
example: 86400
default: 0
required:
@@ -83,7 +93,7 @@ apiKey:
keyString:
type: string
description: API key.
- example: '13ad45b4d0a2f6ea65ecbddf6aa260f2'
+ example: 13ad45b4d0a2f6ea65ecbddf6aa260f2
getApiKeyResponse:
allOf:
@@ -115,22 +125,7 @@ addApiKeyResponse:
- createdAt
acl:
- description: |
- API key permissions:
-
- `addObject`: required to add or update records, copy or move an index.
- `analytics`: required to access the Analytics API.
- `browse`: required to view records
- `deleteIndex`: required to delete indices.
- `deleteObject`: required to delete records.
- `editSettings`: required to change index settings.
- `inference`: required to access the Inference API.
- `listIndexes`: required to list indices.
- `logs`: required to access logs of search and indexing operations.
- `recommendation`: required to access the Personalization and Recommend APIs.
- `search`: required to search records
- `seeUnretrievableAttributes`: required to retrieve [`unretrievableAttributes`](https://www.algolia.com/doc/api-reference/api-parameters/unretrievableAttributes/) for all operations that return records.
- `settings`: required to examine index settings.
+ description: Access control list permissions.
type: string
enum:
- addObject
diff --git a/specs/search/paths/keys/key.yml b/specs/search/paths/keys/key.yml
index b6154df556..26324001a2 100644
--- a/specs/search/paths/keys/key.yml
+++ b/specs/search/paths/keys/key.yml
@@ -2,9 +2,9 @@ get:
tags:
- Api Keys
operationId: getApiKey
- summary: Get API key permissions.
- description: >
- Get the permissions and restrictions of a specific API key.
+ summary: Retrieve API key permissions.
+ description: |
+ Gets the permissions and restrictions of an API key.
When authenticating with the admin API key, you can request information for any of your application's keys.
When authenticating with other API keys, you can only retrieve information for that key.
@@ -33,12 +33,10 @@ put:
x-acl:
- admin
summary: Update an API key.
- description: >
- Replace the permissions of an existing API key.
+ description: |
+ Replaces the permissions of an existing API key.
- Any unspecified parameter resets that permission to its default value.
-
- The request must be authenticated with the admin API key.
+ Any unspecified attribute resets that attribute to its default value.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
requestBody:
@@ -79,11 +77,8 @@ delete:
operationId: deleteApiKey
x-acl:
- admin
- summary: Delete API key.
- description: >
- Delete an existing API key.
-
- The request must be authenticated with the admin API key.
+ summary: Delete an API key.
+ description: Deletes the API key.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
responses:
diff --git a/specs/search/paths/keys/keys.yml b/specs/search/paths/keys/keys.yml
index b9de346c5d..d15ad8dc5d 100644
--- a/specs/search/paths/keys/keys.yml
+++ b/specs/search/paths/keys/keys.yml
@@ -5,7 +5,7 @@ get:
x-acl:
- admin
summary: List API keys.
- description: List all API keys associated with your Algolia application, including their permissions and restrictions.
+ description: Lists all API keys associated with your Algolia application, including their permissions and restrictions.
responses:
'200':
description: OK
@@ -38,13 +38,8 @@ post:
operationId: addApiKey
x-acl:
- admin
- summary: Add API key.
- description: >
- Add a new API key with specific permissions and restrictions.
-
- The request must be authenticated with the admin API key.
-
- The response returns an API key string.
+ summary: Create an API key.
+ description: Creates a new API key with specific permissions and restrictions.
requestBody:
required: true
content:
diff --git a/specs/search/paths/keys/restoreApiKey.yml b/specs/search/paths/keys/restoreApiKey.yml
index ecb23f2b05..d38097f9ac 100644
--- a/specs/search/paths/keys/restoreApiKey.yml
+++ b/specs/search/paths/keys/restoreApiKey.yml
@@ -4,11 +4,14 @@ post:
operationId: restoreApiKey
x-acl:
- admin
- summary: Restore API key.
- description: >
- Restore a deleted API key, along with its associated permissions.
+ summary: Restore an API key.
+ description: |
+ Restores a deleted API key.
- The request must be authenticated with the admin API key.
+ Restoring resets the `validity` attribute to `0`.
+
+ Algolia stores up to 1,000 API keys per application.
+ If you create more, the oldest API keys are deleted and can't be restored.
parameters:
- $ref: 'common/parameters.yml#/KeyString'
responses:
diff --git a/specs/search/paths/manage_indices/listIndices.yml b/specs/search/paths/manage_indices/listIndices.yml
index dcfe9cd2a8..5f723a06dd 100644
--- a/specs/search/paths/manage_indices/listIndices.yml
+++ b/specs/search/paths/manage_indices/listIndices.yml
@@ -5,7 +5,10 @@ get:
x-acl:
- listIndexes
summary: List indices.
- description: List indices in an Algolia application.
+ description: |
+ Lists all indices in the current Algolia application.
+
+ The request follows any index restrictions of the API key you use to make the request.
parameters:
- $ref: '../../../common/parameters.yml#/Page'
- $ref: '../../../common/parameters.yml#/HitsPerPage'
diff --git a/specs/search/paths/manage_indices/operationIndex.yml b/specs/search/paths/manage_indices/operationIndex.yml
index 9e37685fc3..795a9032be 100644
--- a/specs/search/paths/manage_indices/operationIndex.yml
+++ b/specs/search/paths/manage_indices/operationIndex.yml
@@ -4,18 +4,30 @@ post:
operationId: operationIndex
x-acl:
- addObject
- summary: Copy, move, or rename an index.
- description: |-
- This `operation`, _copy_ or _move_, will copy or move a source index's (`IndexName`) records, settings, synonyms, and rules to a `destination` index.
- If the destination index exists, it will be replaced, except for index-specific API keys and analytics data.
- If the destination index doesn't exist, it will be created.
+ summary: Copy or move an index.
+ description: |
+ Copies or moves (renames) an index within the same Algolia application.
- The choice between moving or copying an index depends on your needs. Choose:
+ - Existing destination indices are overwritten, except for index-specific API keys and analytics data.
+ - If the destination index doesn't exist yet, it'll be created.
- - **Move** to rename an index.
- - **Copy** to create a new index with the same records and configuration as an existing one.
+ **Copy**
+
+ - Copying a source index that doesn't exist creates a new index with 0 records and default settings.
+ - The API keys of the source index are merged with the existing keys in the destination index.
+ - You can't copy the `enableReRanking`, `mode`, and `replicas` settings.
+ - You can't copy to a destination index that already has replicas.
+ - Be aware of the [size limits](https://www.algolia.com/doc/guides/scaling/algolia-service-limits/#application-record-and-index-limits).
+ - Related guide: [Copy indices](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/how-to/copy-indices/)
+
+ **Move**
+
+ - Moving a source index that doesn't exist is ignored without returning an error.
+ - When moving an index, the analytics data keep their original name and a new set of analytics data is started for the new name.
+ To access the original analytics in the dashboard, create an index with the original name.
+ - If the destination index has replicas, moving will overwrite the existing index and copy the data to the replica indices.
+ - Related guide: [Move indices](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/how-to/move-indices/).
- > **Note**: When considering copying or moving, be aware of the [rate limitations](https://www.algolia.com/doc/guides/scaling/algolia-service-limits/#application-record-and-index-limits) on these processes and the [impact on your analytics data](https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/concepts/indices-analytics/).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -35,12 +47,11 @@ post:
type: array
items:
$ref: '../../common/enums.yml#/scopeType'
- description: |-
- **This only applies to the _copy_ operation.**
-
- If you omit `scope`, the copy command copies all records, settings, synonyms, and rules.
+ description: |
+ **Only for copying.**
- If you specify `scope`, only the specified scopes are copied.
+ If you specify a scope, only the selected scopes are copied. Records and the other scopes are left unchanged.
+ If you omit the `scope` parameter, everything is copied: records, settings, synonyms, and rules.
required:
- operation
- destination
diff --git a/specs/search/paths/multiclusters/batchAssignUserIds.yml b/specs/search/paths/multiclusters/batchAssignUserIds.yml
index acc0c1e6e9..0b32015115 100644
--- a/specs/search/paths/multiclusters/batchAssignUserIds.yml
+++ b/specs/search/paths/multiclusters/batchAssignUserIds.yml
@@ -4,11 +4,11 @@ post:
operationId: batchAssignUserIds
x-acl:
- admin
- summary: Batch assign userIDs.
- description: >
- Assign multiple user IDs to a cluster.
+ summary: Assign multiple userIDs.
+ description: |
+ Assigns multiple user IDs to a cluster.
- **You can't _move_ users with this operation.**.
+ **You can't move users with this operation**.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInHeader'
requestBody:
@@ -26,7 +26,7 @@ post:
users:
type: array
description: User IDs to assign.
- example: ['einstein', 'bohr', 'feynman']
+ example: [einstein, bohr, feynman]
items:
type: string
required:
diff --git a/specs/search/paths/multiclusters/getTopUserIds.yml b/specs/search/paths/multiclusters/getTopUserIds.yml
index 6f5976da0d..e5371706da 100644
--- a/specs/search/paths/multiclusters/getTopUserIds.yml
+++ b/specs/search/paths/multiclusters/getTopUserIds.yml
@@ -4,11 +4,11 @@ get:
operationId: getTopUserIds
x-acl:
- admin
- summary: Get top userID.
- description: >
+ summary: Get top user IDs.
+ description: |
Get the IDs of the 10 users with the highest number of records per cluster.
- Since it can take up to a few seconds to get the data from the different clusters,
+ Since it can take a few seconds to get the data from the different clusters,
the response isn't real-time.
responses:
'200':
@@ -26,6 +26,7 @@ get:
items:
type: object
additionalProperties:
+ x-additionalPropertiesName: cluster
type: array
items:
$ref: '../../common/schemas/UserId.yml#/userId'
diff --git a/specs/search/paths/multiclusters/hasPendingMappings.yml b/specs/search/paths/multiclusters/hasPendingMappings.yml
index 75cd6a9eb1..dfa8953961 100644
--- a/specs/search/paths/multiclusters/hasPendingMappings.yml
+++ b/specs/search/paths/multiclusters/hasPendingMappings.yml
@@ -5,12 +5,12 @@ get:
x-acl:
- admin
summary: Get migration and user mapping status.
- description: >
+ description: |
To determine when the time-consuming process of creating a large batch of users or migrating users from one cluster to another is complete, this operation retrieves the status of the process.
parameters:
- in: query
name: getClusters
- description: Indicates whether to include the cluster's pending mapping state in the response.
+ description: Whether to include the cluster's pending mapping state in the response.
schema:
type: boolean
responses:
@@ -24,10 +24,10 @@ get:
additionalProperties: false
properties:
pending:
- description: Indicates whether there are clusters undergoing migration, creation, or deletion.
+ description: Whether there are clusters undergoing migration, creation, or deletion.
type: boolean
clusters:
- description: >
+ description: |
Cluster pending mapping state: migrating, creating, deleting.
type: object
additionalProperties:
diff --git a/specs/search/paths/multiclusters/listClusters.yml b/specs/search/paths/multiclusters/listClusters.yml
index 3e940518e5..8e8d9f74bf 100644
--- a/specs/search/paths/multiclusters/listClusters.yml
+++ b/specs/search/paths/multiclusters/listClusters.yml
@@ -5,7 +5,7 @@ get:
x-acl:
- admin
summary: List clusters.
- description: List the available clusters in a multi-cluster setup.
+ description: Lists the available clusters in a multi-cluster setup.
responses:
'200':
description: OK
diff --git a/specs/search/paths/multiclusters/searchUserIds.yml b/specs/search/paths/multiclusters/searchUserIds.yml
index 668ab0370f..e35ae35e24 100644
--- a/specs/search/paths/multiclusters/searchUserIds.yml
+++ b/specs/search/paths/multiclusters/searchUserIds.yml
@@ -6,9 +6,9 @@ post:
x-cacheable: true
x-acl:
- admin
- summary: Search for a user ID.
- description: >
- Since it can take up to a few seconds to get the data from the different clusters,
+ summary: Search for user IDs.
+ description: |
+ Since it can take a few seconds to get the data from the different clusters,
the response isn't real-time.
To ensure rapid updates, the user IDs index isn't built at the same time as the mapping. Instead, it's built every 12 hours, at the same time as the update of user ID usage. For example, if you add or move a user ID, the search will show an old value until the next time the mapping is rebuilt (every 12 hours).
diff --git a/specs/search/paths/multiclusters/userId.yml b/specs/search/paths/multiclusters/userId.yml
index 9ceb754c53..d12e1f4276 100644
--- a/specs/search/paths/multiclusters/userId.yml
+++ b/specs/search/paths/multiclusters/userId.yml
@@ -4,11 +4,11 @@ get:
operationId: getUserId
x-acl:
- admin
- summary: Get userID.
- description: >
- Returns the userID data stored in the mapping.
+ summary: Retrieve user ID.
+ description: |
+ Returns the user ID data stored in the mapping.
- Since it can take up to a few seconds to get the data from the different clusters,
+ Since it can take a few seconds to get the data from the different clusters,
the response isn't real-time.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInPath'
@@ -34,8 +34,8 @@ delete:
operationId: removeUserId
x-acl:
- admin
- summary: Remove userID.
- description: Remove a userID and its associated data from the multi-clusters.
+ summary: Delete user ID.
+ description: Deletes a user ID and its associated data from the clusters.
parameters:
- $ref: '../../common/parameters.yml#/UserIDInPath'
responses:
diff --git a/specs/search/paths/multiclusters/userIds.yml b/specs/search/paths/multiclusters/userIds.yml
index c737480c97..78f0fa3ffc 100644
--- a/specs/search/paths/multiclusters/userIds.yml
+++ b/specs/search/paths/multiclusters/userIds.yml
@@ -5,8 +5,8 @@ post:
x-acl:
- admin
summary: Assign or move a user ID.
- description: >
- Assign or move a user ID to a cluster.
+ description: |
+ Assigns or moves a user ID to a cluster.
The time it takes to move a user is proportional to the amount of data linked to the user ID.
parameters:
@@ -43,11 +43,11 @@ get:
operationId: listUserIds
x-acl:
- admin
- summary: List userIDs.
- description: >
- List the userIDs assigned to a multi-cluster application.
+ summary: List user IDs.
+ description: |
+ Lists the userIDs assigned to a multi-cluster application.
- Since it can take up to a few seconds to get the data from the different clusters,
+ Since it can take a few seconds to get the data from the different clusters,
the response isn't real-time.
parameters:
- $ref: '../../../common/parameters.yml#/Page'
diff --git a/specs/search/paths/objects/batch.yml b/specs/search/paths/objects/batch.yml
index 22d235c694..12abdc2fdc 100644
--- a/specs/search/paths/objects/batch.yml
+++ b/specs/search/paths/objects/batch.yml
@@ -2,12 +2,14 @@ post:
tags:
- Records
operationId: batch
- summary: Batch write operations on one index.
- description: >
- To reduce the time spent on network round trips, you can perform several write actions in a single API call.
- Actions are applied in the order they are specified.
-
- The supported `action`s are equivalent to the individual operations of the same name.
+ summary: Batch indexing operations on one index.
+ description: |
+ Adds, updates, or deletes records in one index with a single API request.
+
+ Batching index updates reduces latency and increases data integrity.
+
+ - Actions are applied in the order they're specified.
+ - Actions are equivalent to the individual API requests of the same name.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -32,12 +34,31 @@ post:
body:
type: object
description: Operation arguments (varies with specified `action`).
- example: {'name': 'Betty Jane McCamey','company': 'Vita Foods Inc.','email': 'betty@mccamey.com'}
+ example:
+ name: Betty Jane McCamey
+ company: Vita Foods Inc.
+ email: betty@mccamey.com
+
required:
- action
- body
required:
- requests
+ examples:
+ batch:
+ summary: Batch indexing request.
+ value:
+ requests:
+ - action: addObject
+ body:
+ name: Betty Jane McCamey
+ company: Vita Foods Inc.
+ email: betty@mccamey.com
+ - action: addObject
+ body:
+ name: Gayla geimer
+ company: Ortman McCain Co.
+ email: gayla@geimer.com
responses:
'200':
description: OK
diff --git a/specs/search/paths/objects/clearObjects.yml b/specs/search/paths/objects/clearObjects.yml
index 9ff050f6b5..24a02fd951 100644
--- a/specs/search/paths/objects/clearObjects.yml
+++ b/specs/search/paths/objects/clearObjects.yml
@@ -5,7 +5,7 @@ post:
x-acl:
- deleteIndex
summary: Delete all records from an index.
- description: Delete the records but leave settings and index-specific API keys untouched.
+ description: Deletes only the records from an index while keeping settings, synonyms, and rules.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
responses:
diff --git a/specs/search/paths/objects/common/schemas.yml b/specs/search/paths/objects/common/schemas.yml
index 79552aa74a..5bb761b06b 100644
--- a/specs/search/paths/objects/common/schemas.yml
+++ b/specs/search/paths/objects/common/schemas.yml
@@ -8,7 +8,7 @@ action:
- deleteObject
- delete
- clear
- description: Type of batch operation.
+ description: Type of indexing operation.
builtInOperationType:
type: string
@@ -20,22 +20,22 @@ builtInOperationType:
- AddUnique
- IncrementFrom
- IncrementSet
- description: Operation to apply to the attribute.
+ description: How to change the attribute.
attribute:
type: string
- description: Value of the attribute to be updated.
+ description: Value of the attribute to update.
builtInOperation:
type: object
- description: To update an attribute without pushing the entire record, you can use these built-in operations.
+ description: Update to perform on the attribute.
additionalProperties: false
properties:
_operation:
$ref: '#/builtInOperationType'
value:
type: string
- description: Value that corresponds to the operation, for example an `Increment` or `Decrement` step, `Add` or `Remove` value.
+ description: Value that corresponds to the operation, for example an `Increment` or `Decrement` step, or an `Add` or `Remove` value.
required:
- _operation
- value
diff --git a/specs/search/paths/objects/deleteBy.yml b/specs/search/paths/objects/deleteBy.yml
index 92ad831d1b..a7863935b4 100644
--- a/specs/search/paths/objects/deleteBy.yml
+++ b/specs/search/paths/objects/deleteBy.yml
@@ -4,11 +4,12 @@ post:
operationId: deleteBy
x-acl:
- deleteIndex
- summary: Delete all records matching a query.
- description: >
- This operation doesn't support all the query options, only its filters (numeric, facet, or tag) and geo queries.
+ summary: Delete records matching a query.
+ description: |
+ This operation doesn't accept empty queries or filters.
- It doesn't accept empty filters or queries.
+ It's more efficient to get a list of object IDs with the [`browse` operation](#tag/Search/operation/browse),
+ and then delete the records using the [`batch` operation](tag/Records/operation/batch).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/objects/getObjects.yml b/specs/search/paths/objects/getObjects.yml
index 4bcdb4b7fe..ae1c5bb805 100644
--- a/specs/search/paths/objects/getObjects.yml
+++ b/specs/search/paths/objects/getObjects.yml
@@ -6,10 +6,11 @@ post:
x-cacheable: true
x-acl:
- search
- summary: Get multiple records.
- description: >
- Retrieve one or more records, potentially from different indices, in a single API operation.
- Results will be received in the same order as the requests.
+ summary: Retrieve records.
+ description: |
+ Retrieves one or more records, potentially from different indices.
+
+ Records are returned in the same order as the requests.
requestBody:
required: true
description: Request object.
@@ -24,7 +25,7 @@ post:
requests:
type: array
items:
- description: Record retrieval operation.
+ description: Request body for retrieving records.
title: getObjectsRequest
type: object
additionalProperties: false
@@ -36,15 +37,17 @@ post:
type: array
items:
type: string
- description: Attributes to retrieve. If not specified, all retrievable attributes are returned.
- example: ['author', 'title', 'content']
+ description: |
+ Attributes to retrieve.
+ If not specified, all retrievable attributes are returned.
+ example: [author, title, content]
objectID:
type: string
- description: Record's objectID.
- example: '8b9b7619230b1950f653b962fb0dfd6b'
+ description: Object ID for the record to retrieve.
+ example: product-1
indexName:
type: string
- description: Name of the index containing the required records.
+ description: Index from which to retrieve the records.
example: books
required:
- requests
@@ -60,10 +63,10 @@ post:
properties:
results:
type: array
- description: Retrieved results.
+ description: Retrieved records.
items:
type: object
- description: Fetched object.
+ description: Retrieved record.
x-is-generic: true
required:
- results
diff --git a/specs/search/paths/objects/multipleBatch.yml b/specs/search/paths/objects/multipleBatch.yml
index c9ac23b303..db4ef88867 100644
--- a/specs/search/paths/objects/multipleBatch.yml
+++ b/specs/search/paths/objects/multipleBatch.yml
@@ -2,13 +2,12 @@ post:
tags:
- Records
operationId: multipleBatch
- description: >
- To reduce the time spent on network round trips, you can perform several write actions in a single request.
- It's a multi-index version of the [`batch` operation](#tag/Records/operation/batch).
- Actions are applied in the order they are specified.
+ description: |
+ Adds, updates, or deletes records in multiple indices with a single API request.
- The supported actions are equivalent to the individual operations of the same name.
- summary: Batch write operations on multiple indices.
+ - Actions are applied in the order they are specified.
+ - Actions are equivalent to the individual API requests of the same name.
+ summary: Batch indexing operations on multiple indices.
requestBody:
required: true
content:
@@ -31,8 +30,6 @@ post:
body:
type: object
description: Operation arguments (varies with specified `action`).
- example: >
- {'requests':[{'action':'addObject','indexName':'contacts','body':{'name':'Betty Jane McCamey','company':'Vita Foods Inc.','email':'betty@mccamey.com'}},{'action':'addObject','indexName':'public_contacts','body':{'name':'Gayla Geimer','company': "Ortman McCain Co','email':'gayla@geimer.com'}}]}
indexName:
type: string
description: Index to target for this operation.
@@ -43,6 +40,23 @@ post:
- indexName
required:
- requests
+ examples:
+ batch:
+ summary: Batch indexing request to two indices.
+ value:
+ requests:
+ - action: addObject
+ indexName: contacts
+ body:
+ name: Betty Jane McCamey
+ company: Vita Foods Inc.
+ email: betty@mccamey.com
+ - action: addObject
+ indexName: public_contacts
+ body:
+ name: Gayla Geimer
+ company: Ortman McCain Co.
+ email: gayla@geimer.com
responses:
'200':
description: OK
@@ -55,7 +69,7 @@ post:
properties:
taskID:
type: object
- description: TaskIDs per index.
+ description: Task IDs. One for each index.
additionalProperties:
$ref: '../../../common/responses/common.yml#/taskID'
objectIDs:
diff --git a/specs/search/paths/objects/object.yml b/specs/search/paths/objects/object.yml
index 326f2d2618..58651f43fb 100644
--- a/specs/search/paths/objects/object.yml
+++ b/specs/search/paths/objects/object.yml
@@ -4,21 +4,25 @@ get:
operationId: getObject
x-acl:
- search
- summary: Get a record.
- description: To get more than one record, use the [`objects` operation](#tag/Records/operation/getObjects).
+ summary: Retrieve a record.
+ description: |
+ Retrieves one record by its object ID.
+
+ To retrieve more than one record, use the [`objects` operation](#tag/Records/operation/getObjects).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
- name: attributesToRetrieve
in: query
- description: >
+ description: |
Attributes to include with the records in the response.
This is useful to reduce the size of the API response.
By default, all retrievable attributes are returned.
- `objectID` is always retrieved, even when not specified.
+ `objectID` is always retrieved.
- [`unretrievableAttributes`](https://www.algolia.com/doc/api-reference/api-parameters/unretrievableAttributes/) won't be retrieved unless the request is authenticated with the admin API key.
+ Attributes included in `unretrievableAttributes`
+ won't be retrieved unless the request is authenticated with the admin API key.
schema:
type: array
items:
@@ -31,7 +35,7 @@ get:
schema:
title: getObjectResponse
type: object
- description: Fetched object.
+ description: The requested record.
additionalProperties:
$ref: 'common/schemas.yml#/attribute'
'400':
@@ -49,19 +53,19 @@ put:
operationId: addOrUpdateObject
x-acl:
- addObject
- summary: Add or update a record (using objectID).
+ summary: Add or replace a record.
description: |
- If you use an existing `objectID`, the existing record will be replaced with the new one.
-
- To update only some attributes of an existing record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject) instead.
+ If a record with the specified object ID exists, the existing record is replaced.
+ Otherwise, a new record is added to the index.
- To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
+ To update _some_ attributes of an existing record, use the [`partial` operation](#tag/Records/operation/partialUpdateObject) instead.
+ To add, update, or replace multiple records, use the [`batch` operation](#tag/Records/operation/batch).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
requestBody:
required: true
- description: Algolia record.
+ description: The record, a schemaless object with attributes that are useful in the context of search and discovery.
content:
application/json:
schema:
@@ -85,7 +89,12 @@ delete:
x-acl:
- deleteObject
summary: Delete a record.
- description: To delete a set of records matching a query, use the [`deleteByQuery` operation](#tag/Records/operation/deleteBy) instead.
+ description: |
+ Deletes a record by its object ID.
+
+ To delete more than one record, use the [`batch` operation](#tag/Records/operation/batch).
+ To delete records matching a query, use the [`deleteByQuery` operation](#tag/Records/operation/deleteBy).
+
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
diff --git a/specs/search/paths/objects/objects.yml b/specs/search/paths/objects/objects.yml
index 980b6c9d8b..ff778e1a2a 100644
--- a/specs/search/paths/objects/objects.yml
+++ b/specs/search/paths/objects/objects.yml
@@ -4,20 +4,22 @@ post:
operationId: saveObject
x-acl:
- addObject
- description: >
- Add a record (object) to an index or replace it.
+ description: |
+ Adds a record to an index or replace it.
- If the record doesn't contain an `objectID`, Algolia automatically adds it.
+ - If the record doesn't have an object ID, a new record with an auto-generated object ID is added to your index.
+ - If a record with the specified object ID exists, the existing record is replaced.
+ - If a record with the specified object ID doesn't exist, a new record is added to your index.
+ - If you add a record to an index that doesn't exist yet, a new index is created.
- If you use an existing `objectID`, the existing record is replaced with the new one.
-
- To add multiple records to your index in a single API request, use the [`batch` operation](#tag/Records/operation/batch).
- summary: Add or update a record.
+ To update _some_ attributes of a record, use the [`partial` operation](#tag/Records/operation/partial).
+ To add, update, or replace multiple records, use the [`batch` operation](#tag/Records/operation/batch).
+ summary: Add or replace a record.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
required: true
- description: The Algolia record.
+ description: The record, a schemaless object with attributes that are useful in the context of search and discovery.
content:
application/json:
schema:
@@ -34,8 +36,8 @@ post:
properties:
createdAt:
type: string
- description: Date of creation (ISO-8601 format).
- example: '2023-06-29T15:15:40.747Z'
+ description: Timestamp when the record was added, in ISO 8601 format.
+ example: 2023-06-29T15:15:40.747Z
taskID:
$ref: '../../../common/responses/common.yml#/taskID'
objectID:
@@ -58,8 +60,19 @@ delete:
operationId: deleteIndex
x-acl:
- deleteIndex
- summary: Delete index.
- description: Delete an existing index.
+ summary: Delete an index.
+ description: |
+ Deletes an index and all its settings.
+
+ - Deleting an index doesn't delete its analytics data.
+ - If you try to delete a non-existing index, the operation is ignored without warning.
+ - If the index you want to delete has replica indices, the replicas become independent indices.
+ - If the index you want to delete is a replica index, you must first unlink it from its primary index before you can delete it.
+ For more information, see [Delete replica indices](https://www.algolia.com/doc/guides/managing-results/refine-results/sorting/how-to/deleting-replicas/).
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/how-to/delete-indices/
+ description: |
+ Related guide: Delete indices.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
responses:
diff --git a/specs/search/paths/objects/partialUpdate.yml b/specs/search/paths/objects/partialUpdate.yml
index b424187f2c..c7dc6b2d5d 100644
--- a/specs/search/paths/objects/partialUpdate.yml
+++ b/specs/search/paths/objects/partialUpdate.yml
@@ -4,25 +4,28 @@ post:
operationId: partialUpdateObject
x-acl:
- addObject
- summary: Update record attributes.
+ summary: Add or update attributes.
x-codegen-request-body-name: attributesToUpdate
- description: >
- Add new attributes or update current ones in an existing record.
+ description: |
+ Adds new attributes to a record, or update existing ones.
- You can use any first-level attribute but not nested attributes. If you specify a [nested attribute](https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/how-to/creating-and-using-nested-attributes/), the engine treats it as a replacement for its first-level ancestor.
+ - If a record with the specified object ID doesn't exist,
+ a new record is added to the index **if** `createIfNotExists` is true.
+ - If the index doesn't exist yet, this method creates a new index.
+ - You can use any first-level attribute but not nested attributes.
+ If you specify a nested attribute, the engine treats it as a replacement for its first-level ancestor.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ObjectID'
- name: createIfNotExists
- description: >
- Indicates whether to create a new record if it doesn't exist yet.
+ description: Whether to create a new record if it doesn't exist.
in: query
schema:
type: boolean
default: true
requestBody:
required: true
- description: Object with attributes to update.
+ description: Attributes with their values.
content:
application/json:
schema:
diff --git a/specs/search/paths/rules/clearRules.yml b/specs/search/paths/rules/clearRules.yml
index 9fc9f61cc5..89a543d8e0 100644
--- a/specs/search/paths/rules/clearRules.yml
+++ b/specs/search/paths/rules/clearRules.yml
@@ -5,7 +5,7 @@ post:
x-acl:
- editSettings
summary: Delete all rules.
- description: Delete all rules in the index.
+ description: Deletes all rules from the index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/rules/common/parameters.yml b/specs/search/paths/rules/common/parameters.yml
index 7f5e94726a..c92f0ae432 100644
--- a/specs/search/paths/rules/common/parameters.yml
+++ b/specs/search/paths/rules/common/parameters.yml
@@ -4,18 +4,17 @@ ClearExistingRules:
required: false
schema:
type: boolean
- description: Indicates whether existing rules should be deleted before adding this batch.
+ description: Whether existing rules should be deleted before adding this batch.
ObjectIDRule:
in: path
name: objectID
description: Unique identifier of a rule object.
- example: 'a-rule-id'
required: true
schema:
- type: string
+ $ref: '../../../../common/parameters.yml#/ruleID'
query:
type: string
- description: Rule object query.
+ description: Search query for rules.
default: ''
diff --git a/specs/search/paths/rules/common/schemas.yml b/specs/search/paths/rules/common/schemas.yml
index 0824892ba4..3ccb09b259 100644
--- a/specs/search/paths/rules/common/schemas.yml
+++ b/specs/search/paths/rules/common/schemas.yml
@@ -4,28 +4,31 @@ rule:
additionalProperties: false
properties:
objectID:
- type: string
- description: Unique identifier for a rule object.
- example: 'hide-12345'
+ $ref: '../../../../common/parameters.yml#/ruleID'
conditions:
type: array
- description: >
- [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions) required to activate a rule. You can use up to 25 conditions per rule.
+ minItems: 0
+ maxItems: 25
+ description: |
+ Conditions that trigger a rule.
+
+ Some consequences require specific conditions or don't require any condition.
+ For more information, see [Conditions](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#conditions).
items:
$ref: '#/condition'
consequence:
$ref: '#/consequence'
description:
type: string
- description: Description of the rule's purpose. This can be helpful for display in the Algolia dashboard.
- example: 'Display a promotional banner'
+ description: Description of the rule's purpose to help you distinguish between different rules.
+ example: Display a promotional banner
enabled:
type: boolean
default: true
- description: Indicates whether to enable the rule. If it isn't enabled, it isn't applied at query time.
+ description: Whether the rule is active.
validity:
type: array
- description: If you specify a validity period, the rule _only_ applies only during that period. If specified, the array must not be empty.
+ description: Time periods when the rule is active.
items:
$ref: '#/timeRange'
required:
@@ -37,48 +40,85 @@ condition:
properties:
pattern:
type: string
- description: Query pattern syntax.
- example: '{facet:brand}'
+ description: |
+ Query pattern that triggers the rule.
+
+ You can use either a literal string, or a special pattern `{facet:ATTRIBUTE}`, where `ATTRIBUTE` is a facet name.
+ The rule is triggered if the query matches the literal string or a value of the specified facet.
+ For example, with `pattern: {facet:genre}`, the rule is triggered when users search for a genre, such as "comedy".
+ example: '{facet:genre}'
anchoring:
$ref: '#/anchoring'
alternatives:
type: boolean
- description: Whether the pattern matches on plurals, synonyms, and typos.
+ description: Whether the pattern should match plurals, synonyms, and typos.
default: false
context:
type: string
- description: 'Rule context format: [A-Za-z0-9_-]+).'
- example: 'trackedFilters'
+ pattern: '[A-Za-z0-9_-]+'
+ description: |
+ An additional restriction that only triggers the rule, when the search has the same value as `ruleContexts` parameter.
+ For example, if `context: mobile`, the rule is only triggered when the search request has a matching `ruleContexts: mobile`.
+ A rule context must only contain alphanumeric characters.
+ example: mobile
+ filters:
+ type: string
+ description: |
+ Filters that trigger the rule.
+
+ You can add add filters using the syntax `facet:value` so that the rule is triggered, when the specific filter is selected.
+ You can use `filters` on its own or combine it with the `pattern` parameter.
+ example: 'genre:comedy'
anchoring:
type: string
- description: Whether the pattern parameter matches the beginning (`startsWith`) or end (`endsWith`) of the query string, is an exact match (`is`), or a partial match (`contains`).
+ description: |
+ Which part of the search query the pattern should match:
+
+ - `startsWith`. The pattern must match the begginning of the query.
+ - `endsWith`. The pattern must match the end of the query.
+ - `is`. The pattern must match the query exactly.
+ - `contains`. The pattern must match anywhere in the query.
+
+ Empty queries are only allowed as pattern with `anchoring: is`.
enum: [is, startsWith, endsWith, contains]
consequence:
type: object
- description: >
- [Consequences](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#consequences) of a rule.
+ description: |
+ Effect of the rule.
+
+ For more information, see [Consequences](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/#consequences).
additionalProperties: false
properties:
params:
$ref: '#/consequenceParams'
promote:
type: array
- description: Records to promote.
+ maxItems: 300
+ description: |
+ Records you want to pin to a specific position in the search results.
+
+ You can promote up to 300 records, either individually, or as groups of up to 100 records each.
items:
$ref: '#/promote'
filterPromotes:
type: boolean
default: false
- description: Only use in combination with the `promote` consequence. When `true`, promoted results will be restricted to match the filters of the current search. When `false`, the promoted results will show up regardless of the filters.
+ description: |
+ Whether promoted records must match an active filter for the consequence to be applied.
+
+ This ensures that user actions (filtering the search) are given a higher precendence.
+ For example, if you promote a record with the `color: red` attribute, and the user filters the search for `color: blue`,
+ the "red" record won't be shown.
hide:
type: array
- description: Records to hide. By default, you can hide up to 50 records per rule.
+ maxItems: 50
+ description: Records you want to hide from the search results.
items:
title: consequenceHide
type: object
- description: Unique identifier of the record to hide.
+ description: Object ID of the record to hide.
additionalProperties: false
properties:
objectID:
@@ -86,8 +126,12 @@ consequence:
required:
- objectID
userData:
- description: Custom JSON object that will be appended to the userData array in the response. This object isn't interpreted by the API. It's limited to 1kB of minified JSON.
- example: {'settingID': 'f2a7b51e3503acc6a39b3784ffb84300','pluginVersion': '1.6.0'}
+ description: |
+ A JSON object with custom data that will be appended to the `userData` array in the response.
+ This object isn't interpreted by the API and is limited to 1 kB of minified JSON.
+ example:
+ settingID: f2a7b51e3503acc6a39b3784ffb84300
+ pluginVersion: '1.6.0'
consequenceParams:
allOf:
@@ -101,14 +145,13 @@ promote:
- $ref: '#/promoteObjectID'
promoteObjectID:
+ title: objectID
description: Record to promote.
type: object
additionalProperties: false
properties:
objectID:
- type: string
- example: '2b642cf64c587f50388eb1b8d047bf56'
- description: Unique identifier of the record to promote.
+ $ref: '../../../../common/parameters.yml#/objectID'
position:
$ref: '#/promotePosition'
required:
@@ -116,16 +159,22 @@ promoteObjectID:
- objectID
promoteObjectIDs:
+ title: objectIDs
description: Records to promote.
type: object
additionalProperties: false
properties:
objectIDs:
type: array
- description: Unique identifiers of the records to promote.
- example: ['3f31c087763a2ceec359b318fc3edef3','63c3c871e31a152d67df7720192fd752']
+ maxItems: 100
+ description: |
+ Object IDs of the records you want to promote.
+
+ The records are placed as a group at the `position`.
+ For example, if you want to promote four records to position `0`,
+ they will be the first four search results.
items:
- type: string
+ $ref: '../../../../common/parameters.yml#/objectID'
position:
$ref: '#/promotePosition'
required:
@@ -134,12 +183,15 @@ promoteObjectIDs:
promotePosition:
type: integer
- description: The position to promote the records to. If you pass objectIDs, the records are placed at this position as a group. For example, if you pronmote four objectIDs to position 0, the records take the first four positions.
+ description: Position in the search results where you want to show the promoted records.
example: 0
params:
type: object
- description: Additional search parameters.
+ description: |
+ Parameters to apply to this search.
+
+ You can use all search parameters, plus special `automaticFacetFilters`, `automaticOptionalFacetFilters`, and `query`.
additionalProperties: false
properties:
query:
@@ -152,7 +204,11 @@ params:
$ref: '../../../../common/schemas/IndexSettings.yml#/renderingContent'
consequenceQuery:
- description: When providing a string, it replaces the entire query string. When providing an object, it describes incremental edits to be made to the query string (but you can't do both).
+ description: |
+ Replace or edit the search query.
+
+ If `consequenceQuery` is a string, the entire search query is replaced with that string.
+ If `consequenceQuery` is an object, it describes incremental edits made to the query.
oneOf:
- $ref: '#/consequenceQueryObject'
- type: string
@@ -162,12 +218,12 @@ consequenceQueryObject:
additionalProperties: false
properties:
remove:
- description: Words to remove.
+ description: Words to remove from the search query.
type: array
items:
type: string
edits:
- description: Edits to apply.
+ description: Changes to make to the search query.
type: array
items:
$ref: '#/edit'
@@ -182,7 +238,7 @@ edit:
description: Text or patterns to remove from the query string.
type: string
insert:
- description: Text that should be inserted in place of the removed text inside the query string.
+ description: Text to be added in place of the deleted text inside the query string.
type: string
editType:
@@ -191,7 +247,12 @@ editType:
enum: [remove, replace]
automaticFacetFilters:
- description: Names of facets to which automatic filtering must be applied; they must match the facet name of a facet value placeholder in the query pattern.
+ description: |
+ Filter to be applied to the search.
+
+ You can use this to respond to search queries that match a facet value.
+ For example, if users search for "comedy", which matches a facet value of the "genre" facet,
+ you can filter the results to show the top-ranked comedy movies.
oneOf:
- type: array
items:
@@ -201,25 +262,32 @@ automaticFacetFilters:
type: string
automaticOptionalFacetFilters:
- description: Same syntax as `automaticFacetFilters`, but the engine treats the filters as optional.
+ description: Optional filters to be applied to the search.
$ref: '#/automaticFacetFilters'
automaticFacetFilter:
type: object
- description: Automatic facet Filter.
+ description: Filter or optional filter to be applied to the search.
additionalProperties: false
properties:
facet:
type: string
- description: Attribute to filter on. This must match a facet placeholder in the Rule's pattern.
+ description: |
+ Facet name to be applied as filter.
+ The name must match placeholders in the `pattern` parameter.
+ For example, with `pattern: {facet:genre}`, `automaticFacetFilters` must be `genre`.
score:
type: integer
default: 1
- description: Score for the filter. Typically used for optional or disjunctive filters.
+ description: Filter scores to give different weights to individual filters.
disjunctive:
type: boolean
default: false
- description: Whether the filter is disjunctive (true) or conjunctive (false).
+ description: |
+ Whether the filter is disjunctive or conjunctive.
+
+ If true the filter has multiple matches, multiple occurences are combined with the logical `OR` operation.
+ If false, multiple occurences are combined with the logical `AND` operation.
required:
- facet
@@ -229,10 +297,10 @@ timeRange:
properties:
from:
type: integer
- description: Lower bound of the time range (Unix timestamp).
+ description: When the rule should start to be active, in Unix epoch time.
until:
type: integer
- description: Upper bound of the time range (Unix timestamp).
+ description: When the rule should stop to be active, in Unix epoch time.
required:
- from
- until
@@ -242,7 +310,7 @@ updatedRuleResponse:
additionalProperties: false
properties:
objectID:
- $ref: '../../../../common/parameters.yml#/objectID'
+ $ref: '../../../../common/parameters.yml#/ruleID'
updatedAt:
$ref: '../../../../common/responses/common.yml#/updatedAt'
taskID:
diff --git a/specs/search/paths/rules/rule.yml b/specs/search/paths/rules/rule.yml
index 17577ad435..03b9a9850e 100644
--- a/specs/search/paths/rules/rule.yml
+++ b/specs/search/paths/rules/rule.yml
@@ -4,8 +4,11 @@ get:
operationId: getRule
x-acl:
- settings
- summary: Get a rule.
- description: Get a rule by its `objectID`. To find the `objectID` for rules, use the [`search` operation](#tag/Rules/operation/searchRules).
+ summary: Retrieve a rule.
+ description: |
+ Retrieves a rule by its ID.
+ To find the object ID of rules, use the [`search` operation](#tag/Rules/operation/searchRules).
+
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: 'common/parameters.yml#/ObjectIDRule'
@@ -31,8 +34,12 @@ put:
operationId: saveRule
x-acl:
- editSettings
- summary: Create or update a rule.
- description: To create or update more than one rule, use the [`batch` operation](#tag/Rules/operation/saveRules).
+ summary: Create or replace a rule.
+ description: |
+ If a rule with the specified object ID doesn't exist, it's created.
+ Otherwise, the existing rule is replaced.
+
+ To create or update more than one rule, use the [`batch` operation](#tag/Rules/operation/saveRules).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: 'common/parameters.yml#/ObjectIDRule'
@@ -66,7 +73,10 @@ delete:
x-acl:
- editSettings
summary: Delete a rule.
- description: Delete a rule by its `objectID`. To find the `objectID` for rules, use the [`search` operation](#tag/Rules/operation/searchRules).
+ description: |
+ Deletes a rule by its ID.
+ To find the object ID for rules,
+ use the [`search` operation](#tag/Rules/operation/searchRules).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: 'common/parameters.yml#/ObjectIDRule'
diff --git a/specs/search/paths/rules/saveRules.yml b/specs/search/paths/rules/saveRules.yml
index 805a3c362f..5704b8ddff 100644
--- a/specs/search/paths/rules/saveRules.yml
+++ b/specs/search/paths/rules/saveRules.yml
@@ -4,8 +4,12 @@ post:
operationId: saveRules
x-acl:
- editSettings
- summary: Save a batch of rules.
- description: Create or update multiple rules.
+ summary: Create or update rules.
+ description: |
+ Create or update multiple rules.
+
+ If a rule with the specified object ID doesn't exist, Algolia creates a new one.
+ Otherwise, existing rules are replaced.
x-codegen-request-body-name: rules
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
@@ -17,7 +21,7 @@ post:
application/json:
schema:
type: array
- description: Rules to add.
+ description: Rules to add or replace.
items:
$ref: 'common/schemas.yml#/rule'
responses:
diff --git a/specs/search/paths/rules/searchRules.yml b/specs/search/paths/rules/searchRules.yml
index 42637f414b..b562fea6b6 100644
--- a/specs/search/paths/rules/searchRules.yml
+++ b/specs/search/paths/rules/searchRules.yml
@@ -7,7 +7,7 @@ post:
x-acl:
- settings
summary: Search for rules.
- description: Search for rules in your index. You can control the search with parameters. To list all rules, send an empty request body.
+ description: Searches for rules in your index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
@@ -25,7 +25,7 @@ post:
$ref: 'common/schemas.yml#/anchoring'
context:
type: string
- description: Restricts responses to the specified [contextual rule](https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/how-to/customize-search-results-by-platform/#creating-contextual-rules).
+ description: Only return rules that match the context (exact match).
example: 'mobile'
page:
$ref: '../../../common/parameters.yml#/page'
@@ -35,15 +35,10 @@ post:
type: boolean
nullable: true
default: null
- description: Restricts responses to enabled rules. When not specified (default), _all_ rules are retrieved.
- requestOptions:
- type: array
- description: Request options to send with the API call.
- example: >
- {timeouts:{read:20}}
- items:
- type: object
- description: Request option.
+ description: |
+ If `true`, return only enabled rules.
+ If `false`, return only inactive rules.
+ By default, _all_ rules are returned.
responses:
'200':
description: OK
@@ -61,12 +56,12 @@ post:
properties:
hits:
type: array
- description: Fetched rules.
+ description: Rules that matched the search criteria.
items:
$ref: 'common/schemas.yml#/rule'
nbHits:
type: integer
- description: Number of fetched rules.
+ description: Number of rules that matched the search criteria.
page:
type: integer
description: Current page.
diff --git a/specs/search/paths/search/browse.yml b/specs/search/paths/search/browse.yml
index ce4b2a01dc..8932742a8b 100644
--- a/specs/search/paths/search/browse.yml
+++ b/specs/search/paths/search/browse.yml
@@ -4,14 +4,18 @@ post:
operationId: browse
x-acl:
- browse
- summary: Get all records from an index.
- description: >
- Retrieve up to 1,000 records per call.
+ summary: Browse for records.
+ description: |
+ Retrieves records from an index, up to 1,000 per request.
- Supports full-text search and filters. For better performance, it doesn't support:
+ While searching retrieves _hits_ (records augmented with attributes for highlighting and ranking details),
+ browsing _just_ returns matching records.
+ This can be useful if you want to export your indices.
- - The `distinct` query parameter
- - Sorting by typos, proximity, words, or geographical distance.
+ - The Analytics API doesn't collect data when using `browse`.
+ - Records are ranked by attributes and custom ranking.
+ - Deduplication (`distinct`) is turned off.
+ - There's no ranking for: typo-tolerance, number of matched words, proximity, geo distance.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/search/search.yml b/specs/search/paths/search/search.yml
index 6c07796328..e58b2982c9 100644
--- a/specs/search/paths/search/search.yml
+++ b/specs/search/paths/search/search.yml
@@ -8,10 +8,16 @@ post:
x-acl:
- search
summary: Search multiple indices.
- description: Send multiple search queries to one or more indices.
+ description: |
+ Sends multiple search request to one or more indices.
+
+ This can be useful in these cases:
+
+ - Different indices for different purposes, such as, one index for products, another one for marketing content.
+ - Multiple searches to the same index—for example, with different filters.
requestBody:
required: true
- description: Query requests and strategies. Results will be received in the same order as the queries.
+ description: Muli-search request body. Results are returned in the same order as the requests.
content:
application/json:
schema:
diff --git a/specs/search/paths/search/searchForFacetValues.yml b/specs/search/paths/search/searchForFacetValues.yml
index 790134da0e..42580a96e7 100644
--- a/specs/search/paths/search/searchForFacetValues.yml
+++ b/specs/search/paths/search/searchForFacetValues.yml
@@ -7,14 +7,19 @@ post:
x-acl:
- search
summary: Search for facet values.
- description: >
- [Search for a facet's values](https://www.algolia.com/doc/guides/managing-results/refine-results/faceting/#search-for-facet-values), optionally restricting the returned values to those contained in records matching other search criteria.
+ description: |
+ Searches for values of a specified facet attribute.
- > **Note**: Pagination isn't supported (`page` and `hitsPerPage` are ignored). By default, the engine returns a maximum of 10 values but you can adjust this with `maxFacetHits`.
+ - By default, facet values are sorted by decreasing count.
+ You can adjust this with the `sortFacetValueBy` parameter.
+ - Searching for facet values doesn't work if you have **more than 65 searchable facets and searchable attributes combined**.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- name: facetName
- description: Facet name.
+ description: |
+ Facet attribute in which to search for values.
+
+ This attribute must be included in the `attributesForFaceting` index setting with the `searchable()` modifier.
in: path
required: true
schema:
diff --git a/specs/search/paths/search/searchSingleIndex.yml b/specs/search/paths/search/searchSingleIndex.yml
index 1cd4a2d2d2..71987f2394 100644
--- a/specs/search/paths/search/searchSingleIndex.yml
+++ b/specs/search/paths/search/searchSingleIndex.yml
@@ -7,7 +7,11 @@ post:
x-acl:
- search
summary: Search an index.
- description: Return records that match the query.
+ description: |
+ Searches a single index and return matching search results (_hits_).
+
+ This method lets you retrieve up to 1,000 hits.
+ If you need more, use the [`browse` operation](#tag/Search/operation/browse) or increase the `paginatedLimitedTo` index setting.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/settings/settings.yml b/specs/search/paths/settings/settings.yml
index 16d5b3de67..bb765e0e7b 100644
--- a/specs/search/paths/settings/settings.yml
+++ b/specs/search/paths/settings/settings.yml
@@ -4,8 +4,8 @@ get:
operationId: getSettings
x-acl:
- search
- description: Return an object containing an index's [configuration settings](https://www.algolia.com/doc/api-reference/settings-api-parameters/).
- summary: Get index settings.
+ description: Retrieves an object with non-null index settings.
+ summary: Retrieve index settings.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
responses:
@@ -30,7 +30,13 @@ put:
operationId: setSettings
x-acl:
- editSettings
- description: Update the specified [index settings](https://www.algolia.com/doc/api-reference/settings-api-parameters/). Specifying null for a setting resets it to its default value.
+ description: |
+ Update the specified index settings.
+
+ Index settings that you don't specify are left unchanged.
+ Specify `null` to reset a setting to its default value.
+
+ For best performance, update the index settings before you add new records to your index.
summary: Update index settings.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
diff --git a/specs/search/paths/synonyms/clearSynonyms.yml b/specs/search/paths/synonyms/clearSynonyms.yml
index 884a9069c8..998864b42b 100644
--- a/specs/search/paths/synonyms/clearSynonyms.yml
+++ b/specs/search/paths/synonyms/clearSynonyms.yml
@@ -5,7 +5,7 @@ post:
x-acl:
- editSettings
summary: Delete all synonyms.
- description: Delete all synonyms in the index.
+ description: Deletes all synonyms from the index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/synonyms/common/parameters.yml b/specs/search/paths/synonyms/common/parameters.yml
index 9b0c680ae4..912b4b70de 100644
--- a/specs/search/paths/synonyms/common/parameters.yml
+++ b/specs/search/paths/synonyms/common/parameters.yml
@@ -3,12 +3,12 @@ ReplaceExistingSynonyms:
name: replaceExistingSynonyms
schema:
type: boolean
- description: Indicates whether to replace all synonyms in the index with the ones sent with this request.
+ description: Whether to replace all synonyms in the index with the ones sent with this request.
Query:
in: query
name: query
- description: Search for synonyms that match this string.
+ description: Search query for synonyms.
schema:
type: string
default: ''
diff --git a/specs/search/paths/synonyms/common/schemas.yml b/specs/search/paths/synonyms/common/schemas.yml
index 32b9668f4e..e04b32c175 100644
--- a/specs/search/paths/synonyms/common/schemas.yml
+++ b/specs/search/paths/synonyms/common/schemas.yml
@@ -1,6 +1,6 @@
synonymHits:
type: array
- description: Synonym objects.
+ description: Matching synonyms.
items:
$ref: '#/synonymHit'
@@ -21,7 +21,7 @@ synonymHit:
items:
type: string
description: Words or phrases considered equivalent.
- example: ['vehicle','auto']
+ example: ['vehicle', 'auto']
input:
type: string
description: Word or phrase to appear in query strings (for [`onewaysynonym`s](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/one-way-synonyms/)).
@@ -35,10 +35,10 @@ synonymHit:
items:
type: string
description: Words to be matched in records.
- example: ['vehicle','auto']
+ example: ['vehicle', 'auto']
placeholder:
type: string
- description: >
+ description: |
[Placeholder token](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/synonyms-placeholders/) to be put inside records.
example: ''
replacements:
@@ -46,7 +46,7 @@ synonymHit:
items:
type: string
description: Query words that will match the [placeholder token](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/in-depth/synonyms-placeholders/).
- example: ['street','st']
+ example: ['street', 'st']
required:
- objectID
- type
diff --git a/specs/search/paths/synonyms/saveSynonyms.yml b/specs/search/paths/synonyms/saveSynonyms.yml
index 320ca0405c..24e6a9d953 100644
--- a/specs/search/paths/synonyms/saveSynonyms.yml
+++ b/specs/search/paths/synonyms/saveSynonyms.yml
@@ -4,8 +4,10 @@ post:
operationId: saveSynonyms
x-acl:
- editSettings
- summary: Save a batch of synonyms.
- description: Create or update multiple synonyms.
+ summary: Create or replace synonyms.
+ description: |
+ If a synonym with the `objectID` doesn't exist, Algolia adds a new one.
+ Otherwise, existing synonyms are replaced.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: '../../../common/parameters.yml#/ForwardToReplicas'
diff --git a/specs/search/paths/synonyms/searchSynonyms.yml b/specs/search/paths/synonyms/searchSynonyms.yml
index 91f67b7451..0c08a78524 100644
--- a/specs/search/paths/synonyms/searchSynonyms.yml
+++ b/specs/search/paths/synonyms/searchSynonyms.yml
@@ -7,7 +7,7 @@ post:
x-acl:
- settings
summary: Search for synonyms.
- description: Search for synonyms in your index. You can control and filter the search with parameters. To get all synonyms, send an empty request body.
+ description: Searches for synonyms in your index.
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
requestBody:
diff --git a/specs/search/paths/synonyms/synonym.yml b/specs/search/paths/synonyms/synonym.yml
index b3be94ba1a..16c0fccfc1 100644
--- a/specs/search/paths/synonyms/synonym.yml
+++ b/specs/search/paths/synonyms/synonym.yml
@@ -4,8 +4,11 @@ get:
operationId: getSynonym
x-acl:
- settings
- summary: Get a synonym object.
- description: Get a syonym by its `objectID`. To find the object IDs for your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
+ summary: Retrieve a synonym.
+ description: |
+ Retrieves a syonym by its ID.
+ To find the object IDs for your synonyms,
+ use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: 'common/parameters.yml#/ObjectID'
@@ -31,14 +34,10 @@ put:
operationId: saveSynonym
x-acl:
- editSettings
- summary: Save a synonym.
- description: >
- Add a [synonym](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#the-different-types-of-synonyms) to an index or replace it.
-
- If the synonym `objectID` doesn't exist, Algolia adds a new one.
-
- If you use an existing synonym `objectID`, the existing synonym is replaced with the new one.
-
+ summary: Create or replace a synonym.
+ description: |
+ If a synonym with the specified object ID doesn't exist, Algolia adds a new one.
+ Otherwise, the existing synonym is replaced.
To add multiple synonyms in a single API request, use the [`batch` operation](#tag/Synonyms/operation/saveSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
@@ -86,7 +85,9 @@ delete:
x-acl:
- editSettings
summary: Delete a synonym.
- description: Delete a synonym by its `objectID`. To find the object IDs of your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
+ description: |
+ Deletes a synonym by its ID.
+ To find the object IDs of your synonyms, use the [`search` operation](#tag/Synonyms/operation/searchSynonyms).
parameters:
- $ref: '../../../common/parameters.yml#/IndexName'
- $ref: 'common/parameters.yml#/ObjectID'
diff --git a/specs/search/paths/vault/appendSource.yml b/specs/search/paths/vault/appendSource.yml
index 84bfe39bfe..07d0cc8aba 100644
--- a/specs/search/paths/vault/appendSource.yml
+++ b/specs/search/paths/vault/appendSource.yml
@@ -4,7 +4,7 @@ post:
operationId: appendSource
x-acl:
- admin
- description: Add a source to the list of allowed sources.
+ description: Adds a source to the list of allowed sources.
summary: Add a source.
requestBody:
required: true
diff --git a/specs/search/paths/vault/deleteSource.yml b/specs/search/paths/vault/deleteSource.yml
index a59bdc6a9a..3abc54972f 100644
--- a/specs/search/paths/vault/deleteSource.yml
+++ b/specs/search/paths/vault/deleteSource.yml
@@ -4,8 +4,8 @@ delete:
operationId: deleteSource
x-acl:
- admin
- description: Remove a source from the list of allowed sources.
- summary: Remove a source.
+ description: Deletes a source from the list of allowed sources.
+ summary: Delete a source.
parameters:
- name: source
in: path
diff --git a/specs/search/paths/vault/vaultSources.yml b/specs/search/paths/vault/vaultSources.yml
index c36452dca2..67f288874c 100644
--- a/specs/search/paths/vault/vaultSources.yml
+++ b/specs/search/paths/vault/vaultSources.yml
@@ -4,8 +4,8 @@ get:
operationId: getSources
x-acl:
- admin
- description: Get all allowed sources (IP addresses).
- summary: Get all allowed IP addresses.
+ summary: List allowed sources.
+ description: Retrieves all allowed IP addresses with access to your application.
responses:
'200':
description: OK
@@ -28,8 +28,8 @@ put:
operationId: replaceSources
x-acl:
- admin
- description: Replace all allowed sources.
- summary: Replace all sources.
+ summary: Replace allowed sources.
+ description: Replaces the list of allowed sources.
requestBody:
required: true
description: Allowed sources.
diff --git a/specs/search/spec.yml b/specs/search/spec.yml
index 082a2ffb71..5f9123e53e 100644
--- a/specs/search/spec.yml
+++ b/specs/search/spec.yml
@@ -1,11 +1,86 @@
openapi: 3.0.2
info:
title: Search API
- description: |-
- Use the Search REST API to manage your data (indices and records), implement search, and improve relevance (with Rules, synonyms, and language dictionaries).
+ description: |
+ The Algolia Search API lets you search, configure, and mange your indices and records.
- Although Algolia provides a REST API, you should use the official open source API [clients, libraries, and tools](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/) instead.
- There's no [SLA](https://www.algolia.com/policies/sla/) if you use the REST API directly.
+ # Client libraries
+
+ Use Algolia's API clients and libraries to reliably integrate Algolia's APIs with your apps.
+ The official API clients are covered by Algolia's [Service Level Agreement](https://www.algolia.com/policies/sla/).
+
+ See: [Algolia's ecosystem](https://www.algolia.com/doc/guides/getting-started/how-algolia-works/in-depth/ecosystem/)
+
+ # Base URLs
+
+ The base URLs for making requests to the Search API are:
+
+ - `https://{APPLICATION_ID}.algolia.net`
+ - `https://{APPLICATION_ID}-dsn.algolia.net`.
+ If your subscription includes a [Distributed Search Network](https://dashboard.algolia.com/infra),
+ this ensures that requests are sent to servers closest to users.
+
+ Both URLs provide high availability by distributing requests with load balancing.
+
+ **All requests must use HTTPS.**
+
+ # Retry strategy
+
+ To guarantee a high availability, implement a retry strategy for all API requests using the URLs of your servers as fallbacks:
+
+ - `https://{APPLICATION_ID}-1.algolianet.com`
+ - `https://{APPLICATION_ID}-2.algolianet.com`
+ - `https://{APPLICATION_ID}-3.algolianet.com`
+
+ These URLs use a different DNS provider than the primary URLs.
+ You should randomize this list to ensure an even load across the three servers.
+
+ All Algolia API clients implement this retry strategy.
+
+ # Authentication
+
+ To authenticate your API requests, add these headers:
+
+
+ x-algolia-application-id- Your Algolia application ID.
+ x-algolia-api-key-
+ An API key with the necessary permissions to make the request.
+ The required access control list (ACL) to make a request is listed in each endpoint's reference.
+
+
+
+ You can find your application ID and API key in the [Algolia dashboard](https://dashboard.algolia.com/account).
+
+ # Request format
+
+ Depending on the endpoint, request bodies are either JSON objects or arrays of JSON objects,
+
+ # Parameters
+
+ Parameters are passed as query parameters for GET and DELETE requests,
+ and in the request body for POST and PUT requests.
+
+ Query parameters must be [URL-encoded](https://developer.mozilla.org/en-US/docs/Glossary/Percent-encoding).
+ Non-ASCII characters must be UTF-8 encoded.
+ Plus characters (`+`) are interpreted as spaces.
+ Arrays as query parameters must be one of:
+
+ - A comma-separated string: `attributesToRetrieve=title,description`
+ - A URL-encoded JSON array: `attributesToRetrieve=%5B%22title%22,%22description%22%D`
+
+ # Response status and errors
+
+ The Search API returns JSON responses.
+ Since JSON doesn't guarantee any specific ordering, don't rely on the order of attributes in the API response.
+
+ Successful responses return a `2xx` status. Client errors return a `4xx` status. Server errors are indicated by a `5xx` status.
+ Error responses have a `message` property with more information.
+
+ # Version
+
+ The current version of the Search API is version 1, as indicated by the `/1/` in each endpoint's URL.
version: 1.0.0
components:
securitySchemes:
@@ -39,40 +114,89 @@ security:
apiKey: []
tags:
- name: Advanced
- description: Advanced operations.
+ description: Query your logs.
- name: Api Keys
- description: Manage your API keys.
+ x-displayName: API keys
+ description: |
+ Manage your API keys.
+
+ API requests must be authenticated with an API key.
+ API keys can have permissions (access control lists, ACL) and restrictions.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/security/api-keys/
+ description: |
+ Related guide: API keys.
+
- name: Clusters
- description: >
+ description: |
Multi-cluster operations.
- Algolia no longer offers [multi-cluster management](https://www.algolia.com/doc/guides/scaling/managing-multiple-clusters-mcm/).
-
- - If you want to partition your data per user, use facets and secured API keys instead.
- - If you need more data, consider upgrading to a bigger cluster to suit your needs. Contact [Algolia's support team](https://support.algolia.com/hc/en-us/requests/new) for details.
+ Algolia no longer offers multi-cluster management.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/scaling/managing-multiple-clusters-mcm/
+ description: |
+ Related guide: Multi-cluster management.
- name: Dictionaries
- description: Dictionary operations allow you to customize linguistic features such as [stop words](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-stop-words/), [plurals](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-plurals-and-other-declensions/), and [segmentation (compounds)](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/how-to/customize-segmentation/).
+ description: |
+ Manage your dictionaries.
+
+ Customize language-specific settings, such as stop words, plurals, or word segmentation.
+
+ Dictionaries are application-wide.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/managing-results/optimize-search-results/handling-natural-languages-nlp/
+ description: |
+ Related guide: Natural languages.
- name: Indices
- description: Manage indices, including listing them, checking and updating settings, deleting, copying, and renaming.
+ description: |
+ Manage your indices and index settings.
+
+ Indices are copies of your data that are stored on Algolia's servers.
+ They're optimal data structures for fast search and are made up of records and settings.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/sending-and-managing-data/manage-indices-and-apps/manage-indices/
+ description: |
+ Related guide: Manage your indices.
- name: Records
- description: Record operations.
+ description: |
+ Add, update, and delete records from your indices.
+
+ Records are individual items in your index.
+ When they match a search query, they're returned as search results, in the order determined by your ranking.
+ Records are schemaless JSON objects.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/sending-and-managing-data/prepare-your-data/
+ description: |
+ Related guide: Prepare your records.
- name: Rules
- description: Rules operations.
+ description: |
+ Create, update, delete, and search for rules.
+
+ Rules are _if-then_ statements that you can use to curate search results.
+ Rules have _conditions_ which can trigger _consequences_.
+ Consequences are changes to the search results, such as changing the order of search results, or boosting a facet.
+ This can be useful for tuning specific queries or for merchandising.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/managing-results/rules/rules-overview/
+ description: |
+ Related guide: Rules.
- name: Search
- description: Search operations.
+ description: Search one or more indices for matching records or facet values.
- name: Synonyms
- description: Synonym operations.
- - name: Vaults
- description: >
- Vault operations.
-
- Algolia Vault allows you to restrict network-level access to your cluster to a specific set of IP addresses: for non-authorized IP addresses, the cluster is invisible.
-
- You should authorize the IP addresses of team members who need to access the Alglolia dashboard, as it's also affected by the restricted list you set up.
-
- To access this feature, [Algolia Vault](https://www.algolia.com/doc/guides/security/algolia-vault/) must be enabled on your server. Contact [Algolia's support team](https://support.algolia.com/hc/en-us/requests/new) for details.
+ description: |
+ Create, update, delete, and search for synonyms.
- > **Note**: The maximum number of allowed sources is 1,000.
+ Synonyms are terms that the search engine should consider equal.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/
+ description: |
+ Related guide: Synonyms.
+ - name: Vaults
+ description: Algolia Vault lets you restrict access to your clusters to specific IP addresses and provides disk-level encryption at rest.
+ externalDocs:
+ url: https://www.algolia.com/doc/guides/security/algolia-vault/
+ description: |
+ Related guide: Algolia Vault.
- name: _model_index_settings
x-displayName: Index settings
description: |
diff --git a/tests/CTS/requests/search/search.json b/tests/CTS/requests/search/search.json
index e03cdcef32..f15f4e143d 100644
--- a/tests/CTS/requests/search/search.json
+++ b/tests/CTS/requests/search/search.json
@@ -363,9 +363,6 @@
"aroundPrecision": 0,
"aroundRadius": "all",
"attributeCriteriaComputedByMinProximity": true,
- "attributesForFaceting": [
- ""
- ],
"attributesToHighlight": [
""
],
@@ -392,10 +389,6 @@
"enableReRanking": true,
"enableRules": true,
"exactOnSingleWordQuery": "attribute",
- "explain": [
- "foo",
- "bar"
- ],
"facetFilters": [
""
],
@@ -545,9 +538,6 @@
"aroundPrecision": 0,
"aroundRadius": "all",
"attributeCriteriaComputedByMinProximity": true,
- "attributesForFaceting": [
- ""
- ],
"attributesToHighlight": [
""
],
@@ -574,10 +564,6 @@
"enableReRanking": true,
"enableRules": true,
"exactOnSingleWordQuery": "attribute",
- "explain": [
- "foo",
- "bar"
- ],
"facetFilters": [
""
],
diff --git a/tests/CTS/requests/search/searchDictionaryEntries.json b/tests/CTS/requests/search/searchDictionaryEntries.json
index 7021cfda72..79bd745360 100644
--- a/tests/CTS/requests/search/searchDictionaryEntries.json
+++ b/tests/CTS/requests/search/searchDictionaryEntries.json
@@ -2,16 +2,31 @@
{
"testName": "get searchDictionaryEntries results with minimal parameters",
"parameters": {
- "dictionaryName": "compounds",
+ "dictionaryName": "stopwords",
"searchDictionaryEntriesParams": {
- "query": "foo"
+ "query": "about"
}
},
"request": {
- "path": "/1/dictionaries/compounds/search",
+ "path": "/1/dictionaries/stopwords/search",
"method": "POST",
"body": {
- "query": "foo"
+ "query": "about"
+ }
+ },
+ "response": {
+ "statusCode": 200,
+ "body": {
+ "hits": [
+ {
+ "objectID": "86ef58032f47d976ca7130a896086783",
+ "language": "en",
+ "word": "about"
+ }
+ ],
+ "page": 0,
+ "nbHits": 1,
+ "nbPages": 1
}
}
},
diff --git a/website/docusaurus.config.js b/website/docusaurus.config.js
index 0d2b300fc2..f04a11b0a6 100644
--- a/website/docusaurus.config.js
+++ b/website/docusaurus.config.js
@@ -84,6 +84,9 @@ function getSpecsForNavBar() {
'redocusaurus',
{
specs: getSpecsForPlugin(),
+ theme: {
+ primaryColor: '#003DFF',
+ },
},
],
],
@@ -93,7 +96,15 @@ function getSpecsForNavBar() {
({
prism: {
// scala is required to make java work
- additionalLanguages: ['php', 'java', 'scala', 'dart', 'go', 'groovy', 'csharp']
+ additionalLanguages: [
+ 'php',
+ 'java',
+ 'scala',
+ 'dart',
+ 'go',
+ 'groovy',
+ 'csharp',
+ ],
},
navbar: {
title: 'Algolia API',
diff --git a/website/redocly.yaml b/website/redocly.yaml
index 9785fc7784..06083f7d2c 100644
--- a/website/redocly.yaml
+++ b/website/redocly.yaml
@@ -10,7 +10,12 @@ theme:
disableSearch: true
downloadDefinitionUrl: https://github.com/algolia/api-clients-automation/tree/main/specs/bundled
hideRequestPayloadSample: true
+ hideSchemaPatterns: true
+ hideSchemaTitles: true
+ hideSecuritySection: true
+ requiredPropsFirst: true
showExtensions:
- x-acl
# See https://redocly.com/docs/api-reference-docs/configuration/theming/
- theme:
+ sortEnumValuesAlphabetically: true
+ sortPropsAlphabetically: true