API 프로젝트를 위한 쿼리 빌더 지원
개요
이 가이드에서는 API 프로젝트에서 쿼리 빌더 모델 및 유틸리티를 구현하여 사용자 정의 쿼리를 활성화하는 방법을 설명합니다. 구현에는 컨트롤러 만들기, 쿼리 빌더 모델 정의, 그리고 이러한 쿼리에서 SQL 문을 실행하고 생성하기 위한 유틸리티 추가가 포함됩니다. 결과적인 사용자 지정을 통해 사용자는 부분 쿼리 지원, 필터링, 논리 연산자, 그리고 필드 선택을 포함한 복잡한 쿼리를 생성하여 데이터 원본에 대해 효율적으로 실행할 수 있습니다.
구현 옵션
API 프로젝트에서 쿼리 빌더 지원을 구현하는 두 가지 방식이 있습니다.
| 방식 | 최고 | 노력 수준 |
|---|---|---|
NuGet 패키지 (Infragistics.QueryBuilder.Executor) | 빠른 통합, 표준 사용 사례 | 낮음 |
| 수동 구현 | 전체 사용자 지정, 복잡한 요구 사항 | 중간-높음 |
옵션 1: Infragistics.QueryBuilder.Executor NuGet 패키지 사용 (권장)
Infragistics.QueryBuilder.Executor 패키지는 기존 API 프로젝트에 최소한의 구성으로 직접 연결할 수 있는 즉시 사용 가능한 클래스, 조건 및 메서드를 제공합니다.
전제 조건
- .NET 8 또는 .NET 9
- Microsoft.EntityFrameworkCore
- AutoMapper
- 기존 ASP.NET Core API 프로젝트
1단계: 패키지 설치
dotnet add package Infragistics.QueryBuilder.Executor
2단계: 서비스 구성
Program.cs 또는 Startup.cs에서 DbContext 및 결과 DTO로 QueryBuilder 서비스를 등록합니다:
// Program.cs
builder.Services.AddQueryBuilder<MyDbContext, MyResultDto>();
// SwaggerUI 호환성을 위해 필수
builder.Services.AddControllers().AddNewtonsoftJson(o =>
o.SerializerSettings.ReferenceLoopHandling = ReferenceLoopHandling.Ignore);
3단계: 쿼리 엔드포인트 노출
쿼리 빌더 기능을 노출하도록 엔드포인트 라우팅을 구성합니다:
app.UseEndpoints(endpoints =>
{
endpoints.UseQueryBuilder<MyDbContext, MyResultDto>("/api/query");
});
4단계: 쿼리 전송
이제 API는 쿼리 페이로드를 수락할 준비가 되었습니다. 다음은 예제 요청입니다:
{
"Entity": "Users",
"ReturnFields": ["Id", "Name", "Email"],
"Operator": "And",
"FilteringOperands": [
{
"FieldName": "IsActive",
"Condition": { "Name": "equals" },
"SearchVal": true
},
{
"FieldName": "CreatedDate",
"Condition": { "Name": "after" },
"SearchVal": "2024-01-01"
}
]
}
5단계: SQL 생성 (선택 사항)
진단 또는 분석을 위해 쿼리 모델에서 SQL을 생성할 수 있습니다:
var sql = SqlGenerator.GenerateSql(query);
Console.WriteLine(sql);
// Output: SELECT Id, Name, Email FROM Users WHERE IsActive = 1 AND CreatedDate > '2024-01-01'
옵션 2: 수동 구현
전체 사용자 지정이나 복잡한 엔터티 매핑이 필요한 프로젝트의 경우 쿼리 빌더를 수동으로 구현할 수 있습니다. 구현은 NorthwindAPI REST API 프로젝트에 제시되어 있습니다.
전제 조건
- .NET Core 또는 .NET API 프로젝트
- LINQ, Entity Framework 또는 데이터 쿼리용 기타 ORM에 대한 친숙함
- C# 및 ASP.NET Core 컨트롤러의 기본 지식
1단계: QueryBuilderController 만들기
QueryBuilderController는 쿼리 요청을 처리하기 위한 진입점으로 작동합니다. 클라이언트에서 Query 객체를 수신하고, QueryExecutor를 사용하여 처리한 후, 결과를 반환합니다.
Controllers 디렉터리에 QueryBuilderController.cs라는 파일을 만듭니다:
[ApiController]
[Route("[controller]")]
public class QueryBuilderController : ControllerBase
{
private readonly DataContext dataContext;
private readonly IMapper mapper;
private readonly ILogger<QueryBuilderController> logger;
public QueryBuilderController(DataContext dataContext, IMapper mapper, ILogger<QueryBuilderController> logger)
{
this.dataContext = dataContext;
this.mapper = mapper;
this.logger = logger;
}
[HttpPost("ExecuteQuery")]
[Consumes("application/json")]
[Produces("application/json")]
public ActionResult<QueryBuilderResult> ExecuteQuery(Query query)
{
var sanitizedEntity = query.Entity.Replace("\r", string.Empty).Replace("\n", string.Empty);
logger.LogInformation("Executing query for entity: {Entity}", sanitizedEntity);
var t = query.Entity.ToLower(CultureInfo.InvariantCulture);
return Ok(new Dictionary<string, object[]?>
{
{
t,
t switch
{
"addresses" => dataContext.Addresses.Run<AddressDb, AddressDto>(query, mapper),
"categories" => dataContext.Categories.Run<CategoryDb, CategoryDto>(query, mapper),
"products" => dataContext.Products.Run<ProductDb, ProductDto>(query, mapper),
"regions" => dataContext.Regions.Run<RegionDb, RegionDto>(query, mapper),
"territories" => dataContext.Territories.Run<TerritoryDb, TerritoryDto>(query, mapper),
"employees" => dataContext.Employees.Run<EmployeeDb, EmployeeDto>(query, mapper),
"customers" => dataContext.Customers.Run<CustomerDb, CustomerDto>(query, mapper),
"orders" => dataContext.Orders.Run<OrderDb, OrderDto>(query, mapper),
"orderdetails" => dataContext.OrderDetails.Run<OrderDetailDb, OrderDetailDto>(query, mapper),
"shippers" => dataContext.Shippers.Run<ShipperDb, ShipperDto>(query, mapper),
"suppliers" => dataContext.Suppliers.Run<SupplierDb, SupplierDto>(query, mapper),
_ => throw new InvalidOperationException($"Unknown entity {t}"),
}
},
});
}
}
전체 예제는 NorthwindAPI QueryBuilderController를 참조하세요.
2단계: 쿼리 빌더 모델 정의
쿼리 빌더는 쿼리 구조를 나타내는 모델 세트에 의존합니다. 이들을 QueryBuilder 디렉터리 또는 네임스페이스에 배치합니다.
FilterType Enum
필터를 결합하기 위한 논리 연산자를 정의합니다:
public enum FilterType
{
And = 0,
Or = 1,
}
Query 클래스
전체 쿼리 구조를 나타냅니다:
public class Query
{
public string Entity { get; set; }
public string[] ReturnFields { get; set; }
public FilterType Operator { get; set; }
public QueryFilter[] FilteringOperands { get; set; }
}
| 속성 | 설명 |
|---|---|
Entity | 쿼리되는 대상 엔터티/테이블(예: “Products”) |
ReturnFields | 결과에 포함할 필드(예: ["Name", "Price"] 또는 모두에 대해 ["*"]) |
Operator | 필터를 결합하기 위한 논리 연산자(And 또는 Or) |
FilteringOperands | 조건을 정의하는 QueryFilter 객체의 배열 |
QueryFilter 클래스
개별 필터링 조건을 나타냅니다:
public class QueryFilter
{
// 기본 조건
public string? FieldName { get; set; }
public bool? IgnoreCase { get; set; }
public QueryFilterCondition? Condition { get; set; }
public object? SearchVal { get; set; }
public Query? SearchTree { get; set; }
// And/Or
public FilterType? Operator { get; set; }
public QueryFilter[] FilteringOperands { get; set; }
}
QueryFilterCondition 클래스
사용 가능한 필터링 조건을 정의합니다:
public class QueryFilterCondition
{
public string Name { get; set; }
public bool IsUnary { get; set; }
public string IconName { get; set; }
}
참조는 NorthwindAPI QueryBuilder Models를 참조하세요.
3단계: QueryExecutor 구현
QueryExecutor 클래스는 Query 객체를 처리하고 이를 IQueryable 데이터 원본에 대해 실행하기 위한 LINQ 표현식으로 변환합니다.
private static Expression BuildConditionExpression<TEntity>(
DataContext db,
IQueryable<TEntity> source,
QueryFilter filter,
ParameterExpression parameter)
{
if (filter.FieldName is not null && filter.Condition is not null)
{
var property = source.ElementType.GetProperty(
filter.FieldName,
BindingFlags.IgnoreCase | BindingFlags.Public | BindingFlags.Instance)
?? throw new InvalidOperationException($"Property '{filter.FieldName}' not found");
var field = Expression.Property(parameter, property);
var targetType = property.PropertyType;
var searchValue = GetSearchValue(filter.SearchVal, targetType);
Expression condition = filter.Condition.Name switch
{
"null" => Expression.Equal(field, Expression.Constant(null)),
"notNull" => Expression.NotEqual(field, Expression.Constant(null)),
"empty" => Expression.Equal(field, Expression.Constant(string.Empty)),
"notEmpty" => Expression.NotEqual(field, Expression.Constant(string.Empty)),
"equals" => Expression.Equal(field, searchValue),
"doesNotEqual" => Expression.NotEqual(field, searchValue),
"inQuery" => BuildInExpression(db, filter.SearchTree, field),
"notInQuery" => Expression.Not(BuildInExpression(db, filter.SearchTree, field)),
"contains" => CallContains(field, searchValue),
"doesNotContain" => Expression.Not(CallContains(field, searchValue)),
"startsWith" => CallStartsWith(field, searchValue),
"endsWith" => CallEndsWith(field, searchValue),
"greaterThan" => Expression.GreaterThan(field, searchValue),
"lessThan" => Expression.LessThan(field, searchValue),
"greaterThanOrEqualTo" => Expression.GreaterThanOrEqual(field, searchValue),
"lessThanOrEqualTo" => Expression.LessThanOrEqual(field, searchValue),
"before" => Expression.LessThan(field, searchValue),
"after" => Expression.GreaterThan(field, searchValue),
"today" => BuildTodayExpression(field),
"yesterday" => BuildYesterdayExpression(field),
"thisMonth" => BuildThisMonthExpression(field),
"lastMonth" => BuildLastMonthExpression(field),
"nextMonth" => BuildNextMonthExpression(field),
"thisYear" => BuildThisYearExpression(field),
"lastYear" => BuildLastYearExpression(field),
"nextYear" => BuildNextYearExpression(field),
"true" => Expression.Equal(field, Expression.Constant(true)),
"false" => Expression.Equal(field, Expression.Constant(false)),
_ => throw new NotImplementedException($"Condition not implemented: {filter.Condition.Name}"),
};
return condition;
}
else
{
// 중첩된 필터 그룹 처리
var subexpressions = filter.FilteringOperands?
.Select(f => BuildConditionExpression(db, source, f, parameter))
.ToArray();
if (subexpressions == null || !subexpressions.Any())
return Expression.Constant(true);
return filter.Operator == FilterType.And
? subexpressions.Aggregate(Expression.AndAlso)
: subexpressions.Aggregate(Expression.OrElse);
}
}
지원되는 필터 조건
두 구현 옵션 모두 다음 필터 조건을 지원하며, 이는 Angular 쿼리 빌더 컴포넌트(IgxQueryBuilderComponent)와 일치합니다:
문자열 조건
| 조건 | 설명 |
|---|---|
contains | 필드에 검색 값이 포함됨 |
doesNotContain | 필드에 검색 값이 포함되지 않음 |
startsWith | 필드가 검색 값으로 시작함 |
endsWith | 필드가 검색 값으로 끝남 |
equals | 필드가 검색 값과 같음 |
doesNotEqual | 필드가 검색 값과 같지 않음 |
empty | 필드가 비어 있음 |
notEmpty | 필드가 비어 있지 않음 |
null | 필드가 null임 |
notNull | 필드가 null이 아님 |
숫자 조건
| 조건 | 설명 |
|---|---|
equals | 필드가 검색 값과 같음 |
doesNotEqual | 필드가 검색 값과 같지 않음 |
greaterThan | 필드가 검색 값보다 큼 |
lessThan | 필드가 검색 값보다 작음 |
greaterThanOrEqualTo | 필드가 검색 값보다 크거나 같음 |
lessThanOrEqualTo | 필드가 검색 값보다 작거나 같음 |
empty | 필드가 비어 있음/0 |
notEmpty | 필드가 비어 있지 않음/0이 아님 |
null | 필드가 null임 |
notNull | 필드가 null이 아님 |
날짜/시간 조건
| 조건 | 설명 |
|---|---|
equals | 필드가 검색 값과 같음 |
doesNotEqual | 필드가 검색 값과 같지 않음 |
before | 필드가 검색 값보다 이전임 |
after | 필드가 검색 값보다 이후임 |
today | 필드가 오늘 날짜와 일치함 |
yesterday | 필드가 어제 날짜와 일치함 |
thisMonth | 필드가 현재 월 내에 있음 |
lastMonth | 필드가 이전 월 내에 있음 |
nextMonth | 필드가 다음 월 내에 있음 |
thisYear | 필드가 현재 연도 내에 있음 |
lastYear | 필드가 이전 연도 내에 있음 |
nextYear | 필드가 다음 연도 내에 있음 |
null | 필드가 null임 |
notNull | 필드가 null이 아님 |
부울 조건
| 조건 | 설명 |
|---|---|
true | 필드가 true임 |
false | 필드가 false임 |
null | 필드가 null임 |
notNull | 필드가 null이 아님 |
부분 쿼리 조건
| 조건 | 설명 |
|---|---|
inQuery | 필드 값이 부분 쿼리 결과에 있음 |
notInQuery | 필드 값이 부분 쿼리 결과에 없음 |
Angular 프론트엔드 통합
쿼리 빌더 API는 Ignite UI for Angular 쿼리 빌더 컴포넌트(IgxQueryBuilderComponent)와 원활하게 작동하도록 설계되었습니다. 컴포넌트는 예상 API 페이로드 형식과 일치하는 쿼리 구조를 생성합니다.
핵심 Angular 컴포넌트
IgniteUI/igniteui-angular 저장소에서:
import {
FilteringExpressionsTree,
FilteringLogic,
IgxQueryBuilderComponent,
IExpressionTree,
IgxNumberFilteringOperand,
IgxStringFilteringOperand,
IgxBooleanFilteringOperand,
IgxDateFilteringOperand,
IgxTimeFilteringOperand,
IgxDateTimeFilteringOperand
} from 'igniteui-angular';
예제: 쿼리 표현식 트리 만들기
// 엔터티 및 필드 정의
const entities = [
{
name: 'Products',
fields: [
{ field: 'productId', dataType: 'number' },
{ field: 'productName', dataType: 'string' },
{ field: 'unitPrice', dataType: 'number' },
{ field: 'discontinued', dataType: 'boolean' },
{ field: 'categoryId', dataType: 'number' }
]
},
{
name: 'OrderDetails',
fields: [
{ field: 'productId', dataType: 'number' },
{ field: 'quantity', dataType: 'number' },
{ field: 'discount', dataType: 'number' }
]
}
];
// 부분 쿼리를 사용한 복잡한 쿼리 빌드
const innerTree = new FilteringExpressionsTree(
FilteringLogic.And,
undefined,
'OrderDetails',
['productId']
);
innerTree.filteringOperands.push({
fieldName: 'quantity',
condition: IgxNumberFilteringOperand.instance().condition('greaterThanOrEqualTo'),
conditionName: 'greaterThanOrEqualTo',
searchVal: 10
});
const mainTree = new FilteringExpressionsTree(
FilteringLogic.And,
undefined,
'Products',
['*']
);
mainTree.filteringOperands.push({
fieldName: 'productId',
condition: IgxStringFilteringOperand.instance().condition('inQuery'),
conditionName: 'inQuery',
searchTree: innerTree
});
mainTree.filteringOperands.push({
fieldName: 'discontinued',
condition: IgxBooleanFilteringOperand.instance().condition('false'),
conditionName: 'false'
});
쿼리 빌더 컴포넌트 사용
<igx-query-builder
#queryBuilder
[entities]="entities"
[expressionTree]="expressionTree"
(expressionTreeChange)="onQueryChange($event)">
<igx-query-builder-header [title]="'Product Query Builder'">
</igx-query-builder-header>
</igx-query-builder>
예제: 부분 쿼리를 사용한 복잡한 쿼리
쿼리 페이로드
{
"filteringOperands": [
{
"fieldName": "categoryId",
"condition": {
"name": "equals",
"isUnary": false,
"iconName": "filter_equal"
},
"conditionName": "equals",
"searchVal": 1,
"searchTree": null,
"ignoreCase": true
},
{
"fieldName": "productId",
"condition": {
"name": "inQuery",
"isUnary": false,
"isNestedQuery": true,
"iconName": "in"
},
"conditionName": "inQuery",
"searchVal": null,
"searchTree": {
"filteringOperands": [
{
"fieldName": "quantity",
"condition": {
"name": "greaterThanOrEqualTo",
"isUnary": false,
"iconName": "filter_greater_than_or_equal"
},
"conditionName": "greaterThanOrEqualTo",
"searchVal": 10,
"searchTree": null,
"ignoreCase": true
},
{
"fieldName": "quantity",
"condition": {
"name": "lessThanOrEqualTo",
"isUnary": false,
"iconName": "filter_less_than_or_equal"
},
"conditionName": "lessThanOrEqualTo",
"searchVal": 15,
"searchTree": null,
"ignoreCase": true
}
],
"operator": 0,
"entity": "orderDetails",
"returnFields": [
"productId"
]
},
"ignoreCase": true
}
],
"operator": 0,
"entity": "products",
"returnFields": [
"productId",
"productName",
"supplierId",
"categoryId",
"quantityPerUnit",
"unitPrice",
"unitsInStock",
"unitsOnOrder",
"reorderLevel",
"discontinued"
]
}
생성된 SQL 출력
SELECT *
FROM products
WHERE categoryId = {{selectedCategory}}
AND productId IN (
SELECT productId
FROM orderDetails
WHERE quantity >= {{quantityGreaterThan}}
AND quantity <= {{quantityLessThan}}
)
API 엔드포인트
POST https://data-northwind.appbuilder.dev/QueryBuilder/ExecuteQuery
Content-Type: application/json
지역화 지원
Angular 쿼리 빌더 컴포넌트는 필터 조건 레이블에 대한 기본 제공 지역화 지원을 포함합니다. igniteui-angular 저장소는 다음을 포함한 여러 언어로 리소스 문자열을 제공합니다:
- 영어(EN) - 기본값
- 프랑스어(FR)
- 독일어(DE)
- 스페인어(ES)
- 이탈리아어(IT)
- 포르투갈어(PT)
- 폴란드어(PL)
- 스웨덴어(SV)
- 기타…
예제 리소스 문자열:
export const QueryBuilderResourceStringsEN: IQueryBuilderResourceStrings = {
igx_query_builder_filter_contains: 'Contains',
igx_query_builder_filter_doesNotContain: 'Does Not Contain',
igx_query_builder_filter_startsWith: 'Starts With',
igx_query_builder_filter_endsWith: 'Ends With',
igx_query_builder_filter_equals: 'Equals',
igx_query_builder_filter_doesNotEqual: 'Does Not Equal',
igx_query_builder_filter_greaterThan: 'Greater Than',
igx_query_builder_filter_lessThan: 'Less Than',
// ... 더 많은 문자열
};
