Naming: facetsDistribution at search (in request and response body)

[curquiza]

Currently, when the users want to get the distribution of their facets, they have to do this query:

curl \
  -X POST 'http://localhost:7700/indexes/movies/search' \
  -H 'Content-Type: application/json' \
  --data-binary '{ "q": "Batman", "facetsDistribution": ["genres"] }'

and they will get this response

{
  …
  "nbHits": 1684,
  "query": "Batman",
  "exhaustiveFacetsCount": false,
  "facetsDistribution": {
    "genres": {
      "action": 273,
      "animation": 118,
      "adventure": 132,
      "fantasy": 67,
      "comedy": 475,
      "mystery": 70,
      "thriller": 217
    }
  }
}

There is a typo since it should have been facetDistribution and not facetsDistribution (without the s).
Months ago, we discussed with @dichotommy who does not really like the "facet distribution" name. With v0.28.0 coming, this is an opportunity to change the naming, or at least, fix the typo.

Pinging @meilisearch/docs-team as the naming champions 🤘

[guimachiavelli]

Two initial questions from me:

1. @dichotommy, what didn't you like about facetDistribution? Not saying I like/dislike it, just curious to know the reason behind it;
2. how does this work with filters now that facets and filters are the same thing? Do we know of any uses for facetsDistribution besides building faceting UIs?

[gmourier]

2. Good question @guimachiavelli, indeed facetsDistribution is necessary to return the information and to be able to build a facetting interface with the count for each item of a facet. Apart from that, I don't see any other obvious use-case.

[guimachiavelli]

thanks for the info, @gmourier. My reasoning here is to understand whether we can become more user-friendly by using a term less specific than facets. Like, a user might not know what a facet is but still appreciate a parameter that gives them a list of hits per attribute value.

From a diametrically opposed perspective, if facetsDistribution is only ever going to be used building faceting UIs, couldn't we just call it facets?

[curquiza]

FYI, facets is used by Algolia (in the body request and response) 😇

[bidoubiwa]

I like @guimachiavelli suggestion of only using facets. On top of that, since these are also estimated distribution, should we consider estimatedFacets ?

As per #394 (reply in thread)

[curquiza]

I agree with you, technically it's estimated.
But I am afraid of the breaking changes later, but also of the "image" of the feature, like it's not working like for Algolia or Typesense.
Also, regarding nbHits, we changed nbHits to estimatedXXX mostly to prevent people from using it.
For the facets, in any case, and no matter is the name, the users would need to use facetsDistribution (or whatever) since it's a feature we promote. But yes, I agree this is technically not totally true without the estimated currently.

[dichotommy]

@dichotommy, what didn't you like about facetDistribution?

I think my main complaints about facetsDistribution were that

1. facet does not mean much to users who aren't experienced with search interfaces,
2. distribution is a big word that could be difficult for non-native english speakers
3. taking the name as a whole, it isn't clear what the parameter will return—or at least it wasn't at all clear to me back when I was a Meilisearch newbie.

It's probably because I've been at Meilisearch for a while and have a good understanding of faceting now that today I look at this parameter and don't really see anything wrong with it 🙈

I don't think these problems are easy to resolve. #2 is particularly difficult because there aren't a lot of other words with this meaning in English ("spread"? "allotment"? "allocation"? none of these improve the situation). As for #1, we may want to keep facet in the word regardless since, as @gmourier said, faceting is the primary use-case for this parameter.

I tried to ignore all of this and create a name for this parameter from scratch, but I am not satisfied with the results.

^ Shorter, less clear
hitSpread
facetSpread
attributeSpread
hitDistribution
valueDistribution
resultDistribution
attributeDistribution
numberOfResultsByFilter
numberOfResultsByFacet
v longer, more clear

Of these, the options containing attribute (attributeSpread and attributeDistribution) would be my preference since they suggest that the parameter accepts a list of attributes.

facetSpread also is not bad, since spread is both less intimidating and shorter than distribution. But even then, not convinced that any of these would be a cut-and-dry improvement over facetDistribution—they would just be different choices.

[guimachiavelli]

I have a weak spot for Very Descriptive and Long Names, so I do like numberOfResultsByFacet. The only space for doubt would be facet because we have established that first-time search engine users might not know what that term means.

I think numberOfResultsByFilter is problematic because a filter can be not only e.g. genre = action, but also e.g. price > 1.00. Meaning, facetsDistributions gives users a result spread based only on a subset of filters.

But in general I agree with @dichotommy: most of the ideas presented so far are not necessarily better than facetDistribution, just different choices with minor tradeoffs.

[bidoubiwa]

