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

1. Click Datablocks in the side menu.

2. Click Create new datablock.

3. Pick the connection (e.g. "Acme Co - Google Ads").

4. 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

1. In the Metrics picker, add the metrics you want — Spend, Clicks, Conversions, ROAS, etc.

2. The available metric list depends on the connection. Google Ads exposes 50+; GA4 has a different list.

Step 3 — Pick dimensions

1. Add the dimensions to group by — Campaign, Ad Group, Date, Device, etc.

2. Order matters for tables: the first dimension is the leftmost column.

Step 4 — Add filters

1. Click Add filter.

2. For each filter, pick a dimension, an operator (equals, contains, in, not in, etc.), and a value.

3. 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

1. Pick a default date range — Last 7 days, Last 30 days, MTD, QTD, YTD, or a fixed range.

2. This default can be overridden by dashboard-level filters when the datablock is used on a dashboard.

Step 6 — Fetch and verify

1. Click Fetch data.

2. Verify the table shows what you expect.

3. 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

1. Click Datablocks → Create new datablock.

2. Pick a SQL connection.

3. 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:

SELECT
  campaign_id,
  campaign_name,
  SUM(spend) AS spend,
  SUM(conversions) AS conversions
FROM marketing.campaign_daily
WHERE date BETWEEN '${start_date}' AND '${end_date}'
GROUP BY 1, 2
ORDER BY spend DESC
LIMIT 100

[Screenshot needed] SQL datablock editor with the query above and a parameter section listing start_date and end_date.

Step 3 — Declare parameters

In the Parameters panel below the editor, for each parameter:

1. Name (matches ${name} in the SQL).

2. Type (Date, String, Number).

3. Default value.

Step 4 — Test and save

1. Click Run to test against the connection.

2. SMAQ shows the result set in a table.

3. 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.