[KQL] 파이프 하나로 흘려보내는 쿼리.. KQL

KQL이란 무엇인가?

KQL(Kusto Query Language)은 Azure Data Explorer(ADX)에서 데이터를 조회하기 위한 전용 쿼리 언어이다.
Micorsoft가 만들었고, 대규모 로그 데이터와 시계열 데이터를 빠르게 검색·집계하는데 최적화되어 있다.

💡 비유
SQL이 MSSQL에서 데이터를 꺼내는 언어라면, KQL은 ADX에서 데이터를 꺼내는 언어이다.
둘 다 "데이터를 조회하는 언어"라는 점은 같지만, 문법 구조가 완전히 다르다.

SQL과 KQL의 구조적 차이

SQL은 "내가 원하는 것을 선언"하는 구조이다.
SELECT, FROM, WHERE을 한꺼번에 적어서 제출하는 주문서 방식이다.
반면 KQL은 "데이터를 파이프라인으로 흘려보내는" 구조이다.
파이프( | )를 통해 데이터를 한 단계씩 가공하면서 아래로 흘려보낸다.

-- SQL
SELECT name, age
FROM users
WHERE age > 20
ORDER BY age


-- KQL
users
| where age > 20
| project name, age
| sort by age

 

💡 비유
SQL은 주문서를 한 장 작성해서 한꺼번에 내미는 느낌이고, KQL은 공장 컨베이어 벨트처럼 데이터를 위에서 올려놓고 한 단계씩 가공하면서 아래로 흘려보내는 느낌이다.

구분	SQL (MSSQL)	KQL (ADX)
읽는 순서	SELECT → FROM → WHERE (실행 순서와 다름)	위에서 아래로 순서대로 (직관적)
구분자	없음 (절 키워드로 구분)	파이프 | 로 단계 구분
컬럼 선택	SELECT	project
필터	WHERE	where
정렬	ORDER BY	osrt by
주요 용도	관계형 DB 조회/조작 (CRUD)	대규모 로그 / 시계열 데이터 분석

왜 ADX에서 SQL 대신 KQL을 쓸까?

ADX가 다루는 데이터는 대부분 로그 데이터이다.
로그는 양이 어마어마하고, 시간 순서대로 쌓이며, 대부분 읽기 전용(INSERT만 있고 UPDATE/DELETE가 거의 없음)이다.
KQL은 이런 로그 데이터를 빠르게 검색하고 집계하는 데 최적화되어 있다.

관점	SQL (MSSQL)	KQL (ADX)
설계 목적	정형 데이터 관리 (CRUD 모두)	대규모 로그 / 시계열 데이터 읽기 특화
데이터 저장	행(Row) 기반 저장	열(Column) 기반 저장 → 집계에 유리
수억 건 집계	느려질 수 있음	수초 내 가능
UPDATE / DELETE	✅ 자유롭게 가능	❌ 거의 불가 (로그는 쌓기만 하니까 OK)

✅ 참고
열(Column) 기반 저장이 왜 빠를까?
"오늘 에러 로그가 몇 건이야?" 같은 질문에서, 행 기반(SQL)은 모든 행을 읽으면서 해당 컬럼을 확인한다.
열 기반(KQL/ADX)은 필요한 컬럼만 쭉 읽고 나머지는 아예 안본다.
데이터가 클수록 차이가 극적이다.

💡 한 줄 정리 : SQL은 만능 도구(스위스 아미 나이프), KQL은 로그 분석 전용 고성능 도구. 용도에 맞게 쓰는 것!

 

 

KQL의 핵심 원리 - 컨베이어 벨트 구조

KQL 문법을 배우기 전에, 모든 KQL 쿼리가 따르는 하나의 원리를 먼저 이해해야 한다.

💡 비유
KQL은 컨베이어 벨트 구조이다.
데이터를 맨 위에 올려놓고, 파이프( | )를 통해 한 단계씩 가공하면서 아래로 흘려보낸다.
위에서 아래로 읽으면 그대로 실행 순서!

