# Create project datablocks

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.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.smaq.io/documentation/features/datablocks/create-project-datablocks.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.