Fabric
Microsoft Fabric의 SQL 데이터를 조회하는 노드입니다.
설명
Fabric 노드는 Microsoft Fabric 워크스페이스의 SQL 데이터를 조회하는 노드입니다. Fabric에서 SQL 엔드포인트로 노출되는 데이터 소스를 조회할 수 있습니다.
- 레이크하우스(Lakehouse) SQL 분석 엔드포인트: 레이크하우스 테이블을 SQL로 조회하는 읽기 전용 엔드포인트입니다.
- 웨어하우스(Warehouse): 읽기·쓰기가 가능한 데이터 웨어하우스입니다. 단, 이 노드는 조회(읽기)만 수행합니다.
두 종류 모두 서버 목록에 함께 표시됩니다. 조회는 SQL을 직접 작성해서 수행하며, 상류(입력) 데이터셋의 값을 {{ }} 문법으로 쿼리에 끼워 넣을 수 있습니다.
사용하려면 먼저 Microsoft 로그인하여 연결하기로 Microsoft 계정을 연동해야 합니다.
Microsoft 계정 연동
- 노드를 캔버스에 추가합니다
- Microsoft 로그인하여 연결하기 버튼을 클릭합니다
- Microsoft 계정 로그인 창에서 계정을 선택합니다
- AI Canvas의 Fabric 접근 권한을 허용합니다
- 연동이 완료되면 서버 선택 드롭다운에 접근 가능한 SQL 엔드포인트와 웨어하우스가 채워집니다
Fabric 노드는 조직(엔터프라이즈) 계정으로만 연동할 수 있습니다. 개인 Microsoft 계정(예: outlook.com, hotmail.com)으로는 로그인할 수 없습니다. Microsoft Fabric 자체가 조직(회사 · 학교) 계정 기반 서비스이기 때문입니다.
Fabric 노드의 Microsoft 연동은 Fabric 리소스 접근 전용입니다. OneDrive · 아웃룩 메일 · 아웃룩 캘린더 · SharePoint · 팀즈 노드의 Microsoft 연동과는 별개로 관리되므로, Fabric 노드에서 별도로 한 번 로그인해야 합니다.
연결을 해제하려면 Microsoft 계정 연결 해제를 클릭합니다. 해제 시 저장해 둔 서버 주소와 데이터베이스도 함께 초기화됩니다.
포트 구성
입력 포트
- 데이터셋 (선택):
{{ }}치환에 사용할 값의 출처입니다.{{ }}를 쓰지 않는 SQL에서는 연결하지 않아도 됩니다.
출력 포트
- 데이터셋: 조회 결과 데이터
속성
서버 선택
서버 선택 드롭다운에는 연동된 계정으로 접근 가능한 SQL 분석 엔드포인트(Lakehouse)와 웨어하우스가 함께 표시됩니다. 항목을 고르면 아래 서버 주소와 데이터베이스가 자동으로 채워집니다.
서버 주소 · 데이터베이스
드롭다운으로 채워진 값을 직접 수정할 수 있습니다. 목록을 불러오지 못했을 때도 두 칸에 값을 직접 입력하면 연결됩니다. 서버 주소는 xxx.datawarehouse.fabric.microsoft.com 형태입니다.
쿼리 타임아웃 (초)
SQL 실행을 기다릴 최대 시간입니다. 오른쪽 속성 패널에서 설정합니다. (기본값: 60, 범위: 5 ~ 600)
SQL
노드 본문에 현재 SQL의 첫 줄이 미리보기로 표시되고, SQL 편집 버튼으로 편집 모달을 엽니다.
SQL 편집 모달은 코드 에디터 기반으로 다음 편의 기능을 제공합니다.
- 구문 하이라이팅: SQL 예약어 · 문자열 · 숫자 등이 색으로 구분됩니다.
- 예약어 자동완성:
SELECT,FROM,WHERE,IN,WITH,GROUP BY,ORDER BY,DESC등 예약어를 대문자로 자동완성합니다. {{ }}자동완성: 입력 데이터셋의 컬럼을 기준으로{{컬럼}}(값) ·{{컬럼.list}}(IN 목록) ·{{컬럼.name}}(식별자) 후보를 제안합니다.- ⌘/Ctrl + Enter: 현재 SQL을 저장하고 곧바로 노드를 실행합니다.
드롭다운에서 고른 항목은 조회 대상이 아니라, SQL을 실행할 서버와 데이터베이스를 지정하는 연결 기준입니다. 실제로 어떤 테이블을 읽을지는 작성한 SQL의 FROM 절이 결정합니다.
사용 방법
- 노드를 캔버스에 추가하고 Microsoft 로그인하여 연결하기로 계정을 연동합니다
{{ }}치환을 사용할 경우, 값의 출처가 될 데이터셋을 입력 포트에 연결합니다- 서버 선택 드롭다운에서 조회할 엔드포인트 또는 웨어하우스를 고릅니다
- SQL 편집 버튼을 눌러 편집 모달을 엽니다
- SQL을 작성합니다 (자동완성 ·
{{ }}치환 활용) - ⌘/Ctrl + Enter로 실행하거나, 저장 후 노드의 실행하기 버튼을 클릭합니다
- 출력 포트에서 조회 결과를 확인할 수 있습니다
입력값 치환 ({{ }})
입력 데이터셋의 컬럼 값을 SQL에 끼워 넣을 수 있습니다. 컬럼 이름을 중괄호로 감싸고, 뒤에 붙이는 접미사에 따라 치환 방식이 달라집니다.
| 문법 | 의미 | 치환 방식 |
|---|---|---|
{{컬럼}} | 값 (스칼라) | 해당 컬럼의 첫 번째 비어 있지 않은 값을 안전한 파라미터로 바인딩 |
{{컬럼.list}} | 값 목록 (IN용) | 해당 컬럼의 중복 제거된 모든 값을 ?, ?, … 로 바인딩 |
{{컬럼.name}} | 식별자 | 첫 번째 비어 있지 않은 값을 컬럼/테이블 이름으로 사용 (대괄호 인용) |
{{컬럼}} 과 {{컬럼.list}} 로 들어가는 값은 SQL 문자열에 직접 이어붙이지 않고 바인딩 파라미터로 전달됩니다. 따라서 값에 따옴표 등이 포함되어도 SQL 인젝션 없이 안전하게 처리됩니다.
아래 예시는 모두 Fabric 샘플 테이블 publicholidays(컬럼: countryOrRegion, holidayName, date …)를 대상으로 합니다.
{{컬럼}} — 값
입력 데이터셋:
| country |
|---|
| Japan |
작성한 SQL:
SELECT holidayName, date
FROM publicholidays
WHERE countryOrRegion = {{country}}
실행되는 SQL(개념):
SELECT holidayName, date
FROM publicholidays
WHERE countryOrRegion = ? -- 파라미터: 'Japan'
→ 일본의 공휴일만 조회됩니다.
{{컬럼.list}} — 값 목록 (IN)
입력 데이터셋:
| country |
|---|
| Japan |
| Sweden |
| Japan |
작성한 SQL (괄호 ( )는 직접 작성):
SELECT countryOrRegion, holidayName
FROM publicholidays
WHERE countryOrRegion IN ({{country.list}})
실행되는 SQL(개념):
SELECT countryOrRegion, holidayName
FROM publicholidays
WHERE countryOrRegion IN (?, ?) -- 파라미터: 'Japan', 'Sweden' (중복 제거)
→ 일본과 스웨덴의 공휴일이 조회됩니다.
{{컬럼.name}} — 식별자
입력 데이터셋:
| col |
|---|
| holidayName |
작성한 SQL:
SELECT {{col.name}}
FROM publicholidays
실행되는 SQL(개념):
SELECT [holidayName]
FROM publicholidays
→ holidayName 컬럼의 값이 조회됩니다.
값 vs 식별자 — 무엇이 다른가
같은 입력 · 같은 형태의 쿼리라도, 접미사에 따라 결과가 완전히 달라집니다. 입력 데이터셋의 target 컬럼 첫 값이 holidayName 이라고 가정합니다.
| 작성한 SQL | 실행되는 SQL | 결과 |
|---|---|---|
SELECT {{target}} FROM publicholidays | SELECT ? FROM publicholidays(파라미터: 'holidayName') | 모든 행에 문자열 "holidayName" 이 그대로 채워진 상수 컬럼 ❌ |
SELECT {{target.name}} FROM publicholidays | SELECT [holidayName] FROM publicholidays | 실제 holidayName 컬럼의 값 ✅ |
- 값(
{{target}}) 은 그 자리에 데이터(문자열/숫자) 를 넣습니다.WHERE 컬럼 = {{...}}처럼 비교 대상 값에 사용합니다. - 식별자(
{{target.name}}) 는 그 자리에 컬럼명·테이블명 을 넣습니다.SELECT·FROM·ORDER BY처럼 이름이 와야 하는 자리에 사용합니다.
{{컬럼}} 과 {{컬럼.name}} 은 여러 행이 들어와도 첫 번째 비어 있지 않은 값만 사용합니다. 빈 값(NaN)은 건너뛰므로 1행이 비어 있으면 2행 값이 쓰입니다. 여러 값을 조건에 넣으려면 {{컬럼.list}} 를 사용하세요.
입력 데이터셋에 없는 컬럼을 쓰거나, 해당 컬럼의 값이 전부 비어 있으면 치환하지 않고 오류로 실패합니다.
주의사항
Fabric 노드를 사용하려면 Microsoft 계정 연동이 필요합니다. 이 연동은 다른 Microsoft 노드와 별개로 관리됩니다.
Fabric 노드는 데이터 조회 전용입니다. 웨어하우스(Warehouse)는 쓰기가 가능한 저장소이지만, 이 노드는 실행 전에 쿼리를 검사하여 단일 SELECT(또는 UNION 등 집합 조회)만 허용합니다. INSERT · UPDATE · DELETE · CREATE · DROP · EXEC 같은 쓰기 · DDL · 다중 구문은 차단되며 오류로 처리됩니다.
서버 선택 드롭다운에는 워크스페이스의 Lakehouse SQL 분석 엔드포인트와 웨어하우스가 함께 표시됩니다. 목록이 비어 있다면, 연동한 계정에 해당 워크스페이스/항목에 대한 접근 권한이 있는지 확인하세요.