@nshiab/simple-data-analysis-core 2.1.12 → 2.1.14

package/src/methods/loadArray.ts

@@ -0,0 +1,310 @@
+import stringifyUnknown from "../helpers/stringifyUnknown.ts";
+import {
+  arrayValue,
+  type DuckDBConnection,
+  DuckDBDateValue,
+  DuckDBTimestampTZValue,
+  DuckDBTimestampValue,
+  DuckDBTimeValue,
+  type DuckDBValue,
+} from "@duckdb/node-api";
+import appendColumnBatches from "../helpers/appendColumnBatches.ts";
+import prepareGeometry from "../helpers/prepareGeometry.ts";
+import prepareJSON from "../helpers/prepareJSON.ts";
+import geometryFromJSON from "../helpers/geometryFromJSON.ts";
+import queueOp from "../helpers/queueOp.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+import parseType from "../helpers/parseTypes.ts";
+import parseDuckDBType from "../helpers/parseDuckDBType.ts";
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+
+export default function loadArray(
+  simpleTable: SimpleTable,
+  rows: { [key: string]: unknown }[],
+  options: NonNullable<Parameters<SimpleTable["loadArray"]>[1]> = {},
+) {
+  // This validation doesn't need the database, so it stays at call time.
+  if (rows.length === 0) {
+    throw new Error(
+      "The array is empty. loadArray needs at least one object to infer the column types.",
+    );
+  }
+
+  const prepared = prepareArray(rows, options.columnTypes, true);
+
+  queueOp(simpleTable, {
+    kind: "barrier",
+    method: "loadArray()",
+    parameters: { rows: `${rows.length} rows` },
+    execute: () => executePreparedArray(simpleTable, prepared),
+  });
+}
+
+type PreparedArray = {
+  keys: string[];
+  types: string[];
+  columnsData: DuckDBValue[][];
+  rowCount: number;
+};
+
+export function prepareArray(
+  rows: { [key: string]: unknown }[],
+  columnTypes: { [key: string]: string } = {},
+  requireExplicitNestedTypes = false,
+): PreparedArray {
+  const keys = Object.keys(rows[0]);
+  const overrides = new Map<string, string>();
+  for (const [key, type] of Object.entries(columnTypes)) {
+    if (!keys.includes(key)) {
+      throw new Error(`Unknown column ${JSON.stringify(key)} in loadArray columnTypes.`);
+    }
+    if (type.toUpperCase() === "JSON") {
+      overrides.set(key, "JSON");
+      continue;
+    }
+    if (/^geometry/i.test(type)) {
+      if (!/^geometry\('EPSG:4326'\)$/i.test(type)) {
+        throw new Error(
+          `Unsupported type ${JSON.stringify(type)} for column ${JSON.stringify(
+            key,
+          )}. GeoJSON ingestion requires GEOMETRY('EPSG:4326'); reproject input to WGS84 first.`,
+        );
+      }
+      overrides.set(key, "GEOMETRY('EPSG:4326')");
+      continue;
+    }
+    try {
+      const normalized = parseType(type as Parameters<typeof parseType>[0]);
+      parseDuckDBType(normalized);
+      overrides.set(key, normalized);
+    } catch {
+      throw new Error(
+        `Unsupported type ${JSON.stringify(type)} for column ${JSON.stringify(key)}.`,
+      );
+    }
+  }
+  const firstNonNullValue = keys.map(
+    (key) => rows.find((obj) => obj[key] !== null && obj[key] !== undefined)?.[key],
+  );
+  const types: string[] = [];
+  const columnsData: DuckDBValue[][] = keys.map(() => {
+    const values: DuckDBValue[] = [];
+    values.length = rows.length;
+    return values;
+  });
+
+  for (let i = 0; i < keys.length; i++) {
+    const key = keys[i];
+    const columnData = columnsData[i];
+    const override = overrides.get(key);
+    if (override !== undefined) {
+      types[i] = override;
+      for (let j = 0; j < rows.length; j++) {
+        columnData[j] = prepareTypedValue(rows[j][key], override, key, j + 1);
+      }
+      continue;
+    }
+    if (requireExplicitNestedTypes) {
+      for (let j = 0; j < rows.length; j++) {
+        const cell = rows[j][key];
+        if (cell !== null && typeof cell === "object" && !(cell instanceof Date)) {
+          throw new Error(
+            `Column ${JSON.stringify(key)}, row ${
+              j + 1
+            }: array and object cells require an explicit columnTypes entry. Use JSON for nested data, FLOAT[n] for fixed-size vectors, or GEOMETRY('EPSG:4326') for GeoJSON geometries.`,
+          );
+        }
+      }
+    }
+    const value = firstNonNullValue[i];
+    const type = typeof value;
+    if (type === "symbol" || type === "function") {
+      throw new Error(
+        `Type ${type} not supported for ${key}. Value: ${stringifyUnknown(value, "template")}`,
+      );
+    } else if (type === "undefined") {
+      types[i] = "VARCHAR";
+      for (let j = 0; j < rows.length; j++) {
+        columnData[j] = null;
+      }
+    } else if (type === "object") {
+      if (value instanceof Date) {
+        types[i] = "TIMESTAMP";
+        for (let j = 0; j < rows.length; j++) {
+          const d = rows[j][key];
+          if (d === null || d === undefined || Number.isNaN(d)) {
+            columnData[j] = null;
+          } else {
+            const date = d as Date;
+            columnData[j] = new DuckDBTimestampValue(BigInt(date.getTime() * 1000));
+          }
+        }
+      } else if (Array.isArray(value)) {
+        types[i] = `FLOAT[${value.length}]`;
+        for (let j = 0; j < rows.length; j++) {
+          const d = rows[j][key];
+          columnData[j] = d === null || d === undefined ? null : arrayValue([...(d as number[])]);
+        }
+      } else {
+        throw new Error(
+          `Type object not supported for ${key}. Value: ${stringifyUnknown(value, "template")}`,
+        );
+      }
+    } else {
+      types[i] = parseType(type);
+      for (let j = 0; j < rows.length; j++) {
+        const d = rows[j][key];
+        columnData[j] =
+          d === null || d === undefined || Number.isNaN(d) ? null : (d as DuckDBValue);
+      }
+    }
+  }
+
+  return { keys, types, columnsData, rowCount: rows.length };
+}
+
+export async function executePreparedArray(simpleTable: SimpleTable, prepared: PreparedArray) {
+  if (simpleTable.connection === undefined) {
+    await simpleTable.sdb.start();
+    simpleTable.connection = simpleTable.sdb.connection;
+  }
+
+  const { keys, types, columnsData, rowCount } = prepared;
+
+  const hasGeometry = types.includes("GEOMETRY('EPSG:4326')");
+  const needsConversion = hasGeometry || types.includes("JSON");
+  const staged = needsConversion
+    ? `__sda_array_${crypto.randomUUID().replaceAll("-", "")}`
+    : simpleTable.name;
+  const storageTypes = types.map((type) =>
+    type.startsWith("GEOMETRY") || type === "JSON" ? "VARCHAR" : type,
+  );
+  if (hasGeometry && !simpleTable.sdb.spatialLoaded) {
+    await simpleTable.sdb.customQuery(
+      "INSTALL spatial; LOAD spatial; SET geometry_always_xy = true;",
+    );
+    simpleTable.sdb.spatialLoaded = true;
+  }
+  try {
+    await simpleTable.sdb.customQuery(
+      `CREATE ${needsConversion ? "TEMP" : "OR REPLACE"} TABLE ${quoteIdentifier(staged)}(${keys
+        .map((key, i) => `${quoteIdentifier(key)} ${storageTypes[i]}`)
+        .join(", ")})`,
+    );
+
+    await appendColumnBatches(
+      simpleTable.connection as DuckDBConnection,
+      staged,
+      storageTypes.map((type) => parseDuckDBType(type)),
+      rowCount,
+      (column, start, end) => columnsData[column].slice(start, end),
+    );
+    if (!needsConversion) return;
+    // CTAS is atomic: conversion must finish before the destination is replaced.
+    await simpleTable.sdb.customQuery(
+      `CREATE OR REPLACE TABLE ${quoteIdentifier(simpleTable.name)} AS SELECT ${keys
+        .map((key, i) =>
+          types[i].startsWith("GEOMETRY")
+            ? `${geometryFromJSON(quoteIdentifier(key))} AS ${quoteIdentifier(key)}`
+            : types[i] === "JSON"
+              ? `${quoteIdentifier(key)}::JSON AS ${quoteIdentifier(key)}`
+              : quoteIdentifier(key),
+        )
+        .join(", ")} FROM ${quoteIdentifier(staged)}`,
+    );
+  } finally {
+    if (needsConversion) {
+      await simpleTable.sdb.customQuery(`DROP TABLE IF EXISTS ${quoteIdentifier(staged)}`);
+    }
+  }
+}
+
+/** Validates and snapshots a value for an explicitly declared destination type. */
+function prepareTypedValue(value: unknown, type: string, column: string, row: number): DuckDBValue {
+  if (type === "JSON") return prepareJSON(value, column, row);
+  if (type === "GEOMETRY('EPSG:4326')") {
+    return prepareGeometry(value, column, row);
+  }
+  if (value === null || value === undefined || Number.isNaN(value)) return null;
+  let compatible = false;
+  if (type === "VARCHAR" && typeof value === "string") return value;
+  if (type === "BOOLEAN" && typeof value === "boolean") return value;
+  if (type === "DOUBLE") {
+    if (typeof value === "number") return value;
+    compatible = typeof value === "bigint";
+    if (typeof value === "bigint") {
+      const number = Number(value);
+      if (Number.isFinite(number) && BigInt(number) === value) return number;
+    }
+  } else if (type === "INTEGER") {
+    compatible = typeof value === "number" || typeof value === "bigint";
+    if (typeof value === "number") {
+      if (Number.isInteger(value) && value >= -2147483648 && value <= 2147483647) {
+        return value;
+      }
+    } else if (typeof value === "bigint" && value >= -2147483648n && value <= 2147483647n) {
+      return Number(value);
+    }
+  } else if (type === "BIGINT") {
+    compatible = typeof value === "number" || typeof value === "bigint";
+    if (typeof value === "bigint") {
+      if (value >= -9223372036854775808n && value <= 9223372036854775807n) {
+        return value;
+      }
+    } else if (
+      typeof value === "number" &&
+      Number.isInteger(value) &&
+      value >= -(2 ** 63) &&
+      value < 2 ** 63
+    ) {
+      // The upper bound is exclusive: 2 ** 63 - 1 rounds up as a JS number.
+      return BigInt(value);
+    }
+  } else if (["DATE", "TIME", "TIMESTAMP", "TIMESTAMP WITH TIME ZONE"].includes(type)) {
+    if (type === "TIME" && value instanceof DuckDBTimeValue) {
+      if (value.micros >= 0n && value.micros <= 86400000000n) {
+        return new DuckDBTimeValue(value.micros);
+      }
+      compatible = true;
+    } else if (value instanceof Date) {
+      const millis = value.getTime();
+      compatible = Number.isFinite(millis);
+      if (compatible) {
+        if (type === "DATE" && millis % 86400000 === 0) {
+          return new DuckDBDateValue(millis / 86400000);
+        }
+        const micros = BigInt(millis) * 1000n;
+        if (type === "TIMESTAMP") return new DuckDBTimestampValue(micros);
+        if (type === "TIMESTAMP WITH TIME ZONE") {
+          return new DuckDBTimestampTZValue(micros);
+        }
+      }
+    }
+  } else if (type.startsWith("FLOAT[") && Array.isArray(value)) {
+    compatible = true;
+    const size = Number(type.slice(6, -1));
+    if (
+      value.length === size &&
+      value.every(
+        (item) =>
+          item === null ||
+          item === undefined ||
+          (typeof item === "number" && (Number.isNaN(item) || Math.fround(item) === item)),
+      )
+    ) {
+      return arrayValue(
+        value.map((item: unknown) =>
+          item === undefined || Number.isNaN(item) ? null : (item as number | null),
+        ),
+      );
+    }
+  }
+  const displayed = typeof value === "string" ? JSON.stringify(value) : stringifyUnknown(value);
+  throw new Error(
+    `Column ${JSON.stringify(column)}, row ${row}: value ${displayed} ${
+      compatible
+        ? `cannot be stored as ${type} without losing information`
+        : `is incompatible with ${type}`
+    }. Select a type compatible with this value.`,
+  );
+}

