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.

Theory of Operation

The CQLi tool accepts a PGN file and a CQL query as input and outputs the games from the PGN file that match the provided query. A game matches the query if any positions appearing in the game match the query. A CQL query consists of one or more filters.

For each game processed by CQLi, a game tree is constructed to represent the game and any variations present. Every position in a game has a unique sequential position id starting at 0 for the initial position. Each position in the game is visited once, starting at the initial position and progressing through the positions corresponding to the moves made in the game in order of increasing position id. For each position, the supplied CQL query is evaluated. Each filter in the CQL query is evaluated at the current position and either matches the position or not. As soon as a filter fails to match, evaluation of the current position stops and the query is then applied to the next position. A position matches if all of the filters in the query succeed for the position. After all positions in the game have been evaluated, the game matches the query if at least one position in the game matched.

Each game that matches the query is saved until processing of all games is complete. When all games have been processed, matching games are sorted according to any provided sort criteria, comments are added for matching positions, tag modifications are applied, and the resulting games are written to the output file.

Running CQLi

CQLi is a command line application which can be run from a shell or command prompt or another program such as a GUI interface or a batch script. CQLi accepts many options that affect the behavior such as how many threads to use, PGN output formatting options, and options that allow queries to be specified or modified on the command line. The full set of available options are documented in Commandline Options. The most important options are summarized below.

The -i option is used to specify the name of the input PGN file which contains the games that will be queried. The -o option is used to specify the name of the output PGN file, i.e. the file to which CQLi will write matching games. The output file is truncated first if it already exists. If no -o option is specified, matching games will be written to a file with a name constructed from the provided CQL query file as explained in the description of the -o option. The -i and -o options both require exactly one argument: the name of the respective file. Options and their corresponding arguments are separated by spaces. The final argument of a typical CQLi invocation is the name of the file that contains the CQL query to be evaluated. For example:

cqli -i input.pgn -o output.pgn test.cql

will process the query contained in test.cql for each game in the input file input.pgn writing any matching games to output.pgn. If the provided query file name cannot be found in the current directory or any directories specified by the CL_PATH environment variable, and does not end with an extension, CQLi will attempt to locate the file with the extension .cql appended.

The text of a CQL query may also be specified directly on the command line using the -cql option, for example the command:

cqli -i input.pgn -o output.pgn -cql 'mate parent : check'

will find games where check was answered by checkmate. When specifying a query with -cql that contains spaces or characters special to the shell, the argument to -cql must be quoted, typically by surrounding the entire argument with single quotes.

A Brief Tour of CQL

This section introduces CQL through a series of short examples aimed at the first-time user. Each example adds one new idea to the previous one: finding checkmate, combining filters, using or and not, describing pieces on squares, expressing attack relationships, comparing material, searching both colors with a transform, and adding comments to matching positions. Detailed explanations of every feature used here can be found in later sections of this manual.

mate

btm
mate

mate or stalemate

check
not mate

mate
Qh7
kg8

k attackedby Q

btm
k attackedby Q

btm
mate
power a - power A >= 8

flipcolor {
    btm
    mate
    power a - power A >= 8
}

flipcolor {
    btm
    mate
    power a - power A >= 8
    comment "Checkmate despite material deficit"
}

Basic Concepts

$check_pos = find check

X = []      // X holds the empty set 
X = a1      // X holds the value a1
X =? []     // X is not modified

if 1 == 2 then X = 1
str(X)      // yields the string "<None>", X is unbound

unbind X

X = 1
Y = 1
unbind Y
isbound X   // true
isbound Y   // false
isbound Z   // false
isunbound X // false
isunbound Y // true
isunbound Z // true

dictionary int --> set Dx

persistent $total_positions += 1

persistent quiet $str = ""

$param = "abc"              // $param created in global scope.
$called = 0                 // $called created in global scope.

function foo($param) {      // $param shadows variable in enclosing scope.
    $called = 1             // Refers to the above $called variable.
    $local = abs $param     // $local is not accessible outside of foo.
    $local + $global        // $global will be accessible at invocation.
}

$global = 10                // $global resides in the global scope.
$result = foo(5)            // foo can access $global from here.

Arithmetic Operators

CQL provides the following arithmetic operator filters for operating on numeric types:

Each of the above operators is a binary infix filter that accepts two numeric arguments and yields a numeric result. The result matches the position unless one of the operands does not match the position or a value of zero is used as the right-hand argument to / or %. Note that division yields only the integral portion of the quotient as CQL does not have a fractional type.

Arithmetic Intrinsics

The following arithmetic intrinsic filters are available:

The sqrt filter does not match the position if its argument has a negative value. Otherwise, all of the above filters match the position if at least one of their operands does. The abs and sqrt filters take exactly one argument which does not need to be parenthesized. The max and min filters require at least two arguments and the argument list must be parenthesized.

The result of the abs filter is the absolute value of its argument. The result of the sqrt filter is the integer portion of the square root of its argument. The min and max filters yield the smallest or largest value, respectively, of their argument list, ignoring arguments that do not match the position.

Comparison Filters

Comparison filters can be used to compare Numeric, Set, String, and Position filters.

All of the comparison filters may be used with two Numeric, String, or Position operands, or with one Numeric operand and one Set operand in which case the Set operand is implicitly converted to a Numeric value that represents the set’s cardinality (the number of squares in the set). The == and != filters may additionally be used with two Set arguments.

The ==, <=, <, >=, and > filters have the same type as their operands and yield the value of the left-hand operand if the corresponding comparison holds and None if it does not. As the comparison filters are also right-to-left associative, they may be chained to express an n-ary relationship. For example $a < $b < $c will yield the value of $a if $b has a value between $a and $c and None otherwise. These filters always yield None if one of their operands is None.

When used with Numeric operands, the standard mathematical relationships are applied. When used with String operands, a Unicode-aware collated comparison is performed. When used with Position operands, checks for an ancestral relationship between the positions.

The != filter yields a Boolean value and X != Y is equivalent to not X == Y for any X and Y. In particular, if X or Y is None, the result of X != Y will be true, even if both X and Y are None.

Logical Operators

CQL provides the and, or, and not logical operator filters. The and and or filters are binary infix operators and not is a prefix operator. and matches the position if both its LHS and RHS operands match the position and or matches the position if either of its operands match the position. The not filter matches the position if its operand does not. The and and or filters employ short-circuited evaluation, i.e. the RHS of and is not evaluated if the LHS does not match the position and the RHS of or is not evaluated if the LHS matches the position.

Set Operators

CQL provides the following set operator filters:

The | and & filters are binary infix filters that accept two set filter arguments A and B. A | B yields the union of sets A and B (A ∪ B or the set of squares that are present in either A or B) and A & B yields the intersection of sets A and B (A ∩ B or the set of squares that are present in both A and B). The ~ and # filters are unary prefix filters that accept one set filter argument. ~A yields a set containing the squares not present in A and #A yields a numeric value representing the number of squares present in A. Because the filter . yields a set of all the squares, ~. yields the empty set.

The in binary infix filter accepts two set filter arguments. A in B yields true if A is a subset of B (A ⊆ B or every square in A is also in B) and false otherwise and is equivalent to A & B == A. The query A in B and A != B can be used to determine if A is a proper subset of B (A ⊂ B, or A is a non-identical subset of B). Note that A in B is always true when A is the empty set which should be considered when A could potentially be empty. In particular, use caution when a piece variable is used on the LHS of the in filter. Piece variables are automatically converted to a set representing the location of the piece but this set could be empty if the piece is not currently on the board (i.e. it was previously captured). For example, the intention of the query below is to find all positions where a white pawn has just promoted:

initial
piece Pawn in P {
    find Pawn in a-h8
}

However, it also matches positions where a white pawn was captured because Pawn converts to the empty set in such positions, causing Pawn in a-h8 to evaluate to true. In this case, the correct solution is to use &:

initial
piece Pawn in P {
    find Pawn & a-h8
}

so that when Pawn is empty, the result of Pawn & a-h8 will be the empty set which will not match the position.

Position Operators

echo (source target) {
    differences = ~(source & target)
    differences > 1
    differences == A & source:_
}

X & Y

square sq in . {
    X:colortype sq == Y:colortype sq
}

String Filters

The + binary infix string filter takes two string arguments and yields a string value that is the concatenation of its operands unless one of its operands does not match the position in which case neither does the + filter. The compound assignment filter += may also be used to append a string to a string variable, in general X += Y is much more efficient than X = X + Y and the latter should be avoided for long strings.

