@cqlite/node 0.9.2 → 0.11.0

package/lib/error-wrapper.js

@@ -351,6 +351,36 @@ function createWrappedDatabase(NativeDatabase, wrapPreparedStatement) {
       };
     }
 
+    /**
+     * Export the results of a CQL query to a Parquet file.
+     *
+     * The query runs with streaming, so large result sets are written
+     * within bounded memory. The export runs off the JavaScript main
+     * thread.
+     *
+     * @param {string} query - CQL SELECT statement to execute
+     * @param {string} path - Destination file path (created or truncated)
+     * @param {Object} [options] - Optional export options
+     * @param {number} [options.rowGroupSize=10000] - Rows per Parquet row group
+     * @param {string} [options.compression='snappy'] - 'snappy', 'zstd', or 'none'
+     * @returns {Promise<number>} Number of rows written
+     * @throws {CqliteError} If the query fails or the file cannot be written
+     *
+     * @example
+     * const rows = await db.exportParquet(
+     *   'SELECT * FROM my_ks.my_table',
+     *   '/tmp/out.parquet',
+     *   { rowGroupSize: 5000, compression: 'zstd' }
+     * );
+     */
+    async exportParquet(query, path, options) {
+      try {
+        return await this._native.exportParquet(query, path, options);
+      } catch (error) {
+        throw enhanceError(error);
+      }
+    }
+
     /**
      * Prepare a CQL query for analysis.
      *

package/lib/index.d.ts

@@ -503,6 +503,30 @@ export interface StreamingConfig {
   chunkSize?: number;
 }
 
+/**
+ * Options for `Database.exportParquet()`.
+ *
+ * @example
+ * ```typescript
+ * await db.exportParquet(query, '/tmp/out.parquet', {
+ *   rowGroupSize: 5000,
+ *   compression: 'zstd',
+ * });
+ * ```
+ */
+export interface ParquetExportOptions {
+  /**
+   * Rows per Parquet row group.
+   * Smaller groups reduce memory at some I/O cost. Default: 10000.
+   */
+  rowGroupSize?: number;
+
+  /**
+   * Compression codec: 'snappy' (default), 'zstd', or 'none'.
+   */
+  compression?: 'snappy' | 'zstd' | 'none';
+}
+
 /**
  * Streaming query result for memory-efficient processing.
  *
@@ -956,6 +980,43 @@ export declare class Database {
    */
   executeStreaming(query: string, config?: StreamingConfig): StreamingResult;
 
+  /**
+   * Export the results of a CQL query to a Parquet file.
+   *
+   * The query runs with streaming, so arbitrarily large result sets are
+   * written within bounded memory (rows are flushed to Parquet row groups
+   * as they arrive). The export runs as an async task off the JavaScript
+   * main thread.
+   *
+   * Types use the high-fidelity schema-driven Arrow mapping: date -> Date32,
+   * time -> Time64(ns), decimal/varint -> Decimal128, uuid ->
+   * FixedSizeBinary(16) with the Arrow UUID extension, list/set -> List,
+   * map -> Map, UDT/tuple -> Struct. CQLite produces Parquet files only;
+   * committing files to Iceberg/Delta table formats is out of scope.
+   *
+   * @param query - CQL SELECT statement to execute
+   * @param path - Destination file path (created or truncated)
+   * @param options - Optional row group size and compression
+   * @returns Promise resolving to the number of rows written
+   * @throws {CqliteError} code "CONFIG" for invalid options, "IO" for
+   *         file/encoding failures, "QUERY"/"PARSE" for query failures
+   *
+   * @example
+   * ```typescript
+   * const rows = await db.exportParquet(
+   *   'SELECT * FROM my_ks.my_table',
+   *   '/tmp/out.parquet',
+   *   { rowGroupSize: 5000, compression: 'zstd' }
+   * );
+   * console.log(`Exported ${rows} row(s)`);
+   * ```
+   */
+  exportParquet(
+    query: string,
+    path: string,
+    options?: ParquetExportOptions
+  ): Promise<number>;
+
   /**
    * Prepare a CQL query for analysis.
    *

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@cqlite/node",
-  "version": "0.9.2",
+  "version": "0.11.0",
   "description": "Node.js bindings for CQLite - read Apache Cassandra 5.0 SSTables without cluster dependencies",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",