An example query is not documentation the agent passively reads. It is a candidate pattern retrieved into query generation. A perfect SQL example can damage accuracy when its natural-language question attracts the wrong user intent. A relevant example can be ignored when schema validation fails. Two individually correct examples can contradict each other when their date, join, grain, or metric conventions overlap.
Microsoft currently allows up to 100 example queries per data source and says the agent typically retrieves the top four most relevant examples for a user question. Run steps can reveal which examples were passed. The goal is therefore not to maximize count; it is to make the retrieved set relevant, non-conflicting, valid, current, and sufficient for the intended SQL or KQL pattern.
Can you show which examples were retrieved for a failed question and why each one belonged? If not, the few-shot layer is not yet observable enough for production ownership.
Define each example as a versioned query-generation contract
Record the owner, supported source, schema version, business intent, natural-language question, approved SQL or KQL, required tables and columns, joins, grain, filters, literals, substitutions, aggregation, ordering, time semantics, expected result, allowed generalization, prohibited neighboring intents, validator result, and regression tests.
| Contract element | Required evidence | Failure risk | Control |
|---|---|---|---|
| Question intent | One clear metric or operation, dimensions, timeframe, filters, literals, and business owner. | A vague or multi-intent question retrieves the pattern for unrelated prompts. | Clarity review, boundary questions, and explicit unsupported variants. |
| Query relatedness | Every requested metric, filter, grain, and period represented in approved SQL or KQL. | The query is valid but solves a different business question. | Independent result reconciliation and Relatedness review. |
| Literal mapping | Numbers, dates, categories, thresholds, regions, and IDs mapped or intentionally parameterized. | A value in the question disappears or becomes a hard-coded stale constant. | Mapping score, substitution comments, and variation tests. |
| Complex pattern | Join keys, cardinality, UDFs, time windows, aggregations, nulls, and business rules. | The agent copies syntax but misses the condition that makes it correct. | Focused query comments, source instructions, and component controls. |
| Retrieval boundary | Questions that should retrieve the example and near-neighbors that must not. | Overlapping examples deliver contradictory guidance in the same prompt. | Collision matrix, distinct scopes, consolidation, and run-step inspection. |
| Lifecycle | Source and schema version, validation status, deployment, consumers, owner, review date, and rollback. | Renamed objects or changed logic leave a stale example active or invalid. | Dependency checks, CI validation, regression suite, and versioned release. |
Curate for distinct patterns, not example volume
Use examples where the query pattern is difficult to express through schema alone: multi-table joins, fiscal calendars, slowly changing dimensions, sessionization, state reconstruction, conditional aggregation, KQL functions, domain-specific exclusions, and controlled parameter substitution. Simple cases already generated correctly do not need to consume retrieval space.
Microsoft recommends comments that explain substitutions and complex logic. Keep comments factual and executable-query-safe. Do not place policy bypasses, hidden credentials, sensitive values, or unsupported instructions in examples. The agent remains read-only and constrained by selected schema, user permissions, and organizational policy.
Avoid duplicate paraphrases that all teach the same query while crowding out other patterns. Avoid near-identical questions paired with different joins or metrics. If two patterns share vocabulary, make the business distinction explicit in the question and source instructions, then test both together.
Test retrieval before scoring the final answer
| Test family | Test | Pass condition | Remediation |
|---|---|---|---|
| Schema validation | Validate every pair against the selected source schema and current objects. | All intended examples pass; invalid pairs are identified before release. | Fix query, schema selection, object reference, permission, or remove example. |
| Retrieval precision | Inspect run steps for exact, paraphrased, and nearby negative questions. | Retrieved examples belong to the intent and exclude contradictory neighbors. | Rewrite question, split scope, remove overlap, or change source instructions. |
| Retrieval coverage | Run production-shaped question families across every approved complex pattern. | At least one useful pattern appears when needed without irrelevant crowding. | Add a distinct example, improve wording, or redesign the question taxonomy. |
| Query generation | Compare generated SQL or KQL with and without the example under the same runtime. | The example improves valid structure and business correctness without copying stale literals. | Query comments, source instructions, parameterization, or example removal. |
| Collision | Ask questions between two examples that differ by metric, date, join, grain, or source. | The generated query follows the correct pattern or asks for clarification. | Narrow examples, make distinctions explicit, consolidate, or separate sources. |
| Security | Repeat under allowed, restricted, RLS, CLS, DLP, and denied personas. | Retrieval never expands schema or access; query and result fail closed. | Schema, permission, policy, source split, or rollout block. |
| Runtime regression | Replay the suite on standard and preview runtimes and after service changes. | Retrieval set, generated query, result, and latency remain within thresholds. | Runtime pin, example revision, rollback, or use-case restriction. |
| Source change | Rename, remove, or alter referenced fields, joins, functions, and formats in test. | Dependency checks catch impact and no stale example reaches production. | Update and validate pair, migration gate, or rollback source change. |
Use Microsoft's Clarity, Relatedness, and Mapping scores as diagnostics, not the release decision. An example is high quality only when all three are positive, but production approval also requires deterministic query correctness, retrieval precision, security, performance, and no material regression across neighboring questions.
Observe the actual runtime and validate every change
Microsoft's current example-query page says the agent typically retrieves the top four examples. Other documentation or runtimes can change over time. Do not design a control that assumes an immutable count. Inspect run steps for the target release, record the observed retrieved set, and gate on relevance and result rather than a fixed implementation detail.
Examples that fail schema validation aren't sent to the agent. Validate after schema selection, rename, type change, function change, source migration, runtime change, or deployment. Track the denominator: a library of 80 examples with 20 silent validation failures is not an 80-example production asset.
Power BI semantic models use a different mechanism. Microsoft currently does not support sample question-query pairs for semantic model sources; configure AI Data Schema, AI Instructions, and Verified Answers in Prep for AI. Keep SQL/KQL example-query governance separate from DAX grounding, even when one Data Agent routes across both.
Run a two-to-four-week example-query assessment
- Select one Data Agent, supported SQL or KQL sources, runtime, question families, owners, current example library, and known wrong queries.
- Inventory schema selection, source instructions, examples, validation state, run-step retrieval, generated queries, permissions, deployments, and changes.
- Define each example contract, expected retrieval boundary, deterministic result, substitutions, prohibited neighbors, and owner.
- Run validator scores, schema execution, exact and paraphrase retrieval, negative collisions, with/without comparison, security, performance, runtime, and source-drift tests.
- Classify failures by question clarity, query relatedness, literal mapping, schema, retrieval, overlap, instruction conflict, generated query, permission, or runtime.
- Remove weak and duplicate examples, refine distinct patterns, rerun the complete suite, and compare draft with published behavior.
- Deliver the curated library, validation register, collision map, retrieval scorecard, regression suite, lifecycle controls, monitoring, runbooks, and go, limit, redesign, or stop recommendation.
Frequently asked questions
What are example queries in Microsoft Fabric Data Agent?
Example queries are natural-language question and SQL or KQL query pairs that guide Fabric Data Agent query generation. They demonstrate approved patterns such as joins, filters, aggregations, date logic, substitutions, and complex business rules for supported data sources.
How many example queries can a Fabric Data Agent use?
Microsoft currently documents up to 100 example queries per data source. More examples are not automatically better: overlapping, contradictory, stale, or weak pairs can retrieve the wrong pattern and reduce query accuracy.
How many example queries does Fabric Data Agent retrieve for a question?
Microsoft's current example-query guidance says the agent typically retrieves the top four most relevant examples. Teams should inspect run steps in the target runtime rather than hard-coding an assumption, then test whether the retrieved set is relevant, non-conflicting, and sufficient.
Why is a Fabric Data Agent example query not being used?
A common cause is failed schema validation: Microsoft says examples that don't validate against the selected source schema aren't sent to the agent. The example may also be irrelevant to the user question, too ambiguous, contradicted by another example or instruction, stale after a schema change, or unsupported for that source type.
Do Power BI semantic models support Fabric Data Agent example queries?
No. Microsoft currently says sample question-query pairs aren't supported for Power BI semantic model sources. Configure AI Data Schema, AI Instructions, and Verified Answers in Power BI Prep for AI instead, then test generated DAX separately.
Official implementation references
- Fabric Data Agent example-query creation, retrieval, and validation
- Fabric Data Agent configuration and 100-example limit
- Example-query support by Data Agent source type
- Fabric Data Agent source instruction and example guidance
- Fabric Data Agent example-query source control and ALM
Start with the failed question whose run steps retrieved a plausible but wrong join or date pattern. Datrick can trace the retrieval set, validate every pair, remove collisions, reconcile generated queries, and turn the library into a governed production asset.