When the argument to the unary prefix # cardinality filter is a string, it yields the number of Unicode code points comprising the string (which may be different than the number of bytes or graphemes). The individual code points in a string may be accessed using String Slicing.

The ~~ binary infix string filter is a regular expression matching and extraction operator. The left-hand operand is a string filter and the right-hand operand is a string containing a regular expression pattern. The result is a string that corresponds to the first matching portion of the left-hand operand. Invalid regular expression patterns are diagnosed at query compilation time if the pattern is a string literal, otherwise such errors are diagnosed at runtime with a fatal error. If the left-hand operand does not match the position or there is no pattern match, the filter does not match the position.

By default, matching is case-sensitive and a match may occur anywhere in the string. See Regex Matching Flags for performing case-insensitive matches and Anchored Patterns to limit matches to the beginning or end of a string.

The \n group extraction filter yields the text of the n^th capture group associated with the most recently evaluated regex matching filter. The \-n filter yields the starting index of the most recently evaluated regex matching filter relative to the beginning of the target match string. Named capture groups may be extracted using \{name} and \-{name} which yield the matched text and starting index, respectively, of the capture group with the specified name. If there was no previously evaluated regex matching filter or the most recently evaluated regex matching filter did not match or did not perform a capture corresponding to the provided group number or name, the result of these filters will be None. These filters will yield None after the final iteration of a regex iteration filter.

The ascii filter accepts either a String or a Numeric operand. When provided with a String operand, if the string consists of exactly one character (code point) and the binary value of the character is 127 or less, the value of the filter is this value, otherwise the filter yields None. When provided with a Numeric operand in the range of 0-127, the result is the ASCII character with the provided value.

The in binary infix string filter yields true if the value of the left-hand string operand appears anywhere in the right-hand string operand, otherwise the filter does not match the position.

The indexof filter takes a parenthesized argument list consisting of two String arguments. If the first string appears within the second string, the result is the index in the second string at which the first string appears, otherwise the filter does not match the position. If the first string appears multiple times in the second string, the result is the location of the earliest occurrence.

The uppercase and lowercase filters each accept a single string filter argument and yield the uppercased or lowercased string. Unicode-aware case conversion is performed by the uppercase and lowercase filters, e.g.:

uppercase "Criança" ⇒ "CRIANÇA"

uppercase "Strauß" ⇒ "STRAUSS"

lowercase "Æ" ⇒ "æ"

The int filter accepts a single string argument and attempts to extract an integral value from the string yielding the numeric result if successful. If no integral value could be extracted, the int filter does not match the position. The int filter first skips any initial whitespace and then looks for a sequence of decimal characters, optionally prefixed by a single plus or minus sign. The resulting value is converted to a numeric value. Non-decimal characters following a valid numeric sequence are ignored.

The replace filter has the form:

replace( subject-string pattern-string replacement-string [ count ] )

and yields a copy of the subject-string with portions of the string that match the pattern-string replaced with the replacement-string.

If pattern-string is a string literal, it will be checked for syntax errors at parse time, otherwise regular expression syntax errors in the pattern string will be diagnosed at runtime with a fatal error. Patterns provided as string literals are also faster to evaluate as the regular expression only needs to be compiled once instead of every time the replace filter is evaluated.

In the replacement-string, the \uxxxx and \UXXXXXXXX sequences are expanded to their corresponding Unicode characters and named and numbered capture groups from pattern-string may be accessed using the syntax $# where # is the number of the captured group or ${name} where name is the name of a named capture group. Unmatched groups will be replaced with an empty string. Invalid capture group names or numbers following a $ will result in a fatal runtime error. A literal $ can be obtained by using \$. All other characters are taken literally. Note that the \n regex group extraction and the \-n regex group index filters that work with the ~~ filter do not interact with the replace filter in any way. The capture groups of a replace filter are accessible only within the pattern and replacement strings of the filter.

If count is not provided or has a value of 0, all instances that match the provided pattern-string are replaced. If count is greater than 0 then only the first count matches will be replaced. If count is negative, then only the last -count matches will be replaced. If the magnitude of count is greater than the number of matches in subject-string, all instances will be replaced.

If any of the arguments supplied to the replace filter does not match the position then the result of the replace filter will not match. Otherwise the replace filter will match the position even if no replacements occur (in which case the result is the value of the subject-string) or the result is an empty string.

The str filter accepts a parenthesized argument list consisting of one or more filters of any type. The str filter converts each of its arguments to a string value and yields the concatenated result. The str filter always matches the position. Values are converted to strings as described below. If str is used with a single filter the parentheses are optional.

X = "A" + \n

X = "A\n"

$idx = 0
while ($idx < #X) {
    $codepoint  = X[$idx]
    $idx += 1
}

while (X ~~ ".") {
    $codepoint = \0
}

while (X ~~ "\X") {
    $codepoint = \0
}

