@databricks/appkit 0.44.0 → 0.45.0

package/dist/appkit/package.js

@@ -1,6 +1,6 @@
 //#region package.json
 var name = "@databricks/appkit";
-var version = "0.44.0";
+var version = "0.45.0";
 
 //#endregion
 export { name, version };

package/dist/connectors/sql-warehouse/arrow-schema.js

@@ -0,0 +1,283 @@
+import { Binary, Bool, DateDay, Decimal, DurationMicrosecond, Field, Float32, Float64, Int16, Int32, Int64, Int8, IntervalYearMonth, List, Map_, Null, Schema, Struct, Table, TimestampMicrosecond, Utf8, tableToIPC } from "apache-arrow";
+
+//#region src/connectors/sql-warehouse/arrow-schema.ts
+/**
+* Parse a Databricks SQL type text (the value returned by the Statement
+* Execution API in `ColumnInfo.type_text`) into an Apache Arrow DataType.
+*
+* Supports:
+*   - All scalar types (STRING, INT, BIGINT, DECIMAL, TIMESTAMP, etc.)
+*   - Parameterized scalars: DECIMAL(p,s), VARCHAR(n), CHAR(n)
+*   - Nested types: ARRAY<T>, MAP<K,V>, STRUCT<f1:T1, f2:T2 COMMENT '...', ...>
+*   - INTERVAL year-month and day-time variants
+*   - Backtick-quoted struct field names with embedded `` `` `` escapes
+*
+* Unknown or unparseable types fall back to Utf8 — empty-Table consumers
+* still see a column with the right name; only the inner type is degraded.
+*/
+function parseDatabricksType(typeText) {
+	const parser = new TypeParser(typeText);
+	const result = parser.parseType();
+	parser.expectEnd();
+	return result;
+}
+/**
+* Build an empty Arrow IPC stream (base64-encoded) matching the column schema
+* returned by the warehouse. Used so ARROW_STREAM responses with no rows still
+* deliver a real Arrow Table to the client, preserving the hook's typed
+* contract.
+*/
+function buildEmptyArrowIPCBase64(columns) {
+	const ipc = tableToIPC(new Table(new Schema(columns.map((col, index) => {
+		const typeText = col.type_text ?? col.type_name ?? "STRING";
+		let dataType;
+		try {
+			dataType = parseDatabricksType(typeText);
+		} catch {
+			dataType = new Utf8();
+		}
+		return new Field(col.name && col.name.length > 0 ? col.name : `column_${index}`, dataType, true);
+	}))), "stream");
+	return Buffer.from(ipc).toString("base64");
+}
+var TypeParser = class {
+	input;
+	pos = 0;
+	constructor(input) {
+		this.input = input;
+	}
+	parseType() {
+		this.skipWs();
+		let name;
+		if (this.peek() === "`") name = this.consumeBacktickIdent();
+		else name = this.consumeIdent();
+		const upper = name.toUpperCase();
+		this.skipWs();
+		if (upper === "INTERVAL") return this.parseInterval();
+		if (this.peek() === "(") {
+			this.consume("(");
+			const args = this.parseNumberArgs();
+			this.consume(")");
+			this.skipWs();
+			return this.makeParameterized(upper, args);
+		}
+		if (this.peek() === "<") {
+			this.consume("<");
+			const result = this.makeGeneric(upper);
+			this.skipWs();
+			this.consume(">");
+			return result;
+		}
+		return this.makeScalar(upper);
+	}
+	expectEnd() {
+		this.skipWs();
+		if (this.pos < this.input.length) throw new Error(`Unexpected trailing input at position ${this.pos}: "${this.input.slice(this.pos)}"`);
+	}
+	makeScalar(upper) {
+		switch (upper) {
+			case "STRING":
+			case "VARIANT": return new Utf8();
+			case "VARCHAR":
+			case "CHAR": return new Utf8();
+			case "BINARY":
+			case "GEOGRAPHY":
+			case "GEOMETRY": return new Binary();
+			case "BOOLEAN":
+			case "BOOL": return new Bool();
+			case "TINYINT":
+			case "BYTE": return new Int8();
+			case "SMALLINT":
+			case "SHORT": return new Int16();
+			case "INT":
+			case "INTEGER": return new Int32();
+			case "BIGINT":
+			case "LONG": return new Int64();
+			case "FLOAT":
+			case "REAL": return new Float32();
+			case "DOUBLE": return new Float64();
+			case "DECIMAL":
+			case "NUMERIC":
+			case "DEC": return new Decimal(0, 10, 128);
+			case "DATE": return new DateDay();
+			case "TIMESTAMP":
+			case "TIMESTAMP_LTZ": return new TimestampMicrosecond("UTC");
+			case "TIMESTAMP_NTZ": return new TimestampMicrosecond();
+			case "VOID":
+			case "NULL": return new Null();
+			default: return new Utf8();
+		}
+	}
+	makeParameterized(upper, args) {
+		switch (upper) {
+			case "DECIMAL":
+			case "NUMERIC":
+			case "DEC": {
+				const precision = args[0] ?? 10;
+				return new Decimal(args[1] ?? 0, precision, 128);
+			}
+			case "VARCHAR":
+			case "CHAR": return new Utf8();
+			default: return new Utf8();
+		}
+	}
+	makeGeneric(upper) {
+		switch (upper) {
+			case "ARRAY": return new List(new Field("item", this.parseType(), true));
+			case "MAP": {
+				const keyType = this.parseType();
+				this.skipWs();
+				this.consume(",");
+				this.skipWs();
+				const valueType = this.parseType();
+				return new Map_(new Field("entries", new Struct([new Field("key", keyType, false), new Field("value", valueType, true)]), false), false);
+			}
+			case "STRUCT": return this.parseStructFields();
+			default:
+				this.skipBalancedAngles();
+				return new Utf8();
+		}
+	}
+	parseStructFields() {
+		const fields = [];
+		while (true) {
+			this.skipWs();
+			if (this.peek() === ">") break;
+			let name;
+			if (this.peek() === "`") name = this.consumeBacktickIdent();
+			else name = this.consumeIdent();
+			this.skipWs();
+			this.consume(":");
+			this.skipWs();
+			const type = this.parseType();
+			this.skipWs();
+			while (this.peekKeyword("NOT")) {
+				this.consumeIdent();
+				this.skipWs();
+				if (this.peekKeyword("NULL")) this.consumeIdent();
+				this.skipWs();
+			}
+			if (this.peekKeyword("COMMENT")) {
+				this.consumeIdent();
+				this.skipWs();
+				this.consumeStringLiteral();
+				this.skipWs();
+			}
+			fields.push(new Field(name, type, true));
+			this.skipWs();
+			if (this.peek() === ",") this.consume(",");
+			else break;
+		}
+		return new Struct(fields);
+	}
+	parseInterval() {
+		const seen = [];
+		while (this.pos < this.input.length) {
+			this.skipWs();
+			const c = this.peek();
+			if (c === "" || c === "," || c === ">" || c === ")") break;
+			const word = this.consumeIdent().toUpperCase();
+			seen.push(word);
+		}
+		return seen.some((w) => w === "YEAR" || w === "MONTH") ? new IntervalYearMonth() : new DurationMicrosecond();
+	}
+	parseNumberArgs() {
+		const args = [];
+		while (true) {
+			this.skipWs();
+			if (this.peek() === ")") break;
+			args.push(this.consumeNumber());
+			this.skipWs();
+			if (this.peek() === ",") this.consume(",");
+			else break;
+		}
+		return args;
+	}
+	peek() {
+		return this.input[this.pos] ?? "";
+	}
+	peekKeyword(word) {
+		if (this.input.slice(this.pos, this.pos + word.length).toUpperCase() !== word.toUpperCase()) return false;
+		const next = this.input[this.pos + word.length] ?? "";
+		return !/[A-Za-z0-9_]/.test(next);
+	}
+	consume(expected) {
+		if (this.peek() !== expected) throw new Error(`Expected "${expected}" at position ${this.pos}, got "${this.peek()}" in "${this.input}"`);
+		this.pos++;
+	}
+	skipWs() {
+		while (this.pos < this.input.length && /\s/.test(this.input[this.pos] ?? "")) this.pos++;
+	}
+	consumeIdent() {
+		const start = this.pos;
+		while (this.pos < this.input.length && /[A-Za-z0-9_]/.test(this.input[this.pos] ?? "")) this.pos++;
+		if (this.pos === start) throw new Error(`Expected identifier at position ${this.pos}, got "${this.peek()}" in "${this.input}"`);
+		return this.input.slice(start, this.pos);
+	}
+	consumeBacktickIdent() {
+		this.consume("`");
+		let value = "";
+		while (this.pos < this.input.length) {
+			if (this.input[this.pos] === "`") {
+				if (this.input[this.pos + 1] === "`") {
+					value += "`";
+					this.pos += 2;
+					continue;
+				}
+				break;
+			}
+			value += this.input[this.pos];
+			this.pos++;
+		}
+		this.consume("`");
+		return value;
+	}
+	consumeNumber() {
+		const start = this.pos;
+		while (this.pos < this.input.length && /[0-9]/.test(this.input[this.pos] ?? "")) this.pos++;
+		if (this.pos === start) throw new Error(`Expected number at position ${this.pos}, got "${this.peek()}" in "${this.input}"`);
+		return Number.parseInt(this.input.slice(start, this.pos), 10);
+	}
+	consumeStringLiteral() {
+		const quote = this.peek();
+		if (quote !== "'" && quote !== "\"") throw new Error(`Expected string literal at position ${this.pos}, got "${quote}" in "${this.input}"`);
+		this.pos++;
+		let value = "";
+		while (this.pos < this.input.length) {
+			const c = this.input[this.pos];
+			if (c === "\\") {
+				const next = this.input[this.pos + 1];
+				if (next !== void 0) {
+					value += next;
+					this.pos += 2;
+					continue;
+				}
+				this.pos++;
+				continue;
+			}
+			if (c === quote) {
+				this.pos++;
+				return value;
+			}
+			value += c;
+			this.pos++;
+		}
+		throw new Error(`Unterminated string literal in "${this.input}"`);
+	}
+	skipBalancedAngles() {
+		let depth = 1;
+		while (this.pos < this.input.length && depth > 0) {
+			const c = this.peek();
+			if (c === "<") depth++;
+			else if (c === ">") {
+				depth--;
+				if (depth === 0) return;
+			}
+			this.pos++;
+		}
+	}
+};
+
+//#endregion
+export { buildEmptyArrowIPCBase64 };
+//# sourceMappingURL=arrow-schema.js.map

