CLI tool that allows you to efficiently search large chess databases in PGN format for games that match specific positions, and apply complex rating filters in addition.
You'll need to set up one YAML configuration file that lists the positions to search for, adhering to the following syntax:
positions:
- fen: "r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3"
- fen: "rnbqkb1r/1p2pppp/p2p1n2/8/3NP3/2N5/PPP2PPP/R1BQKB1R w KQkq - 0 6"
Positions are expressed using Forsyth–Edwards Notation. One convenient way to obtain these notations through the analysis board on Lichess.
Note that move numbers are irrelevant to how positions are matched, thus supporting all possible move transpositions.
In addition to searching for particular positions, games can also be filtered based on the minimum rating of one or both players or the average rating between them. Per position, you can optionally specify the following filters:
positions:
- fen: "r1bqkbnr/pppp1ppp/2n5/1B2p3/4P3/5N2/PPPP1PPP/RNBQK2R b KQkq - 3 3"
filter:
rating:
one: 2100
average: 2200
white: 2100
black: 2300
You can choose to apply just one, or any combination of the filter options listed above. Two or more filters always work cumulatively.
Note that if no rating is specified in the database for any player, the default rating of 1200
is applied for the purpose of applying rating based filters.
Once you have a configuration file set up, use it to search any PGN database (such as an issue of The Week in Chess) you have stored locally like so:
./tabiya --pgn /path/to/games.pgn --config /path/to/config.yaml
Games that match the positions and possible rating filters listed in your configuration will be written as standard output, in the same PGN format as they appear in the source database.
The sample database contains three famous games where black plays the Pirc defense, while the sample configuration file searches for one particular position that occurred in two of the games.
The resulting database was generated with the following instructions in bash:
./tabiya --pgn examples/pirc.pgn --config examples/positions.yaml >> examples/output.pgn
Although the sought after position occurred in two out of three games in the source database, only one is present in the resulting database. This is expected because the configuration file instructs to filter out games where the white player is rated below 2700, which is the case in one of both games that matched the position search.