feat(sea): Thrift-parity for intervals, getInfo, and SQL-error class

Three driver-side parity fixes validated via the node comparator
(thrift-vs-SEA on a live warehouse); params/queryTimeout are intentionally
out of scope (positional params land via the kernel TypedValue codec).

- intervals: default `intervalsAsString: true` on the SEA connection
  (SeaAuth) so INTERVAL columns surface as strings like the Thrift driver,
  and map a physical-Utf8 column carrying INTERVAL type-name metadata to
  STRING in SeaArrowIpc (the kernel keeps the INTERVAL metadata even when
  rendering as string). Result: interval columns match Thrift in both type
  code (7) and value. Requires the kernel napi `intervalsAsString` knob.
- getInfo: synthesize the three TGetInfoTypes the Thrift server answers —
  CLI_SERVER_NAME / CLI_DBMS_NAME = "Spark SQL", CLI_DBMS_VER = "3.1.1" —
  client-side (JDBC DatabaseMetaData style; SEA/kernel has no getInfo RPC),
  and reject the rest like the server does. New SeaServerInfo.ts.
- error class: map kernel `SqlError` (server execution failures —
  PERMISSION_DENIED, SCHEMA_ALREADY_EXISTS, bad SQL) to
  OperationStateError(ERROR) instead of the base HiveDriverError, matching
  the Thrift backend's operation-status error class.

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

Author: msrathore-db

lib/sea/SeaArrowIpc.ts