package/dist/connectors/sql-warehouse/arrow-schema.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"arrow-schema.js","names":[],"sources":["../../../src/connectors/sql-warehouse/arrow-schema.ts"],"sourcesContent":["import {\n  Binary,\n  Bool,\n  type DataType,\n  DateDay,\n  Decimal,\n  DurationMicrosecond,\n  Field,\n  Float32,\n  Float64,\n  Int8,\n  Int16,\n  Int32,\n  Int64,\n  IntervalYearMonth,\n  List,\n  Map_,\n  Null,\n  Schema,\n  Struct,\n  Table,\n  TimestampMicrosecond,\n  tableToIPC,\n  Utf8,\n} from \"apache-arrow\";\n\n/**\n * Parse a Databricks SQL type text (the value returned by the Statement\n * Execution API in `ColumnInfo.type_text`) into an Apache Arrow DataType.\n *\n * Supports:\n *   - All scalar types (STRING, INT, BIGINT, DECIMAL, TIMESTAMP, etc.)\n *   - Parameterized scalars: DECIMAL(p,s), VARCHAR(n), CHAR(n)\n *   - Nested types: ARRAY<T>, MAP<K,V>, STRUCT<f1:T1, f2:T2 COMMENT '...', ...>\n *   - INTERVAL year-month and day-time variants\n *   - Backtick-quoted struct field names with embedded `` `` `` escapes\n *\n * Unknown or unparseable types fall back to Utf8 — empty-Table consumers\n * still see a column with the right name; only the inner type is degraded.\n */\nexport function parseDatabricksType(typeText: string): DataType {\n  const parser = new TypeParser(typeText);\n  const result = parser.parseType();\n  parser.expectEnd();\n  return result;\n}\n\n/**\n * Build an empty Arrow IPC stream (base64-encoded) matching the column schema\n * returned by the warehouse. Used so ARROW_STREAM responses with no rows still\n * deliver a real Arrow Table to the client, preserving the hook's typed\n * contract.\n */\nexport function buildEmptyArrowIPCBase64(\n  columns: Array<{\n    name?: string;\n    type_text?: string;\n    type_name?: string;\n  }>,\n): string {\n  const fields = columns.map((col, index) => {\n    const typeText = col.type_text ?? col.type_name ?? \"STRING\";\n    let dataType: DataType;\n    try {\n      dataType = parseDatabricksType(typeText);\n    } catch {\n      dataType = new Utf8();\n    }\n    const name = col.name && col.name.length > 0 ? col.name : `column_${index}`;\n    return new Field(name, dataType, true);\n  });\n  const schema = new Schema(fields);\n  const table = new Table(schema);\n  const ipc = tableToIPC(table, \"stream\");\n  return Buffer.from(ipc).toString(\"base64\");\n}\n\n// ============================================================================\n// Recursive-descent parser\n// ============================================================================\n\nclass TypeParser {\n  private readonly input: string;\n  private pos = 0;\n\n  constructor(input: string) {\n    this.input = input;\n  }\n\n  parseType(): DataType {\n    this.skipWs();\n\n    let name: string;\n    if (this.peek() === \"`\") {\n      name = this.consumeBacktickIdent();\n    } else {\n      name = this.consumeIdent();\n    }\n    const upper = name.toUpperCase();\n\n    this.skipWs();\n\n    if (upper === \"INTERVAL\") {\n      return this.parseInterval();\n    }\n\n    if (this.peek() === \"(\") {\n      this.consume(\"(\");\n      const args = this.parseNumberArgs();\n      this.consume(\")\");\n      this.skipWs();\n      return this.makeParameterized(upper, args);\n    }\n\n    if (this.peek() === \"<\") {\n      this.consume(\"<\");\n      const result = this.makeGeneric(upper);\n      this.skipWs();\n      this.consume(\">\");\n      return result;\n    }\n\n    return this.makeScalar(upper);\n  }\n\n  expectEnd(): void {\n    this.skipWs();\n    if (this.pos < this.input.length) {\n      throw new Error(\n        `Unexpected trailing input at position ${this.pos}: \"${this.input.slice(this.pos)}\"`,\n      );\n    }\n  }\n\n  // ─── Type constructors ───────────────────────────────────\n\n  private makeScalar(upper: string): DataType {\n    switch (upper) {\n      case \"STRING\":\n      case \"VARIANT\":\n        return new Utf8();\n      case \"VARCHAR\":\n      case \"CHAR\":\n        return new Utf8();\n      case \"BINARY\":\n      case \"GEOGRAPHY\":\n      case \"GEOMETRY\":\n        return new Binary();\n      case \"BOOLEAN\":\n      case \"BOOL\":\n        return new Bool();\n      case \"TINYINT\":\n      case \"BYTE\":\n        return new Int8();\n      case \"SMALLINT\":\n      case \"SHORT\":\n        return new Int16();\n      case \"INT\":\n      case \"INTEGER\":\n        return new Int32();\n      case \"BIGINT\":\n      case \"LONG\":\n        return new Int64();\n      case \"FLOAT\":\n      case \"REAL\":\n        return new Float32();\n      case \"DOUBLE\":\n        return new Float64();\n      case \"DECIMAL\":\n      case \"NUMERIC\":\n      case \"DEC\":\n        return new Decimal(0, 10, 128);\n      case \"DATE\":\n        return new DateDay();\n      case \"TIMESTAMP\":\n      case \"TIMESTAMP_LTZ\":\n        return new TimestampMicrosecond(\"UTC\");\n      case \"TIMESTAMP_NTZ\":\n        return new TimestampMicrosecond();\n      case \"VOID\":\n      case \"NULL\":\n        return new Null();\n      default:\n        return new Utf8();\n    }\n  }\n\n  private makeParameterized(upper: string, args: number[]): DataType {\n    switch (upper) {\n      case \"DECIMAL\":\n      case \"NUMERIC\":\n      case \"DEC\": {\n        const precision = args[0] ?? 10;\n        const scale = args[1] ?? 0;\n        // Arrow JS Decimal constructor signature is (scale, precision, bitWidth).\n        return new Decimal(scale, precision, 128);\n      }\n      case \"VARCHAR\":\n      case \"CHAR\":\n        return new Utf8();\n      default:\n        return new Utf8();\n    }\n  }\n\n  private makeGeneric(upper: string): DataType {\n    switch (upper) {\n      case \"ARRAY\": {\n        const inner = this.parseType();\n        return new List(new Field(\"item\", inner, true));\n      }\n      case \"MAP\": {\n        const keyType = this.parseType();\n        this.skipWs();\n        this.consume(\",\");\n        this.skipWs();\n        const valueType = this.parseType();\n        const entriesStruct = new Struct([\n          new Field(\"key\", keyType, false),\n          new Field(\"value\", valueType, true),\n        ]);\n        return new Map_(new Field(\"entries\", entriesStruct, false), false);\n      }\n      case \"STRUCT\":\n        return this.parseStructFields();\n      default:\n        // Unknown generic — skip to matching '>' and fall back.\n        this.skipBalancedAngles();\n        return new Utf8();\n    }\n  }\n\n  private parseStructFields(): DataType {\n    const fields: Field[] = [];\n    while (true) {\n      this.skipWs();\n      if (this.peek() === \">\") break;\n\n      let name: string;\n      if (this.peek() === \"`\") {\n        name = this.consumeBacktickIdent();\n      } else {\n        name = this.consumeIdent();\n      }\n\n      this.skipWs();\n      this.consume(\":\");\n      this.skipWs();\n\n      const type = this.parseType();\n\n      // Optional `NOT NULL` and `COMMENT '...'`. Both are accepted by\n      // Databricks DDL and may appear in `type_text`.\n      this.skipWs();\n      while (this.peekKeyword(\"NOT\")) {\n        this.consumeIdent();\n        this.skipWs();\n        if (this.peekKeyword(\"NULL\")) {\n          this.consumeIdent();\n        }\n        this.skipWs();\n      }\n      if (this.peekKeyword(\"COMMENT\")) {\n        this.consumeIdent();\n        this.skipWs();\n        this.consumeStringLiteral();\n        this.skipWs();\n      }\n\n      fields.push(new Field(name, type, true));\n\n      this.skipWs();\n      if (this.peek() === \",\") {\n        this.consume(\",\");\n      } else {\n        break;\n      }\n    }\n    return new Struct(fields);\n  }\n\n  private parseInterval(): DataType {\n    // Grammar: INTERVAL <unit> [TO <unit>]\n    // YEAR / MONTH variants -> IntervalYearMonth\n    // DAY / HOUR / MINUTE / SECOND variants -> Duration(microsecond)\n    const seen: string[] = [];\n    while (this.pos < this.input.length) {\n      this.skipWs();\n      const c = this.peek();\n      if (c === \"\" || c === \",\" || c === \">\" || c === \")\") break;\n      const word = this.consumeIdent().toUpperCase();\n      seen.push(word);\n    }\n    const isYearMonth = seen.some((w) => w === \"YEAR\" || w === \"MONTH\");\n    return isYearMonth ? new IntervalYearMonth() : new DurationMicrosecond();\n  }\n\n  private parseNumberArgs(): number[] {\n    const args: number[] = [];\n    while (true) {\n      this.skipWs();\n      if (this.peek() === \")\") break;\n      args.push(this.consumeNumber());\n      this.skipWs();\n      if (this.peek() === \",\") {\n        this.consume(\",\");\n      } else {\n        break;\n      }\n    }\n    return args;\n  }\n\n  // ─── Token utilities ─────────────────────────────────────\n\n  private peek(): string {\n    return this.input[this.pos] ?? \"\";\n  }\n\n  private peekKeyword(word: string): boolean {\n    const slice = this.input.slice(this.pos, this.pos + word.length);\n    if (slice.toUpperCase() !== word.toUpperCase()) return false;\n    // Must be followed by a non-identifier character (boundary check).\n    const next = this.input[this.pos + word.length] ?? \"\";\n    return !/[A-Za-z0-9_]/.test(next);\n  }\n\n  private consume(expected: string): void {\n    if (this.peek() !== expected) {\n      throw new Error(\n        `Expected \"${expected}\" at position ${this.pos}, got \"${this.peek()}\" in \"${this.input}\"`,\n      );\n    }\n    this.pos++;\n  }\n\n  private skipWs(): void {\n    while (\n      this.pos < this.input.length &&\n      /\\s/.test(this.input[this.pos] ?? \"\")\n    ) {\n      this.pos++;\n    }\n  }\n\n  private consumeIdent(): string {\n    const start = this.pos;\n    while (\n      this.pos < this.input.length &&\n      /[A-Za-z0-9_]/.test(this.input[this.pos] ?? \"\")\n    ) {\n      this.pos++;\n    }\n    if (this.pos === start) {\n      throw new Error(\n        `Expected identifier at position ${this.pos}, got \"${this.peek()}\" in \"${this.input}\"`,\n      );\n    }\n    return this.input.slice(start, this.pos);\n  }\n\n  private consumeBacktickIdent(): string {\n    this.consume(\"`\");\n    let value = \"\";\n    while (this.pos < this.input.length) {\n      if (this.input[this.pos] === \"`\") {\n        if (this.input[this.pos + 1] === \"`\") {\n          value += \"`\";\n          this.pos += 2;\n          continue;\n        }\n        break;\n      }\n      value += this.input[this.pos];\n      this.pos++;\n    }\n    this.consume(\"`\");\n    return value;\n  }\n\n  private consumeNumber(): number {\n    const start = this.pos;\n    while (\n      this.pos < this.input.length &&\n      /[0-9]/.test(this.input[this.pos] ?? \"\")\n    ) {\n      this.pos++;\n    }\n    if (this.pos === start) {\n      throw new Error(\n        `Expected number at position ${this.pos}, got \"${this.peek()}\" in \"${this.input}\"`,\n      );\n    }\n    return Number.parseInt(this.input.slice(start, this.pos), 10);\n  }\n\n  private consumeStringLiteral(): string {\n    const quote = this.peek();\n    if (quote !== \"'\" && quote !== '\"') {\n      throw new Error(\n        `Expected string literal at position ${this.pos}, got \"${quote}\" in \"${this.input}\"`,\n      );\n    }\n    this.pos++;\n    let value = \"\";\n    while (this.pos < this.input.length) {\n      const c = this.input[this.pos];\n      if (c === \"\\\\\") {\n        // Escape sequence: keep the next char verbatim.\n        const next = this.input[this.pos + 1];\n        if (next !== undefined) {\n          value += next;\n          this.pos += 2;\n          continue;\n        }\n        this.pos++;\n        continue;\n      }\n      if (c === quote) {\n        this.pos++;\n        return value;\n      }\n      value += c;\n      this.pos++;\n    }\n    throw new Error(`Unterminated string literal in \"${this.input}\"`);\n  }\n\n  private skipBalancedAngles(): void {\n    let depth = 1;\n    while (this.pos < this.input.length && depth > 0) {\n      const c = this.peek();\n      if (c === \"<\") depth++;\n      else if (c === \">\") {\n        depth--;\n        if (depth === 0) return;\n      }\n      this.pos++;\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;AAwCA,SAAgB,oBAAoB,UAA4B;CAC9D,MAAM,SAAS,IAAI,WAAW,SAAS;CACvC,MAAM,SAAS,OAAO,WAAW;AACjC,QAAO,WAAW;AAClB,QAAO;;;;;;;;AAST,SAAgB,yBACd,SAKQ;CAcR,MAAM,MAAM,WADE,IAAI,MADH,IAAI,OAXJ,QAAQ,KAAK,KAAK,UAAU;EACzC,MAAM,WAAW,IAAI,aAAa,IAAI,aAAa;EACnD,IAAI;AACJ,MAAI;AACF,cAAW,oBAAoB,SAAS;UAClC;AACN,cAAW,IAAI,MAAM;;AAGvB,SAAO,IAAI,MADE,IAAI,QAAQ,IAAI,KAAK,SAAS,IAAI,IAAI,OAAO,UAAU,SAC7C,UAAU,KAAK;GACtC,CAC+B,CACF,EACD,SAAS;AACvC,QAAO,OAAO,KAAK,IAAI,CAAC,SAAS,SAAS;;AAO5C,IAAM,aAAN,MAAiB;CACf,AAAiB;CACjB,AAAQ,MAAM;CAEd,YAAY,OAAe;AACzB,OAAK,QAAQ;;CAGf,YAAsB;AACpB,OAAK,QAAQ;EAEb,IAAI;AACJ,MAAI,KAAK,MAAM,KAAK,IAClB,QAAO,KAAK,sBAAsB;MAElC,QAAO,KAAK,cAAc;EAE5B,MAAM,QAAQ,KAAK,aAAa;AAEhC,OAAK,QAAQ;AAEb,MAAI,UAAU,WACZ,QAAO,KAAK,eAAe;AAG7B,MAAI,KAAK,MAAM,KAAK,KAAK;AACvB,QAAK,QAAQ,IAAI;GACjB,MAAM,OAAO,KAAK,iBAAiB;AACnC,QAAK,QAAQ,IAAI;AACjB,QAAK,QAAQ;AACb,UAAO,KAAK,kBAAkB,OAAO,KAAK;;AAG5C,MAAI,KAAK,MAAM,KAAK,KAAK;AACvB,QAAK,QAAQ,IAAI;GACjB,MAAM,SAAS,KAAK,YAAY,MAAM;AACtC,QAAK,QAAQ;AACb,QAAK,QAAQ,IAAI;AACjB,UAAO;;AAGT,SAAO,KAAK,WAAW,MAAM;;CAG/B,YAAkB;AAChB,OAAK,QAAQ;AACb,MAAI,KAAK,MAAM,KAAK,MAAM,OACxB,OAAM,IAAI,MACR,yCAAyC,KAAK,IAAI,KAAK,KAAK,MAAM,MAAM,KAAK,IAAI,CAAC,GACnF;;CAML,AAAQ,WAAW,OAAyB;AAC1C,UAAQ,OAAR;GACE,KAAK;GACL,KAAK,UACH,QAAO,IAAI,MAAM;GACnB,KAAK;GACL,KAAK,OACH,QAAO,IAAI,MAAM;GACnB,KAAK;GACL,KAAK;GACL,KAAK,WACH,QAAO,IAAI,QAAQ;GACrB,KAAK;GACL,KAAK,OACH,QAAO,IAAI,MAAM;GACnB,KAAK;GACL,KAAK,OACH,QAAO,IAAI,MAAM;GACnB,KAAK;GACL,KAAK,QACH,QAAO,IAAI,OAAO;GACpB,KAAK;GACL,KAAK,UACH,QAAO,IAAI,OAAO;GACpB,KAAK;GACL,KAAK,OACH,QAAO,IAAI,OAAO;GACpB,KAAK;GACL,KAAK,OACH,QAAO,IAAI,SAAS;GACtB,KAAK,SACH,QAAO,IAAI,SAAS;GACtB,KAAK;GACL,KAAK;GACL,KAAK,MACH,QAAO,IAAI,QAAQ,GAAG,IAAI,IAAI;GAChC,KAAK,OACH,QAAO,IAAI,SAAS;GACtB,KAAK;GACL,KAAK,gBACH,QAAO,IAAI,qBAAqB,MAAM;GACxC,KAAK,gBACH,QAAO,IAAI,sBAAsB;GACnC,KAAK;GACL,KAAK,OACH,QAAO,IAAI,MAAM;GACnB,QACE,QAAO,IAAI,MAAM;;;CAIvB,AAAQ,kBAAkB,OAAe,MAA0B;AACjE,UAAQ,OAAR;GACE,KAAK;GACL,KAAK;GACL,KAAK,OAAO;IACV,MAAM,YAAY,KAAK,MAAM;AAG7B,WAAO,IAAI,QAFG,KAAK,MAAM,GAEC,WAAW,IAAI;;GAE3C,KAAK;GACL,KAAK,OACH,QAAO,IAAI,MAAM;GACnB,QACE,QAAO,IAAI,MAAM;;;CAIvB,AAAQ,YAAY,OAAyB;AAC3C,UAAQ,OAAR;GACE,KAAK,QAEH,QAAO,IAAI,KAAK,IAAI,MAAM,QADZ,KAAK,WAAW,EACW,KAAK,CAAC;GAEjD,KAAK,OAAO;IACV,MAAM,UAAU,KAAK,WAAW;AAChC,SAAK,QAAQ;AACb,SAAK,QAAQ,IAAI;AACjB,SAAK,QAAQ;IACb,MAAM,YAAY,KAAK,WAAW;AAKlC,WAAO,IAAI,KAAK,IAAI,MAAM,WAJJ,IAAI,OAAO,CAC/B,IAAI,MAAM,OAAO,SAAS,MAAM,EAChC,IAAI,MAAM,SAAS,WAAW,KAAK,CACpC,CAAC,EACkD,MAAM,EAAE,MAAM;;GAEpE,KAAK,SACH,QAAO,KAAK,mBAAmB;GACjC;AAEE,SAAK,oBAAoB;AACzB,WAAO,IAAI,MAAM;;;CAIvB,AAAQ,oBAA8B;EACpC,MAAM,SAAkB,EAAE;AAC1B,SAAO,MAAM;AACX,QAAK,QAAQ;AACb,OAAI,KAAK,MAAM,KAAK,IAAK;GAEzB,IAAI;AACJ,OAAI,KAAK,MAAM,KAAK,IAClB,QAAO,KAAK,sBAAsB;OAElC,QAAO,KAAK,cAAc;AAG5B,QAAK,QAAQ;AACb,QAAK,QAAQ,IAAI;AACjB,QAAK,QAAQ;GAEb,MAAM,OAAO,KAAK,WAAW;AAI7B,QAAK,QAAQ;AACb,UAAO,KAAK,YAAY,MAAM,EAAE;AAC9B,SAAK,cAAc;AACnB,SAAK,QAAQ;AACb,QAAI,KAAK,YAAY,OAAO,CAC1B,MAAK,cAAc;AAErB,SAAK,QAAQ;;AAEf,OAAI,KAAK,YAAY,UAAU,EAAE;AAC/B,SAAK,cAAc;AACnB,SAAK,QAAQ;AACb,SAAK,sBAAsB;AAC3B,SAAK,QAAQ;;AAGf,UAAO,KAAK,IAAI,MAAM,MAAM,MAAM,KAAK,CAAC;AAExC,QAAK,QAAQ;AACb,OAAI,KAAK,MAAM,KAAK,IAClB,MAAK,QAAQ,IAAI;OAEjB;;AAGJ,SAAO,IAAI,OAAO,OAAO;;CAG3B,AAAQ,gBAA0B;EAIhC,MAAM,OAAiB,EAAE;AACzB,SAAO,KAAK,MAAM,KAAK,MAAM,QAAQ;AACnC,QAAK,QAAQ;GACb,MAAM,IAAI,KAAK,MAAM;AACrB,OAAI,MAAM,MAAM,MAAM,OAAO,MAAM,OAAO,MAAM,IAAK;GACrD,MAAM,OAAO,KAAK,cAAc,CAAC,aAAa;AAC9C,QAAK,KAAK,KAAK;;AAGjB,SADoB,KAAK,MAAM,MAAM,MAAM,UAAU,MAAM,QAAQ,GAC9C,IAAI,mBAAmB,GAAG,IAAI,qBAAqB;;CAG1E,AAAQ,kBAA4B;EAClC,MAAM,OAAiB,EAAE;AACzB,SAAO,MAAM;AACX,QAAK,QAAQ;AACb,OAAI,KAAK,MAAM,KAAK,IAAK;AACzB,QAAK,KAAK,KAAK,eAAe,CAAC;AAC/B,QAAK,QAAQ;AACb,OAAI,KAAK,MAAM,KAAK,IAClB,MAAK,QAAQ,IAAI;OAEjB;;AAGJ,SAAO;;CAKT,AAAQ,OAAe;AACrB,SAAO,KAAK,MAAM,KAAK,QAAQ;;CAGjC,AAAQ,YAAY,MAAuB;AAEzC,MADc,KAAK,MAAM,MAAM,KAAK,KAAK,KAAK,MAAM,KAAK,OAAO,CACtD,aAAa,KAAK,KAAK,aAAa,CAAE,QAAO;EAEvD,MAAM,OAAO,KAAK,MAAM,KAAK,MAAM,KAAK,WAAW;AACnD,SAAO,CAAC,eAAe,KAAK,KAAK;;CAGnC,AAAQ,QAAQ,UAAwB;AACtC,MAAI,KAAK,MAAM,KAAK,SAClB,OAAM,IAAI,MACR,aAAa,SAAS,gBAAgB,KAAK,IAAI,SAAS,KAAK,MAAM,CAAC,QAAQ,KAAK,MAAM,GACxF;AAEH,OAAK;;CAGP,AAAQ,SAAe;AACrB,SACE,KAAK,MAAM,KAAK,MAAM,UACtB,KAAK,KAAK,KAAK,MAAM,KAAK,QAAQ,GAAG,CAErC,MAAK;;CAIT,AAAQ,eAAuB;EAC7B,MAAM,QAAQ,KAAK;AACnB,SACE,KAAK,MAAM,KAAK,MAAM,UACtB,eAAe,KAAK,KAAK,MAAM,KAAK,QAAQ,GAAG,CAE/C,MAAK;AAEP,MAAI,KAAK,QAAQ,MACf,OAAM,IAAI,MACR,mCAAmC,KAAK,IAAI,SAAS,KAAK,MAAM,CAAC,QAAQ,KAAK,MAAM,GACrF;AAEH,SAAO,KAAK,MAAM,MAAM,OAAO,KAAK,IAAI;;CAG1C,AAAQ,uBAA+B;AACrC,OAAK,QAAQ,IAAI;EACjB,IAAI,QAAQ;AACZ,SAAO,KAAK,MAAM,KAAK,MAAM,QAAQ;AACnC,OAAI,KAAK,MAAM,KAAK,SAAS,KAAK;AAChC,QAAI,KAAK,MAAM,KAAK,MAAM,OAAO,KAAK;AACpC,cAAS;AACT,UAAK,OAAO;AACZ;;AAEF;;AAEF,YAAS,KAAK,MAAM,KAAK;AACzB,QAAK;;AAEP,OAAK,QAAQ,IAAI;AACjB,SAAO;;CAGT,AAAQ,gBAAwB;EAC9B,MAAM,QAAQ,KAAK;AACnB,SACE,KAAK,MAAM,KAAK,MAAM,UACtB,QAAQ,KAAK,KAAK,MAAM,KAAK,QAAQ,GAAG,CAExC,MAAK;AAEP,MAAI,KAAK,QAAQ,MACf,OAAM,IAAI,MACR,+BAA+B,KAAK,IAAI,SAAS,KAAK,MAAM,CAAC,QAAQ,KAAK,MAAM,GACjF;AAEH,SAAO,OAAO,SAAS,KAAK,MAAM,MAAM,OAAO,KAAK,IAAI,EAAE,GAAG;;CAG/D,AAAQ,uBAA+B;EACrC,MAAM,QAAQ,KAAK,MAAM;AACzB,MAAI,UAAU,OAAO,UAAU,KAC7B,OAAM,IAAI,MACR,uCAAuC,KAAK,IAAI,SAAS,MAAM,QAAQ,KAAK,MAAM,GACnF;AAEH,OAAK;EACL,IAAI,QAAQ;AACZ,SAAO,KAAK,MAAM,KAAK,MAAM,QAAQ;GACnC,MAAM,IAAI,KAAK,MAAM,KAAK;AAC1B,OAAI,MAAM,MAAM;IAEd,MAAM,OAAO,KAAK,MAAM,KAAK,MAAM;AACnC,QAAI,SAAS,QAAW;AACtB,cAAS;AACT,UAAK,OAAO;AACZ;;AAEF,SAAK;AACL;;AAEF,OAAI,MAAM,OAAO;AACf,SAAK;AACL,WAAO;;AAET,YAAS;AACT,QAAK;;AAEP,QAAM,IAAI,MAAM,mCAAmC,KAAK,MAAM,GAAG;;CAGnE,AAAQ,qBAA2B;EACjC,IAAI,QAAQ;AACZ,SAAO,KAAK,MAAM,KAAK,MAAM,UAAU,QAAQ,GAAG;GAChD,MAAM,IAAI,KAAK,MAAM;AACrB,OAAI,MAAM,IAAK;YACN,MAAM,KAAK;AAClB;AACA,QAAI,UAAU,EAAG;;AAEnB,QAAK"}

