CQL ExamplesEach of the CQL examples below links to the result of running that example on sample.pgn, a selection of studies from the Heijden 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 examplesThe CQL files in this section illustrate some of the simple, basic things CQL can do.
|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, commentsCQL can search for things other than moves and position, like player, event, site, year. It can also search comments:
|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 PatternsCQL has a number of features for checking patterns in a fixed positions. CQL also has features for naming pieces and sets of squares.
|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 |
|serialpin.cql||serial pin||pinning chains: x1 pins x2 pins x3... , sorted by the length of the chain|
SortingIt 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.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 PatternsCQL can detect various patterns of movements that span many positions using the
linefacility, including the ability to specify sequences of moves using regular expressions. Here are some examples:
|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?
|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 ThemesLinear 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.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 usageFor 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.
|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|