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

l10n/bundle.l10n.json

@@ -267,6 +267,7 @@
   "Back": "Back",
   "Back to account selection": "Back to account selection",
   "Back to tenant selection": "Back to tenant selection",
+  "below {0}%": "below {0}%",
   "Bitmap index": "Bitmap index",
   "Bitmap index detected: typically used for low-cardinality fields": "Bitmap index detected: typically used for low-cardinality fields",
   "Bulk write error during import into \"{0}.{1}\": {2} document(s) inserted.": "Bulk write error during import into \"{0}.{1}\": {2} document(s) inserted.",

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 formatting', () => {
+    it('preserves precision below 0.1% for non-zero selectivity', () => {
+        const analyzed = createExecutionStatsAnalysis({
+            nReturned: 1,
+        });
+
+        const result = transformStage2Response(analyzed, 12_000);
+
+        expect(result.efficiencyAnalysis.selectivity).toBe('0.008%');
+    });
+
+    it('keeps one-decimal formatting for selectivity 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

@@ -200,7 +200,11 @@ function computeSelectivity(nReturned: number, totalCollectionDocs: number | und
         return null;
     }
     const ratio = Math.min(nReturned / totalCollectionDocs, 1);
-    return `${(ratio * 100).toFixed(1)}%`;
+    const percent = ratio * 100;
+    if (percent > 0 && percent < 0.1) {
+        return `${percent.toFixed(3).replace(/\.?0+$/, '')}%`;
+    }
+    return `${percent.toFixed(1)}%`;
 }
 
 /**

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,10 @@ export const QueryInsightsMain = (): JSX.Element => {
     const docsReturned = getMetricValue(stage2Data?.documentsReturned);
     const keysExamined = getMetricValue(stage2Data?.totalKeysExamined);
     const docsExamined = getMetricValue(stage2Data?.totalDocsExamined);
+    const selectivity = formatSelectivityForDisplay(
+        getCellValue((stage2) => stage2.efficiencyAnalysis.selectivity),
+        l10n.t('below {0}%', '0.1'),
+    );
 
     /**
      * Documentation URL for the AI Performance Insights feature itself
@@ -1133,7 +1138,7 @@ 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;

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

@@ -0,0 +1,26 @@
+/*---------------------------------------------------------------------------------------------
+ *  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%';
+
+    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('0.1%');
+        expect(formatSelectivityForDisplay('5.0%', belowThresholdText)).toBe('5.0%');
+    });
+
+    it('preserves zero and unavailable values', () => {
+        expect(formatSelectivityForDisplay('0.0%', belowThresholdText)).toBe('0.0%');
+        expect(formatSelectivityForDisplay(null, belowThresholdText)).toBeNull();
+        expect(formatSelectivityForDisplay(undefined, belowThresholdText)).toBeUndefined();
+    });
+});

src/webviews/documentdb/collectionView/utils/formatSelectivityForDisplay.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.
+ *--------------------------------------------------------------------------------------------*/
+
+/**
+ * Formats selectivity for UI display.
+ *
+ * For very low non-zero percentages (< 0.1%), we show a threshold label
+ * instead of a rounded numeric value.
+ */
+export function formatSelectivityForDisplay(
+    selectivity: string | null | undefined,
+    belowThresholdLabel: string,
+): string | null | undefined {
+    if (!selectivity) {
+        return selectivity;
+    }
+
+    const selectivityPercent = Number.parseFloat(selectivity);
+    if (Number.isNaN(selectivityPercent)) {
+        return selectivity;
+    }
+
+    if (selectivityPercent > 0 && selectivityPercent < 0.1) {
+        return belowThresholdLabel;
+    }
+
+    return selectivity;
+}