in

The in filter is a binary infix filter that takes two set filters as arguments: one set filter left on the left of the keyword in and one set filter right on the right. The in filter matches the position if the set of squares represented by its left argument is a subset of the set of squares represented by its right argument. For example, the following code:

  A in {. attacked by a}

will match a position in which every white piece is attacked by a black piece. It is equivalent to:

  square all z in A
   z attacked by a

Note: the in filter is rarely used and never needed in CQL. Its functionality can easily be replicated using more fundamental CQL filters, like square all , set equality (set equality) and &.

Note: "in" as a filter distinguished from "in" as a parameter

The in filter has nothing to do with the in parameters that are used with the filters piece, square and echo.

Thus, the in before the A in the examples is not related to the in filter. That usage of in before the A is instead a parameter to the square filter. It is not its own filter.

Use of the in filter with a piece variable

Use care when using the in filter with a left argument that is a piece variable. The value of the piece variable can be empty in the current position (if it was captured), which makes the in filter match the current position. To check if a piece variable represents a piece on a set of squares, use &:

  piece x in Pa-h2 //find pawns that eventually promote
   {find x in a-h8 //wrong! x might be empty (captured)
    find x&a-h8 // correct
  }

Examples

The in filter is used in modelmate.cql, where the line

  [RNBQ] in WhiteParticipants

checks that each white non-pawn non-King piece is a member of the set represented by the user variable named WhiteParticipants, as in the following position: Korolkov 1937, after 8. c8N model mate
(found from CQL file: modelmate.cql)

Here, [RNBQ] is the same N, which also represents the white pieces participating in the mate.