### Get All Semantic Domains with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This GET request retrieves a list of all available semantic domains within the system. It's useful for an overview of the domain structure.

```bash
curl -X GET http://localhost:9080/api/semantic/domain/getDomainList
```

--------------------------------

### Get All Datasets for a Domain with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This GET request retrieves a list of all semantic datasets associated with a specific domain, identified by its `domainId`. It's useful for listing datasets within a particular organizational unit.

```bash
curl -X GET http://localhost:9080/api/semantic/dataSet/getDataSetList?domainId=1
```

--------------------------------

### Get All Users

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves a list of all users in the system. This endpoint does not require specific authentication beyond user privileges. Returns an array of user objects, each containing name, display name, email, and admin status.

```bash
curl -X GET http://localhost:9080/api/auth/user/getUserList
```

--------------------------------

### Get Multiple Semantic Domains by IDs with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This GET request allows fetching multiple semantic domains by providing a comma-separated list of their IDs. This is efficient for retrieving specific domains when their IDs are known.

```bash
curl -X GET http://localhost:9080/api/semantic/domain/getDomainListByIds/1,2,3
```

--------------------------------

### Get Company Address and Name with Min Revenue Proportion

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query selects the headquarter address and company name, along with the minimum revenue proportion, for each company. It joins the company_revenue and company tables and groups the results by company_id.

```sql
SELECT T2.headquarter_address, T2.company_name, min(T1.revenue_proportion) FROM company_revenue AS T1 JOIN company AS T2 ON T1.company_id = T2.company_id GROUP BY T1.company_id	internet
```

--------------------------------

### Get User Tokens

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves all API tokens associated with the current user. This endpoint requires authentication. Returns a list of token objects.

```bash
curl -X GET http://localhost:9080/api/auth/user/getUserTokens
```

--------------------------------

### Get Semantic Dataset Details with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This GET request retrieves the detailed information for a specific semantic dataset, identified by its ID. It provides comprehensive details about the dataset's configuration.

```bash
curl -X GET http://localhost:9080/api/semantic/dataSet/10
```

--------------------------------

### Get Company Address and Name with Sum Revenue Proportion

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query retrieves the headquarter address and company name, along with the sum of revenue proportion, for each company. It joins the company_revenue and company tables and groups the results by company_id.

```sql
SELECT T2.headquarter_address, T2.company_name, sum(T1.revenue_proportion) FROM company_revenue AS T1 JOIN company AS T2 ON T1.company_id = T2.company_id GROUP BY T1.company_id	internet
```

--------------------------------

### Get Semantic Domain Details with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This GET request retrieves the details of a specific semantic domain identified by its ID. It's used to fetch all information associated with a particular domain.

```bash
curl -X GET http://localhost:9080/api/semantic/domain/getDomain/1
```

--------------------------------

### Get Brand Name and Legal Representative with Minimum Revenue

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query finds the minimum revenue for each brand, displaying the brand name and legal representative. It joins the company_brand_revenue and brand tables on brand_id and groups the results by brand_id.

```sql
SELECT T2.legal_representative, T2.brand_name, min(T1.revenue) FROM company_brand_revenue AS T1 JOIN brand AS T2 ON T1.brand_id = T2.brand_id GROUP BY T1.brand_id	internet
```

--------------------------------

### Get Current User Info

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves the information of the currently authenticated user. Requires a Bearer token in the Authorization header. Returns user details including name, display name, email, and admin status.

