웹 앱용 시각적 쿼리 빌더 설계

많은 비즈니스 사용자는 SQL 없이도 복잡한 필터가 필요합니다. 이 가이드는 UX 패턴, 안전한 쿼리 변환, 권한, 성능, 저장된 뷰를 다루고, 직접 시각적 쿼리 빌더를 만드는 데 쓸 수 있는 실전 예시와 YeshBe용 프롬프트도 제공합니다.

어느 순간이 되면 사용자는 단순한 검색 상자와 몇 개의 필터만으로는 부족해집니다. 고객을 행동으로 세분화하고, 아웃리치용 동적 리스트를 만들고, 기간을 비교하고, 특이 케이스를 제외하고, 팀과 공유할 수 있는 뷰를 저장하길 원하죠—그것도 SQL을 쓰지 않고요. 이런 때 필요한 것이 바로 시각적 쿼리 빌더입니다.

잘 만든 쿼리 빌더는 비기술 사용자도 복잡한 조건을 안전하게 표현할 수 있게 해주고, 엔지니어에게는 그 조건을 권한을 준수하고 효율적인 쿼리로 안정적으로 변환하는 방법을 제공합니다. 반대로 잘못 만들면 느리고 혼란스럽고 위험해집니다.

이 가이드는 웹 앱을 위한 견고한 시각적 쿼리 빌더의 아키텍처와 UX를 다룹니다—데이터 모델링, 연산자, 검증, 안전한 쿼리 변환, 성능 전략, 저장된 뷰 등. 또한 원하는 것을 자연어로 설명해 소프트웨어를 만들 수 있는 플랫폼인 YeshBe로 바로 시도해 볼 수 있는 실전 예시와 프롬프트도 제공합니다.

사용자가 풀고자 하는 문제에서 출발하세요

UI 컨트롤을 그리기 전에, 유연한 쿼리가 필요한 실제 업무 과제를 적어 보세요. 범용 SQL 프런트엔드를 만드는 게 아니라, 여러분의 도메인 언어를 제품에 녹여내는 일입니다.

  • CRM 세그먼트: “유럽 거주, 최근 90일 주문 없음, LTV 500달러 이상, 마케팅 수신 동의한 활성 고객을 보여줘.”
  • 주문 운영: “지난주에 생성된 주문 중 라인 아이템에 품절이 하나라도 있고 배송이 익스프레스로 지정된 것.”
  • 재고: “상태가 Discontinued 또는 Archived이고, 최근 180일 동안 판매가 없으며, 현재 수량이 재주문 임계값 <= 인 상품.”
  • 지원: “우선순위 High, 24시간 응답 없음, SRE 팀에 배정되지 않은 티켓.”
  • 애널리틱스: “디바이스가 모바일이고 AND (source에 ‘ads’가 포함 OR utm_campaign이 [spring, summer]에 포함)인 세션.”

이런 예시는 필요한 데이터 필드, 흔히 쓰는 연산자, 타입(날짜, 숫자, enum), 중첩(AND/OR 그룹)을 드러냅니다. 또한 “주문” 안의 “라인 아이템”, “조직” 안의 “팀”처럼 관계도 암시합니다.

쿼리 어휘 정의: 필드, 타입, 연산자

쿼리 빌더의 강력함과 안전성은 제약된 어휘에서 나옵니다. 선택 가능한 모든 필드는 시스템이 알고 있고, 타입이 정해져 있으며, 특정 연산자와 검증 규칙에 매핑되어야 합니다.

필드 카탈로그

  • 필드 이름과 라벨(예: customer.last_name → “성”)
  • 타입: string, text, number, boolean, date, datetime, enum, array, reference/relationship, JSON
  • 타입별 사용 가능 연산자(예: 문자열: contains/starts with/equals; 숫자: =, ≠, >, ≥, <, ≤; 날짜: before/after/between/relative)
  • 널 허용 여부와 널 처리 의미(“비어 있음”, “비어 있지 않음”)
  • 현지화: 정렬(collation), 대소문자 민감도, datetime의 타임존
  • 권한: 누가 이 필드를 조회할 수 있는지; 마스킹 가능 여부(예: PII)