package/dist/connectors/sql-warehouse/client.js

@@ -8,6 +8,7 @@ import "../../errors/index.js";
 import { TelemetryManager } from "../../telemetry/telemetry-manager.js";
 import { SpanKind, SpanStatusCode } from "../../telemetry/index.js";
 import { ArrowStreamProcessor } from "../../stream/arrow-stream-processor.js";
+import { buildEmptyArrowIPCBase64 } from "./arrow-schema.js";
 import { executeStatementDefaults } from "./defaults.js";
 import { WarehousePollBackoff } from "./warehouse-poll-backoff.js";
 import { WarehouseStatusEmitter } from "./warehouse-status-emitter.js";
@@ -16,6 +17,35 @@ import { Context } from "@databricks/sdk-experimental";
 //#region src/connectors/sql-warehouse/client.ts
 const logger = createLogger("connectors:sql-warehouse");
 /**
+* Real column names from a statement's result manifest (positional
+* `column_N` fallback for any blank ones). Databricks encodes ARROW_STREAM
+* schemas positionally (`col_0`, …); these names let consumers relabel an
+* Arrow result to match the JSON path. Returns `undefined` when the manifest
+* carries no columns.
+*/
+function arrowColumnNames(response) {
+	const cols = response.manifest?.schema?.columns;
+	if (!cols || cols.length === 0) return void 0;
+	return cols.map((c, i) => c.name && c.name.length > 0 ? c.name : `column_${i}`);
+}
+/**
+* Maximum size for inline Arrow IPC attachments (25 MiB decoded — the
+* Databricks Statement Execution API hard cap on INLINE responses).
+*
+* The analytics route streams the decoded attachment straight back on the
+* query response body; this cap bounds the single in-memory copy. Larger
+* results fall through to `disposition: "EXTERNAL_LINKS"`, which streams
+* chunk-by-chunk and is not bound by this limit.
+*/
+const MAX_INLINE_ATTACHMENT_BYTES = 25 * 1024 * 1024;
+/**
+* Safety cap on how many additional EXTERNAL_LINKS chunks
+* {@link SQLWarehouseConnector._resolveAllExternalLinks} will follow when the
+* manifest omits `total_chunk_count`. High enough to cover any real result;
+* only bounds a misbehaving warehouse with a cyclic `next_chunk_index`.
+*/
+const MAX_EXTERNAL_CHUNK_FOLLOWS = 1e4;
+/**
 * Default ceiling for how long {@link SQLWarehouseConnector.ensureWarehouseRunning}
 * will wait for a warehouse to reach the RUNNING state before giving up.
 *
@@ -66,7 +96,6 @@ var SQLWarehouseConnector = class {
 	get arrowProcessor() {
 		if (!this._arrowProcessor) this._arrowProcessor = new ArrowStreamProcessor({
 			timeout: this.config.timeout || executeStatementDefaults.timeout,
-			maxConcurrentDownloads: ArrowStreamProcessor.DEFAULT_MAX_CONCURRENT_DOWNLOADS,
 			retries: ArrowStreamProcessor.DEFAULT_RETRIES
 		});
 		return this._arrowProcessor;
@@ -135,9 +164,9 @@ var SQLWarehouseConnector = class {
 						result = await this._pollForStatementResult(workspaceClient, statementId, this.config.timeout, signal);
 						break;
 					case "SUCCEEDED":
-						result = this._transformDataArray(response);
+						result = await this._transformDataArray(response, workspaceClient, signal);
 						break;
-					case "FAILED": throw ExecutionError.statementFailed(status.error?.message);
+					case "FAILED": throw ExecutionError.statementFailed(status.error?.message, status.error?.error_code);
 					case "CANCELED": throw ExecutionError.canceled();
 					case "CLOSED": throw ExecutionError.resultsClosed();
 					default: throw ExecutionError.unknownState(String(status?.state ?? "unknown"));
@@ -163,9 +192,7 @@ var SQLWarehouseConnector = class {
 					});
 					logger.error("Statement execution failed: %s", error instanceof Error ? error.message : String(error));
 				}
-				if (error instanceof Error && error.name === "AbortError") throw error;
-				if (error instanceof AppKitError) throw error;
-				throw ExecutionError.statementFailed(error instanceof Error ? error.message : String(error));
+				this._rethrowStatementError(error);
 			} finally {
 				if (abortHandler && signal) signal.removeEventListener("abort", abortHandler);
 				const duration = Date.now() - startTime;
@@ -462,8 +489,8 @@ var SQLWarehouseConnector = class {
 								"poll.duration_ms": elapsedTime
 							});
 							span.setStatus({ code: SpanStatusCode.OK });
-							return this._transformDataArray(response);
-						case "FAILED": throw ExecutionError.statementFailed(status.error?.message);
+							return this._transformDataArray(response, workspaceClient, signal);
+						case "FAILED": throw ExecutionError.statementFailed(status.error?.message, status.error?.error_code);
 						case "CANCELED": throw ExecutionError.canceled();
 						case "CLOSED": throw ExecutionError.resultsClosed();
 						default: throw ExecutionError.unknownState(String(status?.state ?? "unknown"));
@@ -477,9 +504,7 @@ var SQLWarehouseConnector = class {
 					code: SpanStatusCode.ERROR,
 					message: error instanceof Error ? error.message : String(error)
 				});
-				if (error instanceof Error && error.name === "AbortError") throw error;
-				if (error instanceof AppKitError) throw error;
-				throw ExecutionError.statementFailed(error instanceof Error ? error.message : String(error));
+				this._rethrowStatementError(error);
 			} finally {
 				span.end();
 			}
@@ -488,8 +513,22 @@ var SQLWarehouseConnector = class {
 			includePrefix: true
 		});
 	}
-	_transformDataArray(response) {
-		if (response.manifest?.format === "ARROW_STREAM") return this.updateWithArrowStatus(response);
+	async _transformDataArray(response, workspaceClient, signal) {
+		if (response.manifest?.format === "ARROW_STREAM") {
+			const result = response.result;
+			if (result?.attachment) return this._validateArrowAttachment(response, result.attachment);
+			if (result?.external_links && result.external_links.length > 0) return this.updateWithArrowStatus(response, workspaceClient, signal);
+			if ((!result?.data_array || Array.isArray(result.data_array) && result.data_array.length === 0) && response.manifest?.schema?.columns) {
+				const synthesized = buildEmptyArrowIPCBase64(response.manifest.schema.columns);
+				return {
+					...response,
+					result: {
+						...result ?? {},
+						attachment: synthesized
+					}
+				};
+			}
+		}
 		if (!response.result?.data_array || !response.manifest?.schema?.columns) return response;
 		const columns = response.manifest.schema.columns;
 		const transformedData = response.result.data_array.map((row) => {
@@ -515,59 +554,126 @@ var SQLWarehouseConnector = class {
 			}
 		};
 	}
-	updateWithArrowStatus(response) {
+	/**
+	* Validate a base64 Arrow IPC attachment (INLINE ARROW_STREAM) and attach
+	* the real column names from the result manifest.
+	*
+	* Databricks warehouses encode the Arrow schema positionally (`col_0`, …);
+	* the real, aliased names live only in `manifest.schema.columns`. Rather
+	* than decode/re-encode the payload server-side, we carry the names on the
+	* result (`columnNames`) so the route can hand them to the client in a
+	* response header and the client relabels the decoded Table — the one
+	* mechanism used for both INLINE and EXTERNAL_LINKS.
+	*/
+	_validateArrowAttachment(response, attachment) {
+		const stripped = attachment.replace(/\s+/g, "");
+		const padding = stripped.endsWith("==") ? 2 : stripped.endsWith("=") ? 1 : 0;
+		const decodedSize = Math.floor(stripped.length * 3 / 4) - padding;
+		if (decodedSize > MAX_INLINE_ATTACHMENT_BYTES) throw ExecutionError.statementFailed(`Inline Arrow attachment exceeds maximum size (${decodedSize} > ${MAX_INLINE_ATTACHMENT_BYTES} bytes)`);
+		const columnNames = arrowColumnNames(response);
+		if (columnNames) return {
+			...response,
+			result: {
+				...response.result,
+				statement_id: response.statement_id,
+				columnNames
+			}
+		};
+		return response;
+	}
+	async updateWithArrowStatus(response, workspaceClient, signal) {
+		const statementId = response.statement_id;
 		return { result: {
-			statement_id: response.statement_id,
+			statement_id: statementId,
 			status: {
 				state: response.status?.state,
 				error: response.status?.error
-			}
+			},
+			columnNames: arrowColumnNames(response),
+			external_links: await this._resolveAllExternalLinks(workspaceClient, statementId, response, signal),
+			refreshChunkLink: this._makeChunkLinkRefresher(workspaceClient, statementId)
 		} };
 	}