package/src/methods/loadDB.ts

@@ -0,0 +1,73 @@
+import queryDbFile from "../helpers/queryDbFile.ts";
+import { existsSync } from "node:fs";
+import type SimpleDB from "../class/SimpleDB.ts";
+import cleanPath from "../helpers/cleanPath.ts";
+import getDbFileType from "../helpers/getDbFileType.ts";
+import getCurrentDatabase from "../helpers/getCurrentDatabase.ts";
+import getDbIndexes from "../helpers/getDbIndexes.ts";
+import parseValue from "../helpers/parseValue.ts";
+import prepareDbExtensions from "../helpers/prepareDbExtensions.ts";
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import readDbMetadata from "../helpers/readDbMetadata.ts";
+import setDbProps from "../helpers/setDbProps.ts";
+import writeDbMetadata from "../helpers/writeDbMetadata.ts";
+
+export default async function loadDB(sdb: SimpleDB, file: string) {
+  const type = getDbFileType(file);
+  if (!existsSync(file)) throw new Error(`The file ${file} does not exist.`);
+  if (sdb.readOnly) {
+    throw new Error("loadDB() cannot import into a read-only database.");
+  }
+
+  const destination = await getCurrentDatabase(sdb);
+  const target = quoteIdentifier(destination);
+  const name = `__sda_import_${crypto.randomUUID().replaceAll("-", "")}`;
+  const source = quoteIdentifier(name);
+  if (type === "sqlite") await queryDbFile(sdb, "INSTALL sqlite; LOAD sqlite;");
+  await queryDbFile(sdb, `ATTACH '${cleanPath(file)}' AS ${source} (TYPE ${type}, READ_ONLY);`);
+
+  try {
+    const indexes = type === "duckdb" ? await readDbMetadata(sdb, name) : {};
+    await readDbMetadata(sdb, destination);
+    await prepareDbExtensions(sdb, name, indexes);
+    const conflicts = await queryDbFile(
+      sdb,
+      `SELECT incoming.table_schema, incoming.table_name
+       FROM information_schema.tables incoming
+       JOIN information_schema.tables existing
+         ON lower(incoming.table_schema) = lower(existing.table_schema)
+         AND lower(incoming.table_name) = lower(existing.table_name)
+       WHERE incoming.table_catalog = ${parseValue(name)}
+         AND existing.table_catalog = ${parseValue(destination)}
+         AND incoming.table_schema <> '__sda';`,
+      { returnData: true },
+    );
+    // Also protect registered table handles that have no physical table yet.
+    const incoming = await queryDbFile(
+      sdb,
+      `SELECT table_name FROM information_schema.tables
+       WHERE table_catalog = ${parseValue(name)} AND table_schema = 'main';`,
+      { returnData: true },
+    );
+    const registered = new Set(sdb.getTables().map((table) => table.name.toLowerCase()));
+    const names = new Set([
+      ...conflicts!.map((row) => `${String(row.table_schema)}.${String(row.table_name)}`),
+      ...incoming!
+        .filter((row) => registered.has(String(row.table_name).toLowerCase()))
+        .map((row) => `main.${String(row.table_name)}`),
+    ]);
+    if (names.size > 0) {
+      throw new Error(`loadDB() cannot import existing tables: ${[...names].join(", ")}.`);
+    }
+    const mergedIndexes = { ...getDbIndexes(sdb), ...indexes };
+    await queryDbFile(
+      sdb,
+      `DROP TABLE IF EXISTS ${target}.__sda.metadata;
+       COPY FROM DATABASE ${source} TO ${target};`,
+    );
+    await writeDbMetadata(sdb, destination, mergedIndexes);
+    await setDbProps(sdb, indexes);
+  } finally {
+    await queryDbFile(sdb, `DETACH ${source};`);
+  }
+}