```bash
curl -X GET http://localhost:9080/api/auth/user/getCurrentUser \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

--------------------------------

### Get Company Address and Name with Max Revenue Proportion

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query retrieves the headquarter address and company name, along with the maximum revenue proportion, for each company. It joins the company_revenue and company tables and groups the results by company_id.

```sql
SELECT T2.headquarter_address, T2.company_name, max(T1.revenue_proportion) FROM company_revenue AS T1 JOIN company AS T2 ON T1.company_id = T2.company_id GROUP BY T1.company_id	internet
```

--------------------------------

### Retrieve Company and Brand Revenue Information

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

These SQL queries retrieve company and brand details along with revenue proportions from the 'company_revenue', 'brand', and 'company' tables. They demonstrate basic JOIN operations to link related data across these entities. No specific filtering or aggregation is applied in these examples.

```sql
SELECT T3.company_name, T3.annual_turnover, T2.brand_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id	internet
```

```sql
SELECT T3.company_name, T2.brand_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id	internet
```

```sql
SELECT T3.company_name, T2.brand_name, T2.legal_representative, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id	internet
```

```sql
SELECT T3.company_name, T3.headquarter_address, T2.brand_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id	internet
```

--------------------------------

### Get Company Address and Name with Average Revenue Proportion

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query selects the headquarter address and company name, along with the average revenue proportion, for each company. It joins the company_revenue and company tables and groups the results by company_id.

```sql
SELECT T2.headquarter_address, T2.company_name, avg(T1.revenue_proportion) FROM company_revenue AS T1 JOIN company AS T2 ON T1.company_id = T2.company_id GROUP BY T1.company_id	internet
```

--------------------------------

### Get Brand Name and Legal Representative with Sum Revenue

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query calculates the sum of revenue for each brand, displaying the brand name and legal representative. It joins the company_brand_revenue and brand tables on brand_id and groups the results by brand_id.

```sql
SELECT T2.legal_representative, T2.brand_name, sum(T1.revenue) FROM company_brand_revenue AS T1 JOIN brand AS T2 ON T1.brand_id = T2.brand_id GROUP BY T1.brand_id	internet
```

--------------------------------

### Create a Semantic Domain with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This API call demonstrates how to create a new semantic domain, which serves as a logical container for organizing datasets, metrics, and dimensions. It requires parameters like name, business name, parent ID, status, description, and lists of administrators and viewers.

```bash
curl -X POST http://localhost:9080/api/semantic/domain/createDomain \
  -H "Content-Type: application/json" \
  -d '{
    "name": "E-commerce Analytics",
    "bizName": "ecommerce",
    "parentId": 0,
    "status": 1,
    "description": "Domain for e-commerce data analysis",
    "admins": ["admin", "data_engineer"],
    "viewers": ["analyst", "business_user"]
  }'
```

--------------------------------

### Register New User with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This POST request is used to register a new user in the system. It requires the user's name, display name, password, and email address. This is the first step for new users to gain access.

```bash
curl -X POST http://localhost:9080/api/auth/user/register \
  -H "Content-Type: application/json" \
  -d '{
    "name": "analyst",
    "displayName": "Data Analyst",
    "password": "secure_password",
    "email": "analyst@company.com"
  }'
```

--------------------------------

### Create a Semantic Dataset with Supersonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This POST request is used to create a new semantic dataset, which defines data models for queries. It requires details such as name, business name, domain ID, description, status, data source ID, query type, the SQL query itself, and lists of administrators and viewers.

```bash
curl -X POST http://localhost:9080/api/semantic/dataSet \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Dataset",
    "bizName": "sales_data",
    "domainId": 1,
    "description": "Dataset for sales transactions",
    "status": 1,
    "dataSourceId": 5,
    "queryType": "SQL_QUERY",
    "sqlQuery": "SELECT * FROM fact_sales",
    "admins": ["admin"],
    "viewers": ["analyst"]
  }'
```

--------------------------------

### Analyze Company and Brand Relationships with Ordering and Limits

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

These SQL queries explore relationships between companies and brands, retrieving specific details like brand name, legal representative, and revenue proportion. They utilize joins across `company_revenue`, `brand`, and `company` tables, and apply ordering based on performance metrics (profit proportion, count) and limits for top results. These are useful for identifying top-performing brands or companies.

```sql
SELECT T2.brand_name, T2.legal_representative, avg(T1.revenue_proportion) FROM company_revenue AS T1 JOIN brand AS T2 ON T1.brand_id = T2.brand_id GROUP BY T1.brand_id ORDER BY avg(T1.profit_proportion) DESC LIMIT 1
```

```sql
SELECT T2.brand_name, T2.legal_representative, sum(T1.revenue_proportion) FROM company_revenue AS T1 JOIN brand AS T2 ON T1.brand_id = T2.brand_id GROUP BY T1.brand_id ORDER BY count(*) DESC LIMIT 3
```

```sql
SELECT T3.company_name, T2.brand_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id ORDER BY T1.profit_proportion ASC
```

```sql
SELECT T2.brand_name, T3.company_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id ORDER BY T1.expenditure_proportion ASC LIMIT 3
```

```sql
SELECT T2.brand_name, T3.company_name, T1.revenue_proportion, T1.profit_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id ORDER BY T1.expenditure_proportion DESC LIMIT 3
```

```sql
SELECT T2.brand_name, T3.company_name, T1.revenue_proportion FROM company_revenue AS T1 JOIN brand AS T2 JOIN company AS T3 ON T1.brand_id = T2.brand_id AND T1.company_id = T3.company_id ORDER BY T1.profit_proportion DESC LIMIT 3
```

--------------------------------

### Manage AI Agents with SuperSonic API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

This section illustrates how to manage AI agents within the SuperSonic platform using its REST API. It covers creating new agents with specific configurations, updating existing agents, retrieving a list of all agents, and deleting agents. These agents define the scope and behavior for natural language interactions.

```bash
# Create a new agent
curl -X POST http://localhost:9080/api/chat/agent \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Sales Analytics Agent",
    "description": "Agent for sales data analysis",
    "enableSearch": true,
    "enableFeedback": true,
    "status": 1,
    "examples": [
      "What are the top selling products?",
      "Show me monthly revenue trends"
    ]
  }'

