CQL By Example

See CQL By Example to see many key CQL ideas through several examples.

CQL Examples

CQL ships with many examples of how to search for specific ideas and themes, as well as how to use different CQL features.

Viewing examples as a directory

To view all the examples as one directory, see examples directory.

Introductory 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
greekgift.cqlGreek giftGreek gift sacrifice
checkcheckcheckstalemate.cql+++ stalematethree checks followed by stalemate
smotheredmate.cqlsmothered mateblack is in smothered mate
smotheredmate2.cqlsmothered mate, sorted by year, blockers output to pgnblack is in smothered mate, sorted
loneknightmate.cqllone knight matewhite's only piece, a knight, gives mate
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.

Bohemian mates and stalemates

Note that the examples for computing pure mate, model mate, ideal mate, pure stalemate, model stalemate, and ideal stalemate have been removed. These are now built-in to CQL (see puremate, modelmate, idealmate, purestalemate, modelstalemate, idealstalemate).

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
dingstheme.cqlpawn moves to guard a model matea pawn moves, which guards a square that is later used in a model mate


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-sort.cqlstaircasequeen staircase sorted by length
staircase-sort-annotated.cqlstaircasequeen staircase sorted by length, with better comments in the PGN file
snake.cqlsnakelike a diagonal staircase
likeinterference.cqlmultiple interferencesmultiple serial interferences stopping checks
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
rookleapcorners.cqlrook cornersa rook visits the four corners without making any moves in between
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
followpaths-simple.cqlfollow paths (simple)two pieces follow the same path of at least three squares
two-piece-cycle.cqltwo cycles two pieces traverse the same cycle in consecutive moves

Examples illustrating new features in CQL 6.2

For a basic introduction to and , we suggest the examples staircase-sort.cql and staircase-sort-annotated.cql

For further examples illustrating new features in CQL 6.2, we suggest

It might also be worth checking out a simple Zugzwang theme, zugzwang1.cql for some of the new syntax involving comparing positions for equality.

accessing CQL 6.1 examples

You can compare the CQL 6.2 examples with the CQL 6.1 examples, which are here: old examples directory. Note that sometimes the new examples will have slightly different functionality due to refinements in theme definitions.

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.

followpath.cqlfollowing paths Two pieces each traverse the same set of at least 3 squares in the same order, sorted by length of path
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