ChemQL

ChemQL is a chemistry-focused query language for searching and working with chemical data from Python or an interactive terminal. It provides a compact way to query elements, molecules, and chemical reactions using filters, logical conditions, sorting, and result projections.

Package: chemql-python
Python import: chemql

Features

• Query element, molecule, and reaction datasets.
• Filter records with comparisons and logical conditions.
• Match text using wildcard patterns with like and case-sensitive like!.
• Use and, or, not, and parentheses to combine conditions.
• Use likep for Python regular-expression matching.
• Combine list results with union and intersection.
• Sort, limit, count, and project results with return.
• Look up elements, molecules, and reactions using findel, findmol, and findre.
• Balance chemical equations.
• Set reaction conditions, including temperature, pressure, and catalysts.
• Use Python expressions and control blocks alongside ChemQL queries.
• Use ChemQL from the command line or through its Python API.

Installation

Install the Python package from PyPI:

pip install chemql-python

Upgrading the package or switching versions

If your chemql-python version is >=1.0.1, you can simply run

chemql --upgrade

Or to switch versions to for example 0.2.2

chemql --upgrade 0.2.2

However if you do not have chemql-python version >=1.0.1

pip install --upgrade chemql-python

Or to switch versions to for example 0.2.2

pip install --force-reinstall chemql-python==0.2.2

Quick start

Start the interactive terminal:

chemql

Then try:

search elements name = "Hydrogen"
findel "He"
findmol "H2O"
search molecules molecular_weight < 20 return name formula molecular_weight
search reactions reaction_type = "combustion" return name equation

Show the built-in command reference from the REPL:

help

Command-line usage

Run a single command with -c:

chemql -c 'search elements name = "Hydrogen"'

Run commands from a file with -f:

chemql -f queries.chemql

Check the installed version:

chemql --version

A query file can contain multiple ChemQL commands, one per line. Use the // comment marker for comments and a trailing backslash (\) to continue a command onto the next line.

Example queries.chemql:

// Find lighter molecules
search molecules molecular_weight < 20 return name formula molecular_weight

// Show a subset of the periodic table
search elements atomic_number > 10 and atomic_number < 20 sort atomic_number desc limit 5

Query language

Data sources

ChemQL provides three main sources:

Source Contents

elements Periodic-table element data molecules Molecule properties and identifiers reactions Reaction equations, conditions, and metadata

Search a source explicitly:

search elements
search molecules
search reactions

You can also use search all before a source name, for example:

search all elements atomic_mass < 100

Change the active source in an interactive session with:

source elements
source molecules
source reactions

Filtering

Use comparison operators to filter records:

Operator Meaning

= Equal != Not equal > Greater than < Less than >= Greater than or equal <= Less than or equal like Case-insensitive wildcard match like! Case-sensitive wildcard match likep Python regular-expression match has Check whether a value contains an item

Examples:

search elements atomic_number > 10
search molecules molecular_weight <= 20
search molecules name like "*water*"
search reactions id likep ".*haber(\s*|-|_)process.*"

The wildcard matcher supports * for a sequence of characters and other wildcard tokens supported by ChemQL's pattern matcher. Use likep when you need regular expressions rather than wildcard patterns.

Logical conditions and parentheses

Combine conditions with and, or, and not. Parentheses group conditions. Comparison operators and parentheses can be written without surrounding spaces.

search elements name not like "*ium"
search elements name not like "*ium" and not atomic_mass < 50
search elements atomic_mass > 50 and (density<10 or boil<100)

Combining query results

Use union to combine results and intersection to keep records present in both result lists. Operations are evaluated from left to right.

search elements name not like "*ium" intersection search elements name like "*um"

Use the Python API's query-object operators | and & for union and intersection, respectively, when working with ChemQLQuery objects.

Sorting, limiting, counting, and returning fields

search elements sort atomic_number
search molecules sort molecular_weight desc
search molecules limit 10
search molecules count
search molecules molecular_weight < 20 return name
search molecules molecular_weight < 20 return name formula molecular_weight

• sort <field> [asc|desc] sorts results.
• limit <number> limits the number of results.
• count returns the number of matches.
• return <field...> returns only selected fields. One field produces a list; multiple fields produce a table-like result.
• first and last can be used to select one result.

Find commands

