Settings API - Typo Tolerance

[gmourier]

Naming proposals are open until 2022-03-31
The definitive specification is due at 2022-04-01

---

Summary

This specification describes the configuration options for the typo tolerance settings.

🤖 API Diff
📄 Rendered

• Freeze parameter naming choices
• typo or typoTolerance setting name
• Add dedicated errors for the typo tolerance API resource
• Branch telemetry to the typo tolerance customization
• Update OpenAPI specification
• Add examples for minWordSizeForTypos
• Describes Async/Sync errors

Dependent of #123

Key Points

• Add a typoTolerance index settings resource to manage customization of typo tolerance feature at index level.
  • Expose typoTolerance object on /indexes/:index_uid/settings endpoints.
  • Add GET/POST/DELETE - /indexes/:index_uid/settings/typo-tolerance endpoints.
• typoTolerance object definition is made of the following properties:
  • enabled: Whether the typo tolerance feature is enabled. (Default: true)
  • disableOnAttributes: Disable the typo tolerance feature on the specified document attributes. (Default: [])
  • disableOnWords: Disable the typo tolerance feature for a set of query terms given during a search query. (Default: [])
  • minWordSizeForTypos:
    • oneTypo: Customize the minimum size for a word to tolerate 1 typo (Default: 5)
    • twoTypos: Customize the minimum size for a word to tolerate 2 typos (Default: 9)

---

Informations To Reviewers

We could naturally think of putting the typo tolerance customization in the rankingRules typo.

This seems to be a bad idea for several reasons that have been evaluated previously:

• The rankingRules become less intuitive by doing multiple things. Currently, its purpose is to configure the ordering of the search results given ranking rules positioning.
• It would probably make reading the ranking rules more difficult if a full typo object is described.
• Moreover, if removing typo from the ranking rules settings deactivates the typo tolerance feature and the configuration of typo properties are located in the ranking rule, a user may lose information if the ranking rule is removed to deactivate it.
• In the future, if we want to expose the typo tolerance properties at search time for customization purposes. It will force us to add the customization of rankingRules at search time. Thus, rankingRules need to be updated to manage objects (Currently, it's an array of strings).

As you can see, there are a lot of things that are not desirable if we decide to manage all the typo tolerance properties within the typo ranking rule.

[bidoubiwa]

Hello!

Add a typoTolerance setting to manage customization of typo tolerance feature at index level.

👍 I agree on not adding it in the ranking rules

enabled: Whether the typo tolerance feature is enabled. (Default: true)

👍

disableOnAttributes: Disable the typo tolerance feature on the specified document attributes. (Default: [])

What do you think of disabledAttributes?

disableOnWords: Disable the typo tolerance feature for a set of query terms given during a search query. (Default: [])

What do you think of disabledWords?

minWordSizeFor1Typo: Customize the minimum size for a word to tolerate 1 typo. (Default: 5)
minWordSizeFor2Typos: Customize the minimum size for a word to tolerate 2 typos (Default: 9)

Fiou this is a complex setting 😱 I would not add a number in the setting name. I don't think it is very common to do that. But I'm not sure either.
I feel like the name is complex but I have no better options to suggest, so until then I agree with this one.

Force the definition of the whole payload on POST /indexes/:index_uid/settings/typo_tolerance ?

👍

I think we should force the whole payload. I also think this is the expected behavior. This means that in the case the update is partial, the user could potentially think they removed some settings to reset to the default ones but in fact, it will still be the old value.

Regarding the use of the POST verb, we could change it during v0.28 to PATCH during the API stabilization since it seems to better embrace the REST convention.

In which case, the partial update would make more sense indeed!

[gmourier]

@bidoubiwa I have no preference between disableOnAttributes/disableOnWords or disabledAttributes/disabledWords. Both work for me!

[brunoocasali]

Hi @gmourier this is my first review, I will learn more about the whole typo matching feature in order to help more regarding this config 😉