Merge remote-tracking branch 'origin/main' into pr-363

# Conflicts:
#	CHANGELOG.md

Author: msrathore-db

.prettierignore

@@ -5,6 +5,7 @@ node_modules
 .nyc_output
 coverage_e2e
 coverage_unit
+coverage
 .clinic
 
 dist

CHANGELOG.md

@@ -4,6 +4,12 @@
 
 - Fix Azure AD OAuth for tenant-specific and single-tenant Entra apps, and correct the scope resource: use the Databricks Azure Login App ID (not the tenant GUID) as the OAuth scope; route OIDC discovery to `login.microsoftonline.com/${azureTenantId}/` when `azureTenantId` is provided (fallback `/organizations/` preserved).
 
+## 1.14.0
+
+- Add statement-level query tag support (databricks/databricks-sql-nodejs#366 by @sreekanth-db)
+- Add AI coding agent detection to User-Agent header (databricks/databricks-sql-nodejs#333 by @vikrantpuppala)
+- Internal: telemetry infrastructure improvements — circuit breaker, feature flag cache, telemetry client management (off by default) (databricks/databricks-sql-nodejs#325, #326, #362)
+
 ## 1.13.0
 
 - Add token federation support with custom token providers (databricks/databricks-sql-nodejs#318, databricks/databricks-sql-nodejs#319, databricks/databricks-sql-nodejs#320 by @madhav-db)

examples/query_tags.js

@@ -0,0 +1,59 @@
+const { DBSQLClient } = require('..');
+
+const client = new DBSQLClient();
+
+const host = process.env.DATABRICKS_HOST;
+const path = process.env.DATABRICKS_HTTP_PATH;
+const token = process.env.DATABRICKS_TOKEN;
+
+client
+  .connect({ host, path, token })
+  .then(async (client) => {
+    // Session-level query tags: applied to every statement run on this session
+    // (serialized into the session's QUERY_TAGS configuration).
+    const session = await client.openSession({
+      queryTags: {
+        team: 'engineering',
+        env: 'dev',
+        driver: 'node',
+      },
+    });
+
+    // Statement A: inherits session-level tags only.
+    const opA = await session.executeStatement('SELECT 1 AS inherits_session_tags');
+    console.log(await opA.fetchAll());
+    await opA.close();
+
+    // Statement B: statement-level query tags via executeStatement options.
+    // These are passed via confOverlay as "query_tags" and apply ONLY to this statement.
+    // Note: `env` here overrides the session-level `env: 'dev'` — for this statement
+    // it will be `env: 'prod'`. Subsequent statements without statement-level tags
+    // revert to the session-level values.
+    const opB = await session.executeStatement('SELECT 2 AS has_statement_tags', {
+      queryTags: {
+        env: 'prod',
+        request_id: 'abc-123',
+        feature: 'reporting',
+      },
+    });
+    console.log(await opB.fetchAll());
+    await opB.close();
+
+    // Statement C: demonstrates escaping of special characters (`\`, `:`, `,`)
+    // in tag values, plus null/undefined values which serialize as bare keys.
+    const opC = await session.executeStatement('SELECT 3 AS escaped_and_null_tags', {
+      queryTags: {
+        path: 'C:\\users\\me',
+        note: 'hello, world',
+        flag: null,
+      },
+    });
+    console.log(await opC.fetchAll());
+    await opC.close();
+
+    await session.close();
+    await client.close();
+  })
+  .catch((error) => {
+    console.log(error);
+  });

examples/session_params.js

@@ -10,8 +10,12 @@ client
   .connect({ host, path, token })
   .then(async (client) => {
     const session = await client.openSession({
+      queryTags: {
+        team: 'engineering',
+        test: 'session-params',
+        driver: 'node',
+      },
       configuration: {
-        QUERY_TAGS: 'team:engineering,test:session-params,driver:node',
         ansi_mode: 'false',
       },
     });

lib/DBSQLClient.ts

@@ -16,7 +16,7 @@ import HttpConnection from './connection/connections/HttpConnection';
 import IConnectionOptions from './connection/contracts/IConnectionOptions';
 import Status from './dto/Status';
 import HiveDriverError from './errors/HiveDriverError';
-import { buildUserAgentString, definedOrError } from './utils';
+import { buildUserAgentString, definedOrError, serializeQueryTags } from './utils';
 import PlainHttpAuthentication from './connection/auth/PlainHttpAuthentication';
 import DatabricksOAuth, { OAuthFlow } from './connection/auth/DatabricksOAuth';
 import {
@@ -298,6 +298,16 @@ export default class DBSQLClient extends EventEmitter implements IDBSQLClient, I
       configuration['spark.sql.thriftserver.metadata.metricview.enabled'] = 'true';
     }
 
+    // Serialize queryTags dict and set in configuration; takes precedence over configuration.QUERY_TAGS
+    if (request.queryTags !== undefined) {
+      const serialized = serializeQueryTags(request.queryTags);
+      if (serialized) {
+        configuration.QUERY_TAGS = serialized;
+      } else {
+        delete configuration.QUERY_TAGS;
+      }
+    }
+
     const response = await this.driver.openSession({
       client_protocol_i64: new Int64(TProtocolVersion.SPARK_CLI_SERVICE_PROTOCOL_V8),
       ...getInitialNamespaceOptions(request.initialCatalog, request.initialSchema),

lib/DBSQLSession.ts

@@ -31,7 +31,7 @@ import IOperation from './contracts/IOperation';
 import DBSQLOperation from './DBSQLOperation';
 import Status from './dto/Status';
 import InfoValue from './dto/InfoValue';
-import { definedOrError, LZ4, ProtocolVersion } from './utils';
+import { definedOrError, LZ4, ProtocolVersion, serializeQueryTags } from './utils';
 import CloseableCollection from './utils/CloseableCollection';
 import { LogLevel } from './contracts/IDBSQLLogger';
 import HiveDriverError from './errors/HiveDriverError';
@@ -227,6 +227,11 @@ export default class DBSQLSession implements IDBSQLSession {
       request.parameters = getQueryParameters(options.namedParameters, options.ordinalParameters);
     }
 
+    const serializedQueryTags = serializeQueryTags(options.queryTags);
+    if (serializedQueryTags !== undefined) {
+      request.confOverlay = { ...request.confOverlay, query_tags: serializedQueryTags };
+    }
+
     if (ProtocolVersion.supportsCloudFetch(this.serverProtocolVersion)) {
       request.canDownloadResult = options.useCloudFetch ?? clientConfig.useCloudFetch;
     }

lib/contracts/IDBSQLClient.ts

@@ -60,6 +60,12 @@ export interface OpenSessionRequest {
   initialCatalog?: string;
   initialSchema?: string;
   configuration?: { [key: string]: string };
+  /**
+   * Session-level query tags as key-value pairs. Serialized and passed via session configuration
+   * as "QUERY_TAGS". Values may be null/undefined to include a key without a value.
+   * If both queryTags and configuration.QUERY_TAGS are specified, queryTags takes precedence.
+   */
+  queryTags?: Record<string, string | null | undefined>;
 }
 
 export default interface IDBSQLClient {

lib/contracts/IDBSQLSession.ts

@@ -21,6 +21,12 @@ export type ExecuteStatementOptions = {
   stagingAllowedLocalPath?: string | string[];
   namedParameters?: Record<string, DBSQLParameter | DBSQLParameterValue>;
   ordinalParameters?: Array<DBSQLParameter | DBSQLParameterValue>;
+  /**
+   * Per-statement query tags as key-value pairs. Serialized and passed via confOverlay
+   * as "query_tags". Values may be null/undefined to include a key without a value.
+   * These tags apply only to this statement and do not persist across queries.
+   */
+  queryTags?: Record<string, string | null | undefined>;
 };
 
 export type TypeInfoRequest = {

lib/telemetry/TelemetryClient.ts

@@ -0,0 +1,65 @@
+/**
+ * Copyright (c) 2025 Databricks Contributors
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+import IClientContext from '../contracts/IClientContext';
+import { LogLevel } from '../contracts/IDBSQLLogger';
+
+/**
+ * Telemetry client for a specific host.
+ * Managed by TelemetryClientProvider with reference counting.
+ * One client instance is shared across all connections to the same host.
+ */
+class TelemetryClient {
+  private closed: boolean = false;
+
+  constructor(private context: IClientContext, private host: string) {
+    const logger = context.getLogger();
+    logger.log(LogLevel.debug, `Created TelemetryClient for host: ${host}`);
+  }
+
+  /**
+   * Gets the host associated with this client.
+   */
+  getHost(): string {
+    return this.host;
+  }
+
+  /**
+   * Checks if the client has been closed.
+   */
+  isClosed(): boolean {
+    return this.closed;
+  }
+
+  /**
+   * Closes the telemetry client and releases resources.
+   * Should only be called by TelemetryClientProvider when reference count reaches zero.
+   */
+  close(): void {
+    if (this.closed) {
+      return;
+    }
+    try {
+      this.context.getLogger().log(LogLevel.debug, `Closing TelemetryClient for host: ${this.host}`);
+    } catch {
+      // swallow
+    } finally {
+      this.closed = true;
+    }
+  }
+}
+
+export default TelemetryClient;