OntiCards API Reference

About This Document

This document describes all APIs of the OntiCards system, covering database connection, data source management, AI-powered querying, data auditing, and related features.

Basic information:

• Base path: /console/api

• Session authentication: Flask-Login based session authentication (some endpoints require the @login_required decorator)

• API Key authentication: stateless API Key based authentication (for plugin endpoints and external calls)

• Authentication:

• Request format: JSON (Content-Type: application/json)

• Response format: JSON

Unified response format:

{
  "code": 200,
  "msg": "操作成功",
  "data": {}
}

Table of Contents

1. User Management Module

1. API Key Management Module

1. Data Source Management Module

1. Data Card Management Module

1. Data Discovery Module

1. AI Query Module

1. Data Audit Module

1. Changelog Module

1. Excel Field Extraction Module

1. Model Configuration Management Module

1. Query History Module

1. Monitoring Center Module

1. System Configuration Module

1. SSO Single Sign-On Module

1. Prompt Configuration Module

1. Business Glossary Management Module

1. Data Governance Module - Data Quality Check (Phase 1)

1. Data Governance Module - Remediation (Phase 2)

1. User Management Module

1.1 User Login

Description: Logs in a user and returns a JWT Token.

Method: POST

Path: /console/api/login

Authentication required: No

Request parameters:

Request example:

{
  "username": "admin",
  "password": "123456"
}

Response example:

{
  "code": 200,
  "message": "Login successful",
  "data": {
    "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
  }
}

Error response:

{
  "code": 400,
  "message": "Invalid username or password"
}

1.2 User Registration

Description: Registers a new user.

Method: PUT

Path: /console/api/login

Authentication required: No

Request parameters:

Request example:

{
  "username": "newuser",
  "password": "123456"
}

Response example:

{
  "code": 200,
  "message": "Registration successful"
}

1.3 Get Current User Information

Description: Gets the detailed information of the currently logged-in user.

Method: GET

Path: /console/api/user

Authentication required: Yes

Request parameters: None

Response example:

{
  "code": 200,
  "message": "获取用户信息成功",
  "data": {
    "id": "uuid-string",
    "username": "admin",
    "nickname": "管理员",
    "avatar": "http://example.com/avatar.jpg",
    "user_group_name": "管理员组",
    "role": "admin",
    "login_at": "2025-01-20T10:30:00"
  }
}

1.4 Update Current User Information

Description: Updates the nickname and avatar of the currently logged-in user.

Method: PUT

Path: /console/api/user

Authentication required: Yes

Request parameters:

Request example:

{
  "nickname": "新昵称",
  "avatar": "http://example.com/new_avatar.jpg"
}

Response example:

{
  "code": 200,
  "message": "Current user updated successfully"
}

1.5 Logout

Description: Logs out the current user.

Method: GET

Path: /console/api/logout

Authentication required: Yes

Request parameters: None

Response example:

{
  "code": 200,
  "message": "Logged out successfully"
}

1.6 Change Password

Description: Changes the user's password.

Method: POST

Path: /console/api/change_password

Authentication required: Yes

Request parameters:

Request example:

{
  "id": "uuid-string",
  "old_password": "old123",
  "new_password": "new123"
}

Response example:

{
  "code": 200,
  "message": "Password changed successfully"
}

1.7 Get All Users

Description: Gets the list of all users in the system (administrator permission).

Method: GET

Path: /console/api/users/all

Authentication required: Yes

Permission required: Administrator

Request parameters: None

Response example:

{
  "code": 200,
  "message": "success",
  "data": [
    {
      "id": "uuid-string",
      "username": "admin",
      "nickname": "管理员",
      "avatar": "http://example.com/avatar.jpg",
      "status": "normal",
      "default_lang": "zh-CN",
      "user_group_name": "管理员组",
      "role": "admin",
      "login_at": "2025-01-20T10:30:00"
    }
  ]
}

1.8 User Management (Create/Update/Delete)

Description: Lets administrators create, update, and delete users.

Method: POST / PUT / DELETE

Path: /console/api/users/manage

Authentication required: Yes

Permission required: Administrator

1.8.1 Create User (POST)

Request parameters:

Request example:

{
  "username": "newuser",
  "nickname": "新用户",
  "email": "user@example.com",
  "password": "123456",
  "user_group_id": "uuid-string",
  "role": "normal"
}

1.8.2 Update User (PUT)

Request parameters:

Request example:

{
  "id": "uuid-string",
  "nickname": "更新后的昵称",
  "role": "admin"
}

1.8.3 Delete User (DELETE)

Request parameters:

Request example:

{
  "id": "uuid-string"
}

Response example:

{
  "code": 200,
  "message": "用户删除成功"
}

2. API Key Management Module

2.1 API Key Authentication

API Key authentication method:

An API Key is a stateless authentication method intended for plugin endpoints, external system calls, and similar scenarios. With an API Key, no login session is needed — just include a valid API Key in the request header.

Supported authentication header formats:

1. Authorization header (recommended)

   Authorization: <api_key>

1. Authorization header (Bearer format)

   Authorization: Bearer <api_key>

1. X-API-Key header

   X-API-Key: <api_key>

API Key validation rules:

• The API Key must be in the active state

• The API Key must not be expired (expires_at is null or still in the future)

• The user associated with the API Key must exist and be valid

• After every successful call, the system updates the last_used_at field

Error responses:

• 401 Unauthorized: API Key missing or invalid

• 403 Forbidden: API Key disabled or expired

2.2 Query API Keys

Description: Queries the API Key list or a single API Key's details.

Method: GET

Path: /console/api/api_keys

Authentication required: Yes

Request parameters (Query):

Request example (query the list):

GET /console/api/api_keys

Request example (query a single key):

GET /console/api/api_keys?id=550e8400-e29b-41d4-a716-446655440000

Response example (list):

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "user_id": "660e8400-e29b-41d4-a716-446655440001",
      "name": "生产环境API Key",
      "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
      "status": "active",
      "expires_at": "2025-12-31T23:59:59+00:00",
      "last_used_at": "2025-12-29T10:30:00+00:00",
      "created_at": "2025-01-01T00:00:00+00:00",
      "updated_at": "2025-01-01T00:00:00+00:00"
    }
  ]
}

Response example (single):

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "user_id": "660e8400-e29b-41d4-a716-446655440001",
    "name": "生产环境API Key",
    "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx",
    "status": "active",
    "expires_at": "2025-12-31T23:59:59+00:00",
    "last_used_at": "2025-12-29T10:30:00+00:00",
    "created_at": "2025-01-01T00:00:00+00:00",
    "updated_at": "2025-01-01T00:00:00+00:00"
  }
}

Response field description:

• id: Unique identifier of the API Key

• user_id: ID of the owning user (used for data isolation)

• name: API Key name/note

• api_key: API Key plaintext (returned only at creation and in queries)

• status: Status (active=enabled, disabled=disabled)

• expires_at: Expiry time (ISO 8601 format; null means never expires)

• last_used_at: Last time the key was used

• created_at: Creation time

• updated_at: Update time

2.3 Create an API Key

Description: Creates a new API Key for a specified user.

Method: POST

Path: /console/api/api_keys

Authentication required: Yes

Request parameters:

Request example (auto-generated API Key):

{
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "生产环境API Key",
  "expires_at": "2025-12-31T23:59:59+00:00"
}

Request example (custom API Key):

{
  "user_id": "660e8400-e29b-41d4-a716-446655440001",
  "name": "测试环境API Key",
  "api_key": "ak_custom_key_12345678901234567890",
  "expires_at": null
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "api_key": "ak_xxxxxxxxxxxxxxxxxxxxxxxx"
  }
}

Notes:

1. If the api_key parameter is not passed, the system generates a random 32-character string prefixed with ak_

1. After creation, the api_key plaintext is returned only once; subsequent queries do not return the full plaintext

1. An empty or null expires_at means the key never expires

1. On creation, status defaults to active

2.4 Update an API Key

Description: Updates an API Key's name, status, or expiry time.

Method: PUT

Path: /console/api/api_keys

Authentication required: Yes

Request parameters:

Request example (update name and status):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "name": "生产环境API Key（已更新）",
  "status": "disabled"
}

Request example (extend the expiry time):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": "2026-12-31T23:59:59+00:00"
}

Request example (set to never expire):

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "expires_at": null
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Important rules:

1. expires_at can only be extended, never shortened (for security reasons)

1. If the key already has an expiry time, the new expires_at must be later than the original one

1. A key with an expiry time can be set to never expire (by passing null)

1. status can only be active or disabled

Error response (attempting to shorten the expiry time):

{
  "code": 400,
  "msg": "expires_at 只能延长，不能缩短",
  "data": null
}

2.5 Delete an API Key

Description: Deletes a specified API Key.

Method: DELETE

Path: /console/api/api_keys

Authentication required: Yes

Request parameters:

Request example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

Notes: After deletion, all requests using this key fail immediately.

3. Data Source Management Module

3.1 Test Database Connection

Interface description: Tests whether a database connection is usable.

Request method: POST

Endpoint: /console/api/connect_test

Authentication required: Yes

Request parameters:

Database type reference:

• MySQL: requires username, password, host, port, database

• PostgreSQL: requires username, password, host, port, database

• SQL Server: requires username, password, (dsn or host+port), database

• Oracle: requires username, password, host, port, (service_name or sid)

• SQLite: requires (sqlite_memory=true or sqlite_path)

• Trino: requires host, port, catalog, schema

• KingBase: requires username, password, host, port, database (built on the PostgreSQL kernel, compatible with PostgreSQL syntax)

• OceanBase (MySQL tenant mode): requires username, password, host, port, database; uses the mysql+pymysql protocol, default port 2881

• DM (DMBase): requires username, password, host, port, database (compatible with Oracle syntax)

💡 TIP: OceanBase natively offers both MySQL and Oracle compatibility modes. The current API supports MySQL tenant mode; Oracle tenant mode will be supported in a future release.

Request example (MySQL):

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db"
}

Response example:

{
  "code": 200,
  "msg": "连接成功",
  "result": {
    "database_type": "mysql",
    "database_version": "8.0.33",
    "connection": "mysql+pymysql://root:***@192.168.1.100:3306/test_db"
  }
}

Error response:

{
  "code": 400,
  "msg": "数据库连接失败: Access denied for user",
  "result": null
}

3.2 Extract Table Schemas

Interface description: Extracts table schema information from a database and generates data cards. Supports full extraction (all tables) or targeted extraction (specific tables only).

Request method: POST

Endpoint: /console/api/extract_schema

Authentication required: Yes

Request parameters:

Request example (full extraction):

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db",
  "request_id": "req-123456"
}

Request example (targeted extraction):

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db",
  "table_names": ["customers", "orders"],
  "request_id": "req-123456"
}

Response example:

{
  "code": 200,
  "msg": "提取成功",
  "data": {
    "insert_result": {
      "message": "success",
      "inserted": 2,
      "skipped": 0,
      "total": 2
    },
    "generated_cards": [
      {
        "id": "uuid-xxx",
        "table_name": "customers",
        "card_content": "..."
      }
    ],
    "datasource_info": {
      "id": "ds-xxx",
      "connect_name": "生产库A",
      "database_type": "mysql"
    }
  }
}

3.3 Get the Table List of a Data Source

Interface description: Retrieves all tables and views in a data source (without extracting schemas), so the frontend can let users choose which tables to extract.

Request method: POST

Endpoint: /console/api/list_tables

Authentication required: Yes

Request parameters:

Request example:

{
  "connect_name": "生产库A",
  "db_type": "mysql",
  "username": "root",
  "password": "password123",
  "host": "192.168.1.100",
  "port": 3306,
  "database": "test_db"
}

Success response:

{
  "code": 200,
  "msg": "success",
  "result": {
    "tables": [
      { "name": "customers", "type": "TABLE" },
      { "name": "orders", "type": "TABLE" },
      { "name": "products", "type": "TABLE" },
      { "name": "user_stats_view", "type": "VIEW" }
    ],
    "total": 4
  }
}

Response field descriptions:

Error response:

{
  "code": 400,
  "msg": "数据库连接失败: Access denied",
  "result": null
}

3.4 Cancel Schema Extraction

Interface description: Cancels an ongoing schema extraction and cleans up the data already generated.

Request method: POST

Endpoint: /console/api/cancel_extract_schema

Authentication required: Yes

Request parameters:

Request example:

{
  "request_id": "req-123456",
  "config": {
    "connect_name": "生产库A",
    "db_type": "mysql",
    "host": "192.168.1.100",
    "port": 3306,
    "database": "test_db"
  }
}

Response example:

{
  "code": 200,
  "msg": "取消成功，已清理所有相关数据",
  "data": {
    "request_id": "req-123456",
    "deleted_schemas": 50,
    "deleted_cards": 50,
    "deleted_weaviate": 50,
    "deleted_datasource": 1,
    "status": "cancelled"
  }
}

3.5 Get Data Source List

Interface description: Paginated retrieval of all data sources belonging to the current user.

Request method: GET

Endpoint: /console/api/datasource_tool

Authentication required: Yes

Query parameters:

Request example:

GET /console/api/datasource_tool?page=1&page_size=20

Response example:

{
  "code": 200,
  "msg": "查询成功",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "user_id": "uuid-string",
        "connect_name": "生产库A",
        "db_type": "mysql",
        "database_name": "test_db",
        "table_num": 50,
        "status": "available",
        "connect_info": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
        "datacard_count": 50,
        "weaviate_num": 48,
        "schemas": [
          {
            "id": "uuid-string",
            "table_name": "users",
            "db_type": "mysql",
            "database_name": "test_db",
            "db_version": "8.0",
            "is_view": false,
            "view_name": null,
            "is_filled": true,
            "catalog_type": "mysql",
            "schema_text": {
              "columns": [
                {"name": "id", "type": "int", "nullable": false, "primary_key": true},
                {"name": "name", "type": "varchar(100)", "nullable": true}
              ],
              "indexes": []
            },
            "filled_data": {
              "table_comment": "用户表",
              "business_desc": "存储系统用户信息"
            },
            "created_at": "2025-01-20T10:30:00",
            "updated_at": "2025-01-20T10:30:00"
          }
        ],
        "created_at": "2025-01-20T10:30:00",
        "updated_at": "2025-01-20T10:30:00"
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 5,
    "total_pages": 1,
    "has_next": false,
    "has_prev": false,
    "weaviate_count": 50
  }
}

Response field descriptions:

• datacard_count: Number of data cards linked to this data source

• weaviate_num: Number of records that actually exist in the vector database for this data source (used to verify sync status)

• schema_text: Table schema details (parsed as a JSON object, including column info, indexes, etc.)

• filled_data: Business description filled in by the LLM

• schemas: List of table schema records linked to this data source

• weaviate_count: Total number of records in the current user's vector database (across all data sources)

3.6 Update Data Source Information

Interface description: Updates a data source's connection name, status and other information.

Request method: PUT

Endpoint: /console/api/datasource_tool/

Authentication required: Yes

Path parameters:

Request parameters:

Request example:

{
  "connect_name": "更新后的连接名",
  "status": "available"
}

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid-string",
    "user_id": "uuid-string",
    "connect_name": "更新后的连接名",
    "db_type": "mysql",
    "database_name": "test_db",
    "table_num": 50,
    "status": "available",
    "connect_info": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
    "created_at": "2025-01-20T10:30:00",
    "updated_at": "2025-01-20T10:30:00",
    "schemas_updated": 0,
    "cards_updated": 1
  }
}

Response field descriptions:

• schemas_updated: Number of table schema records updated in sync (when connect_name changes)

• cards_updated: Number of data card records updated in sync (when connect_name changes)

3.7 Delete a Data Source

Interface description: Deletes the specified data source and all associated data (table schemas, data cards, vector data, inventory data, glossary links, etc.).

Request method: DELETE

Endpoint: /console/api/datasource_tool/

Authentication required: Yes

Path parameters:

Request parameters: None

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid-string",
    "schemas_deleted": 50,
    "cards_deleted": 50,
    "term_library_links_deleted": 2,
    "inventory_jobs_deleted": 1,
    "inventory_job_results_deleted": 10,
    "table_relationships_deleted": 5,
    "table_relationship_cards_deleted": 5,
    "field_mappings_deleted": 20,
    "weaviate_count": 50,
    "weaviate_deleted": true,
    "field_index_deleted": 50
  }
}

Response field descriptions:

3.8 Refresh a Data Source

Interface description: Refreshes a data source, supporting two modes: quick refresh (only tests the connection and updates the status) and full refresh (re-extracts table schemas and updates data cards).

Request method: POST

Endpoint: /console/api/datasource_tool//refresh

Authentication required: Yes

Path parameters:

Query parameters:

Mode reference:

• quick: Quick refresh, only tests the database connection and updates the data source status without re-extracting table schemas.

• full: Full refresh, re-extracts all table schemas, compares differences, then updates data cards and the vector database.

3.8.1 Quick Refresh (quick)

Request example:

POST /console/api/datasource_tool/uuid-string/refresh?mode=quick

Response example:

{
  "code": 200,
  "msg": "刷新完成（quick）",
  "data": {
    "mode": "quick",
    "id": "uuid-string",
    "connect_name": "生产库A",
    "status_before": "unavailable",
    "status_after": "available",
    "database_type": "mysql",
    "database_name": "test_db",
    "database_version": "8.0.33",
    "connection": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
    "error": null
  }
}

Response field descriptions:

3.8.2 Full Refresh (full)

Request example:

POST /console/api/datasource_tool/uuid-string/refresh?mode=full

Response example:

{
  "code": 200,
  "msg": "刷新完成（full）",
  "data": {
    "mode": "full",
    "added_tables": ["new_table1"],
    "removed_tables": ["deleted_table"],
    "changed_tables": ["updated_table1", "updated_table2"],
    "unchanged_tables": 47,
    "schemas_deleted": 1,
    "cards_deleted": 1,
    "weaviate_deleted": 1,
    "cards_generated": 3,
    "total_tables": 50
  }
}

Response field descriptions:

4. Data Card Management Module

4.1 Get Data Card List

Interface description: Retrieves all data cards of the current user, with filtering by data source, keyword search and pagination.

Request method: GET

Endpoint: /console/api/datacard_tool

Authentication required: Yes

Query parameters:

Request example:

GET /console/api/datacard_tool?connect_name=生产库A&q=订单&page=1&page_size=20&parse_json=true

Response example (group_by=datasource):

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total_cards": 50,
    "total_datasources": 2,
    "items": [
      {
        "datasource": {
          "connect_name": "生产库A",
          "db_type": "mysql",
          "database_name": "test_db",
          "table_num": 30,
          "status": "available",
          "connect_info_masked": "mysql+pymysql://root:***@192.168.1.100:3306/test_db"
        },
        "cards": [
          {
            "doc_id": "uuid-string",
            "table_name": "orders",
            "connect_name": "生产库A",
            "connect_info_masked": "mysql+pymysql://root:***@192.168.1.100:3306/test_db",
            "w_uuid": "uuid-string",
            "card_data": "{\"table_name\":\"orders\",\"columns\":[...]}"
          }
        ]
      }
    ]
  }
}

Response example (group_by=flat):

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "total_cards": 50,
    "total_datasources": 2,
    "items": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "connect_name": "生产库A",
        "w_uuid": "uuid-string",
        "card_data": "{\"table_name\":\"orders\",\"columns\":[...]}"
      }
    ],
    "page": 1,
    "page_size": 20,
    "total": 50,
    "total_pages": 3
  }
}

4.2 Update a Data Card

Interface description: Updates the content of the specified data card.

Request method: PUT

Endpoint: /console/api/datacard_tool

Authentication required: Yes

Request parameters:

Request example:

{
  "doc_id": "uuid-string",
  "card_data": {
    "table_name": "orders",
    "table_desc": "订单表",
    "columns": [
      {
        "name": "id",
        "type": "int",
        "comment": "订单ID",
        "nullable": false
      }
    ]
  }
}

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "doc_id": "uuid-string",
    "w_uuid": "new-uuid-string",
    "card_data": {...},
    "_vector_ops": {
      "delete_old_ok": true,
      "old_w_uuid": "old-uuid-string",
      "new_w_uuid": "new-uuid-string"
    }
  }
}

Notes: When a data card is updated, the system automatically updates the corresponding vector data in the vector database (Weaviate).

5. Data Discovery Module

5.1 Targeted Inventory

5.1.1 Get Data Source Table List

Interface description: Retrieves all tables in the specified data source, including each table's quality level and number of missing fields.

Request method: GET

Endpoint: /console/api/target_inventory/tables

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "tables": [
      {
        "table_name": "orders",
        "quality_level": "low",
        "missing_fields_count": 5,
        "is_ai_filled": false
      },
      {
        "table_name": "customers",
        "quality_level": "high",
        "missing_fields_count": 0,
        "is_ai_filled": false
      }
    ]
  }
}

Quality level reference:

• low: Target table (a table that needs comments filled in)

• medium: LLM-filled table (comments already supplemented via AI)

• high: High-quality reference table (a table with complete comments)

5.1.2 Start a Targeted Inventory Job

Interface description: Creates a targeted inventory job that recommends field comments and infers table relationships for the selected target tables.

Request method: POST

Endpoint: /console/api/target_inventory/run

Authentication required: Yes

Request parameters:

Request example:

{
  "datasource_id": "xxx-xxx-xxx",
  "target_tables": ["orders", "order_items"],
  "ref_tables": ["customers", "products"],
  "dict_file_id": "dict-001",
  "options": {
    "enable_profiling": true,
    "confidence_threshold": 0.7
  }
}

Response example:

{
  "code": 200,
  "msg": "任务创建成功",
  "data": {
    "job_id": "job-xxx-xxx",
    "status": "queued",
    "created_at": "2025-01-15T10:30:00Z"
  }
}

5.1.3 Confirm Field Mappings

Interface description: The user confirms the recommended field comments, which are then saved to the field mapping table.

Request method: POST

Endpoint: /console/api/target_inventory/confirm

Authentication required: Yes

Request parameters:

Request example:

{
  "job_id": "job-xxx-xxx",
  "mappings": [
    {
      "source_table": "customers",
      "source_column": "customer_name",
      "target_table": "orders",
      "target_column": "cust_name",
      "mapping_type": "semantic_match",
      "confidence": 0.95
    }
  ]
}

5.1.4 Confirm Table Relationships

Interface description: The user confirms the inferred table relationships, which are then saved to the table relationship table.

Request method: POST

Endpoint: /console/api/target_inventory/confirm_relationships

Authentication required: Yes

Request parameters:

Request example:

{
  "job_id": "job-xxx-xxx",
  "relationships": [
    {
      "table_a": "orders",
      "table_b": "customers",
      "relationship_type": "foreign_key",
      "join_conditions": [
        {
          "column_a": "customer_id",
          "column_b": "id",
          "operator": "="
        }
      ],
      "cardinality": "N:1",
      "confidence": 0.98
    }
  ]
}

5.1.5 Generate Relationship Cards

Interface description: Generates relationship cards from the confirmed table relationships and stores them (database + vector database).

Request method: POST

Endpoint: /console/api/target_inventory/generate_cards

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "关系卡片生成成功",
  "data": {
    "cards_count": 5,
    "vector_indexed": true
  }
}

5.2 Global Inventory

5.2.1 Start a Global Inventory

Interface description: Automatically discovers relationships across all tables in a data source, supporting single-data-source and multi-data-source modes.

Request method: POST

Endpoint: /console/api/global_inventory/discover

Authentication required: Yes

Request parameters:

Request example (single data source):

{
  "datasource_id": "xxx-xxx-xxx",
  "schema_name": "public",
  "confidence_threshold": 0.6,
  "max_workers": 8,
  "enable_profiling": true
}

Request example (multiple data sources):

{
  "datasource_ids": ["xxx-xxx-xxx", "yyy-yyy-yyy"],
  "confidence_threshold": 0.7,
  "max_workers": 10
}

Response example:

{
  "code": 200,
  "msg": "全域盘点完成",
  "data": {
    "success": true,
    "tables_count": 25,
    "relationships_count": 48,
    "cards_count": 25,
    "is_multi_source": false,
    "cross_source_count": 0,
    "execution_time": "125.3s"
  }
}

Response example (multiple data sources):

{
  "code": 200,
  "msg": "全域盘点完成",
  "data": {
    "success": true,
    "tables_count": 50,
    "relationships_count": 95,
    "cards_count": 50,
    "is_multi_source": true,
    "cross_source_count": 12,
    "execution_time": "256.7s"
  }
}

5.2.2 Get a Single Table's Relationship Cards

Interface description: Retrieves the complete relationship card data for the specified table.

Request method: GET