SQL과 달리 읽는 순서 = 실행 순서이기 때문에 훨씬 직관적이다.
이 원리만 기억하면 어떤 KQL 쿼리든 위에서 아래로 읽으면 된다.

 

 

기초 문법 - 기본 조회

테이블 조회

테이블 이름만 쓰면 전체 데이터가 조회된다.
SQL의 SELECT * FROM 과 동일하다.

-- SQL
SELECT *
FROM StormEvents


-- KQL
StormEvents

where - 필터링

조건에 맞는 행만 걸러낸다.

-- SQL
SELECT *
FROM StormEvents
WHERE State = 'TEXAS'


-- KQL
StromEvents
| where State == "TEXAS"

연산자	의미	주의사항
=	같다	SQL은 =, KQL은 ==
≠	같지 않다
>, <, ≤, ≥	숫자 비교	SQL과 동일
and / or	조건 조합	SQL의 AND, OR과 동일
문자열 따옴표	큰따옴표 " "	SQL은 작은따옴표 ' ', KQL은 큰따옴표가 기본

여러 조건을 조합할 때는 한 줄에 and / or로 쓰거나, where를 여러 줄로 나눠도 된다.

-- 한 줄에 작성
StormsEvents
| where State == "TEXAS" and EventType == "Flood"


-- 여러 줄로 분리 (가독성 좋음)
StormEvents
| where State == "TEXAS"
| where EventType == "Flood"

project - 컬럼 선택

보고 싶은 컬럼만 골라서 결과에 표시한다.

-- SQL
SELECT EventType, StartTime
FROM StormEvents


-- KQL
StormEvents
| project EventType, StartTime

명령어	역할	설명
project	지정 컬럼만 표시	나머지 컬럼은 모두 제거됨
project-away	지정 컬럼만 제외	나머지 컬럼은 전부 유지
project-rename	컬럼 이름 변경	기존 구조 유지하면서 이름만 바꿈
extend	새 컬럼 추가	기존 컬럼 유지 + 새 컬럼 추가

extend는 특히 자주 쓰이는데, SQL의 SELECT *, 계산식 AS 별명 과 같은 역할이다.

StromEvents
| extend DamageTotal = DamageProperty + DamageCrops

sort by - 정렬

-- SQL
SELECT *
FROM StormEvents
ORDER BY DamageProperty DESC


-- KQL
StormEvents
| sort by DamageProperty desc

take / limit - 개수 제한

SQL의 SELECT TOP N 과 동일하다.
take와 limit은 완전히 같은 동작이다.

-- SQL
SELECT TOP 10 *
FROM StormEvents


-- KQL
StormEvents
| take 10

summarize - 집계 (가장 중요)

KQL의 꽃이다.
SQL의 GROUP BY + 집계 함수와 같은 역할인데, 문법이 더 간결하다.

-- SQL
SELECT  State
	,	COUNT(*)
FROM StormEvents
GROUP BY State


-- KQL
StormEvents
| summarize count() by State

KQL 함수	SQL 대응	설명
count()	COUNT(*)	행 수
sum(col)	SUM(col)	합계
avg(col)	AVG(col)	평균
min(col) / max(col)	MIN / MAX	최솟값 / 최댓값
dcount(col)	COUNT(DISTINCT col)	고유값 수
countif(col)	없음 (CSAE WHEN 필요)	조건에 맞는 행만 카운트

countif는 SQL에는 없는 KQL만의 편리한 함수이다.
SQL에서 SUM(CASE WHEN ... THEN 1 ELSE 0 END) 로 써야 하는 것을 한 단어로 해결한다.

StormEvents
| summarize
	TotalEvents = count(),
    FloodEvents = countif(EventType == "Flood")
    by State

시간 관련 - 로그 분석의 핵심

로그 데이터에서 시간 다루는 일은 필수이다.
KQL은 시간 처리가 특히 강력하다.

