- Category
- Developer Tools
- Rank
- No. 1216Tools index
Previous survey · No. 1165 ·
- Pricing
- Open Source
- Type
- TOOL
- Use case
- Data Processing
- GitHub
- 219 stars
- Latest release
- v0.0.31
- Date
About
Graphene is an open-source toolkit that lets a coding agent do data analysis. It provides a semantic layer with composable metric macros queried through SQL, and MDX-like files that combine Markdown, inline SQL and HTML components for dashboards. It connects to popular data warehouses or local DuckDB, so agents can build reports and change pipelines and dashboards in one PR.
What it does
Graphene gives an AI coding agent a text-only way to do business intelligence work. You describe warehouse tables once in an extended SQL dialect, declaring how they join and naming reusable metrics such as revenue or profit. Queries then call those metrics by name and follow joins with a dot, and Graphene expands them into plain SQL for your database. Reports are Markdown pages with embedded queries and chart tags, rendered by a local server. Everything is files in your repository, driven from one command-line tool that can check, run, and screenshot pages.
Why it's ranked here
The design is built around how an agent actually works: one command-line tool, documentation shipped inside the package as an agent skill, a check command that reports errors before anything runs, and a run command that screenshots a single chart so the agent can see its own output. The query layer does real work: declared join cardinality lets it guard against joins that silently double-count rows. It reaches six warehouses plus local DuckDB. Two facts temper that: the license is Elastic 2.0, not open source in the usual sense, and usage telemetry is on by default.
What's good
Join cardinality is declared as one or many, and the analyzer uses that to catch fan-out, the classic bug where joining users to their orders inflates a sum. Metrics compose, so profit can be defined as revenue minus cost and stays consistent everywhere it is used. Formatting hints such as currency, ratio, and time grain travel with the field, so charts format numbers correctly without per-chart work. The setup guide is written for an agent to follow and tells it to ask rather than guess credentials, to use read-only database users, and to keep secrets out of chat.
Tradeoffs
The Elastic License 2.0 allows internal use free of charge but forbids offering the software to others as a hosted service, and building a commercial product on it means contacting the vendor. Telemetry is sent by default: command name, a hashed project identity, detected agent, platform, flags and timing. It can be turned off with an environment variable or a config setting. Modeled joins are always left outer joins, and only simple equality conditions are supported. Some commands, including export and the eval readers, require the hosted Graphene Cloud service. Without git and a coding agent, the open project offers no point-and-click interface.
How to use it well
Fit it to a team that already keeps analytics code in a repository, such as next to a dbt project, and wants an agent to answer data questions and maintain dashboards through pull requests. Spend the first effort on the models: declare joins from both sides, define metrics once, and add comments, since they become descriptions the agent reads. Turn telemetry off up front if your policy requires it. It does not replace a self-serve tool for colleagues who will not touch git; that need is what the hosted cloud product targets.
Technical notes+
TypeScript monorepo; the published package is @graphenedata/cli (cli/package.json, Elastic-2.0, Node >=20) with database drivers for DuckDB, Postgres, Snowflake, BigQuery, ClickHouse and Athena declared as optional peerDependencies, plus playwright-core for headless page screenshots and echarts/svelte/mdsvex for rendering. cli/cli.ts registers compile, run, export, list, evals, reviews, schema, serve, stop and check via commander; run on a Markdown page analyzes it first and only opens a browser when diagnostics are empty, while export, evals and reviews call the Cloud API through authenticatedFetch. lang/core.ts loadWorkspace globs gsql and md files and ignores readme, agents and claude markdown by default. lang/analyze.ts is a two-phase analyzer over a Lezer parse tree: collect tables, extends and joins, then resolve each query recursively, adding implicit joins for dotted paths, detecting cycles in computed columns and views, and emitting dialect-specific quoting. cli/telemetry.ts posts one event per command to app.graphenedata.com with a 500 ms abort, a random install id persisted under node_modules, a sha256 project hash that excludes credentials, and agent detection from environment markers; GRAPHENE_TELEMETRY_DISABLED=1 or telemetry: false in config disables it. docs/best-practices.md instructs agents to avoid every non-Graphene visualization tool inside a Graphene project.
Observed
- License
- Elastic License 2.0 (source-available; no hosted or managed service offering to third parties)
- Language
- TypeScript
- Packaging
- npm package @graphenedata/cli exposing a graphene command
- Interface
- Command-line tool plus a local dev server that renders Markdown pages
- Data sources
- Snowflake, BigQuery, ClickHouse, Postgres, MotherDuck, Athena, local DuckDB
- Runtime
- Node 20 or later for the CLI package
- Telemetry
- On by default; disabled with GRAPHENE_TELEMETRY_DISABLED=1 or a config flag
- Join model
- Modeled joins are left outer only, with equality predicates only
- Documentation
- Ships inside the npm package as an agent skill
- Test runner
- Vitest configured at the repository root
Read from readme.md, package.json, cli/LICENSE.md, cli/package.json, cli/cli.ts, docs/setup.md, docs/references/graphene-sql.md, docs/references/modeling.md, lang/core.ts, lang/analyze.ts, cli/telemetry.ts, docs/best-practices.md.
Tags
Tech Stack
Comments (0)
No comments yet
Editorially curated, with community endorsements as a secondary signal. Corrections welcome.