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.

When to Use This Skill

Use this skill when you need to:

• Create interactive query builders for filtering data visually
• Define column schemas with types, operators, and validation
• Bind data from local sources or remote APIs
• Manage rules and groups with AND/OR logic
• Add drag-drop functionality for moving and cloning rules
• Customize templates for fields, operators, and values
• Export/import queries as JSON or SQL
• Ensure accessibility with keyboard navigation and ARIA
• Handle complex filtering scenarios in your 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

📄 Read: 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

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!