Skip to content
Switch branches/tags

Latest commit


Git stats


Failed to load latest commit information.
Latest commit message
Commit time

CQL-Java -- a free CQL parser and related tools, for Java


CQL-Java is a Free Software project that provides:

  • A set of classes for representing a CQL parse tree (a base CQLNode class, CQLBooleanNode and its subclasses, CQLTermNode, etc.)
  • A CQLCompiler class (and its lexer) which builds a parse tree given a CQL query as input.
  • A selection of compiler back-ends to render out the parse tree as:
    • XCQL (the standard XML representation)
    • CQL (i.e. decompiling the parse-tree)
    • PQF (Yaz-style Prefix Query Format)
    • BER code for the Z39.50 Type-1 query
  • A random query generator, useful for testing.

CQL is "Common Query Language", a query language designed under the umbrella of the ZING initiative (Z39.59-International Next Generation). The official specification is at and there's more (and friendlier) information at

XCQL is "XML CQL", a representation of CQL-equivalent queries in XML which is supposed to be easier to parse. The specification is at in the form of an XML Schema.

But if you didn't know that, why are you even reading this? :-)

What's What in this Distribution?

  • -- This file
  • Changes -- History of releases
  • LGPL-2.1 -- The GNU lesser GPL (see below)
  • pom.xml -- Maven project file to control compilation.
  • src -- Source-code for the CQL-Java library and tests
  • target -- The compiled library file, cql-java.jar and javadoc
  • bin -- Simple shell-scripts to invoke CQL programs (parser/lexer/generator)
  • util -- Various testing and sanity-checking Perl scripts
  • etc -- Other files: PQF indexes, generator properties, etc.

Compilation and Installation

The build process is controlled by Maven so compilation is the standard:

mvn clean install

which generates build artifacts under target/.

"Installation" of this package would consist of putting the bin directory on your PATH and target/cql-java.jar on your CLASSPATH.


Using the test-harnesses:

$ CQLParser 'title=foo and author=(bar or baz)'
$ CQLParser -c 'title=foo and author=(bar or baz)'
$ CQLParser -p /etc/ 'dc.title=foo and'
$ CQLLexer 'title=foo and author=(bar or baz)'
	(not very interesting unless you're debugging)
$ CQLGenerator etc/ seed 18

Using the library in your own applications:

import org.z3950.zing.cql.*

// Building a parse-tree by hand
CQLNode n1 = new CQLTermNode("", new CQLRelation("="),
CQLNode n2 = new CQLTermNode("dc.title", new CQLRelation("all"),
			     "elements style");
CQLNode root = new CQLAndNode(n1, n2);

// Parsing a CQL query
CQLParser parser = new CQLParser();
CQLNode root = parser.parse("title=dinosaur");
// ... where `config' specifies CQL-qualfier => Z-attr mapping


See the automatically generated class documentation in the "target" subdirectory.


Original code and documentation by Mike Taylor, Index Data At present maintained by Jakub Skoczen, Index Data

Please email us with bug-reports, wishlist items, patches, deployment stories and, of course, large cash donations.


The CQL-Java suite is Free Software, which is pretty much legally equivalent -- though not morally equivalent -- to Open Source. See for a detailed if somewhat one-sided discussion of the differences, and particularly of why Free Software is an important idea.

CQL-Java is distributed under version 2.1 of the LGPL (GNU LESSER GENERAL PUBLIC LICENSE). A copy of the licence is included in this distribution, as the file LGPL-2.1. This licence does not allow you to restrict the freedom of others to use derived versions of CQL-Java (i.e. you must share your enhancements), but does let you do pretty much anything else with it. In particular, you may deploy CQL-Java as a part of a non-free larger work.

See also