-	async getArrowData(workspaceClient, jobId, signal) {
-		const startTime = Date.now();
-		return this.telemetry.startActiveSpan("arrow.getData", {
-			kind: SpanKind.CLIENT,
-			attributes: {
-				"db.system": "databricks",
-				"arrow.job_id": jobId
-			}
-		}, async (span) => {
-			try {
-				const response = await workspaceClient.statementExecution.getStatement({ statement_id: jobId }, this._createContext(signal));
-				const chunks = response.result?.external_links;
-				const schema = response.manifest?.schema;
-				if (!chunks || !schema) throw ExecutionError.missingData("chunks or schema");
-				span.setAttribute("arrow.chunk_count", chunks.length);
-				const result = await this.arrowProcessor.processChunks(chunks, schema, signal);
-				span.setAttribute("arrow.data_size_bytes", result.data.length);
-				span.setStatus({ code: SpanStatusCode.OK });
-				const duration = Date.now() - startTime;
-				this.telemetryMetrics.queryDuration.record(duration, {
-					operation: "arrow.getData",
-					status: "success"
-				});
-				logger.event()?.setContext("sql-warehouse", {
-					arrow_data_size_bytes: result.data.length,
-					arrow_job_id: jobId
-				});
-				return result;
-			} catch (error) {
-				span.setStatus({
-					code: SpanStatusCode.ERROR,
-					message: error instanceof Error ? error.message : "Unknown error"
-				});
-				span.recordException(error);
-				const duration = Date.now() - startTime;
-				this.telemetryMetrics.queryDuration.record(duration, {
-					operation: "arrow.getData",
-					status: "error"
-				});
-				logger.error("Failed Arrow job: %s %O", jobId, error);
-				if (error instanceof AppKitError) throw error;
-				throw ExecutionError.statementFailed(error instanceof Error ? error.message : String(error));
-			}
-		});
+	/**
+	* Resolve pre-signed links for EVERY chunk of an EXTERNAL_LINKS result.
+	*
+	* The execute/getStatement response carries only the first chunk's links
+	* (each link, except the last, exposes `next_chunk_index`); the remaining
+	* chunks are fetched with `getStatementResultChunkN`. Runs in the caller's
+	* identity context (user creds for `.obo.sql`), so there is no cross-identity
+	* fetch. Only the tiny link metadata is resolved eagerly — the bytes still
+	* stream one chunk at a time downstream. Without this a multi-chunk result
+	* would be silently truncated to its first chunk.
+	*/
+	async _resolveAllExternalLinks(workspaceClient, statementId, response, signal) {
+		const first = response.result?.external_links;
+		if (!first || first.length === 0) return first;
+		const links = [...first];
+		const maxFetches = response.manifest?.total_chunk_count ?? MAX_EXTERNAL_CHUNK_FOLLOWS;
+		let next = this._nextChunkIndex(first);
+		for (let fetches = 0; next != null && fetches < maxFetches; fetches++) {
+			if (signal?.aborted) throw ExecutionError.canceled();
+			const chunkLinks = (await workspaceClient.statementExecution.getStatementResultChunkN({
+				statement_id: statementId,
+				chunk_index: next
+			}, this._createContext(signal))).external_links ?? [];
+			if (chunkLinks.length === 0) break;
+			links.push(...chunkLinks);
+			next = this._nextChunkIndex(chunkLinks);
+		}
+		return links;
+	}
+	/** The `next_chunk_index` advertised by a chunk's links, if any. */
+	_nextChunkIndex(links) {
+		for (const link of links) if (link.next_chunk_index != null) return link.next_chunk_index;
+	}
+	/**
+	* A closure that re-mints a single chunk's pre-signed link via
+	* `getStatementResultChunkN`, bound to the caller's workspace client +
+	* statement id. Created here (in the caller's identity context) so the
+	* streamer — which runs outside that context — can refresh an expired link
+	* for `.obo.sql` statements without a cross-identity `getStatement`.
+	*/
+	_makeChunkLinkRefresher(workspaceClient, statementId) {
+		return async (chunkIndex, signal) => {
+			return (await workspaceClient.statementExecution.getStatementResultChunkN({
+				statement_id: statementId,
+				chunk_index: chunkIndex
+			}, this._createContext(signal))).external_links?.find((l) => l.chunk_index === chunkIndex);
+		};
+	}
+	/**
+	* Stream already-resolved EXTERNAL_LINKS chunks as raw Arrow IPC bytes, one
+	* chunk in memory at a time. Takes the `external_links` the caller already
+	* has from `executeStatement` (see {@link updateWithArrowStatus}), so there
+	* is no extra `getStatement` round-trip and no execution-context mismatch —
+	* the pre-signed URLs need no auth to download.
+	*/
+	streamExternalLinks(chunks, signal, refresh) {
+		return this.arrowProcessor.streamChunks(chunks, signal, refresh);
+	}
+	/**
+	* Fetch just the real column names for a completed statement from its result
+	* manifest — no result data. Backs the `/columns/:statementId` fallback the
+	* client uses when a very wide schema's names exceed the response-header
+	* size limit. Stateless: re-derives from the warehouse, no server cache.
+	*/
+	async getColumnNames(workspaceClient, jobId, signal) {
+		return arrowColumnNames(await workspaceClient.statementExecution.getStatement({ statement_id: jobId }, this._createContext(signal)));
+	}
+	/**
+	* Normalize an error caught during statement execution/polling and rethrow.
+	* Abort and already-structured `AppKitError`s pass through untouched;
+	* anything else is wrapped as an `ExecutionError`, preserving the SDK's
+	* structured `ApiError.errorCode` (e.g. "INVALID_PARAMETER_VALUE",
+	* "BAD_REQUEST") so callers can branch on a stable identifier rather than
+	* substring-matching the message.
+	*/
+	_rethrowStatementError(error) {
+		if (error instanceof Error && error.name === "AbortError") throw error;
+		if (error instanceof AppKitError) throw error;
+		const sdkErrorCode = error && typeof error === "object" && "errorCode" in error ? error.errorCode : void 0;
+		throw ExecutionError.statementFailed(error instanceof Error ? error.message : String(error), typeof sdkErrorCode === "string" ? sdkErrorCode : void 0);
 	}
 	_createContext(signal) {
 		return new Context({ cancellationToken: {