Merge pull request #6350 from Countly/uj/arch-distill

fix docs for new changes in Query runner class

Author: kanwarujjaval

QueryRunner-Usage-Guide.md

@@ -18,6 +18,23 @@ API Request → QueryRunner → [MongoDB|ClickHouse|Future Adapters]
 
 ## Query Definition Structure
 
+```typescript
+interface QueryDefinition<TParams = unknown, TResult = unknown> {
+    name: string;           // Unique identifier for logging/debugging
+    adapters: {
+        mongodb?: AdapterConfig<TParams, TResult>;
+        clickhouse?: AdapterConfig<TParams, TResult>;
+    };
+}
+
+interface AdapterConfig<TParams = unknown, TResult = unknown> {
+    handler: QueryHandler<TParams, TResult>;
+    transform?: TransformFunction<TResult>;
+    available?: boolean;    // Optional, defaults to true
+}
+```
+
+**Example implementation:**
 ```javascript
 const queryDef = {
     name: 'QUERY_NAME',           // Unique identifier for logging/debugging
@@ -33,9 +50,8 @@ const queryDef = {
 
                 return {
                     _queryMeta: { 
-                        type: 'mongodb', 
-                        query: pipeline,
-                        collection: 'events'    // Optional: additional metadata
+                        adapter: 'mongodb',     // Required: adapter name
+                        query: pipeline         // Required: actual executed query
                     },
                     data: result
                 };
@@ -54,15 +70,16 @@ const queryDef = {
 
                 return {
                     _queryMeta: { 
-                        type: 'clickhouse', 
-                        query: sql
+                        adapter: 'clickhouse',  // Required: adapter name
+                        query: sql              // Required: actual executed query
                     },
                     data: result.data
                 };
             },
-            transform: async (result, transformOptions) => {
+            transform: async (data, transformOptions) => {
                 // Transform ClickHouse results to match expected format
-                return result.data.map(row => ({
+                // Note: transform receives only the data portion, not full result
+                return data.map(row => ({
                     total: parseInt(row.total) || 0
                 }));
             },
@@ -74,18 +91,34 @@ const queryDef = {
 
 ### Handler Requirements
 
+**TypeScript Signature:**
+```typescript
+type QueryHandler<TParams = unknown, TResult = unknown> = (
+    params: TParams,
+    options?: ExecutionOptions
+) => Promise<QueryResult<TResult>>;
+
+interface QueryResult<TData = unknown> {
+    _queryMeta: QueryMeta;
+    data: TData;
+}
+
+interface QueryMeta {
+    adapter: AdapterName;    // 'mongodb' | 'clickhouse'
+    query: unknown;          // The actual query/pipeline executed
+}
+```
+
 **Input Parameters:**
 - `params`: Query-specific parameters (app_id, date ranges, filters, etc.)
-- `options` *(optional)*: Execution options (timeout, connection settings, etc.)
+- `options` *(optional)*: ExecutionOptions (adapter, comparison mode, etc.)
 
 **Required Output Structure:** 
 ```javascript
 {
     _queryMeta: {
-        type: 'mongodb' | 'clickhouse',      // Adapter type
-        query: actualQuery,                  // Executed query (pipeline/SQL) for debugging
-        collection?: string,                 // Optional: MongoDB collection name
-        // Add any other optional metadata fields as needed
+        adapter: 'mongodb' | 'clickhouse',   // Required: adapter name
+        query: actualQuery                   // Required: executed query for debugging
     },
     data: queryResults                       // Raw query results
 }
@@ -96,9 +129,17 @@ const queryDef = {
 Each adapter can optionally define a transform function to normalize or process results:
 
 **Transform Function Signature:**
+```typescript
+type TransformFunction<TInput = unknown, TOutput = unknown> = (
+    data: TInput,
+    transformOptions?: Record<string, unknown>
+) => Promise<TOutput>;
+```
+
+**Implementation:**
 ```javascript
-transform: async (result, transformOptions) => {
-    // result: Full handler result with _queryMeta and data
+transform: async (data, transformOptions) => {
+    // data: Only the data portion from handler result (not full QueryResult)
     // transformOptions: Configuration object passed from executeQuery
     return transformedData;
 }
@@ -109,12 +150,14 @@ transform: async (result, transformOptions) => {
 - Transform functions should be lightweight and focused
 - Handle data type differences (e.g., string to number conversion)
 - MongoDB adapters often don't need transforms if data is already normalized
+- Transform receives only the `data` portion, not the full `QueryResult` object
 
 #### Handler Best Practices
-- Always include `_queryMeta` with actual executed query for debugging
+- Always include `_queryMeta` with `adapter` name and actual executed `query` for debugging
 - Return consistent data structure across adapters when possible
 - Handle errors gracefully and let them bubble up
-- Use `options` parameter for adapter-specific settings
+- Use `options` parameter for execution-related settings (not adapter-specific configs)
+- Follow TypeScript interfaces for type safety
 
 ## Comparison Mode
 
@@ -140,25 +183,53 @@ const result = await queryRunner.executeQuery(queryDef, params, { comparison: tr
 const QueryRunner = require('./api/parts/data/QueryRunner.js');
 common.queryRunner = new QueryRunner();
 
-// Normal execution
+// Normal execution - returns only transformed data, not full QueryResult
 const result = await common.queryRunner.executeQuery(queryDef, params);
 
 // Force specific adapter
 const result = await common.queryRunner.executeQuery(queryDef, params, { adapter: 'clickhouse' });
 
-// Comparison mode
+// Comparison mode - logs detailed comparison data to files
 const result = await common.queryRunner.executeQuery(queryDef, params, { comparison: true });
 
 // With transform options
 const transformOptions = { dateFormat: 'ISO', includeMetadata: true };
 const result = await common.queryRunner.executeQuery(queryDef, params, {}, transformOptions);
 ```
 
+### TypeScript Usage
+
+```typescript
+import QueryRunner, { QueryDefinition, ExecutionOptions } from './types/QueryRunner';
+
+// Type-safe query definition
+const queryDef: QueryDefinition<{app_id: string}, {total: number}[]> = {
+    name: 'GET_EVENT_TOTALS',
+    adapters: {
+        mongodb: {
+            handler: async (params, options) => {
+                // Implementation with type safety
+                return {
+                    _queryMeta: { adapter: 'mongodb', query: pipeline },
+                    data: results
+                };
+            }
+        }
+    }
+};
+
+// Type-safe execution
+const result: {total: number}[] = await queryRunner.executeQuery(queryDef, { app_id: 'test' });
+```
+
 ## Best Practices
 
-1. Always implement `_queryMeta` for debugging
-2. Use adapter-specific transforms only when data formats differ between adapters
+1. Always implement `_queryMeta` with correct `adapter` name and `query` fields
+2. Use adapter-specific transforms only when data formats differ between adapters  
 3. Keep transform functions lightweight and focused on format normalization
 4. Test with comparison mode during development to validate adapter consistency
 5. Monitor debug timing logs for performance issues
-6. Prefer normalizing data in handlers over complex transforms when possible
+6. Prefer normalizing data in handlers over complex transforms when possible
+7. Use TypeScript definitions for type safety and better IDE support
+8. Remember that `executeQuery` returns only the transformed data, not the full `QueryResult`
+9. Transform functions receive only the `data` portion, not the complete handler result