How bdarwin/quackjvm works
quackjvm is an embedded DuckDB analytical layer for Java: map objects into typed columns, write them in batches, query with SQL, and read answers as Java values. Its distinct product branches add CQEngine-backed persistence and query pushdown, plus an optional live metrics dashboard. The README documents materializations and Arrow as core capabilities; the tree supports their source paths, though their internal wiring was not sampled. Edges below reflect only documented workflow or explicit source evidence; unsampled subsystems are shown without speculative connections.
Main entry points: Rows.java Typed SQL rows · QuackDashboard.java Dashboard server · DuckDBDatabase.java CQEngine database · TableWriter.java Table writer
Components 23
Core analytics
- Columnar layout
quackjvm-core/src/main/java/io/quackjvm/core/layout/ColumnarLayout.java - Table writer
quackjvm-core/src/main/java/io/quackjvm/core/duckdb/TableWriter.java - Typed SQL rows
quackjvm-core/src/main/java/io/quackjvm/core/sql/Rows.java - SQL query stream
quackjvm-core/src/main/java/io/quackjvm/core/sql/SqlQuery.java - Arrow batches
quackjvm-core/src/main/java/io/quackjvm/core/arrow/ArrowBatch.java - Connection pool
quackjvm-core/src/main/java/io/quackjvm/core/duckdb/ConnectionPool.java - Materialization
quackjvm-core/src/main/java/io/quackjvm/core/sql/Materialization.java - Measure queries
quackjvm-core/src/main/java/io/quackjvm/core/measure/MeasureQuery.java
CQEngine persistence
- CQEngine database
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBDatabase.java - Object persistence
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBPersistence.java - Indexed collection
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/persistence/DuckDBIndexedCollection.java - DuckDB indexes
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/index/DuckDBIndex.java - Query pushdown
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/PushedDownQuery.java - Join translation
quackjvm-cqengine/src/main/java/io/quackjvm/cqengine/internal/ForeignQueryTranslator.java
Metrics dashboard
- Metrics registry
quackjvm-core/src/main/java/io/quackjvm/core/metrics/QuackMetrics.java - Query profiles
quackjvm-core/src/main/java/io/quackjvm/core/metrics/QueryProfile.java - Dashboard server
quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/QuackDashboard.java - Metrics sampler
quackjvm-dashboard/src/main/java/io/quackjvm/dashboard/Sampler.java - Live dashboard
quackjvm-dashboard/src/main/resources/io/quackjvm/dashboard/app.js
Other components
- Java application
- DuckDB
- CQEngine client
- Browser user
Connections 25
- Java application → Columnar layout: maps objects
- Java application → Table writer: writes batches
- Java application → Typed SQL rows: submits SQL
- Columnar layout → Table writer: provides columns
- Table writer → DuckDB: loads tables
- Typed SQL rows → DuckDB: executes SQL
- Typed SQL rows → Arrow batches: reads batches
- SQL query stream → DuckDB: executes query
- Connection pool → DuckDB: opens connections
- Java application → Materialization: precomputes queries
- Java application → Measure queries: builds measure SQL
- Measure queries → Typed SQL rows: runs SQL
- CQEngine client → CQEngine database: creates collections
- CQEngine database → Object persistence: configures storage
- Object persistence → Indexed collection: backs collection
- Indexed collection → DuckDB indexes: maintains indexes
- DuckDB indexes → DuckDB: stores and retrieves
- Query pushdown → DuckDB: executes translated query
- Query pushdown → Join translation: translates joins
- CQEngine database → Metrics registry: exposes metrics
- Metrics registry → Dashboard server: supplies observations
- Dashboard server → Metrics sampler: samples metrics
- Dashboard server → Query profiles: records profiles
- Browser user → Live dashboard: views dashboard
- Live dashboard → Dashboard server: polls state