Query Insights: compute numeric selectivity and render low non-zero values as “below 0.1%” (#763)

Author: tnaum-ms

src/documentdb/queryInsights/staticAnalysisSummary.test.ts

@@ -22,7 +22,7 @@ function makeStage2Response(overrides: Partial<QueryInsightsStage2Response> = {}
         isCoveringQuery: false,
         concerns: [],
         efficiencyAnalysis: {
-            selectivity: '5.0%',
+            selectivity: 5,
             indexUsed: 'rating_1',
             fetchOverhead: 'Direct fetch',
             fetchOverheadKind: 'directFetch',
@@ -97,6 +97,13 @@ describe('buildStaticAnalysisSummary', () => {
         expect(summary).toContain('**Selectivity**: Unknown');
     });
 
+    it('should show threshold text when selectivity is non-zero and below 0.1%', () => {
+        const stage2 = makeStage2Response();
+        stage2.efficiencyAnalysis.selectivity = 0.008;
+        const summary = buildStaticAnalysisSummary(stage2);
+        expect(summary).toContain('**Selectivity**: below 0.1%');
+    });
+
     it('should show None when no index used', () => {
         const stage2 = makeStage2Response();
         stage2.efficiencyAnalysis.indexUsed = null;
@@ -176,7 +183,7 @@ describe('buildStaticAnalysisSummary', () => {
             hadCollectionScan: true,
             concerns: ['Collection scan detected', 'In-memory sort required'],
             efficiencyAnalysis: {
-                selectivity: '0.008%',
+                selectivity: 0.008,
                 indexUsed: null,
                 fetchOverhead: 'Collection scan',
                 fetchOverheadKind: 'collectionScan',
@@ -228,7 +235,7 @@ describe('buildStaticAnalysisSummary', () => {
             documentsReturned: 50,
             isCoveringQuery: true,
             efficiencyAnalysis: {
-                selectivity: '0.5%',
+                selectivity: 0.5,
                 indexUsed: 'status_1_createdAt_-1',
                 fetchOverhead: 'Covered query',
                 fetchOverheadKind: 'covered',

src/documentdb/queryInsights/staticAnalysisSummary.ts

@@ -3,6 +3,8 @@
  *  Licensed under the MIT License. See License.txt in the project root for license information.
  *--------------------------------------------------------------------------------------------*/
 
+import * as vscode from 'vscode';
+
 import { type QueryInsightsStage2Response } from '../../webviews/documentdb/collectionView/types/queryInsights';
 
 /**
@@ -42,7 +44,11 @@ export function buildStaticAnalysisSummary(stage2: QueryInsightsStage2Response,
 
     // Summary indicators
     lines.push('### Summary Indicators (4 cells shown to user)');
-    lines.push(`- **Selectivity**: ${stage2.efficiencyAnalysis.selectivity ?? 'Unknown'}`);
+    const formattedSelectivity =
+        stage2.efficiencyAnalysis.selectivity !== null
+            ? formatSelectivityForSummary(stage2.efficiencyAnalysis.selectivity)
+            : 'Unknown';
+    lines.push(`- **Selectivity**: ${formattedSelectivity}`);
     lines.push(`- **Index Used**: ${stage2.efficiencyAnalysis.indexUsed ?? 'None (collection scan)'}`);
     lines.push(
         `- **Fetch Overhead**: ${stage2.efficiencyAnalysis.fetchOverhead} (${stage2.efficiencyAnalysis.fetchOverheadKind})`,
@@ -71,3 +77,22 @@ export function buildStaticAnalysisSummary(stage2: QueryInsightsStage2Response,
 
     return lines.join('\n');
 }
+
+/**
+ * Formats numeric selectivity for static analysis summary text.
+ * Values between 0 and 0.1 are rendered as a threshold label.
+ *
+ * Keep this formatting in sync with the webview selectivity formatter so Stage 3
+ * summary text and the UI display stay consistent for the same underlying values.
+ * We intentionally kept this duplicated for now to avoid a broader refactor.
+ *
+ * @param selectivity - Raw selectivity percentage value
+ * @returns Formatted selectivity string for summary output
+ */
+function formatSelectivityForSummary(selectivity: number): string {
+    const locale = vscode.env?.language || 'en-US';
+    if (selectivity > 0 && selectivity < 0.1) {
+        return `below ${(0.1).toLocaleString(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 })}%`;
+    }
+    return `${selectivity.toLocaleString(locale, { minimumFractionDigits: 1, maximumFractionDigits: 1 })}%`;
+}

src/documentdb/queryInsights/transformations.test.ts

@@ -0,0 +1,50 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { type ExecutionStatsAnalysis } from './ExplainPlanAnalyzer';
+import { transformStage2Response } from './transformations';
+
+function createExecutionStatsAnalysis(overrides: Partial<ExecutionStatsAnalysis> = {}): ExecutionStatsAnalysis {
+    return {
+        executionTimeMillis: 12,
+        totalDocsExamined: 1,
+        totalKeysExamined: 1,
+        nReturned: 1,
+        efficiencyRatio: 1,
+        usedIndexes: ['idx_a'],
+        isCollectionScan: false,
+        isCovered: false,
+        hasInMemorySort: false,
+        isIndexScan: true,
+        performanceRating: {
+            score: 'excellent',
+            diagnostics: [],
+        },
+        rawStats: {},
+        ...overrides,
+    };
+}
+
+describe('transformStage2Response - selectivity computation', () => {
+    it('returns numeric precision below 0.1% for non-zero selectivity', () => {
+        const analyzed = createExecutionStatsAnalysis({
+            nReturned: 1,
+        });
+
+        const result = transformStage2Response(analyzed, 12_000);
+
+        expect(result.efficiencyAnalysis.selectivity).toBeCloseTo(0.008333333333333333, 10);
+    });
+
+    it('returns numeric percent at or above 0.1%', () => {
+        const analyzed = createExecutionStatsAnalysis({
+            nReturned: 1,
+        });
+
+        const result = transformStage2Response(analyzed, 1_000);
+
+        expect(result.efficiencyAnalysis.selectivity).toBe(0.1);
+    });
+});

src/documentdb/queryInsights/transformations.ts

@@ -193,14 +193,13 @@ export function transformStage2Response(
  *
  * @param nReturned          - Number of documents returned
  * @param totalCollectionDocs - Estimated total documents in the collection
- * @returns Formatted percentage string (e.g., "33.2%") or null if unavailable
+ * @returns Raw percentage value (e.g., 33.2375) or null if unavailable
  */
-function computeSelectivity(nReturned: number, totalCollectionDocs: number | undefined): string | null {
+function computeSelectivity(nReturned: number, totalCollectionDocs: number | undefined): number | null {
     if (!totalCollectionDocs || totalCollectionDocs <= 0 || nReturned === undefined) {
         return null;
     }
-    const ratio = Math.min(nReturned / totalCollectionDocs, 1);
-    return `${(ratio * 100).toFixed(1)}%`;
+    return Math.min((nReturned / totalCollectionDocs) * 100, 100);
 }
 
 /**

src/webviews/documentdb/collectionView/components/queryInsightsTab/QueryInsightsTab.tsx

@@ -52,6 +52,7 @@ import {
 } from '../../queryInsightsReducer';
 import { createImprovementCardConfig } from '../../utils/createImprovementCard';
 import { extractErrorCode } from '../../utils/errorCodeExtractor';
+import { formatSelectivityForDisplay } from '../../utils/formatSelectivityForDisplay';
 import { CardStack, FeedbackCard, FeedbackDialog, type CardStackItem } from './components';
 import { CountMetric } from './components/metricsRow/CountMetric';
 import { MetricsRow } from './components/metricsRow/MetricsRow';
@@ -451,6 +452,11 @@ export const QueryInsightsMain = (): JSX.Element => {
     const docsReturned = getMetricValue(stage2Data?.documentsReturned);
     const keysExamined = getMetricValue(stage2Data?.totalKeysExamined);
     const docsExamined = getMetricValue(stage2Data?.totalDocsExamined);
+    const lowSelectivityLabel = `below ${(0.1).toLocaleString(navigator.language, { minimumFractionDigits: 1, maximumFractionDigits: 1 })}%`;
+    const selectivity = formatSelectivityForDisplay(
+        getCellValue((stage2) => stage2.efficiencyAnalysis.selectivity),
+        lowSelectivityLabel,
+    );
 
     /**
      * Documentation URL for the AI Performance Insights feature itself
@@ -1133,30 +1139,31 @@ export const QueryInsightsMain = (): JSX.Element => {
                     <SummaryCard title={l10n.t('Query Efficiency Analysis')}>
                         <GenericCell
                             label={l10n.t('Selectivity')}
-                            value={getCellValue((stage2) => stage2.efficiencyAnalysis.selectivity)}
+                            value={selectivity}
                             loadingPlaceholder="skeleton"
                             tooltipExplanation={(() => {
                                 const selectivity = stage2Data?.efficiencyAnalysis.selectivity;
-                                if (!selectivity) {
+                                if (selectivity === null || selectivity === undefined) {
                                     return l10n.t(
                                         'The percentage of your collection this query returns. Could not be determined for this query.',
                                     );
                                 }
-                                const pct = parseFloat(selectivity);
+                                const displayValue = formatSelectivityForDisplay(selectivity, lowSelectivityLabel);
+                                const pct = selectivity;
                                 if (pct < 1) {
                                     return l10n.t(
                                         'This query returns {0} of your collection.\n\nThis is highly selective: only a small fraction of documents pass the filter. The database does minimal work to produce results.',
-                                        selectivity,
+                                        displayValue,
                                     );
                                 } else if (pct < 20) {
                                     return l10n.t(
                                         'This query returns {0} of your collection.\n\nThis is a reasonable level of selectivity. The filter narrows results to a manageable portion of the data.',
-                                        selectivity,
+                                        displayValue,
                                     );
                                 } else {
                                     return l10n.t(
                                         'This query returns {0} of your collection.\n\nThis is a broad query that returns a large portion of the data. Consider adding more specific filters to narrow the results.',
-                                        selectivity,
+                                        displayValue,
                                     );
                                 }
                             })()}

src/webviews/documentdb/collectionView/queryInsights/queryInsightsRouter.ts

@@ -349,12 +349,9 @@ export const queryInsightsRouter = router({
             ctx.telemetry.measurements.totalCollectionDocs = totalCollectionDocs;
         }
 
-        // Selectivity as a number (strip the '%' if present)
-        if (transformed.efficiencyAnalysis.selectivity) {
-            const selectivityNum = parseFloat(transformed.efficiencyAnalysis.selectivity);
-            if (!isNaN(selectivityNum)) {
-                ctx.telemetry.measurements.selectivityPercent = selectivityNum;
-            }
+        const selectivityPercent = transformed.efficiencyAnalysis.selectivity;
+        if (selectivityPercent !== null && selectivityPercent !== undefined) {
+            ctx.telemetry.measurements.selectivityPercent = selectivityPercent;
         }
 
         // Badge IDs (safe categorical data, no PII)

src/webviews/documentdb/collectionView/types/queryInsights.ts

@@ -81,7 +81,7 @@ export type FetchOverheadKind = 'noMatches' | 'covered' | 'collectionScan' | 'mu
  * - Top-level `examinedToReturnedRatio: number` - Raw ratio for calculations (e.g., 50.5)
  *
  * Efficiency analysis metrics:
- * - `efficiencyAnalysis.selectivity: string | null` - Percentage of collection returned
+ * - `efficiencyAnalysis.selectivity: number | null` - Percentage of collection returned
  * - `efficiencyAnalysis.fetchOverhead: string` - Localized display label for fetch state
  * - `efficiencyAnalysis.fetchOverheadKind: FetchOverheadKind` - Stable key for UI branching
  */
@@ -102,8 +102,8 @@ export interface QueryInsightsStage2Response {
     /** Top-level query warnings (collection scan, in-memory sort, etc.) */
     concerns: string[];
     efficiencyAnalysis: {
-        /** Selectivity: percentage of collection returned (e.g., "33.2%"), or null if unknown */
-        selectivity: string | null;
+        /** Selectivity: raw percentage of collection returned (e.g., 33.2375), or null if unknown */
+        selectivity: number | null;
         indexUsed: string | null;
         /** Fetch overhead state label (e.g., "Direct fetch", "Covered query", "Collection scan") */
         fetchOverhead: string;

src/webviews/documentdb/collectionView/utils/formatSelectivityForDisplay.test.ts

@@ -0,0 +1,30 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+import { formatSelectivityForDisplay } from './formatSelectivityForDisplay';
+
+describe('formatSelectivityForDisplay', () => {
+    const belowThresholdText = 'below 0.1%';
+    // Helper that mirrors the function's own formatting so expectations stay
+    // locale-agnostic when tests run under non-en-US system locales.
+    const fmt = (n: number): string =>
+        `${n.toLocaleString(undefined, { minimumFractionDigits: 1, maximumFractionDigits: 1 })}%`;
+
+    it('returns threshold text for non-zero selectivity below 0.1%', () => {
+        expect(formatSelectivityForDisplay(0.02, belowThresholdText)).toBe(belowThresholdText);
+        expect(formatSelectivityForDisplay(0.008, belowThresholdText)).toBe(belowThresholdText);
+    });
+
+    it('preserves values at or above 0.1%', () => {
+        expect(formatSelectivityForDisplay(0.1, belowThresholdText)).toBe(fmt(0.1));
+        expect(formatSelectivityForDisplay(5, belowThresholdText)).toBe(fmt(5));
+    });
+
+    it('preserves zero and unavailable values', () => {
+        expect(formatSelectivityForDisplay(0, belowThresholdText)).toBe(fmt(0));
+        expect(formatSelectivityForDisplay(null, belowThresholdText)).toBeNull();
+        expect(formatSelectivityForDisplay(undefined, belowThresholdText)).toBeUndefined();
+    });
+});

src/webviews/documentdb/collectionView/utils/formatSelectivityForDisplay.ts

@@ -0,0 +1,36 @@
+/*---------------------------------------------------------------------------------------------
+ *  Copyright (c) Microsoft Corporation. All rights reserved.
+ *  Licensed under the MIT License. See License.txt in the project root for license information.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * Formats selectivity for UI display.
+ *
+ * For very low non-zero percentages (< 0.1%), we show a threshold label
+ * instead of a rounded numeric value.
+ *
+ * Keep this logic in sync with the static analysis summary formatter so Stage 3
+ * output and the webview render the same values for the same input.
+ * We intentionally left this duplicated for now to keep the change simple.
+ */
+export function formatSelectivityForDisplay(selectivity: number, belowThresholdLabel: string): string;
+export function formatSelectivityForDisplay(selectivity: null, belowThresholdLabel: string): null;
+export function formatSelectivityForDisplay(selectivity: undefined, belowThresholdLabel: string): undefined;
+export function formatSelectivityForDisplay(
+    selectivity: number | null | undefined,
+    belowThresholdLabel: string,
+): string | null | undefined;
+export function formatSelectivityForDisplay(
+    selectivity: number | null | undefined,
+    belowThresholdLabel: string,
+): string | null | undefined {
+    if (selectivity === null || selectivity === undefined) {
+        return selectivity;
+    }
+
+    if (selectivity > 0 && selectivity < 0.1) {
+        return belowThresholdLabel;
+    }
+
+    return `${selectivity.toLocaleString(undefined, { minimumFractionDigits: 1, maximumFractionDigits: 1 })}%`;
+}