feat(thrift): per-statement metricViewMetadata knob on ExecuteStatementOptions

Add `metricViewMetadata?: boolean` to `ExecuteStatementOptions`. When true,
the Thrift backend forwards
`spark.databricks.optimizer.enableMetricViewMetadata=true` via the request
`confOverlay`, alongside any `query_tags` already serialized there. The
option is per-statement only and does not persist across queries.

The SEA backend will route the same key through napi `statementConf` once
the kernel statement-options surface lands; until then the option is
honored only on Thrift. Documented in the public option JSDoc so users do
not silently lose the conf on SEA.

Unit tests assert the option appears in the outgoing `TExecuteStatementReq`
when set, is omitted when unset or `false`, and coexists with `queryTags`
in the same `confOverlay`.

Audit refs: rows 1.17 and 2.18 of
sea-workflow/audits/2026-05-28-cross-driver-audit.md (F12 in the PR #347
audit).

Co-authored-by: Isaac
Signed-off-by: Madhavendra Rathore <madhavendra.rathore@databricks.com>

Author: msrathore-db

lib/contracts/IDBSQLSession.ts

@@ -27,6 +27,17 @@ export type ExecuteStatementOptions = {
    * These tags apply only to this statement and do not persist across queries.
    */
   queryTags?: Record<string, string | null | undefined>;
+  /**
+   * Enable metric-view metadata expansion for this statement. When `true`, the
+   * Spark conf `spark.databricks.optimizer.enableMetricViewMetadata=true` is
+   * forwarded via the Thrift `confOverlay`. Applies to a single statement only;
+   * does not persist across queries.
+   *
+   * Equivalent SEA wiring will route the same key through napi `statementConf`
+   * once the kernel statement-options surface lands — until then this knob is
+   * honored only on the Thrift backend.
+   */
+  metricViewMetadata?: boolean;
 };
 
 export type TypeInfoRequest = {

lib/thrift-backend/ThriftSessionBackend.ts

@@ -188,6 +188,13 @@ export default class ThriftSessionBackend implements ISessionBackend {
       request.confOverlay = { ...request.confOverlay, query_tags: serializedQueryTags };
     }
 
+    if (options.metricViewMetadata === true) {
+      request.confOverlay = {
+        ...request.confOverlay,
+        'spark.databricks.optimizer.enableMetricViewMetadata': 'true',
+      };
+    }
+
     if (ProtocolVersion.supportsCloudFetch(this.serverProtocolVersion)) {
       request.canDownloadResult = options.useCloudFetch ?? clientConfig.useCloudFetch;
     }

tests/unit/DBSQLSession.test.ts

@@ -298,6 +298,64 @@ describe('DBSQLSession', () => {
     });
   });
 
+  describe('executeStatement with metricViewMetadata', () => {
+    const metricViewConfKey = 'spark.databricks.optimizer.enableMetricViewMetadata';
+
+    it('should forward the metric-view conf via confOverlay when metricViewMetadata is true', async () => {
+      const context = new ClientContextStub();
+      const driver = sinon.spy(context.driver);
+      const session = new DBSQLSession({ handle: sessionHandleStub, context });
+
+      await session.executeStatement('SELECT * FROM my_metric_view', { metricViewMetadata: true });
+
+      expect(driver.executeStatement.callCount).to.eq(1);
+      const req = driver.executeStatement.firstCall.args[0];
+      expect(req.confOverlay).to.deep.include({ [metricViewConfKey]: 'true' });
+    });
+
+    it('should not set the metric-view conf when metricViewMetadata is omitted', async () => {
+      const context = new ClientContextStub();
+      const driver = sinon.spy(context.driver);
+      const session = new DBSQLSession({ handle: sessionHandleStub, context });
+
+      await session.executeStatement('SELECT 1');
+
+      expect(driver.executeStatement.callCount).to.eq(1);
+      const req = driver.executeStatement.firstCall.args[0];
+      expect(req.confOverlay?.[metricViewConfKey]).to.be.undefined;
+    });
+
+    it('should not set the metric-view conf when metricViewMetadata is false', async () => {
+      const context = new ClientContextStub();
+      const driver = sinon.spy(context.driver);
+      const session = new DBSQLSession({ handle: sessionHandleStub, context });
+
+      await session.executeStatement('SELECT 1', { metricViewMetadata: false });
+
+      expect(driver.executeStatement.callCount).to.eq(1);
+      const req = driver.executeStatement.firstCall.args[0];
+      expect(req.confOverlay?.[metricViewConfKey]).to.be.undefined;
+    });
+
+    it('should coexist with queryTags in the same confOverlay', async () => {
+      const context = new ClientContextStub();
+      const driver = sinon.spy(context.driver);
+      const session = new DBSQLSession({ handle: sessionHandleStub, context });
+
+      await session.executeStatement('SELECT 1', {
+        metricViewMetadata: true,
+        queryTags: { team: 'eng' },
+      });
+
+      expect(driver.executeStatement.callCount).to.eq(1);
+      const req = driver.executeStatement.firstCall.args[0];
+      expect(req.confOverlay).to.deep.include({
+        [metricViewConfKey]: 'true',
+        query_tags: 'team:eng',
+      });
+    });
+  });
+
   describe('getTypeInfo', () => {
     it('should run operation', async () => {
       const session = createSessionForTest({ handle: sessionHandleStub, context: new ClientContextStub() });