SuperSonic Documentation

SuperSonic unifies Chat BI (LLM-powered natural language querying) and Headless BI (semantic layer-powered querying). It is designed to be extensible via Java SPI.

Core Components

• Knowledge Base: Periodically extracts schema information from semantic models to build dictionaries and indexes for schema mapping.
• Schema Mapper: Matches user query text against the knowledge base to identify references to metrics, dimensions, entities, or values.
• Semantic Parser: A hybrid of rule-based and LLM-based parsers that converts user queries into semantic query statements.
• Semantic Corrector: Validates and corrects semantic query statements using rule-based and LLM-based methods.
• Semantic Translator: Converts semantic query statements into executable SQL for physical data models.
• Chat Plugin: Allows extending functionality with third-party tools; an LLM selects the appropriate plugin based on descriptions and sample questions.
• Chat Memory: Stores historical query trajectories to facilitate few-shot prompting.

Key Features

• Chat BI Interface: For business users to query data via natural language.
• Headless BI Interface: For analytics engineers to build semantic data models (metrics, dimensions, tags).
• Data Access Control: Supports three-level control: dataset-level, column-level, and row-level.
• Advanced Chat UX: Includes input auto-completion, multi-turn conversation, and post-query recommendations.

SuperSonic is a next-generation BI platform that merges Chat BI (powered by LLMs) with Headless BI (powered by a semantic layer).

Key Features

• Chat BI Interface: For business users to query data using natural language.
• Headless BI Interface: For analytics engineers to build semantic models.
• Semantic Layer: Defines metrics, dimensions, entities, and tags to reduce LLM hallucinations and complexity.
• Advanced Chat Features: Supports text input suggestions, multi-turn conversations, and follow-up question recommendations.
• Three-level Permission Control: Dataset-level, column-level, and row-level security.

Extensible Components

SuperSonic uses the Java SPI mechanism to allow customization of its core components:

• Knowledge Base: Extracts schema information to build dictionaries and indices.
• Schema Mapper: Matches natural language to the knowledge base.
• Semantic Parser: Extracts semantic information from queries to generate S2SQL.
• Semantic Corrector: Validates and optimizes semantic queries.
• Semantic Translator: Translates semantic queries into executable SQL.
• Chat Plugin: Extends functionality via third-party tools.
• Chat Memory: Encapsulates query history for few-shot prompting.

Use the benchmark.py script to perform automated batch testing of single-turn Q&A dialogues. This is intended for testing a specific model's performance against business questions during product launch phases.

Prerequisites

• Python Version: Requires Python 3.8 (3.8.5 verified).
• Dependencies: Install required packages using:

  pip install -r requirements.txt

• Environment: It is recommended to run this in a development environment. If running in production, avoid peak usage hours.

1. Prepare Test Data

Create a test_data.csv file with a question header. Place this file in the benchmark/data directory.

Example test_data.csv content:

question
各BG期间在职、入职、离职人员的平均薪资是多少？
各BG期间入职且仍在职的人数有多少？

2. Execute the Benchmark

Run the script using the following command structure:

python benchmark.py -u <URL> -a <AGENTID> -c <CHATID> -f <FILEPATH> -p <USERNAME>

3. View Results

Currently, results must be queried directly from the database. Use the following SQL patterns to inspect the parsed information and query results:

Check SQL parsing results:

select question_id,chat_id,create_time,query_text,
       JSON_EXTRACT(parse_info,'$.sqlInfo.s2SQL') as s2sql,
       JSON_EXTRACT(parse_info,'$.sqlInfo.correctS2SQL') as correctS2SQL,
       JSON_EXTRACT(parse_info,'$.sqlInfo.querySQL') as querySQL,
       '请标记正确的SQL' as correctSQL,
       '请标记生成SQL是否正确' as isOk,
       '请分类不正确的原因' as reason
from s2_chat_parse scp where user_name = 'zhaodongsheng' and chat_id = '141';

Check query execution results:

select question_id,chat_id,create_time,query_text,
       JSON_EXTRACT(query_result,'$.querySql') as querySql,
       JSON_EXTRACT(query_result,'$.queryResults') as queryResults
from s2_chat_query where user_name = 'zhaodongsheng' and chat_id = '141' and query_state = 1;

python benchmark.py -u https://chatdata-dev.test.com -a 3 -c 35 -f data/shuce.csv -p zds