CQL: The Chess Query Language (version 6.2 beta)
Note: This is a prototype. It is not fully documented and has bugs. See New CQL 6.2 features for more detailed information and links about this release.
See CQL 6.1 documentation for CQL 6.1 documentation
What is CQL?Chess Query Language (CQL) searches for user-defined patterns in chess games and studies.
To use CQL
- first, define the pattern you are looking for in the CQL language;
- second, run
cqlspecifying that pattern.
Quick intro: Greek gift sacrificeSuppose you are looking for Greek gift sacrifices, where White sacrifices a bishop for a pawn on
h7and follows up with
♘g5+, as in
(found from CQL file: greekgift.cql)
You can find these in your database by running
cql -i sample.pgn examples/greekgift.cql
⊢ ♗×♟h7 check ♚×h7 ♘――g5 check
The meaning of the terms in the pattern specified in greekgift.cql are:
⊢introduces a sequence of moves
♗×♟h7means that a white bishop captures on a black pawn on
checkmeans that one side is in check.
♚×h7means that the black king captures on
♘――g5 checkmeans that the white knight moves to
g5, giving check.
If you wanted to search for black Greek gifts too, just insert the glyph
⬓ before the
flipcolor means to allow the colors to be reversed. (You can always find the ASCII equivalent for a symbol by hovering over it in this documentation).
If you wanted to include queenside Greek gifts, insert the
✵⬓ ⊢ ♗×♟h7...
If you wanted to allow any number of moves by non-
♚ pieces after the king recaptures and before the knight giving check, you can use regular expressions:
✵⬓ ⊢ ♗×♟h7 check ♚×h7 ~♚――* ♘――g5 check
~♚ denotes the squares other than the black king's, so
~♚―― denotes a move by any piece other than the black king. The
* at the end means to repeat 0 or more times, as in string regular expressions.
In general, move sequences in CQL can be augmented with board rotations, reflections, and shifts. Regular expressions can be applied directly to move sequences to allow for more complex patterns.
Click on the examples tab in the sidebar for more examples.
CQL 6.1 compatibilityCQL 6.2 is generally back-compatible with CQL 6.1. Users of CQL 6.1 who do not want to use new CQL 6.2 features can continue to rely on CQL 6.1 language documentation while using the CQL 6.2 executable.
The one extremely rare instance where users might see theoretical incompatibility
is that, if
y are position variables, then
z=x<ywill set the variable
zto the position
xwhen the filter is true, rather than to the position id of
x. Similar considerations apply for the value of relational expressions with position operands.
Additional documentationDocumentation for CQLi also includes new documentation of CQL itself.
The EG discusses CQL in a number of columns, particularly by Emil Vlasàk.
DownloadsCQL may be downloaded here. Questions or comments about CQL should be directed to
costeffat the domain
CQLiCQLi, written by Robert Gamble, is a high-quality, efficient and robust implementation of the CQL 6.1 language. CQLi also has a number of new features that CQL 6 does not support, including support for "imaginary" positions that do not occur in the game tree; Unicode; and communication with external programs. CQLi is extremely well-architected and accurate, and typically runs much faster than CQL. (Much of CQL 6 was tested and debugged by testing it against earlier versions of CQLi).
VersionThe current version of CQL is CQL 6.2 beta