Endpoint: /console/api/global_inventory/cards//

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "table_name": "orders",
    "datasource_id": "xxx-xxx-xxx",
    "relationships": [
      {
        "target_table": "customers",
        "target_datasource_id": "xxx-xxx-xxx",
        "join_conditions": [
          {
            "source_column": "customer_id",
            "target_column": "id",
            "operator": "="
          }
        ],
        "relationship_type": "foreign_key",
        "relationship_strength": 0.95,
        "cardinality": "N:1",
        "is_cross_source": false
      },
      {
        "target_table": "products",
        "target_datasource_id": "yyy-yyy-yyy",
        "join_conditions": [
          {
            "source_column": "product_code",
            "target_column": "code",
            "operator": "="
          }
        ],
        "relationship_type": "semantic_match",
        "relationship_strength": 0.82,
        "cardinality": "N:1",
        "is_cross_source": true
      }
    ],
    "related_datasource_ids": ["xxx-xxx-xxx", "yyy-yyy-yyy"],
    "has_cross_source_relations": true
  }
}

5.2.3 Get All Relationship Cards of a Data Source

Interface description: Retrieves the relationship cards of all tables in the specified data source.

Request method: GET

Endpoint: /console/api/global_inventory/cards/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "datasource_id": "xxx-xxx-xxx",
    "cards": [
      {
        "table_name": "orders",
        "relationships_count": 3,
        "has_cross_source_relations": false
      },
      {
        "table_name": "customers",
        "relationships_count": 2,
        "has_cross_source_relations": true
      }
    ],
    "total_count": 25
  }
}

6. AI Query Module

6.1 Aggregate Query on Data Cards (Session Authentication)

Interface description: Takes a natural-language question, intelligently retrieves the relevant data cards, generates SQL, and executes the query. Supports multi-table joins and cross-source queries.

Request method: POST

Endpoint: /console/api/query_by_datacards_agg

Authentication required: Yes

Request parameters:

Notes:

• The fusion strategy (AND/OR/PRIORITY/UNION) is inferred automatically by the system from the natural-language question; no manual specification is needed.

• The query type (aggregate/detail) is detected automatically by the system.

• When no data source is specified, all of the current user's data sources are searched.

Request example:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "enable_rerank": true
}

Request example with data source IDs:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_ids": ["550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001"],
  "enable_rerank": true
}

Request example with a single data source ID:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000"
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "clusters": [
      {
        "db_type": "mysql",
        "connect_name": "生产库A",
        "cluster_tables": [
          {
            "table_name": "orders",
            "columns": [
              {"name": "order_id", "type": "int"},
              {"name": "customer_id", "type": "varchar"},
              {"name": "amount", "type": "decimal"},
              {"name": "create_time", "type": "datetime"}
            ]
          }
        ],
        "target_sql": "SELECT o.customer_id, SUM(o.amount) as total_amount FROM orders o WHERE o.create_time >= DATE_SUB(NOW(), INTERVAL 1 MONTH) AND o.amount > 1000 GROUP BY o.customer_id",
        "rows": [
          {
            "customer_id": "C001",
            "total_amount": 5000.00
          }
        ],
        "entity_ids": ["C001"],
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "warnings": []
      }
    ],
    "merge": {
      "strategy": "SINGLE_CLUSTER",
      "entity_key": "customer_id",
      "fusion_method": "none",
      "note": "单数据源查询，无需跨源融合"
    },
    "final_rows": [
      {
        "customer_id": "C001",
        "total_amount": 5000.00
      }
    ],
    "fill_warnings": [],
    "data_cards": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "database_name": "ecommerce_db",
        "connect_name": "生产库A",
        "card_content": {}
      }
    ],
    "term_rewrite": {
      "enabled": true,
      "matched_count": 1,
      "matched_terms": [
        {
          "term_name": "GMV",
          "term_definition": "商品交易总额",
          "matched_alias": "订单金额",
          "library_name": "电商术语库"
        }
      ],
      "rewritten_question": "查询最近一个月GMV（商品交易总额）大于1000的客户信息"
    }
  }
}

Response field notes:

Notes:

1. The system first uses vector retrieval to find the relevant data cards.

1. If term expansion is enabled (enable_term_rewrite=true), the question is first analyzed and rewritten for term recognition.

1. Table structures and relationships are built from the data cards.

1. JOIN conditions from relationship cards are preferred (when present) to improve multi-table query accuracy.

1. An LLM generates the SQL query (incorporating relationship card information).

1. The SQL is executed and the results are returned.

1. If multiple data sources are involved, the results are merged according to the fusion strategy (using relationship information).

Relationship card enhancements:

• JOIN condition accuracy improves by 15-20%

• Multi-table query success rate improves by 20-25%

• Cross-source relationship recognition is supported

• Cartesian product issues are significantly reduced

6.2 Aggregate Query on Data Cards (API Key Plugin Interface)

Interface description: An aggregate query interface authenticated via API Key, designed for plugins and external systems. No session login is required.

Request method: POST

Endpoint: /console/api/query_by_datacards_agg_plugin

Authentication required: No (uses API Key authentication)

Authentication method: Carry the API Key in the request header (see 2.1 API Key Authentication).

Request header examples:

Authorization: ak_xxxxxxxxxxxxxxxxxxxxxxxx
or
Authorization: Bearer ak_xxxxxxxxxxxxxxxxxxxxxxxx
or
X-API-Key: ak_xxxxxxxxxxxxxxxxxxxxxxxx

Request parameters:

Parameter precedence:

• connect_name > datasource_id > datasource_ids > unspecified (search all data sources)

• When connect_name is provided, the system looks up the corresponding data source ID among the user's data sources.

Request example:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "enable_rerank": true
}

Request example with a data source name:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "connect_name": "生产库A",
  "enable_rerank": true
}

Request example with data source IDs:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_ids": ["550e8400-e29b-41d4-a716-446655440000", "660e8400-e29b-41d4-a716-446655440001"],
  "enable_rerank": true
}

Request example with a single data source ID:

{
  "query": "查询最近一个月订单金额大于1000的客户信息",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000",
  "enable_rerank": false
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "clusters": [
      {
        "db_type": "mysql",
        "connect_name": "生产库A",
        "cluster_tables": [
          {
            "table_name": "orders",
            "columns": [
              {"name": "order_id", "type": "int"},
              {"name": "customer_id", "type": "varchar"},
              {"name": "amount", "type": "decimal"},
              {"name": "create_time", "type": "datetime"}
            ]
          }
        ],
        "target_sql": "SELECT o.customer_id, SUM(o.amount) as total_amount FROM orders o WHERE o.create_time >= DATE_SUB(NOW(), INTERVAL 1 MONTH) AND o.amount > 1000 GROUP BY o.customer_id",
        "rows": [
          {
            "customer_id": "C001",
            "total_amount": 5000.00
          }
        ],
        "entity_ids": ["C001"],
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "warnings": []
      }
    ],
    "merge": {
      "strategy": "SINGLE_CLUSTER",
      "entity_key": "customer_id",
      "fusion_method": "none",
      "note": "单数据源查询，无需跨源融合"
    },
    "final_rows": [
      {
        "customer_id": "C001",
        "total_amount": 5000.00
      }
    ],
    "fill_warnings": [],
    "data_cards": [
      {
        "doc_id": "uuid-string",
        "table_name": "orders",
        "database_name": "ecommerce_db",
        "connect_name": "生产库A",
        "card_content": {}
      }
    ],
    "term_rewrite": {
      "enabled": true,
      "matched_count": 0,
      "matched_terms": [],
      "rewritten_question": "查询最近一个月订单金额大于1000的客户信息"
    }
  }
}

Response field notes:

Identical to the interface in 6.1; see 6.1 Response Fields. The main difference is that each element in the term_rewrite.matched_terms array also includes the following fields:

Fusion strategy notes: The system automatically infers the fusion strategy from the natural-language question:

• OR: Results satisfy any condition; returns the union across data sources

• AND: Multiple conditions must all be satisfied; returns the intersection across data sources

• PRIORITY: The primary data source takes precedence; others serve as supplements

• UNION: Merges all results and deduplicates

• TRINO_UNIFIED: When all tables are connected through Trino, a unified query runs across Trino catalogs

Relationship card enhancements:

• The system prefers JOIN conditions from relationship cards when generating SQL

• JOIN suggestions from relationship cards include confidence scores and relationship types

• Cross-source relationship recognition is supported (via the is_cross_source flag)

• Multi-table query accuracy (+20-25%) and JOIN condition accuracy (+15-20%) improve significantly

• Common issues such as Cartesian products are reduced

Permission notes:

• Data isolation is based on the user_id bound to the API Key

• Only data sources and data cards that the API Key's owning user has permission to access can be queried

• Data cards recalled by vector retrieval are automatically filtered by user ID

Error responses:

401 Unauthorized - Missing API Key:

{
  "code": 401,
  "msg": "缺少 API Key",
  "data": null
}

401 Unauthorized - Invalid API Key:

{
  "code": 401,
  "msg": "API Key 无效",
  "data": null
}

403 Forbidden - API Key Disabled:

{
  "code": 403,
  "msg": "API Key 已禁用",
  "data": null
}

403 Forbidden - API Key Expired:

{
  "code": 403,
  "msg": "API Key 已过期",
  "data": null
}

400 Bad Request - Missing query parameter:

{
  "code": 400,
  "msg": "请提供 query",
  "data": null
}

Notes:

1. This interface is functionally similar to 6.1, but uses API Key authentication instead of session authentication.

1. Designed for external system integration and plugin development scenarios.

1. The API Key is automatically mapped to its owning user, enforcing data isolation.

1. After each successful call, the system automatically updates the API Key's last_used_at field.

1. Vector retrieval and reranking parameters (e.g., distance_threshold, max_results) use the system defaults.

7. Data Audit Module

7.1 Data Quality Audit

Interface description: Audits the data quality of a specified table, counting NULLs, empty strings, and other conditions across fields.

Request method: POST

Endpoint: /console/api/data_audit

Authentication required: Yes

Request parameters:

connect_info object structure:

Request example:

{
  "db_type": "mysql",
  "connect_info": {
    "host": "192.168.1.100",
    "port": 3306,
    "user": "root",
    "password": "password123"
  },
  "database_name": "test_db",
  "table_name": "orders"
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "db_type": "mysql",
    "database": "test_db",
    "schema": null,
    "table": "orders",
    "report": [
      {
        "column_name": "customer_name",
        "data_type": "varchar(100)",
        "total_rows": 1000,
        "null_count": 50,
        "empty_str_count": 20,
        "missing_count": 70,
        "missing_pct": 7.0
      },
      {
        "column_name": "order_date",
        "data_type": "datetime",
        "total_rows": 1000,
        "null_count": 10,
        "empty_str_count": 0,
        "missing_count": 10,
        "missing_pct": 1.0
      }
    ]
  }
}

Response field notes:

• total_rows: Total number of rows in the table

• null_count: Number of NULL values

• empty_str_count: Number of empty strings (string-typed fields only)

• missing_count: Total number of missing values (null_count + empty_str_count)

• missing_pct: Percentage of missing values

8. Changelog Module

8.1 Get the Changelog List

Interface description: Retrieves the list of all version changelog entries.

Request method: GET

Endpoint: /console/api/changelog

Authentication required: Yes

Request parameters: None

Response example:

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": 1,
      "version": "1.0.0",
      "title": "初始版本发布",
      "content_md": "# 更新内容\n\n- 支持MySQL数据库连接\n- 支持数据卡片生成",
      "status": "public",
      "created_at": "2025-01-20T10:30:00",
      "updated_at": "2025-01-20T10:30:00"
    }
  ]
}

8.2 Get Changelog Entry Details

Interface description: Retrieves the changelog details for a specified version.

Request method: GET

Endpoint: /console/api/changelog/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": 1,
    "version": "1.0.0",
    "title": "初始版本发布",
    "content_md": "# 更新内容\n\n- 支持MySQL数据库连接\n- 支持数据卡片生成",
    "status": "public",
    "created_at": "2025-01-20T10:30:00",
    "updated_at": "2025-01-20T10:30:00"
  }
}

8.3 Create a Changelog Entry

Interface description: Creates a new version changelog entry.

Request method: POST

Endpoint: /console/api/changelog

Authentication required: Yes

Request parameters:

Request example:

{
  "version": "1.1.0",
  "title": "新增数据审计功能",
  "content_md": "# 更新内容\n\n- 新增数据质量审计功能\n- 优化查询性能",
  "status": "public"
}