findel "He"
findel "Hydrogen"

findmol "H2O"
findmol "Water"

findre "Haber process"
findre "RHEA:10000" return name equation source

findmol searches the local molecule dataset first and can use external chemical-data services when a local match is not found. External lookups require an internet connection and may be unavailable if the service is down.

Reactions and equation balancing

ChemQL includes reaction data and commands for working with reaction conditions.

findre "Haber process"
balance O2 + H2 -> H2O
balance O2 + H2 <-> H2O

The -> arrow denotes an irreversible reaction, while <-> denotes a reversible reaction.

Set conditions before using react:

set temperature 723K
set pressure 20265000pa
set catalysts iron zinc
conditions
react N2 3H2

Temperature can be supplied in Celsius (C), Fahrenheit (F), or Kelvin (K). Pressure supports units such as pascals and bar; the available unit conversions depend on the installed version. Preset conditions are also available:

set temperature standard
set pressure room

Use help in the terminal for the command reference included with your installed version.

Python API

Import ChemQL from Python:

import chemql

result = chemql.execute_query_text(
    'search elements name = "Hydrogen"'
)
print(result)

You can also use execute_query for a query string:

import chemql

result = chemql.execute_query('search molecules molecular_weight < 20')
print(result)

The package exposes chemistry data classes and helpers, including Element, Molecule, Reaction, ChemQLError, Unknown, ReturnTable, and balance_stoichiometry.

Query builder API

Versions that include the query-builder API also support chaining query conditions:

import chemql

x = chemql.search("elements")
y = x.atomic_mass.condition(lt=10)
z = y.return_("name")

print(z)          # The query as text
print(z.execute())  # Execute the query

Query objects can be combined with | (union) and & (intersection). The convenience functions chemql.union(x, y) and chemql.intersection(x, y) are also available in versions that include this API.

Hybrid Python

ChemQL can execute Python expressions inside square brackets:

[x = 10]
[print(x)]

It also supports Python control blocks using [for ...], [if ...], [elif ...], [else], [while ...], [break], [continue], and [endblock].

Use {{ ... }} to evaluate a ChemQL query and insert its result into Python:

[print({{ search elements atomic_number = 1 }})]

Only run Python code and shell commands from sources you trust.

Shell Commands

ChemQL supports executing system shell commands by enclosing them in backticks (`). Commands execute in a persistent shell session, allowing shell state to be preserved between commands.

Syntax

`command`

Examples

Execute system commands:

`whoami`
`dir`
`echo Hello`

Change the working directory:

`cd ..`
`cd ~`
`dir`

The working directory persists between commands.

Environment variables and other shell state can also persist between commands, depending on the shell being used.

Platform support

• Linux: Bash
• macOS: Bash
• Windows: Command Prompt (cmd.exe)

PowerShell is not supported by the current implementation.

How it works

ChemQL maintains a persistent shell process and sends commands to it sequentially. Command output is captured and displayed in the ChemQL interface, allowing shell state to persist throughout the session.

Notes

• Commands must be enclosed in backticks to be interpreted as shell commands rather than ChemQL statements.
• Shell syntax differs between operating systems. Use commands appropriate for your platform.
• Commands run with the permissions of the process running ChemQL and may modify files or affect your system.
• Interactive terminal programs and commands requiring direct terminal input may not work correctly because the shell uses pipes rather than a real terminal.

Data and external services

ChemQL loads bundled JSON datasets for elements, molecules, reactions, molecule bonds, and bond energies. Some molecule lookups may query PubChem or other external sources when the local dataset does not contain a match.

The periodic-table dataset is based on PeriodicTableJSON by Bowserinator. Review the dataset's accompanying license and attribution requirements when redistributing it or derivative data. The licenses and sources for the other bundled datasets should be checked in their respective files before redistribution.

Safety note

ChemQL's hybrid Python functionality can execute Python code. If your installed version supports backtick-wrapped shell commands, those can execute operating-system commands as well. Do not run untrusted ChemQL scripts or queries.

Development notes

• The interactive shell uses prompt_toolkit.
• The command-line interface supports single-command execution (-c) and file execution (-f).
• Consult the package's source and included help output for the exact commands and fields supported by your installed version.

License

MIT License

Created by Mohammad Rakibul Islam. Source code: rakibulofficial1017/ChemQL.