while (X ~~ "\X") {
    message("Grapheme of length " #\0 " that starts at position " \-0 ": " \0)
}

Regular Expression Matching

The ~~ and replace filters utilize regular expressions. This section provides an overview of some of the fundamental regular expression capabilities supported by the patterns that these filters accept. For more information see Regular-Expressions.info which is a great resource detailing the features provided by various regular expression implementations, including that employed by CQLi (ICU version 78 or later).

var ~~ "\d+:\d+"

"ABBB" ~~ "AB*"

"ABBBCABD" ~~ "AB*D"

"ABABBABBBB" ~~ "AB+"

"ABBB" ~~ "AB+?"

"#A# #B# #C#" ~~ "#.*#"

"#A# #B# #C#" ~~ "#.*?#"

"ABCCDEEEEF" ~~ "(.)\1{2,}"
\0 == "EEEE"
\1 == "E"

"2024-01-15" ~~ "(?<year>\d{4})-(?<month>\d{2})-(?<day>\d{2})"
\{year} == "2024"
\{month} == "01"
\{day} == "15"
\-{year} == 0
\-{month} == 5

var ~~ "^\d+"

while ("ABC" ~~ ".") {
    message \0
}

Ranges

Several filters accept an optional range argument. A range consists of one or two numeric filters, each of which must be either a numeric variable or a numeric constant. The first filter in a range may be the operand of a negation operator. When a single range constituent is provided the resulting range represents a single value, otherwise the range represents the set of values between (and including) the supplied endpoints. Potential range elements must not be parsable as part of a larger expression, e.g. find 1 10 -3 will be parsed as a find filter with a range of [1:1] and a body of 10-3, not as a range of [1:10] with a body of -3.

The filters accepting a range argument are: consecutivemoves, find, line, and the direction and transform filters (use of ranges in transform filters is deprecated). In the very unusual situation where the body of one of these filters might unintentionally be interpreted as a range, parentheses or braces can be used around the body to prevent it from being parsed as a range.

Ranges were used extensively in CQL 5 which did not possess arithmetic comparison operators and instead relied on ranges to specify target values for many filters. For example, to find positions where White is attacking 50 or more squares in CQL 5, the query attack 50 64 (A .) was used. In CQL 6, the equivalent query is . attackedby A >= 50. CQL 6 retains ranges in several places where the same functionality would not be easily expressed without ranges but they play a much smaller role than they did in CQL 5.

Identity Operator

The identity operator is represented with the backtick character (`). The identity operator is a prefix filter taking a single filter operand of any type. The type and value of the identity operator are those of its operand.

The identity operator never changes the type or value produced by its operand. Instead, it changes how the operand is interpreted in context. The identity filter has the following contextual effects:

• When used to prefix a variable that is an argument in a function call, it suppresses pass-by-ref semantics.

For example, after the following query is executed, $var1 will be set to 0 but $var2 will retain its value:

$var1 = 10
$var2 = 20

function clear($param) { $param = 0 }

clear($var1)
clear(`$var2)

• It forces the normally suppressed PieceID-to-Set conversion in a function call or within a message or comment filter.

For example, in the starting position, the first message filter below will print Ke1 while the second message filter will print e1:

piece King = K
message(K)
message(`K)

• It forces evaluation of arguments in a message or comment filter that would normally emit a string.

For example, the filter message(event "X") will print the value of the Event tag followed by the string X but message(`event "X") will print the Boolean value of the event "X" filter (true if the Event tag contains the string "X" and false otherwise).

• When appearing before the key expression in a dictionary access filter, it will prevent the square brackets from being treated as a piece designator.

For example, if Dx is a dictionary, Dx[a2] will be interpreted as the two filters Dx and [a2]. Using Dx[`a2] will instead cause the filter to be treated as a dictionary access filter with a Set key.

Comment Filters

The originalcomment filter provides access to comments appearing in the processed PGN file, the comment filter allows insertion of new comments, and the removecomment filter allows the removal of original comments appearing in the PGN file.

originalcomment ~~ "^123$"

originalcomment ~~ "B.*2"

originalcomment ~~ "B(.|\n)*2"

originalcomment ~~ "B(?s:.)*2"

{pre-game}
1.e4! {Best by test}
1...e5 $1 $113 {??}
2.d4 $10
*

if originalcomment ~~ "^(.*)\[%clk \d+:\d+:\d+\](.*)$" {
    removecomment
    comment(\1 \2)
}

$new_comment = replace(originalcomment "XX" "Y")
removecomment
comment $new_comment

Comments Added by CQLi

There are six situations in which CQLi may add comments to a position which are described in the following sections.

Comment Order

Multiple comments added to a single position will appear in the following order: header comment, match comment, sort comments, and user and auxiliary comments in the order in which they were added by the corresponding filters. Header and sort comments appear only at the initial position, before the first move. When multiple sort filters are present, sort comments appear in the order in which their respective filters appear in the CQL query. CQLi will never add more than one header comment to a game or more than one match comment to a position.

If the game from the input PGN originally contained comments, all comments added by CQLi in a given position will appear after any original comments at that position.

For example, given the following input:

{Pre-game comment} e4 {Best by test} {second comment} e5 *

and the query:

sort line --> comment "comment 1"
          --> comment "comment 2"
          --> comment "comment 3"

the result will be emitted as:

{Pre-game comment} {Game number 1} {CQL} {<sort-id-0>: 3}
{comment 1} {Start line that ends at move 2(wtm)} 1.e4
{Best by test} {second comment} {comment 2} 1...e5 {comment 3}
{End line of length 3 that starts at move 1(wtm)} *

Comment Coalescing

By default, multiple comments at a position will be written out as multiple distinct comments in the PGN file, each enclosed by a separate set of braces. If the –coalescecomments option is used, multiple comments at a single position will be combined into a single comment with space characters separating each coalesced comment component. For example, the query:

initial
comment("A" "B") comment "X" comment "Y"

produces three comments at the initial position: one containing AB, one containing X, and one containing Y. By default, these comments would be represented in the PGN file as three separate comments:

{AB} {X} {Y}

If comment coalescing is enabled, the combined comment will be represented as:

{AB X Y}

Separately written comments make it clear where each comment begins and ends but some chess software does not handle multiple comments well and may not recognize or preserve multiple comments.

Unique comments

By default, multiple comments with the same text at the same position are not written to the output PGN file. This deduplication occurs before comment coalescing and includes both original comments and comments added by CQLi. If there are duplicate original comments at the same position, all but one of them is removed, even if the duplicate comments were not adjacent. Duplicates between new and original comments are likewise removed. The –nouniquecomments option may be used to allow such duplicate comments.

Smart Comments

The Smart Comments mechanism ensures that only appropriate comments are added to the resulting matching games by suppressing unnecessary comments. Comments added by filters such as comment, line, and find are suppressed in the following cases:

• The position does not match the provided CQL query.
• A subsequent filter in the same compound expression fails to match.
• A filter enclosing the filter responsible for the comment does not match, even if the full query ultimately does.
• Comments added in a filter that only accumulates comments associated with the best value encountered by the filter as described below.

comment "Terminal position"
terminal

if terminal {
    comment "End of mainline"
    mainline
}

(2 < { comment("Pinned pieces:" pin) pin } < 5) or true

min( {comment "A" 1} {comment "B" 2} {comment "X" 1} {comment "Y" 3})

sort {
    num_moves = move legal count
    comment("Number of moves available:" num_moves)
    num_moves
}

checks = 0
line --> { check checks += 1 comment("Check #" checks) } +

The attackedby and attacks Filters

The attackedby and attacks filters provide information about the squares attacked by one or more pieces. Both filters are binary infix filters each accepting a Set filter for both their LHS and RHS operands.

The attackedby filter has the form X attackedby Y and yields a Set value representing the subset of squares in X which are attacked by pieces occupying squares in Y.

The attacks filter has the form X attacks Y and yields a Set value representing the set of squares in X occupied by a piece that attacks a square in Y.

A piece P attacks square S if a king of the opposite color on square S would be in check by piece P. In particular, P can attack S even if P may not legally move to S, e.g. P is pinned, it’s king is in check, or it is not P’s side to move. The pin filter can be used to determine if attacking pieces are pinned.

In the above diagram, the squares attacked by white pieces are highlighted in blue and the squares attacked by black pieces are highlighted in red (this is a very unusual position in that all squares are attacked by exactly one side). The query:

. attackedby A

will yield the set of squares attacked by white pieces (those shown in blue above) and:

. attackedby a

will yield the set of squares attacked by black pieces (those shown in red above). The following query was used to find a position where all squares were attacked by exactly one side:

. attackedby A & . attackedby a == []
. attackedby A | . attackedby a == 64

Note that X attackedby Y will match the position only when Y attacks X would (and vice versa) but the result of these filters is not the same: the former yields the set of squares attacked while the latter yields the pieces which attack these squares. For example:

A attacks k

will yield the squares occupied by white pieces which attack the black king but:

k attackedby A

will yield the square on which the attacked king resides. The following query will find squares on Black’s side of the board that are attacked by White but not defended by Black:

a-h5-8 & (. attackedby A & ~ . attackedby a)

To find undefended black pieces attacked by White use:

a attackedby A & ~ a attackedby a

The below query will find underdefended black pieces attacked by White:

square sq in a {
    a attacks sq
    #A attacks sq > a attacks sq
}

The attackedby and attacks filters have a higher precedence (bind tighter) than most other operators including the &, |, and ~ set filters, comparison filters, and the cardinality filter (#). Consequently, queries such as a attackedby A & ~ a attackedby a and #A attacks sq > a attacks sq used above need not be parenthesized to obtain the expected meaning.

See Calculating Effective Attackers for examples of how to exclude pinned attackers and/or include battery attackers.

CQL 6.1 allows the attackedby filter to be spelled using two tokens: attacked by. For backwards-compatibility CQLi does the same.

The black, white, btm, wtm, and sidetomove Filters

The btm, wtm, and sidetomove filters provide information about the side to move in the current position. The btm filter yields true if it is Black to move and the wtm filter yields true if it is White to move, these filters yield false otherwise. The sidetomove filter yields the value of either black or white corresponding to the side that has the move. black and white are numeric filters that always yield the values -1 and 1 respectively.

The btm and wtm filters are provided for convenience, the same behavior can be achieved with sidetomove, e.g. sidetomove == white to determine if White has the move. The sidetomove filter is useful when using position relationship filters to determine if two different positions have the same side to move.

The check, mate, and stalemate Filters

The check, mate, and stalemate filters yield true if the current side to move is in check, is checkmated, or is stalemated, respectively. The side to move is considered to be in check if said side’s king is attacked by an opposing piece. For Standard chess, the check filter is equivalent to:

flipcolor { wtm and K attackedby a }

The side to move is considered to be checkmated when the said side’s king is in check and no legal moves are available. For Standard chess, the mate filter is equivalent to:

check and move legal count == 0

The side to move is stalemated when there are no legal moves available and the king is not in check. The stalemate filter is equivalent to:

not check and move legal count == 0

Note that some chess variants supported by CQLi have different notions of what constitutes check, mate and/or stalemate. For example, some variants allow pawns to be promoted to kings which are not subject to check. See Behavior of check, mate, and stalemate with Variants for details of how these filters work with such variants.

Examples

The below query will find checkmates delivered via a discovered double check:

mate
flipcolor { wtm a attacks K > 1 }

To find smothered mates (defined here as mate delivered by an opposing knight where the king is surrounded by friendly pieces preventing its potential escape), the below query may be used:

mate
flipcolor {
    wtm
    [_a] attackedby K == []
}

The below query will find stalemates that occurred as the result of a pawn promoting to a queen:

stalemate
move previous promote Q

An example of such a game is:

Black played 57...g1=Q?? stalemate. Black could have mated in 3 by instead playing 57...g1=R or 57...h1=Q.

The following query will find positions where the side to move has at least 4 legal moves but all of them, save one, results in stalemate:

(move count legal == move count legal : stalemate + 1) > 3

Here is one such position found by this query:

There are 10 legal moves by White in the above position, 9 of which are stalemate, the remaining move is checkmate. The correct move is Nc7#, in the actual game White played 50.Ka5??.

The colortype and type Filters

The colortype and type filters each accept a single Set operand. If this operand does not consist of exactly one square, the filter does not match the position. Otherwise the result is a numeric value representing the piece type (for type) or piece type and color (for colortype) present on the specified square. The numeric values used to represent piece types by the type filter is given in the below table:

The colortype filter additionally encodes piece color information in the result by negating the type value for black pieces. For example, a white rook will be represented with the value 4 by colortype and a black rook with the value -4; type would yield a result of 4 in both cases.

The typical use case of these filters is to check if the piece or piece type present on two squares or in two positions are the same.

The currentfen and standardfen Filters

standardfen is a String filter whose result is the representation of the current board state in Forsyth–Edwards Notation (FEN). The FEN string for the starting position in standard chess is:

rnbqkbnr/pppppppp/8/8/8/8/PPPPPPPP/RNBQKBNR w KQkq - 0 1

The first field provides a rank-major listing of piece placements starting at rank 8 with ranks separated by slashes and pieces being presented in file order within each rank. A number represents the specified number of consecutive empty squares in the rank. The second field is either w or b indicating White or Black to move, respectively. The remaining fields represent the castling permissions, the en passant target square, the halfmove clock, and the move number. A - is used to represent the complete lack of castling permissions when appearing in the third field and the lack of an en passant target square when appearing in the fourth field.

The currentfen filter is identical to standardfen except that the halfmove clock is always represented as 0 and the move number represented as 1 making currentfen more amiable for use as a dictionary key when identical board positions should produce the same key. See also Positional Intersection and the zobristkey filter for similar applications.

These filters are useful to dump matching board positions for processing by external tools outside of the PGN format.

The fen Filter

If the fen filter is not immediately followed by a string literal, it behaves the same as currentfen. Otherwise the provided string literal must contain the piece placement portion of a FEN string where the characters A, a, ., and _ may be used in addition to the standard piece characters allowed in a FEN string with their usual meaning in CQL. FEN strings are checked at parse time and an invalid string argument will result in a parse error.

The fen filter matches the position if the pieces on the board in the current position correspond to the provided FEN string. For example:

fen "k7/8/NKB5/8/8/8/8/8"

will match the position:

The FEN string is subject to manipulation by enclosing flipcolor, reversecolor, and dihedral transform filters. For example:

flipcolor fen "k7/8/NKB5/8/8/8/8/8"

will also match the position:

and the query:

flipcolor flip fen "k7/8/NKB5/8/8/8/8/8"

will match any of the following 16 FEN strings (these can be seen when using the --parse option to show the transformed query tree):

k7/8/NKB5/8/8/8/8/8
8/8/8/8/8/5B2/5K2/5N1k
8/8/8/8/8/NKB5/8/k7
8/8/8/8/8/2B5/2K5/k1N5
7k/8/5BKN/8/8/8/8/8
5N1k/5K2/5B2/8/8/8/8/8
8/8/8/8/8/5BKN/8/7k
k1N5/2K5/2B5/8/8/8/8/8
8/8/8/8/8/nkb5/8/K7
5n1K/5k2/5b2/8/8/8/8/8
K7/8/nkb5/8/8/8/8/8
K1n5/2k5/2b5/8/8/8/8/8
8/8/8/8/8/5bkn/8/7K
8/8/8/8/8/5b2/5k2/5n1K
7K/8/5bkn/8/8/8/8/8
8/8/8/8/8/2b5/2k5/K1n5

In most cases, it is easier and clearer to use piece designators to specify desired piece arrangements but the fen filter is convenient when looking for positions that match a FEN string copied from a chess program, online game, or other electronic media. See also the –fen option.

The halfmoveclock Filter

The halfmoveclock filter yields the current value of the halfmove clock, an integer that represents the number of halfmoves (plies) for which no captures or pawn moves have been made. By default, all games start with a halfmove clock initialized to zero. Games may specify a different initial value by using the FEN PGN tag which will be honored by CQLi.

The following query will find positions where a valid claim fifty-move rule claim becomes available, i.e. each side has made 50 moves without a capture or pawn push and the side to move is not mated or stalemated:

halfmoveclock == 100
move legal

The movenumber Filter

The movenumber filter yields the move number of the current position. Move numbers start at 1 unless the FEN PGN tag specifies a valid alternate starting move number in which case the initial position starts at the specified move number. The move number is incremented after each move by Black, regardless of the side to move in the initial position. The movenumber filter always matches the position. The query below will find games that end before move 20:

terminal
movenumber < 20

Pawn Structure Query Filters

A group of two or more pawns of the same color on adjacent files are connected. The group must span at least two files and consists of all of the pawns in the adjacent files. A pawn is isolated if there are no friendly pawns in an adjacent file.

A group of two or more pawns of the same color on a single file are doubled. The pawns in the group need not occupy adjacent ranks. A pawn that has no opposing pawns in front of it on the same or adjacent file (i.e. a pawn that can keep it from advancing) is a passed pawn.

The connectedpawns filter evaluates to the set of squares occupied by connected pawns on both sides. The doubledpawns, isolatedpawns, and passedpawns filters similarly evaluate to the set of squares occupied by doubled pawns, isolated pawns, and passed pawns, respectively.

A pawn query can be isolated to a particular side by using the bitwise and operator &. For example, the query

passedpawns & p

will yield the set of squares occupied by passed black pawns. The query

doubledpawns & a-d1-8

will yield the set of queen side doubled pawns. Connected passed pawns can be found using

connectedpawns & passedpawns

Note that every pawn is either isolated or connected so

isolatedpawns & connectedpawns

will always evaluate to the empty set and

isolatedpawns | connectedpawns == [Pp]

will always be true.

In the diagram below, the connected pawns are highlighted in blue and the isolated pawns are highlighted in red.

In the following diagram, passed pawns are highlighted in blue and doubled pawns in red.

The pawn on a7 is both passed and doubled so it is highlighted twice.

shifthorizontal flipcolor { TP = down a8 & P TP > 2 TP }

flipcolor Pa-h5-8

flipcolor p & up 1 P

flipcolor P & diagonal 1 P

(flipcolor P & diagonal 1 P) & (flipcolor P & ~ up horizontal 0 1 P) 

The power Filter

The power filter takes a single Set argument S and returns a numeric value representing the sum of the power of each of the pieces that occupy the squares in S. For the purpose of this filter, each piece has a static power value, expressed in terms of the power of a pawn, given by the table below.

power X, where X is a set filter, is therefore equivalent to:

#[Pp]&X + #[Nn]&X * 3 + #[Bb]&X * 3 + #[Rr]&X * 5 + #[Qq]&X * 9

The power filter always matches the position and yields a value of zero if the provided Set is empty or there are no non-king pieces occupying the squares in Set.

A user-defined function can be employed to calculate the power of pieces using alternative piece values. For example, if rooks should be valued at 5.5 pawns, queens at 10, and bishops at 3.5, the following function can be used:

function altPower(X) {
    #[Pp]&X * 10 + #[Nn]&X * 30 + #[Bb]&X * 35 +
        #[Rr]&X * 55 + #[Qq]&X * 100 
}

Because numeric values in CQL are integers, relative values need to be scaled. The altPower function therefore represents power in decipawns (tenths of a pawn) instead of pawns.

The ply Filter

The ply filter yields the ply of the current position. The ply represents the number of half-moves made since the initial position. The ply starts at zero for the initial position (regardless of the move number specified by an optional PGN FEN tag) and is incremented by one for each half-move played by either side.

The following query will find games with a length of at least 200 ply (at least 100 moves played by each side):

ply == 200

Note that this will not limit matches to games with exactly 200 ply but rather match any games that have a position where ply is 200. Using ply >= 200 will achieve the same results except that every position above ply 200 will be commented instead of just the position at ply 200 (the --quiet or --matchstring="" options may be used to prevent matched positions from being commented at all). To find games that end at a particular ply, use terminal to match the desired ply at the terminal position, e.g.:

terminal
ply == 200

Changing == in the above query to >= will find all games with 200 plies or more and comment only the terminal position instead of the position that represents the 200^th ply.

Note that an even ply typically represents a position where it is White to move and an odd ply Black to move but this is not always the case. If the game contains a FEN tag that specifies Black to move in the starting position, even plies will correspond to Black-to-move positions. Use the wtm and btm filters to determine which side has the move.

The promotedpieces Filter

The promotedpieces filter yields the set of squares occupied by promoted pawns. For example, the query:

promotedpieces & Q
promotedpieces & q

will match positions where both sides have a promoted queen on the board.

Tracking of promoted pieces is necessary for the Crazyhouse variant (captured promoted pieces are dropped as pawns instead of the promoted piece type) but CQLi performs promoted piece tracking for all variants.

The zobristkey Filter

CQLi maintains a 64-bit Zobrist hash key for each position, the zobristkey filter yields a string containing the hexadecimal representation of this value for the current position.

A Zobrist hash is calculated by XORing predefined 64-bit keys that correspond to characteristics of the current board state. Invented by Albert Zobrist, this simple but effective method is fast to calculate and produces significantly different values for similar positions, providing positional keys that are all but guaranteed to be different for different positions in a game (like all hashing methods, collisions are possible but it is extremely unlikely for different positions in a recorded game to have the same Zobrist hash) and guaranteed to be identical for identical positions even in different games.

The Zobrist hash incorporates the following pieces of board state into the hash key:

• The piece type and color present on each square.
• Castling permissions for each side.
• En-passant capture rights.
• The side to move.
• The pieces each side has in their pocket (only used for the Crazyhouse variant).

For the purpose of calculating the Zobrist hash, the side to move is considered to have “en passant capture rights” if the last move was a double-pawn push and the side to move has a pawn that attacks the square behind this pawn, even if en passant capture would otherwise be illegal (e.g. because the pawn is pinned).

In particular, the ply, move number, and half-move clock (i.e. number of half-moves since the last capture or pawn push) do not influence the value of the Zobrist key making it an effective mechanism to detect positional repetition which is how such detection is commonly employed by chess engines. See Detecting 3-fold Repetition for an example of how this can be accomplished using the zobristkey filter.

Direction Filters

A direction filter consists of a basic or compound direction keyword followed by an optional range and a Set target filter. The result is the set of squares that can be reached by moving in the specified direction from any of the squares in the target set. If an optional range is provided, only the squares that can be reached in a number of steps enclosed by the range are included, a range of 1 7 is implied if not provided. If the range includes 0, the squares in the target set are included in the result. Negative values included in the range represent squares that can be visited by moving in the opposite direction.

The eight basic directions are: up, down, left, right, northeast, northwest, southeast, and southwest. The compound directions and their component directions are given in the below table.

Examples

The between Filter

The between filter takes two Set arguments, set1 and set2, and returns the set of squares that are between any two squares S₁ and S₂ where S₁ is a square in set1 and S₂ is a square in set2. A square S is between two squares S₁ and S₂ if S is present in the set that results from evaluating the query anydirection sq1 & anydirection sq2. In other words, if S is traversed when starting on S₁ and moving in a single direction to reach S₂ then S is between S₁ and S₂. Similarly, if S₁ can be reached by moving in a single direction from S and S₂ can be reached by moving in the opposite direction from S, then S is between S₁ and S₂.

The below diagram shows the result of the query between([a1,a3,g1] a-h8).

The dark and light Filters

The light and dark filters each accept a single Set argument and yield the set of light or dark squares, respectively, contained in the provided set. For example:

dark [Bb]

represents the squares on which dark-squared bishops reside and:

move to light . legal from R

represents the light squares on which a white rook may legally move in the current position.

The meanings of dark and light are influenced by color transforms (see Transform Filters). For example:

flipcolor dark [Aa] == [Aa]

will match any position where all pieces of both sides reside either on light squares or dark squares.

The file and rank Filters

The file and rank filters each take a single Set argument. If the set argument contains exactly one square, the result is the numeric value of the corresponding file or rank of the square, respectively, otherwise these filters yield None. The numeric values returned by these filters are in the range 1-8 with file a having the value 1 and file h having the value 8.

For example, the Chebyshev distance (the minimum number of king moves needed to move between two squares) between two squares sq1 and sq2 is given by the query:

max( abs(file sq1 - file sq2) abs(rank sq1 - rank sq2) )

The makesquare Filter

The makesquare filter accepts either a single String argument or two Numeric arguments, and yields a set value representing the square corresponding to its argument(s) or an empty set if the provided input is not valid.

makesquare "f6" == f6
makesquare "f6x" == []

makesquare(1 3) == a3
makesquare(6 1) == f1
makesquare(0 3) == []
makesquare(3 9) == []

The ray Filter

ray [direction …] ( Set₁ Set₂ … ) ⇒ Set

The ray filter accepts zero or more directions followed by a parenthesized list of two or more Set filters. directions may be any simple or compound directions, a default of anydirection is used if no direction is provided. The result of the ray filter is the set of squares on which matching rays terminate. Matching rays are those that begin on a square in Set₁ and, moving in a prescribed direction, consecutively include a square in each successive set Set_i in the list of provided sets with only unoccupied squares being allowed to appear between successive sets.

Some examples of ray filters include:

ray (A a A a)           // Four pieces in a line of alternating color
ray diagonal (B n k)    // White bishop pinning a black knight
ray up (R [Pp] r)       // Opposing rooks on a file separated by a pawn

The following query will match any position for which there is an orthogonal ray containing two white rooks, a black queen, and a black king, in that order, without any other pieces in between, i.e. a rook battery pinning the black queen to its king:

ray orthogonal (R R q k)

Such a situation occurs in the following position:

The table below contains other examples of rays shown in the above diagram.

The filter ray(r r) would not match the position in the above diagram because of the presence of the black king between the two black rooks, only empty squares may appear between the consecutive set arguments in the ray filter.

A single ray filter may match multiple rays in which case the result will be the set of the endpoints of all matching rays. For example, ray(p p) matches rays ending on squares a7, b6, g6, a7, and h7. The filter ray right (a1 _) will also match multiple rays ending on squares b1, c1, and d1 as empty squares may appear between the squares specified by a1 and _.

The result of the ray filter represents the end of the matching rays, to obtain the beginning of matching rays simply reverse the set arguments (and possibly the direction) of the ray filter, e.g. ray orthogonal (k q R R) instead of ray orthogonal (R R q k).

The xray Filter

xray ( Set₁ … Set_n) ⇒ Set

The xray filter finds pieces along a ray such that a sliding piece in Set₁ would attack a square in Set_n if the squares between them were unoccupied. The result of the xray filter is the set of squares on which matching rays terminate. Matching rays must consecutively consist of a square in each successive set Set_i in the list of provided sets with only unoccupied squares being allowed to appear between successive sets.

The colors of the pieces involved are not significant, it is not even required that pieces reside on any of the squares except a square in Set₁.

The following query looks for a white rook that x-rays a black queen through a white knight such that the knight can move to a square not attacked by Black and simultaneously check the black king:

xray(R (move from N to ~(. attackedby a): check) q)

The second argument to the xray filter in the above query uses the speculative move filter to find moves by white knights to squares not attacked by Black that also result in check. The result of the move filter is the set of squares on which matching knights reside since the first parameter to the move filter is from.

One position matching this query is:

In the above diagram, the matching xray is shown in red (the move 1.Nd6+ wins the black queen), some other examples of xrays are shown with blue arrows.

Note that an xray filter of the form

xray (S₁ … S_n )

is functionally equivalent to:

ray orthogonal ((S₁&[RrQq]) … S_n )
| ray diagonal ((S₁&[BbQq]) … S_n )

The pin Filter

pin [from Set] [through Set] [to Set] ⇒ Set

A pin is induced from a piece P_x on square S_x through a piece P_y on square S_y to a square S_z when all of the following are true:

• P_x attacks P_y
• P_x and P_y are opposite colors
• S_z is not attacked by P_x but would be if P_y were not present on S_y
• S_z is unoccupied or is occupied by a piece of the same color as P_y

In such a case, P_y is said to be pinned to S_z by the pinning piece P_x. Note that only sliding pieces (bishops, rooks, and queens) can induce a pin. P_x attacks P_y if P_y would be in check by P_x if P_y were a king. In particular, P_x attacks P_y even if P_x is itself pinned. It can be inferred from the above definition that S_x, S_y, and S_z must be distinct squares.

The pin filter finds pins where the from, through, and to squares each match a particular set of squares specified by the optional from, through, and to parameters. A default value of [Aa] is used for each of from and through if not provided and a default value of [Kk] is used for to if not provided, the result of which is to find absolute pins.

The pin filter is a set filter with a value that depends on the first parameter provided to the filter. If from is specified first, the result is the set of squares occupied by the pinning pieces matching the pin filter. If to is specified first, the result is the set of squares to which the pinned pieces matching the pin filter are pinned. Otherwise, if through is specified first or if no parameters are specified, the result is the set of squares occupied by pinned pieces matching the pin filter.

When no parameters are provided,

pin

is equivalent to

pin through [Aa] from [Aa] to [Kk]

which has a value corresponding to the squares of pieces pinned to their king. The filter

pin from [Aa]

is equivalent to

pin from [Aa] through [Aa] to [Kk]

and finds the same pins as pin but has a value of the squares occupied by the pinning pieces instead of the pinned pieces.

In the above diagram, there are 3 pinning pieces (highlighted in green) that each pin a single opponent piece (highlighted in red). The squares the pinned pieces are pinned to are highlighted in blue. The black rook on b3 pins the white pawn on b5 to the squares b6, b7, and b8 even though there are no pieces on those squares and pawn cannot currently move to another file. The black queen on d8 pins the white pawn on d7 to d6 and d5. The pawn is not pinned to d4 because if the pawn were removed, the queen would not attack d4. The white bishop on b1 pins the black pawn on e4 to the empty f5 square and the king on g6 but not to the square h7 which would not be attacked by the bishop even if the pawn were removed.

The rook on b3 does not pin the bishop on b1 because even though the rook attacks the bishop, there is no square S_z along the ray of attack that is not attacked by the rook but would be if the bishop were removed (because the bishop is on the edge of the board).

Using the pin filter without any parameters in the diagrammed position will find just the black pawn pinned to the black king. To find all of the pins shown, the query

pin to .

can be used which is equivalent to

pin to . from [Aa] through [Aa]

Note that for the purposes of the pin filter, kings may be pinned (may occupy a square in the through set) despite the fact that such a situation would ordinarily be referred to as a skewer as an attacked king cannot legally remain in check.

The result Filter

The result filter takes a single argument representing a game disposition and yields a Boolean value indicating whether the game terminated with the specified disposition. The valid arguments for the result filter are: 1-0 or "1-0" indicating a win for White, 0-1 or "0-1" indicating a win for Black, 1/2-1/2 or "1/2-1/2" indicating a draw, and * or "*" indicating an incomplete game. The result filter yields true if the specified disposition matches the disposition of the current game and false otherwise.

The game termination token, not the value of the Result PGN tag, is used to determine the game’s disposition. To obtain the value of the Result PGN tag (which should match the game termination token), use tag "Result".

The following query will detect and report conflicts between a game’s termination token (via the result filter) and either the result recorded in the Result tag or the game’s actual disposition (checkmate, stalemate, variant-specific win, etc).

cql()
mainline
terminal

$result_str = "*"
if result 1-0 then $result_str = "1-0"
else if result 0-1 then $result_str = "0-1"
else if result 1/2-1/2 then $result_str = "1/2-1/2"

if ($result_tag = tag "Result") and $result_tag != $result_str {
    message("Value of Result tag ('" $result_tag
        "') is inconsistent with game termination token '"
        $result_str "'")
}

$cur_side = if wtm then "white" else "black"
$off_side = if wtm then "black" else "white"

if variantwin {
    if flipcolor { wtm not result 1-0 }
        message("Game termination token '" $result_str
        "' inconsistent with result of variant win by " $cur_side)
}
else if variantloss {
    if flipcolor { wtm not result 0-1 }
        message("Game termination token '" $result_str
        "' inconsistent with result of variant loss by " $off_side)
}
else if variantdraw {
    if flipcolor { wtm not result 1/2-1/2 }
        message("Game termination token '" $result_str
        "' inconsistent with result of variant draw")
}
else if stalemate {
    if not result 1/2-1/2
        message("Game termination token '" $result_str
        "' inconsistent with result of stalemate")
}
else if mate {
    if flipcolor { wtm not result 0-1 }
        message("Game termination token '" $result_str
        "' inconsistent with result of checkmate by " $off_side)
}

false

Tag Filters

Tag filters operate on the tag pairs appearing before the move text section of a PGN file.

notransform { player white + \n + player black }

2000 <= year <= 2005

cql(quiet)
mainline
terminal
settag("PlyCount" str ply)

cql(variations quiet)
initial
settag("TotalPlyCount" str find all true - 1)

cql(variations quiet)
initial
settag("MaxPly" str echo(x y) in all { terminal ply })

The gamenumber Filter

Every game is assigned a game number by CQLi which is a one-based index representing the physical order of the game within the PGN file. The first game in the PGN file has a game number of 1, the second a game number of 2, etc. The gamenumber filter yields the game number of the current game.

The proper ordering of game numbers is maintained even when using multiple threads where one thread may process several games in the time it takes another thread to process one game. When using the –gamenumber option to skip games, the indices of the skipped games are not reused, e.g. the option --gamenumber 10 20 specifies that only games 10 through 20 (inclusive) should be processed and the gamenumber filter will yield values between 10 and 20 for these games.

Synopsis

ancestor( Position Position ) ⇒ Boolean
child ⇒ Position
child( Number ) ⇒ Position
currentposition ⇒ Position
depth ⇒ Number
descendant( Position Position ) ⇒ Boolean
distance( Position Position ) ⇒ Number
initial ⇒ Boolean
initialposition ⇒ Position
lca( Position Position ) ⇒ Position
mainline ⇒ Boolean
parent ⇒ Position
position Number ⇒ Position
positionid ⇒ Number
terminal ⇒ Boolean
variation ⇒ Boolean
virtualmainline ⇒ Boolean

The Game Tree

A chess game forms a tree with nodes representing individual positions and edges that connect two nodes representing the moves that transitions from one position to another. When there are no variations, this tree is flat with each node having at most one child and a single path from the initial position to the last position. The PGN format provides a syntax for specifying variations (alternate moves) by enclosing moves corresponding to the variation in parentheses. Variations can be nested and the resulting game tree may have many branches consisting of nodes with two or more children.

For example, given the PGN game

1.e4 (1.d4 Nf6 (1...d5) 2.c4) 1...c5 (1...e5) (1...e6 2.d4 (2.d3) 2...c5 (2...d5))

the corresponding tree representation will look something like:

The number in each node is the position id which is the number that CQL assigns to each position in a game and reflects the order in which positions are visited during game traversal.

The position with position id 0 represents the initial position of the game. Each non-initial position has exactly one parent which is the position that immediately precedes it. Each position contains zero or more children which represent positions reachable from it with a single move. In the figure above, the initial position has two children, positions 1 and 9, and the parent of both of these children is position 0.

Given two positions A and B occurring in a game, A is considered to be an ancestor of B if A can be reached from B by iteratively traversing parent nodes, starting at B. In other words, if and only if there exists a sequence of one or more moves, starting at A, that reaches B, then A is an ancestor of B. The initial position is an ancestor of all other positions. In the above diagram, position 1 is an ancestor of positions 2-8, position 4 is an ancestor of positions 5-8, etc. Position B is called a descendant of A if A is an ancestor of B.

The Comparison Filters may be used to check for ancestral relationships. The filter A < B matches the position when A is an ancestor of B and A > B matches when A is a descendant of B. The filters A <= B and A >= B will also match when A and B are the same position.

If a position does not have any children (there are no recorded moves at the position), the position is called a terminal position. The first move specified at a position is called the primary move and any alternate moves specified are called secondary moves. The initial position and all positions reachable from it via primary moves are called mainline positions, all other positions (those that require traversing a secondary move to reach) are called variation positions. In the above diagram, the left-most child always represents the position reached from its parent via the primary move and all other children are reached via secondary moves. In the diagram below, terminal positions are represented by double-circled nodes and mainline positions are highlighted in green.

1.e4 (1.d4 Nf6 (1…d5) 2.c4) 1…c5 (1…e5) (1…e6 2.d4 (2.d3) 2…c5 (2…d5))

The variation depth of a position is an integer that indicates how many secondary moves are traversed to reach the position from the initial position. The variation depth also corresponds to the number of unclosed parentheses at the corresponding position in the PGN file. Any position with a variation depth of zero is a mainline position.

The latest common ancestor (LCA) of two positions A and B is the position with the greatest ply that is a generalized ancestor of positions A and B. A generalized ancestor of A is either an ancestor of A or A itself. Therefore, the LCA of positions A and B will be one of: A, B, or an ancestor of both A and B. In the above figure, the LCA of positions 1 and 2 is position 1, the LCA of positions 6 and 7 is position 5, and the LCA of 4 and 9 is the initial position. The distance between two positions A and B is the sum of the number of moves that separates each of A and B from the LCA of A and B. For example, the distance between positions 4 and 9 is 3 (the integer 3, not position 3) because the LCA of positions 4 and 9 is position 0, there are 2 moves separating position 0 from position 4 and 1 move separating position 9 from position 0; the sum of which is 3.

A position is a virtual mainline position if it is a mainline position or if it can be reached from a mainline position without traversing secondary moves when it is White to move. All children of a virtual mainline position are virtual mainline positions if it is Black to move, otherwise only the position resulting from the primary move is a virtual mainline position. In the following diagram, all virtual mainline positions are highlighted in green and nodes that represent a position where it is Black to move are designated as btm.

1.e4 (1.d4 Nf6 (1…d5) 2.c4) 1…c5 (1…e5) (1…e6 2.d4 (2.d3) 2…c5 (2…d5))

The ancestor and descendant Filters

The ancestor and descendant filters accept a parenthesized list of two Position filters. The filter ancestor(x y) matches the position if x and y are valid positions and position x is an ancestor of position y. The filter descendant(x y) matches the position if x and y are valid positions and position x is a descendant of position y. Note that ancestor(x y) is equivalent to descendant(y x). The ancestor and descendant filters are now deprecated in favor of the equivalent comparison filters: x < y for ancestor(x y) and x > y for descendant(x y). Note that x <= y and x >= y may also be used to test for generalized ancestor or descendant relationships.

The child and parent Filters

The parent filter yields the position that is the parent of the current position. The parent will fail to match the initial position which does not have a parent.

The child filter yields the position that results from the first child of the current position (the one resulting from the primary move at the current position). The child(n) filter yields the n^th child at the current position. child(0) is equivalent to child and child(n) yields the position that results from the n^th secondary move at the current position. If the specified child does not exist at the current position, the child filter does not match.

Every position, except for the initial position, has exactly one parent. Every position will also have zero or more children. To determine the number of children at the current position, the following filter may be used:

currentposition: move count

The use of currentposition: prevents linearization within a line filter from restricting the visible moves to those in the line being processed.

The currentposition, initialposition, position, and positionid Filters

The currentposition filter yields the position that is currently being evaluated, curpos is a shorthand alias for currentposition. The position filter takes a single numeric argument and yields the position with the provided position ID. If there is no position with the specified position ID, position yields the None value. The positionid filter yields the numeric position ID of the current position. The initialposition filter yields the position that is the initial position of the game, it is equivalent to position 0. initialposition always matches as all games, even those with no moves, have an initial position.

The initial and terminal Filters

The initial filter matches if the current position is the initial position, i.e. the position with position id 0 and no parent. Note that while the initial position is usually the standard starting position in chess, this need not be the case if the FEN PGN tag is used to specify an alternate initial position for the game. initial is equivalent to not parent and positionid == 0.

The terminal filter matches if the current position ends the mainline or a variation, i.e. if the position has no children. terminal is equivalent to not child.

The mainline and variation Filters

A mainline position is one that can be reached from the initial position exclusively via primary moves, all other positions are variations. The mainline filter matches if the current position is a mainline position. The variation filter matches if the current position is a variation position. mainline is equivalent to not variation and depth == 0. variation is equivalent to not mainline and depth > 0.

The depth, distance, and lca Filters

The depth filter yields the variation depth of the current position, i.e. the number of secondary moves that need to be traversed from the initial position to reach the current position. The distance and lca filters each accept a parenthesized argument list containing two position arguments. The lca filter yields the position that is the LCA (latest common ancestor) of the provided positions. The distance filter yields the numeric distance between the provided positions, i.e. the sum of the number of moves separating each position from the LCA of the positions.

The virtualmainline Filter

The virtualmainline filter yields true if the current position is a virtual mainline position, i.e. if it can be reached from the initial position without traversing secondary moves when it is White to move.

The find Filter

find [quiet] [<--] [all | range] target-filter

The find filter evaluates the target-filter first at the current position and then at every position that is a descendant of the current position until the result of target-filter matches the position in which it is evaluated. The result of the find filter is the first position for which the target-filter matched or None if no position matches. If the token <-- appears between find and target-filter, the target-filter will be evaluated for each ancestor position instead of each descendant. If the all keyword appears before the target-filter, the search will not stop at the first matching position and the result of the find filter will be the number of matching positions or None if no searched position matches. If a range is provided in place of all, the result will be the number of matching positions if the number of matching positions is within the provided range (which may include zero) and None otherwise. The quiet, <--, and all keywords may appear in any order but may not follow the optional range.

Positions are searched in position ID order (ascending order for descendants, descending order for ancestors) which is the same order that CQLi uses to process positions in the game evaluation loop.

// Games with 10 or more captures by a single piece
initial
piece $p in [Aa] {
    sort "Number captures by single piece"
    { find all move previous capture . from $p } >= 10
}

{Number captures by single piece: 13} 1.e4 c5 2.Qh5 d6 3.Bc4 e6 4.Qh4
Qxh4 {Found 1 of 13} 5.g3 Qxe4+ {Found 2 of 13} 6.Ne2 Qxc4 {Found 3 of 13}
7.Nec3 Nc6 8.Na3 Qd4 9.Ne2 Qe5 10.O-O Nb4 11.Nc4 Qxe2 {Found 4 of 13}
12.Re1 Qxe1+ {Found 5 of 13} 13.Kg2 Qe4+ 14.Kg1 Qxc4 {Found 6 of 13} 15.b3
Qxc2 {Found 7 of 13} 16.Ba3 Nxa2 17.Rxa2 Qxa2 {Found 8 of 13} 18.Bb4 Qxb3
{Found 9 of 13} 19.Kg2 Qxb4 {Found 10 of 13} 20.h4 Qe4+ 21.f3 Qe2+ 22.Kh3
Qxf3 {Found 11 of 13} 23.d3 Qxd3 {Found 12 of 13} 24.Kg4 e5+ 25.Kg5 Qf3
26.g4 Qxg4# {Found 13 of 13} 0-1

// Games with 10 or more captures on a single square
initial
square sq in . { 
    sort "Most captures on a single square"
    { find all move previous capture sq } >= 10
}

// Games with more than 5 promotions
initial
sort "Number of promotions" find all move promote A previous > 5

// Games with more than 5 promotions in a single line
terminal
sort "Number of promotions" find <-- all move promote A > 5

// Games where neither side castled
terminal
not find <-- move castle

The echo Filter

echo [quiet] ( source target ) [in all] target-filter

The echo filter is used to search for arbitrary relationships between positions in a game. The echo filter takes a parenthesized list of two identifier names and creates a new variable scope in which Position variables with the names source and target are created. The target-filter is then evaluated once for every position in the game except the current position. For each evaluation of target-filter, the source variable is set to the original current position, and the target variable is set to the new position. If in all appears immediately after the parenthesized list, the original current position is included in the list of target positions. Target positions are processed in position ID order.

If target-filter has Numeric type, the echo filter is also Numeric with the result being the largest value of target-filter during evaluation of the echo filter. Otherwise the type of echo is Boolean and matches the position if any evaluation of target-filter matches the position.

For example, to find pairs of positions that are identical except for the side to move, the following query may be used:

echo (source target) {
    source & target == .
    sidetomove != source:sidetomove
}

Note that while it is conventional to name the source and target variables source and target, they may have any valid variable names. The following example will find pairs of positions that differ only in that en passant capture is available in the one case and not in the another:

move legal enpassant
echo (source target) {
    not move legal enpassant
    source & target == .
    sidetomove == source:sidetomove
    source:move legal enpassant:
        comment("enpassant capture " currentmutation " legal here")
    comment("enpassant capture not legal here")
}

Below is a matching study found in the HHdbVI endgame study database:

{Schach/3 (EG#21134).} {Game number 6319} 1.Bf2+ $1 1...Kh1 2.Kf3 f4 {LCA}
(2...g5 3.Bg3) 3.c5 $1 (3.g4 $2 3...g5 4.c5 {enpassant capture not legal here}
{target -->move 4(btm)} {id:14}) 3...g5 4.g4 {CQL} {enpassant capture 4...fxg3
legal here} {source <--move 4(btm)[14]} 4...fxg3 5.Bxg3 Kg1 6.Bxh2+ 1-0 

echo (source target) {
    ...
}

source = currentposition
initialposition : find quiet all {
    target = currentposition
    source != target    // Remove to obtain the 'in all' behavior
    ...
}

The consecutivemoves Filter

consecutivemoves [quiet] [range] ( position1 position2 )

The consecutivemoves filter takes two Position arguments and determines the longest common sequence of identical moves in the lines bound by the provided positions and their LCA. The result of the consecutivemoves filter is the length of the longest common move sequence. The positions corresponding to the longest common move sequence pair found by a consecutivemoves filter across all evaluations for the current game are annotated with correlating comments unless the quiet parameter is specified. This means that a single consecutivemoves filter will annotate at most one sequence pair per game, regardless of how many times the filter is evaluated during the game.

For the purposes of this filter, two moves are considered to be identical if the to square and from square are the same and the color and type of piece moved is the same. This means that promotion of a pawn to different pieces are considered the same, as are moves that differ only in whether a capture occurred. Additionally, there is no distinguishing between a normal pawn capture and an enpassant capture (both involve a pawn moving from and to identical squares).

If either of the two arguments provided to consecutivemoves is None, the result of the filter is None. If both provided positions are part of the same line, then one of them will be the LCA of the two positions and the result of consecutivemoves will be None.

The consecutivemoves filter is typically used to identify key sequences in chess endgame studies and is often accompanied by the echo to provide the positions from which to analyze.

consecutivemoves(x y)

1.Bd5+ (1.Rd1 1...Nd3+ 2.Kd2 b2 3.h7 a1=Q) 1...Kxd5 2.O-O-O+ 2...Nd3+
(2...Kc4 3.Kb2 Nd3+ 4.Ka1) 3.Rxd3+ Kc4 4.Rd4+ (4.Kb2 {y-move[1]}
4...Kxd3 {y-move[2]} 5.h7 {y-move[3]} 5...a1=Q+ {y-move[4]} 6.Kxa1
{y-move[5]} 6...Kc2 7.h8=Q b2+ 8.Ka2 b1=Q+ 9.Ka3 Qb3#) 4...Kxc3 5.Rc4+
5...Kxc4 6.Kb2 {x-move[1]} 6...Kd3 {x-move[2]} 7.h7 {x-move[3]} 7...a1=Q+
{x-move[4]} 8.Kxa1 {x-move[5]} 8...Kc2 9.h8=Q 1-0

Multiple sort Filters

If multiple sort filters appear in a query, a separate sort comment will be generated for each sort filter in the order in which the corresponding sort filters appeared. Games in the output PGN file will be ordered by each sort filter with the first sort filter providing the primary ordering, the second sort filter provided a secondary ordering, etc. with the game number providing a final ordering.

Smart Comments are applied to each sort filter independently of other sort filters. In particular, a sort filter enclosing another sort filter does not influence the best value of the nested filter. For example the query:

sort "max-ply" {
    comment("greatest ply: " ply)
    sort min "min-ply" { comment("smallest ply: " ply) ply }
}

will result in the first sort filter having a best value that corresponds to the position with the largest ply and the nested sort filter having a best value of zero (the smallest ply). The comment smallest ply will be inserted at the initial position and the comment greatest ply will be added to the position with the largest ply. The inner sort is not affected by the outer sort, e.g. the outer sort does not limit the values seen by the inner sort or affect the comment enclosed by the inner sort.

sort Comments

Every sort filter will be represented by a corresponding sort comment at the beginning of each matching game, this comment will include the provided description (or generated identifier) followed by a colon (:), a space, and the best value encountered for the sort filter within that game. If the sort filter was never evaluated or never matched, the articulated value will be none. If the quiet keyword parameter is provided or the –silent command line option is used, a sort comment is not emitted. If there are multiple sort filters with the same description string, the quiet parameter is ignored on all but the first of them.

Unmatched sort Filters

It is possible for a game to match a CQL query without matching a contained sort filter, either because the sort filter was not reached or because it appeared as part of a larger expression that did match. For example, the query:

terminal
if movenumber > 100 then sort min date

will match all games with a Date tag but the sort filter will only be reached for games with more than 100 moves. In the following query, the sort filter is always reached but its target filter will not match every game:

terminal
if sort (movenumber > 100) then comment "Long game"

A sort filter that never matches has an empty best value which sorts after any non-empty value, regardless of sort direction. For example, in the first query above, games with more than 100 moves will appear first in the output PGN file sorted in ascending order by date while the remaining games will appear in game number order (the default output sort order). In the second example, games with more than 100 moves will appear first, sorted in descending order by number of moves, followed by remaining games appearing in the default sort order.

Multiple Best Values

If multiple evaluations of the sort filter yield the same best value, only the comments generated during the first evaluation of the best value will be retained by default. The –keepallbest option may be used to retain the comments associated with every evaluation producing the best value.

Examples

The sort filter may be used with any Numeric or String filter but is often used with the echo, line, and find filters. For example, the following query will find games where one side was subjected to check 10 or more times in a row. If there are multiple sequences of 10 or more checks in a game, only the longest sequence will be considered. Matching games will be ordered in the output PGN file with the games having longer sequences appearing first.

sort "Consecutive checks"
    { line singlecolor nestban --> check + } >= 10

Below is an example of a game found by the above query:

{Game number 1711785} {Consecutive checks: 32} 1.d4 e6 2.c4 Nf6 3.Nc3 Bb4 4.Nf3
c5 5.Qb3 Ne4 6.Nd2 Nxd2 7.Bxd2 Nc6 8.dxc5 Bxc5 9.Ne4 Be7 10.Qg3 O-O 11.Bc3 f6
12.O-O-O d5 13.e3 Nb4 14.a3 a5 15.Be2 Bd7 16.axb4 axb4 17.Nxf6+ Bxf6 18.Bxb4
Ra1+ 19.Kd2 Ra2 20.Rb1 Bxb2 21.Ke1 Rf5 22.h4 Be5 23.f4 Bf6 24.Qf3 d4 25.e4 Bc6
26.g3 Rfa5 27.Bxa5 Qxa5+ 28.Kf2 d3 29.Qxd3 Rd2 30.Qf3 Qc5+ 31.Ke1 Qd4 32.Qg4
Kf7 33.Qh5+ g6 34.Qxh7+ Bg7 35.h5 Rxe2+ {CQL} {Start line that ends at move
67(wtm)} 36.Kxe2 Qxe4+ 37.Kd2 Qd4+ 38.Ke2 Qe4+ 39.Kd2 Qg2+ 40.Ke3 Qxg3+ 41.Kd2
Qc3+ 42.Ke2 Qxc4+ 43.Kd2 Qxf4+ 44.Kc2 Be4+ 45.Kb3 Bd5+ 46.Kc2 Be4+ 47.Kb3 Qe3+
48.Kb4 Qb6+ 49.Kc4 Qd4+ 50.Kb3 Qc3+ 51.Ka4 Bc2+ 52.Kb5 Qc6+ 53.Kb4 Qb6+ 54.Kc4
Qd4+ 55.Kb5 Bd3+ 56.Ka5 Qc5+ 57.Ka4 Bc2+ 58.Rb3 Qa7+ 59.Kb5 Qa6+ 60.Kc5 Qc6+
61.Kb4 Qb6+ 62.Ka4 Qxb3+ 63.Ka5 b6+ 64.Ka6 Qa4+ 65.Kxb6 Qb4+ 66.Kc7 Qc4+ {End
line of length 32 that starts at move 36(wtm)} 67.Kd8 g5 68.Rf1+ Qxf1 69.Qxc2
Bf6+ 70.Kc7 Qf5 71.Qa4 Qd5 72.h6 Qd8+ 73.Kb7 Kg6 74.Qe4+ Kxh6 0-1

The below query will find decisive games with more than 100 moves (by each side), sorted by the number of moves:

terminal
flipcolor result 1-0
sort "Total moves: " movenumber > 100

To find all games played by Viswanathan Anand, ordered in ascending order by date played, the following query may be used:

cql(silent)
initial
player "Viswanathan"
sort min tag "Date"

The silent parameter in the CQL header suppresses both the matching position comments and the sort comments, neither of which are likely to be desired here.