Data model
Default properties
The contextual fields every SDK adds to every event for free — geo, OS, device, app, browser, session — and which ones get promoted to indexed columns.
Every Sankofa SDK enriches events with default properties before they leave the device. The engine takes the highest-value defaults and promotes them into indexed ClickHouse columns, so you can break down or filter by them at query time without paying a JSON-decode cost.
You don't configure default properties — they're free, automatic, and consistent across SDKs. This page is a complete reference for what gets attached and how it's collected per platform.
The promoted defaults
These nine fields are stored as indexed columns and queryable directly. You'll see them in the dashboard's filter / breakdown menus alongside your custom properties.
$countrystring$regionstring$citystring$timezonestring$osstring$os_versionstring$device_modelstring$app_versionstring$session_idstringThe full default set
Beyond the promoted nine, every SDK also attaches platform-specific defaults under default_properties. These are queryable but not indexed; filtering by them is slower at scale.
Web (@sankofa/browser)
$current_urlstring$hoststring$pathnamestring$searchstring$referrerstring$browserstring$browser_versionstring$screen_widthnumber$screen_heightnumber$viewport_widthnumber$viewport_heightnumber$device_pixel_rationumber$languagestringMobile (Flutter, React Native, iOS, Android)
$device_manufacturerstring$device_modelstring$app_build_numberstring$app_namespacestring$app_releasestring$network_typestring$network_carrierstring$screen_densitynumber$localestringServer (Node, Go, Python, Java)
Server SDKs add fewer defaults because there's no human at a screen — they focus on the runtime and the call site:
$runtimestring$runtime_versionstring$hostnamestring$pidnumber$environmentstring$releasestringIf you wired the SDK's HTTP middleware (Express, Fastify, Servlet, net/http, FastAPI, Django, Flask), the request context adds:
$request_methodstring$request_pathstring$request_idstring$user_agentstringHow promotion works
Promotion is one of the engine's quiet superpowers. Instead of forcing you to declare which fields to index up front, Sankofa watches your traffic and promotes the highest-value defaults into materialized columns during ingest.
The current promoted set is the nine listed at the top of this page. We picked them because they're:
- present on at least 60% of events across customers;
- queried frequently (filtered or broken down on);
- low cardinality (so the index is cheap).
Promotion happens at write time on the engine, not at query time. This means filtering by $country = 'GH' runs as a column scan, not a JSON parse — orders of magnitude faster on tables with billions of rows.