syncfusion-aspnetcore-query-builder

Implementing QueryBuilder in ASP.NET Core

The Syncfusion QueryBuilder is a UI component for creating and editing filter conditions visually. Users can define rules and groups, combine them with AND/OR connectors, and export them as JSON, SQL, or MongoDB queries — all using ASP.NET Core TagHelper syntax.

Navigation Guide

Getting Started

📄 Read: references/getting-started.md

• NuGet package installation and TagHelper setup
• CDN stylesheet and script references
• Basic QueryBuilder with columns
• Render with initial Rule (JSON)
• EmployeeView model class example

Column Configuration

📄 Read: references/columns.md

• Auto-generating columns from DataSource
• Labels, field mapping, data types
• Operators table (all supported types)
• Number step and date/number format
• Validation (isRequired, min, max)
• Column-level custom input templates

Data Binding

📄 Read: references/data-binding.md

• Local data binding (JSON array, DataManager)
• Remote data (OData, ODataV4, WebAPI, UrlAdaptor)
• Using getPredicate to filter data
• Grid integration via ruleChange event

Import & Export

📄 Read: references/import-export.md

• Import from JSON (initial Rule / setRules)
• Import from SQL (Inline, Parameter, Named Parameter)
• Import from MongoDB (setMongoQuery)
• Export to JSON (getRules)
• Export to SQL variants and MongoDB

Filtering & Rule Management

📄 Read: references/filtering-and-rules.md

• ShowButtons configuration (ruleDelete, groupInsert, groupDelete, clone, lock)
• addRules / deleteRules / addGroups / deleteGroups methods
• cloneGroup / cloneRule methods
• lockGroup / lockRule methods
• EnableSeparateConnector between rules
• EnableNotCondition for NOT groups

Templates & Appearance

📄 Read: references/templates-and-appearance.md

• Header template customization
• Display mode (Horizontal / Vertical)
• Summary view (collapsed read-only display)
• Model binding (fieldModel, operatorModel, valueModel)
• CSS classes for styling customization

Configuration & How-To

📄 Read: references/configuration-and-how-to.md

• Drag and drop (AllowDragAndDrop, events)
• MaxGroupCount to restrict nested groups
• SortDirection for column field ordering
• EnablePersistence (state saved in localStorage)
• EnableRtl for right-to-left languages
• ReadOnly mode, Width/Height, CssClass
• AutoSelectField, AutoSelectOperator, MatchCase

Localization

📄 Read: references/localization.md

• Setting the Locale property
• Full locale key reference table
• Example: Arabic / RTL localization

API Reference

📄 Read: references/api.md

• Complete properties with types and defaults
• All events with descriptions
• QueryBuilderColumn sub-properties
• QueryBuilderShowButtons sub-properties
• TagHelper attribute naming conventions

Quick Start Example

@* _ViewImports.cshtml must have: @addTagHelper *, Syncfusion.EJ2 *@

<ejs-querybuilder id="querybuilder" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Title" label="Title" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="HireDate" label="Hire Date" type="date" format="dd/MM/yyyy"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Common Patterns

Render with Initial Rule

@using Syncfusion.EJ2.QueryBuilder
@{
    QueryBuilderRule rule = new QueryBuilderRule()
    {
        Condition = "and",
        Rules = new List<QueryBuilderRule>()
        {
            new QueryBuilderRule { Label = "First Name", Field = "FirstName", Type = "string", Operator = "startswith", Value = "Nancy" },
            new QueryBuilderRule { Label = "Country", Field = "Country", Type = "string", Operator = "equal", Value = "USA" }
        }
    };
    var dataSource = EmployeeView.GetAllRecords();
}
<ejs-querybuilder id="querybuilder" width="70%" rule="rule" dataSource="dataSource">
    <e-querybuilder-columns>
        <e-querybuilder-column field="EmployeeID" label="Employee ID" type="number"></e-querybuilder-column>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Export Rules to SQL

var queryBuilder = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);

// Get JSON rules
var jsonRules = queryBuilder.getRules();

// Get Inline SQL
var sql = queryBuilder.getSqlFromRules(jsonRules);

// Get Parameterized SQL
var paramSql = queryBuilder.getParameterizedSql(jsonRules);

Grid Integration with QueryBuilder