Response example:

{
  "code": 200,
  "msg": "created",
  "data": {
    "id": 2
  }
}

8.4 Update a Changelog Entry

Interface description: Updates the changelog for a specified version.

Request method: PUT

Endpoint: /console/api/changelog/

Authentication required: Yes

Path parameters:

Request parameters:

Request example:

{
  "title": "更新后的标题",
  "status": "public"
}

Response example:

{
  "code": 200,
  "msg": "updated",
  "data": {
    "id": 2
  }
}

8.5 Delete a Changelog Entry

Interface description: Deletes the changelog for a specified version.

Request method: DELETE

Endpoint: /console/api/changelog/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "deleted",
  "data": {
    "id": 2
  }
}

9. Excel Field Extraction Module

9.1 Extract Field Data from Excel

Interface description: Extracts table field descriptions from an Excel file and populates them into the database table structure.

Request method: POST

Endpoint: /console/api/extract_field_data_excel

Authentication required: Yes

Request parameters: FormData

field_data JSON structure:

Request example (FormData):

file: [Excel file]
sheet_name: "字段描述"
field_data: {
  "tb_name_column": "A",
  "tb_desc_column": "B",
  "field_name_column": "C",
  "field_desc_column": "D",
  "field_value_desc_column": "E",
  "has_title": true
}

Response example:

{
  "code": 200,
  "msg": "提取成功",
  "data": {
    "total_tables": 10,
    "filled_tables": 10,
    "total_fields": 150,
    "filled_fields": 145
  }
}

Notes: This endpoint parses the Excel file to extract table names, field names, field descriptions and other metadata, then automatically fills them into the corresponding database table structures.

10. Model Configuration Management Module

Interface description: Manages the LLM configurations available in the system, including querying, creating, updating and deleting model configurations.

Base path: /console/api/model_config

10.1 Query Model Configurations

• Request method: GET

• Authentication required: No

• Query parameters:

Request example:

GET /console/api/model_config
GET /console/api/model_config?id=550e8400-e29b-41d4-a716-446655440000

Response example (list):

{
  "code": 200,
  "msg": "success",
  "data": [
    {
      "id": "550e8400-e29b-41d4-a716-446655440000",
      "model_name": "豆包大模型",
      "model_type": "豆包",
      "model_api_key": "sk-****",
      "model_class": "大语言",
      "url": "https://api.doubao.com/v1/chat/completions",
      "created_at": "2025-11-28T12:49:00+08:00",
      "updated_at": "2025-11-28T12:49:00+08:00"
    }
  ]
}

Response example (single record):

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "model_name": "豆包大模型",
    "model_type": "豆包",
    "model_api_key": "sk-****",
    "model_class": "大语言",
    "url": "https://api.doubao.com/v1/chat/completions",
    "created_at": "2025-11-28T12:49:00+08:00",
    "updated_at": "2025-11-28T12:49:00+08:00"
  }
}

10.2 Add a Model Configuration

• Request method: POST

• Authentication required: No

• Request parameters (JSON):

Request example:

{
  "model_name": "千问大模型",
  "model_type": "千问",
  "model_api_key": "sk-qianwen-key-12345",
  "model_class": "大语言",
  "url": "https://api.qianwen.com/v1/chat/completions"
}

Success response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

10.3 Update a Model Configuration

• Request method: PUT

• Authentication required: No

• Request parameters (JSON):

Request example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "model_name": "豆包大模型-v2",
  "model_api_key": "sk-new-key"
}

Success response:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

10.4 Delete a Model Configuration

• Request method: DELETE

• Authentication required: No

• Request parameters (JSON):

Request example:

{
  "id": "550e8400-e29b-41d4-a716-446655440000"
}

Success response:

{
  "code": 200,
  "msg": "deleted",
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  }
}

11. Query History Module

11.1 List Query History

Interface description: Paginated retrieval of a user's query history, with filtering by data source, status and date range.

Request method: GET

Endpoint: /console/api/query_history/list

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "total": 100,
    "page": 1,
    "page_size": 20,
    "total_pages": 5,
    "items": [
      {
        "id": "uuid-string",
        "question": "查询最近一周的订单",
        "processed_question": "查询最近一周的GMV（成交总额）",
        "term_rewrite_info": {
          "matched_terms": [
            {
              "term_name": "GMV",
              "term_definition": "商品交易总额",
              "matched_alias": "订单"
            }
          ]
        },
        "sql": "SELECT * FROM orders WHERE ...",
        "cluster_sqls": [
          {
            "datasource_ids": ["uuid1"],
            "datasource_names": ["生产库A"],
            "table_names": ["orders"],
            "sql": "SELECT * FROM orders WHERE ..."
          }
        ],
        "source_datasource_ids": ["uuid1", "uuid2"],
        "source_datasource_names": ["生产库A", "生产库B"],
        "total_duration_ms": 2500,
        "total_tokens": 1500,
        "status": "success",
        "result_count": 50,
        "fusion_strategy": "OR",
        "has_full_result": true,
        "created_at": "2026-04-09T10:30:00"
      }
    ]
  }
}

Response field descriptions:

11.2 Query History Details

Interface description: Retrieves the full details of a single query history record, including performance metrics, Token consumption and quality metrics.

Request method: GET

Endpoint: /console/api/query_history/

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "user_id": "user-uuid",
    "api_key_id": "api-key-uuid",
    "question": "查询最近一周的订单",
    "processed_question": "查询最近一周的GMV（成交总额）",
    "term_rewrite_info": {
      "matched_terms": [
        {
          "term_name": "GMV",
          "term_definition": "商品交易总额",
          "matched_alias": "订单",
          "library_name": "电商术语库"
        }
      ],
      "rewrite_count": 1
    },
    "sql": "SELECT * FROM orders WHERE ...",
    "cluster_sqls": [
      {
        "datasource_ids": ["uuid1"],
        "datasource_names": ["生产库A"],
        "table_names": ["orders"],
        "sql": "SELECT * FROM orders WHERE ..."
      }
    ],
    "source_datasource_ids": ["uuid1"],
    "source_datasource_names": ["生产库A"],
    "datasource_ids": ["uuid1"],
    "datasource_names": ["生产库A"],
    "table_names": ["orders", "customers"],
    "performance": {
      "total_duration_ms": 2500,
      "vector_search_ms": 300,
      "rerank_ms": 200,
      "llm_gen_sql_ms": 800,
      "sql_execution_ms": 1200,
      "fusion_ms": 0
    },
    "tokens": {
      "embedding_tokens": 500,
      "rerank_tokens": 200,
      "llm_prompt_tokens": 600,
      "llm_completion_tokens": 200,
      "total_tokens": 1500
    },
    "result": {
      "result_count": 50
    },
    "quality": {
      "cards_recalled": 15,
      "cards_reranked": 10,
      "cards_selected": 5,
      "top1_rerank_score": 0.95,
      "avg_rerank_score": 0.88
    },
    "status": "success",
    "fusion_strategy": "OR",
    "full_response_result": {...},
    "created_at": "2026-04-09T10:30:00"
  }
}

Response field descriptions:

11.3 Delete Query History

Interface description: Deletes a single query history record (aggregated statistics are updated accordingly).

Request method: DELETE

Endpoint: /console/api/query_history/

Authentication required: Yes

Path parameters:

Query parameters:

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "deleted_id": "uuid-string"
  }
}

11.4 Batch Delete Query History

Interface description: Deletes query history records in bulk, supporting deletion by ID list, date range, or retention days.

Request method: DELETE

Endpoint: /console/api/query_history/batch

Authentication required: Yes

Query parameters:

Notes: At least one of query_ids, before_date, and keep_days must be provided.

Response example:

{
  "code": 200,
  "msg": "成功删除 50 条记录",
  "data": {
    "deleted_count": 50,
    "total_found": 50
  }
}

11.5 Query History Statistics

Interface description: Retrieves a summary of the user's query statistics.

Request method: GET

Endpoint: /console/api/query_history/stats

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "period": {
      "start_date": "2026-04-01",
      "end_date": "至今"
    },
    "total_queries": 500,
    "success_queries": 480,
    "error_queries": 15,
    "timeout_queries": 5,
    "success_rate": 96.0,
    "total_tokens": 75000,
    "avg_duration_ms": 2300,
    "min_duration_ms": 500,
    "max_duration_ms": 15000
  }
}

12. Monitoring Center Module

12.1 Monitoring Overview

Interface description: Retrieves monitoring overview data, including real-time statistics, trend data and comparison analysis.

Request method: GET

Endpoint: /console/api/monitoring/overview

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "recent_24h": {
      "total_queries": 150,
      "success_queries": 145,
      "error_queries": 3,
      "timeout_queries": 2,
      "success_rate": 96.67,
      "avg_duration_ms": 2300,
      "total_tokens": 22500,
      "embedding_tokens": 7500,
      "rerank_tokens": 3000,
      "llm_tokens": 12000
    },
    "today": {
      "total_queries": 45,
      "success_queries": 43,
      "total_tokens": 6750
    },
    "daily_trend": [...],
    "summary_30d": {
      "total_queries": 1500,
      "total_tokens": 225000,
      "total_cost_yuan": 1.25
    },
    "cost_note": "⚠️ 成本为预估值，仅供参考，实际费用以云厂商账单为准",
    "comparison": {
      "vs_yesterday": {...},
      "vs_last_week": {...}
    },
    "hourly_distribution": {...},
    "datasource_stats": {...},
    "status_breakdown": {...},
    "quality_metrics": {...}
  }
}

12.2 Monitoring Trends

Interface description: Retrieves monitoring trend data, with daily query volume, Token consumption and cost statistics.

Request method: GET

Endpoint: /console/api/monitoring/trend

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "days": 30,
    "items": [
      {
        "date": "2026-04-09",
        "total_queries": 50,
        "success_queries": 48,
        "error_queries": 1,
        "timeout_queries": 1,
        "success_rate": 96.0,
        "tokens": {
          "embedding": 2500,
          "rerank": 1000,
          "llm": 4000,
          "total": 7500
        },
        "cost_yuan": 0.045,
        "performance": {...},
        "quality": {...}
      }
    ],
    "statistics": {...},
    "growth_analysis": {...},
    "peak_valley": {...},
    "weekly_pattern": {...}
  }
}

12.3 Real-time Monitoring

Interface description: Retrieves real-time monitoring data (last 1 hour).

Request method: GET

Endpoint: /console/api/monitoring/realtime

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "summary": {
      "total_queries": 25,
      "avg_duration_ms": 2100,
      "total_tokens": 3750
    },
    "minute_data": [...],
    "current_status": {...},
    "qps_stats": {...},
    "error_alerts": {...},
    "recent_queries": {...},
    "datasource_health": {...}
  }
}

12.4 Performance Analysis

Interface description: Retrieves performance analysis data, including stage-level latency breakdown and per-data-source performance.

Request method: GET

Endpoint: /console/api/monitoring/performance

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "period_days": 7,
    "stage_averages": {
      "vector_search_ms": 300,
      "rerank_ms": 200,
      "llm_gen_sql_ms": 800,
      "sql_execution_ms": 1000,
      "total_avg_ms": 2300
    },
    "slow_queries_top10": [...],
    "latency_distribution": {...},
    "stage_breakdown": {...},
    "datasource_performance": {...},
    "performance_trend": {...},
    "query_patterns": {...}
  }
}

13. System Configuration Module

13.1 Get Token Price Configuration

Interface description: Retrieves the current Token price configuration (Embedding, Rerank, LLM input/output).

Request method: GET

Endpoint: /console/api/system_config/token_prices

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "scope": "system",
    "embedding": {
      "key": "token_price_embedding",
      "value": "0.0007",
      "description": "Embedding Token 单价（元/千token）"
    },
    "rerank": {
      "key": "token_price_rerank",
      "value": "0.002",
      "description": "Rerank Token 单价（元/千token）"
    },
    "llm_input": {
      "key": "token_price_llm_input",
      "value": "0.002",
      "description": "LLM 输入 Token 单价（元/千token）"
    },
    "llm_output": {
      "key": "token_price_llm_output",
      "value": "0.006",
      "description": "LLM 输出 Token 单价（元/千token）"
    }
  }
}

13.2 Update Token Price Configuration

Interface description: Updates Token price configuration in bulk.

Request method: PUT

Endpoint: /console/api/system_config/token_prices

Authentication required: Yes

Request parameters:

