Explain Query Language#
The idea of Search-a-licious is to provide a powerfull yet easy to use API, through the use of a well proven language: Lucene Query Language.
While Elasticsearch provides a way to use this language in the queries, it has some important limitations like the lack of support for nested and object fields.
Thanks to the luqum library, Search-a-licious is able to use Lucene Query Language in a broader way.
Search-a-licious also use luqum to introspect the query and transform it to add features corresponding to your configuration and leverage taxonomies and other peculiarities.
It enables for example taking into account synonyms, or adding the languages to query about on the fly without the need to complexify the query to much at API level.
Query syntax#
The query syntax is quite simple, you can either:
- query for simple word in the default texts fields (those having
full_text_searchproperty in your configuration) by simply having the word in your query:Entries with textchocolatechocolate - or match exactly a full sentences by using quotes:
Entries with text
"dark chocolate"dark chocolate - you can also match a word or phrase in a specific field by using the field name, followed by a colon:
Entries with labels containing
labels:organicorganic - you can have more than one term, the query will try to match all terms:
Entries with text
"dark chocolate" labels:organicdark chocolateand labels containingorganic. This example assumes theindexsynonyms strategy, whereorganicis matched through the synonyms of the taxonomy. With thenonestrategy, or if you want to match a stored value exactly, use the value as stored in the index (for Open Food Facts labels, the taxonomy id, eg.labels:"en:organic"). See taxonomy fields. - you can combine queries with
AND,ORandNOToperators, and use parenthesis to group them:Entries with text"dark chocolate" AND (labels:organic OR labels:vegan) AND NOT nutriscore_grade:(e OR d)dark chocolate, labels containingorganicorvegan, and Nutri-Score noteord - you can query a sub field of an object by using "." between the field and the sub field
(the ":" form is not valid):
Entries with sugar between 10 and 15 grams per 100g
nutriments.sugars_100g:[10 TO 15] - in range you can use * for unbounded values:
Entries with sugar below 20 g and proteins above 2g for 100g
nutriments.sugars_100g:[* TO 20] AND nutriments.proteins_100g:[2 TO *] - match field existence with
*:Entries with Nutri-Score computednutriscore_grade:*
Different type of fields#
When you created you configuration, you defined different fields types. It's important because the matching possibilities are not the same.
In particular for text entries, there are two types of fields:
- keyword fields, that are used for exact matching
- full text fields, where part of the text can be matched, with complex matching possibilities
There are also numeric and date fields, that can be used for range matching, or to make computations.
Taxonomy fields#
What you can write after labels: depends on the
synonyms_strategy of your index:
- with
index, you can use a name or a synonym, in any language of the request:labels:organic,labels:bio - with
none, the field only contains taxonomy ids, so you must use the id, with its language prefix:labels:"en:organic". A barelabels:organicmatches nothing.
Full text queries#
A word or a quoted phrase without a field name is searched in all the fields
that have full_text_search: true in the configuration.
For fields that have one text per language,
only the languages of the request (the langs parameter) are searched.
- a word matches if it is found in any of those fields
- a quoted phrase matches if the words are found next to each other, in the same order
*and?can be used inside a word (choco*,milk?), but*alone is refused because it would match everything- the
boost_phraseparameter of the API favors entries where the words of the query are consecutive, even if you did not use quotes. It only applies to the default best-match order: it is ignored whensort_byis set.
Queries are transformed before being sent to Elasticsearch, this is how the languages and your configuration are taken into account.