Create project datablocks
Build custom datablocks tailored to your specific data sources and analytical needs. Step-by-step for both API and SQL connections.
A project datablock is just a saved query. The exact builder UI depends on the connection type — API connections (Google Ads, Meta, GA4, etc.) get a guided picker; SQL connections get a SQL editor with parameter binding.
When to create a project datablock
The metric or dimension combo you need isn't in any global datablock.
You need specific filters baked in (campaign tags, date windows, segment filters).
You're querying a SQL database or custom endpoint.
You want to share a curated query with your team — datablocks are sharable across the project.
Path 1 — API-based connection (Google Ads, Meta, GA4, TikTok, etc.)
Step 1 — Start a new datablock
Click Datablocks in the side menu.
Click Create new datablock.
Pick the connection (e.g. "Acme Co - Google Ads").
Give it a clear name (e.g. "Google Ads — Brand campaigns weekly") and a one-line description. The description matters: the AI uses it to find your datablock during chat.
[Screenshot needed] New datablock creation form with name, description, and connection picker.
Step 2 — Pick metrics
In the Metrics picker, add the metrics you want — Spend, Clicks, Conversions, ROAS, etc.
The available metric list depends on the connection. Google Ads exposes 50+; GA4 has a different list.
Step 3 — Pick dimensions
Add the dimensions to group by — Campaign, Ad Group, Date, Device, etc.
Order matters for tables: the first dimension is the leftmost column.
Step 4 — Add filters
Click Add filter.
For each filter, pick a dimension, an operator (equals, contains, in, not in, etc.), and a value.
Filters combine with AND (no OR groups in the visual filter — see Limitations and tips).
[Screenshot needed] Datablock builder with three metrics, two dimensions, and one filter configured.
Step 5 — Set the date range
Pick a default date range — Last 7 days, Last 30 days, MTD, QTD, YTD, or a fixed range.
This default can be overridden by dashboard-level filters when the datablock is used on a dashboard.
Step 6 — Fetch and verify
Click Fetch data.
Verify the table shows what you expect.
Save.
[Screen video needed] End-to-end API datablock build — pick metrics, pick dimensions, add filter, fetch, save. ~75 seconds.
Path 2 — SQL connection (Postgres, MySQL, BigQuery, ClickHouse, Azure SQL, MongoDB)
SQL datablocks use a different builder: you write the SQL.
Step 1 — Start a new datablock
Click Datablocks → Create new datablock.
Pick a SQL connection.
Name and describe it.
Step 2 — Write the SQL
The SQL editor supports:
Standard SQL syntax for whichever flavor your connection uses.
Parameters —
${start_date},${end_date},${campaign_id}, etc. SMAQ substitutes values at fetch time based on dashboard filters or explicit overrides.
Example:
[Screenshot needed] SQL datablock editor with the query above and a parameter section listing
start_dateandend_date.
Step 3 — Declare parameters
In the Parameters panel below the editor, for each parameter:
Name (matches
${name}in the SQL).Type (Date, String, Number).
Default value.
Step 4 — Test and save
Click Run to test against the connection.
SMAQ shows the result set in a table.
Save.
Path 3 — Custom endpoint
Custom endpoint datablocks work like API datablocks — pick fields and filters from the JSON shape SMAQ auto-detected during connection. See Custom endpoint.
Tips
Name like a person, not a query. "Google Ads — Brand campaigns weekly" beats "GoogleAdsCampaignsWeekly1." The AI prefers descriptive names.
Write descriptions. They cost five seconds and they 5× the AI's ability to find the right datablock in chat.
Use the smallest date range that's useful. A 90-day default is fine for trends; for daily summaries, pick 7 or 30.
Build incrementally. Start with the simplest version, render it on a dashboard, then add filters/dimensions as needed.
What's next
Custom metrics — derive new metrics from datablock columns.
Adding custom charts — visualize a datablock.
Playbooks — bundle related datablocks into a reusable analysis.
Last updated