@simonecoelhosfo/optimizely-mcp-server/dist/analytics/intelligent-query-engine/types.d.ts

Optimizely MCP Server for AI assistants with integrated CLI tools

/**
 * Intelligent Query Engine - Core Type Definitions
 *
 * This file contains all type definitions for the Intelligent Query Engine.
 * The engine provides a universal, extensible query system that auto-discovers
 * field locations and relationships across different data models.
 */
import type { QueryIntent as EnhancedQueryIntent, FieldLocalityInfo, JoinHints, AggregationContext as EnhancedAggregationContext, DecomposedQuery } from '../robust-parser/types/enhanced-types.js';
/**
 * Core interface that all data model adapters must implement.
 * Adapters provide discovery and execution capabilities for specific data sources.
 */
export interface DataModelAdapter {
    name: string;
    version: string;
    description?: string;
    discoverEntities(): Promise<EntityDefinition[]>;
    discoverFields(entity: string): Promise<FieldDefinition[]>;
    discoverRelationships(): Promise<RelationshipMap>;
    executeNativeQuery(query: any): Promise<any[]>;
    getConnectionPool(): any;
    getCapabilities(): AdapterCapabilities;
}
/**
 * Defines what an adapter can and cannot do.
 * Used by the Query Planner to determine execution strategies.
 */
export interface AdapterCapabilities {
    supportsSQL: boolean;
    supportsJSONPath: boolean;
    supportsJSONata: boolean;
    supportsAggregations: boolean;
    supportsJoins: boolean;
    supportsTransactions: boolean;
    maxQueryComplexity: number;
    optimizedOperations: string[];
}
/**
 * Describes an entity (table, collection, etc.) in the data model.
 */
export interface EntityDefinition {
    name: string;
    type: 'table' | 'collection' | 'view' | 'virtual';
    description?: string;
    primaryKey?: string;
    estimatedRowCount?: number;
    lastModified?: Date;
    metadata?: Record<string, any>;
}
/**
 * Describes a field within an entity.
 */
export interface FieldDefinition {
    name: string;
    type: FieldType;
    nullable: boolean;
    description?: string;
    defaultValue?: any;
    metadata?: Record<string, any>;
    jsonPath?: string;
    jsonSchema?: any;
    computed?: boolean;
    computeExpression?: string;
}
/**
 * Supported field types across all data models.
 */
export type FieldType = 'string' | 'number' | 'boolean' | 'date' | 'json' | 'array' | 'object' | 'binary' | 'unknown';
/**
 * Maps entity relationships for JOIN operations.
 */
export interface RelationshipMap {
    [entityName: string]: Relationship[];
}
/**
 * Defines a relationship between entities.
 */
export interface Relationship {
    from: {
        entity: string;
        field: string;
    };
    to: {
        entity: string;
        field: string;
    };
    type: 'one-to-one' | 'one-to-many' | 'many-to-many';
    nullable: boolean;
    cascadeDelete?: boolean;
}
/**
 * Describes where a field can be found in the data model.
 */
export interface FieldLocation {
    entity: string;
    physicalLocation: {
        type: 'column' | 'json_path' | 'computed' | 'related';
        path: string;
        jsonPath?: string;
        jsonExtractFunction?: string;
        relationship?: Relationship;
        requiresJoin?: boolean;
    };
    indexed?: boolean;
    cacheable?: boolean;
    estimatedCost?: number;
}
/**
 * Universal query representation that can be executed by any adapter.
 */
export interface UniversalQuery {
    find: string;
    select?: string[];
    where?: QueryCondition[];
    groupBy?: string[];
    orderBy?: OrderByClause[];
    limit?: number;
    offset?: number;
    aggregations?: Aggregation[];
    joins?: JoinClause[];
    having?: QueryCondition[];
    hints?: ExecutionHints;
    platform?: 'web' | 'feature' | 'both';
    error?: string;
}
/**
 * Query condition representation.
 */
export interface QueryCondition {
    field: string;
    operator: ComparisonOperator;
    value: any;
    logicalOperator?: 'AND' | 'OR';
    nested?: QueryCondition[];
}
/**
 * Supported comparison operators.
 */
export type ComparisonOperator = '=' | '!=' | '<' | '>' | '<=' | '>=' | 'IN' | 'NOT IN' | 'LIKE' | 'NOT LIKE' | 'IS NULL' | 'IS NOT NULL' | 'BETWEEN' | 'CONTAINS' | 'STARTS WITH' | 'ENDS WITH' | 'YEAR' | 'MONTH' | 'DAY' | 'LAST_N_DAYS';
/**
 * Order by clause.
 */
export interface OrderByClause {
    field: string;
    direction: 'ASC' | 'DESC';
    nullsFirst?: boolean;
}
/**
 * Aggregation definition.
 */