타입별 연산자 설계

  • 문자열: 포함, 포함하지 않음, 같음, 같지 않음, ~로 시작, ~로 끝남, 목록에 포함, 목록에 불포함, 비어 있음, 비어 있지 않음
  • 숫자: 같음, 같지 않음, 초과, 이상, 미만, 이하, 구간(between), 목록에 포함
  • 불리언: true, false, 비어 있음(Nullable일 때), 비어 있지 않음
  • 날짜/DateTime: 이전, 이후, 해당일, 구간; “지난 N일”, “다가올 N주”, “오늘”, “이번 달”, “이전 분기” 같은 상대 연산자
  • Enum: 같음, 같지 않음, 목록에 포함, 목록에 불포함
  • 배열: 값 포함, 다음 중 하나 포함, 모두 포함, 길이 같음/초과
  • 관계: 관련 레코드가 [서브쿼리]와 일치함; 관련 레코드 개수 [연산자] [값]

연산자는 도메인에 맞게 유지하세요. 예를 들어 “LTV between”는 타당하지만 “LTV contains”는 아닙니다. UI에서 잘못된 조합은 비활성화하세요.

누구나 접근하기 쉬운 쿼리 빌딩 UX 패턴

1) 조합 가능한 조건과 그룹

조건은 행(row) 기반으로, AND/OR가 가능한 중첩 그룹을 허용하세요. 그룹의 시각적 구분이 핵심입니다. 사용자가 괄호를 떠올리지 않아도 우선순위를 이해할 수 있어야 합니다.

  • 조건 행: [필드] [연산자] [값(들)]
  • 그룹 컨트롤: 조건 추가, 그룹 추가, 그룹 단위 AND/OR 토글
  • 들여쓰기와 은은한 테두리로 중첩을 표시

2) 타입 인지 입력 컴포넌트

  • 문자열: 텍스트 입력 + 선택적 대소문자 구분 토글
  • 숫자: 최소/최대 제약이 있는 숫자 입력; “between”일 때는 두 개 입력
  • 날짜: 캘린더 피커; 상대 날짜 프리셋(예: 최근 7/30/90일)
  • Enum: “목록에 포함”일 때 멀티셀렉트 칩이 있는 드롭다운
  • 불리언: 라디오 버튼(true/false) + 필요 시 “비어 있음”
  • 배열: 토큰화 입력, 필요 시 드래그로 순서 변경

3) 필드 탐색과 검색

필드가 많다면 검색과 카테고리(“Customer”, “Order”, “Billing”)를 제공하세요. 필드에 마우스를 올리면 설명과 예시를 보여주고, 권한이 없는 필드는 숨기세요.

4) 실시간 피드백

  • 결과 개수를 미리 보여주는 디바운스된 “일치 항목 수”
  • 잘못된 조합이나 값 타입에 대한 인라인 검증
  • 비용이 큰 쿼리에 대한 경고(“큰 날짜 범위에서는 느릴 수 있습니다”)

5) 막다른 길이 아닌 가드레일

  • 안전한 기본값 제공(예: 날짜 기준 엔터티는 “최근 30일”)
  • 제출 후 실패시키기보다, 잘못된 연산자는 회색 처리로 비활성화
  • 왜 잘못됐는지 설명(“숫자에는 ‘contains’를 쓸 수 없습니다”)

6) 쿼리를 설명하세요

빌더 옆에 “일반어 설명” 요약을 보여주세요. 파워 유저를 위해 읽기 전용 텍스트 DSL이나 “생성된 SQL 보기”(비밀값 마스킹)를 제공하면 신뢰 형성과 지원에 도움이 됩니다.

뷰 저장, 공유, 관리

사용자는 쿼리를 한 번만 만들지 않습니다. 쿼리를 수명주기와 권한이 있는 1급 아티팩트로 취급하세요.

  • 뷰 저장 및 이름 지정; 즐겨찾기 고정
  • 개인/팀 공개 범위; 읽기 전용 공유 뷰
  • 공통 세그먼트를 위한 템플릿 갤러리(“고가치·이탈 위험”, “최근 7일 응답 없음”)
  • 민감한 뷰에 대한 버전 관리 또는 변경 이력
  • 파라미터화 가능한 뷰(예: 실행 시 N을 선택하는 “최근 N일”)

