Help:CirrusSearch/Logical operators

'  currently does not support'' classic boolean searching, and the logical operators  and  should be used with great care, if at all. '''

Negation and parentheses
CirrusSearch does support several ways of indicating negation. The following queries are all equivalent: (minus sign),  (exclamation point), and  (  operator).

CirrusSearch does not support parentheses, and they are removed from the query.

Lucene,, and
CirrusSearch is built on top of Elasticsearch, which in turn is built on Lucene. Our Lucene implementation does not support the classic boolean or  operators, though it does offer those keywords as binary operators.

Instead Lucene converts and  to a different formalism—unary  and  operators—giving results that sometimes mimic the expected boolean results, but which can also be very divergent from them. ( Note that CirrusSearch does not currently support   or    operators in user queries.  They are used here only to demonstrate the internal workings of Lucene. )

In Lucene,  indicates that a search term is required and must be present in any results. So, a query like would only return results that contain some form of dog in them (note that this would also be equivalent to just searching for  ).

On the other hand, terms are optional but should be present if possible; while they are not strictly required, they do effect ranking. So would require dog in every result, but would generally rank those that also contain cat as better matches.

The one exception to terms being optional is that if there are zero  terms, then at least one  term would be present in each result. Thus, would actually give results that have at least one of dog, cat , or fish present—though any results with all three would generally rank higher.

Classic boolean search often has an implicit, meaning that any query terms without an explicit boolean operator between them are assumed to have an  between them. In Lucene, any query term without an explicit or  is assumed to have an implicit  applied to it.

Converting and
Lucene converts and  to  and  in a way that sometimes gives the expected results, but often leads to very unexpected results.

When Lucene encounters, it applies  to the terms before and after the. When it encounters, it applies  to the terms before and after the. The query is processed left to right, and later or  operators override earlier ones (see examples below).

This effectively gives an unusual "backward order precedence" to the operators, and the results can be quite unexpected compared to classic boolean searching.

Examples that go wrong
Below are some worked examples where the conversion from / to / gives divergent results from the expectations of classic boolean operators.


 * convert to  before and after, giving:
 * convert to  before and after (in this case overriding the previously applied  ), giving:
 * The result set is thus the same as, with  being optional (and only affecting ranking).
 * convert to  before and after (in this case overriding the previously applied  ), giving:
 * The result set is thus the same as, with  being optional (and only affecting ranking).
 * The result set is thus the same as, with  being optional (and only affecting ranking).


 * convert to  before and after, giving:
 * apply an implicit to any term without an explicit  or , giving:
 * In a classic boolean system with implicit, we would expect that  and  to be the same, but compare this to the example above to see the difference—only  is required here, while  and  are both required above.
 * apply an implicit to any term without an explicit  or , giving:
 * In a classic boolean system with implicit, we would expect that  and  to be the same, but compare this to the example above to see the difference—only  is required here, while  and  are both required above.
 * In a classic boolean system with implicit, we would expect that  and  to be the same, but compare this to the example above to see the difference—only  is required here, while  and  are both required above.


 * convert to  before and after, giving:
 * convert to  before and after, giving:
 * The result set is thus the same as simply searching for, with  and  only affecting ranking.  This also means that if there are zero documents with either  or  in them, you will get the same results searching for  as you would for just searching for  , which is not what you would expect from a classic boolean system.
 * convert to  before and after, giving:
 * The result set is thus the same as simply searching for, with  and  only affecting ranking.  This also means that if there are zero documents with either  or  in them, you will get the same results searching for  as you would for just searching for  , which is not what you would expect from a classic boolean system.
 * The result set is thus the same as simply searching for, with  and  only affecting ranking.  This also means that if there are zero documents with either  or  in them, you will get the same results searching for  as you would for just searching for  , which is not what you would expect from a classic boolean system.

In general, mixing with , including implicit  in one query gives results that are unintuitive in a classic boolean framework. It can also be very difficult to detect these cases where the boolean logic goes awry, unless you already know exactly how many documents contain each possible positive and negative combination of your query terms.

Common use cases
If you have no explicit operators, then the boolean default is and the Lucene default is , which are equivalent if they are the only operators present in the query:


 * — user intent: all three terms must be present in any results
 * — explicit classic boolean query: all three terms must be present in any results
 * — Lucene interpretation: all three terms must be present in any results

However, since is implicit, nothing is gained by making it explicit by using , other than the potential for later boolean confusion.

If the only operator in the query is —crucially meaning that there is no implicit , then it is the same as everything having a  (recall that if a query has  terms but no  terms, than at least one of the  terms will be present in any result):


 * — classic boolean query: at least one of the three terms must be present in any results
 * — Lucene interpretation: at least one of the three terms must be present in any results

Be very careful with implicit / ! In the example above, the implicit  applied to  means that neither  nor  are strictly required to be in the results.

Booleans, keywords, and prefixes
and do not interact predictably with special keywords (like  or  ) or with namespaces (like  or  ) and probably should not be used in conjunction with either.

Future plans
Of course, the Search Platform team is not very happy with this state of affairs.

In the short term we are creating this document and updating the documentation to reflect the reality of our current system.

Longer term, we plan to implement a new layer in CirrusSearch that will properly construct a Lucene / query that is equivalent to a given classic boolean query, including proper support for parentheses and return the expected results. (It is possible to specify in Lucene that at least one of a set of query terms or clauses is a required to match, which is equivalent to a boolean ; requiring that all of a set of query terms or clauses match is the same as a boolean  .)

Beyond that, we may also make explicit the and  operators, possibly using the unary syntax shown in this document, but also possibly using some other syntax, as yet to be determined.