Fabric topics can hold a million characters—but only retrieved rules reach NL2SQL

Microsoft Fabric’s data-agent topics feature is easy to misread as a larger prompt box. It is really a retrieval layer in front of text-to-SQL—and that changes what teams need to test.

Fabric lets a creator attach up to 1 million characters of Markdown-organized topic content to each supported SQL source. The agent does not send that entire body with every question. It searches the topics, selects sections it considers relevant, and passes only those sections to NL2SQL. Microsoft exposes the selected heading path, the selection reason and the exact instructions passed onward in an Open Data Source Topic run step. Topics remain preview-only and require the preview runtime. (Microsoft: topics)

Retrieval is now part of correctness

That architecture creates two independent failure points. A business rule can be written correctly yet never reach query generation because the agent selected the wrong heading—or none at all. Conversely, the right topic can be retrieved but still fail to produce the intended SQL. Microsoft’s own testing guidance says to try direct questions, alternate phrasings and questions requiring more than one topic, then inspect the retrieved content in the run trace. (Microsoft: topics)

A practical acceptance test should therefore record both outcomes:

1. Context retrieval: Did the run select the expected topic headings and omit conflicting ones?
2. Query behavior: Given that retrieved context, did the generated SQL apply the intended tables, filters, relationships and calculations?

Testing only the final answer makes those failures hard to distinguish. When an answer is wrong, operators need to know whether to rewrite a heading, move a rule into global instructions, or change the example-query and schema configuration.

Put invariants outside topics

Microsoft draws a useful boundary between topics and data-source instructions. Data-source instructions are sent every time the source is used; topics are searched and included only when judged relevant. Its example puts an organization-wide fiscal-year definition in data-source instructions, while detailed retention logic belongs under a retention topic. The documentation also warns against duplicate or contradictory guidance across the two surfaces. (Microsoft: topics)

That implies a deployment rule: requirements that must hold for every query should not depend on retrieval. Topics are better suited to conditional domain context—definitions, table choices and calculation rules that apply only to a class of questions.

Fabric’s Advanced NL2SQL preview can combine schema selection, example queries, data-source instructions, schema descriptions and retrieved topics. Microsoft says the preview uses multi-step reasoning and may ask clarifying questions, while the standard runtime uses a single-pass GA tool and cannot use topics. (Microsoft: SQL sources)

The million-character limit is therefore not the important production number. The important artifact is a retrieval test set: representative questions mapped to expected headings, followed by SQL and result validation. Treat topic selection as observable system behavior, not invisible prompt plumbing.