GraphQL 집계를 사용하여 Microsoft Fabric 데이터를 실행 가능한 인사이트로 변환합니다. 수천 장의 개별 레코드를 검색하고 애플리케이션에서 처리하는 대신 Fabric에 데이터를 그룹화하고 요약 서버 쪽을 계산하여 성능을 크게 향상시키고 데이터 전송을 줄이도록 요청할 수 있습니다.
GraphQL 집계는 SQL GROUP BY 작업처럼 작동하지만 GraphQL API를 통해 작동합니다. 범주별 항목 수를 계산하거나, 수익 합계를 계산하거나, 평균 등급을 찾거나, 레이크하우스 및 웨어하우스 테이블에서 최소/최대값을 결정할 수 있습니다( 모두 하나의 효율적인 쿼리).
주요 이점:
- 서버 쪽 처리: 패브릭의 최적화된 쿼리 엔진을 사용하여 계산
- 데이터 전송 감소: 원시 레코드 대신 요약 가져오기
- 단일 쿼리 효율성: 여러 클라이언트 쪽 작업을 하나의 집계로 바꾸기
이 가이드에서는 기본적인 그룹화에서 고급 함수 및 중요한 제한 사항에 이르기까지 모든 것을 다루는 실용적인 전자 상거래 예제를 사용하여 집계 쿼리를 빌드하는 방법을 보여 줍니다.
집계를 사용해야 할 대상자
GraphQL 집계는 다음을 위해 유용합니다.
- 요약된 패브릭 데이터가 필요한 사용자 지정 대시보드 및 분석 애플리케이션을 빌드하는 애플리케이션 개발자
- 패브릭 레이크하우스 및 웨어하우스에서 미리 계산된 메트릭 및 KPI를 제공하는 데이터 API를 만드는 데이터 엔지니어
- 집계된 패브릭 데이터로 Power BI를 보완하는 사용자 지정 분석 솔루션을 빌드하는 BI 개발자
- 패브릭의 요약 통계가 필요한 애플리케이션 및 워크플로를 만드는 통합 개발자
- 패브릭 데이터에서 그룹화된 집계 인사이트가 필요한 셀프 서비스 분석 솔루션을 빌드하는 데이터 분석가
데이터를 검색하여 차트를 표시하거나, 합계를 계산하거나, 보고서를 생성하거나, 추세를 분석하는 경우 집계는 애플리케이션의 성능을 크게 향상시키고 데이터 전송을 줄일 수 있습니다.
대답할 수 있는 일반적인 비즈니스 질문
GraphQL 집계는 패브릭 데이터에 대한 분석 질문에 답변하는 데 탁월합니다.
- 계산 및 그룹화: "각 범주에 있는 제품 수?" 또는 "매월 주문 수?"
- 재무 계산: "지역별 총 수익은 무엇인가요?" 또는 "고객 부문별 평균 주문 가치?"
- 성능 메트릭: "각 범주에서 가장 높고 가장 낮은 등급의 제품은 무엇인가요?"
- 고객 인사이트: "이번 달에 방문한 고유 고객은 몇 명입니까?" 또는 "활성 사용자가 가장 많은 도시는 무엇인가요?"
이러한 쿼리는 개별 레코드가 아닌 요약된 데이터가 필요한 대시보드를 빌드하고, 보고서를 생성하고, 분석 애플리케이션을 구동하는 데 적합합니다.
필수 조건
GraphQL 집계를 사용하기 전에 다음이 있는지 확인합니다.
- 적절한 권한이 있는 Microsoft Fabric 작업 영역
- 집계하려는 데이터가 포함된 테이블이 있는 레이크하우스 또는 웨어하우스
- 패브릭 항목에 대해 구성된 GraphQL 엔드포인트용 API
- GraphQL 쿼리 구문에 대한 기본 숙지
이러한 쿼리를 실행할 위치
빠른 시작: 패브릭 작업 영역에서 GraphQL용 API 편집 기를 사용하여 이 문서의 모든 예제를 테스트합니다. 편집기에서는 스키마 탐색, 쿼리 유효성 검사 및 즉각적인 결과를 제공합니다.
애플리케이션의 경우: 프로그래밍 언어에 대한 GraphQL 클라이언트 라이브러리를 사용하여 GraphQL 엔드포인트에 HTTP POST 요청으로 쿼리를 보냅니다.
개발: GraphQL Playground, Insomnia 또는 Postman과 같은 도구는 쿼리 개발 및 테스트에 적합합니다.
비고
이 문서의 예제는 GraphQL 엔드포인트에 대한 API를 구성한 후 복사하고 실행할 준비가 된 것입니다. 일부 예제는 간결성을 위해 단축되며 특정 스키마에 맞게 조정해야 할 수 있습니다.
예제 시나리오: 패브릭의 전자 상거래 데이터
이 가이드에서는 Microsoft Fabric 레이크하우스 또는 웨어하우스에 저장된 가상의 전자 상거래 데이터 세트를 사용합니다. 이 시나리오에서는 GraphQL 집계를 사용하여 소매 데이터를 분석하는 방법을 보여 줍니다.
이 예제에서 제품 데이터는 범주에 속하며, 각각 Product 가격 및 등급(집계에 적합한 숫자 값) 및 관계 Category와 같은 필드가 포함됩니다. Fabric의 API for GraphQL을 통해 이러한 테이블을 노출하면 생성된 스키마는 다음과 같이 표시될 수 있습니다.
type Category {
id: ID!
name: String!
products: [Product!]! # one-to-many relationship
}
type Product {
id: Int!
name: String!
price: Float!
rating: Int!
category_id: Int!
category: Category! # many-to-one relationship
}
type ProductResult { # automatically generated, adding groupBy capabilities
items: [Product!]!
endCursor: String
hasNextPage: Boolean!
groupBy(fields: [ProductScalarFields!]): [ProductGroupBy!]!
}
type Query {
products(
first: Int
after: String
filter: ProductFilterInput
orderBy: ProductOrderByInput
): ProductResult!
}
이 예제에서 쿼리는 products 일반 항목 목록을 반환하거나 사용되는 경우 groupBy 집계된 결과를 반환할 수 있습니다. 이 쿼리의 groupBy와 집계 기능 사용에 집중해 보겠습니다.
비고
동일한 쿼리에서 일반 항목과 그룹화된 결과를 모두 검색할 수 없습니다. 자세한 내용은 집계와 원시 항목이 상호 배타적임을 참조하십시오.
사용 가능한 집계 함수
사용 가능한 정확한 함수는 구현에 따라 달라지지만 일반적인 집계 작업에는 다음이 포함됩니다.
- count – 그룹의 레코드 수(또는 필드의 null이 아닌 값)입니다.
- sum – 숫자 필드에 있는 모든 값의 합계입니다.
- avg – 숫자 필드에 있는 값의 평균(평균)입니다.
- min – 필드의 최소값입니다.
- max – 필드의 최대값입니다.
GraphQL 집계에서는 예제 등과 같이 함수 이름 및 대상 필드를 지정합니다count(field: id)sum(field: price). 각 함수는 적용된 하나 이상의 필드를 선택할 수 있는 개체를 반환합니다.
비고
Microsoft Fabric의 GraphQL용 API에서 , , countsumavgmin 등의 max집계 작업은 현재 숫자 또는 정수 필드(정수, 부동 소수점)에서만 작동합니다. 텍스트 또는 날짜 필드에는 직접 사용할 수 없습니다. 예를 들어 문자열 필드의 "평균"을 계산할 수 없습니다. 다른 데이터 형식(예: 텍스트 연결 또는 어휘 최소/최대)에 대한 집계 수행 지원은 향후 Fabric 업데이트에서 추가될 수 있습니다.
집계 쿼리 기본 사항
Fabric의 GraphQL API에서 집계를 수행하려면 쿼리에서 인수를 groupBy 지정하여 데이터를 그룹화하는 방법을 정의하고 결과에서 집계 필드(예: 개수 또는 합계)를 요청합니다. Fabric의 GraphQL 엔진은 기본 레이크하우스 또는 웨어하우스 테이블에 대해 이러한 쿼리를 효율적으로 처리하여 키 값과 계산된 집계 메트릭이 있는 그룹화된 레코드 목록을 반환합니다.
예제 1: 범주별 제품 수
범주별로 제품을 그룹화하고 각 그룹에 있는 제품 수를 계산해 보겠습니다. 쿼리는 다음과 같을 수 있습니다.
query {
products {
groupBy(fields: [category_id])
{
fields {
category_id # grouped key values
}
aggregations {
count(field: id) # count of products in each group (count of "id")
}
}
}
}
이 쿼리에서:
-
groupBy(fields: [category_id])는 패브릭 GraphQL 엔진에 필드별로category_id제품을 그룹화하도록 지시합니다. - 결과 선택에서
group을 요청하고count필드에 대해id집계를 요청합니다. 계산id은 해당 그룹의 제품을 효과적으로 계산합니다.
결과는 다음과 같습니다 . 응답의 각 항목은 하나의 범주 그룹을 나타냅니다.
groupBy 개체에 그룹화 키가 포함되어 있습니다. 여기에 값을 category_id 포함하고 count { id } 해당 범주의 제품 수를 제공합니다.
{
"data": {
"products": {
"groupBy": [
{
"fields": {
"category_id": 1
},
"aggregations": {
"count": 3
}
},
{
"fields": {
"category_id": 2
},
"aggregations": {
"count": 2
}
},
// Sample shortened for brevity
]
}
}
}
이 출력은 범주 1에 3개의 제품이 있고, 범주 2에는 2가 있습니다.
예제 2: 합계 및 평균
한 쿼리에서 여러 집계 메트릭을 요청할 수 있습니다. 각 범주에 대해 모든 제품의 총 가격과 평균 등급을 원한다고 가정합니다.
query {
products {
groupBy(fields: [category_id])
{
fields {
category_id
}
aggregations {
count(field: id) # number of products in the category
sum(field: price) # sum of all product prices in the category
avg(field: rating) # average rating of products in the category
}
}
}
}
이 쿼리는 다음 결과를 반환합니다.
{
"data": {
"products": {
"groupBy": [
{
"fields": {
"category_id": 1
},
"aggregations": {
"count": 3,
"sum": 2058.98,
"avg": 4
}
},
{
"fields": {
"category_id": 2
},
"aggregations": {
"count": 2,
"sum": 109.94,
"avg": 4
}
},
...
]
}
}
}
각 그룹 개체에는 제품 수, 가격 합계 및 해당 범주의 평균 등급과 같은 범주 및 계산 집계가 포함됩니다.
예제 3: 여러 필드로 그룹화
여러 필드를 그룹화하여 다중 수준 그룹화할 수 있습니다. 예를 들어, rating 필드가 제품에 있는 경우, category_id와 rating로 그룹화한 다음, 그 그룹에 대해 price의 평균을 계산할 수 있습니다.
query {
products {
groupBy(fields: [category_id, rating])
{
fields {
category_id
rating
}
aggregations {
avg(field: price)
}
}
}
}
이렇게 하면 아래와 같이 범주 와 등급의 고유한 조합으로 제품을 그룹화합니다.
{
"fields": {
"category_id": 10,
"rating": 4
},
"aggregations": {
"avg": 6.99
}
}
또한 데이터의 각 범주 등급 쌍에 대해 이 작업을 진행합니다.
팁 (조언)
여러 필드를 기준으로 그룹화할 때 명시적 정렬은 예측 가능한 결과에 특히 중요합니다. 그룹화된 결과 정렬을 참조하려면 명시적 순서 지정이 필요합니다.
예제 4: 고유 사용
집계 기능은 고유 값을 계산하거나 고려하는 고유 한정자를 지원합니다. 예를 들어 제품 컬렉션에 존재하는 고유 범주 수를 확인하려면 고유 개수를 사용할 수 있습니다.
query {
products {
groupBy(fields: [category_id])
{
fields {
category_id
}
aggregations {
count(field: id, distinct: true)
}
}
}
}
이 쿼리는 각 범주에 대한 고유 제품 수를 사용하여 결과를 반환합니다. 결과는 다음과 같습니다.
{
"data": {
"products": {
"groupBy": [
{
"fields": {
"category_id": 1
},
"aggregations": {
"count": 3
}
},
{
"fields": {
"category_id": 2
},
"aggregations": {
"count": 2
}
},
...
]
}
}
}
팁 (조언)
고유를 적절하게 사용하는 시기와 방법에 대한 자세한 지침은 고유 집계를 적절하게 사용하는 방법을 참조하세요.
예제 5: 별칭 사용
집계에 대한 별칭을 만들어 집계된 결과에 대한 의미 있고 이해하기 쉬운 이름을 제공할 수 있습니다. 예를 들어 결과를 더 잘 이해하기 위해 고유한 제품 범주를 계산하기 때문에 이전 예제 distinctProductCategoryCount 의 집계 이름을 지정할 수 있습니다.
query {
products {
groupBy(fields: [category_id])
{
fields {
category_id
}
aggregations {
distinctProductCategoryCount: count(field: id, distinct: true)
}
}
}
}
결과는 유사하지만 사용자 지정 별칭과 더 의미가 있습니다.
{
"data": {
"products": {
"groupBy": [
{
"fields": {
"category_id": 1
},
"aggregations": {
"distinctProductCategoryCount": 3
}
},
{
"fields": {
"category_id": 2
},
"aggregations": {
"distinctProductCategoryCount": 2
}
},
...
]
}
}
}
예제 6: having 절 사용
절을 사용하여 집계된 결과를 필터링할 수 있습니다 having . 예를 들어 두 개보다 큰 결과만 반환하도록 이전 예제를 수정할 수 있습니다.
query {
products {
groupBy(fields: [category_id])
{
fields {
category_id
}
aggregations {
distinctProductCategoryCount: count(field: id, distinct: true, having: {
gt: 2
})
}
}
}
}
결과는 두 개 이상의 제품이 있는 유일한 범주의 단일 값을 반환합니다.
{
"data": {
"products": {
"groupBy": [
{
"fields": {
"category_id": 1
},
"aggregations": {
"distinctProductCategoryCount": 3
}
}
]
}
}
}
제한 사항 및 모범 사례
Microsoft Fabric의 API for GraphQL에서 집계를 사용하는 경우 고려해야 할 중요한 규칙과 제한 사항이 있습니다. 이러한 모범 사례를 따르고 이러한 제한을 이해하면 특히 큰 데이터 세트를 사용하거나 페이지 매김을 구현할 때 예측 가능한 결과를 보장하면서 강력한 인사이트를 생성하는 효과적인 GraphQL 집계 쿼리를 빌드할 수 있습니다.
집계 기능은 보고 및 분석 사용 사례에 유용하지만 쿼리를 신중하게 구조화해야 합니다. 항상 groupBy 필드가 선택한 출력 필드와 일치하는지 철저히 확인하고, 특히 페이지 매김 시 예측 가능한 순서를 위해 정렬을 추가하며, 데이터 유형에 적합하게 고유 함수와 집계 함수를 적절하게 사용하세요.
다음 섹션에서는 이해해야 하는 세 가지 주요 영역을 다룹니다. 집계 및 원시 항목은 상호 배타적이고, 그룹화된 결과를 정렬하려면 명시적 순서 지정이 필요하며, 고유 집계를 적절하게 사용합니다.
집계 및 원시 항목은 상호 배타적입니다.
현재는 그룹화된 요약 데이터와 동일한 쿼리에 있는 항목의 원시 목록을 동시에 검색할 수 없습니다. 쿼리에서 사용하는 groupBy 경우 API는 "집계 모드"로 전환되고 그룹화된 결과만 반환합니다. 이 디자인은 응답 구조를 명확하게 유지합니다. 각 쿼리는 "집계 모드" 또는 "목록 항목 모드"에 있지만 둘 다 아닙니다.
실제로 작동하는 방식:
쿼리는 다음 products(...) 중 하나를 반환합니다.
- 개별 제품 목록(사용되지 않는 경우
groupBy) - 집계 데이터가 있는 그룹화된 결과 목록(사용되는 경우
groupBy)
위의 집계 예제에서는 응답에 groupBy과 집계 필드가 포함되어 있지만, 일반적인 items 제품 목록은 없습니다.
두 가지 모두를 시도하면 어떻게 되나요?
동일한 쿼리에서 일반 항목과 그룹을 모두 요청하려고 하면 GraphQL 엔진이 오류를 반환하거나 해당 선택을 허용하지 않습니다.
해결 방법:
원시 데이터와 집계된 데이터가 모두 필요한 경우 원시 데이터와 집계된 데이터에 대해 하나씩 두 개의 개별 쿼리를 실행합니다. 이 방법을 사용하면 두 데이터 세트를 완벽하게 제어할 수 있으며 특정 캐싱 및 성능 요구 사항에 따라 최적화할 수 있습니다.
그룹화된 결과를 정렬하려면 명시적 순서 지정이 필요합니다.
명시적 정렬을 지정하지 않으면 집계된 그룹은 예측할 수 없는 순서로 반환됩니다. 일관되고 의미 있는 결과를 보장하기 위해 항상 orderBy 또는 sort 인수를 사용하십시오.
명시적 순서 지정이 중요한 이유:
-
예측할 수 없는 기본 순서: 없으면
orderBy그룹이 임의의 데이터베이스 결정 순서로 반환될 수 있습니다. - 페이지 매김 요구 사항: 일관된 페이지 매김 동작에 안정적인 정렬 순서가 필요합니다.
- 사용자 환경: 예측 가능한 순서 지정으로 데이터 해석 및 애플리케이션 안정성 향상
순서 지정을 지정해야 하는 경우:
-
groupBy 필드에 기본 키 없음: 그룹화 필드에 기본 키가 포함되지 않은 경우 추가해야 합니다.
orderBy - 고유하지 않은 그룹화 키: 범주 이름 또는 날짜와 같은 필드를 기준으로 그룹화할 때
- 페이지 매김 시나리오: 제한/오프셋 또는 커서 페이지 매김을 사용하려는 경우
모범 사례:
- 분석 인사이트에 대한 집계 값(예: 가장 높은 개수 먼저)을 기준으로 정렬
- 범주 기반 그룹에 사전순 정렬 사용
- 복잡한 순서 지정 요구 사항에 대한 여러 정렬 조건 결합
고유한 집계를 적절하게 사용
distinct 한정자는 집계를 수행하기 전에 중복 값을 제거하여 데이터에 중복 항목이 있을 때 정확한 계산을 보장합니다.
일반적인 사용 사례:
-
고유 개수:
count(field: category_id, distinct: true)각 그룹에 존재하는 다양한 범주 수를 계산합니다. -
중복 제거된 합계:
sum(field: price, distinct: true)각 고유 가격 값을 그룹당 한 번만 추가합니다. - 조인 시나리오: 테이블 조인으로 인해 제품이 여러 번 표시되면 고유하게 각 항목이 한 번 계산됩니다.
고유값을 사용해야 할 때:
- 데이터에는 계산을 왜곡하는 합법적인 중복 항목이 포함되어 있습니다.
- 중복 행을 만드는 조인된 테이블로 작업하고 있습니다.
- 총 발생 횟수가 아닌 고유 값의 개수를 계산해야 합니다.
성능 고려 사항:
고유 작업을 수행하려면 더 많은 처리가 필요합니다. 데이터 정확도에 필요한 경우에만 사용합니다.