Implementing QueryBuilder in TypeScript

The QueryBuilder is a powerful Syncfusion component for building dynamic, complex queries with a visual UI. This skill provides comprehensive guidance for implementing, configuring, and customizing the QueryBuilder in TypeScript applications.

Control Overview

QueryBuilder is an advanced UI component that enables users to build complex filter conditions without writing code. It supports:

• Multiple data types (string, number, date, boolean)
• Various operators (equals, contains, between, etc.)
• Rule grouping with AND/OR conditions
• Nested group hierarchies
• Custom templates for UI customization
• Drag-drop interactions (rearrange, clone, lock rules)
• JSON import/export and SQL generation
• RTL support and full keyboard accessibility
• WCAG 2.1 AA compliance

Documentation and Navigation Guide

Getting Started

See also: references/getting-started.md

• Installation and npm package setup
• Syncfusion dependencies configuration
• CSS imports and theme setup
• Basic QueryBuilder initialization
• Column definitions with types
• Running your first QueryBuilder application

Columns and Schema Definition

See also: references/columns-definition.md

• Column definitions and schema structure
• Auto-generation of columns from data
• Field mapping and labels
• Supported data types (string, number, date, boolean)
• Operators for each data type
• Step and format properties for numbers/dates
• Custom column configuration patterns

Data Binding

See also: references/data-binding.md

• Local data binding with JavaScript arrays
• Remote data binding with DataManager
• DataSource assignment patterns
• RuleModel structure for predefined queries
• Binding with initial rules
• Dynamic data updates and refresh
• DataManager configuration

Rules and Groups Management

See also: references/rules-and-groups.md

• Rule model structure (condition, rules, field, operator, value)
• Creating single filter rules
• Grouping rules with AND/OR logic
• Adding and deleting rules programmatically
• Adding and deleting groups
• Rule validation and constraints
• Nested group hierarchies

Filtering and Search Operations

See also: references/filtering-search.md

• Filtering conditions creation and deletion
• Query execution methods
• Custom filter condition patterns
• Search functionality within conditions
• ShowButtons configuration (rule delete, group insert/delete)
• UI-based and programmatic filtering
• Event handling for filter changes

Templates and Customization

See also: references/templates-customization.md

• Value template customization
• Operator template customization
• Field template customization
• Custom HTML template creation
• Template rendering and binding
• CSS class customization
• Dynamic template rendering patterns

Drag-Drop and Rule Interaction

See also: references/drag-drop-clone-lock.md

• Drag and drop functionality for rules
• Cloning rules within groups
• Locking rules to prevent modification
• Separator and connector behavior
• Moving rules between groups
• Drag-drop event handling
• Visual feedback and styling

Import/Export and Persistence

See also: references/import-export.md

• Exporting rules to JSON format
• Importing rules from JSON
• SQL query generation
• JSON serialization patterns
• Format conversions (rules to SQL/JSON)
• Data persistence strategies
• State management

Accessibility and RTL

See also: references/accessibility-rtl.md

• WCAG 2.1 AA compliance standards
• Keyboard navigation patterns
• ARIA attributes and labels
• Screen reader support
• RTL (Right-to-Left) language support
• Focus management and indicators
• Localization and internationalization

Advanced Features and Troubleshooting

See also: references/advanced-features.md

• Global and local configuration options
• Model binding patterns
• Advanced validation strategies
• Performance optimization techniques
• Event handling and callbacks
• State persistence patterns
• Common issues and troubleshooting
• Best practices for complex scenarios

API Reference

See also: references/api.md

• Complete properties reference with types and defaults
• All public methods with parameters and return types
• All events with event argument interfaces
• Key model interfaces (RuleModel, ColumnsModel, ShowButtonsModel, ValueModel, TemplateColumn, Validation)
• Event arg interfaces (ActionEventArgs, ChangeEventArgs, RuleChangeEventArgs, DragEventArgs, DropEventArgs)
• SQL/query output interfaces (ParameterizedSql, ParameterizedNamedSql)
• Usage examples for initialization, SQL export, rule management, clone/lock, and drag-drop