@@ -112,6 +112,19 @@ export function patchIpcBytes(ipcBytes: Buffer): Buffer {
 function arrowTypeToTTypeId(field: Field<DataType>): TTypeId {
   const typeName = field.metadata.get(DATABRICKS_TYPE_NAME)?.toUpperCase();
 
+  // `intervals_as_string` (set by the SEA backend for Thrift parity)
+  // renders INTERVAL columns as physical Arrow `Utf8` while the kernel
+  // keeps the `INTERVAL …` type_name metadata. The Thrift driver reports
+  // such string-rendered intervals as STRING (type 7), so honour the
+  // physical type here rather than the semantic metadata — otherwise the
+  // SEA path would report INTERVAL (20/21) and diverge from Thrift on a
+  // column whose values are already identical strings. Native interval
+  // encodings (the kernel default) are Duration / MonthInterval, never
+  // Utf8, so this guard is inert unless `intervals_as_string` is on.
+  if (typeName?.startsWith('INTERVAL') && DataType.isUtf8(field.type)) {
+    return TTypeId.STRING_TYPE;
+  }
+
   switch (typeName) {
     case 'BOOLEAN':
       return TTypeId.BOOLEAN_TYPE;

lib/sea/SeaAuth.ts

@@ -66,6 +66,24 @@ export interface SeaSessionDefaults {
   catalog?: string;
   schema?: string;
   sessionConf?: Record<string, string>;
+  /**
+   * Render `INTERVAL` / `DURATION` result columns as strings
+   * (kernel `ResultConfig.intervals_as_string`). The kernel default is
+   * native Arrow `month_interval` / `duration[us]`, but the NodeJS
+   * Thrift driver surfaces intervals as strings — so the SEA path sets
+   * this `true` so its result shape is a byte-compatible drop-in for the
+   * Thrift backend. Omitting it falls back to the kernel's native types.
+   */
+  intervalsAsString?: boolean;
+  /**
+   * Render complex (`ARRAY` / `MAP` / `STRUCT` / `VARIANT`) result
+   * columns as JSON strings (kernel `ResultConfig.complex_types_as_json`).
+   * Left unset on the SEA path: native Arrow nested types already decode
+   * identically to the Thrift backend through the shared Arrow converter,
+   * so forcing JSON here would *introduce* a divergence rather than
+   * remove one.
+   */
+  complexTypesAsJson?: boolean;
 }
 
 export type SeaNativeConnectionOptions = SeaSessionDefaults &
@@ -161,6 +179,13 @@ export function buildSeaConnectionOptions(options: ConnectionOptions): SeaNative
   const base = {
     hostName: options.host,
     httpPath: prependSlash(options.path),
+    // Match the NodeJS Thrift driver, which surfaces INTERVAL columns as
+    // strings. The kernel defaults to native Arrow interval/duration
+    // types; forcing the string rendering here keeps the SEA path a
+    // byte-compatible drop-in. Complex types are intentionally left at
+    // the kernel default (native Arrow) — they already decode identically
+    // to Thrift via the shared Arrow converter.
+    intervalsAsString: true,
   };
 
   const oauth = options as {

lib/sea/SeaErrorMapping.ts

@@ -147,6 +147,18 @@ export function mapKernelErrorToJsError(kErr: KernelErrorShape): ErrorWithSqlSta
       error = new ParameterError(message);
       break;
 
+    case 'SqlError':
+      // A server-side SQL execution failure (the statement reached an
+      // ERROR state on the warehouse — bad SQL, PERMISSION_DENIED,
+      // SCHEMA_ALREADY_EXISTS, …). The Thrift backend surfaces exactly
+      // this situation as an `OperationStateError(ERROR)` after polling
+      // the operation status, so we mirror that class here for
+      // drop-in parity (both extend HiveDriverError, so existing
+      // `catch (HiveDriverError)` callers are unaffected).
+      error = new OperationStateError(OperationStateErrorCode.Error);
+      error.message = message;
+      break;
+
     // All remaining kernel ErrorCode variants map to the base driver error class.
     // M0 intentionally does not introduce new error classes; M1 may add nuance.
     case 'NotFound':
@@ -156,7 +168,6 @@ export function mapKernelErrorToJsError(kErr: KernelErrorShape): ErrorWithSqlSta
     case 'Internal':
     case 'InvalidStatementHandle':
     case 'NetworkError':
-    case 'SqlError':
       error = new HiveDriverError(message);
       break;
 

lib/sea/SeaServerInfo.ts

@@ -0,0 +1,67 @@
+// Copyright (c) 2026 Databricks, Inc.
+//
+// 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 { TGetInfoType, TGetInfoValue } from '../../thrift/TCLIService_types';
+
+/**
+ * `getInfo` (JDBC `DatabaseMetaData` / ODBC `SQLGetInfo`) is a Thrift-protocol
+ * concept: the Thrift backend forwards `TGetInfoReq` to the server's `getInfo`
+ * RPC. The SEA REST protocol and the Rust kernel have **no** equivalent
+ * endpoint, so — exactly as JDBC does for `DatabaseMetaData` — we synthesize
+ * the values client-side.
+ *
+ * The Databricks Thrift server itself answers only three `TGetInfoType`s and
+ * rejects every other value; we mirror that surface byte-for-byte so the SEA
+ * path is a drop-in equivalent:
+ *
+ *   | TGetInfoType        | Thrift server | SEA (here)        |
+ *   |---------------------|---------------|-------------------|
+ *   | CLI_SERVER_NAME (13)| "Spark SQL"   | "Spark SQL"        |
+ *   | CLI_DBMS_NAME   (17)| "Spark SQL"   | "Spark SQL"        |
+ *   | CLI_DBMS_VER    (18)| "3.1.1"       | "3.1.1"            |
+ *   | (any other)         | error         | undefined → error  |
+ */
+
+/** Canonical DBMS product name — identical to the Thrift server's value. */
+export const SEA_DBMS_NAME = 'Spark SQL';
+
+/** Server-name answer — identical to the Thrift server's value. */
+export const SEA_SERVER_NAME = 'Spark SQL';
+
+/**
+ * DBMS version string. Mirrors the constant the Databricks Thrift server
+ * reports for `CLI_DBMS_VER` (the HiveServer2-compat Spark SQL version, not
+ * the DBR release). Kept in lock-step with Thrift for parity; if the server
+ * ever changes it the comparator's GET_INFO suite flags the drift.
+ */
+export const SEA_DBMS_VERSION = '3.1.1';
+
+/**
+ * Synthesize the `TGetInfoValue` for a `getInfo` request on the SEA path.
+ * Returns `undefined` for any `TGetInfoType` the (Thrift) server does not
+ * answer — the caller surfaces that as an error, matching Thrift's
+ * reject-unsupported-info-type behaviour.
+ */
+export function seaServerInfoValue(infoType: number): TGetInfoValue | undefined {
+  switch (infoType) {
+    case TGetInfoType.CLI_SERVER_NAME:
+      return new TGetInfoValue({ stringValue: SEA_SERVER_NAME });
+    case TGetInfoType.CLI_DBMS_NAME:
+      return new TGetInfoValue({ stringValue: SEA_DBMS_NAME });
+    case TGetInfoType.CLI_DBMS_VER:
+      return new TGetInfoValue({ stringValue: SEA_DBMS_VERSION });
+    default:
+      return undefined;
+  }
+}

lib/sea/SeaSessionBackend.ts

@@ -35,6 +35,7 @@ import { SeaNativeConnection } from './SeaNativeLoader';
 import { decodeNapiKernelError } from './SeaErrorMapping';
 import SeaOperationBackend from './SeaOperationBackend';
 import SeaTableTypeFilter from './SeaTableTypeFilter';
+import { seaServerInfoValue } from './SeaServerInfo';
 
 export interface SeaSessionBackendOptions {
   /** The opaque napi `Connection` handle returned by `openSession`. */
@@ -90,8 +91,23 @@ export default class SeaSessionBackend implements ISessionBackend {
     return this._id;
   }
 
-  public async getInfo(_infoType: number): Promise<InfoValue> {
-    throw new HiveDriverError('SeaSessionBackend.getInfo: not implemented yet (deferred to M1)');
+  public async getInfo(infoType: number): Promise<InfoValue> {
+    this.failIfClosed();
+    // `getInfo` (TGetInfoReq) is a Thrift/JDBC concept with no SEA-protocol or
+    // kernel equivalent, so — like JDBC's DatabaseMetaData — we synthesize the
+    // values client-side. `seaServerInfoValue` returns matches for the three
+    // TGetInfoTypes the Thrift server answers (server name, DBMS name, DBMS
+    // version) and `undefined` for the rest, which we surface as an error to
+    // mirror the server's reject-unsupported-info-type behaviour.
+    const value = seaServerInfoValue(infoType);
+    if (value === undefined) {
+      throw new HiveDriverError(
+        `SEA getInfo: TGetInfoType ${infoType} is not supported. The SEA/kernel protocol ` +
+          'has no getInfo RPC; only CLI_SERVER_NAME, CLI_DBMS_NAME and CLI_DBMS_VER are ' +
+          'synthesised (matching the Thrift server, which also rejects all other info types).',
+      );
+    }
+    return new InfoValue(value);
   }
 
   /**

tests/unit/sea/SeaIntervalParity.test.ts

@@ -40,9 +40,11 @@ import {
   RecordBatch,
   makeData,
   Struct,
+  Utf8,
   vectorFromArray,
   tableToIPC,
 } from 'apache-arrow';
+import { arrowSchemaToThriftSchema } from '../../../lib/sea/SeaArrowIpc';
 
 // eslint-disable-next-line import/no-internal-modules
 import { Message as FbMessage } from 'apache-arrow/fb/message';
@@ -363,3 +365,29 @@ describe('SeaOperationBackend — INTERVAL parity with thrift', () => {
     expect((rows[0] as any).iv).to.equal('1 00:00:00.000000000');
   });
 });
+
+describe('SeaArrowIpc interval-as-string type mapping (Thrift parity)', () => {
+  const { TTypeId } = require('../../../thrift/TCLIService_types'); // eslint-disable-line @typescript-eslint/no-var-requires, global-require, import/no-internal-modules
+
+  function thriftType(field: Field) {
+    const cols = arrowSchemaToThriftSchema(new Schema([field])).columns;
+    return cols[0].typeDesc?.types?.[0]?.primitiveEntry?.type;
+  }
+
+  it('Utf8 + INTERVAL DAY TO SECOND metadata → STRING (matches Thrift, not INTERVAL)', () => {
+    // intervals_as_string=true renders the column as physical Utf8 while the
+    // kernel keeps the INTERVAL type_name metadata; we must report STRING.
+    const f = new Field('dt', new Utf8(), true, new Map([['databricks.type_name', 'INTERVAL DAY TO SECOND']]));
+    expect(thriftType(f)).to.equal(TTypeId.STRING_TYPE);
+  });
+
+  it('Utf8 + INTERVAL YEAR TO MONTH metadata → STRING', () => {
+    const f = new Field('ym', new Utf8(), true, new Map([['databricks.type_name', 'INTERVAL YEAR TO MONTH']]));
+    expect(thriftType(f)).to.equal(TTypeId.STRING_TYPE);
+  });
+
+  it('native Arrow Interval + INTERVAL metadata still maps to INTERVAL_YEAR_MONTH (guard is inert without intervals_as_string)', () => {
+    const f = new Field('ym', new Interval(IntervalUnit.YEAR_MONTH), true, new Map([['databricks.type_name', 'INTERVAL YEAR TO MONTH']]));
+    expect(thriftType(f)).to.equal(TTypeId.INTERVAL_YEAR_MONTH_TYPE);
+  });
+});

tests/unit/sea/auth-m2m.test.ts

@@ -38,6 +38,7 @@ describe('SeaAuth + SeaBackend — OAuth M2M auth flow', () => {
         authMode: 'OAuthM2m',
         oauthClientId: 'client-uuid',
         oauthClientSecret: 'dose-fake-secret',
+        intervalsAsString: true,
       });
     });
 
@@ -182,6 +183,7 @@ describe('SeaAuth + SeaBackend — OAuth M2M auth flow', () => {
         authMode: 'OAuthM2m',
         oauthClientId: 'client-uuid',
         oauthClientSecret: 'dose-fake-secret',
+        intervalsAsString: true,
       });
 
       await session.close();

tests/unit/sea/auth-pat.test.ts

@@ -33,6 +33,7 @@ describe('SeaAuth — PAT auth options builder', () => {
         httpPath: '/sql/1.0/warehouses/abc',
         authMode: 'Pat',
         token: 'dapi-fake-pat',
+        intervalsAsString: true,
       });
     });
 

tests/unit/sea/auth-u2m.test.ts

@@ -35,6 +35,7 @@ describe('SeaAuth + SeaBackend — OAuth U2M auth flow', () => {
         httpPath: '/sql/1.0/warehouses/abc',
         authMode: 'OAuthU2m',
         oauthRedirectPort: 8030,
+        intervalsAsString: true,
       });
     });
 
@@ -145,6 +146,7 @@ describe('SeaAuth + SeaBackend — OAuth U2M auth flow', () => {
         httpPath: '/sql/1.0/warehouses/abc',
         authMode: 'OAuthU2m',
         oauthRedirectPort: 8030,
+        intervalsAsString: true,
       });
 
       await session.close();

tests/unit/sea/error-mapping.test.ts

@@ -76,8 +76,15 @@ describe('SeaErrorMapping.mapKernelErrorToJsError', () => {
       expectedClass: HiveDriverError,
     },
     {
+      // Server-side SQL execution failures surface as OperationStateError(ERROR),
+      // mirroring the Thrift backend's operation-status-poll error path so the
+      // two drivers throw the same class. (OperationStateError extends
+      // HiveDriverError, so base-class catchers still match.)
       code: 'SqlError',
-      expectedClass: HiveDriverError,
+      expectedClass: OperationStateError,
+      extra: (err) => {
+        expect((err as OperationStateError).errorCode).to.equal(OperationStateErrorCode.Error);
+      },
     },
   ];