データ アプリコンフィグレーションファイル

このドキュメントでは、 TiDB Cloudのデータアプリの構成ファイルについて説明します。

データアプリをGitHubに接続しましたがある場合は、次のように GitHub の指定したディレクトリでデータ アプリの構成ファイルを見つけることができます。

├── <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

データソースの構成

データ アプリのデータ ソースは、リンクされた TiDB クラスターから取得されます。データ ソースの構成はdata_sources/cluster.jsonにあります。

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

各データ アプリに対して、1 つまたは複数の TiDB クラスターにリンクできます。

以下はcluster.jsonの構成例です。この例では、このデータ アプリには 2 つのリンクされたクラスターがあります。

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

フィールドの説明は次のとおりです。

データアプリの構成

データ アプリのプロパティには、アプリ ID、名前、タイプが含まれます。プロパティはdataapp_config.jsonファイルにあります。

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

以下は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>"
}

各フィールドの説明は次のとおりです。

HTTPエンドポイント構成

データ アプリ ディレクトリでは、エンドポイント構成はhttp_endpoints/config.jsonに、SQL ファイルは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

エンドポイント構成

各データ アプリには、1 つまたは複数のエンドポイントが存在します。データ アプリのすべてのエンドポイントの構成は、 http_endpoints/config.jsonで確認できます。

以下はconfig.jsonの構成例です。この例では、このデータ アプリには 2 つのエンドポイントがあります。

[
  {
    "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"
  }
]

各フィールドの説明は次のとおりです。

SQLファイルの構成

エンドポイントの SQL ファイルは、エンドポイントを介してデータをクエリするための SQL ステートメントを指定します。データ アプリのエンドポイント SQL ファイルは、 http_endpoints/sql/ディレクトリにあります。エンドポイントごとに、対応する SQL ファイルがあります。

SQL ファイルmethod名前は<method>-<endpoint-path>.sql形式です。3 と<endpoint-path> http_endpoints/config.jsonの<method>とendpoint構成と一致する必要があります。

SQL ファイルでは、テーブル結合クエリ、複雑なクエリ、集計関数などのステートメントを記述できます。以下は SQL ファイルの例です。

/* 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};

SQL ファイルを書き込むときは、次の点に注意してください。

• SQL ファイルの先頭で、SQL ステートメントにデータベースを指定する必要があります。たとえば、 USE database_name;です。

• エンドポイントのパラメータを定義するには、SQL ステートメントに${variable-name}のような変数プレースホルダとして挿入します。

  前の例では、エンドポイントのパラメータとして${country}が使用されています。このパラメータを使用すると、エンドポイントの curl コマンドでクエリする国を指定できます。

  注記：

  • パラメータ名では大文字と小文字が区別されます。
  • パラメータはテーブル名または列名にすることはできません。
  • SQL ファイル内のパラメータ名は、 http_endpoints/config.jsonで構成されたパラメータ名と一致します。