CompassQL is a visualization query language that powers chart recommendations in Voyager 2.
spec) for describing a collection of queried visualizations. This
spec's syntax follows a structure similar to Vega-Lite's unit specification. However,
spec in CompassQL can have enumeration specifiers (or wildcards) describing properties that can be enumerated.1
Grouping/Nesting method names (
nest) for grouping queried visualizations into groups or hierarchical groups.
Ranking method names (
chooseBy) for ordering queried visualizations or choose a top visualization from the collection.
config) for customizing query parameters.
Internally, CompassQL engine contains a collection of constraints for enumerating a set of candidate visualizations based on the input specification, and methods for grouping and ranking visualization.
1 Since multiple encoding channels can be a wildcard, the
encoding object in Vega-Lite is flatten as
encodings which is an array of Encoding in CompassQL's
Given a row-based array of data object, you can use CQL in two steps.
var schema = cqlschema;
(You can reuse the same schema for querying the same dataset multiple times.)
var output = cql;var query = outputquery; // normalized queryvar result = outputresult; // recommendation result
Currently, a result is an object of class
SpecQueryModelGroup that can contains items of class
For example source code, please see index.html and its source code and console log. (Currently we don't output any to the HTML yet.)
To understand more about the structure of a CompassQL Query, look at its interface declaration.
SpecQueryinterface, which follows the same structure as Vega-Lite's
UnitSpec. The interface name has
Querysuffixes to hint that its instance (which can contain wildcards) is a query that describe a collection of specifications. Most interfaces under
SpecQuerysimilarly describe a "query" version of directives in Vega-Lite.
The root file of our project is
src/cql.ts, which defines the top-level namespace
cql for the compiled files. Other files under
src/ reflect namespace structure. All methods for
cql.xxx will be in either
src/xxx/xxx.ts. For example,
cql.util.* methods are in
cql.query is in
You can install npm dependency with:
You can use the following npm commands such as
npm run build npm run lint npm run test npm run cover // see test coverage (see coverage/lcov-report/index.html) npm run watch // watcher that build, lint, and test npm run test-debug // useful for debugging unit-test with vscode npm run clean // useful for wiping out js files that's created from other branch
(See package.json for Full list of commands.)
To play with latest CompassQL in the vega-editor, use branch
cql-vl2, which has been updated to use Vega-Lite 2 and Vega 3.
(For CompassQL 0.7 or older, use branch
compassql, which uses Vega-Lite 1.x).
Make sure to link CompassQL to the editor
cd COMPASSQL_DIR npm link cd VEGA_EDITOR_DIR npm run vendor -- -l compassql
(You might want to link your local version of Vega-Lite as well.)
The main method is
cql.recommend, which is in
examples- Example CompassQL queries
examples/specs– All JSON files for CompassQL queries
examples/cql-examples.json- A json files listing all CompasssQL examples that should be shown in Vega-editor.
src/- Main source code directory.
src/cql.tsis the root file for CompassQL codebase that exports the global
cqlobject. Other files under
src/reflect namespace structure.
test/- Code for unit testing.
test's structure reflects
src's' directory structure. For example,
test/constraint/test files inside
typings/- TypeScript typing declaration for dependencies. Some of them are downloaded from the TypeStrong community.