SQL API

Workers Analytics Engine の SQL API は、Workers Analytics Engine のデータセットに対して SQL クエリを実行できる HTTP API です。

API のホストは https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql です。

認証

認証はベアラートークンで行います。API へのすべてのリクエストに、Authorization: Bearer <token> ヘッダーを付ける必要があります。

ダッシュボードで、アカウントの分析データを読み取る権限を持つトークンを作成します。

Cloudflare ダッシュボードの API tokens ↗ ページを開きます。
Create Token を選択します。
Create Custom Token を選択します。
Create Custom Token フォームを次のように入力します。
- トークンに分かりやすい名前を付けます。
- Permissions で Account | Account Analytics | Read を選択します。
- 必要に応じて、アカウント制限、IP 制限、TTL を設定します。
- フォームを送信して確認し、トークンを作成します。
トークン文字列を控えておきます。

API をクエリする

クエリ本文を POST リクエストのボディに入れて、API アドレスへ送信します。返されるデータの形式は、クエリの FORMAT オプションで選べます。

cURL で API を試すには、次のコマンドを使います。<account_id> はダッシュボードで確認できる 32 文字のアカウント ID に、<token> は上で生成したトークン文字列に置き換えます。

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT 'Hello Workers Analytics Engine' AS message"

データがすでに公開されている場合は、次を実行して、データセットが DB に作成されていることを確認できます。

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SHOW TABLES"

サポートされているクエリ構文の全体は、Workers Analytics Engine の SQL リファレンスを参照してください。

テーブル構造

Worker からイベントの書き込みを始めると、データセットごとにテーブルが自動で作成されます。

テーブルには次の列があります。

名前	型	説明
dataset	string	すべての行にデータセット名が入ります。
timestamp	DateTime	Worker でイベントが記録された時刻です。
_sample_interval	integer	データがサンプリングされている場合、この列はこの行のサンプルレートを示します（つまり、元データの何行分をこの行が表すかです）。詳細は下のサンプリングを参照してください。
index1	string	イベントとともに記録されたインデックス値です。この列の値は、サンプリングのキーとして使います。
blob1 ... blob20	string	イベントとともに記録された blob 値です。
double1 ... double20	double	イベントとともに記録された double 値です。

サンプリング

非常に大量のデータでは、Analytics Engine はパフォーマンスを維持するためにデータをダウンサンプルします。サンプリングは書き込み時と読み取り時の両方で発生することがあります。サンプリングはデータセットのインデックスに基づきます。イベント数が大きいインデックスだけがサンプリングされます。たとえば、Worker が複数の顧客にサービスを提供している場合、顧客 ID をインデックスフィールドにするとよいでしょう。こうすると、ある顧客のリクエストレートが高くなった場合、その顧客のイベントだけがサンプリングされ、他の顧客のデータはサンプリングされません。

Cloudflare では、このサンプリング方式を長年検証してきました。これにより、Web 分析システムを非常に高いスループットへスケールさせつつ、サイトのトラフィック量にかかわらず統計的に意味のある結果を提供できます。

データのサンプルレートは _sample_interval 列で確認できます。データを統計的に分析する場合は、この列を考慮する必要があることがあります。例:

元のクエリ	サンプリングを考慮したクエリ
`SELECT COUNT() FROM ...`	`SELECT SUM(_sample_interval) FROM ...`
`SELECT SUM(double1) FROM ...`	`SELECT SUM(_sample_interval * double1) FROM ...`
`SELECT AVG(double1) FROM ...`	`SELECT SUM(_sample_interval * double1) / SUM(_sample_interval) FROM ...`

さらに、QUANTILEEXACTWEIGHTED 関数は、第 3 引数にサンプル間隔を渡して使う想定です。

クエリの例

列エイリアスでデータを選択する

クエリでは列エイリアスを使い、データセット内の blob と double に名前を付けられます。

SELECT
    timestamp,
    blob1 AS location_id,
    double1 AS inside_temp,
    double2 AS outside_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '1' DAY

サンプル間隔を考慮した集計

過去 7 日間に各ロケーションで取得した読み取り回数を計算します。この例ではインデックスフィールドでグループ化しているため、データがサンプリングされていても正確な件数を計算できます。

SELECT
    index1 AS location_id,
    SUM(_sample_interval) AS n_readings
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1

過去 7 日間の各ロケーションの平均温度を計算します。サンプル間隔を考慮しています。

SELECT
    index1 AS location_id,
    SUM(_sample_interval * double1) / SUM(_sample_interval) AS average_temp
FROM temperatures
WHERE timestamp > NOW() - INTERVAL '7' DAY
GROUP BY index1