# Response
{
  "id": 1,
  "name": "Sales Analytics Agent",
  "description": "Agent for sales data analysis",
  "enableSearch": true,
  "enableFeedback": true,
  "status": 1,
  "createdAt": "2025-12-17T10:30:00",
  "createdBy": "admin"
}

# Update an existing agent
curl -X PUT http://localhost:9080/api/chat/agent \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "Sales Analytics Agent",
    "description": "Enhanced agent for sales data analysis",
    "enableSearch": true,
    "enableFeedback": true,
    "status": 1
  }'

# Get all agents
curl -X GET http://localhost:9080/api/chat/agent/getAgentList

# Delete an agent
curl -X DELETE http://localhost:9080/api/chat/agent/1
```

--------------------------------

### Get All Organization IDs for User

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves all organization IDs that a given user is associated with. The username is provided as a path parameter. Returns an array of strings, where each string is an organization ID.

```bash
curl -X GET http://localhost:9080/api/auth/user/getUserAllOrgId/analyst
```

--------------------------------

### User Authentication API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

APIs for user login and registration.

```APIDOC
## POST /api/auth/user/login

### Description
Authenticates a user and returns a JWT token upon successful login.

### Method
POST

### Endpoint
/api/auth/user/login

### Parameters
#### Request Body
- **name** (string) - Required - The username.
- **password** (string) - Required - The user's password.

### Request Example
```json
{
  "name": "admin",
  "password": "admin123"
}
```

### Response
#### Success Response (200)
- (string) - JWT token for authenticated user.

#### Response Example
```
"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiJhZG1pbiIsImlhdCI6MTYzOTc0MDAwMH0.abc123def456"
```

## POST /api/auth/user/register

### Description
Registers a new user account.

### Method
POST

### Endpoint
/api/auth/user/register

### Parameters
#### Request Body
- **name** (string) - Required - The username for the new account.
- **displayName** (string) - Required - The display name for the user.
- **password** (string) - Required - The password for the new account.
- **email** (string) - Required - The email address for the user.

### Request Example
```json
{
  "name": "analyst",
  "displayName": "Data Analyst",
  "password": "secure_password",
  "email": "analyst@company.com"
}
```

### Response
#### Success Response (200)
(Typically returns a success message or status code indicating successful registration)

```

--------------------------------

### Get Users by Organization

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves a list of users belonging to a specific organization. The organization ID is provided as a path parameter. Returns an array of user objects associated with that organization.

```bash
curl -X GET http://localhost:9080/api/auth/user/getUserByOrg/org_002
```

--------------------------------

### Get Organization Tree

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves the hierarchical structure of organizations. Returns a nested array of organization objects, including their IDs, names, parent IDs, and children. Useful for visualizing organizational relationships.

```bash
curl -X GET http://localhost:9080/api/auth/user/getOrganizationTree
```

--------------------------------

### Domain Management API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

APIs for creating, updating, retrieving, and deleting semantic domains.

```APIDOC
## POST /api/semantic/domain/createDomain

### Description
Creates a new semantic domain.

### Method
POST

### Endpoint
/api/semantic/domain/createDomain

### Parameters
#### Request Body
- **name** (string) - Required - The name of the domain.
- **bizName** (string) - Required - The business name of the domain.
- **parentId** (integer) - Optional - The parent domain ID.
- **status** (integer) - Required - The status of the domain (e.g., 1 for active).
- **description** (string) - Optional - A description of the domain.
- **admins** (array of strings) - Optional - A list of admin usernames.
- **viewers** (array of strings) - Optional - A list of viewer usernames.