-- SQL
SELECT *
FROM StormEvents
WHERE  StartTime > DATEADD(DAY, -7, GETDATE())


-- KQL
StormEvents
| where StartTime > ago(7d)

시간 표현	의미
ago(1h)	1시간 전
ago(30m)	30분 전
ago(7d)	7일 전

bin( ) 함수를 쓰면 시간 단위로 집계할 수 있다.
SQL에서 날짜를 잘라서 GROUP BY 하려면 CAST나 CONVERT가 필요하지만, KQL은 bin( ) 하나면 끝이다!

 

 

중급 문법 - 변수, 범위, 타입

let - 변수 선언

KQL에서 가장 자주 쓰이는 문법 중 하나이다.
값이나 쿼리 결과에 이름을 붙여서 재사용할 수 있다.

💡 비유
요리 시작 전에 재료를 미리 손질해서 그릇에 담아두는 것이다.
양파는 여기, 마늘은 저기 - 미리 준비해놓으면 본 요리에서 바로 꺼내 쓸 수 있다.

-- 단순 값 저장
let targetDate = datetime('2024-06-01');
let maxCount = 100;


-- 쿼리 결과를 변수에 저장 (가장 강력한 기능!)
let errorLogs = 
	AppLogs
    | where Level == "Error"
    | where Time > ago(1d);


errorLogs
| summarize count() by ServiceName

 

⚠️ 주의
let 문은 반드시 세미콜론( ; )으로 끝나야 한다.
안 붙이면 에러가 발생한다.

✅ 참고
SQL의 CTE( WITH 문 )와 가장 비슷하지만, CTE는 바로 다음 SELECT에서만 쓸 수 있는 반면 let 은 여러 번 재사용 가능하다.
"CTE의 편리함 + 임시 테이블의 재사용성" 을 합친 것이라고 생각하면 된다.

datatable - 임시 테이블 만들기

DB에 없는 데이터를 코드 안에서 직접 만들어 쓸 수 있다.

let targets = datatable (Deviced:string) [
	"SRV-01",
    "SRV-02",
    "SRV-03"
];

in - 목록 포함 필터

-- 직접 목록 지정
AppLogs
| where ServiceName in ("Auth", "Payment")


-- 변수(서브쿼리)와 함께 사용
AppLogs
| where Deviced in (targets | project DeviceId)


-- 반대 - 포함되지 않는 것
AppLogs
| where Servicename !in ("Auth", "Payment")

between - 범위 필터

AppLogs
| where Time between (datetime('2024-06-01') .. datetime('2024-06-30'))


-- 숫자에도 사용 가능
| where DamageProperty between (100 .. 500)

 

✅ 포인트
between 문법은 괄호 ( ) 와 점 두 개 .. 를 함께 써야 한다.
between (A .. B) → A 이상 B 이하.

타입 변환 함수

KQL은 데이터 타입에 민감하다.
JSON에서 꺼낸 값은 dynamic 타입이라 비교하려면 변환이 필요하다.

KQL 함수	SQL 대응	역할
tostring(값)	CAST(값 AS NVARCHAR)	문자열로 변환
toint(값)	CAST(값 AS INT)	정수로 변환
tolong(값)	CAST(값 AS BIGINT)	큰 정수로 변환
todouble(값)	CAST(값 AS FLOAT)	실수로 변환
todatetime(값)	CAST(값 AS DATETIME)	날짜로 변환

날짜 / 시간 함수

KQL 함수	SQL 대응	역할
datetime_add('hour', 9, dt)	DATEADD(HOUR, 9 dt)	날짜에 시간 더하기
endofday(dt)	직접 대응 없음	해당 날짜의 23:59:59 반환
startofday(dt)	직접 대응 없음	해당 날짜의 00:00:00 반환
startofmonth(dt)	직접 대응 없음	해당 월의 1일 00:00:00
format_datetime(dt, 'yyyy-MM-dd')	FORMAT(dt, 'yyyy-MM-dd')	원하는 형식으로 출력

 

 

중급 문법 - arg_max, union, join

