Data App Configuration Files

This document describes the configuration files of a Data App in TiDB Cloud.

If you have connected your Data App to GitHub, you can find the configuration files of your Data App in your specified directory on GitHub as follows:

├── <Your Data App directory>
│   ├── 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 source configuration

The data source of a Data App comes from its linked TiDB clusters. You can find the data source configuration in data_sources/cluster.json.

├── <Your Data App directory>
│   ├── data_sources
│   │   └── cluster.json

For each Data App, you can link to one or multiple TiDB clusters.

The following is an example configuration of cluster.json. In this example, there are two linked clusters for this Data App.

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

The field description is as follows:

Data App configuration

The properties of a Data App contain the App ID, name, and type. You can find the properties in the dataapp_config.json file.

├── <Your Data App directory>
│   ├── dataapp_config.json

The following is an example configuration of dataapp_config.json.

{
  "app_id": "<Data App ID>",
  "app_name": "<Data App name>",
  "app_type": "dataapi",
  "app_version": "<Data App version>",
  "description": "<Data App description>"
}

The description of each field is as follows:

HTTP endpoint configuration

In your Data App directory, you can find endpoint configurations in http_endpoints/config.json and the SQL files in http_endpoints/sql/<method>-<endpoint-name>.sql.

├── <Your Data App directory>
│   ├── http_endpoints
│   │   ├── config.json
│   │   └── sql
│   │       ├── <method>-<endpoint-path1>.sql
│   │       ├── <method>-<endpoint-path2>.sql
│   │       └── <method>-<endpoint-path3>.sql

Endpoint configuration

For each Data App, there can be one or multiple endpoints. You can find the configurations of all endpoints for a Data App in http_endpoints/config.json.

The following is an example configuration of config.json. In this example, there are two endpoints for this Data App.

[
  {
    "name": "<Endpoint name1>",
    "description": "<Endpoint description1>",
    "method": "<HTTP method1>",
    "endpoint": "<Endpoint path1>",
    "data_source": {
      "cluster_id": <Cluster ID1>
    },
    "params": [],
    "settings": {
      "timeout": <Endpoint timeout>,
      "row_limit": <Maximum rows>,
      "enable_pagination": <0 | 1>,
      "cache_enabled": <0 | 1>,
      "cache_ttl": <time-to-live period>
    },
    "tag": "Default",
    "batch_operation": <0 | 1>,
    "sql_file": "<SQL file directory1>",
    "type": "sql_endpoint",
    "return_type": "json"
  },
  {
    "name": "<Endpoint name2>",
    "description": "<Endpoint description2>",
    "method": "<HTTP method2>",
    "endpoint": "<Endpoint path2>",
    "data_source": {
      "cluster_id": <Cluster ID2>
    },
    "params": [
      {
        "name": "<Parameter name>",
        "type": "<Parameter type>",
        "required": <0 | 1>,
        "default": "<Parameter default value>",
        "description": "<Parameter description>",
        "is_path_parameter": <true | false>
      }
    ],
    "settings": {
      "timeout": <Endpoint timeout>,
      "row_limit": <Maximum rows>,
      "enable_pagination": <0 | 1>,
      "cache_enabled": <0 | 1>,
      "cache_ttl": <time-to-live period>
    },
    "tag": "Default",
    "batch_operation": <0 | 1>,
    "sql_file": "<SQL file directory2>",
    "type": "sql_endpoint",
    "return_type": "json"
  }
]

The description of each field is as follows:

SQL file configuration

The SQL file of an endpoint specifies the SQL statements to query data through the endpoint. You can find the endpoint SQL files of a Data App in the http_endpoints/sql/ directory. For each endpoint, there should be a corresponding SQL file.

The name of a SQL file is in the <method>-<endpoint-path>.sql format, where <method> and <endpoint-path> must match the method and endpoint configuration in http_endpoints/config.json.

In the SQL file, you can write statements such as table join queries, complex queries, and aggregate functions. The following is an example SQL file.

/* Getting Started:
Enter "USE {database};" before entering your SQL statements.
Type "--your question" + Enter to try out AI-generated SQL queries in the TiDB Cloud console.
Declare a parameter like "Where id = ${arg}".
*/
USE sample_data;
SELECT
  rank,
  company_name,
FROM
  global_fortune_500_2018_2022
WHERE
  country = ${country};

When writing a SQL file, pay attention to the following:

• At the beginning of the SQL file, you need to specify the database in the SQL statements. For example, USE database_name;.

• To define a parameter of the endpoint, you can insert it as a variable placeholder like ${variable-name} to the SQL statement.

  In the preceding example, ${country} is used as a parameter of the endpoint. With this parameter, you can specify a desired country to query in your endpoint curl command.

  Note

  • The parameter name is case-sensitive.
  • The parameter cannot be a table name or column name.
  • The parameter name in the SQL file match the parameter name configured in http_endpoints/config.json.