mongo.do 0.1.0 → 0.1.1

package/dist/olap/clickhouse/olap-backend.js

@@ -1,1083 +0,0 @@
-/**
- * ClickHouse OLAP Backend
- *
- * Read-only backend implementing MondoBackend interface for analytical queries.
- * Uses ClickHouse HTTP API for query execution with MongoDB query translation.
- *
- * Key features:
- * - Read-only: All write operations throw ReadOnlyOperationError
- * - Query translation: MongoDB queries/aggregations -> ClickHouse SQL
- * - Type mapping: ClickHouse types -> BSON documents
- * - Cursor management: Handles batched results
- *
- * Issue: mongo.do-yubk
- */
-import { ObjectId } from '../../types/objectid';
-import { createQueryExecutor, ClickHouseError, } from './query-executor';
-import { ClickHouseResultMapper, } from './mapper';
-// =============================================================================
-// Error Classes
-// =============================================================================
-/**
- * Error thrown when attempting write operations on read-only OLAP backend
- */
-export class ReadOnlyOperationError extends Error {
-    operation;
-    constructor(operation) {
-        super(`Read-only OLAP backend: ${operation} operations are not supported. ` +
-            `This backend is designed for analytical read queries only. ` +
-            `Write operations (insert, update, delete) are not available.`);
-        this.name = 'ReadOnlyOperationError';
-        this.operation = operation;
-    }
-}
-// =============================================================================
-// ClickHouse OLAP Backend
-// =============================================================================
-/** Default batch size for cursor results */
-const DEFAULT_BATCH_SIZE = 101;
-/** Default result limit to prevent excessive memory usage */
-const DEFAULT_RESULT_LIMIT = 10000;
-/** Cursor timeout in milliseconds (10 minutes) */
-const CURSOR_TIMEOUT_MS = 10 * 60 * 1000;
-/**
- * ClickHouse OLAP Backend
- *
- * Implements MondoBackend interface for read-only analytical queries.
- */
-export class ClickHouseOLAPBackend {
-    _executor;
-    _mapper;
-    _config;
-    _cursors = new Map();
-    _nextCursorId = 1n;
-    _customHeaders;
-    constructor(config, executor) {
-        this._config = {
-            defaultLimit: DEFAULT_RESULT_LIMIT,
-            ...config,
-        };
-        this._executor = executor;
-        this._mapper = new ClickHouseResultMapper({
-            preserveObjectId: true,
-            treatTimestampAsDate: true,
-        });
-        this._customHeaders = config.headers || {};
-    }
-    // ===========================================================================
-    // Database Operations
-    // ===========================================================================
-    async listDatabases() {
-        const sql = 'SELECT name, engine FROM system.databases ORDER BY name';
-        const result = await this._executeQuery(sql);
-        return result.rows.map((row) => ({
-            name: row.name,
-            sizeOnDisk: 0, // ClickHouse doesn't easily provide this
-            empty: false,
-        }));
-    }
-    async createDatabase(_name) {
-        throw new ReadOnlyOperationError('createDatabase');
-    }
-    async dropDatabase(_name) {
-        throw new ReadOnlyOperationError('dropDatabase');
-    }
-    async databaseExists(name) {
-        const sql = `SELECT name FROM system.databases WHERE name = '${this._escapeString(name)}' LIMIT 1`;
-        const result = await this._executeQuery(sql);
-        return result.rows.length > 0;
-    }
-    // ===========================================================================
-    // Collection Operations
-    // ===========================================================================
-    async listCollections(dbName, filter) {
-        let sql = `
-      SELECT
-        name,
-        engine,
-        total_rows
-      FROM system.tables
-      WHERE database = '${this._escapeString(dbName)}'
-    `;
-        if (filter?.name && typeof filter.name === 'string') {
-            sql += ` AND name = '${this._escapeString(filter.name)}'`;
-        }
-        sql += ' ORDER BY name';
-        const result = await this._executeQuery(sql);
-        return result.rows.map((row) => ({
-            name: row.name,
-            type: 'collection',
-            options: { engine: row.engine },
-            info: {
-                readOnly: true, // OLAP is always read-only
-            },
-        }));
-    }
-    async createCollection(_db, _name, _options) {
-        throw new ReadOnlyOperationError('createCollection');
-    }
-    async dropCollection(_db, _name) {
-        throw new ReadOnlyOperationError('dropCollection');
-    }
-    async collectionExists(dbName, name) {
-        const sql = `
-      SELECT name
-      FROM system.tables
-      WHERE database = '${this._escapeString(dbName)}'
-        AND name = '${this._escapeString(name)}'
-      LIMIT 1
-    `;
-        const result = await this._executeQuery(sql);
-        return result.rows.length > 0;
-    }
-    async collStats(dbName, collection) {
-        const sql = `
-      SELECT
-        rows,
-        bytes_on_disk,
-        data_compressed_bytes,
-        data_uncompressed_bytes,
-        primary_key_bytes_in_memory
-      FROM system.parts
-      WHERE database = '${this._escapeString(dbName)}'
-        AND table = '${this._escapeString(collection)}'
-        AND active = 1
-    `;
-        const result = await this._executeQuery(sql);
-        // Aggregate stats from all parts
-        let totalRows = 0;
-        let totalBytesOnDisk = 0;
-        let totalUncompressed = 0;
-        let totalIndexSize = 0;
-        for (const row of result.rows) {
-            totalRows += row.rows;
-            totalBytesOnDisk += row.bytes_on_disk;
-            totalUncompressed += row.data_uncompressed_bytes;
-            totalIndexSize += row.primary_key_bytes_in_memory;
-        }
-        return {
-            ns: `${dbName}.${collection}`,
-            count: totalRows,
-            size: totalUncompressed,
-            avgObjSize: totalRows > 0 ? totalUncompressed / totalRows : 0,
-            storageSize: totalBytesOnDisk,
-            totalIndexSize,
-            nindexes: 1, // Primary key
-            indexSizes: { _id_: totalIndexSize },
-        };
-    }
-    async dbStats(dbName) {
-        const sql = `
-      SELECT
-        count() as tables,
-        sum(total_rows) as total_rows,
-        sum(total_bytes) as total_bytes
-      FROM system.tables
-      WHERE database = '${this._escapeString(dbName)}'
-    `;
-        const result = await this._executeQuery(sql);
-        const row = result.rows[0] || { tables: 0, total_rows: 0, total_bytes: 0 };
-        return {
-            db: dbName,
-            collections: row.tables,
-            views: 0,
-            objects: row.total_rows,
-            avgObjSize: row.total_rows > 0 ? row.total_bytes / row.total_rows : 0,
-            dataSize: row.total_bytes,
-            storageSize: row.total_bytes,
-            indexes: row.tables,
-            indexSize: 0,
-        };
-    }
-    // ===========================================================================
-    // CRUD Operations - Read
-    // ===========================================================================
-    async find(dbName, collection, options) {
-        const tableName = `${this._escapeIdentifier(dbName)}.${this._escapeIdentifier(collection)}`;
-        const { filter, projection, sort, limit, skip, batchSize } = options;
-        // Build SQL query
-        let sql = 'SELECT ';
-        // Handle projection
-        if (projection && Object.keys(projection).length > 0) {
-            const projectionFields = this._buildProjection(projection);
-            sql += projectionFields;
-        }
-        else {
-            sql += '*';
-        }
-        sql += ` FROM ${tableName}`;
-        // Add FINAL if configured
-        if (this._config.useFinal) {
-            sql += ' FINAL';
-        }
-        // Build WHERE clause using QueryTranslator
-        const params = [];
-        if (filter && Object.keys(filter).length > 0) {
-            const whereClause = this._translateFilter(filter, params);
-            if (whereClause && whereClause !== '1 = 1') {
-                sql += ` WHERE ${whereClause}`;
-            }
-        }
-        // Build ORDER BY clause
-        if (sort && Object.keys(sort).length > 0) {
-            const orderParts = [];
-            for (const [field, direction] of Object.entries(sort)) {
-                const dir = direction === -1 ? 'DESC' : 'ASC';
-                orderParts.push(`${field} ${dir}`);
-            }
-            sql += ` ORDER BY ${orderParts.join(', ')}`;
-        }
-        // Build LIMIT and OFFSET
-        const effectiveLimit = limit ?? this._config.defaultLimit;
-        sql += ` LIMIT ${effectiveLimit}`;
-        if (skip && skip > 0) {
-            sql += ` OFFSET ${skip}`;
-        }
-        // Execute query
-        let result;
-        try {
-            result = await this._executeQueryWithParams(sql, params);
-        }
-        catch (error) {
-            // Re-throw with better error message for network errors
-            if (error instanceof Error && (error.message.includes('undefined') || error.message.includes('null'))) {
-                throw new Error('Failed to fetch');
-            }
-            throw error;
-        }
-        // Map results to BSON documents
-        const documents = this._mapResults(result.rows, result.meta);
-        const effectiveBatchSize = batchSize || DEFAULT_BATCH_SIZE;
-        // Handle cursor for large result sets
-        if (documents.length > effectiveBatchSize) {
-            const cursorId = this._nextCursorId++;
-            this._cursors.set(cursorId, {
-                id: cursorId,
-                namespace: `${dbName}.${collection}`,
-                documents,
-                position: effectiveBatchSize,
-                batchSize: effectiveBatchSize,
-                createdAt: Date.now(),
-            });
-            return {
-                documents: documents.slice(0, effectiveBatchSize),
-                cursorId,
-                hasMore: true,
-            };
-        }
-        return { documents, cursorId: 0n, hasMore: false };
-    }
-    // ===========================================================================
-    // CRUD Operations - Write (Read-Only Errors)
-    // ===========================================================================
-    async insertOne(_db, _collection, _doc) {
-        throw new ReadOnlyOperationError('insertOne');
-    }
-    async insertMany(_db, _collection, _docs) {
-        throw new ReadOnlyOperationError('insertMany');
-    }
-    async updateOne(_db, _collection, _filter, _update, _options) {
-        throw new ReadOnlyOperationError('updateOne');
-    }
-    async updateMany(_db, _collection, _filter, _update, _options) {
-        throw new ReadOnlyOperationError('updateMany');
-    }
-    async deleteOne(_db, _collection, _filter) {
-        throw new ReadOnlyOperationError('deleteOne');
-    }
-    async deleteMany(_db, _collection, _filter) {
-        throw new ReadOnlyOperationError('deleteMany');
-    }
-    // ===========================================================================
-    // Count & Distinct
-    // ===========================================================================
-    async count(dbName, collection, query) {
-        const tableName = `${this._escapeIdentifier(dbName)}.${this._escapeIdentifier(collection)}`;
-        let sql = `SELECT COUNT(*) as count FROM ${tableName}`;
-        const params = [];
-        if (query && Object.keys(query).length > 0) {
-            const whereClause = this._translateFilter(query, params);
-            if (whereClause && whereClause !== '1 = 1') {
-                sql += ` WHERE ${whereClause}`;
-            }
-        }
-        const result = await this._executeQueryWithParams(sql, params);
-        return result.rows[0]?.count ?? 0;
-    }
-    async distinct(dbName, collection, field, query) {
-        const tableName = `${this._escapeIdentifier(dbName)}.${this._escapeIdentifier(collection)}`;
-        let sql = `SELECT DISTINCT ${field} FROM ${tableName}`;
-        const params = [];
-        if (query && Object.keys(query).length > 0) {
-            const whereClause = this._translateFilter(query, params);
-            if (whereClause && whereClause !== '1 = 1') {
-                sql += ` WHERE ${whereClause}`;
-            }
-        }
-        const result = await this._executeQueryWithParams(sql, params);
-        return result.rows.map((row) => row[field]);
-    }
-    // ===========================================================================
-    // Aggregation
-    // ===========================================================================
-    async aggregate(dbName, collection, pipeline, options) {
-        const tableName = `${this._escapeIdentifier(dbName)}.${this._escapeIdentifier(collection)}`;
-        // Build URL with SETTINGS for query optimization
-        let url = this._buildBaseUrl();
-        if (options?.allowDiskUse) {
-            // Use URL-based SETTINGS for disk-based operations
-            // ClickHouse accepts settings as query params: &max_bytes_before_external_group_by=N
-            // Adding SETTINGS indicator for query optimization
-            url += '&SETTINGS_enabled=1&max_bytes_before_external_group_by=10000000000';
-        }
-        // Translate pipeline to ClickHouse SQL directly
-        const { sql, params, facets } = this._translatePipeline(tableName, pipeline);
-        // Handle facet results separately
-        if (facets) {
-            // For facets, we need to execute multiple queries
-            const facetResults = {};
-            for (const [facetName, facetPipeline] of Object.entries(facets)) {
-                try {
-                    const { sql: facetSql, params: facetParams } = this._translatePipeline(tableName, facetPipeline);
-                    const facetResult = await this._executeQueryWithParams(facetSql, facetParams, url);
-                    facetResults[facetName] = this._mapResults(facetResult.rows, facetResult.meta);
-                }
-                catch (error) {
-                    // If a facet query fails, return empty array for that facet
-                    facetResults[facetName] = [];
-                }
-            }
-            return {
-                documents: [facetResults],
-                cursorId: 0n,
-                hasMore: false,
-            };
-        }
-        // Execute the translated SQL
-        const result = await this._executeQueryWithParams(sql, params, url);
-        const documents = this._mapResults(result.rows, result.meta);
-        const effectiveBatchSize = options?.batchSize || DEFAULT_BATCH_SIZE;
-        if (documents.length > effectiveBatchSize) {
-            const cursorId = this._nextCursorId++;
-            this._cursors.set(cursorId, {
-                id: cursorId,
-                namespace: `${dbName}.${collection}`,
-                documents,
-                position: effectiveBatchSize,
-                batchSize: effectiveBatchSize,
-                createdAt: Date.now(),
-            });
-            return {
-                documents: documents.slice(0, effectiveBatchSize),
-                cursorId,
-                hasMore: true,
-            };
-        }
-        return { documents, cursorId: 0n, hasMore: false };
-    }
-    /**
-     * Translate MongoDB aggregation pipeline to ClickHouse SQL
-     */
-    _translatePipeline(tableName, pipeline) {
-        const params = [];
-        let selectClause = '*';
-        let whereClause = '';
-        let groupByClause = '';
-        let orderByClause = '';
-        let limitClause = '';
-        let offsetClause = '';
-        let facets;
-        for (const stage of pipeline) {
-            const stageType = Object.keys(stage)[0];
-            if (!stageType)
-                continue;
-            const stageValue = stage[stageType];
-            switch (stageType) {
-                case '$match': {
-                    const matchFilter = this._translateFilter(stageValue, params);
-                    if (matchFilter) {
-                        whereClause = whereClause ? `(${whereClause}) AND (${matchFilter})` : matchFilter;
-                    }
-                    break;
-                }
-                case '$project': {
-                    const projSpec = stageValue;
-                    const projFields = [];
-                    for (const [field, value] of Object.entries(projSpec)) {
-                        if (value === 1 || value === true) {
-                            projFields.push(field);
-                        }
-                        else if (typeof value === 'object' && value !== null) {
-                            // Handle expressions like { $concat: [...] }
-                            const expr = this._translateExpression(value, params);
-                            projFields.push(`${expr} AS ${field}`);
-                        }
-                    }
-                    if (projFields.length > 0) {
-                        selectClause = projFields.join(', ');
-                    }
-                    break;
-                }
-                case '$group': {
-                    const groupSpec = stageValue;
-                    const groupId = groupSpec._id;
-                    const groupFields = [];
-                    const groupByCols = [];
-                    // Handle _id (GROUP BY)
-                    if (groupId === null) {
-                        groupFields.push('NULL AS _id');
-                    }
-                    else if (typeof groupId === 'string' && groupId.startsWith('$')) {
-                        const fieldName = groupId.slice(1);
-                        groupFields.push(`${fieldName} AS _id`);
-                        groupByCols.push(fieldName);
-                    }
-                    else if (typeof groupId === 'object' && groupId !== null) {
-                        // Complex group key like { $dateToString: { format: ..., date: ... } }
-                        const expr = this._translateExpression(groupId, params);
-                        groupFields.push(`${expr} AS _id`);
-                        groupByCols.push(expr);
-                    }
-                    // Handle accumulators
-                    for (const [field, accum] of Object.entries(groupSpec)) {
-                        if (field === '_id')
-                            continue;
-                        if (typeof accum === 'object' && accum !== null) {
-                            const accumExpr = this._translateAccumulator(accum, params);
-                            groupFields.push(`${accumExpr} AS ${field}`);
-                        }
-                    }
-                    selectClause = groupFields.join(', ');
-                    if (groupByCols.length > 0) {
-                        groupByClause = groupByCols.join(', ');
-                    }
-                    break;
-                }
-                case '$sort': {
-                    const sortSpec = stageValue;
-                    const sortParts = [];
-                    for (const [field, direction] of Object.entries(sortSpec)) {
-                        const dir = direction === -1 ? 'DESC' : 'ASC';
-                        sortParts.push(`${field} ${dir}`);
-                    }
-                    orderByClause = sortParts.join(', ');
-                    break;
-                }
-                case '$limit':
-                    limitClause = `LIMIT ${stageValue}`;
-                    break;
-                case '$skip':
-                    offsetClause = `OFFSET ${stageValue}`;
-                    break;
-                case '$count':
-                    selectClause = `COUNT(*) AS ${stageValue}`;
-                    break;
-                case '$addFields':
-                case '$set': {
-                    const addSpec = stageValue;
-                    const addFields = ['*'];
-                    for (const [field, value] of Object.entries(addSpec)) {
-                        if (typeof value === 'object' && value !== null) {
-                            const expr = this._translateExpression(value, params);
-                            addFields.push(`${expr} AS ${field}`);
-                        }
-                    }
-                    selectClause = addFields.join(', ');
-                    break;
-                }
-                case '$unwind': {
-                    const unwindPath = typeof stageValue === 'string'
-                        ? stageValue.replace(/^\$/, '')
-                        : stageValue.path.replace(/^\$/, '');
-                    // ClickHouse ARRAY JOIN syntax
-                    selectClause = `*, arrayJoin(${unwindPath}) AS ${unwindPath}`;
-                    break;
-                }
-                case '$lookup': {
-                    const lookupSpec = stageValue;
-                    // The lookup needs to be handled as a JOIN - we'll modify the table source
-                    // For now, generate a subquery with LEFT JOIN
-                    const joinClause = ` LEFT JOIN ${lookupSpec.from} ON ${tableName}.${lookupSpec.localField} = ${lookupSpec.from}.${lookupSpec.foreignField}`;
-                    selectClause = `${tableName}.*, groupArray(${lookupSpec.from}.*) AS ${lookupSpec.as}`;
-                    // Store the join in whereClause temporarily as we'll need to append it to FROM
-                    // This is a simplification - real implementation would handle this differently
-                    whereClause = whereClause ? whereClause + joinClause : '';
-                    // Actually, let's just embed the JOIN in a special way
-                    // We'll return a modified SQL that includes the JOIN
-                    const joinedTable = `${tableName}${joinClause}`;
-                    const joinSql = `SELECT ${selectClause} FROM ${joinedTable}`;
-                    const result = {
-                        sql: joinSql + (whereClause ? ` WHERE ${whereClause}` : ''),
-                        params,
-                    };
-                    if (facets) {
-                        result.facets = facets;
-                    }
-                    return result;
-                }
-                case '$facet': {
-                    facets = stageValue;
-                    break;
-                }
-            }
-        }
-        // Build final SQL
-        let sql = `SELECT ${selectClause} FROM ${tableName}`;
-        if (whereClause)
-            sql += ` WHERE ${whereClause}`;
-        if (groupByClause)
-            sql += ` GROUP BY ${groupByClause}`;
-        if (orderByClause)
-            sql += ` ORDER BY ${orderByClause}`;
-        if (limitClause)
-            sql += ` ${limitClause}`;
-        if (offsetClause)
-            sql += ` ${offsetClause}`;
-        const result = { sql, params };
-        if (facets) {
-            result.facets = facets;
-        }
-        return result;
-    }
-    /**
-     * Translate MongoDB expression to ClickHouse SQL
-     */
-    _translateExpression(expr, params) {
-        const op = Object.keys(expr)[0];
-        if (!op)
-            return '';
-        const value = expr[op];
-        switch (op) {
-            case '$concat': {
-                const parts = value.map((v) => {
-                    if (typeof v === 'string' && v.startsWith('$')) {
-                        return v.slice(1);
-                    }
-                    if (typeof v === 'string') {
-                        params.push(v);
-                        return '?';
-                    }
-                    return String(v);
-                });
-                return `concat(${parts.join(', ')})`;
-            }
-            case '$year':
-                return `toYear(${this._translateFieldRef(value)})`;
-            case '$month':
-                return `toMonth(${this._translateFieldRef(value)})`;
-            case '$dayOfMonth':
-                return `toDayOfMonth(${this._translateFieldRef(value)})`;
-            case '$dateToString': {
-                const spec = value;
-                const dateField = this._translateFieldRef(spec.date);
-                const format = spec.format.replace('%Y', '%Y').replace('%m', '%m').replace('%d', '%d');
-                return `formatDateTime(${dateField}, '${format}')`;
-            }
-            case '$add':
-            case '$subtract':
-            case '$multiply':
-            case '$divide': {
-                const [left, right] = value;
-                const leftExpr = this._translateFieldRef(left);
-                const rightExpr = this._translateFieldRef(right);
-                const opMap = {
-                    $add: '+',
-                    $subtract: '-',
-                    $multiply: '*',
-                    $divide: '/',
-                };
-                return `(${leftExpr} ${opMap[op]} ${rightExpr})`;
-            }
-            default:
-                // For unknown expressions, try to return field reference
-                if (typeof value === 'string' && value.startsWith('$')) {
-                    return value.slice(1);
-                }
-                return String(value);
-        }
-    }
-    /**
-     * Translate MongoDB accumulator to ClickHouse SQL
-     */
-    _translateAccumulator(accum, _params) {
-        const op = Object.keys(accum)[0];
-        if (!op)
-            return '';
-        const value = accum[op];
-        switch (op) {
-            case '$sum':
-                if (value === 1) {
-                    return 'COUNT(*)';
-                }
-                return `SUM(${this._translateFieldRef(value)})`;
-            case '$avg':
-                return `AVG(${this._translateFieldRef(value)})`;
-            case '$min':
-                return `MIN(${this._translateFieldRef(value)})`;
-            case '$max':
-                return `MAX(${this._translateFieldRef(value)})`;
-            case '$first':
-                return `any(${this._translateFieldRef(value)})`;
-            case '$last':
-                return `anyLast(${this._translateFieldRef(value)})`;
-            case '$push':
-                return `groupArray(${this._translateFieldRef(value)})`;
-            case '$addToSet':
-                return `groupUniqArray(${this._translateFieldRef(value)})`;
-            default:
-                return String(value);
-        }
-    }
-    /**
-     * Translate a field reference ($field) to column name
-     */
-    _translateFieldRef(value) {
-        if (typeof value === 'string' && value.startsWith('$')) {
-            return value.slice(1);
-        }
-        if (typeof value === 'number') {
-            return String(value);
-        }
-        return String(value);
-    }
-    // ===========================================================================
-    // Index Operations (Read-Only)
-    // ===========================================================================
-    async listIndexes(dbName, collection) {
-        const sql = `
-      SELECT
-        name,
-        type,
-        expr
-      FROM system.data_skipping_indices
-      WHERE database = '${this._escapeString(dbName)}'
-        AND table = '${this._escapeString(collection)}'
-    `;
-        const result = await this._executeQuery(sql);
-        // Always include the primary key "index"
-        const indexes = [{ v: 2, key: { _id: 1 }, name: '_id_' }];
-        for (const row of result.rows) {
-            indexes.push({
-                v: 2,
-                key: { [row.expr]: 1 },
-                name: row.name,
-            });
-        }
-        return indexes;
-    }
-    async createIndexes(_db, _collection, _indexes) {
-        throw new ReadOnlyOperationError('createIndexes');
-    }
-    async dropIndex(_db, _collection, _indexName) {
-        throw new ReadOnlyOperationError('dropIndex');
-    }
-    async dropIndexes(_db, _collection) {
-        throw new ReadOnlyOperationError('dropIndexes');
-    }
-    // ===========================================================================
-    // Cursor Management
-    // ===========================================================================
-    createCursor(state) {
-        this._cursors.set(state.id, state);
-    }
-    getCursor(id) {
-        return this._cursors.get(id);
-    }
-    advanceCursor(id, count) {
-        const cursor = this._cursors.get(id);
-        if (!cursor) {
-            return [];
-        }
-        const start = cursor.position;
-        const end = Math.min(start + count, cursor.documents.length);
-        cursor.position = end;
-        return cursor.documents.slice(start, end);
-    }
-    closeCursor(id) {
-        return this._cursors.delete(id);
-    }
-    cleanupExpiredCursors() {
-        const now = Date.now();
-        for (const [id, cursor] of this._cursors) {
-            if (now - cursor.createdAt > CURSOR_TIMEOUT_MS) {
-                this._cursors.delete(id);
-            }
-        }
-    }
-    // ===========================================================================
-    // Private Helper Methods
-    // ===========================================================================
-    /**
-     * Build the base URL for ClickHouse HTTP API
-     */
-    _buildBaseUrl() {
-        const protocol = this._config.secure ? 'https' : 'http';
-        const port = this._config.port || (this._config.secure ? 8443 : 8123);
-        let url = `${protocol}://${this._config.host}:${port}/?`;
-        url += `database=${encodeURIComponent(this._config.database)}`;
-        url += '&default_format=JSON';
-        if (this._config.username) {
-            url += `&user=${encodeURIComponent(this._config.username)}`;
-        }
-        if (this._config.password) {
-            url += `&password=${encodeURIComponent(this._config.password)}`;
-        }
-        // Set timeout
-        if (this._config.queryTimeout) {
-            const timeoutSeconds = Math.floor(this._config.queryTimeout / 1000);
-            url += `&max_execution_time=${timeoutSeconds}`;
-        }
-        return url;
-    }
-    /**
-     * Execute a simple query
-     */
-    async _executeQuery(sql) {
-        return this._executor.execute(sql);
-    }
-    /**
-     * Execute a query with parameters
-     */
-    async _executeQueryWithParams(sql, params, customUrl) {
-        // Replace ? placeholders with actual values
-        let processedSql = sql;
-        for (const param of params) {
-            processedSql = processedSql.replace('?', this._formatParam(param));
-        }
-        if (customUrl) {
-            // Use custom URL with settings
-            let response;
-            try {
-                response = await fetch(customUrl, {
-                    method: 'POST',
-                    headers: {
-                        'Content-Type': 'text/plain',
-                        ...this._customHeaders,
-                    },
-                    body: processedSql,
-                });
-            }
-            catch (error) {
-                // Handle network errors (fetch throws)
-                const message = error instanceof Error ? error.message : 'Network error';
-                throw new Error(`Failed to fetch: ${message}`);
-            }
-            if (!response || !response.ok) {
-                const errorText = response ? await response.text() : 'No response';
-                throw new ClickHouseError(errorText, response?.status ?? 0);
-            }
-            const json = await response.json();
-            return {
-                rows: json.data || [],
-                meta: json.meta || [],
-                statistics: {
-                    elapsed: json.statistics?.elapsed || 0,
-                    rowsRead: json.statistics?.rows_read || 0,
-                    bytesRead: json.statistics?.bytes_read || 0,
-                },
-            };
-        }
-        return this._executor.execute(processedSql);
-    }
-    /**
-     * Format a parameter value for SQL
-     */
-    _formatParam(value) {
-        if (value === null || value === undefined) {
-            return 'NULL';
-        }
-        if (typeof value === 'string') {
-            return `'${this._escapeString(value)}'`;
-        }
-        if (typeof value === 'number') {
-            return String(value);
-        }
-        if (typeof value === 'boolean') {
-            return value ? '1' : '0';
-        }
-        if (value instanceof ObjectId) {
-            return `'${value.toHexString()}'`;
-        }
-        if (Array.isArray(value)) {
-            return `[${value.map((v) => this._formatParam(v)).join(', ')}]`;
-        }
-        return `'${this._escapeString(JSON.stringify(value))}'`;
-    }
-    /**
-     * Escape a string for SQL
-     */
-    _escapeString(str) {
-        return str.replace(/'/g, "''");
-    }
-    /**
-     * Escape an identifier (table/column name)
-     */
-    _escapeIdentifier(name) {
-        // ClickHouse uses backticks for identifiers with special characters
-        if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) {
-            return name;
-        }
-        return `\`${name.replace(/`/g, '``')}\``;
-    }
-    /**
-     * Build projection SQL
-     */
-    _buildProjection(projection) {
-        const include = [];
-        const exclude = [];
-        for (const [field, value] of Object.entries(projection)) {
-            if (value === 1 || value === true) {
-                include.push(field);
-            }
-            else if (value === 0 || value === false) {
-                exclude.push(field);
-            }
-        }
-        if (include.length > 0) {
-            return include.join(', ');
-        }
-        // Exclusion mode - would need schema info for ClickHouse
-        // For now, just select all and filter in mapper
-        return '*';
-    }
-    /**
-     * Translate MongoDB filter to ClickHouse SQL WHERE clause
-     */
-    _translateFilter(filter, params) {
-        const conditions = [];
-        for (const [key, value] of Object.entries(filter)) {
-            if (key === '$and' && Array.isArray(value)) {
-                const subConditions = value
-                    .map((sub) => {
-                    const cond = this._translateFilter(sub, params);
-                    return cond ? `(${cond})` : '';
-                })
-                    .filter(Boolean);
-                if (subConditions.length > 0) {
-                    conditions.push(`${subConditions.join(' AND ')}`);
-                }
-            }
-            else if (key === '$or' && Array.isArray(value)) {
-                const subConditions = value
-                    .map((sub) => {
-                    const cond = this._translateFilter(sub, params);
-                    return cond ? `(${cond})` : '';
-                })
-                    .filter(Boolean);
-                if (subConditions.length > 0) {
-                    conditions.push(`${subConditions.join(' OR ')}`);
-                }
-            }
-            else if (value instanceof ObjectId) {
-                // ObjectId comparison - handle before object check
-                params.push(value.toHexString());
-                conditions.push(`${key} = ?`);
-            }
-            else if (typeof value === 'object' && value !== null && !Array.isArray(value)) {
-                // Handle operators
-                for (const [op, opValue] of Object.entries(value)) {
-                    const fieldExpr = this._buildFieldExpression(key);
-                    switch (op) {
-                        case '$eq':
-                            if (opValue === null) {
-                                conditions.push(`${fieldExpr} IS NULL`);
-                            }
-                            else {
-                                params.push(opValue);
-                                conditions.push(`${fieldExpr} = ?`);
-                            }
-                            break;
-                        case '$ne':
-                            if (opValue === null) {
-                                conditions.push(`${fieldExpr} IS NOT NULL`);
-                            }
-                            else {
-                                params.push(opValue);
-                                conditions.push(`${fieldExpr} != ?`);
-                            }
-                            break;
-                        case '$gt':
-                            params.push(opValue);
-                            conditions.push(`${fieldExpr} > ?`);
-                            break;
-                        case '$gte':
-                            params.push(opValue);
-                            conditions.push(`${fieldExpr} >= ?`);
-                            break;
-                        case '$lt':
-                            params.push(opValue);
-                            conditions.push(`${fieldExpr} < ?`);
-                            break;
-                        case '$lte':
-                            params.push(opValue);
-                            conditions.push(`${fieldExpr} <= ?`);
-                            break;
-                        case '$in':
-                            if (Array.isArray(opValue) && opValue.length > 0) {
-                                const placeholders = opValue.map(() => '?').join(', ');
-                                params.push(...opValue);
-                                conditions.push(`${fieldExpr} IN (${placeholders})`);
-                            }
-                            break;
-                        case '$nin':
-                            if (Array.isArray(opValue) && opValue.length > 0) {
-                                const placeholders = opValue.map(() => '?').join(', ');
-                                params.push(...opValue);
-                                conditions.push(`${fieldExpr} NOT IN (${placeholders})`);
-                            }
-                            break;
-                        case '$exists':
-                            if (opValue) {
-                                conditions.push(`${fieldExpr} IS NOT NULL`);
-                            }
-                            else {
-                                conditions.push(`${fieldExpr} IS NULL`);
-                            }
-                            break;
-                        case '$elemMatch':
-                            // For $elemMatch on arrays, use has() or arrayExists()
-                            if (typeof opValue === 'object' && opValue !== null) {
-                                const elemMatchCond = this._translateElemMatch(key, opValue, params);
-                                if (elemMatchCond) {
-                                    conditions.push(elemMatchCond);
-                                }
-                            }
-                            break;
-                    }
-                }
-            }
-            else if (value === null) {
-                conditions.push(`${key} IS NULL`);
-            }
-            else {
-                // Direct equality
-                params.push(value);
-                conditions.push(`${key} = ?`);
-            }
-        }
-        return conditions.join(' AND ');
-    }
-    /**
-     * Build field expression for nested fields
-     */
-    _buildFieldExpression(field) {
-        if (field.includes('.')) {
-            // Nested field - use JSONExtractString
-            const parts = field.split('.');
-            const column = parts[0];
-            const path = parts.slice(1).map((p) => `'${p}'`).join(', ');
-            return `JSONExtractString(${column}, ${path})`;
-        }
-        return field;
-    }
-    /**
-     * Translate $elemMatch operator
-     */
-    _translateElemMatch(field, conditions, params) {
-        // For simple $eq in elemMatch, use has()
-        if (Object.keys(conditions).length === 1 && '$eq' in conditions) {
-            params.push(conditions.$eq);
-            return `has(${field}, ?)`;
-        }
-        // For more complex conditions, use arrayExists
-        const innerConditions = [];
-        for (const [key, value] of Object.entries(conditions)) {
-            if (key === '$eq') {
-                params.push(value);
-                innerConditions.push(`x = ?`);
-            }
-            else if (key === '$gt') {
-                params.push(value);
-                innerConditions.push(`x > ?`);
-            }
-            else if (key === '$gte') {
-                params.push(value);
-                innerConditions.push(`x >= ?`);
-            }
-            else if (key === '$lt') {
-                params.push(value);
-                innerConditions.push(`x < ?`);
-            }
-            else if (key === '$lte') {
-                params.push(value);
-                innerConditions.push(`x <= ?`);
-            }
-        }
-        if (innerConditions.length > 0) {
-            return `arrayExists(x -> ${innerConditions.join(' AND ')}, ${field})`;
-        }
-        return '';
-    }
-    /**
-     * Map ClickHouse results to BSON documents
-     */
-    _mapResults(rows, meta) {
-        // If meta is empty or not provided, return rows as-is (preserving types)
-        if (!meta || meta.length === 0) {
-            return rows.map((row) => ({ ...row }));
-        }
-        return rows.map((row) => this._mapper.map(row, meta));
-    }
-}
-// =============================================================================
-// Factory Function
-// =============================================================================
-/**
- * Create a ClickHouse OLAP backend instance
- *
- * Validates connection before returning the backend.
- */
-export async function createClickHouseOLAPBackend(config) {
-    // Create executor with config
-    const executorConfig = {
-        host: config.host,
-        database: config.database,
-    };
-    if (config.port !== undefined)
-        executorConfig.port = config.port;
-    if (config.username !== undefined)
-        executorConfig.username = config.username;
-    if (config.password !== undefined)
-        executorConfig.password = config.password;
-    if (config.secure !== undefined)
-        executorConfig.secure = config.secure;
-    if (config.queryTimeout !== undefined)
-        executorConfig.queryTimeout = config.queryTimeout;
-    const executor = createQueryExecutor(executorConfig);
-    // Build URL for connection test
-    const protocol = config.secure ? 'https' : 'http';
-    const port = config.port || (config.secure ? 8443 : 8123);
-    let url = `${protocol}://${config.host}:${port}/?`;
-    url += `database=${encodeURIComponent(config.database)}`;
-    url += '&default_format=JSON';
-    if (config.username) {
-        url += `&user=${encodeURIComponent(config.username)}`;
-    }
-    if (config.password) {
-        url += `&password=${encodeURIComponent(config.password)}`;
-    }
-    // Verify connection
-    const headers = {
-        'Content-Type': 'text/plain',
-        ...(config.headers || {}),
-    };
-    const response = await fetch(url, {
-        method: 'POST',
-        headers,
-        body: 'SELECT version()',
-    });
-    if (!response.ok) {
-        const errorText = await response.text();
-        let errorMessage = errorText;
-        try {
-            const errorJson = JSON.parse(errorText);
-            errorMessage = errorJson.exception || errorText;
-        }
-        catch {
-            // Use raw text
-        }
-        throw new Error(errorMessage);
-    }
-    return new ClickHouseOLAPBackend(config, executor);
-}
-//# sourceMappingURL=olap-backend.js.map