Экспорт аналитики

Выгрузка аналитики в CSV или JSON для BI, кастомных дашбордов и долговременного хранения.

Дашборд и oRPC-процедуры покрывают большинство сценариев, но два случая требуют экспорт:

BI / warehouse. Подключить AACSearch в Looker, Metabase, BigQuery, Snowflake — туда, где уже живёт ваша продуктовая аналитика.
Долгое хранение. Дефолтный retention — 90 дней; для compliance или долгого тренда — тяните данные и храните сами.

Эндпоинты экспорта

Формат	Эндпоинт	Сценарий
CSV (period)	`GET /v1/projects/{projectId}/analytics?format=csv`	Электронные таблицы, ad-hoc анализ
JSON (period)	`GET /v1/projects/{projectId}/analytics?format=json`	API-потребители, кастомные дашборды
Webhook	Per-org конфиг — события стримятся live	Live-ингест в warehouse

CSV / JSON ограничены периодом (?period=24h|7d|30d|90d). Полный backfill — пагинируйте по from / to. Webhook стримит live — это правильный выбор, если нужна свежесть выше period.

CSV export

curl -H "Authorization: Bearer <admin-key>" \
  "https://your-app.com/v1/projects/proj_123/analytics?period=30d&format=csv" \
  > aacsearch-events-30d.csv

Колонки (стабильно, аддитивно):

Колонка	Тип	Описание
`event_id`	string	Стабильный id; безопасно дедупить.
`created_at`	ISO 8601	UTC.
`organization_id`	string	Tenant id (= org вызывающего).
`index_slug`	string	Индекс события (`null` для cross-index).
`event_type`	string	`search_query`, `result_click`, `conversion`, `zero_results`, …
`query`	string	Нормализованный запрос.
`query_id`	string	Связь search → click → conversion.
`session_id`	string	Псевдоним клиентской сессии.
`anonymous_user_id`	string	Опциональный stable pseudonymous id.
`position`	int	Для `result_click` — ранг (1-based).
`product_id`	string	Document id события.
`filters_json`	string	`filterBy` на момент события.
`sort`	string	`sortBy` на момент события.
`locale`	string	Локаль.
`referrer`	string	Санитизированный — host + path, без query string / fragment.
`latency_ms`	int	Латентность для `search_query`.
`found`	int	Hits для `search_query`.
`conversion_type`	string	Для `conversion` — `"purchase" / "signup" / …`.
`value_minor`	bigint	`metadata.value` в BigInt minor units (копейки/центы).
`currency`	string	Currency code.

Порядок append-only: новые колонки добавляются справа, в середину не вставляются. Позиционный CSV-парсер не сломается.

JSON export

curl -H "Authorization: Bearer <admin-key>" \
  -H "Accept: application/json" \
  "https://your-app.com/v1/projects/proj_123/analytics?period=30d&format=json"

{
  "events": [
    {
      "eventId": "evt_…",
      "createdAt": "2025-…",
      "type": "search_query",
      "query": "wireless headphones",
      "queryId": "qry_…",
      "indexSlug": "products",
      "found": 47,
      "latencyMs": 38,
      "filters": { "brand": ["Sony"] },
      "metadata": { … }
    }
  ],
  "page": 1,
  "pageSize": 1000,
  "total": 12440
}

Те же поля, что в CSV, плюс развёрнутые filters и metadata. Pagination — ?page=2; max page size — 1000.

И CSV, и JSON режут период по retention тарифа. Запросили period=90d на 30-day plan — ответ обрезан до доступных 30 дней + флаг truncated: true (или хедер X-Truncated: true в CSV).

Webhook стриминг

В дашборде Integrations → Analytics webhook конфигурится URL. Система POST-ит батчи событий в ~30 секунд после получения:

POST <your-webhook-url>
Content-Type: application/json
X-AACSearch-Signature: t=…,v1=hmacSha256(…)

{
  "organizationId": "org_…",
  "batchId": "batch_…",
  "events": [
    { "eventId": "…", "type": "search_query", … }
  ]
}

Проверяйте HMAC так же, как у платёжного провайдера. Replay-protection: t= сверяется на принимающей стороне — отбрасывайте старше 5 минут.

Ретраи: не-2xx ретраятся exponential backoff до 24 часов, потом дроп. В дашборде webhook-панель показывает доставки/фейлы — см. Webhooks.

Auth для экспорта

CSV / JSON pull: admin-ключ (ss_search_* со scope admin). Read-only ss_search_* не дают аналитику.
Webhook: настроен серверно; caller-credential не нужен.

Admin-ключ — тот же, что и для POST /v1/projects/.../keys (ротация) — API keys.

Retention

Поверхность	Дефолтный retention
Дашборд (24h / 7d / 30d)	90 дней (платный), 30 дней (free), 7 дней для 24h-only
`SearchUsageEvent` сырые	90 дней (платный), 30 дней (free)
`SearchActivityEvent`	365 дней
Webhook delivery log	30 дней

Для большего — pull и хранение у себя. Апгрейд тарифа продлевает retention, но дороже, чем self-archive для большинства.

Privacy и PII при экспорте

referrer санитизирован — host + path. Без query string. Без fragment.
Сырого IP, email, телефона нет.
anonymous_user_id и session_id — псевдонимные id; в DPA считайте PII для retention.
Right-to-be-forgotten — erasure нужно прокатить и на warehouse-копии. AACSearch стирает по anonymous_user_id по запросу — Data privacy.

BI-паттерны

Куда сходится большинство:

Ночной cron pull-ит прошлые 24 ч period=24h&format=json.
Кладёт строки в таблицу aacsearch_events в warehouse.
dbt / Looker / Metabase моделирует поверх — top queries, CTR, conversion rate, period-over-period.
Данные старше 90 дней выживают в warehouse, доступны вечно.

Webhook лучше, если warehouse умеет stream-ингест (BigQuery streaming, Snowflake Snowpipe, Redshift Kinesis). Стрим побеждает по свежести; ночной — по простоте.

Rate limits

CSV / JSON — 6 запросов в минуту per organization. Для большого backfill — пагинируйте внутри одного экспорта, а не палите много мелких.