저장된 뷰는 원시 텍스트나 인터폴레이션된 SQL이 아닌, 직렬화되고 검증된 객체(AST)로 표현하세요. 이렇게 하면 UI 변화에도 안정적이고, 환경 간 안전하게 이식됩니다.

보안: 설계 자체로 안전하게

쿼리 빌더는 설계 차원에서 취약점 클래스 전체를 예방해야 합니다—특히 인젝션 위험, 무제한 필드를 통한 데이터 유출, 행 수준 권한 회피 등.

  • 서버 사이드 평가만. 클라이언트에서 사용자 작성 SQL을 실행하지 마세요. 클라이언트는 검증되고 타입이 명확한 구조(AST)를 보내고, 서버가 이를 파라미터라이즈드 쿼리로 변환합니다.
  • 필드 수준 권한. 사용자는 권한이 있는 필드만 보고, 그 필드와 역할에 타당한 연산자만 사용할 수 있어야 합니다.
  • 행 수준 보안. 테넌시 및 레코드별 규칙은 빌더 외부에서 강제하세요. 빌더는 기본 접근 규칙을 대체하지 않고 보강해야 합니다.
  • 파라미터라이즈. 항상 파라미터라이즈드 쿼리로 컴파일하고, 값을 SQL 문자열에 연결하지 마세요.
  • 복잡도 제한. 그룹 최대 깊이, 조건 수, 날짜 범위, 목록 크기에 상한을 두어 성능을 보호하세요.
  • 시간 및 행 수 제한. 기본 타임아웃과 행 수 캡을 두고, 큰 결과셋에는 페이지네이션을 권장하세요.

UI에서 쿼리까지: 안정적인 AST 설계

견고한 빌더의 핵심은 쿼리의 중간 표현입니다. 필드, 연산자, 값, 그룹핑, 메타데이터(예: 타임존)를 담는 추상 구문 트리(AST)라고 생각하세요.

{ "type": "group", "op": "AND", "children": [ { "type": "condition", "field": "customer.country", "operator": "in", "value": ["DE", "FR", "ES"] }, { "type": "group", "op": "OR", "children": [ { "type": "condition", "field": "order.last_order_at", "operator": "lt_relative_days", "value": 90, "timezone": "Europe/Berlin" }, { "type": "condition", "field": "customer.ltv", "operator": "gte", "value": 500 } ] }, { "type": "condition", "field": "customer.marketing_opt_in", "operator": "eq", "value": true } ] }

이 구조를 서버 사이드에서 필드 카탈로그에 따라 검증하세요. 필드 존재 여부, 필드 타입에 허용되는 연산자인지, 값이 규격에 맞는지를 확인하고, 변환 전에 잘못된 구조는 거부하거나 교정합니다.

AST를 SQL(또는 데이터 저장소)로 변환

검증이 끝났다면 AST를 안전하고 효율적인 쿼리로 컴파일하세요. 다음 패턴이 도움이 됩니다.

1) 쿼리 빌더로 파라미터라이즈드 SQL 작성

파라미터라이즈, 조인, 서브쿼리를 지원하는 서버 사이드 쿼리 빌더나 ORM을 사용하세요. 각 조건을 절로, 각 그룹을 괄호 있는 AND/OR 시퀀스로 컴파일합니다.

-- Pseudocode for a simple compiler function compile(node): if node.type == 'condition': fieldInfo = catalog.get(node.field) col = fieldInfo.columnRef switch node.operator: case 'eq': return (col + ' = ?'), [node.value] case 'in': return (col + ' = ANY(?)'), [node.value] case 'contains': return (col + ' ILIKE ?'), ['%' + node.value + '%'] case 'lt_relative_days': return (col + ' < ?'), [now() - interval(node.value, 'days')] ... else if node.type == 'group': parts = [] params = [] for child in node.children: sql, p = compile(child) parts.append('(' + sql + ')') params.extend(p) return parts.join(' ' + node.op + ' '), params

여기서는 타임존 처리, 널 의미, 관계 매핑 같은 세부 사항을 생략했습니다. 실제 구현에서는 주의 깊은 매핑이 필요합니다.

2) 관계: JOIN과 EXISTS