Request example:

{
  "embedding": 0.0008,
  "rerank": 0.0025,
  "llm_input": 0.003,
  "llm_output": 0.008
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "message": "系统级价格配置更新成功",
    "scope": "system",
    "updated": [
      {"key": "token_price_embedding", "value": "0.0008"}
    ]
  }
}

13.3 Get Data Retention Configuration

Interface description: Retrieves the data retention period configuration.

Request method: GET

Endpoint: /console/api/system_config/data_retention

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "scope": "system",
    "query_logs_retention_days": {
      "value": "180",
      "description": "查询日志保留天数",
      "unit": "天"
    },
    "stats_retention_days": {
      "value": "365",
      "description": "聚合统计保留天数",
      "unit": "天"
    }
  }
}

13.4 Update Data Retention Configuration

Interface description: Updates the data retention period configuration.

Request method: PUT

Endpoint: /console/api/system_config/data_retention

Authentication required: Yes

Request parameters:

13.5 Manually Trigger Data Cleanup

Interface description: Manually triggers the expired data cleanup task.

Request method: POST

Endpoint: /console/api/system_config/cleanup

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "数据清理完成",
  "data": {
    "type": "all",
    "results": {
      "query_logs": {"deleted": 100},
      "query_stats_daily": {"deleted": 5}
    },
    "total_deleted": 105,
    "duration_ms": 500,
    "executed_at": "2026-04-09T10:30:00"
  }
}

13.6 Get System Configuration List

Interface description: Retrieves all system configuration items.

Request method: GET

Endpoint: /console/api/system_config/config

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "configs": [
      {
        "id": "uuid",
        "config_key": "token_price_embedding",
        "config_value": "0.0007",
        "description": "Embedding Token 单价（元/千token）",
        "user_id": null,
        "scope": "system"
      }
    ]
  }
}

13.7 Update System Configuration

Interface description: Updates or creates a system configuration item.

Request method: PUT

Endpoint: /console/api/system_config/config

Authentication required: Yes

Request parameters:

13.8 Delete System Configuration

Interface description: Deletes a system configuration item (critical configurations cannot be deleted).

Request method: DELETE

Endpoint: /console/api/system_config/config

Authentication required: Yes

14. SSO Single Sign-On Module

14.1 SSO Login Endpoint

Interface description: Implements SSO single sign-on via a JWT Token, completing authentication without a username and password.

Request method: GET

Endpoint: /sso/login

Authentication required: No

Query parameters:

URL encoding notes:

• The token parameter must be URL-encoded with encodeURIComponent().

• The redirect_url parameter must be URL-encoded with encodeURIComponent().

Full URL format:

/sso/login?token={encodeURIComponent(JWT Token)}&redirect_url={encodeURIComponent(callback URL)}

JWT Token structure:

Required Payload fields:

Optional Payload fields:

JWT Token generation example (Python):

import jwt
from datetime import datetime, timedelta, timezone

SECRET_KEY = "your_shared_secret_key"

payload = {
    "username": "zhang_san",
    "user_id": "SYS_USER_001",
    "nickname": "张三",
    "email": "zhangsan@example.com",
    "source": "your_app",
    "iat": datetime.now(timezone.utc),
    "exp": datetime.now(timezone.utc) + timedelta(minutes=5)
}

token = jwt.encode(payload, SECRET_KEY, algorithm="HS256")
print(token)

JWT Token generation example (Node.js):

const jwt = require('jsonwebtoken');

const secretKey = 'your_shared_secret_key';

const payload = {
    username: 'zhang_san',
    user_id: 'SYS_USER_001',
    nickname: '张三',
    email: 'zhangsan@example.com',
    source: 'your_app'
};

const token = jwt.sign(payload, secretKey, {
    algorithm: 'HS256',
    expiresIn: '5m'
});

console.log(token);

Redirect example:

// Generate the Token
const token = jwt.sign(payload, secretKey, { algorithm: 'HS256', expiresIn: '5m' });

// Build the SSO login URL
const ssoUrl = `${API_BASE}/sso/login?token=${encodeURIComponent(token)}&redirect_url=${encodeURIComponent(FRONTEND_URL)}`;

// Redirect
window.location.href = ssoUrl;

Successful login response:

After a successful login, the browser is redirected to the specified redirect_url with an access_token parameter in the URL:

{redirect_url}?access_token={OntiCards平台Token}

Example:

https://frontend.onticards.com/overview?access_token=eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...

Frontend token handling example:

// Read access_token from the URL
function getAccessToken() {
    const params = new URLSearchParams(window.location.search);
    return params.get('access_token');
}

// Store the Token
const token = getAccessToken();
if (token) {
    localStorage.setItem('access_token', token);

    // Clean the token from the URL (avoid token leakage in browser history)
    window.history.replaceState({}, document.title, window.location.pathname);
}

Error responses:

Error response example:

{
  "code": 401,
  "msg": "token无效",
  "error": "token无效"
}

Error page example: When SSO login fails, an error message page is returned:

<!DOCTYPE html>
<html>
<head>
    <title>SSO Login Error</title>
</head>
<body>
    <h1>SSO Login Failed</h1>
    <p>Error: token无效</p>
</body>
</html>

14.2 SSO Login Flow

Overall flow:

1. The enterprise system authenticates the user identity
   ↓
2. The enterprise backend generates a JWT Token (containing user information)
   ↓
3. Build the SSO login URL
   {OntiCards API URL}/sso/login?token={JWT Token}&redirect_url={callback URL}
   ↓
4. The user's browser navigates to the OntiCards SSO endpoint
   ↓
5. OntiCards verifies the JWT signature and validity period
   ↓
6. Creates/links the user and generates a platform Token
   ↓
7. Redirects to the callback URL with access_token
   ↓
8. The frontend receives the Token and login is complete

User creation/linking logic:

1. Receive the JWT Token → extract the token parameter from the URL

1. Parse the Header → obtain the algorithm information (HS256)

1. Verify the signature → use the shared secret to check that the token has not been tampered with

1. Check expiration → verify that exp is still valid

1. Extract the Payload → obtain username, user_id and other user information

1. Look up the user → search for an existing user by idp_user_id + idp_source

1. Create/link → new users are created automatically, existing users are linked at login

1. Generate the Token → generate OntiCards' own login Token

1. Redirect to the callback → redirect to redirect_url with the new Token

14.3 SSO Test Pages

SSO test center:

http://localhost:9103/static/sso_test.html

Callback test page:

http://localhost:9103/static/sso_callback.html

Test page features:

• Generate a test JWT Token

• Fill in the callback URL

• Initiate an SSO login with one click

• View the login result

14.4 SSO Configuration

Server-side configuration (environment variable):

Configuration example:

SSO_SECRET_KEY=K7x#9mP$2nL@qR8

Secret requirements:

• We recommend a random string of 64 characters or more.

• The client and server must use the same secret.

• In production, use a strong secret; do not use the example secret.

14.5 SSO Security Notes

14.6 SSO vs. API Key

15. Prompt Configuration Module

Module overview: Provides management for system prompt templates, including syncing prompts from files to the database, online editing and hot reload.

Base path: /console/api/prompt_config

Prompt file location: libs/prompt/query_agg_prompt/

Supported prompt files:

Prompt load priority: Database (highest) > Cache > File (fallback)

15.1 List Prompts

Interface description: Paginated retrieval of the prompt list, with search, category filtering and database type filtering.

Request method: GET

Endpoint: /console/api/prompt_config/list

Authentication required: Yes

Query parameters:

Request example:

GET /console/api/prompt_config/list?page=1&page_size=20&category=multi-table%20query

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "file_name": "mysql_multi_table.txt",
        "description": "MySQL 多表查询SQL生成 提示词",
        "category": "多表查询",
        "db_type": "MySQL",
        "prompt_length": 15360
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 17,
      "total_pages": 1
    }
  }
}

15.2 Get Prompt Details

Interface description: Retrieves the full content of a single prompt by UUID.

Request method: GET

Endpoint: /console/api/prompt_config/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "prompt": "你是一名专业的 MySQL SQL 查询生成器...",
    "description": "MySQL 多表查询SQL生成 提示词",
    "category": "多表查询",
    "db_type": "MySQL",
    "prompt_length": 15360
  }
}

15.3 Get a Prompt by File Name

Interface description: Retrieves the prompt content by file name.

Request method: GET

Endpoint: /console/api/prompt_config/file/

Authentication required: Yes

Path parameters:

Request example:

GET /console/api/prompt_config/file/mysql_multi_table.txt

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "prompt": "你是一名专业的 MySQL SQL 查询生成器...",
    "description": "MySQL 多表查询SQL生成 提示词",
    "category": "多表查询",
    "db_type": "MySQL",
    "from_cache": true
  }
}

15.4 Create a Prompt

Interface description: Creates a new prompt configuration.

Request method: POST

Endpoint: /console/api/prompt_config/list

Authentication required: Yes

Request parameters:

Request example:

{
  "file_name": "custom_prompt.txt",
  "prompt": "自定义提示词内容...",
  "description": "自定义提示词"
}

Response example:

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid-string",
    "file_name": "custom_prompt.txt",
    "description": "自定义提示词",
    "message": "创建成功"
  }
}

Error response (file name already exists):

{
  "code": 409,
  "msg": "文件名 'xxx.txt' 已存在，如需更新请使用 PUT 接口"
}

15.5 Update a Prompt

Interface description: Updates the prompt content or description.

Request method: PUT

Endpoint: /console/api/prompt_config/

Authentication required: Yes

Path parameters:

Request parameters:

Request example:

{
  "prompt": "更新后的提示词内容...",
  "description": "更新后的描述"
}

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid-string",
    "file_name": "mysql_multi_table.txt",
    "updated_fields": ["prompt", "description"],
    "message": "更新成功"
  }
}

Notes: After an update, the prompt's cache is cleared automatically, so the next request reads the latest content from the database (hot reload).

15.6 Delete a Prompt

Interface description: Deletes the specified prompt configuration.

Request method: DELETE

Endpoint: /console/api/prompt_config/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "file_name": "custom_prompt.txt",
    "message": "删除成功"
  }
}

15.7 Sync Prompts (File to Database)

Interface description: Syncs prompt file content to the database, for a single file or all files.

Request method: POST

Endpoint: /console/api/prompt_config/sync

Authentication required: Yes

Request parameters:

Request example (sync a single file):

{
  "file_name": "mysql_multi_table.txt"
}

Request example (sync all):

{}

Response example (single file):

{
  "code": 200,
  "msg": "同步成功",
  "data": {
    "file_name": "mysql_multi_table.txt",
    "message": "同步成功",
    "prompt_length": 15360
  }
}

Response example (all files):

{
  "code": 200,
  "msg": "同步完成",
  "data": {
    "success": ["mysql_multi_table.txt", "postgresql_multi_table.txt", ...],
    "failed": [],
    "total": 17,
    "message": "同步完成，成功 17 个，失败 0 个"
  }
}

15.8 Get Prompt Categories

Interface description: Retrieves all prompt categories and their statistics.

Request method: GET

Endpoint: /console/api/prompt_config/categories

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "categories": [
      {
        "name": "多表查询",
        "count": 6,
        "db_types": ["MySQL", "PostgreSQL", "SQL Server", "Oracle", "SQLite", "Trino", "电科金仓（KingBase）", "OceanBase（MySQL 租户模式）", "达梦（DMBase）"]
      },
      {
        "name": "查询策略",
        "count": 1,
        "db_types": ["通用"]
      },
      {
        "name": "结果融合",
        "count": 1,
        "db_types": ["通用"]
      },
      {
        "name": "重试提示",
        "count": 2,
        "db_types": ["通用"]
      }
    ],
    "db_types": ["MySQL", "PostgreSQL", "SQL Server", "Oracle", "SQLite", "Trino", "电科金仓（KingBase）", "OceanBase（MySQL 租户模式）", "达梦（DMBase）", "通用"]
  }
}

15.9 Script Sync Tool

Notes: In addition to the API endpoints, a command-line script is provided to sync prompt files to the database.

Script location: scripts/sync_prompts_to_db.py

Usage:

# 1. Enter the project directory
cd OntiCards_Api

# 2. Run the sync script (requires a Flask app context)
python scripts/sync_prompts_to_db.py

Interactive menu:

============================================================
Prompt Sync Tool
============================================================
[1] Sync all prompts to the database
[2] List prompts in the database
[3] Clear all prompts (caution)
[4] Exit

