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

このドキュメントでは、 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>-<endpoint-path>.sql形式です。3 と<endpoint-path> <method> 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; 。

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

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

  注記：

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