Algolia Contextual Search Generates Incorrect FaceFilters

karl-cardenas-coding commented 2 months ago

Have you read the Contributing Guidelines on issues?

[X] I have read the Contributing Guidelines on issues.

Prerequisites

[X] I'm using the latest version of Docusaurus.
[X] I have tried the npm run clear or yarn clear command.
[X] I have tried rm -rf node_modules yarn.lock package-lock.json and re-installing packages.
[X] I have tried creating a repro with https://new.docusaurus.io.
[X] I have read the console error message carefully (if applicable).

Description

When experimenting with the Algolia Crawler, I noticed that when contextual search is enabled no results are returned. The API requests are successful (status code 200), but no hits are returned.

I stumbled upon this Aloglia support thread trying to understand what might be causing the issue.

Upon closer investigation I noticed how the facetFilter parameter generated by Docusarus is incorrect compared to what Algolia expects.

The Crawler’s search UI includes the following values in the searchFacets query when I enable some custom facets such as as docusaurus_tag , version, and language.

[["docusaurus_tag:docs-default-4.3.x"],["version:4.3.x"],["lang:en"]]"}]}

This returns results as expected.

Now, in Docusarus, when contextual search in enabled, here is what is provided in the API request.

 ["language:en",["docusaurus_tag:default","docusaurus_tag:docs-default-current","docusaurus_tag:docs-api-current"]]"}]}

The list value is not generated correctly.

If I re-create the API post request with this vale for the faceFilter, I get the expected results.

facetFilters=[["docusaurus_tag:docs-default-4.3.x"],["version:4.3.x"],["lang:en"]]"}]}

Reproducible demo

No response

Steps to reproduce

You can use this codebox URL.

But or spin up a quick Docusarus project and use my Algolia config or the one included in the Algolia issue.

Expected behavior

The expected behavior is to return the expected results using the facefilter Docusarus includes in the post request.

Actual behavior

No results are returned.

Your environment

Public source code.
Public site URL: https://docs.spectrocloud.com
Docusaurus version used: 3.2.1
Environment name and version (e.g. Chrome 89, Node.js 16.4): Node.js 18, Chrome 123.0.6312.123
Operating system and version (e.g. Ubuntu 20.04.2 LTS): MacOS 14.4.1 (23E224)

Self-service

[ ] I'd be willing to fix this bug myself.

karl-cardenas-coding commented 2 months ago

We can close this ticket. I figured out the issue. Check your index and make sure language is an exposed facet.

I'm not sure if the default Algolia crawler config is what's causing the issue but lang is not gonna help you. You need to make sure the face language is an attribute available on you index.

{
      attributesForFaceting: [
        "type",
        "lang",
        "language",
        "version",
        "type",
        "docusaurus_tag",
      ]
}

I hope this saves other some time 😅

slorber commented 2 months ago

Yes, you need to make sure your index match our official recommendations, otherwise it's your responsibility to make things work

The recommended config contains that "language" facetting field

https://docsearch.algolia.com/docs/templates/#docusaurus-v3-template

slorber commented 2 months ago

If that helps anyone stumbling on this issue, I posted this answer in a few Algolia issues, hope it helps.

https://github.com/facebook/docusaurus/issues/6693#issuecomment-2039757018

No search result?

For anyone passing by, if you don't get any Algolia search results:

make sure that your Algolia index has the fields in the screenshot below

If you don't see these fields, then you have an index config problem

You should check your crawler config, make sure it matches the recommended one, and then delete/recreate your index based on the newly updated/fixed crawler config (Algolia team recommendation)

See also: #10007 (comment)

karl-cardenas-coding commented 2 months ago

@slorber would you be open to a PR that adds this tiny bit of information to the https://docusaurus.io/docs/search#contextual-search page? It could be a tiny lil info box and that also links to the issue #6693

Happy to author it.

slorber commented 2 months ago

@karl-cardenas-coding thanks for your proposal, but it was already on my todo list to add this index troubleshooting section so I just did it (https://github.com/facebook/docusaurus/pull/10056).

We get many support requests about this over time so it's important to explain this thing properly so I preferred to do it myself.

karl-cardenas-coding commented 2 months ago

No worries 😊 @slorber and thank you for adding the updates. That's gonna help a lot for future users.

facebook / docusaurus