Programmatic invocation:

from app import app
from controllers.prompt_config.sync_prompts_to_db import sync_all_prompts

with app.app_context():
    result = sync_all_prompts()
    print(result)
    # {'success': [...], 'failed': [...], 'total': 17}

16. Business Glossary Management Module

The business glossary module provides complete term management, supporting the creation of glossaries, management of business terms, importing terms from templates, and linking glossaries to data sources. This module is primarily used for term expansion and rewriting in NL2SQL scenarios, helping the system understand natural-language queries more accurately.

Core features:

• Glossary management: create, query, update and delete glossaries

• Business term management: add, edit and delete business terms within a glossary

• Term templates: quickly import industry terms from built-in templates

• Data source linking: link a glossary to a data source for automatic term recognition and rewriting

Use cases:

• When a user types "query GMV", the system recognizes "GMV" as a business term and expands it to "成交总额" (gross merchandise value)

• Multiple aliases can map to the same canonical term, e.g. "订单金额" and "交易额" both map to "GMV"

• Different data sources can be linked to different glossaries for precise term recognition

16.1 Glossary Management

16.1.1 Get Glossary List

Interface description: Retrieves the current user's glossaries, with pagination, search, category and status filtering.

Request method: GET

Endpoint: /console/api/business_term/libraries

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "电商术语库",
        "description": "电商领域常用术语",
        "category": "电商",
        "status": "active",
        "term_count": 25,
        "created_at": "2026-05-14T10:00:00",
        "updated_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 5,
      "total_pages": 1
    }
  }
}

Response field descriptions:

16.1.2 Create a Glossary

Interface description: Creates a new glossary.

Request method: POST

Endpoint: /console/api/business_term/libraries

Authentication required: Yes

Request parameters (Body):

{
  "name": "电商术语库",
  "description": "电商领域常用术语",
  "category": "电商"
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid",
    "name": "电商术语库",
    "message": "创建成功"
  }
}

Error response:

{
  "code": 409,
  "msg": "术语库 '电商术语库' 已存在",
  "data": null
}

16.1.3 Get Glossary Details

Interface description: Retrieves the details of a specified glossary, including all terms within it (paginated).

Request method: GET

Endpoint: /console/api/business_term/libraries/

Authentication required: Yes

Path parameters:

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "name": "电商术语库",
    "description": "电商领域常用术语",
    "category": "电商",
    "status": "active",
    "term_count": 2,
    "created_at": "2026-05-14T10:00:00",
    "updated_at": "2026-05-14T10:00:00",
    "terms": [
      {
        "id": "uuid",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "status": "active",
        "created_at": "2026-05-14T10:00:00"
      }
    ],
    "terms_pagination": {
      "page": 1,
      "page_size": 100,
      "total": 2,
      "total_pages": 1
    }
  }
}

Response field descriptions:

16.1.4 Update a Glossary

Interface description: Updates the information of a specified glossary.

Request method: PUT

Endpoint: /console/api/business_term/libraries/

Authentication required: Yes

Path parameters:

Request parameters (Body):

{
  "name": "电商术语库（更新）",
  "description": "电商领域常用术语（已更新）",
  "status": "active"
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "updated_fields": ["name", "description"],
    "message": "更新成功"
  }
}

16.1.5 Delete a Glossary

Interface description: Deletes the specified glossary along with all terms it contains (cascading delete).

Request method: DELETE

Endpoint: /console/api/business_term/libraries/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid",
    "message": "删除成功，关联术语一并删除"
  }
}

Notes: Deleting a glossary also deletes all terms within it and the links between data sources and the glossary.

16.2 Business Term Management

16.2.1 Get Term List

Interface description: Retrieves the term list, with filtering by glossary, pagination, search and status.

Request method: GET

Endpoint: /console/api/business_term/list

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "library_id": "uuid",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "applicable_conditions": "适用于电商场景",
        "status": "active",
        "created_at": "2026-05-14T10:00:00",
        "updated_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 50,
      "total_pages": 3
    }
  }
}

Response field descriptions:

16.2.2 Create a Term

Interface description: Creates a new term in the specified glossary.

Request method: POST

Endpoint: /console/api/business_term/list

Authentication required: Yes

Request parameters (Body):

{
  "library_id": "uuid",
  "term_name": "GMV",
  "term_alias": ["成交总额", "交易总额"],
  "term_definition": "商品交易总额",
  "applicable_conditions": "适用于电商场景",
  "remarks": "核心指标"
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "创建成功",
  "data": {
    "id": "uuid",
    "term_name": "GMV",
    "message": "创建成功"
  }
}

Error response:

{
  "code": 409,
  "msg": "术语 'GMV' 已存在",
  "data": null
}

16.2.3 Get Term Details

Interface description: Retrieves the details of a specified term.

Request method: GET

Endpoint: /console/api/business_term/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid",
    "library_id": "uuid",
    "term_name": "GMV",
    "term_alias": ["成交总额", "交易总额"],
    "term_definition": "商品交易总额",
    "applicable_conditions": "适用于电商场景",
    "remarks": "核心指标",
    "related_datacards": [],
    "related_fields": [],
    "related_terms": [],
    "status": "active",
    "created_at": "2026-05-14T10:00:00",
    "updated_at": "2026-05-14T10:00:00"
  }
}

16.2.4 Update a Term

Interface description: Updates the information of a specified term.

Request method: PUT

Endpoint: /console/api/business_term/

Authentication required: Yes

Path parameters:

Request parameters (Body):

{
  "term_name": "GMV（更新）",
  "term_alias": ["成交总额", "交易总额", "总GMV"],
  "term_definition": "商品交易总额（已更新）",
  "status": "active"
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "updated_fields": ["term_name", "term_alias"],
    "message": "更新成功"
  }
}

16.2.5 Delete a Term

Interface description: Deletes the specified term.

Request method: DELETE

Endpoint: /console/api/business_term/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "id": "uuid",
    "message": "删除成功"
  }
}

16.3 Term Template Management

16.3.1 Get Template Categories

Interface description: Retrieves category statistics for all term templates, including the template names and term counts within each category.

Request method: GET

Endpoint: /console/api/business_term/templates/categories

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "categories": [
      {
        "category": "电商",
        "templates": [
          {
            "template_name": "电商核心指标",
            "count": 15
          },
          {
            "template_name": "电商用户行为",
            "count": 10
          }
        ]
      },
      {
        "category": "金融",
        "templates": [
          {
            "template_name": "金融风控指标",
            "count": 20
          }
        ]
      }
    ]
  }
}

Response field descriptions:

16.3.2 Get Template List

Interface description: Retrieves the list of term templates, with filtering by category and template name.

Request method: GET

Endpoint: /console/api/business_term/templates

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "category": "电商",
        "template_name": "电商核心指标",
        "term_name": "GMV",
        "term_alias": ["成交总额", "交易总额"],
        "term_definition": "商品交易总额",
        "applicable_conditions": "适用于电商场景"
      }
    ],
    "total": 15
  }
}

Response field descriptions:

16.3.3 Import Terms from a Template

Interface description: Imports terms in bulk from built-in templates into the specified glossary. Supports importing by template ID, category or template name.

Request method: POST

Endpoint: /console/api/business_term/templates/import

Authentication required: Yes

Request parameters (Body):

{
  "library_id": "uuid",
  "template_ids": ["uuid1", "uuid2"],
  "category": "电商",
  "template_name": "电商核心指标"
}

Request field descriptions:

Notes: At least one of template_ids, category and template_name must be provided.

Response example:

{
  "code": 200,
  "msg": "导入完成",
  "data": {
    "imported_count": 12,
    "skipped_count": 3,
    "message": "导入成功 12 个，跳过 3 个（已存在）",
    "skipped_items": ["GMV", "DAU", "MAU"]
  }
}

Response field descriptions:

16.4 Data Source–Glossary Link Management

16.4.1 Get the Glossaries Linked to a Data Source

Interface description: Retrieves the glossaries already linked to the specified data source, with pagination and status filtering.

Request method: GET

Endpoint: /console/api/business_term/datasource//libraries

Authentication required: Yes

Path parameters:

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "datasource_id": "uuid",
        "library_id": "uuid",
        "library_name": "电商术语库",
        "library_category": "电商",
        "term_count": 25,
        "is_enabled": true,
        "added_at": "2026-05-14T10:00:00"
      }
    ],
    "pagination": {
      "page": 1,
      "page_size": 20,
      "total": 3,
      "total_pages": 1
    }
  }
}

Response field descriptions:

16.4.2 Link a Glossary to a Data Source

Interface description: Links a glossary to the specified data source.

Request method: POST

Endpoint: /console/api/business_term/datasource//libraries

Authentication required: Yes

Path parameters:

Request parameters (Body):

{
  "library_id": "uuid",
  "is_enabled": true
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "添加成功",
  "data": {
    "id": "uuid",
    "datasource_id": "uuid",
    "library_id": "uuid",
    "library_name": "电商术语库",
    "is_enabled": true,
    "message": "术语库添加成功"
  }
}

Error response:

{
  "code": 409,
  "msg": "术语库 '电商术语库' 已添加到此数据源",
  "data": null
}

16.4.3 Update a Data Source's Glossary Link Status

Interface description: Updates the status of a glossary linked to a data source (enable/disable).

Request method: PUT

Endpoint: /console/api/business_term/datasource//libraries/

Authentication required: Yes

Path parameters:

Request parameters (Body):

{
  "is_enabled": false
}

Request field descriptions:

Response example:

{
  "code": 200,
  "msg": "更新成功",
  "data": {
    "id": "uuid",
    "is_enabled": false,
    "message": "状态更新成功"
  }
}

16.4.4 Remove a Glossary from a Data Source

Interface description: Removes the linked glossary from a data source.

Request method: DELETE

Endpoint: /console/api/business_term/datasource//libraries/

Authentication required: Yes

Path parameters:

Response example:

{
  "code": 200,
  "msg": "移除成功",
  "data": {
    "id": "uuid",
    "message": "术语库 '电商术语库' 已从数据源移除"
  }
}

16.4.5 Get Glossaries Available to a Data Source

Interface description: Retrieves the glossaries that can be added to a data source (glossaries not yet linked), with search and filtering.

Request method: GET

Endpoint: /console/api/business_term/datasource//available

Authentication required: Yes

Path parameters:

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid",
        "name": "金融术语库",
        "description": "金融领域常用术语",
        "category": "金融",
        "status": "active",
        "term_count": 30,
        "created_at": "2026-05-14T10:00:00"
      }
    ],
    "total": 5
  }
}

Notes: This endpoint only returns glossaries with a status of active that are not yet linked to the data source.

Response field descriptions:

17. Data Governance Module - Data Quality Check (Phase 1)

Module overview: Data governance is delivered in two phases. Phase 1 is data quality check (implemented), and Phase 2 is actual remediation (planned).

This chapter documents all endpoints of Phase 1 "data quality check", covering the full chain of rule library management, rule management, rule execution and report generation.

For Phase 2 "remediation" endpoints, see Chapter 18.

Base path: /console/api/governance

Core features:

• Rule library management: create, query, update and delete rule libraries

• Rule management: three creation modes (manual/expert, AI natural language, template import), rule parsing, SQL preview, rule suggestions

• Rule execution: batch rule execution, basic null-value checks, table relationship discovery

• Report generation: generate downloadable quality check reports (MD/DOCX/PDF/XLSX formats)

• Quality overview: data quality score, rating and trend analysis

Endpoint summary:

17.1 Rule Library Management

17.1.1 Get Rule Library List

Interface description: Paginated retrieval of the current user's rule libraries, with search and data source filtering.

Request method: GET

Endpoint: /console/api/governance/libraries

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "name": "订单数据质量规则库",
        "description": "针对订单表的数据质量检测",
        "datasource_id": "uuid-string",
        "connect_name": "生产库A",
        "database_name": "ecommerce_db",
        "datasource_db_type": "mysql",
        "status": "active",
        "rule_count": 15,
        "created_at": "2026-06-01T10:00:00"
      }
    ],
    "total": 5,
    "page": 1,
    "page_size": 20,
    "pages": 1
  }
}

17.1.2 Create a Rule Library

Interface description: Creates a new rule library, which must be linked to a data source.

Request method: POST

Endpoint: /console/api/governance/libraries

Authentication required: Yes

Request parameters:

Request example:

