始める

Wrangler 設定ファイル に次を追加し、Workers Analytics Engine データセットへの バインディング を作成します。データセットは SQL のテーブルに似ています。行と列の意味は一貫している必要があります。

{
	"analytics_engine_datasets": [
		{
			"binding": "<BINDING_NAME>",
			"dataset": "<DATASET_NAME>"
		}
	]
}

[[analytics_engine_datasets]]
binding = "<BINDING_NAME>"
dataset = "<DATASET_NAME>"

作成したバインディングに公開されている writeDataPoint() メソッドを呼び、Worker からデータポイントを書き込めます。

async fetch(request, env) {
  env.WEATHER.writeDataPoint({
    'blobs': ["Seattle", "USA", "pro_sensor_9000"], // City, State
    'doubles': [25, 0.5],
    'indexes': ["a3cd45"]
  });
  return new Response("OK!");
}

データポイントは、次で構成される構造化イベントです。

• Blobs（文字列） — グループ化とフィルタリングに使うディメンションです。他のメトリクスシステムではラベルと呼ばれることもあります。
• Doubles（数値） — データポイントに記録したい数値です。
• Indexes — （文字列） — サンプリング キーとして使います。

上の例では、大気質のサンプルを集めているとします。書き込む各データポイントは、気象センサーの 1 回の読み取りです。blobs は都市、州、センサーモデルを定義します。あとでクエリを絞り込むディメンションです。doubles は温度と気圧の数値です。index は顧客の ID です。受信リクエストのコンテキスト（地理位置情報など）を含め、データポイントへ追加情報を足すこともできます。

現在、writeDataPoint() API は値の順序付き配列を受け取ります。フィールドは一貫した順序で渡す必要があります。indexes フィールドは配列を受け取りますが、現時点ではインデックスは 1 つだけにしてください。複数のインデックスを渡そうとすると、データポイントは記録されません。

書き込んだデータは、次の 2 つの方法でクエリできます。

• SQL API — 自分でクエリを書く場合や、Grafana などの外部ツールと連携する場合に適しています。
• GraphQL API — Cloudflare ダッシュボードが使うのと同じ API です。

この例では、SQL API を使います。

Account Analytics Read 権限を持つ API Token ↗ を作成します。

次のクエリは、温度が 0 より大きいときの平均湿度がもっとも高い都市の上位 10 件を返します。

SELECT
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE double1 > 0
GROUP BY city
ORDER BY avg_humidity DESC
LIMIT 10

このクエリは、SQL API へ HTTP リクエストを送って実行できます。

curl "https://api.cloudflare.com/client/v4/accounts/{account_id}/analytics_engine/sql" \
--header "Authorization: Bearer <API_TOKEN>" \
--data "SELECT blob1 AS city, SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity FROM WEATHER WHERE double1 > 0 GROUP BY city ORDER BY avg_humidity DESC LIMIT 10"

対応する SQL 機能の一覧は、Workers Analytics Engine SQL リファレンス を参照してください。

Workers Analytics Engine は、Grafana などのツールで可視化できる時系列分析向けに最適化されています。ランタイムから書き込まれたすべてのイベントには、自動で timestamp フィールドが入ります。ほとんどの時系列は、timestamp を丸めたうえで GROUP BY することが想定されています。例:

SELECT
  intDiv(toUInt32(timestamp), 300) * 300 AS t,
  blob1 AS city,
  SUM(_sample_interval * double2) / SUM(_sample_interval) AS avg_humidity
FROM WEATHER
WHERE
  timestamp >= NOW() - INTERVAL '1' DAY
  AND double1 > 0
GROUP BY t, city
ORDER BY t, avg_humidity DESC

このクエリは、まず timestamp フィールドを 5 分単位に丸めます。そのあと、そのフィールドと都市でグループ化し、各都市の 5 分間の平均湿度を計算します。

Workers Analytics Engine に対する効率的な Grafana クエリの作り方は、Grafana から Workers Analytics Engine をクエリする を参照してください。

• 始める
• 例
• SQL API
• SQL リファレンス
• Grafana からのクエリ
• Worker からクエリする
• WAE のサンプリング
• 料金
• 制限