# QQqq.cql

The CQL file QQqq.cql is a simple introduction to CQL that illustrates some basic features.

## running CQL

You should first of all have CQL installed and know how to run CQL. You can download the QQqq.cql example from this link or you can see in the`examples`

directory of the main CQL distribution.
Suppose we run the file. From the command line we can run

cql -i sample.pgn QQqq.cqlThe effect of this will be to run

`QQqq.cql`

on each position in each game in the pgn file `sample.pgn`

.
Any time a position in such a game *matches* the CQL file `QQqq.cql`

, the game itself will be output to the output file `QQqq-out.pgn`

.

# QQqq.cql line by line

The first line (ignoring comments) iscql(input hhdbvi.pgn)This tells CQL that the file is in fact a CQL file and that, by default, the input pgn file containg games to be searched is in the file

`hhdbvi.pgn`

. This is the PGN consisting of Harold van der Heijden's file of studies, see Heijden database VI interface.
The next line is the first line of the *body* of the CQL file, which contains the series of assertions that will be run against each position of the current game being searched. This line is:

♕==♛==2

Intuitively, this will match any position with exactly two white queens and two black queens. It is equivalent to the two lines:

♕==2 ♛==2Now, one might think that

`♕==2`

simply means "a position with exactly two white queens." And in a sense that description is accurate.
But more precisely, the symbol `♕`

is a piece designator which denotes a set of squares. In this case, `♕`

is the piece designator that is the set of squares on which there is a white queen in the current position. (The currentposition is the position being looked at by CQL).

For example, if there were white queens on `d4`

and `e8`

, then `♕`

would stand for a set with two squares in it, `d4`

and `e8`

.

Given any set of squares at all in CQL, say

, the expression
*x*

#is the number of squares inx

*x*

. Thus,
` #♕`

would has a numeric value equal to the number of white queens in the current position.
Finally, if

is any set, then
*x*

is shorthand forx== 2

#.x== 2

Thus,

`♕==2`

means
`#♕==2`

which is true if the set of squares containing white queens has exactly two elements, i.e., that there are two white queens in the current position.
Similarly, `♛==2`

is true if there are two black queens in the current positions.

The last line of the body is

` ◭==6`

Here, `◭`

is a special symbol that means any piece, white or black. more exactly, `◭`

is a piece designator that represents the set of squares containing a piece (or pawn).

# summary

The body of the CQL file QQqq.cql contains two filters. A*filter*is an expression that is true or false of any particular position.

The first filter is

♕==♛==2which is true when there are exactly two black queens and exactly two white queens in the current position.

The second filter is

`◭==6`

which is true if there are exactly 6 pieces in the position.
A CQL file matches a position if each filter in the body of that CQL file matches the position. The body of `QQqq.cql`

will match any position with 6 total pieces, two of which are white queens and two of which are black queens.

If a game has a position (in the main line) that matches such a position, the game will be output to `QQqq-out.cql`

. In addition, there will be PGN annotations added to each matching position in this matching game. The annotation will be just the single comment `CQL`

although this can be changed in many ways.