{
  "name": "订单数据质量规则库",
  "datasource_id": "550e8400-e29b-41d4-a716-446655440000",
  "description": "针对订单表的数据质量检测"
}

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "name": "订单数据质量规则库",
    "datasource_id": "uuid-string",
    "datasource_name": "生产库A",
    "description": "针对订单表的数据质量检测",
    "status": "active",
    "created_at": "2026-06-01T10:00:00"
  }
}

Error response:

{
  "code": 400,
  "msg": "datasource_id 不能为空，创建规则库必须关联数据源"
}

17.1.3 Get Rule Library Details

Interface description: Retrieves the details of a specified rule library, including the rule list and data source information.

Request method: GET

Endpoint: /console/api/governance/libraries/

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "name": "订单数据质量规则库",
    "description": "针对订单表的数据质量检测",
    "datasource_id": "uuid-string",
    "datasource": {
      "id": "uuid-string",
      "name": "生产库A",
      "db_type": "mysql"
    },
    "rules": [
      {
        "id": "uuid-string",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "target_table": "orders",
        "target_column": "phone",
        "severity": "critical",
        "enabled": true
      }
    ],
    "created_at": "2026-06-01T10:00:00"
  }
}

17.1.4 Update a Rule Library

Interface description: Updates a rule library's name, description or status.

Request method: PUT

Endpoint: /console/api/governance/libraries/

Authentication required: Yes

Request parameters:

Request example:

{
  "name": "更新后的规则库名称",
  "status": "inactive"
}

17.1.5 Delete a Rule Library

Interface description: Deletes a rule library (all rules under it are deleted in cascade).

Request method: DELETE

Endpoint: /console/api/governance/libraries/

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "删除成功"
}

17.2 Rule Management

17.2.1 Get Rule List

Interface description: Retrieves the rule list, with filtering by rule library, rule type, enabled status and creation source.

Request method: GET

Endpoint: /console/api/governance/rules

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "items": [
      {
        "id": "uuid-string",
        "library_id": "uuid-string",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "rule_type_name": "空值检测",
        "target_table": "orders",
        "target_column": "phone",
        "condition_expr": "phone IS NOT NULL",
        "severity": "critical",
        "enabled": true,
        "create_source": "template",
        "created_at": "2026-06-01T10:00:00"
      }
    ],
    "total": 50,
    "page": 1,
    "page_size": 20,
    "pages": 3
  }
}

17.2.2 Create a Rule

Interface description: Creates a new rule, with three supported modes.

Request method: POST

Endpoint: /console/api/governance/rules

Authentication required: Yes

Request parameters:

Rule type reference:

Request example (manual/expert mode):

{
  "library_id": "uuid-string",
  "rule_name": "订单金额必须为正数",
  "rule_type": "threshold",
  "target_table": "orders",
  "target_column": "total_amount",
  "condition_expr": "total_amount > 0",
  "severity": "critical",
  "enabled": true
}

Request example (composite rule mode):

{
  "library_id": "uuid-string",
  "rule_name": "订单完整性检测",
  "rule_type": "composite",
  "target_table": "orders",
  "conditions": [
    {"column": "customer_id", "condition": "customer_id IS NOT NULL"},
    {"column": "total_amount", "condition": "total_amount > 0"},
    {"column": "order_date", "condition": "order_date IS NOT NULL"}
  ],
  "condition_mode": "AND",
  "severity": "critical"
}

Request example (AI natural-language mode):

{
  "library_id": "uuid-string",
  "rule_name": "订单金额检测",
  "create_source": "ai",
  "rule_config": {
    "target_table": "orders",
    "target_column": "total_amount",
    "rule_type": "threshold",
    "condition_expr": "total_amount > 0",
    "severity": "warning"
  }
}

17.2.3 Get Rule Details

Request method: GET

Endpoint: /console/api/governance/rules/

Authentication required: Yes

17.2.4 Update a Rule

Request method: PUT

Endpoint: /console/api/governance/rules/

Authentication required: Yes

Query parameters:

Body parameters:

Notes:

• Updating conditions automatically switches the rule to composite rule mode.

• target_column is not updated in composite rule mode.

• Switching from composite mode to a non-composite mode clears conditions_config.

17.2.5 Delete a Rule

Request method: DELETE

Endpoint: /console/api/governance/rules/

Authentication required: Yes

Query parameters:

17.2.6 Enable/Disable a Rule

Interface description: Toggles the enabled status of a rule.

Request method: PUT

Endpoint: /console/api/governance/rules//toggle

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "enabled": false,
    "msg": "禁用成功"
  }
}

17.2.7 Test-Execute a Single Rule

Interface description: Verifies that a rule is configured correctly by executing it immediately and returning the result.

Request method: POST

Endpoint: /console/api/governance/rules/execute

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "uuid-string",
    "rule_id": "uuid-string",
    "rule_name": "手机号非空检测",
    "rule_type": "null_check",
    "table_name": "orders",
    "column_name": "phone",
    "total_count": 10000,
    "passed_count": 9980,
    "failed_count": 20,
    "failed_rate": 0.20,
    "status": "passed",
    "execution_time_ms": 125
  }
}

17.3 Rule Parsing and Suggestions

17.3.1 Rule Parsing (Natural Language → Structured Rule)

Interface description: Parses a natural-language rule description into a structured rule configuration, supporting two-stage interaction (parse + confirm).

Request method: POST

Endpoint: /console/api/governance/rules/parse

Authentication required: Yes

Request parameters:

Response example (Stage 1 – parsed successfully):

{
  "code": 200,
  "data": {
    "success": true,
    "needs_confirmation": false,
    "stage": "rule_preview",
    "confidence": 0.95,
    "rule_config": {
      "rule_type": "threshold",
      "target_table": "orders",
      "target_column": "total_amount",
      "condition_expr": "total_amount > 0",
      "severity": "warning"
    },
    "sql_preview": "SELECT * FROM orders WHERE NOT (total_amount > 0) LIMIT 20",
    "reasoning": "检测到数值类型的金额字段，建议使用阈值规则"
  }
}

Response example (Stage 1 – confirmation required):

{
  "code": 200,
  "data": {
    "success": true,
    "needs_confirmation": true,
    "stage": "table_selection",
    "confidence": 0.7,
    "rule_config": null,
    "candidates": {
      "type": "table",
      "items": [
        {"name": "orders", "score": 0.9, "reason": "表名匹配", "description": "订单主表"},
        {"name": "sales_orders", "score": 0.7, "reason": "实体匹配", "description": "销售订单"}
      ]
    },
    "reasoning": "找到多个候选表，请确认"
  }
}

17.3.2 SQL Preview

Interface description: Generates and previews the detection SQL from a rule configuration, with four supported modes.

Request method: POST

Endpoint: /console/api/governance/rules/preview

Authentication required: Yes

Request parameters (template mode):

Request parameters (single-condition expert mode):

Request parameters (composite rule mode):

Mode priority: template_id > conditions > condition_expr > auto

Response example:

{
  "code": 200,
  "data": {
    "success": true,
    "sql": "SELECT * FROM orders WHERE NOT (total_amount > 0) LIMIT 20",
    "scope": "column",
    "mode": "expert",
    "rule_type": "threshold",
    "rule_type_label": "阈值检测",
    "description": "专家模式：直接使用用户输入的条件",
    "template_name": null
  }
}

Response field descriptions:

17.3.3 Rule Suggestions

Interface description: Recommends applicable rule templates based on the data source schema.

Request method: POST

Endpoint: /console/api/governance/rules/suggest

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "data": {
    "success": true,
    "source": "llm",
    "suggestions": [
      {
        "table": "users",
        "column": "phone",
        "column_comment": "手机号码",
        "data_type": "varchar(20)",
        "rule_type": "format",
        "rule_name": "手机号格式检测",
        "rule_description": "手机号应为11位，以1开头",
        "confidence": 0.95,
        "reasoning": "基于列名和注释推断为手机号字段，建议进行格式校验"
      },
      {
        "table": "orders",
        "column": "total_amount",
        "column_comment": "订单总金额",
        "data_type": "decimal(10,2)",
        "rule_type": "threshold_positive",
        "rule_name": "正数检测",
        "rule_description": "金额字段建议检测正数",
        "confidence": 0.90,
        "reasoning": "基于列名和注释推断为金额字段，建议检测正数"
      }
    ]
  }
}

Response field descriptions:

17.4 Rule Execution Engine (Core of Stage 2)

17.4.1 Batch Execute Rules

Interface description: Executes the rules in a rule library, collects quality check results and generates a report. This is the core endpoint of the data quality check phase.

Request method: POST

Endpoint: /console/api/governance/execute

Authentication required: Yes

Request parameters:

Notes: If neither library_ids nor rule_ids is provided, only basic null-value checks are executed.

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "report_id": "uuid-string",
    "quality_score": 85.5,
    "grade": "良好",
    "summary": {
      "total_rules": 20,
      "passed_rules": 17,
      "failed_rules": 3,
      "error_rules": 0,
      "quality_score": 85.0,
      "grade": "良好"
    },
    "execution_time": "2026-07-21T14:30:00",
    "basic_audit": {
      "tables_count": 5,
      "tables": [...]
    },
    "basic_audit_detail": {
      "rules_count": 15,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": null,
          "rule_name": "空值检测: users.phone",
          "rule_type": "null_check",
          "severity": "warning",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.20,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "quality_audit": {
      "rules_count": 5,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": "rule-uuid",
          "rule_name": "手机号非空检测",
          "rule_type": "null_check",
          "severity": "critical",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.20,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "relation_discovery": {
      "tables_count": 20,
      "relationships_count": 15,
      "cards_count": 10,
      "statistics": {...},
      "relationships": [...],
      "cards": [...]
    }
  }
}

Response field descriptions:

Quality score calculation:

• Pass rate = passed_count / total_count × 100

• Severity deduction = critical_fails × 5 + warning_fails × 2

• Final score = max(0, min(100, pass rate - deduction))

Quality grade thresholds:

17.5 Report Management

17.5.1 Get Report List

Request method: GET

Endpoint: /console/api/governance/reports

Authentication required: Yes

Query parameters:

17.5.2 Get Report Details

Request method: GET

Endpoint: /console/api/governance/reports/

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "id": "report-uuid",
    "user_id": "user-uuid",
    "datasource_id": "datasource-uuid",
    "report_name": "质检结果_2026-07-23",
    "execution_time": "2026-07-23T10:30:00",
    "scope_tables": null,
    "rules_applied": 20,
    "include_quality": true,
    "include_basic_audit": true,
    "include_relationship": false,
    "quality_score": 85.5,
    "grade": "良好",
    "basic_audit_result": {
      "users": {
        "columns": {
          "phone": {"null_count": 20, "null_rate": 0.002, "total_count": 10000},
          "email": {"null_count": 5, "null_rate": 0.0005, "total_count": 10000}
        },
        "total_count": 10000
      }
    },
    "basic_audit_detail": {
      "rules_count": 15,
      "results": [
        {
          "id": "result-uuid",
          "rule_id": null,
          "rule_name": "空值检测: users.phone",
          "rule_type": "null_check",
          "severity": "warning",
          "table_name": "users",
          "column_name": "phone",
          "total_count": 10000,
          "passed_count": 9980,
          "failed_count": 20,
          "failed_rate": 0.002,
          "failed_samples": [...],
          "status": "passed"
        }
      ]
    },
    "full_relation_discovery": null,
    "quality_audit_result": [
      {
        "id": "result-uuid",
        "rule_id": "rule-uuid",
        "rule_name": "手机号非空检测",
        "rule_type": "null_check",
        "severity": "critical",
        "table_name": "users",
        "column_name": "phone",
        "total_count": 10000,
        "passed_count": 9980,
        "failed_count": 20,
        "failed_rate": 0.002,
        "failed_samples": [...],
        "status": "passed"
      }
    ],
    "summary": {
      "total_rules": 20,
      "passed_rules": 18,
      "failed_rules": 2,
      "error_rules": 0,
      "quality_score": 85.0,
      "grade": "良好"
    },
    "created_at": "2026-07-23T10:30:00",
    "exported_file_path": "/exports/report_xxx.docx",
    "exported_file_type": "docx",
    "exported_file_name": "质检报告_2026年07月23日.docx",
    "file_size": 123456,
    "file_created_at": "2026-07-23T11:00:00",
    "file_status": "completed",
    "file_error_msg": null,
    "has_export": true,
    "history_files": [
      {
        "id": "file-uuid",
        "file_name": "质检报告_2026年07月23日.docx",
        "file_path": "/exports/report_xxx.docx",
        "file_type": "docx",
        "file_size": 123456,
        "created_at": "2026-07-23T11:00:00"
      }
    ]
  }
}

