The Data 360 Query API: Prove Your Grounding with Plain SQL

Last week I walked through the multi-turn Agentforce flow I built for HanseWatt, a fictional DACH energy retailer — a real, deployed agent that explains a customer’s consumption spike using data from Data 360. The number at the center of that explanation is +64.6% above the trailing average.

This week: where that number comes from, and the habit that saved me the most time and money on the whole project — proving the grounding with plain SQL before the agent ever saw it.

The question every grounded agent depends on

An agent’s answer can only be as good as the data it retrieves. So before wiring anything, you need to answer one question with certainty:

If my agent asks the data layer this question right now, what exactly comes back?

Not “what should come back according to my design.” What actually comes back — column names, data types, null rows, off-by-one date windows, all of it.

There are two ways to find out. You can build the whole chain — agent, action, grounding — and debug through conversations. Or you can ask the data layer directly. The second way is the Data 360 Query API: you send SQL over REST, you get rows back. Zero UI clicks, zero agent credits, answers in seconds.

For the HanseWatt project, every fact the agent states about consumption was verified this way first.

The anomaly insight, in SQL

The business question was simple: is this meter’s latest reading unusually high compared to its own recent history? That’s a Calculated Insight — a metric computed across records — and the natural language for it is SQL with a window function.

Here’s the shape of it. This is a simplified version — real DMO names are longer and the production insight handles more edge cases — but the logic is honest:

WITH readings AS (
    SELECT
        meter_id__c,
        reading_month__c,
        kwh__c,
        AVG(kwh__c) OVER (
            PARTITION BY meter_id__c
            ORDER BY reading_month__c
            ROWS BETWEEN 6 PRECEDING AND 1 PRECEDING
        ) AS trailing_avg_kwh
    FROM meter_reading__dlm
)
SELECT
    meter_id__c,
    reading_month__c,
    kwh__c,
    trailing_avg_kwh,
    ROUND((kwh__c - trailing_avg_kwh) / trailing_avg_kwh * 100, 1)
        AS pct_vs_trailing_avg
FROM readings
WHERE trailing_avg_kwh IS NOT NULL
ORDER BY reading_month__c DESC

Read it slowly if window functions are new to you. The OVER (...) clause says: for each meter, look at the six readings before this one (6 PRECEDING AND 1 PRECEDING — deliberately excluding the current row) and average them. Then the outer query asks how far the current reading sits above or below that trailing average, as a percentage.

For the meter in my demo scenario, the top row came back with pct_vs_trailing_avg = 64.6. That row is the grounding. When the HanseWatt agent tells a customer “your consumption is about 65% above your recent average,” it’s phrasing this row — not improvising.

The meter data itself is simulated (seeded records standing in for a smart-meter MDM feed — no real utility gave me their pipeline). But the insight, the query, and the grounding path are exactly what a real deployment would use. Swap the seed data for a live stream and nothing downstream changes.

Why prove it in SQL first

Three reasons, in ascending order of importance.

It’s the cheapest test you will ever run

Debugging grounding through agent conversations burns Flex Credits on every turn — and most of those turns teach you nothing except that a column was null. A Query API call costs effectively nothing and answers the same question in two seconds. On this project my discipline was the same as on the Apex side: prove the logic in the cheap layer, spend credits only on what conversations alone can teach you (phrasing, planning, tone).

It separates data bugs from agent bugs

When an agent gives a wrong answer, there are two suspects: the data was wrong, or the agent mishandled correct data. If you’ve already proven via SQL that the data layer returns the right rows, you’ve eliminated a suspect before the investigation starts. Every confusing agent behavior I debugged on this project got shorter because I could say with certainty: the +64.6% is real, it’s in the insight, so the problem is downstream.

It forces you to know your data model

Writing the SQL by hand — real DMO names, real field suffixes, real date grains — surfaces every wrong assumption early: the field that’s monthly when you assumed daily, the join key that isn’t what the diagram implied. Better to meet those in a query result than in a customer conversation.

How this slots under an Agentforce action

Once the SQL proved the insight was right, wiring it into the agent was the easy part. The HWExplainConsumption action — one of the four @InvocableMethod actions from last week’s post — reads the same Calculated Insight the query verified and returns the facts in a typed response:

public class Response {
    @InvocableVariable public Decimal latestKwh;
    @InvocableVariable public Decimal trailingAvgKwh;
    @InvocableVariable public Decimal pctVsTrailingAvg;  // 64.6
    @InvocableVariable public String readingMonth;
}

The agent’s planner calls the action, gets these fields, and phrases them for the customer. The chain is fully traceable: SQL query → Calculated Insight → Apex action → agent sentence. At every link, I can point at the layer below and show where the number came from. That traceability is what “grounded” means in practice — and the Query API is where the chain was proven first, under the Einstein Trust Layer like everything else in the org.

The teacher’s version of this habit

In my classroom years I never handed out an exam I hadn’t solved myself first, with the answer key written before any student saw question one. The Query API is the answer key for your grounding. Write the SQL, look at the actual rows, confirm the number — then let the agent take the test. If the agent says something wrong afterward, you’ll know immediately whether the material was wrong or the student misread it.

Your next step

If Calculated Insights are new to you, Calculated Insights: Turning Raw Data into Useful Metrics covers the concept gently, and Data Cloud + Agentforce explains why this pairing matters. Then read last week’s post to see where the verified insight ends up — inside a deployed agent that explains a bill and logs a Case. More in the Data Cloud category.