Quick Start Example

Here's a minimal example to get started with QueryBuilder:

import { QueryBuilder, ColumnsModel, RuleModel } from '@syncfusion/ej2-querybuilder';

// Define your data
const employeeData = [
  {
    EmployeeID: 1,
    FirstName: 'Nancy',
    Title: 'Sales Representative',
    HireDate: '22/07/2001',
    City: 'Seattle',
    Country: 'USA'
  },
  {
    EmployeeID: 2,
    FirstName: 'Andrew',
    Title: 'Vice President',
    HireDate: '21/04/2003',
    City: 'Tacoma',
    Country: 'USA'
  }
];

// Define columns matching your data
const columnData: ColumnsModel[] = [
  { field: 'EmployeeID', label: 'Employee ID', type: 'number' },
  { field: 'FirstName', label: 'First Name', type: 'string' },
  { field: 'Title', label: 'Title', type: 'string' },
  { field: 'HireDate', label: 'Hire Date', type: 'date', format: 'dd/MM/yyyy' },
  { field: 'City', label: 'City', type: 'string' },
  { field: 'Country', label: 'Country', type: 'string' }
];

// Optional: Define initial rules
const initialRules: RuleModel = {
  condition: 'and',
  rules: [
    {
      label: 'Employee ID',
      field: 'EmployeeID',
      type: 'number',
      operator: 'equal',
      value: 1
    },
    {
      label: 'Title',
      field: 'Title',
      type: 'string',
      operator: 'startswith',
      value: 'Sales'
    }
  ]
};

// Create QueryBuilder instance
const queryBuilder = new QueryBuilder({
  width: '100%',
  dataSource: employeeData,
  columns: columnData,
  rule: initialRules
});

// Render to DOM
queryBuilder.appendTo('#querybuilder');

Common Patterns

Pattern 1: Basic Filter with Single Rule

For simple filtering scenarios, use a single rule without groups:

const rule: RuleModel = {
  condition: 'and',
  rules: [{
    field: 'FirstName',
    type: 'string',
    operator: 'startswith',
    value: 'A'
  }]
};

Pattern 2: AND/OR Logic with Groups

For complex filters combining multiple conditions:

const rule: RuleModel = {
  condition: 'and',
  rules: [
    { field: 'City', operator: 'equal', value: 'Seattle' },
    {
      condition: 'or',
      rules: [
        { field: 'Title', operator: 'contains', value: 'Sales' },
        { field: 'Title', operator: 'contains', value: 'Manager' }
      ]
    }
  ]
};

Pattern 3: Dynamic Rule Addition

Add rules programmatically in response to user actions:

const newRule = [{
  field: 'Country',
  operator: 'equal',
  value: 'USA'
}];
queryBuilder.addRules(newRule, 'group0');

Pattern 4: Export to JSON for Storage

Save the current query state for persistence:

const rules = queryBuilder.getRules();
const jsonQuery = JSON.stringify(rules);
// Store in database or local storage

Key Concepts

• RuleModel: Represents a single filter condition with field, operator, and value
• Condition: Logical operator (AND/OR) for combining multiple rules
• GroupModel: Container for rules with AND/OR conditions
• Operators: Comparison methods (equal, contains, between, etc.)
• Data Types: Supported column types (string, number, date, boolean)
• Templates: Custom UI elements for fields, operators, and values
• State: Current configuration of rules and groups

Common Use Cases

1. Advanced Search Filter - Let users build complex queries for data search
2. Report Generation - Create dynamic filters for report parameters
3. Data Export - Filter data before export with visual UI
4. Log Analysis - Build complex queries to analyze system logs
5. Customer Segmentation - Filter customers based on multiple criteria
6. Permission Rules - Define access rules with complex conditions
7. Notification Rules - Create dynamic alert conditions
8. ETL Workflows - Filter source data before transformation

Need help with a specific feature? Check the reference files above for detailed guidance on columns, data binding, templates, and more!