Frequently Asked Questions

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 -version

will 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 the initial 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 a sort 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 a FEN 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 filter message currentfen to the location within the query where you would like the FEN to be emitted.

Where can I download PGN databases?

The Resources page contains sources for obtaining game and study databases.

How can I report a bug or request a feature?

Feedback about CQLi is always appreciated. Please feel free to reach out to the author of CQLi, Robert Gamble, at with questions, feedback, or feature requests.