export interface Aggregation {
    field: string;
    function: AggregationFunction;
    alias: string;
}
/**
 * Supported aggregation functions.
 */
export type AggregationFunction = 'COUNT' | 'SUM' | 'AVG' | 'MIN' | 'MAX' | 'COUNT DISTINCT' | 'GROUP_CONCAT';
/**
 * Join clause definition.
 */
export interface JoinClause {
    type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
    entity: string;
    on: {
        leftField: string;
        rightField: string;
    };
    alias?: string;
}
/**
 * Execution hints for optimization.
 */
export interface ExecutionHints {
    preferredStrategy?: ExecutionStrategy | 'sql' | 'jsonata' | 'hybrid';
    maxExecutionTime?: number;
    enableParallelExecution?: boolean;
    cacheResult?: boolean;
    cacheTTL?: number;
    enhancedHints?: {
        queryIntent?: EnhancedQueryIntent;
        fieldLocality?: Map<string, FieldLocalityInfo>;
        joinHints?: JoinHints;
        aggregationContext?: EnhancedAggregationContext;
        decomposedQuery?: DecomposedQuery;
    };
}
/**
 * Execution plan created by the Query Planner.
 */
export interface ExecutionPlan {
    id: string;
    query: UniversalQuery;
    strategy: ExecutionStrategy;
    phases: ExecutionPhase[];
    estimatedCost: number;
    estimatedRows: number;
    requiresPostProcessing: boolean;
}
/**
 * Execution strategy chosen by the planner.
 */
export type ExecutionStrategy = 'pure-sql' | 'pure-jsonata' | 'hybrid-sql-first' | 'hybrid-jsonata-first' | 'parallel';
/**
 * Individual phase in the execution plan.
 */
export interface ExecutionPhase {
    name: string;
    type: 'sql' | 'jsonata' | 'post-process';
    query: any;
    inputFrom?: string;
    outputTo?: string;
    parallel?: boolean;
}
/**
 * Query execution result.
 */
export interface QueryResult {
    data: any[];
    metadata: ResultMetadata;
    plan?: ExecutionPlan;
}
/**
 * Metadata about query execution.
 */
export interface ResultMetadata {
    rowCount: number;
    executionTime: number;
    cacheHit: boolean;
    cached?: boolean;
    cacheKey?: string;
    cacheTTL?: number;
    totalExecutionTime?: number;
    warnings?: string[];
    pagination?: {
        page: number;
        pageSize: number;
        totalPages: number;
        totalRows: number;
    };
    error?: string;
    plan?: ExecutionPlan;
}
/**
 * Query pattern for learning system.
 */
export interface QueryPattern {
    hash: string;
    query: UniversalQuery;
    executionCount: number;
    averageExecutionTime: number;
    lastExecuted: Date;
    optimalStrategy?: ExecutionStrategy;
}
/**
 * Performance metrics for optimization.
 */
export interface PerformanceMetrics {
    queryHash: string;
    executionTime: number;
    rowsReturned: number;
    memoryUsed: number;
    cacheHit: boolean;
    timestamp: Date;
}
/**
 * Engine configuration.
 */
export interface EngineConfiguration {
    discovery: {
        autoDiscover: boolean;
        discoveryInterval: number;
        cacheTTL: number;
    };
    execution: {
        defaultStrategy: ExecutionStrategy;
        maxQueryTime: number;
        enableParallel: boolean;
        parallelThreshold: number;
    };
    learning: {
        enabled: boolean;
        sampleRate: number;
        optimizationThreshold: number;
    };
    adapters: {
        [adapterName: string]: any;
    };
    cache?: {
        enabled?: boolean;
        warmupOnStart?: boolean;
        statsInterval?: number;
        maxSizeMB?: number;
        defaultTTL?: number;
        syncIntegration?: {
            enabled?: boolean;
            batchInvalidation?: boolean;
            batchDelay?: number;
            warmupAfterSync?: boolean;
        };
    };
}
/**
 * Base error class for query engine.
 */
export declare class QueryEngineError extends Error {
    code: string;
    details?: any | undefined;
    constructor(message: string, code: string, details?: any | undefined);
}
/**
 * Field resolution error.
 */
export declare class FieldResolutionError extends QueryEngineError {
    constructor(field: string, entity: string, details?: any);
}
/**
 * Query execution error.
 */
export declare class QueryExecutionError extends QueryEngineError {
    constructor(message: string, details?: any);
}
/**
 * Adapter error.
 */
export declare class AdapterError extends QueryEngineError {
    constructor(adapterName: string, message: string, details?: any);
}
//# sourceMappingURL=types.d.ts.map