CQL Examples

Each of the CQL examples below links to the result of running that example on sample.pgn, a selection of studies from the HHdbVI endgame study database.

For example, the file puremate-simple.cql is a simple implementation of a pure mate. If one were to run CQL by:

      cql -i sample.pgn puremate-simple.cql

then cql would create an output file called puremate-simple-out.pgn. This output file is linked to from the HTML version of puremate-simple.cql so that you can see what CQL output looks like without installing and running CQL.

Introductory CQL examples

The CQL files in this section illustrate some of the simple, basic things CQL can do.

QQqq.cqlQQqqWhite has two queens, black has two queens, and there are no other pieces except for kings
mirrormate.cqlMirror matemated king is surrounded by empty squares
mirrorstalemate.cqlMirror stalematestalemated king is surrounded by empty squares
puremate-simple.cqlpure mate (simplified) each square in the King's field is attacked only once.
pins.cqlpins At least 3 pieces are pinned against their own King in a position. The output is sorted by the maximum number of pins in each game.
excelsior-simple.cqlExcelsior(simple version) White pawn starts on the second rank and promotes
zugzwang1.cqlZugzwangsimple zugzwang script

Metadata: player, event, year, comments

CQL can search for things other than moves and position, like player, event, site, year. It can also search comments:

gameinfo.cqlmetadata (simple) This simple file illustrates using CQL to search for certain game-level information.
gameinfo2.cqlmetadata Use movenumber to sort by the length of the game, with games that have "1.p" in their event field, indicating 1st prize in the Heijden database
persistent.cql Summary statistics print the total number of wins, draws, mates, stalemates, underpromotions in the database, using persistent variables

Position Patterns

CQL has a number of features for checking patterns in a fixed positions. CQL also has features for naming pieces and sets of squares.

puremate.cqlpure mate each square in the King's field is guarded only once
modelmate.cqlmodel mate pure mate in which each non-King non-pawn white piece participates in the mate
idealmate.cqlideal matemodel mate in which each piece participates
purestalemate.cqlpure stalematestalemate in which each square in the king's field is guarded once only
modelstalemate.cqlmodel stalemate Model stalemate, but checks that each White non-King non-pawn piece participates in the stalemate
idealstalemate.cqlideal stalematemodel stalemate in which each piece participates
massivestalemate.cqlmassive stalematestalemates where the stalemated side has total material value (power) of at least 15, sorted by the power
immured.cqlimmuredat least 3 non-pinned non-pawn pieces by one side that have no legal moves in a position. Sort by the maximum number of such pieces in any position
Qq-rotations-90-degree.cql90° rotationa particular configuration (two queens on a vertical or horizontal line separated by a square) recurs in all 4 versions rotated by 90°
Qq-rotations.cql45° rotationsa particular configuration (two queens on a line separated by a square) recurs in at least 5 of the 8 rotated versions, where rotation is a multiple of 45°
horizontallysymmetric.cqlhorizontal symmetrypositions that are identical when they are flipped about the horizontal bisector and colors interchanged (e.g., the position after 1.e4 e5)
serialpin.cqlserial pinpinning chains: x1 pins x2 pins x3... , sorted by the length of the chain


It turns out to be extremely useful to sort games by a particular feature you are interested in. CQL can sort games in many different ways, by putting the keyword sort in front of a feature you're interested in. CQL can sort by the length of a game; by the length of a move; by the number of moves in a pattern; by the number of squares in a set; the number of times a square is visited; and so on.

Here are some more examples of sorting. Sorting is also used in many additional examples listed in other sections.

most-visited-square.cqlmost visited squarethe same square was visited at least 15 times, sorted by the number of times the square was visited
most-visited-square-2.cqlmost visited squarethe same square was visited at least 15 times, sorted by the number of times the square was visited, and outputs the actual square visited
consecutive-checks.cqlconsecutive checksat least two consecutive checks, sorted by the number of consecutive checks
passers.cqlpassed pawnspassed pawns, sorted by number of such pawns.
excelsior-multiple.cqlmultiple Excelsiormultiple excelsiors in a game, sorted by the number of excelsiors
multiple-discovered-checks.cqlmultiple discovered checkesat least 5 discovered checks, sorted by the number of discovered checks
powerdifference-stalemate.cqlpower difference stalematestalemated side has much more material than the stalemating side, sorted by the difference in material
most-king-moves.cqlking movesat least 20 moves by the black King, sorted by the number of such moves
averagedistance.cqlaverage move distancegames sorted by the average length of their moves

Movement Patterns

CQL can detect various patterns of movements that span many positions using the line facility, including the ability to specify sequences of moves using regular expressions. Here are some examples:

