Frequently Asked Questions
For a step-by-step tutorial, see the Quick Start guide.
What is CQLi?
CQLi is a free, BSD-licensed command-line chess database search tool that implements the Chess Query Language (CQL). It lets you search millions of chess games stored in PGN files by positional patterns, move sequences, piece configurations, tactics, and game metadata. CQLi runs natively on Windows, macOS, and Linux with no external dependencies.
How is CQLi different from CQL 6.1?
CQLi extends the original CQL 6.1 language with:
- Retrograde analysis — reverse move generation and the
reachablepositionfilter support retrograde analysis tasks - Chess variant support — Chess960, Crazyhouse, Atomic, Horde, and other variants
- Imaginary position exploration — the
imaginefilter and the speculativemovefilter allow queries to explore positions beyond the moves actually played - Unicode support — Unicode-aware PGN processing and string operations
- Command Pipe — integration with external programs written in any language
- Dynamic output file splitting — route matching games to different output files based on tag contents or query results
- Processing speed — generally much faster processing than CQL 6.1
See the "Differences Between CQL 6.1" section in the Reference Manual for a comprehensive list.
Is CQLi compatible with CQL 6.1 queries?
Yes. CQLi is substantially compatible with CQL 6.1 queries. Most CQL 6.1 queries will run under CQLi with no changes. CQLi extends the language significantly, but the core filter names and syntax are consistent with the original CQL specification.
What is a PGN file and how does CQLi use it?
PGN (Portable Game Notation) is the standard file format for storing chess games. CQLi reads PGN files as input, evaluates your CQL query against every position in every game, and writes matching games to an output PGN file. Free PGN databases are available from Lichess, The Week in Chess, and other sources listed on the Resources page.
Does CQLi work with Lichess databases?
Yes. CQLi fully supports the PGN format used by Lichess database exports at database.lichess.org. Lichess exports include over 7 billion rated games split by month and chess variant. CQLi also supports all chess variants available on Lichess.
How do I find all games with a specific checkmate pattern?
Use position filters combined with the mate filter. For example, to find all Arabian mates:
mate flipcolor flip { kh8 Nf6 Rh7 }
The flipcolor transform automatically handles both White and Black being checkmated,
and flip handles all board reflections. The "Mating Patterns" section of the Reference Manual
provides ready-to-use queries and discussion for over two dozen checkmate patterns.
Can CQLi detect illegal or unreachable chess positions?
Yes. CQLi implements retrograde analysis through the reachableposition filter,
which determines whether a position can legally arise from the standard starting position. The query:
not reachablepositionfinds compositions whose starting position is provably unreachable. CQLi used this capability to identify dozens of flawed studies in the HHdbVII endgame database.
How do I know what version of CQLi I have?
The-version command line option can be used to find the version number, i.e.:
cqli -versionwill yield something that looks like:
CQLi version 1.0.6 (c) Robert Gamble Built on Feb 10 2026 with ICU4C version 78.1
How fast is CQLi?
The speed of CQLi largely depends on the complexity of the query and the hardware on which it is run.
For relatively simple queries (like those found on the Quick-Start page), CQLi processes over 80,000 games per second / 5,000,000 positions per second with 4 threads on a 2020 MacBook Air.
How can I make CQLi run faster?
There are several ways the performance of CQLi might be improved.Process files locally
If the PGN database being processed resides on a network drive or resource, copy the file to a local hard drive before attempting to process it. Attempting to process a remote database can introduce substantial latency, significantly affecting performance.Tweak the number of processing threads
By default, CQLi will use a number of processing threads that is one less than the number of concurrent threads supported by the host system. On many systems, this is not the optimal value and the better performance can be realized by specifying a larger or smaller value using the-threads option. The optimal value
is typically the number of physical cores present on the machine. Since many machines report twice this amount for
hyperthreaded cores, specifying a smaller value may improve performance.
Query optimization
The performance of expensive queries may be optimized by placing complex or resource-intensive checks after simpler checks so that the more expensive checks are only performed on positions that have already matched previous filters. In most cases it makes sense to place the checks that will weed out the largest number of positions first. Some queries only need to execute once per game, such as those that just examine tag data or characteristics of the final position. In those cases it is more efficient to place theinitial or
terminal filter at the beginning of the query so that the rest of the query only gets
executed at the starting or ending position for each game.
How can I reduce the memory used by CQLi
By default, CQLi stores in memory each game that matches the provided query until the end of processing so that it can write games out in either the order they appeared in the source file or as specified with asort filter. Stored games typically
occupy 1-2 kB of memory which can be problematic when running queries that match a huge
number of games or when the host system has limited available memory. In such cases the
--nosort option may be used to cause CQLi to write matches out immediately
instead of storing them in memory.
What variants does CQLi support?
CQLi supports the chess variants listed in the table below. See the "Chess Variants" chapter of the CQLi Reference Manual for more information about how CQLi supports variants.
| Variant Name | Brief Description | Recognized Aliases |
|---|---|---|
| Atomic | Captures cause explosions that destroy surrounding pieces. | Atom, Atomic, Atomic Chess |
| Chess960 | Random setup of backrank pieces. | Chess960, Fischerandom |
| Crazyhouse | Captured pieces change color and may be dropped on later moves. | Crazyhouse, Crazy House, House, ZH |
| Giveaway | Lose all pieces or get stalemated to win. Captures are compulsory. | Antichess, Giveaway, Give away, Giveaway Chess, Give away chess |
| Horde | White has 36 pawns and and wins by checkmating Black before all white pawns are captured. | Horde, Horde Chess |
| King of the Hill | Like standard chess but a king that makes it to a center square immediately wins the game. | King of the Hill, kingOfTheHill, KOTH |
| Losers | Lose all pieces except the king, get checkmated, or get stalemated to win. Captures are compulsory. | Losers |
| Racing Kings | There are no pawns. White and black pieces start on the first two ranks. Win by getting your king to the last rank first. Moves that would result in check are forbidden. | Race, Racing, RacingKings, Racing Kings |
| Standard | Standard chess. | Chess, Classical, Normal, Standard |
| Suicide | Lose all pieces to win. Captures are compulsory. | Suicide, Suicide Chess |
| Three-Check | Like standard chess but giving three checks to the opponent also wins the game. | Three-Check, Three Check, ThreeCheck, Three Check Chess, 3-Check, 3 Check |
How can I evaluate arbitrary chess positions?
Arbitrary positions can be presented to CQLi by creating a game in a PGN file having aFEN tag set to the FEN string of the desired
position and a SetUp tag with a value of "1". For example:
[FEN "7k/7p/p1Pb1np1/8/4P3/3B4/PPP2P2/R3K3 w - - 0 1"]
[SetUp "1"]
{Rook Maze in 17} *
How can I get CQLi to process variation lines in my database?
By default, CQLi does not process variation lines. The-variations
option can be used to cause variation lines to be processed.
How can I obtain engine evaluations for positions?
CQLi does not have builtin position evaluation algorithms but the Command Pipe feature allows CQLi to easily communicate with external programs written in any programming language. This feature can be used to submit positions to a chess engine to obtain such an evaluation. See "Other Features" ⇒ "Interacting with External Programs using Command Pipe" ⇒ "Examples" ⇒ "Communicating with a Chess Engine" in the Reference Manual for an example that uses a short Python script to obtain Stockfish engine evaluations from within CQLi.How can I print the FENs of positions matching my query?
Add the filtermessage currentfen to the location within
the query where you would like the FEN to be emitted.