Fabric

Microsoft Fabric의 SQL 데이터를 조회하는 노드입니다.

---

설명

Fabric 노드는 Microsoft Fabric 워크스페이스의 SQL 데이터를 조회하는 노드입니다. Fabric에서 SQL 엔드포인트로 노출되는 데이터 소스를 조회할 수 있습니다.

• 레이크하우스(Lakehouse) SQL 분석 엔드포인트: 레이크하우스 테이블을 SQL로 조회하는 읽기 전용 엔드포인트입니다.
• 웨어하우스(Warehouse): 읽기·쓰기가 가능한 데이터 웨어하우스입니다. 단, 이 노드는 조회(읽기)만 수행합니다.

두 종류 모두 워크스페이스의 SQL 엔드포인트 목록에 함께 표시되며, 아래 두 가지 방식으로 데이터를 가져옵니다.

• 테이블 선택 모드: 워크스페이스 → 엔드포인트 → 스키마 → 테이블을 차례로 골라 해당 테이블의 데이터를 그대로 가져옵니다.
• SQL 직접 입력 모드: SQL을 직접 작성하여 조회합니다. 상류(입력) 데이터셋의 값을 {{ }} 문법으로 쿼리에 끼워 넣을 수 있습니다.

사용하려면 먼저 Microsoft 로그인하여 연결하기로 Microsoft 계정을 연동해야 합니다.

---

Microsoft 계정 연동

1. 노드를 캔버스에 추가합니다
2. Microsoft 로그인하여 연결하기 버튼을 클릭합니다
3. Microsoft 계정 로그인 창에서 계정을 선택합니다
4. AI Canvas의 Fabric 접근 권한을 허용합니다
5. 연동이 완료되면 테이블 선택 모달에서 워크스페이스 목록을 조회할 수 있습니다

조직(엔터프라이즈) 계정만 지원

Fabric 노드는 조직(엔터프라이즈) 계정으로만 연동할 수 있습니다. 개인 Microsoft 계정(예: outlook.com, hotmail.com)으로는 로그인할 수 없습니다. Microsoft Fabric 자체가 조직(회사 · 학교) 계정 기반 서비스이기 때문입니다.

Fabric 전용 연결

Fabric 노드의 Microsoft 연동은 Fabric 리소스 접근 전용입니다. OneDrive · 아웃룩 메일 · 아웃룩 캘린더 · SharePoint · 팀즈 노드의 Microsoft 연동과는 별개로 관리되므로, Fabric 노드에서 별도로 한 번 로그인해야 합니다.

연결을 해제하려면 Microsoft 계정 연결 해제를 클릭합니다. 해제 시 선택해 둔 워크스페이스 · 엔드포인트 · 테이블 정보도 함께 초기화됩니다.

---

포트 구성

입력 포트

• 데이터셋 (선택): SQL 직접 입력 모드에서 {{ }} 치환에 사용할 값의 출처입니다. 테이블 선택 모드나 {{ }}를 쓰지 않는 SQL에서는 연결하지 않아도 됩니다.

출력 포트

• 데이터셋: 조회 결과 데이터

---

속성

모드

데이터를 가져오는 방식을 선택합니다.

• 테이블 선택: 모달에서 고른 테이블의 데이터를 조회합니다.
• SQL 직접 입력: 직접 작성한 SQL로 조회합니다.

연결 대상 선택

노드 본문의 테이블 선택(이미 선택한 경우 다시 선택하기) 버튼을 누르면 Fabric 테이블 선택 모달이 열립니다. 모달은 왼쪽부터 오른쪽으로 이어지는 4단계 선택으로 구성됩니다.

1. 워크스페이스: 연동된 계정으로 접근 가능한 Fabric 워크스페이스를 선택합니다.
2. SQL 엔드포인트: 워크스페이스 안의 SQL 분석 엔드포인트(Lakehouse)와 웨어하우스가 함께 표시됩니다. 하나를 선택합니다.
3. 스키마: 선택한 엔드포인트의 스키마(예: dbo)를 선택합니다.
4. 테이블: 스키마에 속한 테이블을 선택합니다. 뷰(View)는 VIEW 배지로 구분됩니다.

테이블을 선택하면 하단의 미리보기를 눌러 상위 몇 개 행을 확인할 수 있습니다. 선택 완료를 누르면 선택 내용이 노드에 저장됩니다. (저장만 되며, 실제 조회는 노드의 실행하기 버튼으로 수행합니다.)

SQL (SQL 직접 입력 모드 전용)

