Percival is a declarative data query and visualization language. It provides a reactive, web-based notebook environment for exploring complex datasets, producing interactive graphics, and sharing results.
Percival combines the flexibility of Datalog as a query language for relational data with the beauty of exploratory visualization grammars. These declarative components interact through a reactive dataflow system. Because Percival uses web technologies (including Web Workers for multithreaded, sandboxed execution), fully-interactive notebooks can be shared with anyone on the Internet, making data analyses more tangible to others.
This is an early-stage research project, and we welcome your feedback, so please feel free to say hello at our discussions page!
If you've gotten to this point in the README, please first try out the web application and demo notebook at percival.ink! The information below is technical documentation intended for contributors.
wasm-pack build --target web crates/percival-wasm
npm run dev
This should open a Percival notebook in your browser, with live reloading.
This section outlines the high-level technical design of Percival.
Percival is a client-side web application running fully in the user's browser. The notebook interface is built with Svelte and styled with Tailwind CSS. It relies on numerous other open source libraries, including CodeMirror 6 for live code editing and syntax highlighting, Remark and KaTeX for Markdown rendering, and Vite for frontend bundling.
The code for the web frontend is located in
src/, which contains a mix of Svelte (in
src/components/) and TypeScript (in
src/lib/). These modules are bundled into a static website at build time, and there is no dynamic server-side rendering.
crates/ folder. For ergonomic parsing with human-readable error messages, the compiler relies on chumsky, a parser combinator library.
In production, the
main branch of this repository is continuously deployed to percival.ink via Vercel, which hosts the static website. It also runs a serverless function (see
api/index.go) that allows users to share notebooks through the GitHub Gist API.
To build, lint, and format the Svelte project, use the corresponding scripts:
npm run build
npm run check
npm run format
For the Rust crates, you can run unit tests for the core functionality with:
You can also run tests for the WebAssembly component using a headless Chrome or Firefox browser:
wasm-pack test --chrome --headless crates/percival-wasm