arg_max - 그룹별 최신 행 가져오기

KQL에서 가장 자주 쓰이면서도 SQL에서는 꽤 번거로운 작업이다.
"각 그룹에서 특정 컬럼이 가장 큰(최신인) 행을 1건만 가져와"라는 의미다.

💡 비유
학생 30명의 시험 기록이 여러 건씩 있을 때, "각 학생의 가장 최근 시험 결과만 가져와"라는 요청을 한 줄로 처리한다.

-- SQL
SELECT *
FROM (
    SELECT   *
        ,    ROW_NUMBER() OVER (PARTITION BY UserId, ORDER BY Time DESC) AS rn
    FROM AppLogs
) AS t
WHERE rn = 1


-- KQL
AppLogs
| summarize arg_max(Time, *) by UserId

함수	의미	용도
arg_max(Time, *)	Time이 가장 큰(최신) 행의 모든 컬럼	최신 상태 조회
arg_min(Time, *)	Time이 가장 작은(최초) 행의 모든 컬럼	최초 기록 조회

union - 두 결과 합치기

SQL의 UNION ALL 과 동일하다.
두 개의 결과를 하나로 합친다.

💡 비유
두 개의 접시에 담긴 음식을 하나의 큰 접시에 합치는 것이다.

let morningLogs = AppLogs | where Time between (sDate .. noon);
let eveningLogs = AppLogs | where Time between (noon .. eDate);

morningLogs
| union eveningLogs
| summarize count() by Level

join - 두 테이블 연결하기

Users
| join kind-inner Purchase on UserId

KQL	SQL 대응	설명
kind=inner	INNER JOIN	양쪽 모두 있는 것만
kind=leftouter	LEFT JOIN	왼쪽 전부 + 오른쪽 매칭
kind=rightouter	RIGHT JOIN	오른쪽 전부 + 왼쪽 매칭
kind=fullouter	FULL OUTER JOIN	양쪽 전부
kind=leftnanti	직접 대응 없음	⭐ 왼쪽에만 있고 오른쪽에는 없는 것
kind=leftsemi	직접 대응 없음	왼쪽 중에서 오른쪽에 있는 것만

leftanti - 핵심 조인 패턴

💡 비유
"A 반 명단에는 있는데 B 반 명단에는 없는 학생만 찾아줘."라는 요청이다.

-- SQL
SELECT *
FROM anyRange AS a
WHERE NOT EXISTS (
    SELECT 1 
    FROM inRange AS b
    WHERE b.DeviceId = a.DeviceId
)


-- KQL
anyRange
| join kind=leftanti inRange on DeviceId

✅ 포인트
실무 활용 패턴 : "오늘 로그가 있으면 그것, 없으면 과거 최신 로그"를 가져오는 전략에서 union + leftanti가 함께 쓰인다.
모든 대상의 최신 데이터를 빠짐없이 확보하는 핵심 패턴이다.

let lastest_rows = inRange
| union (anyRange | join kind leftanti inRange on DeviceId);

-- inRange : 오늘 로그 있는 대상
-- anyRange leftanti inRange : 오늘 로그 없는 대상의 과거 최신
-- union : 둘을 합쳐서 모든 대상 확보!

 

 

고급 문법 - 동적 타입과 mv-expand

동적 타입 (Dynamic Type) - JSON 데이터 접근

ADX의 로그 데이터는 한 컬럼에 JSON이 통째로 들어있는 경우가 많다.
KQL에서는 이를 dynamic 타입이라 부르며, 점( . )으로 내부에 접근한다.

💡 비유
MSSQL에서는 데이터가 엑셀 표처럼 깔끔하게 컬럼별로 저장된다.
하지만 ADX의 로그 데이터는 한 칸 안에 택배 상자(JSON)가 통째로 들어있는 경우가 많다.
KQL은 그 상자를 점( . )만 찍으면 열 수 있다.

