SuperSonic: A Chat BI and Headless BI Platform from Tencent Music

What SuperSonic Actually Solves (and for Whom)

The README frames the problem directly: Text2SQL works in demos but its reliability "falls short for large-scale real-world applications." SuperSonic's answer is to stop asking the LLM to generate the whole SQL statement. Instead, a semantic layer holds the definitions of metrics, dimensions and tags, and the LLM only needs to map a natural language question onto those definitions. The project calls the two halves Chat BI and Headless BI, and the README states the unification means Chat BI "has access to the same curated and governed semantic data models as traditional BI."

The intended audience is split in two. Business users get a chat box and a chart. Analytics engineers get a headless interface where they define the semantic models. If your organisation has neither a person who will maintain metric definitions nor a business user who wants to type questions instead of clicking a dashboard, the platform's two halves both go unused. The README is explicit that the semantic models are a prerequisite, not an optional layer: "the only thing necessary is to build logical semantic models."

The Pipeline: Knowledge Base, Schema Mapper, Parser, Corrector, Translator

The README lists six extensible components, and the order matters because it shows where the LLM sits. A Knowledge Base periodically extracts schema information from the semantic models and builds a dictionary and index. A Schema Mapper then "matches the query text against the knowledge base" to find references to metrics, dimensions, entities and values. Only after that does the Semantic Parser produce a semantic query statement, using a combination of rule-based and LLM-based parsers.

A Semantic Corrector checks the statement and fixes it, again mixing rules with LLM calls. The Semantic Translator then converts the semantic statement into SQL against the physical data models. Two further components sit outside the main chain: a Chat Plugin lets an LLM pick among configured third-party tools by description and sample question, and Chat Memory stores historical query trajectories for few-shot prompting.

The design choice worth noting is that advanced SQL syntax (joins, formulas) is generated by the semantic layer, not the model. The README states this is deliberate, to "reduce complexity" for the LLM. That is a real architectural commitment: it means the quality ceiling of your answers depends more on how well your semantic models are built than on which model you plug in. A weak semantic model will not be rescued by a stronger LLM.

Installing SuperSonic with docker-compose and Running a First Query

The README gives two paths. The fastest is Docker. Install Docker and docker-compose, then fetch the compose file and bring the stack up.

wget https://raw.githubusercontent.com/tencentmusic/supersonic/master/docker/docker-compose.yml
docker-compose up -d

After that, the README says to open a browser at http://localhost:9080 to start exploring. The repository also ships sample semantic models and chat conversations, so you should land on a working demo rather than an empty project.

If you prefer to run the Java service directly, download the latest prebuilt binary from the release page and start the daemon script:

assembly/bin/supersonic-daemon.sh start

The same http://localhost:9080 address is the entry point. There is also an online playground at http://117.72.46.148:9080, but the README asks visitors not to modify system configurations and notes the instance is reset regularly each weekend, so treat it as a demo and not a place to build anything.

What the README does not give you is a list of required environment variables, a supported database matrix for the semantic layer, or a rollback procedure. The compose file is referenced by URL only; its contents are not reproduced in the README.

Where SuperSonic Falls Short

The most visible limitation is release cadence. The most recent tagged release listed for the repository is v0.9.8 from 2024-11-01, while the last push to master was on 2026-09-08. That gap means the binary you download from the release page is not the code in the repository, and anyone building from source is working with unreleased changes. The README does not document an upgrade path between versions, and the CHANGELOG.md file exists at the repository root but its contents are not reproduced in the README.

A second limitation is operational. The platform depends on a Knowledge Base that "extracts schema information periodically" from semantic models. That is a synchronisation step with its own failure mode: if the extraction lags behind a model change, the Schema Mapper will resolve user terms against stale definitions, and the resulting query may be valid SQL that answers the wrong question. The README does not describe how to force a refresh or how to observe that the index is out of date.

A third is scope. SuperSonic is a Java application with a semantic layer, a chat interface and a web app in the repository. If your team has no Java engineers and no appetite for reading source to answer configuration questions, the README's pointer to the external Docs site is the only guidance you get. The README itself does not cover deployment topologies, authentication setup beyond the mention of three-level access control, or capacity planning.

SuperSonic Compared with a Plain Text2SQL Pipeline

The obvious alternative is the thing SuperSonic was built to replace: sending a schema dump and a user question straight to an LLM and executing whatever SQL comes back. The difference in approach is where correctness is enforced. In a plain Text2SQL pipeline, the model produces the join and the formula, and you validate the output by inspecting it. In SuperSonic, the model produces a semantic query statement against named metrics and dimensions, and the Semantic Translator produces the join and the formula deterministically.

That shifts the failure surface. A plain pipeline fails by generating plausible SQL that runs and returns a subtly wrong number. SuperSonic fails earlier, when the Schema Mapper cannot find a metric matching the user's phrasing, or when the Corrector rejects a statement. The first failure is silent; the second is visible. For a business user typing a question into a chat box, visible failure is better, but it also means the platform will refuse questions that a raw LLM would have attempted.

The trade-off is setup cost. A plain pipeline needs a database connection and a prompt. SuperSonic needs someone to build logical semantic models first, which the README treats as the entry condition for the whole product. If your metric definitions live in people's heads and not in a model, SuperSonic has nothing to map against.

Maintenance, Releases and the Licence Question

The repository is not archived and the last push was on 2026-09-08, which is recent. That said, the release history in the README tops out at v0.9.8 on 2024-11-01, so the project publishes tags far less often than it commits. Plan for source builds if you want current behaviour, and pin the docker-compose.yml you fetched rather than re-downloading it on every deploy.

The licence is recorded as NOASSERTION in the repository metadata, which means GitHub could not match the LICENSE file to a known licence identifier. The LICENSE file is present at the repository root. Before you ship anything built on SuperSonic, read that file directly and have whoever handles licensing at your organisation classify it. The README makes no statement about commercial use, redistribution or attribution, so there is nothing in the documentation to rely on.

Upgrade cost is the other unknown. With no documented migration path between v0.9.4, v0.9.6 and v0.9.8, and with master running well ahead of the last tag, the practical approach is to treat each upgrade as a fresh deployment against a copy of your semantic models and compare query results before cutting over.

Editorial conclusion

SuperSonic is worth a look if you are an analytics engineer or platform team willing to read Java source and build semantic models yourself, and if you already run the databases its semantic layer supports. It is the wrong tool if you need a maintained, documented release cadence or a hosted service with support. Before adopting, verify three things: the current master branch builds from source, the semantic models in headless/ cover the joins your metrics need, and the docker-compose.yml at docker/docker-compose.yml matches the version you intend to run.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. tencentmusic/supersonic on GitHub