Response field descriptions:

17.5.3 Delete a Report

Request method: DELETE

Endpoint: /console/api/governance/reports/

Authentication required: Yes

Response example:

{
  "code": 200,
  "msg": "删除成功",
  "data": {
    "report_id": "uuid-string",
    "files_deleted": 2,
    "files_not_found": [],
    "rule_execution_results_cleared": "cascade",
    "table_relationships_deleted": 5,
    "table_relationship_cards_deleted": 3
  }
}

Response field descriptions:

17.5.4 Rename a Report

Request method: PUT

Endpoint: /console/api/governance/reports/

Authentication required: Yes

Request parameters:

Request example:

{
  "report_name": "新的报告名称_2026-07-23"
}

Response example:

Successful response:

{
  "code": 200,
  "msg": "修改成功",
  "data": {
    "report_id": "uuid-string",
    "report_name": "新的报告名称_2026-07-23",
    "files_updated": 3,
    "updated_at": "2026-07-23T10:30:00"
  }
}

Failure response (report not found):

{
  "code": 404,
  "msg": "报告不存在"
}

Failure response (empty name):

{
  "code": 400,
  "msg": "report_name 不能为空"
}

Failure response (name too long):

{
  "code": 400,
  "msg": "报告名称不能超过255个字符"
}

Response field descriptions:

Synchronized update notes:

This endpoint updates the following two tables in sync to keep the data consistent:

Fields that are not affected:

Frontend impact:

• The report name shown in the report list updates to the new value.

• The report_name field of each historical record in the history_files list on the report detail page is also updated.

• The file names of already-downloaded/generated reports do not change (a new generation is required for the name change to take effect in the file name).

17.5.5 Download a Report File

Interface description: Downloads the report document file, with support for downloading historical files.

Request method: GET

Endpoint: /console/api/governance/reports//download

Authentication required: Yes

Query parameters:

17.5.6 Delete a Report File

Request method: DELETE

Endpoint: /console/api/governance/reports//file

Authentication required: Yes

17.5.7 Delete an Exported File Record

Request method: DELETE

Endpoint: /console/api/governance/files/

Authentication required: Yes

17.6 Report Generation (Core of Stage 3)

17.6.1 Generate a Report Document

Interface description: Generates a downloadable document from an existing report (report_id). This is the final output endpoint of the data quality check phase.

Request method: POST

Endpoint: /console/api/governance/report

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "report_id": "uuid-string",
    "file_path": "/path/to/report.docx",
    "file_name": "质检报告_2026年07月21日.docx",
    "file_size": 12345,
    "format": "docx",
    "mode": "soffice"
  }
}

Generation mode reference:

Report document structure (six sections):

1. Basic information

1. Quality overview (summary of the three quality check modules)

1. Basic null-value check results (grouped by table)

1. Execution details (rule-library based)

1. Failed sample details (all violating field records)

1. LLM smart summary + improvement suggestions

17.6.2 Query Report Document Generation Status

Interface description: Queries the generation status of a report document.

Request method: GET

Endpoint: /console/api/governance/report/

Authentication required: Yes

Response example:

{
  "code": 200,
  "data": {
    "report_id": "uuid-string",
    "file_status": "completed",
    "file_error_msg": null,
    "exported_file_name": "质检报告_2026年07月21日.docx",
    "exported_file_path": "/path/to/report.docx",
    "file_size": 12345
  }
}

file_status values:

17.7 Rule Templates

17.7.1 Get System Template List

Interface description: Retrieves all built-in rule templates, with grouping by type and keyword search.

Request method: GET

Endpoint: /console/api/governance/templates

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "groups": [
      {
        "rule_type": "null_check",
        "rule_type_name": "空值检测",
        "templates": [
          {
            "id": "uuid-string",
            "template_id": "tmpl-null-check",
            "template_name": "空值检测",
            "default_condition": "column IS NOT NULL",
            "applicable_columns": ["varchar", "text", "int", "decimal"]
          }
        ]
      }
    ],
    "total": 27
  }
}

17.7.2 Get Template Details

Request method: GET

Endpoint: /console/api/governance/templates/

Authentication required: Yes

17.7.3 Import Rules from a Template

Interface description: Creates rules based on a template.

Request method: POST

Endpoint: /console/api/governance/templates/import

Authentication required: Yes

Request parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "imported_count": 2,
    "target_table": "orders",
    "target_column": null,
    "rules": [
      {
        "id": "rule-uuid",
        "rule_name": "空值检测(orders)",
        "rule_type": "null_check",
        "target_table": "orders",
        "severity": "warning",
        "enabled": true
      }
    ]
  }
}

17.8 Governance Overview and Metadata

17.8.1 Quality Overview

Interface description: Retrieves the governance module's home-page statistics, including score, grade, trends, dimension scores and a summary of critical findings.

Request method: GET

Endpoint: /console/api/governance/quality/overview

Authentication required: Yes

Query parameters:

Response example:

{
  "code": 200,
  "msg": "success",
  "data": {
    "quality_score": 85.5,
    "grade": "良好",
    "report_count": 50,
    "library_count": 5,
    "rule_count": 120,
    "enabled_rule_count": 100,
    "dimensions": {
      "completeness": 92.5,
      "uniqueness": 88.0,
      "validity": 85.0,
      "consistency": 90.0,
      "timeliness": 95.0,
      "composite": 80.0
    },
    "critical_findings": [
      {
        "rule_name": "手机号非空检测",
        "table_name": "users",
        "column_name": "phone",
        "failed_count": 20,
        "failed_rate": 0.002,
        "status": "failed",
        "severity": "critical",
        "rule_id": "rule-uuid",
        "report_id": "report-uuid"
      }
    ],
    "report_trend": [
      {
        "date": "2026-07-20",
        "count": 5,
        "avg_score": 87.5
      }
    ],
    "rule_type_stats": [
      {
        "type": "null_check",
        "type_name": "空值检测",
        "count": 50,
        "percentage": 41.7
      }
    ],
    "date_range": {
      "start": "2026-06-21T00:00:00",
      "end": "2026-07-21T00:00:00",
      "range": "30d"
    }
  }
}

Response field descriptions:

17.8.2 Get All Tables in a Data Source

Request method: GET

Endpoint: /console/api/governance/datasources//tables

Authentication required: Yes

17.8.3 Get the Columns of a Specified Table

Request method: GET

Endpoint: /console/api/governance/datasources//tables//columns

Authentication required: Yes

17.9 End-to-End Data Quality Check Flow

End-to-End Data Quality Check Flow (implemented)
=================================================

[Stage 1: Rule Creation]
------------------------
  User actions
    - Manual expert mode: enter SQL conditions directly
    - AI NL mode: enter "order amount must not be negative" -> LLM parses -> user confirms
    - Template import mode: pick a preset template, fill in table/column
    - Rule suggestions: smart recommendations based on the schema

  Core endpoints
    - POST /governance/rules/parse    -> NL parsing
    - POST /governance/rules/preview  -> SQL preview & validation
    - POST /governance/rules          -> create rule

[Stage 2: Rule Execution]
-------------------------
  POST /governance/execute  (core endpoint)

  Input:
    {
      datasource_id: "xxx",
      library_ids: ["lib1", "lib2"],
      include_basic_audit: true,
      include_relation_discovery: true
    }

  Execution:
    1. AuditExecutor.execute_only() -> run rules in the library
    2. Basic null-value checks (optional)
    3. Table relation discovery (optional)
    4. Compute quality score + update the report
    5. Save to execution_response (single source of truth)

  Output:
    {
      report_id: "xxx",
      quality_score: 85.5,
      grade: "good",
      summary: {...}
    }

[Stage 3: Report Generation]
----------------------------
  POST /governance/report  (core endpoint)

  Input:
    {
      report_id: "xxx",     // from Stage 2
      format: "docx",       // docx/pdf/xlsx/md
      file_name: "custom name"
    }

  Execution:
    1. Read execution_response
    2. LibreOfficeExporter / MarkdownExporter generate the document
    3. Record the file in governance_report_files

  Output:
    {
      report_id: "xxx",
      file_path: "/path/to/report.docx",
      file_name: "quality_report_2026-07-21.docx",
      file_size: 12345,
      mode: "soffice"
    }

18. Data Governance Module - Remediation (Phase 2)

Module overview: Phase 2 is the actual remediation stage, which executes targeted remediation actions based on the problems identified during Phase 1 data quality checks.

Examples include: reconciliation difference handling, repairing/backfilling problem data, data quarantine/cleaning, alert notifications, etc.

The content of this chapter is pending implementation and will be supplemented with the specific API documentation once complete.

Error Code Reference

Notes

1. Authentication: Most interfaces require login authentication. Carry a valid Session Cookie or JWT Token in the request header.

1. Data source connections: Connection parameters differ by database type. Refer to the required-parameter notes for each database.

1. Async operations: Schema extraction is asynchronous. A request ID is returned immediately, and the actual processing runs in the background.

1. Vector retrieval: Data card queries use vector retrieval and require a configured Weaviate vector database.

1. SQL generation: The AI query feature relies on an LLM to generate SQL and requires the corresponding API key to be configured.

1. File upload: Excel file uploads are limited to 20MB and support both .xlsx and .xls formats.

1. Pagination: List interfaces support pagination. Set page_size sensibly to avoid performance issues.

Project Feature Overview

Core Features

1. Multi-source management: Supports MySQL, PostgreSQL, SQL Server, Oracle, SQLite, Trino, KingBase, OceanBase (MySQL tenant mode), DMBase, and other databases

1. Intelligent schema extraction: Automatically extracts database table schemas and generates standardized data cards

1. Vector retrieval: Semantic retrieval over data cards, backed by the Weaviate vector database

1. AI-powered SQL generation: Uses LLM technology to generate SQL queries from natural-language questions

1. Cross-source queries: Supports federated queries across data sources with multiple fusion strategies

1. Business glossary: Create and manage business glossaries to support term recognition and rewriting in NL2SQL scenarios, improving query accuracy

1. Data quality auditing: Performs data quality checks on database tables, counting NULLs, empty strings, and more

1. User permission management: A complete permission system covering users, user groups, and roles

Technical Architecture

• Backend framework: Flask + Flask-RESTful

• Database ORM: SQLAlchemy

• Vector database: Weaviate

• Base chat: qwen-max-latest

• Reranking: Qwen's gte-rerank-v2

• Text embedding: Qwen's text-embedding-v3

• LLM integration: Supports Qwen and other large language models

• Supported databases: MySQL, PostgreSQL, SQL Server, Oracle, SQLite, Trino, KingBase, OceanBase (MySQL tenant mode), DMBase

Business Process

1. Data source onboarding: The user configures the database connection info; the system tests the connection and extracts the table schemas

1. Data card generation: The system automatically generates a data card for each table, including schema, field descriptions, and other information

1. Vector storage: Data card content is vectorized and stored in Weaviate to support semantic retrieval

1. AI query: The user enters a natural-language question; the system retrieves the relevant data cards, generates SQL, and executes it

1. Result fusion: For multi-source queries, results are merged according to the fusion strategy

Appendix

Database Connection String Examples

MySQL:

mysql+pymysql://username:password@host:port/database

PostgreSQL:

postgresql+psycopg://username:password@host:port/database

SQL Server:

mssql+pyodbc://username:password@dsn_name/database
or
mssql+pyodbc://username:password@host:port/database?driver=OOntiCards+Driver+17+for+SQL+Server

Oracle:

oracle+oracledb://username:password@host:port/?service_name=SERVICE_NAME
or
oracle+oracledb://username:password@host:port/?sid=SID

SQLite:

sqlite:///path/to/database.db
or
sqlite:///:memory:  (in-memory mode)

Trino:

trino://username@host:port/catalog/schema

KingBase:

postgresql+psycopg://username:password@host:port/database

OceanBase (MySQL tenant mode):

mysql+pymysql://username:password@host:port/database

OceanBase MySQL tenants use the mysql+pymysql protocol (default port 2881), and the connection string format is identical to MySQL. Oracle tenant mode will be supported in a later release.

DMBase:

dm+pymysql://username:password@host:port/database

DMBase uses the dm+pymysql protocol and is compatible with Oracle syntax style.

---

Document version: 1.5.1 Last updated: 2026-08-04 Maintained by: OntiCards development team