# CQLi — Chess Query Language

> CQL (Chess Query Language) is a domain-specific language for searching chess
> games in PGN files by position, pattern, move sequence, material, metadata, and
> game-tree structure. CQLi is an independent implementation: a fast,
> multi-threaded command-line tool that reads a PGN file and a CQL query and
> writes out the games that match, annotated with comments at the matching
> positions.

CQL is small but unusual. Two of its rules cause most mistakes: a query is a
list of filters that must all match **the same position**, and a filter can
yield a value while still failing to match (`0` and `""` match; `false`, `None`,
and the empty set `[]` do not). Anyone writing a query — human or model — should
read those rules before anything else.

If you are a language model asked to write a CQL query, fetch
[llms-full.txt](https://cql64.com/llms-full.txt) and work from it. It is a
complete condensation of the reference manual written for this purpose: the full
filter set with types and signatures, the precedence table, the traps that
produce queries which parse but do the wrong thing, and roughly a hundred worked
examples. Do not invent filters or parameters that do not appear in it.

## For language models

- [llms-full.txt](https://cql64.com/llms-full.txt): the whole language in one file — execution model, types, piece designators, every filter, precedence, worked examples, common mistakes, and differences from CQL 6.1.

## Getting started

- [Quick start](https://cql64.com/quick-start.html): install CQLi and run a first query.
- [Examples](https://cql64.com/examples.html): a gallery of queries with the positions they find.
- [Download](https://cql64.com/download.html): binaries and source.
- [FAQs](https://cql64.com/faqs.html)

## Reference manual

- [Full manual, single page](https://cql64.com/manual/all/): everything below in one document.
- [Manual contents](https://cql64.com/manual/): chapter index.
- [CQL fundamentals](https://cql64.com/manual/cql-fundamentals/): execution model, types and matching, literals, variables, piece designators, operators, strings and regular expressions.
- [Board state filters](https://cql64.com/manual/board-state-filters/): `attacks`, `attackedby`, `check`, `mate`, `power`, `fen`, pawn structure, `ply`, `zobristkey`.
- [Board geometry filters](https://cql64.com/manual/board-geometry-filters/): direction filters, `between`, `dark`/`light`, `file`/`rank`, `makesquare`.
- [Ray filters](https://cql64.com/manual/ray-filters/): `ray`, `xray`, `pin`.
- [Metadata filters](https://cql64.com/manual/metadata-filters/): `result`, PGN tag filters, `elo`, `year`, `settag`, `removetag`.
- [Gametree filters](https://cql64.com/manual/the-gametree-filters/): parents, children, mainline and variations, ancestry, `lca`, `distance`.
- [Position relationship filters](https://cql64.com/manual/position-relationship-filters/): `find`, `echo`, `consecutivemoves`.
- [The move filter](https://cql64.com/manual/the-move-filter/): played, legal, pseudolegal, and reverse moves and their parameters.
- [The line filter](https://cql64.com/manual/the-line-filter/): matching sequences of positions with regex-style repetition.
- [The sort filter](https://cql64.com/manual/the-sort-filter/): ranking games by a computed value.
- [Selection and iteration filters](https://cql64.com/manual/selection-and-iteration-filters/): `if`, `square`, `piece`, `key`, `while`, `loop`.
- [Functions](https://cql64.com/manual/functions/): user-defined functions and `import`.
- [Transform filters](https://cql64.com/manual/transform-filters/): `flipcolor`, dihedral transforms, shifts, `rotate45`, `notransform`.
- [Imaginary position exploration](https://cql64.com/manual/imaginary-position-exploration/): the speculative `move` filter, `imagine`, `saveposition`, `legalposition`, `reachableposition`.
- [Comments](https://cql64.com/manual/comments/): reading, adding, and removing PGN comments, and Smart Comments.
- [Chess variants](https://cql64.com/manual/chess-variants/): Atomic, Chess960, Crazyhouse, Antichess, Horde, King of the Hill, Racing Kings, Three-Check.
- [Other features](https://cql64.com/manual/other-features/): piece tracking, `cqlbegin`/`cqlend`, file I/O, command pipe, multi-threading, the `cql()` header, HHdb interface.
- [Filter conspectus](https://cql64.com/manual/filter-conspectus/): every filter with its type, the keyword list, and the precedence table.
- [Commandline options](https://cql64.com/manual/commandline-options/): all CQLi options, including filter injection and PGN output formatting.
- [Diagnostics](https://cql64.com/manual/diagnostics/): warning levels and the list of warnings and infos.

## Examples

- [Synoptic examples](https://cql64.com/manual/synoptic-examples/): short queries with illustrative positions, plus tag, comment, and output-file recipes.
- [Expository examples](https://cql64.com/manual/expository-examples/): longer walkthroughs — effective attackers, threefold repetition, insufficient material, puzzle generation, mating patterns.

## Optional

- [Appendix A: differences from CQL 6.1](https://cql64.com/manual/appendix-a-differences-between-cql-6.1/): what CQLi adds and where it behaves differently.
- [Revision history](https://cql64.com/revisions.html)
- [Other resources](https://cql64.com/manual/appendix-c-other-resources/): databases, books, and related tools.