### Request Example
```json
{
  "name": "E-commerce Analytics",
  "bizName": "ecommerce",
  "parentId": 0,
  "status": 1,
  "description": "Domain for e-commerce data analysis",
  "admins": ["admin", "data_engineer"],
  "viewers": ["analyst", "business_user"]
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created domain.
- **name** (string) - The name of the domain.
- **bizName** (string) - The business name of the domain.
- **parentId** (integer) - The parent domain ID.
- **status** (integer) - The status of the domain.
- **description** (string) - The description of the domain.
- **admins** (array of strings) - The list of admin usernames.
- **viewers** (array of strings) - The list of viewer usernames.
- **createdAt** (string) - The creation timestamp.
- **createdBy** (string) - The user who created the domain.

#### Response Example
```json
{
  "id": 1,
  "name": "E-commerce Analytics",
  "bizName": "ecommerce",
  "parentId": 0,
  "status": 1,
  "description": "Domain for e-commerce data analysis",
  "admins": ["admin", "data_engineer"],
  "viewers": ["analyst", "business_user"],
  "createdAt": "2025-12-17T10:00:00",
  "createdBy": "admin"
}
```

## POST /api/semantic/domain/updateDomain

### Description
Updates an existing semantic domain.

### Method
POST

### Endpoint
/api/semantic/domain/updateDomain

### Parameters
#### Request Body
- **id** (integer) - Required - The ID of the domain to update.
- **name** (string) - Optional - The new name of the domain.
- **description** (string) - Optional - The new description of the domain.
- **status** (integer) - Optional - The new status of the domain.

### Request Example
```json
{
  "id": 1,
  "name": "E-commerce Analytics",
  "description": "Updated domain for comprehensive e-commerce analysis",
  "status": 1
}
```

### Response
#### Success Response (200)
(Response body typically mirrors the created domain structure or indicates success)

## GET /api/semantic/domain/getDomain/{id}

### Description
Retrieves the details of a specific semantic domain by its ID.

### Method
GET

### Endpoint
/api/semantic/domain/getDomain/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the domain to retrieve.

### Response
#### Success Response (200)
(Response body mirrors the created domain structure)

## GET /api/semantic/domain/getDomainList

### Description
Retrieves a list of all semantic domains.

### Method
GET

### Endpoint
/api/semantic/domain/getDomainList

### Response
#### Success Response (200)
- (Array of domain objects, each mirroring the created domain structure)

## GET /api/semantic/domain/getDomainListByIds/{ids}

### Description
Retrieves a list of semantic domains by their IDs.

### Method
GET

### Endpoint
/api/semantic/domain/getDomainListByIds/{ids}

### Parameters
#### Path Parameters
- **ids** (string) - Required - A comma-separated string of domain IDs.

### Response
#### Success Response (200)
- (Array of domain objects, each mirroring the created domain structure)

## DELETE /api/semantic/domain/deleteDomain/{id}

### Description
Deletes a semantic domain by its ID.

### Method
DELETE

### Endpoint
/api/semantic/domain/deleteDomain/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the domain to delete.

### Response
#### Success Response (200)
(Typically returns a success message or status code)

```

--------------------------------

### Get Chat Query History - curl

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Retrieves the query history for a specific chat. Requires chatId, current page number, page size, and optionally userName. Returns a list of past queries.

```bash
curl -X POST http://localhost:9080/api/chat/manage/pageQueryInfo?chatId=100 \
  -H "Content-Type: application/json" \
  -d '{
    "current": 1,
    "pageSize": 10,
    "userName": "admin"
  }'
```

--------------------------------

### Semantic Layer - Metric Queries

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Query metrics and dimensions using the semantic layer API with structured requests.

```APIDOC
## POST /api/semantic/query/metric

### Description
Query metrics and dimensions using the semantic layer API.

### Method
POST

### Endpoint
/api/semantic/query/metric

### Parameters
#### Request Body
- **domainId** (integer) - Required - The ID of the domain to query.
- **metricIds** (array of integers) - Required - A list of metric IDs to retrieve.
- **dimensionIds** (array of integers) - Optional - A list of dimension IDs to group or filter by.
- **dateInfo** (object) - Optional - Information about the date range for the query.
  - **dateMode** (string) - Required - The mode for date filtering (e.g., "RECENT").
  - **unit** (integer) - Required - The number of units for the date range.
  - **period** (string) - Required - The period for the date range (e.g., "DAY", "MONTH").
- **filters** (array of objects) - Optional - Filters to apply to the query.
  - **bizName** (string) - Required - The business name of the filter field.
  - **operator** (string) - Required - The comparison operator (e.g., "=", ">", "IN").
  - **value** (any) - Required - The value to filter by.
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "domainId": 1,
  "metricIds": [101, 102],
  "dimensionIds": [201],
  "dateInfo": {
    "dateMode": "RECENT",
    "unit": 7,
    "period": "DAY"
  },
  "filters": [
    {
      "bizName": "department",
      "operator": "=",
      "value": "Sales"
    }
  ],
  "limit": 100
}
```

