pieceid

The pieceid filter is a numeric filter that consists of the keyword pieceid followed by one argument, a set filter:
  pieceid set

An example of a pieceid filter with argument Q is the right hand side of the assignment filter below:

  x=pieceid Q

Each piece in a game has a unique numeric value, called its piece id. This value does not change as the piece moves or promotes.

Suppose the set filter following pieceid corresponds (in the current position) to a set of squares set. If the number of elements in set is not equal to 1, then the pieceid filter does not match. Otherwise the set contains a single square s. If the square s is empty, then the pieceid filter does not match.

If the square s contains a piece, then the value of the pieceid filter is the value of the piece id of the piece on s.

Thus, in the example above, if there is exactly one white queen in the current position, then the value of pieceid Q is the piece id of that queen. Otherwise, the pieceid Q filter does not match.

Examples

The pieceid filter is used in underpromotionecho.cql, which finds games in which two positions are the same except that a pawn has promoted to a different piece in one of the positions.

There, the user variable Mismatch is bound to a single square, representing the only square in which the current position and the position named by the variable source differ. But even though the squares are different in the sense of having pieces of different types on them, the pieces on the squares will have the same pieceid if they were the result of promoting the same pawn. So the line

      pieceid Mismatch==source:pieceid Mismatch

checks that the pieceid of the piece on the Mismatch square in the current position is the same as the pieceid of the piece on the Mismatch square in the source.

Thus, in the position in the Didukh study matched by running underpromotionecho.cql against the sample database database, the source variable will be bound to the mainline position after move 9:

Didukh 2006, mainline after white's move 9
(found from CQL file: underpromotionecho.cql)

The current position will be bound to the position in the variation after move 9:

Didukh 2006, variation after white's move 9

The Mismatch variable will be bound to d8, the square on which their contents differ. But the pieceid of the that square in these two position will be the same, since the Q and R are the result of promoting the same pawn.