Condition Builder & Query Parsing
Relevant source files
The following files were used as context for generating this wiki page:
The Condition Builder and Query Parsing system enables users to define, validate, and serialize complex equity screening criteria. The system provides a visual interface for selecting technical, fundamental, and momentum-based indicators, which are then parsed into the Nexus Query Language (NQL) for execution against market data snapshots.
This module acts as the bridge between user intent in the UI and the underlying execution engine. It supports boolean logic (Match All/Match Any), parameter validation, and human-readable explanations of active filters. Users can either build queries visually through the ScreenerModal or ConditionCatalogModal, or provide raw text queries that are evaluated by a Python-based backend service.
Sources: frontend/README.md, frontend/src/components/ExploreTab.tsx:64-77
Core Data Structures
The system relies on a strictly typed set of interfaces to represent screening criteria and the resulting expression trees.
Condition Definitions
Every available filter is defined as a ConditionDef. These definitions include metadata for the UI and specifications for the required parameters.
| Structure | Description |
|---|---|
ConditionDef | Defines the ID, label, category, and available parameters for a condition. |
ParameterSpec | Describes individual parameters, including types (number, select, boolean), default values, and range limits. |
ActiveCondition | Represents a condition selected by the user, including specific parameter values and an instance ID. |
ExpressionNode | A recursive structure forming a tree of conditions grouped by boolean operators (MatchMode). |
Sources: frontend/src/types/screener.ts:21-72, frontend/src/data/conditionCatalog.ts:31-300
Logic Flow Diagram
The following diagram illustrates how user selections are transformed into a validated expression tree.
The application uses a local map to track active conditions before applying them to the global state.
Sources: frontend/src/components/ConditionCatalogModal.tsx:67-118, frontend/src/components/ScreenerModal.tsx:166-215
Nexus Query Language (NQL) Parsing
The NQL Parser converts internal ActiveCondition objects into human-readable strings. This serves two purposes: providing UI feedback in the "Query Summary" and preparing diagnostic information for the explanation service.
Parsing Logic
The explainCondition function uses a switch-case structure to map condition IDs to descriptive templates. For example:
- Trend Price vs MA: "Price is ABOVE SMA 50 (threshold: 0%)"
- Momentum RVOL: "Relative Volume (20-Day RVOL) is BETWEEN 1.5x and 20x average volume"
- Fundamental Market Cap: "Market Capitalization is BETWEEN ₹1000 Cr. and ₹2000000 Cr."
Sources: frontend/src/utils/nqlParser.ts:16-120
Expression Tree Traversal
To explain a complex query, the explainExpressionTree function recursively traverses the ExpressionNode tree.
Visual Condition Catalog
The ConditionCatalogModal provides a categorized grid for discovering and configuring indicators.
Categories
Conditions are grouped into logical families to assist equity researchers:
- Trend: EMA/SMA crossovers, slopes, and persistence.
- Momentum: Returns, gap analysis, and relative volume (RVOL).
- Range & Patterns: 52-week proximity, inside bars, and VCP contraction.
- Relative Strength: Proprietary RS ratings and bench-marking against Nifty indices.
- Fundamentals: P/E ratios, earnings growth, and market capitalization.
- Liquidity: Average daily turnover and F&O segment status.
Sources: frontend/src/components/ConditionCatalogModal.tsx:16-24, frontend/src/data/conditionCatalog.ts:173-356
Parameter Controls
The modal dynamically renders inputs based on the ParameterType defined in the catalog:
- Select/Dropdown: Used for MA types (SMA/EMA) or operator selection (Above/Below).
- Number Input: Supports
min,max, andstepvalues for precise technical thresholds. - Boolean/Checkbox: Used for flags like "Invalidate on Break" in divergence patterns.
- Multiselect: Used for excluding specific circuit limit bands.
Sources: frontend/src/components/ScreenerModal.tsx:43-118, frontend/src/types/screener.ts:11
Validation and Execution
Before a screen is executed, the conditionValidation utility ensures all parameters meet required constraints.
- Numeric Boundaries: Checks if values are within the
minandmaxdefined in theParameterSpec. - Integer Requirements: Ensures fields like "MA Period" or "Consecutive Days" do not contain decimals.
- Required Fields: Blocks submission if mandatory numeric fields are cleared.
- UI Feedback: The "Apply Filters" button is disabled and an alert message is displayed if validation fails.
Sources: frontend/src/components/ConditionCatalogModal.tsx:120-125, frontend/src/tests/conditionModals.test.tsx:28-44
Data Flow Diagram: Execution
The sequence below shows how a parsed request reaches the execution engine.
Summary
The Condition Builder and Query Parsing system provides a structured framework for defining NSE market screens. By combining a metadata-driven UI catalog with a recursive expression tree and NQL parser, it ensures that complex boolean queries are both user-friendly and technically valid for the underlying execution engine.