### Response
#### Success Response (200)
- **queryId** (string) - The ID of the query.
- **queryState** (string) - The state of the query (e.g., "SUCCESS").
- **queryTimeCost** (integer) - The time taken to execute the query in milliseconds.
- **columns** (array of objects) - Information about the returned columns.
  - **nameEn** (string) - The English name of the column.
  - **type** (string) - The type of the column (e.g., "DIMENSION", "METRIC").
- **resultList** (array of objects) - The query results.
- **sql** (string) - The generated SQL query.

#### Response Example
```json
{
  "queryId": "qry_12345",
  "queryState": "SUCCESS",
  "queryTimeCost": 856,
  "columns": [
    {"nameEn": "department", "type": "DIMENSION"},
    {"nameEn": "revenue", "type": "METRIC"},
    {"nameEn": "order_count", "type": "METRIC"}
  ],
  "resultList": [
    {
      "department": "Sales",
      "revenue": 1250000.50,
      "order_count": 3420
    }
  ],
  "sql": "SELECT department, SUM(revenue) as revenue, COUNT(order_id) as order_count FROM fact_orders WHERE department = 'Sales' AND date >= '2025-12-10' GROUP BY department"
}
```
```

```APIDOC
## POST /api/semantic/query/download/metric

### Description
Download metric data as CSV.

### Method
POST

### Endpoint
/api/semantic/query/download/metric

### Parameters
#### Request Body
- **domainId** (integer) - Required - The ID of the domain to query.
- **metricIds** (array of integers) - Required - A list of metric IDs to download.
- **dateInfo** (object) - Optional - Information about the date range for the query.
  - **dateMode** (string) - Required - The mode for date filtering (e.g., "RECENT").
  - **unit** (integer) - Required - The number of units for the date range.
  - **period** (string) - Required - The period for the date range (e.g., "DAY", "MONTH").

### Request Example
```json
{
  "domainId": 1,
  "metricIds": [101],
  "dateInfo": {
    "dateMode": "RECENT",
    "unit": 30,
    "period": "DAY"
  }
}
```

### Response
- **File Download** - The response will be a CSV file containing the requested metric data.
```

```APIDOC
## POST /api/semantic/query/downloadBatch/metric

### Description
Batch download multiple metrics as CSV files within a zip archive.

### Method
POST

### Endpoint
/api/semantic/query/downloadBatch/metric

### Parameters
#### Request Body
- **queries** (array of objects) - Required - A list of query objects to download.
  - **domainId** (integer) - Required - The ID of the domain for the metric.
  - **metricIds** (array of integers) - Required - A list of metric IDs to download.
  - **fileName** (string) - Required - The desired filename for the CSV file.

### Request Example
```json
{
  "queries": [
    {
      "domainId": 1,
      "metricIds": [101],
      "fileName": "revenue.csv"
    },
    {
      "domainId": 1,
      "metricIds": [102],
      "fileName": "orders.csv"
    }
  ]
}
```

### Response
- **File Download** - The response will be a zip archive containing the requested CSV files.
```

--------------------------------

### Dataset Management API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

APIs for creating, updating, retrieving, and deleting semantic datasets.

```APIDOC
## POST /api/semantic/dataSet

### Description
Creates a new semantic dataset.

### Method
POST

### Endpoint
/api/semantic/dataSet

### Parameters
#### Request Body
- **name** (string) - Required - The name of the dataset.
- **bizName** (string) - Required - The business name of the dataset.
- **domainId** (integer) - Required - The ID of the domain this dataset belongs to.
- **description** (string) - Optional - A description of the dataset.
- **status** (integer) - Required - The status of the dataset (e.g., 1 for active).
- **dataSourceId** (integer) - Required - The ID of the data source.
- **queryType** (string) - Required - The type of query (e.g., "SQL_QUERY").
- **sqlQuery** (string) - Required if `queryType` is "SQL_QUERY" - The SQL query defining the dataset.
- **admins** (array of strings) - Optional - A list of admin usernames.
- **viewers** (array of strings) - Optional - A list of viewer usernames.

### Request Example
```json
{
  "name": "Sales Dataset",
  "bizName": "sales_data",
  "domainId": 1,
  "description": "Dataset for sales transactions",
  "status": 1,
  "dataSourceId": 5,
  "queryType": "SQL_QUERY",
  "sqlQuery": "SELECT * FROM fact_sales",
  "admins": ["admin"],
  "viewers": ["analyst"]
}
```

