CQL Examples

CQL can search for many different kinds of things, and there are a lot of different commands in it. There are a It is helpful to look at as many examples as possible to get an idea of options for how to do things.

Introductory CQL examples

The CQL files in this section illustrate some of the simple, basic things CQL can do.
  • pure mate 1 A simple implementation of pure mate: each square in the King's field is attacked only once.
  • 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 a position in that game.
  • consecutive checks Games with at least two consecutive checks, sorted by the number of consecutive checks
  • excelsior White pawn starts on the second rank and promotes
  • zugzwang A simple zugzwang script
The following sections expand on some of these ideas and features

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:
  • Game level information This simple file illustrates using CQL to search for certain game-level information. Here, games where Ivanchuk wins, at a particular site and event, sorted by year in descending order.
  • Sorting by the game length Using 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
  • Match every game This file matches ouputs every game in the input. It can be useful to quickly find all games by a player from the command line. E.g., 
    cql --player Kasparyan --year 2000 2005 any
    outputs Kasparyan games from 2000 to 2005

Position Patterns

CQL has a number of features for checking patterns in a fixed positions. The most important of these are ray which lets you look at lines on the board and pieces on them; and attack which lets you look at which pieces attack which squares (and how often). CQL also has features for naming pieces and squares.
  • Pure mate 1 A simple implementation of pure mate: each square in the King's field is attacked only once
  • Pure mate 2 Same as pure mate 1 but checks that each black piece in the King's field is either pinned or not attacked
  • Model mate Same as pure mate 2 but checks that each White non-King non-pawn piece participates in the mate
  • Ideal mate Same as modelmate but checks that each black piece participates in the mate
  • pure stalemate 1 Stalemate where each empty square in the King's field is attacked only once
  • pure stalemate 2 Same pure stalemate 1, but also checks that each black piece in the King's field is either pinned or is not attacked
  • model stalemate 1 Same as pure stalemate 2, but checks that each White non-King non-pawn piece participates in the stalemate
  • model stalemate 2 Same as model stalemate 1, but sorts the output by the number of black pieces
  • Massive stalemate Stalemates where the stalemated side has total material value (power) at least 15, sorted by the power
  • Immured pieces A position with at least 3 non-pinned non-pawn pieces by one side that have no legal moves. Sort by the maximum number of such pieces in any position
  • 90 degree rotated configuration A particular configuration (two queens on a vertical or horizontal line separated by a square) recurs in all 4 rotated versions. Rotation is a multiple for 90 degrees.
  • 45 degree rotated configuration A particular configuration (two queens on a line separated by a square) recurs in at least 5 of the 8 rotated versions. Rotation is a multiple of 45 degrees.

Sorting

It turns out to be surprisingly useful to be able 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; by the number of things that happen on a square; 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 Games in which the same square was visited at least 15 times, sorted by the number of times the square was visited
  • consecutive checks Games with at least two consecutive checks, sorted by the number of consecutive checks
  • Multiple white passed pawns At least 5 White passed pawns
  • Multiple white passed pawns version 2 Another way to find passed pawns, and sort the output by the number of the white passed pawns.
  • quadrupled pawns games with quadrupled pawns. Converted from CQL version 3 to illustrate using flip and shift operators
  • Multiple excelsiors Multiple excelsiors in a game, sorted by the number of excelsiors
  • Multiple discovered checks At least 5 discovered checks, sorted by the number of discovered checks
  • Stalemates Find stalemates where the stalemated side has much more material than the stalemating side, sorted by the difference in material.
  • most king moves Games with at least 20 moves by the black King, sorted by the number of such moves

Movement Patterns

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

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, but not the other. Maybe one can be reached by shifting the other.

When we search for logical studies like this, we don't only specify the difference between the positions, but we can also specify the relationships between the paths to the positions themselves. Are the positions nearby in the game, or do many moves separate them? Are the two positions reached by paths that share many of the same moves?

  • en passant relation using transforms Two positions are the same except that en passant is legal in one, and not legal in the other. This version uses shifthorizontal rather than square and direction operators. It is slower, but maybe easier to understand.
  • en passant relation Two positions are the same except that en passant is legal in one, and not legal in the other
  • castle relation Two positions are the same except for castling rights.
  • logical underpromotion studies Position recurs except that a white piece is changed to another white piece. The two positions are separated by at least 20 ply
  • A pin of a pawn by a queen fails in the variation In the variations, Black can pin a pawn by a queen. In the mainline he cannot because the White King and nothing else has moved
  • Missing white piece Same position recurs with a missing white piece (this was the study theme of the 7th World Chess Composition Tournament)
  • pawn interposes to stop a check In the mainline, a Black bishop attacks the White King, but White interposes a pawn. In the variation the pawn cannot interpose because it is moved or missing. All other pieces remain the same.
  • black piece moves Two positions differ only in that a Black piece has changed its location. The two positions are reached by a path from their latest common ancestor that has at least 25 consecutive identical moves.
  • Knight fork of King and Pawn prevented In the main line, a knight forks a King a pawn on the seventh. In the variation, the fork is prevented by a piece on the forking square
  • White try Illustrates how to use past to find White tries: variations that were originally created by a White move from the mainline
  • Simple zugzwangs A basic zugzwang script
  • Zugzwangs with common substrings Zugzwangs, but where the mainline and the try have at least 15 contiguous common moves from their latest common ancestor
  • Fata Morgana theme The Fata Morgana theme, in which White spends a long time trying to lose a move. The distance between the original position, with White to move, and the position White is trying to reach, with black to move, must be at least 40 ply
  • vertically reflected echo The same position occurs reflected about the vertical axis. Output is sorted by number of pieces, the number of white pieces and the number of black pieces
  • Chameleon echo The same position occurs in the target and the source but is shifted in the target. It is shifted in such a way that the color of the square each piece is on is different in the source and the target

Line Themes

Line themes lie at the intersection of chess and geometry. In a line theme, the pieces themselves trace specific geometric patterns while they aim for mate. Although the terminology of the line 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 a battery, a battery that later fires on its target.
  • Bristol 1 Converted from CQL version 3, illustrates searching for certain simple Bristols
  • Bristol 2 Another version of Bristol 1, that uses piece variables instead of transforms
  • Bristol theme Bristol theme, both diagonally and orthogonally, and sorted by the length of the thematic move
  • Turton the Turton theme, involving the interchange of two line pieces in order to support motion of the front piece.
  • Wurzburg-Plachutta Wurzburg-Plachutta by White: two black line pieces interfere in like motion on a critical square.
  • Clearance, delayed Same as immediate clearance but delayed: White delays several moves before exploiting the clearance. The results are sorted by the length of the delay.