mongo.do 0.1.0

package/dist/olap/clickhouse/olap-backend.d.ts

@@ -0,0 +1,181 @@
+/**
+ * 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 type { Document } from 'bson';
+import { ClickHouseQueryExecutor } from './query-executor';
+import type { MondoBackend, DatabaseInfo, CollectionInfo, FindOptions, FindResult, InsertResult, UpdateResult, DeleteResult, AggregateResult, CollStats, DbStats, IndexInfo, IndexSpec, CursorState } from '../../wire/backend/interface';
+/**
+ * ClickHouse OLAP Backend configuration
+ */
+export interface ClickHouseOLAPConfig {
+    /** ClickHouse host */
+    host: string;
+    /** ClickHouse port (default: 8123 or 8443 for secure) */
+    port?: number;
+    /** Default database name */
+    database: string;
+    /** Username for authentication */
+    username?: string;
+    /** Password for authentication */
+    password?: string;
+    /** Use HTTPS */
+    secure?: boolean;
+    /** Custom HTTP headers */
+    headers?: Record<string, string>;
+    /** Use FINAL modifier for ReplacingMergeTree tables */
+    useFinal?: boolean;
+    /** Query timeout in milliseconds */
+    queryTimeout?: number;
+    /** Default result limit (safety limit) */
+    defaultLimit?: number;
+}
+/**
+ * Cursor interface for OLAP results
+ */
+export interface ClickHouseOLAPCursor {
+    /** All documents from the query */
+    documents: Document[];
+    /** Current position in results */
+    position: number;
+    /** Batch size for iteration */
+    batchSize: number;
+    /** Creation timestamp */
+    createdAt: number;
+}
+/**
+ * Error thrown when attempting write operations on read-only OLAP backend
+ */
+export declare class ReadOnlyOperationError extends Error {
+    readonly operation: string;
+    constructor(operation: string);
+}
+/**
+ * ClickHouse OLAP Backend
+ *
+ * Implements MondoBackend interface for read-only analytical queries.
+ */
+export declare class ClickHouseOLAPBackend implements MondoBackend {
+    private _executor;
+    private _mapper;
+    private _config;
+    private _cursors;
+    private _nextCursorId;
+    private _customHeaders;
+    constructor(config: ClickHouseOLAPConfig, executor: ClickHouseQueryExecutor);
+    listDatabases(): Promise<DatabaseInfo[]>;
+    createDatabase(_name: string): Promise<void>;
+    dropDatabase(_name: string): Promise<void>;
+    databaseExists(name: string): Promise<boolean>;
+    listCollections(dbName: string, filter?: Document): Promise<CollectionInfo[]>;
+    createCollection(_db: string, _name: string, _options?: Document): Promise<void>;
+    dropCollection(_db: string, _name: string): Promise<void>;
+    collectionExists(dbName: string, name: string): Promise<boolean>;
+    collStats(dbName: string, collection: string): Promise<CollStats>;
+    dbStats(dbName: string): Promise<DbStats>;
+    find(dbName: string, collection: string, options: FindOptions): Promise<FindResult>;
+    insertOne(_db: string, _collection: string, _doc: Document): Promise<InsertResult>;
+    insertMany(_db: string, _collection: string, _docs: Document[]): Promise<InsertResult>;
+    updateOne(_db: string, _collection: string, _filter: Document, _update: Document, _options?: {
+        upsert?: boolean;
+        arrayFilters?: Document[];
+    }): Promise<UpdateResult>;
+    updateMany(_db: string, _collection: string, _filter: Document, _update: Document, _options?: {
+        upsert?: boolean;
+        arrayFilters?: Document[];
+    }): Promise<UpdateResult>;
+    deleteOne(_db: string, _collection: string, _filter: Document): Promise<DeleteResult>;
+    deleteMany(_db: string, _collection: string, _filter: Document): Promise<DeleteResult>;
+    count(dbName: string, collection: string, query?: Document): Promise<number>;
+    distinct(dbName: string, collection: string, field: string, query?: Document): Promise<unknown[]>;
+    aggregate(dbName: string, collection: string, pipeline: Document[], options?: {
+        batchSize?: number;
+        allowDiskUse?: boolean;
+    }): Promise<AggregateResult>;
+    /**
+     * Translate MongoDB aggregation pipeline to ClickHouse SQL
+     */
+    private _translatePipeline;
+    /**
+     * Translate MongoDB expression to ClickHouse SQL
+     */
+    private _translateExpression;
+    /**
+     * Translate MongoDB accumulator to ClickHouse SQL
+     */
+    private _translateAccumulator;
+    /**
+     * Translate a field reference ($field) to column name
+     */
+    private _translateFieldRef;
+    listIndexes(dbName: string, collection: string): Promise<IndexInfo[]>;
+    createIndexes(_db: string, _collection: string, _indexes: IndexSpec[]): Promise<string[]>;
+    dropIndex(_db: string, _collection: string, _indexName: string): Promise<void>;
+    dropIndexes(_db: string, _collection: string): Promise<void>;
+    createCursor(state: CursorState): void;
+    getCursor(id: bigint): CursorState | undefined;
+    advanceCursor(id: bigint, count: number): Document[];
+    closeCursor(id: bigint): boolean;
+    cleanupExpiredCursors(): void;
+    /**
+     * Build the base URL for ClickHouse HTTP API
+     */
+    private _buildBaseUrl;
+    /**
+     * Execute a simple query
+     */
+    private _executeQuery;
+    /**
+     * Execute a query with parameters
+     */
+    private _executeQueryWithParams;
+    /**
+     * Format a parameter value for SQL
+     */
+    private _formatParam;
+    /**
+     * Escape a string for SQL
+     */
+    private _escapeString;
+    /**
+     * Escape an identifier (table/column name)
+     */
+    private _escapeIdentifier;
+    /**
+     * Build projection SQL
+     */
+    private _buildProjection;
+    /**
+     * Translate MongoDB filter to ClickHouse SQL WHERE clause
+     */
+    private _translateFilter;
+    /**
+     * Build field expression for nested fields
+     */
+    private _buildFieldExpression;
+    /**
+     * Translate $elemMatch operator
+     */
+    private _translateElemMatch;
+    /**
+     * Map ClickHouse results to BSON documents
+     */
+    private _mapResults;
+}
+/**
+ * Create a ClickHouse OLAP backend instance
+ *
+ * Validates connection before returning the backend.
+ */
+export declare function createClickHouseOLAPBackend(config: ClickHouseOLAPConfig): Promise<ClickHouseOLAPBackend>;
+//# sourceMappingURL=olap-backend.d.ts.map

package/dist/olap/clickhouse/olap-backend.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"olap-backend.d.ts","sourceRoot":"","sources":["../../../src/olap/clickhouse/olap-backend.ts"],"names":[],"mappings":"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"}