Merge pull request #147 from algolia/feature/explain-decompounding

Feature/explain decompounding

Author: q-litzler

src/commonMain/kotlin/com/algolia/search/dsl/DSLQuery.kt

@@ -1,5 +1,6 @@
 package com.algolia.search.dsl
 
+import com.algolia.search.dsl.advanced.DSLExplainModules
 import com.algolia.search.dsl.advanced.DSLResponseFields
 import com.algolia.search.dsl.attributes.DSLAttributes
 import com.algolia.search.dsl.attributes.DSLAttributesSet
@@ -170,4 +171,11 @@ public fun Query.analyticsTags(block: DSLStrings.() -> Unit) {
  */
 public fun Query.responseFields(block: DSLResponseFields.() -> Unit) {
     responseFields = DSLResponseFields(block)
+}
+
+/**
+ * Assign the output of [block] to [Query.explainModules].
+ */
+public fun Query.explainModules(block: DSLExplainModules.() -> Unit) {
+    explainModules = DSLExplainModules(block)
 }

src/commonMain/kotlin/com/algolia/search/dsl/advanced/DSLExplainModules.kt

@@ -0,0 +1,31 @@
+package com.algolia.search.dsl.advanced
+
+import com.algolia.search.dsl.DSL
+import com.algolia.search.dsl.DSLParameters
+import com.algolia.search.model.search.ExplainModule
+
+
+/**
+ * DSL for building a [List] of [ExplainModule].
+ */
+@Suppress("PropertyName")
+@DSLParameters
+public class DSLExplainModules(
+    private val explainModules: MutableList<ExplainModule> = mutableListOf()
+) {
+
+    public val MatchAlternatives = ExplainModule.MatchAlternatives
+    /**
+     * Add [this] to [explainModules].
+     */
+    public operator fun ExplainModule.unaryPlus() {
+        explainModules += this
+    }
+
+    public companion object : DSL<DSLExplainModules, List<ExplainModule>> {
+
+        override operator fun invoke(block: DSLExplainModules.() -> Unit): List<ExplainModule> {
+            return DSLExplainModules().apply(block).explainModules
+        }
+    }
+}

src/commonMain/kotlin/com/algolia/search/model/response/ResponseSearch.kt

@@ -5,6 +5,7 @@ import com.algolia.search.model.Attribute
 import com.algolia.search.model.IndexName
 import com.algolia.search.model.ObjectID
 import com.algolia.search.model.QueryID
+import com.algolia.search.model.filter.FilterGroup
 import com.algolia.search.model.insights.InsightsEvent
 import com.algolia.search.model.search.*
 import com.algolia.search.model.settings.Settings
@@ -132,7 +133,7 @@ public data class ResponseSearch(
     @SerialName(KeyFacets) @Serializable(KSerializerFacetMap::class) val facetsOrNull: Map<Attribute, List<Facet>>? = null,
     /**
      * A mapping of each facet name to the corresponding facet counts for disjunctive facets.
-     * Returned only by the [EndpointSearch.searchDisjunctiveFacets] method.
+     * Returned only by the [EndpointSearch.advancedSearch] method.
      * [Documentation][https://www.algolia.com/doc/guides/building-search-ui/going-further/backend-search/how-to/faceting/?language=kotlin#conjunctive-and-disjunctive-faceting]
      */
     @SerialName(KeyDisjunctiveFacets) @Serializable(KSerializerFacetMap::class) val disjunctiveFacetsOrNull: Map<Attribute, List<Facet>>? = null,
@@ -152,9 +153,14 @@ public data class ResponseSearch(
      */
     @SerialName(KeyQueryID) val queryIDOrNull: QueryID? = null,
     /**
-     *
+     * A mapping of each facet name to the corresponding facet counts for hierarchical facets.
+     * Returned only by the [EndpointSearch.advancedSearch] method, only if a [FilterGroup.And.Hierarchical] is used.
      */
-    @SerialName(KeyHierarchicalFacets) val hierarchicalFacetsOrNull: Map<Attribute, List<Facet>>? = null
+    @SerialName(KeyHierarchicalFacets) val hierarchicalFacetsOrNull: Map<Attribute, List<Facet>>? = null,
+    /**
+     * Meta-information as to how the query was processed.
+     */
+    @SerialName(KeyExplain) val explainOrNull: Explain? = null
 ) {
 
     public val hits: List<Hit>
@@ -244,6 +250,9 @@ public data class ResponseSearch(
     public val hierarchicalFacets: Map<Attribute, List<Facet>>
         get() = hierarchicalFacetsOrNull!!
 
+    public val explain: Explain
+        get() = explainOrNull!!
+
     @Deprecated(
         message = "Use getObjectPosition instead.",
         replaceWith = ReplaceWith("getObjectPosition(objectID)"),

src/commonMain/kotlin/com/algolia/search/model/search/Alternative.kt

@@ -0,0 +1,15 @@
+package com.algolia.search.model.search
+
+import com.algolia.search.serialize.*
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+
+@Serializable
+public data class Alternative(
+    @SerialName(KeyTypes) val types: List<AlternativeType>,
+    @SerialName(KeyWords) val words: List<String>,
+    @SerialName(KeyTypos) val typos: Int,
+    @SerialName(KeyOffset) val offset: Int,
+    @SerialName(KeyLength) val length: Int
+)

src/commonMain/kotlin/com/algolia/search/model/search/AlternativeType.kt

@@ -0,0 +1,115 @@
+package com.algolia.search.model.search
+
+import com.algolia.search.model.Raw
+import com.algolia.search.serialize.*
+import kotlinx.serialization.Decoder
+import kotlinx.serialization.Encoder
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.internal.StringSerializer
+
+/**
+ * Type for [Alternative.type]
+ */
+@Serializable(AlternativeType.Companion::class)
+public sealed class AlternativeType(override val raw: String) : Raw<String> {
+
+    /**
+     * Literal word from the query
+     */
+    public object Original : AlternativeType(KeyOriginal)
+
+    /**
+     * Original keywords that should not appear in the results because it had a “minus” sign at the beginning and
+     * [Query.advancedSyntax] enabled.
+     */
+    public object Excluded : AlternativeType(KeyExcluded)
+
+    /**
+     * Original keywords that was declared in [Query.optionalWords].
+     */
+    public object Optional : AlternativeType(KeyOptional)
+
+    /**
+     * Original keywords that was discarded by [Query.removeStopWords].
+     */
+    public object StopWord : AlternativeType(KeyStopWord)
+
+    /**
+     * Alternative that mostly looks like another original keyword. “Mostly looks like” is defined by the
+     * Damerau-Levenshtein distance between the two words, which counts 1 typo as any insertion, deletion, substitution,
+     * or transposition of a single character. The field typos contains this number.
+     * Because it would make no sense to display every combination of typos possible, the response only contains typos
+     * that were found in the documents.
+     */
+    public object Typo : AlternativeType(KeyTypo)
+
+    /**
+     * Alternative that tries to split every original keyword into 2 valid sub-keywords.
+     * As for typo, only sub-keywords that were found in the documents may return a split.
+     * There is always 0 or 1 split per original keyword.
+     */
+    public object Split : AlternativeType(KeySplit)
+
+    /**
+     * Alternative that tries to build bigrams out of every adjacent pair of keywords (up to the 5th keyword),
+     * and to build an n-gram out of all the words of the query (if it contains at least 3 words).
+     */
+    public object Concat : AlternativeType(KeyConcat)
+
+    /**
+     * Any of the following kinds of alternatives: one-way synonym, two-way synonym, n-way synonym.
+     */
+    public object Synonym : AlternativeType(KeySynonym)
+
+    /**
+     * Any of the following kinds of alternatives: one-way alternative correction, two-way alternative correction,
+     * n-way alternative correction. The difference between a synonym and an alternative correction can also be seen
+     * in the field typos, which will always be 0 in the case of a synonym and 1 or 2 in the case of an alternative
+     * correction.
+     */
+    public object AlternativeCorrection : AlternativeType(KeyAltcorrection)
+
+    /**
+     * Any declension of the original keywords, including singular and plural, case
+     * (nominative, accusative, genitive etc.), gender, and others depending on the language.
+     * Every possible combination is returned, regardless of what the documents contain.
+     */
+    public object Plural : AlternativeType(KeyPlural)
+
+    /**
+     * Word made of several consecutive original query words.
+     * It is like a concatenation,but based on a decompounding dictionary.
+     */
+    public object Compound : AlternativeType(KeyCompound)
+
+    public data class Other(override val raw: String) : AlternativeType(raw)
+
+    companion object : KSerializer<AlternativeType> {
+
+        private val serializer = StringSerializer
+
+        override val descriptor = serializer.descriptor
+
+        override fun serialize(encoder: Encoder, obj: AlternativeType) {
+            serializer.serialize(encoder, obj.raw)
+        }
+
+        override fun deserialize(decoder: Decoder): AlternativeType {
+            return when (val string = serializer.deserialize(decoder)) {
+                KeyOriginal -> Original
+                KeyExcluded -> Excluded
+                KeyOptional -> Optional
+                KeyStopWord -> StopWord
+                KeyTypo -> Typo
+                KeySplit -> Split
+                KeyConcat -> Concat
+                KeySynonym -> Synonym
+                KeyAltcorrection -> AlternativeCorrection
+                KeyPlural -> Plural
+                KeyCompound -> Compound
+                else -> Other(string)
+            }
+        }
+    }
+}

src/commonMain/kotlin/com/algolia/search/model/search/Explain.kt

@@ -0,0 +1,11 @@
+package com.algolia.search.model.search
+
+import com.algolia.search.serialize.KeyMatch
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+
+@Serializable
+public data class Explain(
+    @SerialName(KeyMatch) val match: Match
+)

src/commonMain/kotlin/com/algolia/search/model/search/ExplainModule.kt

@@ -0,0 +1,36 @@
+package com.algolia.search.model.search
+
+import com.algolia.search.model.Raw
+import com.algolia.search.serialize.KeyMatchAlternatives
+import kotlinx.serialization.Decoder
+import kotlinx.serialization.Encoder
+import kotlinx.serialization.KSerializer
+import kotlinx.serialization.Serializable
+import kotlinx.serialization.internal.StringSerializer
+
+
+@Serializable(ExplainModule.Companion::class)
+public sealed class ExplainModule(override val raw: String) : Raw<String> {
+
+    public object MatchAlternatives : ExplainModule(KeyMatchAlternatives)
+
+    public data class Other(override val raw: String) : ExplainModule(raw)
+
+    companion object : KSerializer<ExplainModule> {
+
+        private val serializer = StringSerializer
+
+        override val descriptor = serializer.descriptor
+
+        override fun serialize(encoder: Encoder, obj: ExplainModule) {
+            serializer.serialize(encoder, obj.raw)
+        }
+
+        override fun deserialize(decoder: Decoder): ExplainModule {
+            return when (val string = serializer.deserialize(decoder)) {
+                KeyMatchAlternatives -> MatchAlternatives
+                else -> Other(string)
+            }
+        }
+    }
+}

src/commonMain/kotlin/com/algolia/search/model/search/Match.kt

@@ -0,0 +1,11 @@
+package com.algolia.search.model.search
+
+import com.algolia.search.serialize.KeyAlternatives
+import kotlinx.serialization.SerialName
+import kotlinx.serialization.Serializable
+
+
+@Serializable
+public data class Match(
+    @SerialName(KeyAlternatives) val alternatives: List<Alternative>
+)

src/commonMain/kotlin/com/algolia/search/model/search/Query.kt

@@ -456,16 +456,26 @@ public data class Query(
      * [Documentation][https://www.algolia.com/doc/api-reference/api-parameters/percentileComputation/?language=kotlin]
      */
     @SerialName(KeyPercentileComputation) var percentileComputation: Boolean? = null,
+
     /**
      *  Overrides the query parameter and performs a more generic search that can be used to find "similar" results.
      *  Engine default: ""
      *  [Documentation][https://www.algolia.com/doc/api-reference/api-parameters/similarQuery/?language=kotlin]
      */
     @SerialName(KeySimilarQuery) var similarQuery: String? = null,
+
     /**
      * Whether this query should be taken into consideration by currently active ABTests.
      * Engine default: true
      * [Documentation][https://www.algolia.com/doc/api-reference/api-parameters/enableABTest/?language=kotlin]
      */
-    @SerialName(KeyEnableABTest) var enableABTest: Boolean? = null
+    @SerialName(KeyEnableABTest) var enableABTest: Boolean? = null,
+
+    /**
+     * Enriches the API’s response with meta-information as to how the query was processed.
+     * It is possible to enable several [ExplainModule] independently.
+     * Engine default: null
+     * [Documentation][https://www.algolia.com/doc/api-reference/api-parameters/decompoundedAttributes/?language=kotlin]
+     */
+    @SerialName(KeyExplain) var explainModules: List<ExplainModule>? = null
 )

src/commonMain/kotlin/com/algolia/search/model/settings/DecompoundedAttributes.kt

@@ -3,7 +3,7 @@ package com.algolia.search.model.settings
 import com.algolia.search.model.Attribute
 import com.algolia.search.model.search.Language
 import kotlinx.serialization.*
-import kotlinx.serialization.internal.HashMapSerializer
+import kotlinx.serialization.internal.PairSerializer
 
 
 /**
@@ -14,16 +14,12 @@ import kotlinx.serialization.internal.HashMapSerializer
  * The goal of decompounding, regarding the previous example, is to index both Baum and Haus separately,
  * nstead of as a single word.
  */
-@Serializable(DecompoundedAttributes.Companion::class)
+@Serializable
 public data class DecompoundedAttributes internal constructor(
-    val map: Map<Language, List<Attribute>>
+    val language: Language,
+    val attributes: List<Attribute>
 ) {
 
-    internal constructor(
-        language: Language,
-        attributes: List<Attribute>
-    ) : this(mapOf(language to attributes.toList()))
-
     public constructor(
         language: Language.German,
         vararg attributes: Attribute
@@ -38,19 +34,4 @@ public data class DecompoundedAttributes internal constructor(
         language: Language.Dutch,
         vararg attributes: Attribute
     ) : this(language, attributes.toList())
-
-    companion object : KSerializer<DecompoundedAttributes> {
-
-        private val serializer = HashMapSerializer(Language, Attribute.list)
-
-        override val descriptor: SerialDescriptor = serializer.descriptor
-
-        override fun serialize(encoder: Encoder, obj: DecompoundedAttributes) {
-            serializer.serialize(encoder, obj.map)
-        }
-
-        override fun deserialize(decoder: Decoder): DecompoundedAttributes {
-            return DecompoundedAttributes(serializer.deserialize(decoder))
-        }
-    }
 }