What is Chess Query Language (CQL)?
Chess Query Language (CQL) is a formal query language for searching chess game databases. A CQL query consists of one or more filters that are evaluated against every position in every game of a PGN database. Games containing at least one position that satisfies all filters are returned as results.
CQLi is a modern implementation of CQL. It extends the original CQL tool by adding chess variant support, imaginary position exploration, retrograde analysis capabilities, communication with external programs, explicit support for the HHdbVII endgame database, and the ability to split output across multiple files. CQLi typically runs much faster than CQL. CQLi is free and runs natively on Windows, macOS, and Linux.
Core CQL Concepts
Filters
A CQL query is a collection of filters. Each filter tests something about the current position — the presence of a piece on a square, whether the position is a checkmate, the value of a PGN tag, or a more complex relationship. A position matches a query when all filters in the query are satisfied simultaneously.
Piece designators
Pieces are referred to using single-letter codes: uppercase for White (K, Q, R, B, N, P) and lowercase for Black (k, q, r, b, n, p). The special designator A means any White piece and a means any Black piece. Square ranges and compound designators like [QB] (Queen or Bishop) allow flexible pattern matching.
Transform filters
Transform filters like flipcolor, rotate90, and flip automatically apply a spatial or color transformation to the entire query. For example, adding flipcolor to a checkmate query will also match the mirror case where the colors are reversed, without writing a separate query.
Persistent variables and scripting
CQL supports variables ($name), conditionals, loops, and dictionaries. This allows aggregation queries — for example, counting the number of captures by each piece across a database, or finding the game with the most available moves at any position.
What can you do with CQL?
- Find all games ending with a specific checkmate pattern (e.g., Arabian mate, back-rank mate, smothered mate)
- Find games where a pawn promotes, or where both sides promote in the same game
- Filter games by ECO code, Elo rating, time control, or any PGN tag value
- Find games where a specific tactical motif occurs (pin, fork, skewer, discovered check)
- Detect chess compositions with unreachable or illegal starting positions
- Populate ECO and Opening tags in bulk across a database
- Split a large database into multiple output files organized by opening or result
- Strip clock annotations or engine evaluations from PGN comments
- Search variant databases (Chess960, Crazyhouse, Atomic, and more)
- Communicate with external programs (e.g., Stockfish) to evaluate positions during a query
CQL implementations
Chess Query Language was originally designed and implemented by Gady Costeff and Lewis Stiller. CQL 6.1, available at gadycosteff.com/cql-6-1, established the core language: piece designators, position filters, transform filters, and a move-sequence NFA.
CQLi is an independent modern implementation of CQL developed by Robert Gamble. It is backward compatible with the vast majority of CQL 6.1 queries while adding substantial new capabilities including chess variant support, retrograde analysis, external program communication, improved Unicode support, and output file splitting.