> For the complete documentation index, see [llms.txt](https://docs.smaq.io/documentation/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.smaq.io/documentation/features/datablocks/create-project-datablocks.md).

# 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](/documentation/features/datablocks.md).
* 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](/documentation/features/dashboard/mastering-dashboard-filters/limitations-and-tips.md)).

> **\[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:

```sql
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](/documentation/connections/custom-endpoint.md).

### 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](/documentation/features/datablocks/custom-metrics.md) — derive new metrics from datablock columns.
* [Adding custom charts](/documentation/features/dashboard/adding-custom-charts.md) — visualize a datablock.
* [Playbooks](/documentation/features/chat/playbooks.md) — bundle related datablocks into a reusable analysis.