コンテンツにスキップ

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>ヘッダーを提供する必要があります。

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

  1. CloudflareダッシュボードのAPIトークン ↗ページにアクセスします。
  2. トークンを作成を選択します。
  3. カスタムトークンを作成を選択します。
  4. カスタムトークンを作成フォームを以下のように記入します：
    • トークンに説明的な名前を付けます。
    • 権限でアカウント | アカウント分析 | 読み取りを選択します。
    • 必要に応じてアカウントおよびIP制限とTTLを設定します。
    • フォームを送信してトークンを作成します。
  5. トークン文字列をメモしておきます。

APIのクエリ

クエリテキストをPOSTリクエストのボディに送信してAPIアドレスに送ります。返されるデータの形式は、クエリ内のFORMATオプションを使用して選択できます。

以下のようにcURLを使用してAPIをテストできます。<account_id>をダッシュボードで取得した32文字のアカウントIDに、<token>を上で生成したトークン文字列に置き換えます。

Terminal window
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に作成されていることを確認できます。

Terminal window
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リファレンスを参照してください。

テーブル構造

新しいテーブルは、ワーカーからイベントを書き始めると自動的に各データセットのために作成されます。

テーブルには以下の列があります：

NameTypeDescription
datasetstringこの列には、すべての行にデータセット名が含まれます。
timestampDateTimeイベントがワーカーに記録された時刻のタイムスタンプ。
_sample_intervalintegerデータがサンプリングされた場合、この列はこの行のサンプルレートを示します（つまり、元のデータの何行がこの行で表されているか）。詳細については、以下のサンプリングセクションを参照してください。
index1stringイベントと共に記録されたインデックス値。この列の値はサンプリングのキーとして使用されます。
blob1
…
blob20		stringイベントと共に記録されたblob値。
double1
…
double20		doubleイベントと共に記録されたdouble値。

サンプリング

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

私たちはCloudflareで数年間このサンプリングシステムをテストしており、非常に高いスループットでウェブ分析システムをスケールさせることができ、ウェブサイトが受け取るトラフィックの量に関係なく統計的に意味のある結果を提供しています。

データがサンプリングされるレートは、\_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 ...

さらに、QUANTILEWEIGHTED関数は、サンプル間隔を第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
Cloudflare DashboardDiscordCommunityLearning CenterSupport Portal
Cookie Settings