SuperDB: unified analytics for JSON and relational data

SuperDB's unified data model

SuperDB addresses a specific problem in analytics: relational databases tend to require a defined schema, while document stores tend to force JSON through a separate access and query path. SuperDB places relational tables and JSON on the same footing. The README says that all handled data, including JSON, CSV, Parquet files, Arrow streams, and relational tables, is converted into super-structured data.

The important design decision is that there are no separate "JSON columns" and no second JSON query mode. A single runtime supports statically typed relational data and dynamically typed JSON values. Values remain strongly and dynamically typed, so a field can participate in typed computation while the surrounding data can still contain heterogeneous structures.

This model is aimed at data wrangling and exploratory analytics over large, mixed datasets. The README specifically positions SuperDB for exploring or processing "large eclectic data sets," as well as analytics and search use cases. The tradeoff is that this is not simply a conventional SQL engine with a JSON convenience type. It is a new analytics database whose query language and internal execution model are being refined.

SuperSQL processing flow

SuperDB extends SQL with pipe syntax and additional operators and shortcuts. Queries can begin with a source such as a URL, then pass values through `SELECT`, grouping, ordering, limiting, forks, joins, and value construction without leaving the SQL dialect. The runtime converts incoming data into super-structured data and evaluates it through one compute engine.

The README's GitHub Archive example shows the intended flow. It reads a compressed JSON source, computes the set of repositories touched by each user, groups records by user, orders by repository count, limits the result to five users, forks each selected user into a GitHub API request, and joins the API response with the original result. The final `VALUES` expression combines the two sides.

This is more than a syntax demonstration. The same query mechanism works across relational and semi-structured inputs, so a team can select fields from irregular JSON and join the result to API or file data. The README also links to schema inference through the `fuse` operator, but says ingestion keeps data in its natural form by default. That choice reduces the need to impose one schema on heterogeneous input before querying it.

SUP, BSUP, and CSUP storage formats

SuperDB extends JSON to define the Super, or SUP, format. Every JSON value is also valid SUP, while SUP adds typed and polymorphic support for values that do not fit one fixed record shape. Sequences do not need to conform to a single predefined schema.

The project also defines two storage-oriented representations. Super Binary, or BSUP, is described as an efficient binary representation of SUP, similar in purpose to Avro. Super Columnar, or CSUP, is the columnar representation, described as similar to Parquet. These formats matter because SuperDB's type model is not limited to text JSON. The runtime and storage layers can work with typed values and different physical layouts.

SuperDB can still read and write most common data formats, so adopting SUP does not mean abandoning existing files. The practical boundary is that format choice affects ingestion, storage, and downstream tooling. The repository and README do not document migration procedures, compatibility guarantees for every external format, or a rollback path from a database to original files.

Installing SuperDB and running a first query

The README directs users to the SuperDB installation documentation and describes SuperDB as a dependency-free binary. It does not include platform-specific installation commands, download URLs, or a complete first-run command, so those details should be taken from `https://superdb.org/getting-started/install.html` rather than inferred from the repository overview.

For a source checkout, the Makefile confirms that Go must be available and that the project targets Go 1.27 through `go.mod`. It also rejects unsupported 32-bit architectures. The repository defines a build target for the `super` command, and the JavaScript package runs that build through its `prepack` script.

Use the repository's build target when following a source-build workflow:

make build

The package metadata confirms the same build entry point:

{
  "scripts": {
    "prepack": "make build"
  }
}

A first useful query can be the README's GitHub Archive example, which reads remote JSON and joins it with API results:

FROM 'https://data.gharchive.org/2015-01-01-15.json.gz'
| SELECT union(repo.name) AS repos, actor.login AS user
  GROUP BY user
  ORDER BY len(repos) DESC
  LIMIT 5
| FORK
  ( FROM f'https://api.github.com/users/{user}'
    SELECT login AS user, created_at::time AS created_at )
  ( PASS )
| JOIN USING (user)
| VALUES {...left,repos:right.repos}

The README states that the local `super` command can access files, HTTP endpoints, and S3 paths without a storage engine. It does not specify the exact shell invocation for this query, so the installation documentation should supply that command before execution.

Local engine and developing database mode

SuperDB has two usage contexts documented in the README. The query engine can run locally without a storage engine by reading files, HTTP endpoints, or S3 paths through the `super` command. This is useful when the immediate requirement is data exploration or ad hoc processing and a persistent database is unnecessary.

The project also supports a database built on super-structured data through `super db` sub-commands. The README describes this as an available development mode, but it does not provide a complete configuration example, authentication model, deployment topology, or operational guide for that database. Based on the repository layout, database functionality is part of the Go codebase under `db/`, with service and CLI code elsewhere in the tree.

That distinction affects adoption. A file-oriented query workflow can be evaluated without first designing a service. A persistent installation raises different questions about backups, access control, upgrades, and recovery. The README does not document those operational details, so they should not be inferred from the existence of the database commands.

Compatibility, licensing, and maintenance considerations

SuperDB's long-term goal is Postgres compatibility and interoperability with existing SQL tooling. The README qualifies that goal by saying that SuperSQL is currently a moving target and that community input is needed to refine its syntax and semantics. That makes it unsuitable for teams that require exact Postgres behavior or stable query syntax across upgrades without checking the compatibility documentation.

The repository identifies Go 1.27 in `go.mod` and uses the module path `github.com/superdb/super`. Its `Makefile` exposes developer commands including `test-unit`, `test-system`, `test-generate`, `vet`, `fmt`, and `tidy`. The `test-system` and related targets also depend on `bin/rustfs`, whose Makefile target downloads a RustFS release. This indicates that a full development setup has more moving parts than a basic local binary query.

The repository's license field is listed as custom because GitHub cannot classify it. `LICENSE.md` exists, but the terms are not included in the README. License implications therefore cannot be assessed beyond noting that the project is not presented as a standard GitHub-classified license. The project is not archived, and its last push was on 2026-10-15. Recent releases include v0.3.0 on 2026-03-20, v0.2.0 on 2026-02-28, and v0.1.0 on 2026-01-30.

A genuine alternative is a conventional Postgres-compatible system paired with JSONB or a document-processing layer. That approach keeps familiar SQL tooling and explicit schema control, but it separates structured relational access from document exploration and may require schema inference or application-side handling for heterogeneous records. SuperDB instead uses one typed, polymorphic data model and one extended SQL engine. The choice is unified heterogeneous analytics versus compatibility and ecosystem familiarity.

Editorial conclusion

Adopt SuperDB when your workload combines irregular JSON exploration with relational-style analytics and you can tolerate an evolving SQL dialect. Do not choose it as a drop-in Postgres replacement without checking compatibility first. Verify the exact `super` installation path, the required Go version for source builds, and the SuperSQL features your existing queries depend on.

Frequently asked questions

Official sources

1. Issues
2. Project website
3. README
4. Releases
5. superdb/super on GitHub