package/src/methods/loadData.ts

@@ -0,0 +1,238 @@
+import quoteIdentifier from "../helpers/quoteIdentifier.ts";
+import parseValue from "../helpers/parseValue.ts";
+import queueOp from "../helpers/queueOp.ts";
+import getExtension from "../helpers/getExtension.ts";
+import stringToArray from "../helpers/stringToArray.ts";
+import type SimpleTable from "../class/SimpleTable.ts";
+
+export default function loadData(
+  simpleTable: SimpleTable,
+  files: string | string[],
+  options: {
+    fileType?: "csv" | "dsv" | "json" | "parquet" | "excel";
+    autoDetect?: boolean;
+    conditions?: string;
+    limit?: number;
+    includeFilename?: boolean;
+    unifyColumns?: boolean;
+    columnTypes?: { [key: string]: string };
+    // column selection
+    columns?: string[];
+    // csv options
+    header?: boolean;
+    allText?: boolean;
+    delim?: string;
+    skip?: number;
+    nullPadding?: boolean;
+    ignoreErrors?: boolean;
+    compression?: "none" | "gzip" | "zstd";
+    encoding?: string;
+    strict?: boolean;
+    // json options
+    jsonFormat?: "unstructured" | "newlineDelimited" | "array";
+    records?: boolean;
+    // excel options
+    sheet?: string;
+  } = {},
+) {
+  files = Array.isArray(files) ? [...files] : files;
+  options = structuredClone(options);
+  // Building the SELECT doesn't need the database, so invalid arguments
+  // (like the columns option with an Excel file) throw at call time.
+  const select = loadDataSelect(stringToArray(files), options);
+
+  queueOp(simpleTable, {
+    kind: "source",
+    method: "loadData()",
+    parameters: { files, options },
+    rawSQL: options.conditions === undefined ? undefined : [options.conditions],
+    schema: knownSourceSchema(stringToArray(files), options),
+    buildSelect: () => select,
+  });
+}
+
+type LoadDataOptions = {
+  fileType?: "csv" | "dsv" | "json" | "parquet" | "excel";
+  autoDetect?: boolean;
+  conditions?: string;
+  limit?: number;
+  includeFilename?: boolean;
+  unifyColumns?: boolean;
+  columnTypes?: { [key: string]: string };
+  columns?: string[];
+  header?: boolean;
+  allText?: boolean;
+  delim?: string;
+  skip?: number;
+  nullPadding?: boolean;
+  ignoreErrors?: boolean;
+  compression?: "none" | "gzip" | "zstd";
+  encoding?: string;
+  strict?: boolean;
+  jsonFormat?: "unstructured" | "newlineDelimited" | "array";
+  records?: boolean;
+  sheet?: string;
+};
+
+function knownSourceSchema(
+  files: string[],
+  options: LoadDataOptions,
+): { [column: string]: string } | undefined {
+  if (options.columns === undefined || options.columns.length === 0) {
+    return undefined;
+  }
+  const extension = getExtension(files[0]);
+  const textSource =
+    options.fileType === "csv" ||
+    options.fileType === "dsv" ||
+    options.fileType === "excel" ||
+    extension === "csv" ||
+    extension === "xlsx" ||
+    typeof options.delim === "string";
+  if (!textSource) return undefined;
+  if (options.allText === true) {
+    return Object.fromEntries(options.columns.map((column) => [column, "VARCHAR"]));
+  }
+  if (
+    options.columnTypes !== undefined &&
+    options.columns.every((column) => options.columnTypes?.[column] !== undefined)
+  ) {
+    return Object.fromEntries(
+      options.columns.map((column) => [column, options.columnTypes![column].toUpperCase()]),
+    );
+  }
+  return undefined;
+}
+
+export function loadDataQuery(table: string, files: string[], options: LoadDataOptions = {}) {
+  return `CREATE OR REPLACE TABLE ${quoteIdentifier(table)} AS ${loadDataSelect(files, options)};`;
+}
+
+function loadDataSelect(files: string[], options: LoadDataOptions = {}) {
+  if (Object.values(options.columnTypes ?? {}).some((type) => /^\s*geometry\b/i.test(type))) {
+    throw new Error(
+      "Geometry column types are not supported by loadData(). Use loadGeoData() instead.",
+    );
+  }
+  const fileExtension = getExtension(files[0]);
+  if (
+    options.fileType !== undefined &&
+    !["csv", "dsv", "json", "parquet", "excel"].includes(options.fileType)
+  ) {
+    throw unsupportedFileTypeError(files[0], options.fileType, fileExtension);
+  }
+  const filesAsString = "[" + files.map((file) => parseValue(file)).join(", ") + "]";
+
+  // Column selection: throw for Excel, build SELECT list for others
+  const isExcel = options.fileType === "excel" || fileExtension === "xlsx";
+  if (options.columns && options.columns.length > 0 && isExcel) {
+    throw new Error("The 'columns' option is not supported for Excel files.");
+  }
+  const selectColumns =
+    options.columns && options.columns.length > 0
+      ? options.columns.map((c) => `${quoteIdentifier(c)}`).join(", ")
+      : "*";
+
+  // General options, except for parquet
+  const autoDetect =
+    typeof options.autoDetect === "boolean"
+      ? `, auto_detect=${String(options.autoDetect).toUpperCase()}`
+      : ", auto_detect=TRUE";
+  const columnTypes = options.columnTypes
+    ? `${Object.entries(options.columnTypes)
+        .map(([column, type]) => `${parseValue(column)}: ${parseValue(type)}`)
+        .join(", ")}`
+    : null;
+  const includeFilename =
+    typeof options.includeFilename === "boolean"
+      ? `, filename=${String(options.includeFilename).toUpperCase()}`
+      : "";
+  const unifyColumns =
+    typeof options.unifyColumns === "boolean"
+      ? `, union_by_name=${String(options.unifyColumns).toUpperCase()}`
+      : "";
+  const generalOptions = `${autoDetect}${includeFilename}${unifyColumns}`;
+
+  const conditions = options.conditions ? ` WHERE ${options.conditions}` : "";
+  const limit = typeof options.limit === "number" ? ` LIMIT ${options.limit}` : "";
+
+  if (
+    options.fileType === "csv" ||
+    fileExtension === "csv" ||
+    options.fileType === "dsv" ||
+    typeof options.delim === "string"
+  ) {
+    const header =
+      typeof options.header === "boolean"
+        ? `, header=${String(options.header).toUpperCase()}`
+        : ", header=TRUE";
+    const allText =
+      typeof options.allText === "boolean"
+        ? `, all_varchar=${String(options.allText).toUpperCase()}`
+        : "";
+    const delim = options.delim ? `, delim=${parseValue(options.delim)}` : "";
+    const skip = options.skip ? `, skip=${options.skip}` : "";
+    const ignoreErrors = options.ignoreErrors ? `, ignore_errors	=${options.ignoreErrors}` : "";
+    const nullPadding = options.nullPadding ? `, null_padding=${options.nullPadding}` : "";
+    const compression = options.compression
+      ? `, compression=${parseValue(options.compression)}`
+      : "";
+    const encoding = options.encoding ? `, encoding=${parseValue(options.encoding)}` : "";
+    const strict = options.strict === false ? `, strict_mode=FALSE` : "";
+    const types = columnTypes === null ? "" : `, types={${columnTypes}}`;
+
+    return `SELECT ${selectColumns} FROM read_csv_auto(${filesAsString}${generalOptions}${types}${header}${allText}${delim}${skip}${compression}${encoding}${strict}${nullPadding}${ignoreErrors})${conditions}${limit}`;
+  } else if (options.fileType === "json" || fileExtension === "json") {
+    // DuckDB expects "newline_delimited" (snake_case), unlike the other two
+    // format values, which already match the public camelCase option.
+    const jsonFormat = options.jsonFormat
+      ? `, format=${parseValue(
+          options.jsonFormat === "newlineDelimited" ? "newline_delimited" : options.jsonFormat,
+        )}`
+      : "";
+    const records =
+      typeof options.records === "boolean"
+        ? `, records=${String(options.records).toUpperCase()}`
+        : "";
+    const columns = columnTypes === null ? "" : `, columns={${columnTypes}}`;
+    return `SELECT ${selectColumns} FROM read_json_auto(${filesAsString}${generalOptions}${columns}${jsonFormat}${records})${conditions}${limit}`;
+  } else if (options.fileType === "parquet" || fileExtension === "parquet") {
+    return `SELECT ${selectColumns} FROM read_parquet(${filesAsString}${includeFilename}${unifyColumns})${conditions}${limit}`;
+  } else if (options.fileType === "excel" || fileExtension === "xlsx") {
+    if (files.length > 1) {
+      throw new Error(
+        "For excel files or files with extension .xlsx, you can pass only one file at the time.",
+      );
+    }
+
+    const header =
+      typeof options.header === "boolean"
+        ? `, header=${String(options.header).toUpperCase()}`
+        : ", header=TRUE";
+    const allText =
+      typeof options.allText === "boolean"
+        ? `, all_varchar=${String(options.allText).toUpperCase()}`
+        : "";
+
+    return `SELECT ${selectColumns} FROM read_xlsx(${parseValue(files[0])}${
+      options.sheet ? `, sheet=${parseValue(options.sheet)}` : ""
+    }${header}${allText})${conditions}${limit}`;
+  } else {
+    throw unsupportedFileTypeError(files[0], options.fileType, fileExtension);
+  }
+}
+
+function unsupportedFileTypeError(
+  file: string,
+  fileType: string | undefined,
+  fileExtension: string,
+): Error {
+  const receivedFileType = JSON.stringify(fileType) ?? String(fileType);
+  return new Error(
+    `loadData() could not determine a supported file type for ${JSON.stringify(
+      file,
+    )}. options.fileType: ${receivedFileType}. Detected extension: ${JSON.stringify(
+      `.${fileExtension}`,
+    )}. Supported file types: "csv", "dsv", "json", "parquet", and "excel" (for .xlsx files).`,
+  );
+}