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

このドキュメントでは、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にエンドポイント構成があり、 http_endpoints/sql/<method>-<endpoint-name>.sqlに 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形式です。ここで、 <method>と<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;のようになります。

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

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

  注記：

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