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.

file	theme	description
QQqq.cql	QQqq	White has two queens, black has two queens, and there are no other pieces except for kings
mirrormate.cql	Mirror mate	mated king is surrounded by empty squares
mirrorstalemate.cql	Mirror stalemate	stalemated king is surrounded by empty squares
puremate-simple.cql	pure mate (simplified)	each square in the King's field is attacked only once.
pins.cql	pins	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.cql	Excelsior(simple version)	White pawn starts on the second rank and promotes
zugzwang1.cql	Zugzwang	simple 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:

file	theme	description
gameinfo.cql	metadata (simple)	This simple file illustrates using CQL to search for certain game-level information.
gameinfo2.cql	metadata	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.

file	theme	description
puremate.cql	pure mate	each square in the King's field is guarded only once
modelmate.cql	model mate	pure mate in which each non-King non-pawn white piece participates in the mate
idealmate.cql	ideal mate	model mate in which each piece participates
purestalemate.cql	pure stalemate	stalemate in which each square in the king's field is guarded once only
modelstalemate.cql	model stalemate	Model stalemate, but checks that each White non-King non-pawn piece participates in the stalemate
idealstalemate.cql	ideal stalemate	model stalemate in which each piece participates
massivestalemate.cql	massive stalemate	stalemates where the stalemated side has total material value (power) of at least 15, sorted by the power
immured.cql	immured	at 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.cql	90° rotation	a particular configuration (two queens on a vertical or horizontal line separated by a square) recurs in all 4 versions rotated by 90°
Qq-rotations.cql	45° rotations	a 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.cql	horizontal symmetry	positions that are identical when they are flipped about the horizontal bisector and colors interchanged (e.g., the position after 1.e4 e5)
serialpin.cql	serial pin	pinning chains: x1 pins x2 pins x3... , sorted by the length of the chain

Sorting

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.

file	theme	description
most-visited-square.cql	most visited square	the same square was visited at least 15 times, sorted by the number of times the square was visited
most-visited-square-2.cql	most visited square	the 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.cql	consecutive checks	at least two consecutive checks, sorted by the number of consecutive checks
passers.cql	passed pawns	passed pawns, sorted by number of such pawns.
excelsior-multiple.cql	multiple Excelsior	multiple excelsiors in a game, sorted by the number of excelsiors
multiple-discovered-checks.cql	multiple discovered checkes	at least 5 discovered checks, sorted by the number of discovered checks
powerdifference-stalemate.cql	power difference stalemate	stalemated side has much more material than the stalemating side, sorted by the difference in material
most-king-moves.cql	king moves	at least 20 moves by the black King, sorted by the number of such moves
averagedistance.cql	average move distance	games 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:

file	theme	description
staircase.cql	staircase	queen staircase
staircase-sort.cql	staircase	queen staircase sorted by length
rook-corners-1.cql	rook corners	The same rook visits all four corners of the board
rook-corners-2.cql	rook corners	same as rook-corners-1.cql, but uses rotate90 to illustrate a more compact way to express the theme
rook-corners-rotate-with-range.cql	rook corners	same as rook-corners-1.cql, but uses rotate90 with a range for yet another way to express the theme
platzwechseln1.cql	Platzwechsel	Two white knights exchange places
platzwechseln2.cql	Platzwechsel, separated	white and a black knight switch places, separated by at least 3 squares
platzwechselecho.cql	Plazwechsel	platzwechseln2.cql using echo
excelsior-return.cql	Excelsior and return	pawn starts on its square in the starting position, promotes, then returns to its original square.
forced-moves-both-sides.cql	forced moves, both sides	longest sequence of consecutive forced moves.
forced-moves-either-side.cql	forced moves, one color	longest sequence of consecutive forced moves by one color
forced-moves-white.cql	forced move by white	white 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?

file	theme	description
enpassantecho.cql	en passant echo	two positions are the same except that en passant is legal in one but not the other
castleecho.cql	castle echo	two positions are the same except for castling rights
underpromotionecho.cql	underpromotion echo	two positions are the same except that piece was promoted to a different piece
queenpawnpinecho.cql	queen pins pawn echo	in the variations, Black can pin a pawn by a queen, but in the mainline Black cannot because the White king moved
wcct7.cql	missing white piece	same position recurs with a missing white piece (theme of the 7th World Chess Composition Tournament)
movedblackpieceecho.cql	moved black piece echo	two positions differ only in that a Black piece has changed its location
knightpawnforkecho.cql	knight pawn fork echo	in 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.cql	zugzwang	a 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.cql	Fata Morgana	White spends a long time trying to lose a move.
flipverticalecho.cql	vertical symmetry echo	the same position occurs reflected about the vertical axis
chameleon.cql	chameleon	the same position recurs shifted in such a way that all its pieces are on different colored squares from their original squares
queentriangulation.cql	queen triangulation	one side makes a series of queen moves which repeat the position with the side to move changed
missingwhitepiece.cql	missing white piece	the 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.

file	theme	description
bristol-universal.cql	Bristol	the Bristol theme, both diagonally and orthogonally, and sorted by the length of the thematic move
turton.cql	Turton theme	two line pieces interchange in order to support motion of one of them
wurzburg-plachutta.cql	Wurzburg-Plachutta	two black line pieces interfere in like motion on a critical square
clearance-delayed.cql	delayed clearance	white 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.

file	theme	description
two-piece-cycle.cql	two cycles	two pieces traverse the same cycle in consecutive moves
parallelpaths.cql	parallel paths	Two pieces each traverse the same set of at least 3 squares in the same order
lacny.cql	Lacny	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.cql	systematic maneuver	A set of at least 4 pieces is rigidly shifted in the same way around the board