분석 경로

분석 경로는 *“운영 실적”*이나 *“손익계산서”*처럼 자주 분석하는 테이블에 붙이는 알기 쉬운 이름입니다. 한 번 등록해 두면 이후로는 매번 어떤 프로젝트의 어떤 테이블인지 반복해서 말하지 않고도, 사용자와 연결된 AI 어시스턴트가 그 이름으로 질문할 수 있습니다.

하나를 워크스페이스 기본값으로 지정하면 “지난 분기에 이 값이 왜 올랐나요?” 같은 일반 질문도 그대로 동작합니다. 어시스턴트가 “이 값”이 무엇을 가리키는지 이미 알고 있기 때문입니다.

사용하는 이유

분석 경로가 없으면 모든 질문에서 데이터가 있는 위치, 즉 프로젝트 와 테이블을 정확히 밝혀야 하는데, 금방 번거로워지고 실수하기도 쉽습니다. 분석 경로가 있으면 실제로 생각하는 방식대로 데이터를 이야기할 수 있습니다.

이름으로 질문합니다. “ops_summary_v3 테이블을 Enterprise Profitability 프로젝트에서 요약해 줘.” 대신 *“운영 실적을 요약해 줘.”*라고 하면 됩니다.
기본값을 설정합니다. 가장 많이 쓰는 테이블을 기본값으로 지정하면 이름을 아예 생략할 수 있습니다. *“지난달 이후 무엇이 바뀌었나요?”*라고 물으면 자동으로 올바른 데이터를 대상으로 합니다.
모두가 일관되게 사용합니다. 팀 전체가 *“손익계산서”*라고 부르면 모두가 같은 테이블에 도달하므로 추측하거나 오래된 사본을 쓸 일이 없습니다.

분석 경로 등록

워크스페이스 관리자라면 양식이나 설정 화면이 필요 없습니다. 연결된 AI 어시스턴트에게 일상 언어로 경로를 등록해 달라고 요청하면 됩니다.

“Enterprise Profitability 프로젝트의 ops_summary 테이블을 가리키는 운영 실적이라는 분석 경로를 등록해 줘.”

어시스턴트가 경로를 확인해 주면 즉시 사용할 수 있습니다. 정기적으로 분석하는 테이블마다 하나씩, 원하는 만큼 등록할 수 있습니다.

기본 경로 설정

관리자는 테이블을 지정하지 않은 질문이 자동으로 대상으로 삼도록 경로 하나를 기본값으로 지정할 수 있습니다.

“운영 실적을 기본 분석 경로로 지정해 줘.”

이후에는 “이번 분기에 가장 크게 변동한 항목은 무엇인가요?” 또는 “합계가 왜 줄었나요?” 같은 질문이 다른 지정 없이 해당 테이블을 대상으로 실행됩니다. 기본값은 워크스페이스 전체에서 하나뿐이므로 모든 사람의 대상 미지정 질문이 같은 테이블로 연결됩니다. 새 기본값을 설정하면 기존 기본값이 그쪽으로 옮겨질 뿐이며, 기본값은 항상 하나만 존재하고 어시스턴트가 어느 것인지 알려 줍니다.

AI 어시스턴트에 유용한 경로 만들기

이름과 테이블은 어시스턴트에게 데이터가 어디에 있는지 알려 줍니다. 하지만 데이터가 무엇을 의미하는지, 즉 항상 적용되는 필터, 회계 연도 운영 방식, 팀에서 쓰는 용어가 무엇을 가리키는지는 알려 주지 않습니다. 이런 정보가 없으면 어시스턴트는 추측하게 되고, 자신 있게 내놓은 틀린 답은 느린 답보다 나쁩니다. 이 섹션에서는 그 지식을 담는 두 곳과 두 곳 모두 중요한 이유를 설명합니다.

이 가이드에서 AI 어시스턴트는 PlaidCloud MCP를 통해 연결된 모든 LLM(Claude, Microsoft Copilot, ChatGPT 등)과 PlaidCloud 내장 AI를 의미합니다.