관계를 가로지르는 조회에서는 EXISTS 서브쿼리나 범위가 잘 제한된 JOIN을 선호하세요.

  • 1:N: “라인 아이템 중 재고가 없는 항목이 하나라도 있는 주문” → EXISTS (SELECT 1 FROM line_items WHERE line_items.order_id = orders.id AND line_items.in_stock = false)
  • N:M: “태그가 [VIP, Partner]에 포함된 고객” → 브리지 테이블을 통한 조인 또는 브리지에 대한 EXISTS 사용.
  • 개수 조건: “지원 티켓이 >= 3개인 고객” → COUNT가 있는 서브쿼리와 HAVING, 또는 상관 서브쿼리.

3) Null과 빈 값

명확하게 정의하세요: 문자열의 “비어 있음”은 종종 IS NULL OR value = ''를 의미하고, 다른 타입은 보통 IS NULL입니다. 선택을 문서화하고 일관성을 유지하세요.

4) 문자열 매칭과 인덱스

ILIKE 같은 대소문자 무시 연산은 느릴 수 있습니다. 다음을 고려하세요:

  • 소문자화 + 함수 인덱스(LOWER(column))
  • contains류 매칭을 위한 trigram 인덱스
  • 풀텍스트 검색은 전용 검색 엔진에 위임하되, FTS 대상 필드에 한정

5) JSON과 반정형 데이터

동적 속성을 JSON에 저장한다면, 조회 가능한 키를 제한하고 안전한 경로 표현식을 생성하세요. 인기 속성은 성능을 위해 타입이 있는 컬럼으로 미리 계산하세요.

빠른 응답을 위한 성능 전략

  • 엔터티별로 가장 많이 조회되는 10–20개 필드를 인덱싱. 흔한 필터 쌍(status + created_at)에 대한 복합 인덱스.
  • 빈번한 조건(예: active = true)에 대한 부분 인덱스.
  • 무거운 집계를 위한 머티리얼라이즈드 뷰; 스케줄 또는 변경 이벤트로 갱신.
  • last_activity_at, 카운트, 플래그를 비정규화해 흔한 조건을 가속.
  • 페이지네이션과 선택 컬럼 제한; SELECT * 지양.
  • 카운트와 공통 세그먼트는 캐시하고, 쓰기 시 무효화 또는 짧은 TTL 사용.
  • 쿼리 플랜을 관찰; 필요한 경우에만 힌트 추가(지원되는 범위 내).

쿼리가 비쌀 가능성이 있으면 일찍 경고하세요(예: “8천만 행 전체 스캔—날짜 필터 추가를 고려하세요”). 조용한 타임아웃보다 가이던스를 선호하세요.

권한과 데이터 프라이버시 심화

아무리 훌륭한 빌더라도 잘못된 데이터를 노출하면 실패입니다. 여러 레이어를 결합하세요.

  • 역할/정책별 필드 기능 맵: 읽기, 필터링 가능, 집계 가능.
  • 행 수준 정책(예: tenant_id = current_tenant)은 빌더와 무관하게 항상 적용.
  • PII 마스킹: 이메일 등은 정확한 값이 유출되지 않도록 허용된 방식으로만 필터(예: “비어 있음” 또는 “도메인 같음”).
  • 감사 로그: 누가 어떤 저장된 뷰나 애드혹 쿼리를 실행했고 어떤 필드를 썼는지 기록.

테스트: 정확성, 안전성, 회귀 방지

  • 연산자 매핑에 대한 단위 테스트(입력 → SQL/파라미터), 널 의미 포함.
  • 복잡한 AST의 골든 테스트: 컴파일 결과를 스냅샷해 안정성 보장.
  • 권한 테스트: 제한 필드 금지, 행 수준 가드가 항상 추가되는지 확인.
  • 퍼즈 테스트: 유효/무효 AST를 무작위 생성해 컴파일러가 절대 안전하지 않은 SQL을 만들지 않음을 보장.
  • 대표 데이터셋에서의 성능 테스트; 연산자/필드별 p95 지연 시간 추적.

접근성 및 현지화

  • 조건 추가/삭제 및 AND/OR 토글에 키보드 우선 상호작용 제공.
  • 스크린 리더 라벨은 조건 의미를 반영(“필드 ‘Status’, 연산자 ‘equals’, 값 ‘Open’”).
  • 날짜 피커는 로케일 형식과 타임존을 존중; 서버는 UTC로 저장/연산.
  • 숫자 포맷은 로케일에 따라 “1,234.56”과 “1.234,56” 모두 허용하되, 서버에서 안전하게 정규화.