staircase.cqlstaircasequeen staircase
staircase-sort.cqlstaircasequeen staircase sorted by length
rook-corners-1.cqlrook corners The same rook visits all four corners of the board
rook-corners-2.cqlrook cornerssame as rook-corners-1.cql, but uses rotate90 to illustrate a more compact way to express the theme
rook-corners-rotate-with-range.cqlrook cornerssame as rook-corners-1.cql, but uses rotate90 with a range for yet another way to express the theme
platzwechseln1.cqlPlatzwechselTwo white knights exchange places
platzwechseln2.cqlPlatzwechsel, separatedwhite and a black knight switch places, separated by at least 3 squares
platzwechselecho.cqlPlazwechselplatzwechseln2.cql using echo
excelsior-return.cqlExcelsior and returnpawn starts on its square in the starting position, promotes, then returns to its original square.
forced-moves-both-sides.cqlforced moves, both sideslongest sequence of consecutive forced moves.
forced-moves-either-side.cqlforced moves, one colorlongest sequence of consecutive forced moves by one color
forced-moves-white.cqlforced move by whitewhite forced moves sorted by length of sequence

Logical studies (thematic try and solution)

In a typical logical study there is some relationship between two different positions in the study. Typically these positions are almost the same - but they are different in one crucial, subtle aspect. It is this difference that is interesting and that drives the study.

Maybe the two positions are the same except that the side to move is different in the two positions. Maybe en passant or castling is allowed in one position but not the other position. Maybe one can be reached by shifting the other position.

When we search for logical studies like this, we are not limited to specifying the difference between the positions themselves: we can also specify relationships between the paths to each. Are the positions nearby in the game, do many moves separate them? Are the two positions reached by paths that share many of the same moves?

enpassantecho.cqlen passant echotwo positions are the same except that en passant is legal in one but not the other
castleecho.cqlcastle echotwo positions are the same except for castling rights
underpromotionecho.cqlunderpromotion echotwo positions are the same except that piece was promoted to a different piece
queenpawnpinecho.cqlqueen pins pawn echoin the variations, Black can pin a pawn by a queen, but in the mainline Black cannot because the White king moved
wcct7.cqlmissing white piecesame position recurs with a missing white piece (theme of the 7th World Chess Composition Tournament)
movedblackpieceecho.cqlmoved black piece echotwo positions differ only in that a Black piece has changed its location
knightpawnforkecho.cqlknight pawn fork echoin the main line, a knight forks a king and a pawn on the seventh; in the variation, the fork is prevented by a piece on the forking square
zugzwang2.cqlzugzwanga position in a variation of a win study is the same as a mainline position except that the mainline position is black to move
fatamorgana.cqlFata MorganaWhite spends a long time trying to lose a move.
flipverticalecho.cqlvertical symmetry echothe same position occurs reflected about the vertical axis
chameleon.cqlchameleonthe same position recurs shifted in such a way that all its pieces are on different colored squares from their original squares
queentriangulation.cqlqueen triangulation one side makes a series of queen moves which repeat the position with the side to move changed
missingwhitepiece.cqlmissing white piecethe mainline and variation positions differ in that the variation has a missing white piece, in a win study

Linear Themes

Linear themes lie at the intersection of chess and geometry. In a linear theme, the pieces themselves trace specific geometric patterns while they aim for mate.

Although the terminology of linear themes can seem unfamiliar and forbidding at first, the underlying ideas are usually simple and powerful. In the Bristol theme a line piece makes a long move purely to make space for another piece, which follows it, piston-like. In the Turton theme, a pair of line pieces swap places for the sake of forming kind of battering ram that later fires on its target.

bristol-universal.cqlBristolthe Bristol theme, both diagonally and orthogonally, and sorted by the length of the thematic move
turton.cqlTurton themetwo line pieces interchange in order to support motion of one of them
wurzburg-plachutta.cqlWurzburg-Plachuttatwo black line pieces interfere in like motion on a critical square
clearance-delayed.cqldelayed clearancewhite delays several moves before exploiting a clearance, sorted by the length of the delay

Advanced CQL usage

For the previous themes, the relationship between the the CQL code and the underlying chess idea has been fairly straightforward. At least, that's the goal. Sometimes though the user has to resort to CQL techniques that look more like programming than chess. These examples illustrate techniques (or hacks) that might be helpful to advanced users.

two-piece-cycle.cqltwo cycles two pieces traverse the same cycle in consecutive moves
parallelpaths.cqlparallel paths Two pieces each traverse the same set of at least 3 squares in the same order
lacny.cqlLacny Three-fold Lacny, a cyclic problem theme (CQL is not designed for problems, but can be used sometimes).
indian.cql Indian White moves a line piece over a critical square. Then white moves another piece to the critical square, preventing a stalemate.
systematicmaneuver.cqlsystematic maneuverA set of at least 4 pieces is rigidly shifted in the same way around the board