Help:CirrusSearch/Logical operators

CirrusSearch 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 are no implicit  s—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 Help:CirrusSearch 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.