// In ruleChange event handler:
function ruleChanged(args) {
    var qryBldrObj = ej.base.getInstance(document.getElementById("querybuilder"), ejs.querybuilder.QueryBuilder);
    var gridObj = ej.base.getInstance(document.getElementById("Grid"), ejs.grids.Grid);
    gridObj.query = qryBldrObj.getDataManagerQuery(qryBldrObj.getRules());
    gridObj.refresh();
}

Drag and Drop Enabled

<ejs-querybuilder id="querybuilder" allowDragAndDrop="true" width="70%">
    <e-querybuilder-columns>
        <e-querybuilder-column field="FirstName" label="First Name" type="string"></e-querybuilder-column>
        <e-querybuilder-column field="Country" label="Country" type="string"></e-querybuilder-column>
    </e-querybuilder-columns>
</ejs-querybuilder>

Key Properties Quick Reference

Property	TagHelper Attribute	Purpose
Columns	e-querybuilder-columns	Define filterable fields
Rule	rule="rule"	Initial rule — C# QueryBuilderRule object
DataSource	dataSource	Bind local/remote data
AllowDragAndDrop	allowDragAndDrop	Enable rule reordering
AllowValidation	allowValidation	Validate rule inputs
EnableSeparateConnector	enableSeparateConnector	Per-rule AND/OR connectors
EnableNotCondition	enableNotCondition	NOT group operator
MaxGroupCount	maxGroupCount	Limit nested group depth
SummaryView	summaryView	Show collapsed rule summary
DisplayMode	displayMode	Horizontal or Vertical layout
EnablePersistence	enablePersistence	Save state to localStorage
EnableRtl	enableRtl	Right-to-left layout
SortDirection	sortDirection	Sort column field list
Readonly	readonly	Disable all interactions
Width / Height	width / height	Component dimensions

Common Use Cases

• Data grid filter UI → QueryBuilder + Grid integration via ruleChange
• Save/restore conditions → getRules + setRules with localStorage or backend
• SQL WHERE clause builder → getSqlFromRules / getParameterizedSql
• MongoDB filter → getMongoQuery / setMongoQuery
• Read-only filter display → summaryView="true" + readonly="true"
• Mobile-friendly layout → displayMode="Vertical" + maxGroupCount="2"
• Localized UI → locale property + L10n translation object

Security & Trust Boundary

External Dependency: CDN-Based JavaScript Execution

The Syncfusion QueryBuilder requires runtime execution of external JavaScript from the official CDN endpoint (https://cdn.syncfusion.com/ej2/*/dist/ej2.min.js). This is a required trusted dependency with the following security considerations:

Risk Mitigation Strategies

1. Use HTTPS Only

   • Always reference CDN resources via HTTPS to prevent man-in-the-middle attacks
   • Verify your layout template uses https:// scheme

2. Subresource Integrity (SRI)

   • Include SRI hash attributes to validate script integrity:

   <script src="https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js" 
           integrity="sha384-[HASH]" 
           crossorigin="anonymous"></script>
   

3. Content Security Policy (CSP)

   • Add Syncfusion CDN to your CSP whitelist:

   script-src 'self' https://cdn.syncfusion.com;
   style-src 'self' https://cdn.syncfusion.com;
   

4. Vendor Lock & Trust Assessment

   • Trusted Vendor: Syncfusion is an established commercial component vendor with industry adoption
   • No Open-Source Alternatives: QueryBuilder functionality is specialized; evaluate internal development costs vs. vendor dependency
   • Consider Bundling: For enhanced control, bundle Syncfusion scripts locally instead of using CDN (download and host on your own domain)

5. Version Pinning

   • Always pin the specific version instead of using wildcard versions:

   ❌ https://cdn.syncfusion.com/ej2/latest/dist/ej2.min.js
   ✅ https://cdn.syncfusion.com/ej2/23.1.43/dist/ej2.min.js
   

6. Update Management

   • Regularly update Syncfusion NuGet packages and verify corresponding CDN versions match
   • Subscribe to Syncfusion security announcements
   • Test updates in staging environment before production deployment

Acceptable Risk Assessment

• Severity: Medium (requires trust boundary evaluation at deployment)
• Mitigation: Implement SRI + CSP + version pinning
• Approval: Obtain security team sign-off for use in compliant applications

---

Start here: Read references/getting-started.md to set up your first QueryBuilder.