프롬프트 지침 추가

각 분석 경로에는 프롬프트 지침이 있습니다. 어시스턴트가 경로를 사용하는 방법을 알려 주기 위해 사용자가 직접 작성하는 자유 텍스트입니다. 한 줄에 지시 사항 하나를 작성하십시오.

추가하려면 도구 메뉴를 열고 분석 경로를 선택한 다음 경로를 선택하고 편집을 선택합니다(새로 만들려면 새로 만들기를 선택). 프롬프트 지침 필드는 테이블 다음, 작업 영역 기본값으로 설정 바로 앞에 있습니다. 분석 경로를 관리할 권한으로 연결된 어시스턴트도 이를 설정할 수 있습니다. MCP 및 API 호출자에게는 이 필드가 description으로 보입니다. 예: “운영 실적 경로의 description을 … 로 설정해 줘.”

어시스턴트는 프롬프트 지침을 두 가지 방식으로 사용합니다.

경로를 선택하기 위해. 질문에 경로 이름이 없으면 어시스턴트는 질문을 각 경로의 이름 및 프롬프트 지침과 비교하여 가장 잘 맞는 경로를 선택합니다.
상시 지침으로. 경로를 선택한 후에는 해당 경로에 대한 모든 쿼리에 프롬프트 지침을 적용합니다. 즉 포함할 필터, 변환할 용어를 적용합니다. MCP로 연결된 어시스턴트의 경우 비즈니스 수치 자체는 지침이 아니라 프로젝트의 지표 정의에서 가져옵니다.

프롬프트 지침은 경로와 함께 저장되며, 분석 경로를 볼 수 있는 워크스페이스의 모든 사람이 볼 수 있습니다. 지침은 MCP를 통해 작동하는 어시스턴트와 PlaidCloud 내장 AI에 전달됩니다. 워크플로의 LLM 단계 안에 있는 AI 지원에는 전달되지 않습니다.

작성할 내용

이 테이블을 처음 다루는 신입 분석가에게 알려 줘야 할 내용을 포함하십시오. 지시 사항마다 한 줄씩 작성합니다.

작성할 내용	예
경로가 답할 수 있는 질문과 답할 수 없는 질문.	“사업 부문별 월간 영업 실적. 매출, 비용, EBITDA 질문에 사용. 인원수나 예측에는 사용하지 않으며, 이 경우 예측 경로를 사용.”
MCP로 연결된 어시스턴트를 위한 비즈니스 용어가 의미하는 지표.	“’매출’은 순매출 지표입니다. `billed_amount`는 청구액이지 매출이 아닙니다.”
항상 적용되는 필터.	“예산에 대해 묻지 않는 한 항상 `scenario = 'Budget'`을 제외합니다. 계열사 간 행은 `entity_type = 'IC'`이며 합계에서 제외합니다.”
부호 규칙, 달력, 단위 수준.	“비용은 음수로 저장됩니다. 회계 연도는 7월에 시작하므로 FY26은 2025년 7월부터 2026년 6월까지입니다. 사업 부문당 월당 한 행입니다.”
데이터에 매핑된 비즈니스 용어.	“’중서부’는 `region IN ('IL','IN','OH','MI')`를 의미합니다. ’핵심 제품’은 `product_tier = 'A'`를 의미합니다.”

짧고 구체적으로 작성하십시오. 한 줄에 지시 사항 하나가 문단보다 낫고, 제한은 1,000자입니다. 앞뒤 공백은 제거됩니다.

작성하지 말아야 할 내용

어시스턴트가 이미 보는 정보. 열 유형, 키, 행 수는 테이블과 함께 반환됩니다. 이를 반복하면 1,000자만 낭비됩니다.
열 하나의 의미. 이는 테이블이 어디에서 사용되든 열과 함께 유지되도록 열 메모에 넣으십시오. 프롬프트 지침은 경로 전체를 사용하는 방법을 위한 것입니다.
기밀 정보. 프롬프트 지침은 테이블이 속한 프로젝트에 접근할 수 있는 사람뿐 아니라 워크스페이스 전체에 표시됩니다. 비밀번호나 키, 개인 데이터, 모든 워크스페이스 멤버에게 보여 주고 싶지 않은 수치와 의견을 포함하지 마십시오.

