@simonecoelhosfo/optimizely-mcp-server/dist/analytics/QueryAnalysisEngine.d.ts

Optimizely MCP Server for AI assistants with integrated CLI tools

/**
 * Query Analysis Engine - Phase 3.2 of Dynamic Analytics Query Engine
 *
 * This engine analyzes SQL queries to determine:
 * 1. Which fields are being accessed and how
 * 2. Whether array flattening is required
 * 3. Query complexity and optimization opportunities
 * 4. Performance characteristics and bottlenecks
 *
 * The engine integrates with the UnifiedFieldResolver from Phase 3.1 to provide
 * intelligent query planning that prevents the "variations.key does not exist" errors
 * by understanding data structure requirements before execution.
 */
import { QueryContext, ResolvedField } from './UnifiedFieldResolver.js';
import { EntityType } from './types.js';
/**
 * Represents a parsed SQL query with field analysis
 */
export interface ParsedQuery {
    /** Original SQL query string */
    originalQuery: string;
    /** Type of SQL operation (SELECT, INSERT, UPDATE, DELETE) */
    operation: 'SELECT' | 'INSERT' | 'UPDATE' | 'DELETE';
    /** Primary entity being queried */
    primaryEntity: EntityType;
    /** All fields referenced in the query */
    referencedFields: string[];
    /** Fields that appear in WHERE clauses */
    filterFields: string[];
    /** Fields that appear in SELECT clauses */
    projectionFields: string[];
    /** Fields that appear in GROUP BY clauses */
    groupByFields: string[];
    /** Fields that appear in ORDER BY clauses */
    orderByFields: string[];
    /** JOINs detected in the query */
    joins: QueryJoin[];
    /** Subqueries detected */
    subqueries: ParsedQuery[];
}
/**
 * Information about JOINs in the query
 */
export interface QueryJoin {
    /** Type of join (INNER, LEFT, RIGHT, FULL) */
    type: 'INNER' | 'LEFT' | 'RIGHT' | 'FULL';
    /** Table/entity being joined */
    joinedEntity: EntityType;
    /** Join condition fields */
    joinFields: string[];
}
/**
 * Analysis results for flattening requirements
 */
export interface FlatteningAnalysis {
    /** Whether any flattening is required */
    requiresFlattening: boolean;
    /** Fields that need array flattening */
    arrayFields: FlatteningRequirement[];
    /** Fields that need object flattening */
    objectFields: FlatteningRequirement[];
    /** Estimated impact on result set size */
    estimatedImpact: 'minimal' | 'moderate' | 'significant' | 'explosive';
    /** Recommended approach */
    recommendation: FlatteningStrategy;
}
/**
 * Specific flattening requirement for a field
 */
export interface FlatteningRequirement {
    /** Field name that needs flattening */
    fieldName: string;
    /** Resolved field information */
    resolvedField: ResolvedField;
    /** Type of flattening needed */
    flatteningType: 'array_to_rows' | 'object_to_columns' | 'nested_array';
    /** Depth of nesting */
    nestingDepth: number;
    /** Estimated cardinality */
    estimatedCardinality: number;
}
/**
 * Strategy for handling flattening
 */
export interface FlatteningStrategy {
    /** Overall approach */
    approach: 'no_flattening' | 'selective_flattening' | 'full_flattening' | 'staged_flattening';
    /** Specific steps to take */
    steps: FlatteningStep[];
    /** Performance considerations */
    performanceNotes: string[];
    /** Alternative approaches */
    alternatives: string[];
}
/**
 * Individual step in flattening strategy
 */
export interface FlatteningStep {
    /** Order of execution */
    order: number;
    /** Description of the step */
    description: string;
    /** SQL/JSONata expression to execute */
    expression: string;
    /** Expected result size impact */
    sizeImpact: number;
}
/**
 * Query optimization analysis
 */
export interface QueryOptimization {
    /** Complexity level of the query */
    complexityLevel: 'simple' | 'moderate' | 'complex' | 'very_complex';
    /** Performance score (0-100, higher is better) */
    performanceScore: number;
    /** Identified performance issues */
    issues: PerformanceIssue[];
    /** Suggested optimizations */
    optimizations: QueryOptimizationSuggestion[];
    /** Estimated execution time range */
    estimatedExecutionTime: {
        min: number;
        max: number;
        confidence: number;
    };
}
/**
 * Performance issue in query
 */
export interface PerformanceIssue {
    /** Severity level */
    severity: 'low' | 'medium' | 'high' | 'critical';
    /** Issue category */
    category: 'cartesian_product' | 'inefficient_join' | 'missing_index' | 'large_result_set' | 'complex_aggregation';
    /** Description of the issue */
    description: string;
    /** Location in query where issue occurs */
    location: string;
    /** Suggested fix */
    suggestion: string;
    /** Expected improvement if fixed */
    expectedImprovement: string;
}
/**
 * Suggested query optimization
 */
export interface QueryOptimizationSuggestion {
    /** Type of optimization */
    type: 'rewrite' | 'index' | 'restructure' | 'cache' | 'paginate';
    /** Description */
    description: string;
    /** Before/after comparison */
    comparison: {
        before: string;
        after: string;
        improvement: string;
    };
    /** Implementation difficulty */
    difficulty: 'easy' | 'moderate' | 'hard';
}
/**
 * Complete analysis result for a query
 */
export interface QueryAnalysisResult {
    /** Parsed query structure */
    parsedQuery: ParsedQuery;
    /** Field resolution results */
    fieldResolutions: ResolvedField[];
    /** Flattening analysis */
    flatteningAnalysis: FlatteningAnalysis;
    /** Optimization analysis */
    optimization: QueryOptimization;
    /** Overall recommendation */
    recommendation: QueryRecommendation;
    /** Analysis metadata */
    metadata: {
        analysisTime: number;
        analyzerVersion: string;
        contextUsed: QueryContext;
    };
}
/**
 * Overall recommendation for query execution
 */
export interface QueryRecommendation {
    /** Whether query should be executed as-is */
    executeAsIs: boolean;
    /** Suggested modifications */
    modifications: string[];
    /** Alternative approaches */
    alternatives: string[];
    /** Risk assessment */
    riskLevel: 'low' | 'medium' | 'high';
    /** Confidence in recommendation */
    confidence: number;
}
/**
 * Main Query Analysis Engine
 */
export declare class QueryAnalysisEngine {
    private fieldResolver;
    private readonly version;
    constructor();
    /**
     * Analyze a complete query and provide recommendations
     */
    analyzeQuery(query: string, context: QueryContext): Promise<QueryAnalysisResult>;
    /**
     * Parse SQL query into structured representation
     *
     * Note: This is a simplified parser. In production, consider using
     * a proper SQL parser like node-sql-parser or similar.
     */
    private parseQuery;
    /**
     * Resolve all fields referenced in the query using UnifiedFieldResolver
     */
    private resolveQueryFields;
    /**
     * Analyze which fields require flattening and estimate impact
     */
    private analyzeFlatteningRequirements;
    /**
     * Analyze query performance and optimization opportunities
     */
    private analyzeOptimization;
    /**
     * Generate overall recommendation for query execution
     */
    private generateRecommendation;
    private extractFieldReferences;
    private extractFilterFields;
    private extractProjectionFields;
    private extractGroupByFields;
    private extractOrderByFields;
    private extractJoins;
    private calculateNestingDepth;
    private estimateCardinality;
    private estimateImpact;
    private recommendFlatteningStrategy;
}
//# sourceMappingURL=QueryAnalysisEngine.d.ts.map