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.
| file | theme | description |
|---|---|---|
| QQqq.cql | QQqq | White has two queens, black has two queens, and there are no other pieces except for kings |
| greekgift.cql | Greek gift | Greek gift sacrifice |
| checkcheckcheckstalemate.cql | +++ stalemate | three checks followed by stalemate |
| smotheredmate.cql | smothered mate | black is in smothered mate |
| smotheredmate2.cql | smothered mate, sorted by year, blockers output to pgn | black is in smothered mate, sorted |
| loneknightmate.cql | lone knight mate | white's only piece, a knight, gives mate |
| 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.
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).
| file | theme | description |
|---|---|---|
| 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 |
| dingstheme.cql | pawn moves to guard a model mate | a pawn moves, which guards a square that is later used in a model mate |
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 theline facility, including the ability to specify sequences of moves
using regular expressions. Here are some examples:
| file | theme | description |
|---|---|---|
| staircase-sort.cql | staircase | queen staircase sorted by length |
| staircase-sort-annotated.cql | staircase | queen staircase sorted by length, with better comments in the PGN file |
| snake.cql | snake | like a diagonal staircase |
| likeinterference.cql | multiple interferences | multiple serial interferences stopping checks |
| 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 |
| rookleapcorners.cql | rook corners | a rook visits the four corners without making any moves in between |
| 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 |
| followpaths-simple.cql | follow paths (simple) | two pieces follow the same path of at least three squares |
| two-piece-cycle.cql | two 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
- rookleapcorners.cql
- snake.cql (compare the old-style version snake-old.cql )
- turton.cql (compare to the old turton-old.cql)
- babson0.cql (one way to do Babson)
- babson3.cql (another way, compare to old-style babson-old.cql)
- rundlaufe.cql
- likeinterference.cql
- followpaths-simple.cql
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.
| file | theme | description |
|---|---|---|
| followpath.cql | following paths | Two pieces each traverse the same set of at least 3 squares in the same order, sorted by length of path |
| 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 |