Introduction
CQLi is a command-line utility that can search for, modify, and extract chess games from PGN databases using arbitrarily complex criteria. CQLi is a BSD-licensed, from-scratch clone of the Chess Query Language (CQL) that adds many new features including Unicode support, support for popular chess variants, imaginary position exploration, and a powerful extensibility mechanism. The accompanying PDF Reference Manual provides comprehensive documentation for the tool and includes many examples.
Quick Start
A CQL query consists of a series of filters. For each position in each game of the provided PGN file,
the supplied query is evaluated. Matching positions are those for which all of the filters in the query are true.
Games with matching positions are written to the output file. By default, matching positions are commented with
the string "CQL", this may be changed or suppressed using the --matchstring option.
The following CQL query will find KNBvK endgames that ended in mate (i.e. checkmates with knight and bishop).
terminal // Only consider final positions
mate // Positions that are checkmate
flipcolor {
A == K // White only has a king
a == 3 // Black has exactly three men
b == 1 // including one bishop
n == 1 // and one knight
}
Non-terminal positions will never make it to the second filter (mate).
Games that end in mate will make it to the final filter which compares the set of
pieces on the board using piece designators. The piece designators A
and a correspond to the set of all pieces for White and Black, respectively.
The filter A == K is true only when White has just a king. The filter
a == 3 is true when Black has exactly 3 men, b == 1 is true when
there is exactly one black bishop on the board and n == 1 is true when there
is exactly one black knight. The flipcolor filter transforms this last
part of the query such that it is also true when the colors are reversed, i.e. Black has
just the king and White has the pieces.
To use CQLi to run the query, copy the query text above into a text file, traditionally with
the .cql extension, e.g. test.cql. Then use the following command
to invoke CQLi:
cqli -i input.pgn -o output.pgn test.cql
where input.pgn is the input file to process and output.pgn
is the file to write the matching results to. For example, when run on the set of standard rated
games played on lichess.org in January 2015,
the query finds 46 games, including this bullet game.
Filters are self-terminating and spacing is not significant, the above query could have been
specified on a single line. Queries may also be provided on the command-line using the
--cql option, for example:
cqli -i input.pgn -o output.pgn --cql 'terminal mate flipcolor { A == K a == 3 b == 1 n == 1 }'
See the included Reference Manual for complete details and examples of significantly more complex queries.
Download CQLi
64-bit builds are provided for Linux, macOS, and Windows.
CQLi 1.0.4 for Linux
CQLi 1.0.4 for macOS
CQLi 1.0.4 for Windows
CQLi Copyright (c) 2021-2024 Robert Gamble.