SQL 직접 입력 모드에서는 노드 본문에 현재 SQL의 첫 줄이 미리보기로 표시되고, SQL 편집 버튼으로 편집 모달을 엽니다.

SQL 편집 모달은 코드 에디터 기반으로 다음 편의 기능을 제공합니다.

• 구문 하이라이팅: SQL 예약어 · 문자열 · 숫자 등이 색으로 구분됩니다.
• 예약어 자동완성: SELECT, FROM, WHERE, IN, WITH, GROUP BY, ORDER BY, DESC 등 예약어를 대문자로 자동완성합니다.
• {{ }} 자동완성: 입력 데이터셋의 컬럼을 기준으로 {{컬럼}}(값) · {{컬럼.list}}(IN 목록) · {{컬럼.name}}(식별자) 후보를 제안합니다.
• ⌘/Ctrl + Enter: 현재 SQL을 저장하고 곧바로 노드를 실행합니다.

SQL 모드의 "연결 기준"

SQL 직접 입력 모드에서도 먼저 대상(워크스페이스 → 엔드포인트 → 테이블)을 선택합니다. 이때 선택한 테이블은 조회 대상이 아니라, SQL을 실행할 엔드포인트/데이터베이스를 지정하는 연결 기준입니다. 실제로 어떤 테이블을 읽을지는 작성한 SQL의 FROM 절이 결정합니다.

---

사용 방법

테이블 선택 모드

1. 노드를 캔버스에 추가하고 Microsoft 로그인하여 연결하기로 계정을 연동합니다
2. 모드를 테이블 선택으로 둡니다 (기본값)
3. 테이블 선택 버튼을 눌러 모달을 엽니다
4. 워크스페이스 → SQL 엔드포인트 → 스키마 → 테이블을 차례로 선택합니다
5. 필요하면 미리보기로 데이터를 확인합니다
6. 선택 완료를 누릅니다
7. 노드의 실행하기 버튼을 클릭합니다
8. 출력 포트에서 조회한 테이블 데이터를 확인할 수 있습니다

SQL 직접 입력 모드

1. 노드를 캔버스에 추가하고 Microsoft 계정을 연동합니다
2. {{ }} 치환을 사용할 경우, 값의 출처가 될 데이터셋을 입력 포트에 연결합니다
3. 모드를 SQL 직접 입력으로 변경합니다
4. 테이블 선택 버튼으로 연결 기준(엔드포인트)을 선택합니다
5. SQL 편집 버튼을 눌러 편집 모달을 엽니다
6. SQL을 작성합니다 (자동완성 · {{ }} 치환 활용)
7. ⌘/Ctrl + Enter로 실행하거나, 저장 후 노드의 실행하기 버튼을 클릭합니다
8. 출력 포트에서 조회 결과를 확인할 수 있습니다

---

입력값 치환 ({{ }})

SQL 직접 입력 모드에서는 입력 데이터셋의 컬럼 값을 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}} 은 여러 행이 들어와도 첫 번째 행 값만 사용합니다. 여러 값을 조건에 넣으려면 {{컬럼.list}} 를 사용하세요.

---

주의사항

계정 연동 필수

Fabric 노드를 사용하려면 Microsoft 계정 연동이 필요합니다. 이 연동은 다른 Microsoft 노드와 별개로 관리됩니다.

읽기 전용 (SELECT만 가능)

Fabric 노드는 데이터 조회 전용입니다. 웨어하우스(Warehouse)는 쓰기가 가능한 저장소이지만, 이 노드는 실행 전에 쿼리를 검사하여 단일 SELECT(또는 UNION 등 집합 조회)만 허용합니다. INSERT · UPDATE · DELETE · CREATE · DROP · EXEC 같은 쓰기 · DDL · 다중 구문은 차단되며 오류로 처리됩니다.

엔드포인트가 안 보일 때

SQL 엔드포인트 목록에는 워크스페이스의 Lakehouse SQL 분석 엔드포인트와 웨어하우스가 함께 표시됩니다. 목록이 비어 있다면, 연동한 계정에 해당 워크스페이스/항목에 대한 접근 권한이 있는지 확인하세요.

테이블을 바꾸면 컬럼 선택 초기화

테이블 선택 모드에서 다른 테이블로 다시 선택하면, 이전 테이블 기준으로 저장돼 있던 컬럼 정보가 초기화됩니다. 이는 새 테이블에 없는 컬럼으로 조회가 실패하는 것을 막기 위한 동작입니다.