흔한 엣지 케이스와 처리 방법

  • 빈 그룹: no-op으로 처리하거나 저장 불가; 명확한 경고 표시.
  • 깊게 중첩된 로직: 중첩 깊이에 상한; 여러 저장 뷰로 분할 권장.
  • 큰 “목록 포함” 값: 제한(예: 500개) 도입, 서버 사이드로 매핑하는 리스트 업로드 유도.
  • 서머타임(DST)을 넘는 상대 날짜: 타임존 인지 라이브러리로 계산; 투명성을 위해 평가된 정확한 범위 표시.
  • 배열 vs 문자열: “contains” 혼동 방지. 배열의 “값 포함”은 멤버십, 문자열의 “포함”은 서브스트링입니다.

버저닝과 진화

데이터 모델은 변합니다. 저장된 뷰의 안정성을 지키세요.

  • 내부적으로 안정적인 필드 ID; 라벨은 변경되어도 저장된 뷰가 깨지지 않게.
  • 사용 중단 필드/연산자를 새 등가물로 매핑하는 마이그레이션; 사용자 주의가 필요한 뷰는 표시.
  • 미래 호환성을 위한 AST 스키마 버저닝.

개선을 이끄는 텔레메트리

  • 가장 많이 쓰인 필드와 연산자 → 사전 인덱싱 및 UI 노출 후보
  • 검증 실패 → 가드레일과 메시지 개선
  • 느린 쿼리 → 비정규화나 머티리얼라이즈드 뷰 도입 판단 근거
  • 빌더 세션 이탈 → UX 마찰 지점 분석

모든 것을 합치기: 엔드 투 엔드 예시

CRM에 연락처용 “세그먼트 빌더”가 필요하다고 가정해 봅시다. 핵심 필드는 다음과 같습니다.

  • contact.email(string, 마스킹 가능), contact.country(enum), contact.tags(enum 배열), contact.created_at(datetime)
  • engagement.last_open_at(datetime), engagement.open_count_30d(숫자)
  • account.plan(enum), account.mrr(숫자)

쿼리: “EU 국가의 연락처 중, 최근 90일 내 생성되고, open_count_30d가 >= 2이며, account plan이 [Pro, Enterprise]에 포함된 대상.”

{ "type": "group", "op": "AND", "children": [ { "type": "condition", "field": "contact.country", "operator": "in", "value": ["DE", "FR", "ES", "IT"] }, { "type": "condition", "field": "contact.created_at", "operator": "gte_relative_days", "value": 90 }, { "type": "condition", "field": "engagement.open_count_30d", "operator": "gte", "value": 2 }, { "type": "condition", "field": "account.plan", "operator": "in", "value": ["Pro", "Enterprise"] } ] }

컴파일 시 고려사항:

  • contacts → accounts를 account_id로 조인하여 plan을 조회.
  • open_count_30d는 미리 계산하거나 인덱싱되어 있어야 함.
  • 모든 테이블에 기본 정책 tenant_id = :tenant 적용.
  • 상대 날짜는 NOW() - INTERVAL '90 days'와 같이 안전하게 바인딩해 파라미터화.
SELECT c.id, c.first_name, c.last_name, c.country, a.plan FROM contacts c JOIN accounts a ON a.id = c.account_id WHERE c.tenant_id = $1 AND c.country = ANY($2) AND c.created_at >= (NOW() AT TIME ZONE 'UTC' - INTERVAL '90 days') AND c.engagement_open_count_30d >= $3 AND a.plan = ANY($4) ORDER BY c.created_at DESC LIMIT 100 OFFSET 0;

파라미터 플레이스홀더의 사용과 안전하며 제한된 컬럼 선택에 주목하세요.

YeshBe로 시도해 볼 수 있는 프롬프트

YeshBe는 원하는 것을 설명하고 AI와 함께 반복하면서 소프트웨어를 만드는 플랫폼입니다. 쿼리 빌더의 스캐폴드를 요청한 뒤, 필드·연산자·검증·쿼리 변환을 점진적으로 다듬을 수 있습니다. 다음은 시작점입니다:

우리 CRM 앱에 비기술 사용자도 country(enum), plan(accounts 테이블의 enum), created_at(date/relative), tags(array), engagement_open_count_30d(number)로 연락처를 필터링할 수 있는 “세그먼트 빌더” 화면을 추가해 주세요. AND/OR 그룹, 저장된 뷰(개인 및 팀), 디바운스된 일치 개수를 지원합니다.

검증된 JSON AST 조건을 Postgres용 파라미터라이즈드 SQL로 변환하는 서버 사이드 컴파일러를 만드세요. tenant_id 격리, 필드 수준 권한, 쿼리당 최대 50개 조건을 강제하고, 플레이스홀더가 있는 쿼리 문자열과 params 배열을 반환합니다.

잘못된 연산자/필드 조합(예: 숫자에 대한 “contains”)을 방지하는 검증을 추가하세요. 날짜는 “지난 N일” 같은 상대 연산자를 지원하고, 제공된 타임존을 사용해 서버에서 UTC 기준으로 계산합니다.

{ "type": "group", "op": "OR", "children": [ { "type": "condition", "field": "order.status", "operator": "eq", "value": "pending" }, { "type": "condition", "field": "order.expected_ship_at", "operator": "lt_relative_days", "value": 2 } ] }

AST를 사람이 읽을 수 있는 문장으로 변환하는 “쿼리 설명(Explain)” 패널을 구현하세요(예: “status가 ‘pending’이거나 예상 배송일이 향후 2일 이내인 주문”).

대화를 통해 반복하세요: 필드를 추가하고, 연산자를 다듬고, UI를 조정하고, 실제 데이터셋으로 테스트합니다. YeshBe는 사전 제작 모듈 모음이 아니라 소프트웨어를 만드는 플랫폼이므로, 여러분이 어휘, 권한, 데이터 모델을 주도적으로 통제할 수 있습니다.

롤아웃 계획: 가치를 일찍 제공하고 점진적으로 심화

  1. 1단계: 핵심 필드와 단순 AND 로직; 개인용 저장 뷰; 안전한 기본값(예: 최근 30일).
  2. 2단계: OR 그룹, 상대 날짜, 팀 공유 뷰 추가; 텔레메트리 계측.
  3. 3단계: 관계 조건(EXISTS), 개수 기반 필터; 성능 경고 도입; 핫 필드 인덱싱.
  4. 4단계: 템플릿, 버저닝, 파라미터화된 저장 뷰; “설명(Explain)” 패널과 선택적 보기 전용 SQL.

이 단계적 접근은 컴파일러와 권한 강화를 개발하는 동안에도 사용자에게 빠르게 유용성을 제공합니다.

체크리스트: “좋은”의 기준

  • 선택 가능한 모든 필드는 타입이 정의되고, 문서화되어 있으며, 권한이 부여됨.
  • 타입별로 의미 있는 연산자만 제공; 잘못된 조합은 UI에서 불가능.
  • 쿼리는 검증된 AST에서 파라미터라이즈드 스테이트먼트로 컴파일됨.
  • 테넌트 및 행 수준 정책이 모든 쿼리에 자동 적용됨.
  • 복잡도 제한과 타임아웃으로 성능 보호.
  • 저장된 뷰는 원시 SQL이 아닌 버전이 있는 아티팩트임.
  • 사용자는 즉각적 피드백(카운트, 경고, 명확한 검증)을 얻음.
  • 텔레메트리가 인덱싱, 비정규화, UX 개선을 이끔.

마무리 생각

시각적 쿼리 빌더는 단일 컴포넌트가 아니라, 제품 언어·데이터 모델링·권한·성능 간의 계약입니다. 도메인의 어휘를 안전하고 표현력 있는 빌더로 인코딩하면, 보안이나 속도를 해치지 않고도 사용자에게 분석적 슈퍼파워를 줄 수 있습니다. 실제 업무에서 출발하고, 어휘를 제한하며, 안전한 쿼리로 컴파일하고, 공개적으로 반복하세요. 그 결과는 리포팅, 운영, 자동화 전반에서 오래도록 가치를 창출하는 역량이 됩니다.

가장 먼저 무엇을 만들어 볼까요?

한 문장으로 시작하세요. 결과를 확인한 뒤 원하는 부분을 자유롭게 바꿀 수 있습니다.

무료로 시작하세요. 신용카드는 필요하지 않습니다.