### Response
#### Success Response (200)
- **id** (integer) - The ID of the created dataset.
- **name** (string) - The name of the dataset.
- **bizName** (string) - The business name of the dataset.
- **domainId** (integer) - The domain ID.
- **description** (string) - The description of the dataset.
- **status** (integer) - The status of the dataset.
- **dataSourceId** (integer) - The data source ID.
- **queryType** (string) - The query type.
- **createdAt** (string) - The creation timestamp.
- **createdBy** (string) - The user who created the dataset.

#### Response Example
```json
{
  "id": 10,
  "name": "Sales Dataset",
  "bizName": "sales_data",
  "domainId": 1,
  "description": "Dataset for sales transactions",
  "status": 1,
  "dataSourceId": 5,
  "queryType": "SQL_QUERY",
  "createdAt": "2025-12-17T11:00:00",
  "createdBy": "admin"
}
```

## PUT /api/semantic/dataSet

### Description
Updates an existing semantic dataset.

### Method
PUT

### Endpoint
/api/semantic/dataSet

### Parameters
#### Request Body
- **id** (integer) - Required - The ID of the dataset to update.
- **name** (string) - Optional - The new name of the dataset.
- **description** (string) - Optional - The new description of the dataset.
- **status** (integer) - Optional - The new status of the dataset.

### Request Example
```json
{
  "id": 10,
  "name": "Sales Dataset",
  "description": "Enhanced dataset for sales transactions with additional metrics",
  "status": 1
}
```

### Response
#### Success Response (200)
(Response body typically mirrors the updated dataset structure or indicates success)

## GET /api/semantic/dataSet/{id}

### Description
Retrieves the details of a specific semantic dataset by its ID.

### Method
GET

### Endpoint
/api/semantic/dataSet/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the dataset to retrieve.

### Response
#### Success Response (200)
(Response body mirrors the created dataset structure)

## GET /api/semantic/dataSet/getDataSetList?domainId={domainId}

### Description
Retrieves a list of all semantic datasets for a specific domain.

### Method
GET

### Endpoint
/api/semantic/dataSet/getDataSetList

### Parameters
#### Query Parameters
- **domainId** (integer) - Required - The ID of the domain to filter datasets by.

### Response
#### Success Response (200)
- (Array of dataset objects, each containing id, name, bizName, domainId, and status)

#### Response Example
```json
[
  {
    "id": 10,
    "name": "Sales Dataset",
    "bizName": "sales_data",
    "domainId": 1,
    "status": 1
  },
  {
    "id": 11,
    "name": "Marketing Dataset",
    "bizName": "marketing_data",
    "domainId": 1,
    "status": 1
  }
]
```

## DELETE /api/semantic/dataSet/{id}

### Description
Deletes a semantic dataset by its ID.

### Method
DELETE

### Endpoint
/api/semantic/dataSet/{id}

### Parameters
#### Path Parameters
- **id** (integer) - Required - The ID of the dataset to delete.

### Response
#### Success Response (200)
(Typically returns a success message or status code)

```

--------------------------------

### Semantic Layer - SQL Queries

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Execute raw SQL queries with validation and correction through the semantic layer.

```APIDOC
## POST /api/semantic/query/sql

### Description
Execute raw SQL queries through the semantic layer.

### Method
POST

### Endpoint
/api/semantic/query/sql

### Parameters
#### Request Body
- **sql** (string) - Required - The SQL query to execute.
- **dataSetId** (integer) - Optional - The ID of the dataset to associate the query with.

### Request Example
```json
{
  "sql": "SELECT department, SUM(revenue) FROM sales_data WHERE date >= '\''2025-01-01'\'' GROUP BY department",
  "dataSetId": 10
}
```

### Response
#### Success Response (200)
- **queryId** (string) - The ID of the query.
- **queryState** (string) - The state of the query (e.g., "SUCCESS").
- **queryTimeCost** (integer) - The time taken to execute the query in milliseconds.
- **resultList** (array of objects) - The query results.

#### Response Example
```json
{
  "queryId": "qry_sql_001",
  "queryState": "SUCCESS",
  "queryTimeCost": 678,
  "resultList": [
    {
      "department": "Sales",
      "revenue": 1250000.50
    },
    {
      "department": "Marketing",
      "revenue": 450000.00
    }
  ]
}
```
```

```APIDOC
## POST /api/semantic/query/validate

### Description
Validate a SQL query without executing it.

### Method
POST

### Endpoint
/api/semantic/query/validate

