Query Pilot Script Diagrams And Annotations

Help ID: query-runner.script-annotations

Query Pilot can read special Minion comments inside normal SQL scripts. The comments do not change how SQL Server sees the script, so the same file still runs in SSMS, sqlcmd, and other editors.

Mermaid Diagrams

Use a MINION DIAGRAM mermaid block comment to carry a diagram with the script:

/*
MINION DIAGRAM mermaid
Title: Stored procedure layout
flowchart TD
    A[Validate params] --> B[Load temp tables]
    B --> C[Apply business rules]
    C --> D[Return result set]
*/

When Query Pilot sees the block, it shows a Diagram tab in the results pane. The tab renders the Mermaid diagram and keeps the original Mermaid source underneath it.

This solves the "what does this big procedure actually do" problem. Instead of reading every branch first, a DBA can open the script and immediately see the intended flow.

Good places to use diagrams:

Large stored procedures with multiple branches.
Deployment scripts with setup, validation, and cleanup phases.
Parallel SQL regions where batches fan out and then converge.
Troubleshooting scripts that a new DBA may need to run safely.

Inline Tags, Comments, And Info

Use pipe-separated metadata in line comments to annotate script elements:

DECLARE @FakeID int = 42; -- Tags: debug | Comments: "Fake ID used for local repro.", "Remove before prod."

SELECT *
FROM dbo.CustomerOrders; -- Tags: wide-table, review | Info: "Use Expand * before sending this to prod."

Query Pilot renders annotation comments as editor markers instead of making you read long green comment text. Depending on your settings, tags can appear at the beginning or end of the rendered line, and comment/info markers can appear at the line start, line end, or in the gutter. The results pane also shows an Annotations tab with:

Line number.
Tags.
Comments.
Info.
Risk, owner, review, ticket, and expiration values when present.

The SQL still executes normally because the metadata is a comment.

Metadata Keys

These keys are recognized today:

-- Tags: inventory, wide-table | Comments: "Use Expand * before finalizing."
-- Info: "This reads the repo table, not the target server."
-- Risk: Medium | Owner: Sean | Review: Required | Ticket: DBA-123 | Expires: 2026-08-01

Tags are short labels. Comments and Info can contain quoted text. Risk, Owner, Review, Ticket, and Expires are displayed in the annotations grid and summary so scripts can carry review and handoff context without becoming non-portable.

Visual Sections And Regions

Use bounded SECTION blocks for column groups or smaller chunks inside a statement:

SELECT
-- SECTION Customer info | Color: Gold | Info: "Main customer identity columns."
    c.CustomerID,
    c.CustomerName,
-- END SECTION Customer info

-- SECTION Shipping info | Color: Teal
    s.Address1,
    s.City
-- END SECTION Shipping info
FROM dbo.Customers c
JOIN dbo.Shipping s ON s.CustomerID = c.CustomerID;

Use bounded REGION blocks for larger script areas:

-- REGION Load Customers | Color: Yellow | Tags: load, customer
SELECT *
INTO #Customers
FROM dbo.Customers;
-- END REGION Load Customers

Query Pilot gives these blocks a colored editor band and fold boundaries. The comments remain real SQL comments, so SSMS and sqlcmd simply ignore the visual metadata.

Settings

Open Query Pilot settings > Annotations to control:

Whether annotation markers are shown.
Where comment/info icons appear.
Where tags appear.
Tag style: pills, text, square, outline, or compact count.
Tag foreground, tag background, and comment icon colors.
A live SQL preview that uses the same editor renderer as Query Pilot.

Syntax Rules

Mermaid blocks must start with /* MINION DIAGRAM mermaid.
The diagram ends at the matching */.
Title: is optional.
Inline annotation comments can include Tags:, Comments:, Info:, Risk:, Owner:, Review:, Ticket:, and Expires:.
Use | to separate metadata sections.
Tags can be separated with commas or semicolons.
Comments can be quoted when more than one note is needed.
SECTION and REGION blocks need matching END SECTION or END REGION comments to fold cleanly.

Scenario: Debug Variables

A developer keeps a fake ID in a script for local testing:

DECLARE @CustomerID int = 1001; -- Tags: debug | Comments: "Fake customer used for QA repro.", "Change before prod run."

The annotation makes the risk visible without preventing the script from running in ordinary tools.

Scenario: Wide Tables

A table has hundreds of columns and the script starts with SELECT * while the DBA is investigating:

SELECT *
FROM dbo.CustomerAudit; -- Tags: wide-table | Info: "Use Expand * or projection shorthand before finalizing."

The annotation gives the next person context and points them toward Query Pilot's wide-table column projection tools.

Documentation revision: 45388F9F01093D3A