Analytics & PQL

Puddle's analytics answer questions about your store through one small query language, PQL (Puddle Query Language). It covers:

• Commerce: orders, products, customers and carts.
• Website: pageviews, visitors, visits, referrers, campaigns, devices and regions.

The same query format powers the analytics dashboard, Puddle AI and the MCP server (Claude, ChatGPT and other MCP clients). To start asking questions, see Using your analytics.

{
  "dataset": "blend",
  "measures": ["orders.revenue", "web.visitors", "conversion_rate"],
  "dimensions": ["time.week"],
  "time": { "range": "last_90_days" }
}

The same query in the one-line text form:

blend: orders.revenue, web.visitors, conversion_rate by time.week during last_90_days

ConceptsCopy Anchor Link

• Dataset: what you're counting. orders, products, customers, carts, web, or blend for cross-source metrics.
• Measure: an aggregate such as revenue, visitors or bounce_rate. Business rules live in the definition, for example revenue is order totals minus refunds on placed, non-deleted orders.
• Dimension: what to group by, such as time.day, product, referrer or utm_campaign.
• Filters, time range, comparison, sort and limit: see Query language.

You ask for named measures and dimensions. You never write SQL or join tables.

Store isolationCopy Anchor Link

A store can only ever read its own data. This is enforced by Puddle, not by the person or app asking:

1. Queries have no store field. The store always comes from your signed-in account, or the account behind an MCP connection. MCP connections are also limited to stores where you have the View analytics permission.
2. No raw SQL. Queries can only use the named datasets, measures and dimensions in the reference.
3. Limits: at most 1,000 rows per query, a 10-second time limit, a two-year maximum range for website data, and results cached per store for one minute.

If a store has no website analytics connected, the web and blend datasets report themselves as unavailable. The other datasets keep working.