{
    "Device": {
        "Id": "SRV-01",
        "Name": "Server-A01"
    },
    "Metrics": [
        {
            "MetircType": "CPU",
            "Value": 85
        },
        {
            "MetricType": "Memory",
            "Value": 72
        },
        {
            "MetricType": "Disk",
            "Value": 60
        }
    ]
}

 

상황	해결책
JSON에서 꺼낸 값은 dynamic 타입	tostring(), toint() 등으로 변환 필요
키에 특수문자/공백이 있을 때	Data["server-info"] 대괄호 표기법 사용
존재하지 않는 키에 접근하면	에러 없이 null 반환 (안전함)

mv-expand - 배열을 행으로 펼치기

💡 비유
택배 상자(JSON) 안에 여러 개의 작은 상품(배열)이 함께 포장되어 있을 때, 상품 하나하나를 꺼내서 각각 별도의 행으로 나열하는 작업이다.

latest_rows
| mv-expand Data_Metrics = Data.Metrics
| project
    DeviceId = DeviceId,
    MetricType = tostring(Data_Metrics.MetricType),
    Value = tostring(Data_Metrics.Value)

⚠️ 주의
행이 크게 늘어남 : 배열 원소 수만큼 행이 곱해진다.
1만 행에 각 10개씩이면 → 10만행. 또한 빈 배열[ ] 은 해당 열이 결과에서 사라지므로 주의해야 한다.

 

 

실전 쿼리 - 전체 흐름 분석

 

 

SQL ↔ KQL 치트시트

SQL을 아는 상태에서 KQL을 빠르게 찾아볼 수 있도록 정리한 표

하고 싶은 것	SQL (MSSQL)	KQL (ADX)
전체 조회	SELECT * FROM T	T
조건 필터	WHERE col = 'a'	| where col = "a"
컬럼 선택	SELECT a, b	| project a, b
새 컬럼 추가	SELECT *, a+b AS c	| extend c = a + b
정렬	ORDER BY a DESC	| sort by a desc
개수 제한	SELECT TOP 10	| take 10
집계	GROUP BY + COUNT(*)	| summarize count() by col
고유값 수	COUNT(DISTINCT col)	dcount(col)
조건부 카운트	SUM(CASE WHEN ...)	countif(조건)
최근 N일	DATEADD(DAY, -7, GETDATE())	ago(7d)
시간 단위 집계	CAST + GROUP BY	bin(col, 1h)
변수 선언	DECLARE @v / CTE	let v = ...;
그룹별 최신 행	ROW_NUMBER() OVER(...)	arg_max(Time, *) by col
JSON 접근	JSON_VALUE(col, '$.key')	col.key
배열 펼치기	CROSS APPLY OPENJSON	mv-expand col
결과 합치기	UNION ALL	union
없는 것만 필터	NOT EXISTS / LEFT JOIN + IS NULL	join kind-leftanti

 

 

References

주제	문서	링크
KQL 전체 레퍼런스	Kusto Query Language 개요	https://learn.microsoft.com/ko-kr/kusto/query/?view=microsoft-fabric
KQL 튜토리얼	Kusto 쿼리 자습서	https://learn.microsoft.com/ko-kr/kusto/query/tutorials/learn-common-operators?view=microsoft-fabric
SQL → KQL 변환	SQL에서 Kusto로의 치트 시트	https://learn.microsoft.com/ko-kr/kusto/query/sql-cheat-sheet?view=microsoft-fabric
summarize 연산자	summarize 공식 문서	https://learn.microsoft.com/ko-kr/kusto/query/summarize-operator?view=microsoft-fabric
join 연산자	join 종류와 사용법	https://learn.microsoft.com/ko-kr/kusto/query/join-operator?view=microsoft-fabric
mv-expand 연산자	mv-expand 공식 문서	https://learn.microsoft.com/ko-kr/kusto/query/mv-expand-operator?view=microsoft-fabric
Azure Data Explorer	ADX(Azure Data Explorer) 개요	https://learn.microsoft.com/ko-kr/azure/data-explorer/data-explorer-overview