← Аналитика / analytics / analytics-engine

SQL API

Workers Analytics Engine SQL API представляет собой HTTP API, который позволяет выполнять SQL-запросы к наборам данных Workers Analytics Engine.

Это API размещено по адресу https://api.cloudflare.com/client/v4/accounts/<account_id>/analytics_engine/sql.

Аутентификация выполняется с помощью bearer-токена. Authorization: Bearer <token> заголовок должен передаваться с каждым запросом к API.

С помощью дашборда создайте токен с разрешением на чтение аналитических данных вашего аккаунта:

1. Перейдите в API-токены ↗ странице панели управления Cloudflare.
2. Выберите Create Token.
3. Выберите Create Custom Token.
4. Выполните Create Custom Token форму следующим образом:
   • Дайте токену понятное название.
   • Для Разрешения выбрать Аккаунт | Account Analytics | Чтение
   • При необходимости настройте ограничения по аккаунту и IP-адресам, а также TTL.
   • Отправьте и подтвердите форму, чтобы создать токен.
5. Запишите строку токена.

Отправьте текст запроса в теле POST запрос на адрес API. Формат возвращаемых данных можно выбрать с помощью FORMAT опцию в вашем запросе.

Протестировать API с помощью cURL можно следующим образом, заменив <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"

Если вы уже опубликовали какие-то данные, можно выполнить следующий запрос, чтобы убедиться, что набор данных создан в БД.

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, для него автоматически будет создана новая таблица.

Таблица будет содержать следующие столбцы:

При очень больших объёмах данных Analytics Engine прореживает данные, чтобы сохранить производительность. Выборка может происходить как при записи, так и при чтении. Выборка основана на индексе вашего набора данных, поэтому выбираются только те индексы, которые получают большое количество событий. Например, если ваш worker обслуживает несколько клиентов, можно сделать ID клиента полем индекса. Это означает, что если один клиент начнёт отправлять запросы с высокой частотой, события от этого клиента могут попасть в выборку, а данные остальных клиентов останутся невыборочными.

Мы тестировали эту систему выборки в Cloudflare на протяжении нескольких лет, и она позволила нам масштабировать системы веб-аналитики до очень высокой пропускной способности, сохраняя при этом статистически значимые результаты независимо от объёма трафика, который получает сайт.

Частота, с которой производится выборка данных, доступна через _sample_interval столбец. Это означает, что при статистическом анализе данных вам может понадобиться учитывать этот столбец. Например:

Кроме того, QUANTILEEXACTWEIGHTED функция предназначена для использования с интервалом выборки в качестве третьего аргумента.

Псевдонимы столбцов можно использовать в запросах, чтобы присваивать имена полям типа 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 дней. Здесь группировка ведётся по полю index, чтобы получить точное количество даже если данные подверглись выборке:

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