Data App 配置文件

本文档描述了 TiDB Cloud 中 Data App 的配置文件。

如果你已经将你的 Data App 连接到 GitHub，你可以在 GitHub 上的指定目录中找到你的 Data App 的配置文件，如下所示：

├── <你的 Data App 目录>
│   ├── data_sources
│   │   └── cluster.json
│   ├── dataapp_config.json
│   ├── http_endpoints
│   │   ├── config.json
│   │   └── sql
│   │       ├── <method>-<endpoint-path1>.sql
│   │       ├── <method>-<endpoint-path2>.sql
│   │       └── <method>-<endpoint-path3>.sql

数据源配置

Data App 的数据源来自其链接的 TiDB 集群。你可以在 data_sources/cluster.json 中找到数据源配置。

├── <你的 Data App 目录>
│   ├── data_sources
│   │   └── cluster.json

对于每个 Data App，你可以链接一个或多个 TiDB 集群。

以下是 cluster.json 的示例配置。在此示例中，此 Data App 有两个链接的集群。

[
  {
    "cluster_id": <集群 ID1>
  },
  {
    "cluster_id": <集群 ID2>
  }
]

字段说明如下：

Data App 配置

Data App 的属性包含 App ID、名称和类型。你可以在 dataapp_config.json 文件中找到这些属性。

├── <你的 Data App 目录>
│   ├── dataapp_config.json

以下是 dataapp_config.json 的示例配置。

{
  "app_id": "<Data App ID>",
  "app_name": "<Data App 名称>",
  "app_type": "dataapi",
  "app_version": "<Data App 版本>",
  "description": "<Data App 描述>"
}

每个字段的说明如下：

HTTP 端点配置

在你的 Data App 目录中，你可以在 http_endpoints/config.json 中找到端点配置，在 http_endpoints/sql/<method>-<endpoint-name>.sql 中找到 SQL 文件。

├── <你的 Data App 目录>
│   ├── http_endpoints
│   │   ├── config.json
│   │   └── sql
│   │       ├── <method>-<endpoint-path1>.sql
│   │       ├── <method>-<endpoint-path2>.sql
│   │       └── <method>-<endpoint-path3>.sql

端点配置

对于每个 Data App，可以有一个或多个端点。你可以在 http_endpoints/config.json 中找到 Data App 的所有端点的配置。

以下是 config.json 的示例配置。在此示例中，此 Data App 有两个端点。

[
  {
    "name": "<端点名称1>",
    "description": "<端点描述1>",
    "method": "<HTTP 方法1>",
    "endpoint": "<端点路径1>",
    "data_source": {
      "cluster_id": <集群 ID1>
    },
    "params": [],
    "settings": {
      "timeout": <端点超时时间>,
      "row_limit": <最大行数>,
      "enable_pagination": <0 | 1>,
      "cache_enabled": <0 | 1>,
      "cache_ttl": <生存时间周期>
    },
    "tag": "Default",
    "batch_operation": <0 | 1>,
    "sql_file": "<SQL 文件目录1>",
    "type": "sql_endpoint",
    "return_type": "json"
  },
  {
    "name": "<端点名称2>",
    "description": "<端点描述2>",
    "method": "<HTTP 方法2>",
    "endpoint": "<端点路径2>",
    "data_source": {
      "cluster_id": <集群 ID2>
    },
    "params": [
      {
        "name": "<参数名称>",
        "type": "<参数类型>",
        "required": <0 | 1>,
        "default": "<参数默认值>",
        "description": "<参数描述>",
        "is_path_parameter": <true | false>
      }
    ],
    "settings": {
      "timeout": <端点超时时间>,
      "row_limit": <最大行数>,
      "enable_pagination": <0 | 1>,
      "cache_enabled": <0 | 1>,
      "cache_ttl": <生存时间周期>
    },
    "tag": "Default",
    "batch_operation": <0 | 1>,
    "sql_file": "<SQL 文件目录2>",
    "type": "sql_endpoint",
    "return_type": "json"
  }
]

每个字段的说明如下：

SQL 文件配置

端点的 SQL 文件指定了通过端点查询数据的 SQL 语句。你可以在 http_endpoints/sql/ 目录中找到 Data App 的端点 SQL 文件。每个端点都应该有一个对应的 SQL 文件。

SQL 文件的名称格式为 <method>-<endpoint-path>.sql，其中 <method> 和 <endpoint-path> 必须与 http_endpoints/config.json 中的 method 和 endpoint 配置匹配。

在 SQL 文件中，你可以编写表连接查询、复杂查询和聚合函数等语句。以下是一个示例 SQL 文件。

/* 入门：
在输入 SQL 语句之前，输入 "USE {database};"。
输入 "--你的问题" + Enter 可以在 TiDB Cloud 控制台中尝试 AI 生成的 SQL 查询。
声明参数的格式为 "Where id = ${arg}"。
*/
USE sample_data;
SELECT
  rank,
  company_name,
FROM
  global_fortune_500_2018_2022
WHERE
  country = ${country};

编写 SQL 文件时，请注意以下事项：

• 在 SQL 文件的开头，你需要在 SQL 语句中指定数据库。例如，USE database_name;。

• 要定义端点的参数，你可以将其作为变量占位符（如 ${variable-name}）插入到 SQL 语句中。

  在上述示例中，${country} 用作端点的参数。使用此参数，你可以在端点 curl 命令中指定所需的国家/地区进行查询。

  注意

  • 参数名称区分大小写。
  • 参数不能是表名或列名。
  • SQL 文件中的参数名称必须与 http_endpoints/config.json 中配置的参数名称匹配。