Introduction

About CQL

CQL was developed by Gady Costeff and Lewis Stiller around 2003 being described as a tool “designed to allow researchers, authors, and players to search for games, problems, and studies that match specific themes”. CQL 3 was introduced in EG 151 in January 2004 which provided several examples including the following which finds a pair of positions within a game that are identical except that White is missing between 1 and 10 pieces in the later position.

(match
  :pgn heijden.pgn
  :output out.pgn
  :result 1-0  ;return only win studies
  (position
    :markall
    :relation (:missingpiececount A 1 10)
  )
)

CQL 3 provided powerful and innovative search features allowing users to classify endgame studies by theme, extract studies containing specific positional characteristics and inter-positional relationships. The CQL language remained largely unchanged until the release of CQL 5 in 2017 which introduced a more expressive and approachable syntax and increased functionality. Released in 2019, CQL 6 expanded upon this base and CQL 6.1 (the version described in this manual) provides many refinements including support for string and dictionary types, string regular expression matching, generalized tag manipulation, and a dedicated interface for querying the HHdbVI endgame study database.

About CQLi

CQLi is a from-scratch clone of CQL which incorporates many new features and improvements including:

• Imaginary position exploration

CQLi extends the move filter to allow exploration of positions not reached within a recorded game. The new imagine filter allows the board to be temporarily modified in arbitrary ways by placing, removing, or swapping pieces and querying the resulting position. This feature may be used to find unplayed moves that would result in mate, stalemate, or some other condition and is instrumental in using CQLi to solve and generate various types of chess problems.

• Variant support

CQLi fully supports several popular chess variants including Chess960, Crazyhouse, Racing Kings, Atomic, Losing Chess, Suicide, Giveaway, Three-check Chess, King of the Hill, and Horde. The variant of each game is automatically determined from the value of the Variant PGN tag allowing a single PGN file to contain games of different variants. CQLi contains extensions to applicable filters to support these variants and adds new filters to identify variants and their specific win/loss/draw conditions.

• Unicode support

CQLi supports UTF-8 encoded PGN and cql query files. Unicode characters are supported and preserved within PGN strings and comments and within cql queries. String operations are Unicode aware and pattern matching and comparison operations are performed using Unicode aware facilities.

• Powerful Extensibility

The Command Pipe feature allows CQL queries to easily interact with external programs in order to delegate complex operations, such as engine analysis, tablebase lookup, ECO or rating assignments, etc., and utilize the results of those operations within the query.

Other improvements include expressive diagnostics that more precisely identify issues and distinguish errors from warnings, 64-bit numeric types, smarter “smart comments”, greater flexibility over output PGN formatting, transactional evaluation of line filters, unreachable position detection, support for persistent variables in multi-threaded mode, implicit promoted piece tracking, reverse move generation, splitting output across multiple files, cqlbegin and cqlend blocks that are evaluated at the start and end of processing, immediate output using the –nosort option, Polyglot-compatible zobrist key calculation, and scoped variables.

Typographical Conventions

The following typographical conventions are used in this reference manual:

• Italic text is used to introduce new terms, refer to specific chess variants, and as a general emphasis mechanism.

• Bold monospace text is used when referring to CQL filters, options, chess moves, and inline code snippets.

• External links are underlined in red and internal links are underlined in blue, such links can be clicked on to navigate to the link target in most pdf readers.

• CQL code blocks are presented with syntax highlighting in a blue shaded box.

• Chess diagrams use colored circles to draw attention to specific pieces, highlighting to emphasize particular squares, and arrows to represent pertinent moves or rays.

The colors used in this document are intended to be easily distinguishable by readers with various forms of color-blindness. If you are color-blind and have difficulty differentiating the colors used in this document, please let us know.

Notes for CQL6 Users

In most cases CQLi may be used as a drop-in replacement for CQL 6.1 but there are some differences in the feature set and default behaviors that current users of CQL 6.1 should be aware of. The most notable differences are provided below, see here for a more comprehensive accounting of the differences between CQL 6.1 and CQLi.

• CQL 6.1 combines multiple comments at a single position into a single conglomerate comment. By default, CQLi will write multiple comments as separate individual comments, e.g. e4 {A} {B} instead of e4 {A B}. Use the –coalescecomments option to obtain the CQL 6.1 behavior.

• Variables declared in the body of an iteration filter are not visible outside the filter which may result in a syntax error for queries accepted by CQL 6.1. The solution is to move the declaration outside the iteration filter. See Variable Scopes for more information.

• CQLi does not yet support the --gui, --guipgnstdin, or --guipgnstdout options which are planned for a future version of CQLi. The option -o stdout can be used to cause matching games to be printed to stdout.

System Requirements

Acknowledgements

Thanks to Lewis Stiller and Gady Costeff for designing the CQL language and making the CQL program freely available.

Thanks to Lewis Stiller for his consistent and gracious support which was instrumental in understanding many of the more subtle aspects and design choices of CQL and for the feedback and encouragement he provided during the development of CQLi.