좋은 프롬프트 지침과 부족한 프롬프트 지침

아래 두 예는 같은 경로에 대한 것이며, 같은 질문을 합니다. “작년 중서부의 EBITDA는 얼마였나요?”

	부족한 지침	좋은 지침
텍스트	“운영 데이터.”	“사업 부문별 월간 영업 실적. EBITDA = `ebitda_adj`, `ebitda`는 무시. `scenario = 'Budget'`과 계열사 간 행(`entity_type = 'IC'`)은 제외. 회계 연도는 7월에 시작. 중서부 = IL, IN, OH, MI.”
어시스턴트의 동작	단순한 `ebitda` 열을 선택하고, 예산과 계열사 간 행을 포함하며, “작년”을 달력 연도로 해석합니다.	`ebitda_adj`를 사용하고, 예산과 계열사 간 행을 제외하며, 마지막으로 완료된 회계 연도를 사용하고, 중서부 4개 주로 필터링합니다.
답변	그럴듯하지만 틀렸고 재무팀의 수치와 다른 숫자.	재무팀이 보고하는 숫자.

부족한 지침이 틀린 것은 아닙니다. 모든 판단을 어시스턴트의 추측에 맡길 뿐입니다.

열 메모 추가

프롬프트 지침은 경로 전체를 다룹니다. 열 메모는 열 하나를 설명하며, 어시스턴트가 열에 실제로 무엇이 들어 있는지 알게 되는 수단입니다. 열의 용도가 이름만으로 분명하지 않을 때, 메모는 올바른 열과 그럴듯하지만 잘못된 열을 가르는 차이입니다.

경로 테이블의 메모는 열 목록과 함께 AI 어시스턴트에게 반환됩니다. table_describe에서 include=['columns']를 사용하면 메모가 있는 각 열에 memo로 나타납니다. 메모가 없는 열은 이전과 같이 반환됩니다. 같은 메모는 워크플로의 LLM 단계 안에 있는 AI 지원에도, 해당 단계가 사용하는 테이블에 대해 전달됩니다.

메모가 필요한 경우

메모를 추가할 대상	메모 예
코드와 약어	`seg_cd`: “고객 세그먼트 코드: E = 엔터프라이즈, M = 중견 기업, S = 중소기업.”
비슷해 보이는 측정값	`ebitda_adj`: “일회성 항목을 제거한 후의 EBITDA. 보고에는 이것을 사용하며, `ebitda`는 조정되지 않은 값입니다.”
플래그	`is_ic`: “행이 계열사 간 거래이면 1. 연결 합계에서 제외합니다.”
단위 또는 통화	`amt_local`: “엔터티의 현지 통화 금액, 천 단위.”
파생 값 또는 배부된 값	`alloc_cost`: “인원수 기준으로 이 부문에 배부된 공통 비용. 직접 발생한 비용이 아닙니다.”

invoice_date나 customer_name처럼 이름만으로 충분한 열은 건너뛰십시오. 이름을 반복하는 메모는 아무 도움이 되지 않습니다.

메모 추가 방법

경로의 테이블을 테이블 탐색기에서 엽니다.
도구 모음에서 열 속성을 켭니다.
열 목록에서 열을 선택합니다.
메모에 텍스트를 입력합니다.

테이블에 설정한 메모는 해당 테이블을 가리키는 모든 분석 경로를 포함하여 테이블이 사용되는 모든 곳에 적용됩니다.

프롬프트 지침 또는 메모

각 사실은 한 곳에만 두십시오.

	프롬프트 지침	열 메모
