> 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.md).

# Datablocks

Datablocks are SMAQ's foundational unit: a reusable, named query that pulls data from one of your connections. Everything else — dashboards, automations, chat — builds on them.

A datablock answers a question once and stays answered. You define it (connection + metrics + dimensions + filters + date range), and then you can drop it onto any dashboard, reference it in chat, point an automation at it, or include it in a playbook.

### Two flavors

#### Global datablocks

Pre-built by SMAQ and available in every project. They cover the questions almost everyone asks:

* Campaign performance by week (Google Ads, Meta, TikTok, etc.)
* Channel mix and conversion funnel (GA4)
* Search term breakdown (Google Ads)
* Top landing pages by traffic and conversions
* Top performing creative by ROAS

Global datablocks update automatically as SMAQ adds new ones. You can't edit them — but you can [duplicate one as the starting point for a project datablock](/documentation/features/datablocks/create-project-datablocks.md).

#### Project datablocks

Custom datablocks you build for your project's specific needs. Use these when:

* You need a metric or dimension that isn't in a global datablock.
* You want specific filters baked in (e.g. "only campaigns tagged \[Q2 launch]").
* You're connecting to a SQL database or custom endpoint — there are no global datablocks for those.

See [Create project datablocks](/documentation/features/datablocks/create-project-datablocks.md).

### Where to find datablocks

In any project, click **Datablocks** in the side menu. The page shows:

* **My Datablocks** — your project datablocks
* **Global** — the pre-built library, organized by connection type

> **\[Screenshot needed]** Datablocks page with both tabs visible and the Global tab open, showing a list of GA4 and Google Ads datablocks.

### Custom metrics

If you need a calculated KPI on top of a datablock — ROAS, AOV, CPA, etc. — use [Custom metrics](/documentation/features/datablocks/custom-metrics.md). They live alongside datablocks and can blend across multiple sources.

### How datablocks differ from charts

A datablock is the **query**; a chart is the **visualization**. The same datablock can be rendered as a line chart, a bar chart, a table, a pivot table, or a metric card — all from the same underlying data. See [Adding custom charts](/documentation/features/dashboard/adding-custom-charts.md).

### Datablocks in chat

When you chat with SMAQ AI, it uses your datablocks as the primary way to answer data questions. The more well-named, well-described project datablocks you have, the better the AI's chat answers. See [Search Datablock agent](/documentation/features/chat/capabilities.md) for how the AI finds them.

### What's next

* [Create project datablocks](/documentation/features/datablocks/create-project-datablocks.md) — full walkthrough.
* [Custom metrics](/documentation/features/datablocks/custom-metrics.md) — calculated KPIs.
* [Adding custom charts](/documentation/features/dashboard/adding-custom-charts.md) — turn a datablock into a chart.