I likehitDistribution it makes sense for me more than facetDistribution. It could be explained by How the hits are distributed amongst the different facets (I think, my brain hurts).

But facetDistribution is still a valid option

[gmourier]

My concern with your suggestion is most of them do not include the facet term, which is known by the users wanting the feature. Can you confirm (or not) @gmourier?

I have the same concerns, I think keeping facet in the name is important for several things.

1. Advanced users who have already built a search experience will immediately understand what it is for.
2. What term will we use in the documentation or in our communication to talk about faceted search?

[bidoubiwa]

Advanced users who have already built a search experience will immediately understand what it is for.

Advanced user might also understand what hitDistribution means. It is technically not incorrect. By changing its name to something more simple, we also ensure non-advanced user can understand quickly what it contains.

What term will we use in the documentation or in our communication to talk about faceted search?

We do not need to change this naming for me. It is not incompatible to have hitDistribution and a guide called faceted search.

[gmourier]

The drawback is that the feature could be directly acquired with the name facet. Knowing that this field will be mainly used in the construction of a faceted search I'm not sure it's a good idea to "separate" the purpose from the field name 🤔

[guimachiavelli]

Having a "Faceted search guide" using a facet-less terms is not that bad, I think it is generally better to keep (customer-facing) things consistent. If something will almost only ever be used for faceting, referring facets in that thing's name is reasonable.

As for users who do not know what facets are…I guess the docs are there for them?

[gmourier]

I also agree with you @guimachiavelli, the documentation is also there to explain the terms used and make the users more knowledgeable IMO.

[curquiza]

After reading your comments, and discussing with @gmourier, we decided to add a constraint to this new name: having the facet word in the name.

Before opening a survey, it means the short list could be

• facet
• facets
• facetDistribution
• facetSpread

Do you think about any other candidate you would like to see in the survey?

Other question: does the response and request parameter should keep the same name?

[bidoubiwa]

Other question: does the response and request parameter should keep the same name?

I don't think this is a good idea. It is misleading that both naming have different types depending on the environment.

For the naming I don't like spread, I feel like it is not the use case for that wording. It would be more like spreading the information to all instances for example.

For the response body, I think facetsDistribution is the most clear one but I may be biased. In which case facets is cool.

For the request, addFacetDistribution ?

[curquiza]

I don't this is a good idea. It is misleading that both naming have different types depending on the environment.

I'm not sure to understand, do you want 2 different names or the same name?

For the request, addFacetDistribution ?

addFacetDistribution supposed the variable a boolean, as we are discussion for the new matches name, which is not true here

[bidoubiwa]

I'm not sure to understand, do you want 2 different names or the same name?

Yes, I think it is confusing! Sorry if it was not clear.

If in one typed object I have

type SearchParams = {
   // ...
   facetsDistribution?: string[]
}

and in another

type SearchResponse = {
   // ...
   facetsDistribution: Record<Facet, CategoriesDistribution>
}

It might be easy to make mistakes or misunderstand which types is used in which condition.

addFacetDistribution supposed the variable a boolean, as we are discussion for the new matches name, which is not true here

Do you mean we would not be consistent since we are using matches (boolean) as a search query parameter? So it would make more consistent to call it facets or just facetDistribution?

[curquiza]

Do you mean we would not be consistent since we are using matches (boolean) as a search query parameter? So it would make more consistent to call it facets or just facetDistribution?

I say, when you are using a verb at the beginning of the search parameter like addMatchesPostition, you understand you have to give a boolean.
Here if you have the name addFacetDistribution as a search parameter, you can think you have to give a boolean as value, but it's false: you have to give an attribute list

[bidoubiwa]

You are right!

facets is the best option for me now

[curquiza]

Final survey - in the search REQUEST

Please take a look at the previous discussion before voting, ensuring you have the whole context 😇

Currently in the search REQUEST, to activate the faceting feature, the users have to use the facetsDistribution parameter. Due to the English typo, keep the current name is not a possibility

Here are the new alternatives:
😄 facet
🎉 facets
❤️ facetDistribution
🚀 facetSpread

[curquiza]

Final survey - in the search RESPONSE

Please take a look at the previous discussion before voting, ensuring you have the whole context 😇

Currently in the search RESPONSE, when returning the facets, Meilisearch returns them into the facetsDistribution field in the search response. Due to the English typo, keeping the current name is not a possibility

Here are the new alternatives:
😄 facet
🎉 facets
❤️ facetDistribution
🚀 facetSpread

[curquiza]

Hello, here are the final namings:
In the request body: facets
In the response body: facetDistribution

@gmourier I let you update this spec: meilisearch/specifications#135 😇

[gmourier]

Specified in meilisearch/specifications#135.

Locking the discussion.