Skip to content

API 프로젝트를 위한 쿼리 빌더 지원

개요

이 가이드에서는 API 프로젝트에서 쿼리 빌더 모델 및 유틸리티를 구현하여 사용자 정의 쿼리를 활성화하는 방법을 설명합니다. 구현에는 컨트롤러 만들기, 쿼리 빌더 모델 정의, 그리고 이러한 쿼리에서 SQL 문을 실행하고 생성하기 위한 유틸리티 추가가 포함됩니다. 결과적인 사용자 지정을 통해 사용자는 부분 쿼리 지원, 필터링, 논리 연산자, 그리고 필드 선택을 포함한 복잡한 쿼리를 생성하여 데이터 원본에 대해 효율적으로 실행할 수 있습니다.

구현 옵션

API 프로젝트에서 쿼리 빌더 지원을 구현하는 두 가지 방식이 있습니다.

방식최고노력 수준
NuGet 패키지 (Infragistics.QueryBuilder.Executor)빠른 통합, 표준 사용 사례낮음
수동 구현전체 사용자 지정, 복잡한 요구 사항중간-높음

옵션 1: Infragistics.QueryBuilder.Executor NuGet 패키지 사용 (권장)

Infragistics.QueryBuilder.Executor 패키지는 기존 API 프로젝트에 최소한의 구성으로 직접 연결할 수 있는 즉시 사용 가능한 클래스, 조건 및 메서드를 제공합니다.

NuGet

전제 조건

  • .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',
    // ... 더 많은 문자열
};

추가 참조