### Parameters
#### Request Body
- **sql** (string) - Required - The SQL query to validate.
- **dataSetId** (integer) - Optional - The ID of the dataset to associate the query with.

### Request Example
```json
{
  "sql": "SELECT * FROM sales_data WHERE invalid_column = 1",
  "dataSetId": 10
}
```

### Response
#### Success Response (200)
- **isValid** (boolean) - Indicates if the SQL query is valid.
- **message** (string) - A message providing details about validation, including errors if any.

#### Response Example
```json
{
  "isValid": false,
  "message": "Error: Column 'invalid_column' does not exist in dataset 10."
}
```
```

--------------------------------

### Semantic Layer - Dataset Queries

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Query data from semantic datasets with full control over dimensions, metrics, and filters.

```APIDOC
## POST /api/semantic/query/dataSet

### Description
Query data from a specified semantic dataset.

### Method
POST

### Endpoint
/api/semantic/query/dataSet

### Parameters
#### Request Body
- **dataSetId** (integer) - Required - The ID of the dataset to query.
- **metrics** (array of objects) - Required - A list of metrics to retrieve.
  - **name** (string) - Required - The name of the metric.
- **dimensions** (array of objects) - Optional - A list of dimensions to include in the results.
  - **name** (string) - Required - The name of the dimension.
- **filters** (array of objects) - Optional - Filters to apply to the query.
  - **name** (string) - Required - The name of the field to filter on.
  - **operator** (string) - Required - The comparison operator (e.g., "=", ">", "IN").
  - **value** (any) - Required - The value to filter by.
- **dateInfo** (object) - Optional - Information about the date range for the query.
  - **startDate** (string) - Required - The start date (YYYY-MM-DD).
  - **endDate** (string) - Required - The end date (YYYY-MM-DD).
- **aggregators** (array of objects) - Optional - Specifies columns for grouping.
  - **column** (string) - Required - The name of the column to group by.
  - **func** (string) - Required - The aggregation function (e.g., "GROUP_BY").
- **limit** (integer) - Optional - The maximum number of results to return.

### Request Example
```json
{
  "dataSetId": 10,
  "metrics": [
    {"name": "total_revenue"},
    {"name": "avg_order_value"}
  ],
  "dimensions": [
    {"name": "product_category"},
    {"name": "region"}
  ],
  "filters": [
    {
      "name": "product_category",
      "operator": "IN",
      "value": ["Electronics", "Clothing"]
    }
  ],
  "dateInfo": {
    "startDate": "2025-01-01",
    "endDate": "2025-12-31"
  },
  "aggregators": [
    {
      "column": "product_category",
      "func": "GROUP_BY"
    }
  ],
  "limit": 50
}
```

### Response
#### Success Response (200)
- **queryId** (string) - The ID of the query.
- **queryState** (string) - The state of the query (e.g., "SUCCESS").
- **queryTimeCost** (integer) - The time taken to execute the query in milliseconds.
- **columns** (array of objects) - Information about the returned columns.
  - **nameEn** (string) - The English name of the column.
  - **type** (string) - The type of the column (e.g., "DIMENSION", "METRIC").
- **resultList** (array of objects) - The query results.
- **sql** (string) - The generated SQL query.

#### Response Example
```json
{
  "queryId": "qry_67890",
  "queryState": "SUCCESS",
  "queryTimeCost": 1234,
  "columns": [
    {"nameEn": "product_category", "type": "DIMENSION"},
    {"nameEn": "region", "type": "DIMENSION"},
    {"nameEn": "total_revenue", "type": "METRIC"},
    {"nameEn": "avg_order_value", "type": "METRIC"}
  ],
  "resultList": [
    {
      "product_category": "Electronics",
      "region": "North",
      "total_revenue": 850000.00,
      "avg_order_value": 425.50
    },
    {
      "product_category": "Clothing",
      "region": "North",
      "total_revenue": 320000.00,
      "avg_order_value": 85.25
    }
  ],
  "sql": "SELECT product_category, region, SUM(revenue) as total_revenue, AVG(order_value) as avg_order_value FROM dataset_10 WHERE product_category IN ('Electronics', 'Clothing') AND date BETWEEN '2025-01-01' AND '2025-12-31' GROUP BY product_category, region LIMIT 50"
}
```
```

--------------------------------

### Get Brand Name and Legal Representative with Average Revenue

Source: https://github.com/tencentmusic/supersonic/blob/master/evaluation/data/gold_example_dusql.txt

This query calculates the average revenue for each brand, displaying the brand name and legal representative. It joins the company_brand_revenue and brand tables on brand_id and groups the results by brand_id.

```sql
SELECT T2.legal_representative, T2.brand_name, avg(T1.revenue) FROM company_brand_revenue AS T1 JOIN brand AS T2 ON T1.brand_id = T2.brand_id GROUP BY T1.brand_id	internet
```

--------------------------------

### User Authentication and Management API

Source: https://context7.com/tencentmusic/supersonic/llms.txt

Endpoints for managing user accounts, authentication, and generating API tokens.

```APIDOC
## GET /api/auth/user/getCurrentUser

