Molecular Query Language
Switch branches/tags
Nothing to show
Clone or download
Fetching latest commit…
Cannot retrieve the latest commit at this time.
Failed to load latest commit information.


MolQL (Molecular Query Language) is a declarative language for describing selections/substructures of molecular data.

Goals of the language:

  • Provide a common set of functions that is straightforward to implement in different environments while being powerful enough to express a wide range of queries. MolQL could therefore serve as a compilation target for other selection languages, for example the ones used by PyMOL, Jmol, or VMD. For a list of available function, see the language reference.
  • Make it easy to serialize/deserialize the expressions. JSON is the default format.
  • Easily extensible. The language is essentially a stripped-down (Mini) LISP. New functionality is as easy as adding a new symbol.

The language is based on work described in this dissertation that was implemented as part the PattenQuery service (publication), the CoordinateServer (@PDB) and LiteMol.

You can play with MolQL in your browser using the MolQL Explorer.

Project Structure

Building & Running


npm install
npm run build

Interactive builds on file save:

npm run watch

Building docs:

npm run docs

Building MolQL Explorer

npm run app

Then just open web/explorer-dev.html.

To build the minified version, also call npm run appmin, then web/explorer.html will work.


How to add a new symbol to the language?

  1. Add the symbol definition to the appropriate place in src/symbol-table/.
  2. Add implementation to an appropriate place in src/reference-implementation/molql/runtime/.
  3. Map the symbol to implementation in src/reference-implementation/molql/runtime.ts.
    • If adding new atom properties and implementing them in src/reference-implementation/molql/runtime/structure/atom-propeties.ts, this step could be skipped provided the same "key" is used for the symbol.
  4. Add alias for it to src/transpilers/molql-list/symbols.
  5. If possible, add a unit test to src/reference-implementation/molql/spec/?.