Return empty primary-key metadata for missing objects in Thrift

CHANGELOG.md

@@ -3,6 +3,7 @@
 ## Unreleased
 
 - **Breaking:** require Node.js versions containing the CVE-2026-111497 Brotli decoder fix: 22.23.4+, 24.22.1+, or 26.12.1+. Node.js 20, 23, and 25 are no longer supported because those end-of-life lines have no fix.
+- Return empty results with the standard schema from Thrift `getPrimaryKeys()` when a catalog, schema, or table is missing, instead of throwing. (#553)
 
 ## 2.4.0
 

lib/thrift-backend/EmptyOperationBackend.ts

@@ -0,0 +1,44 @@
+import { v4 } from 'uuid';
+import { TTableSchema } from '../../thrift/TCLIService_types';
+import IOperationBackend from '../contracts/IOperationBackend';
+import { OperationState, OperationStatus } from '../contracts/OperationStatus';
+import { ResultFormat, ResultMetadata } from '../contracts/ResultMetadata';
+import Status from '../dto/Status';
+
+export default class EmptyOperationBackend implements IOperationBackend {
+  public readonly id = v4();
+
+  constructor(private readonly schema: TTableSchema) {}
+
+  public hasResultSet(): boolean {
+    return true;
+  }
+
+  public async fetchChunk(): Promise<Array<object>> {
+    return [];
+  }
+
+  public async hasMore(): Promise<boolean> {
+    return false;
+  }
+
+  public async waitUntilReady(): Promise<void> {
+    return undefined;
+  }
+
+  public async status(): Promise<OperationStatus> {
+    return { state: OperationState.Succeeded, hasResultSet: true };
+  }
+
+  public async getResultMetadata(): Promise<ResultMetadata> {
+    return { schema: this.schema, resultFormat: ResultFormat.ColumnBased, isStagingOperation: false };
+  }
+
+  public async cancel(): Promise<Status> {
+    return Status.success();
+  }
+
+  public async close(): Promise<Status> {
+    return Status.success();
+  }
+}

lib/thrift-backend/ThriftOperationBackend.ts

@@ -7,6 +7,8 @@ import {
   TSparkRowSetType,
   TCloseOperationResp,
   TOperationState,
+  TStatusCode,
+  TTableSchema,
 } from '../../thrift/TCLIService_types';
 import IOperationBackend, { IOperationBackendWaitOptions } from '../contracts/IOperationBackend';
 import IClientContext from '../contracts/IClientContext';
@@ -24,12 +26,15 @@ import ArrowResultConverter from '../result/ArrowResultConverter';
 import ResultSlicer from '../result/ResultSlicer';
 import { definedOrError } from '../utils';
 import HiveDriverError from '../errors/HiveDriverError';
+import isObjectNotFound from './metadataErrors';
+import { synthesizeThriftResultSetMetadata } from './wireSynthesis';
 
 interface ThriftOperationBackendOptions {
   handle: TOperationHandle;
   directResults?: TSparkDirectResults;
   context: IClientContext;
   functionCatalog?: string | null;
+  emptyResultOnNotFound?: TTableSchema;
 }
 
 async function delay(ms?: number): Promise<void> {
@@ -78,6 +83,8 @@ export default class ThriftOperationBackend implements IOperationBackend {
 
   private readonly functionCatalog?: string | null;
 
+  private readonly emptyResultOnNotFound?: TTableSchema;
+
   private readonly operationHandle: TOperationHandle;
 
   private readonly _data: RowSetProvider;
@@ -94,18 +101,25 @@ export default class ThriftOperationBackend implements IOperationBackend {
 
   private resultHandler?: ResultSlicer<any>;
 
-  constructor({ handle, directResults, context, functionCatalog }: ThriftOperationBackendOptions) {
+  constructor({
+    handle,
+    directResults,
+    context,
+    functionCatalog,
+    emptyResultOnNotFound,
+  }: ThriftOperationBackendOptions) {
     this.operationHandle = handle;
     this.context = context;
     this.functionCatalog = functionCatalog;
+    this.emptyResultOnNotFound = emptyResultOnNotFound;
+    this.metadata = directResults?.resultSetMetadata;
 
     const useOnlyPrefetchedResults = Boolean(directResults?.closeOperation);
 
     if (directResults?.operationStatus) {
       this.processOperationStatusResponse(directResults.operationStatus);
     }
 
-    this.metadata = directResults?.resultSetMetadata;
     this._data = new RowSetProvider(
       this.context,
       this.operationHandle,
@@ -130,7 +144,7 @@ export default class ThriftOperationBackend implements IOperationBackend {
   }
 
   public hasResultSet(): boolean {
-    return Boolean(this.operationHandle.hasResultSet);
+    return Boolean(this.emptyResultOnNotFound || this.operationHandle.hasResultSet);
   }
 
   public async fetchChunk({
@@ -377,6 +391,37 @@ export default class ThriftOperationBackend implements IOperationBackend {
   }
 
   private processOperationStatusResponse(response: TGetOperationStatusResp) {
+    const isError =
+      response.operationState === TOperationState.ERROR_STATE ||
+      (response.operationState == null && response.status.statusCode === TStatusCode.ERROR_STATUS);
+    if (
+      this.emptyResultOnNotFound &&
+      isError &&
+      response.status.statusCode !== TStatusCode.INVALID_HANDLE_STATUS &&
+      (isObjectNotFound(response) || isObjectNotFound(response.status))
+    ) {
+      this.context.getLogger().log(
+        LogLevel.debug,
+        `Returning empty primary keys for missing object: ${JSON.stringify({
+          sqlState: response.sqlState ?? response.status.sqlState,
+          message: response.errorMessage ?? response.displayMessage ?? response.status.errorMessage,
+        })}`,
+      );
+      this.metadata = synthesizeThriftResultSetMetadata({
+        schema: this.emptyResultOnNotFound,
+        resultFormat: ResultFormat.ColumnBased,
+        isStagingOperation: false,
+      });
+      this.resultHandler = new ResultSlicer(this.context, {
+        fetchNext: async () => [],
+        hasMore: async () => false,
+      });
+      response = {
+        status: { statusCode: TStatusCode.SUCCESS_STATUS },
+        operationState: TOperationState.FINISHED_STATE,
+        hasResultSet: true,
+      };
+    }
     Status.assert(response.status);
 
     this.state = response.operationState ?? this.state;

lib/thrift-backend/ThriftSessionBackend.ts

@@ -9,6 +9,8 @@ import {
   TSparkParameter,
   TProtocolVersion,
   TExecuteStatementReq,
+  TStatusCode,
+  TOperationState,
 } from '../../thrift/TCLIService_types';
 import ISessionBackend from '../contracts/ISessionBackend';
 import IOperationBackend from '../contracts/IOperationBackend';
@@ -33,6 +35,9 @@ import { DBSQLParameter, DBSQLParameterValue } from '../DBSQLParameter';
 import { LogLevel } from '../contracts/IDBSQLLogger';
 import ThriftOperationBackend from './ThriftOperationBackend';
 import escapeCatalogName from '../utils/escapeCatalogName';
+import EmptyOperationBackend from './EmptyOperationBackend';
+import isObjectNotFound from './metadataErrors';
+import createPrimaryKeysSchema from './primaryKeysSchema';
 
 interface OperationResponseShape {
   status: TStatus;
@@ -313,7 +318,31 @@ export default class ThriftSessionBackend implements ISessionBackend {
       runAsync: this.getRunAsyncForMetadataOperations(),
       ...getDirectResultsOptions(request.maxRows, this.context.getConfig()),
     });
-    return this.createOperationBackend(response);
+    const notFound = response.status.statusCode === TStatusCode.ERROR_STATUS && isObjectNotFound(response.status);
+    if (notFound && !response.operationHandle) {
+      this.context.getLogger().log(
+        LogLevel.debug,
+        `Returning empty primary keys for missing object: ${JSON.stringify({
+          sqlState: response.status.sqlState,
+          message: response.status.errorMessage,
+        })}`,
+      );
+      return new EmptyOperationBackend(createPrimaryKeysSchema());
+    }
+    if (!notFound) {
+      Status.assert(response.status);
+    }
+    return new ThriftOperationBackend({
+      handle: definedOrError(response.operationHandle),
+      context: this.context,
+      directResults: notFound
+        ? {
+            ...response.directResults,
+            operationStatus: { status: response.status, operationState: TOperationState.ERROR_STATE },
+          }
+        : response.directResults,
+      emptyResultOnNotFound: createPrimaryKeysSchema(),
+    });
   }
 
   public async getCrossReference(request: CrossReferenceRequest): Promise<IOperationBackend> {

lib/thrift-backend/metadataErrors.ts

@@ -0,0 +1,17 @@
+interface MetadataError {
+  sqlState?: string | null;
+  errorMessage?: string | null;
+  displayMessage?: string | null;
+}
+
+export default function isObjectNotFound(error: MetadataError): boolean {
+  // Match Databricks JDBC's metadata not-found classification.
+  return (
+    error.sqlState === '42704' ||
+    [error.errorMessage, error.displayMessage].some((message) =>
+      ['NO_SUCH_CATALOG_EXCEPTION', 'SCHEMA_NOT_FOUND', 'TABLE_OR_VIEW_NOT_FOUND', 'INVALID_PARAMETER_VALUE'].some(
+        (errorClass) => message?.includes(errorClass),
+      ),
+    )
+  );
+}

lib/thrift-backend/primaryKeysSchema.ts

@@ -0,0 +1,17 @@
+import { TTableSchema, TTypeId } from '../../thrift/TCLIService_types';
+
+export default function createPrimaryKeysSchema(): TTableSchema {
+  return {
+    // Preserve the Thrift server's KEQ_SEQ spelling.
+    columns: ['TABLE_CAT', 'TABLE_SCHEM', 'TABLE_NAME', 'COLUMN_NAME', 'KEQ_SEQ', 'PK_NAME'].map(
+      (columnName, index) => ({
+        columnName,
+        typeDesc: {
+          types: [{ primitiveEntry: { type: columnName === 'KEQ_SEQ' ? TTypeId.INT_TYPE : TTypeId.STRING_TYPE } }],
+        },
+        position: index + 1,
+        comment: '',
+      }),
+    ),
+  };
+}

tests/e2e/primary_keys_metadata.test.ts

@@ -0,0 +1,69 @@
+import { expect } from 'chai';
+import { v4 } from 'uuid';
+import { DBSQLClient } from '../../lib';
+import IDBSQLSession from '../../lib/contracts/IDBSQLSession';
+import { TOperationState, TStatusCode, TTypeId } from '../../thrift/TCLIService_types';
+import config from './utils/config';
+
+describe('Thrift primary-key metadata', () => {
+  const missingName = `missing_primary_keys_${v4().replace(/-/g, '')}`;
+  let client: DBSQLClient;
+  let session: IDBSQLSession;
+
+  before(async () => {
+    client = new DBSQLClient();
+    await client.connect({ host: config.host, path: config.path, token: config.token });
+    session = await client.openSession({ initialCatalog: config.catalog, initialSchema: config.schema });
+  });
+
+  after(async () => {
+    try {
+      await session?.close();
+    } finally {
+      await client?.close();
+    }
+  });
+
+  [
+    { missingObject: 'schema', catalogName: config.catalog, schemaName: missingName },
+    { missingObject: 'catalog', catalogName: missingName, schemaName: config.schema },
+    { missingObject: 'table', catalogName: config.catalog, schemaName: config.schema },
+  ].forEach(({ missingObject, catalogName, schemaName }) => {
+    [1000, null].forEach((maxRows) => {
+      it(`returns typed empty primary keys for a missing ${missingObject} with direct results ${
+        maxRows === null ? 'off' : 'on'
+      }`, async () => {
+        const operation = await session.getPrimaryKeys({
+          catalogName,
+          schemaName,
+          tableName: missingName,
+          maxRows,
+        });
+        try {
+          const schema = await operation.getSchema();
+          expect(
+            schema?.columns.map((column) => [
+              column.columnName,
+              column.typeDesc.types[0].primitiveEntry?.type,
+              column.position,
+            ]),
+          ).to.deep.equal([
+            ['TABLE_CAT', TTypeId.STRING_TYPE, 1],
+            ['TABLE_SCHEM', TTypeId.STRING_TYPE, 2],
+            ['TABLE_NAME', TTypeId.STRING_TYPE, 3],
+            ['COLUMN_NAME', TTypeId.STRING_TYPE, 4],
+            ['KEQ_SEQ', TTypeId.INT_TYPE, 5],
+            ['PK_NAME', TTypeId.STRING_TYPE, 6],
+          ]);
+          expect(await operation.fetchAll()).to.deep.equal([]);
+          expect(await operation.hasMoreRows()).to.be.false;
+          const status = await operation.status();
+          expect(status.status.statusCode).to.equal(TStatusCode.SUCCESS_STATUS);
+          expect(status.operationState).to.equal(TOperationState.FINISHED_STATE);
+        } finally {
+          await operation.close();
+        }
+      });
+    });
+  });
+});