{}: the compound filter

A compound filter is a sequence of zero or more constituent filters enclosed in braces.

A compound filter is true in a position if all of its constituent filters are true in the position. For example,

    {check Ra3}

is a compound filter with two constituent filters: check and Ra3. It is true in a position if one side is in check and if a white Rook is on a3 in that position.

short circuit evaluation

Whenever a filter in a compound filter is false in a position, later filters are not evaluated. For example,

has two filters, but the check filter will be evaluated only if the first filter matches the position, i.e., if the King is on h2.

value of a compound filter

The value of a compound filter is the value (if any) of its last filter.


  • if the last filter in the compound filter is a set filter, then the compound filter is also a set filter (if the compound filter does not match, it represents the empty set).
  • if the last filter in the compound filter is a position filter, then the compound filter is a position filter
  • if the last filter in the compound filter is a numeric filter, then the compound filter is a numeric filter
For example,
    . attacked by Q}

is a compound filter whose last filter is

. attacked by Q

Therefore, the compound filter represents the set of squares attacked by the white queen if the position is a check; otherwise it represents the empty set.

use of compound filters

Compound filters are used in several situations:

  1. Compound filters for controlling the order of evaluation
  2.     not Ra3 or Bb5
    is a single not filter with argument Ra3 or Bb5. It is true whenever there is no R on a3 or B on b5. If we want to write
        {not Ra3} or Bb5
    for positions in which either there is no R on a3 or there is a B on b5, then we need to use braces, i.e. the compound filter.

    Braces are often used this way with transforms, since transform filters take a single argument but it is common to want to apply them to multiple arguments.

    When a compound filter contains only a single filter, parenetheses can be used to contain that filter instead of braces. This can make numeric expressions look more natural:

        {2+4} * 3
        (2+4) * 3

  3. Compound filters used for clarity
  4. The second reason, clarity, is also illustrated by this example. Sometimes in CQL long strings of filters are chained together, particularly in long argument lists such as in a next filter. Rather than checking the operator precedence and parsing rules for CQL, it is much better just to enclose things in braces for clarity. There is never any performance penalty for this and it can make code clearer.

  5. Compound filter as logical AND
  6. Sometimes we can use a compound filter just to check that each of several conditions is true. For example, suppose we want to match positions that are either (a) stalemate or (b) a double check black mating position. This can be done via:
            or {mate
    	    A attacks k>1 }
    In this particular example we can just the logical and operator:
    stalemate or mate and A attacks>1
    Sometimes braces are easier to read.

  7. Compound filters used in functions
  8. The body of a function definition is a compound filter.

  9. Implicit compound filter at the top level
  10. The body of a CQL file itself is an implicit compound filter: it matches a position only if all its constituent filters do as well. That is, all the top-level filters of the body of the CQL file are collected and form a single implicit compound filter, exactly as if the body were enclosed in a pair of braces.