대상	경로 전체를 사용하는 방법	열 하나의 의미
일반적인 내용	답할 수 있는 질문, 상시 필터, 회계 달력, 비즈니스 용어	코드, 단위, 플래그, 비슷한 열 중 사용할 것
예	“합계에서 계열사 간 행을 제외합니다.”	`is_ic`: “행이 계열사 간 거래이면 1.”

여기서 메모는 is_ic가 무엇을 의미하는지 알려 주고, 프롬프트 지침은 그것으로 무엇을 할지 알려 줍니다.

사용하기

경로를 등록한 후에는 그냥 질문하면 됩니다.

이름으로 — “운영 실적의 처음 몇 행을 보여 줘.”
기본값으로 — “지난 분기 대비 무엇이 바뀌었나요?” (테이블을 지정하지 않으면 워크스페이스 기본 경로를 사용합니다.)
자유롭게 전환 — “이제 예측에 대해서도 똑같이 해 줘.” 어시스턴트가 경로에서 경로로 따라옵니다.

이 기능은 배부 질문과도 잘 어울립니다. 배부 추적을 참조하십시오. *“운영 실적이 왜 변했나요?”*에서 바로 그 뒤에 있는 계정과 동인으로 이동할 수 있습니다.

MCP로 사용하기

MCP로 연결된 어시스턴트가 분석 경로를 도구에 전달할 때는 경로의 이름(대소문자 구분 없음) 또는 id를 사용할 수 있습니다. 존재하지 않는 id로 경로를 업데이트하면 거부됩니다. 새 경로를 만들려면 id를 생략하십시오.

query_data_read는 table, json_paths, dimension_value, column_values, aggregate에서 프로젝트와 테이블 대신 analysis_path를 받습니다.

일부 열만 미리 보기. query_data_read(action='table')에 columns=[...]를 전달하면 이름을 지정한 열만 반환합니다. 행 액세스 규칙은 그대로 완전히 적용됩니다. version_id와 함께 사용할 수 없습니다.

한 번의 호출로 필터링된 합계 가져오기. column_values에 측정값을 요청하고 관심 있는 열로 필터링하십시오.

query_data_read(
  action='column_values',
  project_id=<project>,
  table_id=<table>,
  dimension_column_name=<filter column>,
  value_column_name=<measure>,
  filters={<filter column>: <value>}
)

해당 값에 대해 한 행을 반환합니다. 열 이름의 철자가 틀리면 오류에 가장 비슷한 이름이 최대 다섯 개 표시되므로 어시스턴트가 수정하여 다시 시도할 수 있습니다.

한 번의 호출로 합계 또는 세부 분류. 행을 읽는 대신 action='aggregate'를 사용하여 하나 이상의 열로 그룹화하고 서버에서 측정값을 합산, 평균 또는 개수 계산하십시오.

query_data_read(
  action='aggregate',
  project_id=<project>,
  table_id=<table>,
  group_by=['Product'],
  measures=[{'column': 'Revenue', 'agg': 'sum'}, {'column': 'Volume'}],
  filters={'Fiscal Year': 2027},
  order_by='Revenue',
  limit=10
)

measures의 agg는 sum(기본값), avg, min, max 또는 count를 사용하며, count는 '*'도 받습니다. filters 값은 여러 값 중 하나와 일치시키는 목록일 수 있습니다. limit의 기본값은 50이고 최대 500입니다. order_by는 측정값 또는 그룹 열의 이름을 지정하며, 측정값은 높은 값부터 정렬됩니다. 응답에는 rows, total_groups, truncated가 포함되며, 마지막 항목은 limit로 반환된 것보다 그룹이 더 많으면 true입니다. 행 액세스 규칙은 합계를 계산하기 전에 적용됩니다.

설정할 수 있는 사람

분석 경로 설정, 즉 등록과 기본값 선택은 관리자의 작업이며, 이는 공유 이름을 모든 사람에게 깔끔하고 신뢰할 수 있게 유지하기 위한 것입니다. 경로가 만들어지면 워크스페이스의 모든 멤버가 질문에서 사용할 수 있으며, 각자는 여전히 본인 권한이 허용하는 데이터만 봅니다.