v1.3: Define search field at search time

[guimachiavelli]

v1.3 introduces a new search parameter, attributesToSearchOn.

attributesToSearchOn is a search parameter accepting an array of strings indicating one or more document attributes. Queries using attributesToSearchOn will restrict the search to the indicated attributes.

Given the following dataset:

{
  "id": 0,
  "name": "Our Wives Under the Sea",
  "genre": ["horror", "scifi"],
  "synopsis": "A woman returns to her wife transformed after a deep-sea adventure."
},
{
  "id": 1,
  "name": "A Strange and Stubborn Endurance",
  "genre": ["adventure"],
  "synopsis": "A man must overcome trauma and fight off a mysterious assassin."
}

And the following query:

{
  "q": "adventure",
  "attributesToSearchOn": ["genre"]
}

Meilisearch will only return document 1.

Both documents contain the word adventure, but "attributesToSearchOn": ["genre"] instructs Meilisearch to only consider results found on the genre field.

Tasks

• Add attributesToSearchOn to /reference/api/search#search_parameters
• Update search parameter tables in /reference/api/search and /reference/api/multi_search
• (Optional) Add <Capsule /> mentioning attributesToSearchOn to /learn/fine_tuning_results/filtering

References

• engine issue: Define field to search on at search-time meilisearch#3772
• engine PR: Define searchable fields at runtime meilisearch#3834
• PRD (private): https://www.notion.so/meilisearch/Define-Fields-To-Search-On-At-Search-Time-0725a20ed5bd46b593683a67697d3e7b
• SME: @ManyTheFish

[ManyTheFish]

Hello @guimachiavelli,
Some details about the feature:

• giving the attributes in a different order than the order set in the settings searchableAttributes doesn't reorder the fields' rank for the attributes ranking rule
• if the user doesn't set an array of strings, an error is thrown under the code invalid_attributes_to_search_on:

{
    "message": "Invalid value type at `.attributesToSearchOn`: expected an array, but found a string: `\"hello\"`",
    "code": "invalid_attributes_to_search_on",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_attributes_to_search_on"
}

• if the user sets an attribute that isn't in the settings searchableAttributes list, an error is thrown under the code invalid_attributes_to_search_on:

{
    "message": "Attribute `unknown` is not searchable. Available searchable attributes are: `id, title`.",
    "code": "invalid_attributes_to_search_on",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_attributes_to_search_on"
}

• a variant exists for the previous error message if some of the searchableAttributes are not in the displayAttributes, all the attributes listed in both lists will be listed in the error message but the ones that are not in the displayAttributes will be hidden and the <..hidden-attributes> mark will be added to the listed attributes in the error message:

{
    "message": "Attribute `unknown` is not searchable. Available searchable attributes are: `id, title, <..hidden-attributes>`.",
    "code": "invalid_attributes_to_search_on",
    "type": "invalid_request",
    "link": "https://docs.meilisearch.com/errors#invalid_attributes_to_search_on"
}

See you!

[guimachiavelli]

Thanks for the clarification, @ManyTheFish!

A couple of questions:

1. does attributesToSearchOn accept wildcards? For example, can I use "*" or ["*"] to select all searchableAttributes?
2. What is the default value of attributesToSearchOn? null, "*", ["*"], something else entirely?

[ManyTheFish]

Hello @guimachiavelli,

Does attributesToSearchOn accept wildcards? For example, can I use "" or [""] to select all searchableAttributes?

No, the behavior to select all attributes is to not define the field or set it to null

What is the default value of attributesToSearchOn? null, "", [""], something else entirely?

the default value is null

[ManyTheFish]

Hello @guimachiavelli, there is a small change in the error code invalid_attributes_to_search_on becomes invalid_search_attributes_to_search_on.

Meanwhile, I've updated the related specifications, I put below the dedicated PR:
meilisearch/specifications#251

Sorry for the late change! See you!

diff: #2480 (comment)

[guimachiavelli]

No problem, thanks for letting me know (and for updating the draft PR 🙏)