Tables for sql queries
The sql`…` command is part of the Server SDK: it reads data straight from the
Qubix database and is available in scripts,
Britva auto-rules, and site handlers. This is a
reference for which tables and columns you can reach, and by what rules.
How access works
- Read-only. Only queries that start with
SELECT,WITH,SHOW,DESCRIBE, orEXPLAINare allowed. Any data changes (INSERT,UPDATE,DELETE) and reaching out to external sources from inside the query are blocked. - Safe parameters. Values passed through
${…}always go as query parameters, not spliced into the text. You do not escape anything by hand, and query substitution is impossible. - You see only your own data. The query runs within your role's permissions: you get exactly the rows you are allowed to see in reports. Other people's data is not reachable.
- A size limit. A single query returns at most a few thousand rows (the administrator
sets the exact cap). For large selections, aggregate right in the query —
count(),sum(),GROUP BY.
The table name is written without a database prefix — just qubix_events.
qubix_events — the event stream
The main table: one row per visitor event and per conversion action. Through it you can see everything that happens to the traffic — from the first visit to the deposit and to push delivery.
Event and identity
| Column | What it is |
|---|---|
event | The event type (values in the table below) |
event_time | The event time |
piuid | The visitor id (persistent across visits) |
pwa_id | The PWA the event belongs to |
domain | The domain the event happened on |
url | The page address |
Geo and device
| Column | What it is |
|---|---|
geo, country | The visitor's country (by GeoIP) |
city | The city |
language | The browser language |
ua | The User-Agent |
ip | The IP address |
device | Device data (JSON) |
Tracking and attribution
| Column | What it is |
|---|---|
click_id | The tracker click id |
campaign_id | The tracker campaign |
ad_id | The ad |
sub_id_1 … sub_id_16 | Custom tracker tags |
fbc, fbp, fbclid | Facebook attribution parameters |
gclid, ttclid | Google / TikTok attribution |
source_clid | The original click id |
pixel | The pixel id |
params | All address parameters (a "key → value" map) |
Offer
| Column | What it is |
|---|---|
offer_id | The offer |
offer_url | The offer link |
Push
| Column | What it is |
|---|---|
push_campaign_id | The push campaign |
subscription_id | The visitor's push subscription |
message_id | The sent message id |
push_title, push_body | The push text |
Conversion
| Column | What it is |
|---|---|
status | The conversion status |
revenue | The revenue for the event |
currency | The currency |
response_code | The response code (for server-side events) |
error_message | The error text, if any |
external_id | An external identifier |
extra | Extra event data (JSON) |
event values
The main event types you'll see in the stream:
| Group | Values |
|---|---|
| Visits and views | campaign_visit, render, white_page |
| PWA install | install_accepted, install_rejected, install_blocked, installed, launch_pwa, install_fallback_redirect |
| Push | push_prompt_shown, push_allow, push_deny, push_ignored, push_subscribe, push_sent, push_shown, push_click, push_dismiss, push_expired |
| Conversions | reg (registration), dep (deposit) |
The subscribe and install event values match the Browser SDK events — what
window.sdk sends from the browser lands right here.
Example
How many visitors from each country allowed push in the last day:
const rows = sql`
SELECT geo, count() AS allowed
FROM qubix_events
WHERE event = 'push_allow'
AND event_time >= now() - INTERVAL 1 DAY
GROUP BY geo
ORDER BY allowed DESC`
for (const row of rows) console.log(row.geo, row.allowed)
Other tables
| Table | What's inside |
|---|---|
pwa_apps | PWA app settings: pwa_id, name, status, country, category, rating, downloads, push_placement, and other constructor fields |
push_subscriptions | Push subscriptions: subscription_id, pwa_id, geo_country, active, subscribed_at |
push_campaigns | Push campaigns: push_campaign_id, name, status, target_geo |
Ready-made report metrics (spend, revenue, ROAS, per-ad conversions) are easier to take not
from the raw stream but from the ad object's fields — the full list is in
Metrics and columns.
Service secrets are not reachable from queries — for example, the private keys for push cannot be read. A query always works read-only and only within your role's permissions.