diff --git a/specs/composition-full/common/params/Composition.yml b/specs/composition-full/common/params/Composition.yml new file mode 100644 index 00000000000..71f49754c41 --- /dev/null +++ b/specs/composition-full/common/params/Composition.yml @@ -0,0 +1,29 @@ +enableABTest: + type: boolean + description: | + Whether to enable index level A/B testing for this run request. + If the composition mixes multiple indices, the A/B test is ignored. + default: true + x-categories: + - Advanced + +enableRules: + type: boolean + description: Whether to enable composition rules. + default: true + +getRankingInfo: + type: boolean + description: Whether the run response should include detailed ranking information. + +ruleContexts: + type: array + items: + type: string + description: | + Assigns a rule context to the run 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 \ No newline at end of file diff --git a/specs/composition-full/common/params/Search.yml b/specs/composition-full/common/params/Search.yml new file mode 100644 index 00000000000..a2c18b5f17f --- /dev/null +++ b/specs/composition-full/common/params/Search.yml @@ -0,0 +1,565 @@ +advancedSyntax: + type: boolean + 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 + +advancedSyntaxFeatures: + type: array + items: + $ref: '../../../common/schemas/IndexSettings.yml#/advancedSyntaxFeatures' + 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 + +distinct: + $ref: '../../../common/schemas/IndexSettings.yml#/distinct' + +allowTyposOnNumericTokens: + type: boolean + 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 + +alternativesAsExact: + type: array + items: + $ref: '../../../common/schemas/IndexSettings.yml#/alternativesAsExact' + description: | + Determine which plurals and synonyms should be considered an exact matches + By default, Algolia treats singular and plural forms of a word, and single-word synonyms, as [exact](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#exact) matches when searching. + For example + - "swimsuit" and "swimsuits" are treated the same + - "swimsuit" and "swimwear" are treated the same (if they are [synonyms](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#regular-synonyms)) + - `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 + +analytics: + type: boolean + description: Whether this search will be included in Analytics. + default: true + x-categories: + - Analytics + +analyticsTags: + type: array + items: + type: string + description: Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/). + default: [] + x-categories: + - Analytics + +aroundLatLng: + $ref: '../../../common/schemas/SearchParams.yml#/aroundLatLng' + +aroundLatLngViaIP: + $ref: '../../../common/schemas/SearchParams.yml#/aroundLatLngViaIP' + +aroundPrecision: + $ref: '../../../common/schemas/SearchParams.yml#/aroundPrecision' + +aroundRadius: + $ref: '../../../common/schemas/SearchParams.yml#/aroundRadius' + +attributeCriteriaComputedByMinProximity: + type: boolean + 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 + +attributesToHighlight: + type: array + items: + type: string + example: [author, title, 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. + Attribute names are case-sensitive + 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 for which to enable snippets. + Attribute names are case-sensitive + 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 + +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. + Attribute names are case-sensitive. + + - `*` 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 + +clickAnalytics: + type: boolean + 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 + +disableExactOnAttributes: + type: array + items: + type: string + 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). + Attribute names are case-sensitive + This can be useful for attributes with long values, where the likelihood 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 + +decompoundQuery: + type: boolean + description: | + Whether to split compound words in the query 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. + Decompounding doesn't work for words with [non-spacing mark Unicode characters](https://www.charactercodes.net/category/non-spacing_mark). + For example, `Gartenstühle` won't be decompounded if the `ü` consists of `u` (U+0075) and `◌̈` (U+0308). + default: true + x-categories: + - Languages + +disableTypoToleranceOnAttributes: + 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/). + Attribute names are case-sensitive + 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 + +enableABTest: + type: boolean + description: Whether to enable A/B testing for this search. + default: true + x-categories: + - Advanced + +enablePersonalization: + type: boolean + description: Whether to enable Personalization. + default: false + x-categories: + - Personalization + +enableReRanking: + type: boolean + 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 + +enableRules: + type: boolean + description: Whether to enable rules. + default: true + x-categories: + - Rules + +exactOnSingleWordQuery: + $ref: '../../../common/schemas/IndexSettings.yml#/exactOnSingleWordQuery' + +facets: + type: array + items: + type: string + 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 + +facetFilters: + $ref: '../../../common/schemas/SearchParams.yml#/facetFilters' + +facetingAfterDistinct: + type: boolean + 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 + +filters: + $ref: '../../../common/schemas/SearchParams.yml#/filters' + +getRankingInfo: + type: boolean + description: Whether the search response should include detailed ranking information. + +highlightPreTag: + type: string + 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 tag to insert after the highlighted parts in all highlighted results and snippets. + default: + x-categories: + - Highlighting and Snippeting + +hitsPerPage: + $ref: '../../../common/schemas/IndexSettings.yml#/hitsPerPage' + +ignorePlurals: + $ref: '../../../common/schemas/IndexSettings.yml#/ignorePlurals' + +insideBoundingBox: + $ref: '../../../common/schemas/SearchParams.yml#/insideBoundingBox' + +insidePolygon: + $ref: '../../../common/schemas/SearchParams.yml#/insidePolygon' + +query: + $ref: '../../../common/schemas/SearchParams.yml#/query' + +queryLanguages: + type: array + items: + $ref: '../../../common/schemas/IndexSettings.yml#/supportedLanguage' + example: + - es + description: | + Languages for language-specific query processing steps such as plurals, stop-word removal, 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 + +queryType: + $ref: '../../../common/schemas/IndexSettings.yml#/queryType' + +length: + type: integer + description: Number of hits to retrieve (used in combination with `offset`). + minimum: 0 + maximum: 1000 + x-categories: + - Pagination + +maxFacetHits: + $ref: '../../../common/schemas/IndexSettings.yml#/maxFacetHits' + +maxValuesPerFacet: + type: integer + description: Maximum number of facet values to return for each facet. + default: 100 + maximum: 1000 + x-categories: + - Faceting + +minimumAroundRadius: + type: integer + description: Minimum radius (in meters) for a search around a location when `aroundRadius` isn't set. + minimum: 1 + x-categories: + - Geo-Search + +minProximity: + type: integer + minimum: 1 + maximum: 7 + 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 + +minWordSizefor1Typo: + type: integer + 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 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 + +naturalLanguages: + type: array + items: + $ref: '../../../common/schemas/IndexSettings.yml#/supportedLanguage' + 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 + +numericFilters: + $ref: '../../../common/schemas/SearchParams.yml#/numericFilters' + +optionalFilters: + $ref: '../../../common/schemas/SearchParams.yml#/optionalFilters' + +optionalWords: + type: array + items: + type: string + 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 divided 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 + +page: + $ref: '../../../common/schemas/SearchParams.yml#/page' + +percentileComputation: + type: boolean + description: Whether to include this search when calculating processing-time percentiles. + default: true + x-categories: + - Advanced + +personalizationImpact: + type: integer + 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 + +relevancyStrictness: + type: integer + +removeStopWords: + $ref: '../../../common/schemas/IndexSettings.yml#/removeStopWords' + +removeWordsIfNoResults: + $ref: '../../../common/schemas/IndexSettings.yml#/removeWordsIfNoResults' + +replaceSynonymsInHighlight: + type: boolean + 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 occurrences of "house" are replaced by "home" in the highlighted response. + default: false + x-categories: + - Highlighting and Snippeting + +responseFields: + type: array + items: + type: string + 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 + +restrictSearchableAttributes: + type: array + items: + type: string + example: [title, author] + description: | + Restricts a search to a subset of your searchable attributes. + Attribute names are case-sensitive. + default: [] + x-categories: + - Filtering + +restrictHighlightAndSnippetArrays: + type: boolean + 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 + +ruleContexts: + type: array + items: + type: string + 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 + +sortFacetValuesBy: + type: string + 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 + +snippetEllipsisText: + type: string + description: String used as an ellipsis indicator when a snippet is truncated. + default: … + x-categories: + - Highlighting and Snippeting + +sumOrFiltersScores: + type: boolean + description: | + Whether to sum all filter scores + 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 + +synonyms: + type: boolean + description: Whether to take into account an index's synonyms for this search. + default: true + x-categories: + - Advanced + +userToken: + $ref: '../../../common/schemas/SearchParams.yml#/userToken' + +typoTolerance: + $ref: '../../../common/schemas/IndexSettings.yml#/typoTolerance' diff --git a/specs/composition-full/common/schemas/SearchParams.yml b/specs/composition-full/common/schemas/SearchParams.yml deleted file mode 100644 index 4e1e8cce086..00000000000 --- a/specs/composition-full/common/schemas/SearchParams.yml +++ /dev/null @@ -1,134 +0,0 @@ -params: - title: Composition Search parameters as object - type: object - additionalProperties: false - properties: - query: - $ref: '../../../common/schemas/SearchParams.yml#/query' - filters: - $ref: '../../../common/schemas/SearchParams.yml#/filters' - page: - $ref: '../../../common/schemas/SearchParams.yml#/page' - getRankingInfo: - type: boolean - description: Whether the search response should include detailed ranking information. - relevancyStrictness: - type: integer - facetFilters: - $ref: '../../../common/schemas/SearchParams.yml#/facetFilters' - optionalFilters: - $ref: '../../../common/schemas/SearchParams.yml#/optionalFilters' - numericFilters: - $ref: '../../../common/schemas/SearchParams.yml#/numericFilters' - hitsPerPage: - $ref: '../../../common/schemas/IndexSettings.yml#/hitsPerPage' - aroundLatLng: - $ref: '../../../common/schemas/SearchParams.yml#/aroundLatLng' - aroundLatLngViaIP: - $ref: '../../../common/schemas/SearchParams.yml#/aroundLatLngViaIP' - aroundRadius: - $ref: '../../../common/schemas/SearchParams.yml#/aroundRadius' - aroundPrecision: - $ref: '../../../common/schemas/SearchParams.yml#/aroundPrecision' - minimumAroundRadius: - type: integer - description: Minimum radius (in meters) for a search around a location when `aroundRadius` isn't set. - minimum: 1 - x-categories: - - Geo-Search - insideBoundingBox: - $ref: '../../../common/schemas/SearchParams.yml#/insideBoundingBox' - insidePolygon: - $ref: '../../../common/schemas/SearchParams.yml#/insidePolygon' - queryLanguages: - type: array - items: - $ref: '../../../common/schemas/IndexSettings.yml#/supportedLanguage' - example: - - es - description: | - Languages for language-specific query processing steps such as plurals, stop-word removal, 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 - naturalLanguages: - type: array - items: - $ref: '../../../common/schemas/IndexSettings.yml#/supportedLanguage' - 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 - enableRules: - type: boolean - description: Whether to enable rules. - default: true - x-categories: - - Rules - ruleContexts: - type: array - items: - type: string - 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 - userToken: - $ref: '../../../common/schemas/SearchParams.yml#/userToken' - clickAnalytics: - type: boolean - 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: Whether this search will be included in Analytics. - default: true - x-categories: - - Analytics - analyticsTags: - type: array - items: - type: string - description: Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/). - default: [] - x-categories: - - Analytics - enableABTest: - type: boolean - description: Whether to enable A/B testing for this search. - default: true - x-categories: - - Advanced - enableReRanking: - type: boolean - 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 \ No newline at end of file diff --git a/specs/composition-full/common/schemas/components/Injection.yml b/specs/composition-full/common/schemas/components/Injection.yml index 15819b0b382..fd3d63d5f41 100644 --- a/specs/composition-full/common/schemas/components/Injection.yml +++ b/specs/composition-full/common/schemas/components/Injection.yml @@ -1,953 +1,125 @@ -mainInjectionQueryParameters: - title: Composition Main Injection Query parameters as object +baseInjectionQueryParameters: + title: Composition common query parameters between main and injected items as object type: object additionalProperties: false properties: - 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. - Attribute names are case-sensitive. - - - `*` 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 - restrictSearchableAttributes: - type: array - items: - type: string - example: [title, author] - description: | - Restricts a search to a subset of your searchable attributes. - Attribute names are case-sensitive. - default: [] - x-categories: - - Filtering - filters: - $ref: '../../../../common/schemas/SearchParams.yml#/filters' - facetFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/facetFilters' - optionalFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/optionalFilters' - numericFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/numericFilters' - sumOrFiltersScores: - type: boolean - description: | - Whether to sum all filter scores. - - 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 - facets: - type: array - items: - type: string - 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 - maxValuesPerFacet: - type: integer - description: Maximum number of facet values to return for each facet. - default: 100 - maximum: 1000 - x-categories: - - Faceting - facetingAfterDistinct: - type: boolean - 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 - sortFacetValuesBy: - type: string - 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 + advancedSyntax: + $ref: '../../params/Search.yml#/advancedSyntax' + advancedSyntaxFeatures: + $ref: '../../params/Search.yml#/advancedSyntaxFeatures' + allowTyposOnNumericTokens: + $ref: '../../params/Search.yml#/allowTyposOnNumericTokens' + alternativesAsExact: + $ref: '../../params/Search.yml#/alternativesAsExact' + analytics: + $ref: '../../params/Search.yml#/analytics' + attributeCriteriaComputedByMinProximity: + $ref: '../../params/Search.yml#/attributeCriteriaComputedByMinProximity' attributesToHighlight: - type: array - items: - type: string - example: [author, title, 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. - Attribute names are case-sensitive. - - 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 + $ref: '../../params/Search.yml#/attributesToHighlight' + attributesToRetrieve: + $ref: '../../params/Search.yml#/attributesToRetrieve' attributesToSnippet: - type: array - items: - type: string - example: - - content:80 - - description - description: | - Attributes for which to enable snippets. - Attribute names are case-sensitive. - - 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 tag to insert before the highlighted parts in all highlighted results and snippets. - default: - x-categories: - - Highlighting and Snippeting - highlightPostTag: - type: string - description: HTML tag to insert after the highlighted parts in all highlighted results and snippets. - default: - x-categories: - - Highlighting and Snippeting - snippetEllipsisText: - type: string - description: String used as an ellipsis indicator when a snippet is truncated. - default: … - x-categories: - - Highlighting and Snippeting - restrictHighlightAndSnippetArrays: - type: boolean - 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 - hitsPerPage: - $ref: '../../../../common/schemas/IndexSettings.yml#/hitsPerPage' - length: - type: integer - description: Number of hits to retrieve (used in combination with `offset`). - minimum: 0 - maximum: 1000 - x-categories: - - Pagination - minWordSizefor1Typo: - type: integer - 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 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 - typoTolerance: - $ref: '../../../../common/schemas/IndexSettings.yml#/typoTolerance' - allowTyposOnNumericTokens: - type: boolean - 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 - disableTypoToleranceOnAttributes: - 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/). - Attribute names are case-sensitive. - - 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 - ignorePlurals: - $ref: '../../../../common/schemas/IndexSettings.yml#/ignorePlurals' - removeStopWords: - $ref: '../../../../common/schemas/IndexSettings.yml#/removeStopWords' - queryLanguages: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/supportedLanguage' - example: - - es - description: | - Languages for language-specific query processing steps such as plurals, stop-word removal, 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 - naturalLanguages: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/supportedLanguage' - 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 + $ref: '../../params/Search.yml#/attributesToSnippet' + clickAnalytics: + $ref: '../../params/Search.yml#/clickAnalytics' decompoundQuery: - type: boolean - description: | - Whether to split compound words in the query 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. - Decompounding doesn't work for words with [non-spacing mark Unicode characters](https://www.charactercodes.net/category/non-spacing_mark). - For example, `Gartenstühle` won't be decompounded if the `ü` consists of `u` (U+0075) and `◌̈` (U+0308). - default: true - x-categories: - - Languages - enableRules: - type: boolean - description: Whether to enable rules. - default: true - x-categories: - - Rules - ruleContexts: - type: array - items: - type: string - 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 - enablePersonalization: - type: boolean - description: Whether to enable Personalization. - default: false - x-categories: - - Personalization - personalizationImpact: - type: integer - 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 - queryType: - $ref: '../../../../common/schemas/IndexSettings.yml#/queryType' - removeWordsIfNoResults: - $ref: '../../../../common/schemas/IndexSettings.yml#/removeWordsIfNoResults' - advancedSyntax: - type: boolean - 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 - optionalWords: - type: array - items: - type: string - 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 divided 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 + $ref: '../../params/Search.yml#/decompoundQuery' disableExactOnAttributes: - type: array - items: - type: string - 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). - Attribute names are case-sensitive. - - This can be useful for attributes with long values, where the likelihood 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 - exactOnSingleWordQuery: - $ref: '../../../../common/schemas/IndexSettings.yml#/exactOnSingleWordQuery' - alternativesAsExact: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/alternativesAsExact' - description: | - Determine which plurals and synonyms should be considered an exact matches. - - By default, Algolia treats singular and plural forms of a word, and single-word synonyms, as [exact](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#exact) matches when searching. - For example: - - - "swimsuit" and "swimsuits" are treated the same - - "swimsuit" and "swimwear" are treated the same (if they are [synonyms](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#regular-synonyms)). - - - `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 - advancedSyntaxFeatures: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/advancedSyntaxFeatures' - 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 + $ref: '../../params/Search.yml#/disableExactOnAttributes' + disableTypoToleranceOnAttributes: + $ref: '../../params/Search.yml#/disableTypoToleranceOnAttributes' distinct: - $ref: '../../../../common/schemas/IndexSettings.yml#/distinct' - getRankingInfo: - type: boolean - description: Whether the search response should include detailed ranking information. - clickAnalytics: - type: boolean - 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: Whether this search will be included in Analytics. - default: true - x-categories: - - Analytics - analyticsTags: - type: array - items: - type: string - description: Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/). - default: [] - x-categories: - - Analytics - synonyms: - type: boolean - description: Whether to take into account an index's synonyms for this search. - default: true - x-categories: - - Advanced - replaceSynonymsInHighlight: - type: boolean - 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 occurrences of "house" are replaced by "home" in the highlighted response. - default: false - x-categories: - - Highlighting and Snippeting - minProximity: - type: integer - minimum: 1 - maximum: 7 - 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 - responseFields: - type: array - items: - type: string - 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: - $ref: '../../../../common/schemas/IndexSettings.yml#/maxFacetHits' - percentileComputation: - type: boolean - description: Whether to include this search when calculating processing-time percentiles. - default: true - x-categories: - - Advanced - attributeCriteriaComputedByMinProximity: - type: boolean - 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 + $ref: '../../params/Search.yml#/distinct' enableABTest: - type: boolean - description: Whether to enable A/B testing for this search. - default: true - x-categories: - - Advanced + $ref: '../../params/Search.yml#/enableABTest' + enablePersonalization: + $ref: '../../params/Search.yml#/enablePersonalization' enableReRanking: - type: boolean - 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 - -injectedItemsQueryParameters: - title: Composition injectedItems Query parameters as object - type: object - additionalProperties: false - properties: - 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. - Attribute names are case-sensitive. - - - `*` 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 - restrictSearchableAttributes: - type: array - items: - type: string - example: [title, author] - description: | - Restricts a search to a subset of your searchable attributes. - Attribute names are case-sensitive. - default: [] - x-categories: - - Filtering - filters: - $ref: '../../../../common/schemas/SearchParams.yml#/filters' + $ref: '../../params/Search.yml#/enableReRanking' + enableRules: + $ref: '../../params/Search.yml#/enableRules' + exactOnSingleWordQuery: + $ref: '../../params/Search.yml#/exactOnSingleWordQuery' facetFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/facetFilters' - optionalFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/optionalFilters' - numericFilters: - $ref: '../../../../common/schemas/SearchParams.yml#/numericFilters' - attributesToHighlight: - type: array - items: - type: string - example: [author, title, 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. - Attribute names are case-sensitive. - - 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 for which to enable snippets. - Attribute names are case-sensitive. - - 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 tag to insert before the highlighted parts in all highlighted results and snippets. - default: - x-categories: - - Highlighting and Snippeting + $ref: '../../params/Search.yml#/facetFilters' + filters: + $ref: '../../params/Search.yml#/filters' + getRankingInfo: + $ref: '../../params/Search.yml#/getRankingInfo' highlightPostTag: - type: string - description: HTML tag to insert after the highlighted parts in all highlighted results and snippets. - default: - x-categories: - - Highlighting and Snippeting - snippetEllipsisText: - type: string - description: String used as an ellipsis indicator when a snippet is truncated. - default: … - x-categories: - - Highlighting and Snippeting - restrictHighlightAndSnippetArrays: - type: boolean - 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 + $ref: '../../params/Search.yml#/highlightPostTag' + highlightPreTag: + $ref: '../../params/Search.yml#/highlightPreTag' + ignorePlurals: + $ref: '../../params/Search.yml#/ignorePlurals' + maxFacetHits: + $ref: '../../params/Search.yml#/maxFacetHits' + minProximity: + $ref: '../../params/Search.yml#/minProximity' minWordSizefor1Typo: - type: integer - 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 + $ref: '../../params/Search.yml#/minWordSizefor1Typo' minWordSizefor2Typos: - type: integer - 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 - typoTolerance: - $ref: '../../../../common/schemas/IndexSettings.yml#/typoTolerance' - allowTyposOnNumericTokens: - type: boolean - 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 - disableTypoToleranceOnAttributes: - 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/). - Attribute names are case-sensitive. - - 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 - ignorePlurals: - $ref: '../../../../common/schemas/IndexSettings.yml#/ignorePlurals' - removeStopWords: - $ref: '../../../../common/schemas/IndexSettings.yml#/removeStopWords' - queryLanguages: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/supportedLanguage' - example: - - es - description: | - Languages for language-specific query processing steps such as plurals, stop-word removal, 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 + $ref: '../../params/Search.yml#/minWordSizefor2Typos' naturalLanguages: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/supportedLanguage' - 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 - decompoundQuery: - type: boolean - description: | - Whether to split compound words in the query 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. - Decompounding doesn't work for words with [non-spacing mark Unicode characters](https://www.charactercodes.net/category/non-spacing_mark). - For example, `Gartenstühle` won't be decompounded if the `ü` consists of `u` (U+0075) and `◌̈` (U+0308). - default: true - x-categories: - - Languages - enableRules: - type: boolean - description: Whether to enable rules. - default: true - x-categories: - - Rules - ruleContexts: - type: array - items: - type: string - 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 - enablePersonalization: - type: boolean - description: Whether to enable Personalization. - default: false - x-categories: - - Personalization + $ref: '../../params/Search.yml#/naturalLanguages' + numericFilters: + $ref: '../../params/Search.yml#/numericFilters' + optionalFilters: + $ref: '../../params/Search.yml#/optionalFilters' + optionalWords: + $ref: '../../params/Search.yml#/optionalWords' + percentileComputation: + $ref: '../../params/Search.yml#/percentileComputation' personalizationImpact: - type: integer - 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 + $ref: '../../params/Search.yml#/personalizationImpact' + queryLanguages: + $ref: '../../params/Search.yml#/queryLanguages' queryType: - $ref: '../../../../common/schemas/IndexSettings.yml#/queryType' + $ref: '../../params/Search.yml#/queryType' + removeStopWords: + $ref: '../../params/Search.yml#/removeStopWords' removeWordsIfNoResults: - $ref: '../../../../common/schemas/IndexSettings.yml#/removeWordsIfNoResults' - advancedSyntax: - type: boolean - 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 - optionalWords: - $ref: '../../../../common/schemas/IndexSettings.yml#/optionalWords' - disableExactOnAttributes: - type: array - items: - type: string - 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). - Attribute names are case-sensitive. - - This can be useful for attributes with long values, where the likelihood 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 - exactOnSingleWordQuery: - $ref: '../../../../common/schemas/IndexSettings.yml#/exactOnSingleWordQuery' - alternativesAsExact: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/alternativesAsExact' - description: | - Determine which plurals and synonyms should be considered an exact matches. - - By default, Algolia treats singular and plural forms of a word, and single-word synonyms, as [exact](https://www.algolia.com/doc/guides/managing-results/relevance-overview/in-depth/ranking-criteria/#exact) matches when searching. - For example: - - - "swimsuit" and "swimsuits" are treated the same - - "swimsuit" and "swimwear" are treated the same (if they are [synonyms](https://www.algolia.com/doc/guides/managing-results/optimize-search-results/adding-synonyms/#regular-synonyms)). - - - `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 - advancedSyntaxFeatures: - type: array - items: - $ref: '../../../../common/schemas/IndexSettings.yml#/advancedSyntaxFeatures' - 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 - distinct: - $ref: '../../../../common/schemas/IndexSettings.yml#/distinct' - getRankingInfo: - type: boolean - description: Whether the search response should include detailed ranking information. - clickAnalytics: - type: boolean - 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: Whether this search will be included in Analytics. - default: true - x-categories: - - Analytics - analyticsTags: - type: array - items: - type: string - description: Tags to apply to the query for [segmenting analytics data](https://www.algolia.com/doc/guides/search-analytics/guides/segments/). - default: [] - x-categories: - - Analytics - synonyms: - type: boolean - description: Whether to take into account an index's synonyms for this search. - default: true - x-categories: - - Advanced + $ref: '../../params/Search.yml#/removeWordsIfNoResults' replaceSynonymsInHighlight: - type: boolean - 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 occurrences of "house" are replaced by "home" in the highlighted response. - default: false - x-categories: - - Highlighting and Snippeting - minProximity: - type: integer - minimum: 1 - maximum: 7 - 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 + $ref: '../../params/Search.yml#/replaceSynonymsInHighlight' responseFields: - type: array - items: - type: string - 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: - $ref: '../../../../common/schemas/IndexSettings.yml#/maxFacetHits' - percentileComputation: - type: boolean - description: Whether to include this search when calculating processing-time percentiles. - default: true - x-categories: - - Advanced - attributeCriteriaComputedByMinProximity: - type: boolean - description: | - Whether the best matching attribute should be determined by minimum proximity. + $ref: '../../params/Search.yml#/responseFields' + restrictHighlightAndSnippetArrays: + $ref: '../../params/Search.yml#/restrictHighlightAndSnippetArrays' + restrictSearchableAttributes: + $ref: '../../params/Search.yml#/restrictSearchableAttributes' + ruleContexts: + $ref: '../../params/Search.yml#/ruleContexts' + snippetEllipsisText: + $ref: '../../params/Search.yml#/snippetEllipsisText' + synonyms: + $ref: '../../params/Search.yml#/synonyms' + typoTolerance: + $ref: '../../params/Search.yml#/typoTolerance' - 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 - enableABTest: - type: boolean - description: Whether to enable A/B testing for this search. - default: true - x-categories: - - Advanced - enableReRanking: - type: boolean - description: | - Whether this search will use [Dynamic Re-Ranking](https://www.algolia.com/doc/guides/algolia-ai/re-ranking/). +mainInjectionQueryParameters: + title: Composition Main Injection Query parameters as object + type: object + additionalProperties: false + allOf: + - $ref: '#/baseInjectionQueryParameters' + - type: object + additionalProperties: false + properties: + facetingAfterDistinct: + $ref: '../../params/Search.yml#/facetingAfterDistinct' + facets: + $ref: '../../params/Search.yml#/facets' + hitsPerPage: + $ref: '../../params/Search.yml#/hitsPerPage' + maxValuesPerFacet: + $ref: '../../params/Search.yml#/maxValuesPerFacet' + sortFacetValuesBy: + $ref: '../../params/Search.yml#/sortFacetValuesBy' + sumOrFiltersScores: + $ref: '../../params/Search.yml#/sumOrFiltersScores' - This setting only has an effect if you activated Dynamic Re-Ranking for this index in the Algolia dashboard. - default: true - x-categories: - - Filtering +injectedItemsQueryParameters: + title: Composition injectedItems Query parameters as object + $ref: '#/baseInjectionQueryParameters' diff --git a/specs/composition-full/common/schemas/requestBodies/RunParams.yml b/specs/composition-full/common/schemas/requestBodies/RunParams.yml new file mode 100644 index 00000000000..bdf7fb4a8ad --- /dev/null +++ b/specs/composition-full/common/schemas/requestBodies/RunParams.yml @@ -0,0 +1,57 @@ +params: + title: Run composition parameters as object + type: object + additionalProperties: false + properties: + query: + $ref: '../../params/Search.yml#/query' + filters: + $ref: '../../params/Search.yml#/filters' + page: + $ref: '../../params/Search.yml#/page' + getRankingInfo: + $ref: '../../params/Composition.yml#/getRankingInfo' + relevancyStrictness: + $ref: '../../params/Search.yml#/relevancyStrictness' + facetFilters: + $ref: '../../params/Search.yml#/facetFilters' + optionalFilters: + $ref: '../../params/Search.yml#/optionalFilters' + numericFilters: + $ref: '../../params/Search.yml#/numericFilters' + hitsPerPage: + $ref: '../../params/Search.yml#/hitsPerPage' + aroundLatLng: + $ref: '../../params/Search.yml#/aroundLatLng' + aroundLatLngViaIP: + $ref: '../../params/Search.yml#/aroundLatLngViaIP' + aroundRadius: + $ref: '../../params/Search.yml#/aroundRadius' + aroundPrecision: + $ref: '../../params/Search.yml#/aroundPrecision' + minimumAroundRadius: + $ref: '../../params/Search.yml#/minimumAroundRadius' + insideBoundingBox: + $ref: '../../params/Search.yml#/insideBoundingBox' + insidePolygon: + $ref: '../../params/Search.yml#/insidePolygon' + queryLanguages: + $ref: '../../params/Search.yml#/queryLanguages' + naturalLanguages: + $ref: '../../params/Search.yml#/naturalLanguages' + enableRules: + $ref: '../../params/Composition.yml#/enableRules' + ruleContexts: + $ref: '../../params/Composition.yml#/ruleContexts' + userToken: + $ref: '../../params/Search.yml#/userToken' + clickAnalytics: + $ref: '../../params/Search.yml#/clickAnalytics' + analytics: + $ref: '../../params/Search.yml#/analytics' + analyticsTags: + $ref: '../../params/Search.yml#/analyticsTags' + enableABTest: + $ref: '../../params/Composition.yml#/enableABTest' + enableReRanking: + $ref: '../../params/Search.yml#/enableReRanking' \ No newline at end of file diff --git a/specs/composition-full/paths/search/search.yml b/specs/composition-full/paths/search/search.yml index b9d9fd3a3e1..8e293971bbf 100644 --- a/specs/composition-full/paths/search/search.yml +++ b/specs/composition-full/paths/search/search.yml @@ -20,7 +20,7 @@ post: additionalProperties: false properties: params: - $ref: '../../common/schemas/SearchParams.yml#/params' + $ref: '../../common/schemas/requestBodies/RunParams.yml#/params' responses: '200': description: OK diff --git a/specs/composition-full/paths/search/searchForFacetValues.yml b/specs/composition-full/paths/search/searchForFacetValues.yml index 8f2164a4218..424ce7ee098 100644 --- a/specs/composition-full/paths/search/searchForFacetValues.yml +++ b/specs/composition-full/paths/search/searchForFacetValues.yml @@ -41,7 +41,7 @@ post: maxFacetHits: $ref: '../../../common/schemas/IndexSettings.yml#/maxFacetHits' searchQuery: - $ref: '../../common/schemas/SearchParams.yml#/params' + $ref: '../../common/schemas/requestBodies/RunParams.yml#/params' responses: '200': description: OK