### Description
Retrieves the currently logged-in user's information.

### Method
GET

### Endpoint
/api/auth/user/getCurrentUser

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://localhost:9080/api/auth/user/getCurrentUser \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

### Response
#### Success Response (200)
- **name** (string) - The username.
- **displayName** (string) - The user's display name.
- **email** (string) - The user's email address.
- **isAdmin** (integer) - Indicates if the user is an administrator (1 for true, 0 for false).

#### Response Example
```json
{
  "name": "admin",
  "displayName": "System Admin",
  "email": "admin@company.com",
  "isAdmin": 1
}
```
```

```APIDOC
## GET /api/auth/user/getUserList

### Description
Retrieves a list of all users in the system.

### Method
GET

### Endpoint
/api/auth/user/getUserList

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://localhost:9080/api/auth/user/getUserList
```

### Response
#### Success Response (200)
- An array of user objects, each containing:
  - **name** (string) - The username.
  - **displayName** (string) - The user's display name.
  - **email** (string) - The user's email address.
  - **isAdmin** (integer) - Indicates if the user is an administrator (1 for true, 0 for false).

#### Response Example
```json
[
  {
    "name": "admin",
    "displayName": "System Admin",
    "email": "admin@company.com",
    "isAdmin": 1
  },
  {
    "name": "analyst",
    "displayName": "Data Analyst",
    "email": "analyst@company.com",
    "isAdmin": 0
  }
]
```
```

```APIDOC
## POST /api/auth/user/resetPassword

### Description
Resets a user's password. Requires the current password and the new password.

### Method
POST

### Endpoint
/api/auth/user/resetPassword

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **password** (string) - Required - The user's current password.
- **newPassword** (string) - Required - The user's new password.

### Request Example
```json
{
  "password": "old_password",
  "newPassword": "new_secure_password"
}
```

### Response
#### Success Response (200)
(No specific response body documented, typically indicates success)

#### Response Example
(No example provided)
```

```APIDOC
## POST /api/auth/user/generateToken

### Description
Generates a new API token for integration purposes.

### Method
POST

### Endpoint
/api/auth/user/generateToken

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **name** (string) - Required - A descriptive name for the API token.
- **expireTime** (string) - Required - The expiration date and time for the token in ISO 8601 format (e.g., 'YYYY-MM-DDTHH:MM:SS').

### Request Example
```json
{
  "name": "API Token for Integration",
  "expireTime": "2026-12-31T23:59:59"
}
```

### Response
#### Success Response (200)
- **id** (integer) - The unique identifier for the generated token.
- **name** (string) - The name of the API token.
- **token** (string) - The generated API token.
- **expireTime** (string) - The expiration date and time of the token.
- **createdAt** (string) - The date and time when the token was created.

#### Response Example
```json
{
  "id": 1,
  "name": "API Token for Integration",
  "token": "sk_live_abc123def456...",
  "expireTime": "2026-12-31T23:59:59",
  "createdAt": "2025-12-17T12:00:00"
}
```
```

```APIDOC
## GET /api/auth/user/getUserTokens

### Description
Retrieves a list of all API tokens associated with the current user.

### Method
GET

### Endpoint
/api/auth/user/getUserTokens

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X GET http://localhost:9080/api/auth/user/getUserTokens
```

### Response
#### Success Response (200)
(Response body structure not specified in the provided text)

#### Response Example
(No example provided)
```

```APIDOC
## DELETE /api/auth/user/delete/{userId}

### Description
Deletes a user from the system. This action is typically restricted to administrators.

### Method
DELETE

### Endpoint
/api/auth/user/delete/{userId}

### Parameters
#### Path Parameters
- **userId** (string) - Required - The unique identifier of the user to delete.

#### Query Parameters
None

#### Request Body
None

### Request Example
```bash
curl -X DELETE http://localhost:9080/api/auth/user/delete/5
```

### Response
#### Success Response (200)
(No specific response body documented, typically indicates success)

#### Response Example
(No example provided)
```