지표 정의

지표 정의(metric definition)는 계산 방식이 합의되어 문서로 정리된 비즈니스 수치입니다. 예를 들면 Net Revenue, Headcount (FTE), Units Shipped 같은 것입니다. 지표 정의에는 수치가 어느 테이블에서 나오는지, 행을 어떻게 합산하는지, 어떤 행을 포함하는지, 어떤 열로 세분화할 수 있는지가 담깁니다.

지표 정의가 없으면 *“지난 분기 EMEA의 순매출은 얼마였나요?”*라는 질문을 받은 AI 어시스턴트는 어떤 테이블, 열, 필터를 사용할지 스스로 결정하므로, 같은 질문을 해도 사람마다 다른 수치를 얻을 수 있습니다. 지표 정의는 이 결정을 어시스턴트에게서 가져옵니다. 프로젝트 아키텍트가 정의를 한 번 작성하고 저장하면, 그 순간부터 어시스턴트는 작성된 그대로 수치를 계산합니다.

참고

지표 정의는 MCP로 연결된 AI 어시스턴트 또는 REST API를 통해 관리하며, 아직 PlaidCloud에 전용 화면은 없습니다. 지표는 PlaidCloud 기본 제공 AI 어시스턴트와 MCP로 연결된 모든 어시스턴트에서 사용할 수 있습니다. 기본 제공 어시스턴트는 지표를 찾고 계산할 수 있지만 만들거나 편집하거나 폐기할 수는 없습니다.

아키텍트: 지표 정의하기부터 시작하십시오. 분석가: 지표에 대해 질문하기부터 시작하십시오.

지표 정의는 저장된 결과가 아니라 계산 방법입니다. 요청될 때마다 질문한 사람의 행 접근 권한에 따라 다시 계산됩니다. EMEA만 볼 수 있는 사람은 EMEA 수치를 얻습니다. 같은 정의라도 보이는 행이 다르기 때문에 두 사람이 서로 다른 합계를 얻을 수 있지만, 계산 방식은 동일합니다.

정의에 담기는 내용

항목	설명	예시
이름	사람들이 해당 수치를 부르는 이름입니다. 최대 200자입니다.	Net Revenue
동의어	사람들이 같은 수치를 가리킬 때 쓰는 다른 말로, 어시스턴트가 질문을 인식하는 데 사용됩니다. 최대 25개입니다.	revenue, sales
설명(API에서는 memo)	수치의 의미와 사용 시점으로, 어시스턴트와 사람 모두를 위한 내용입니다. 최대 1,000자입니다.	반품과 할인을 반영한 매출입니다. 모든 매출 관련 질문에 사용합니다.
소스 테이블	행을 가져오는 테이블입니다.	sales_fact
조인	일치하는 열을 기준으로 소스에 조인되는 룩업 테이블입니다. 각 룩업 테이블은 키마다 행이 하나만 있어야 합니다(예: 지역 코드당 한 행). 그렇지 않으면 일치하는 행이 두 번 계산됩니다.	region_lookup, 소스의 region_code와 룩업의 code를 일치시킴
측정값	행을 합산하는 방식입니다. 열에 대한 sum, count, count_distinct, min, max, avg, 또는 두 번째 열(weight)로 가중치를 준 열의 weighted_avg입니다. 이 값은 두 값이 모두 설정된 행에서 값과 가중치의 곱을 합산하여 가중치의 합으로 나눈 값이며, 가중치의 합이 0이면 비어 있습니다.	net_amount의 sum, units 가중치를 적용한 unit_price의 weighted_avg
필터	항상 포함되는 행을 정합니다. 각 필터는 열, 연산자(eq, ne, in, not_in, lt, le, gt, ge, between, is_null, not_null), 그리고 값으로 구성됩니다.	status eq Posted
세분화 열(API에서는 grain)	질문할 때 그룹화하거나 필터링할 수 있는 열입니다. 필터는 고정되어 있지만 세분화 열은 질문하는 사람이 선택합니다.	region_lookup.region, product_line, fiscal_year
시나리오(선택 사항)	실적 행과 예산 행을 구분하는 열과 각각의 값입니다. 지표는 실적 행이며, 예산 행은 차이를 계산할 때만 읽습니다.	scenario, 실적 Actual, 예산 Budget
차원(선택 사항, API에서는 dimensions)	차원에 연결된 세분화 열입니다. 질문에 쓰인 단어가 해당 차원의 멤버 및 별칭과 대조되어 열의 값으로 변환됩니다. 지표에 대해 질문하기를 참조하십시오. 차원은 프로젝트에 있어야 합니다.	region_lookup.region을 Region 차원에 연결
시간 열(선택 사항, API에서는 time)	날짜 열 또는 회계 연도 열과 기간 열로, 질문에서 특정 회계 기간을 지정하고 시간에 따라 비교할 수 있게 합니다.	fiscal_year 및 fiscal_period

룩업 테이블의 열은 <table>.<column> 형식으로 작성하며, 이 형식은 어시스턴트가 대신 작성합니다. 정의에 포함된 모든 테이블과 열은 프로젝트에 있어야 하며, 없는 것을 지정한 정의는 저장할 때 거부됩니다. 시나리오가 있는 지표는 시나리오 열을 필터링하거나 세분화 열로 제공할 수 없습니다. 시나리오가 어떤 행을 읽을지 결정하므로 scenario eq Actual 같은 필터는 필터가 아니라 시나리오에 속합니다.

지표는 다른 지표를 바탕으로 비율, 합, 차 또는 배수로 만들 수도 있습니다. 다른 지표에서 파생된 지표 만들기를 참조하십시오.

한 프로젝트에서 두 지표가 같은 이름이나 동의어를 가지는 것을 막지는 않습니다. 서로 구별되게 유지하십시오. 그렇지 않으면 어시스턴트가 어느 쪽을 의미하는지 추측하거나 되물어야 합니다.

누가 무엇을 할 수 있나요

• 프로젝트 아키텍트는 정의를 작성하고, 편집하고, 폐기합니다. 공개 프로젝트에서는 모든 멤버가 이름뿐인 아키텍트 역할을 가지며 이는 인정되지 않습니다. 공개 프로젝트에서는 아무도 지표를 정의할 수 없으므로, 지표는 자체 액세스 목록이 있는 프로젝트에 두십시오.
• 프로젝트를 읽을 수 있는 사람은 누구나 정의를 보고 실행할 수 있습니다.
• 잠긴 프로젝트는 모든 변경을 거부합니다. 정의, 편집, 폐기는 모두 프로젝트의 잠금이 해제될 때까지 대기합니다.

지표 정의하기

프로젝트 아키텍트라면 연결된 AI 어시스턴트에게 일상적인 말로 요청하십시오.

“Sales 프로젝트에서 동의어가 revenue, sales인 Net Revenue라는 이름의 지표를 정의해 주세요. sales_fact의 net_amount 합계이며, region_code를 기준으로 region_lookup에 조인하고, 룩업의 region, product_line, fiscal_year로 세분화할 수 있어야 합니다. 실적 행은 scenario가 Actual이고 예산 행은 scenario가 Budget입니다.”

어시스턴트가 이를 저장하며, 지정한 테이블이나 열이 없으면 알려 줍니다. 지표는 저장되는 즉시 사용할 수 있습니다. 모든 편집은 정의의 새 버전이 되며 편집한 사람이 기록되고, 읽는 사람은 새 버전을 즉시 받습니다. 아무것도 바꾸지 않는 저장은 거부됩니다. 마지막으로 저장된 버전이 지표의 현재 버전입니다.

개발자를 위해, REST API로 같은 정의를 작성하는 방법은 다음과 같습니다.

POST /rest/v1/analyze/metric/definition
{
  "project_id": "<project>",
  "name": "Net Revenue",
  "synonyms": ["revenue", "sales"],
  "memo": "Revenue after returns and discounts. Use for all revenue questions.",
  "definition": {
    "source": "sales_fact",
    "joins": [{"table_id": "region_lookup", "on": [["region_code", "code"]]}],
    "measure": {"agg": "sum", "column": "net_amount"},
    "filters": [],
    "grain": ["region_lookup.region", "product_line", "fiscal_year"],
    "scenario": {"column": "scenario", "actual": "Actual", "budget": "Budget"},
    "time": {"year_column": "fiscal_year", "period_column": "fiscal_period"}
  }
}

on의 각 쌍은 [source column, lookup column]입니다. time은 선택적 periods_per_year가 있는 {"year_column", "period_column"}이거나, 선택적 fiscal_year_start와 fiscal_year_label이 있는 날짜 열용 {"column"}입니다. 시간에 따라 비교하기를 참조하십시오.

저장할 때 검사하는 내용

저장할 때마다 다음 검사를 실행하며, 하나라도 통과하지 못한 정의는 문제를 지적하는 메시지와 함께 거부됩니다.

• 모든 테이블과 열이 프로젝트에 있어야 합니다.
• 모든 룩업 테이블은 키마다 행이 하나여야 합니다. 검사는 그 시점의 데이터를 기준으로 합니다. 같은 키에 행이 둘인 룩업 테이블은 일치하는 소스 행을 두 배로 늘리므로 저장이 거부되고 해당 테이블이 지목됩니다. 키 값이 없는 룩업 행은 소스 행과 일치하지 않으므로 이 검사에서 무시됩니다.
• 파생 지표의 입력이 존재해야 하며, 폐기되었거나 그 자체가 파생 지표가 아니어야 합니다.

룩업 검사는 저장할 때마다 실행됩니다

키당 한 행인지 확인하는 검사는 저장하는 날의 룩업 테이블 데이터를 기준으로 합니다. 이후 해당 테이블에서 어떤 키에 두 번째 행이 생기면 그 키와 일치하는 소스 행이 이중으로 계산되며 아무런 경고도 표시되지 않습니다. 검사를 다시 실행하려면 지표를 다시 저장하십시오(설명을 바꾸는 것만으로 충분합니다). 더 좋은 방법은 룩업을 기록하는 워크플로에서 룩업의 키를 고유하게 유지하는 것입니다.

각 버전에는 저장한 사람과 시간이 기록됩니다. 지표를 편집하면 새 버전이 저장되며 읽는 사람은 즉시 새 버전을 받습니다.

다른 지표에서 파생된 지표 만들기

파생 지표는 이미 있는 지표에 대한 산술입니다. Net Revenue per FTE는 Net Revenue를 *Headcount (FTE)*로 나눈 값입니다. 다른 지표와 마찬가지로 정의하고, 질문하고, 폐기합니다. 다른 점은 정의에 테이블이 아니라 그 바탕이 되는 지표가 지정된다는 것입니다.

연산	계산 내용	입력
ratio	첫 번째 입력을 두 번째 입력으로 나눈 값	지표 두 개
add	첫 번째 입력과 두 번째 입력의 합	지표 두 개
subtract	첫 번째 입력에서 두 번째 입력을 뺀 값	지표 두 개
scale	입력에 고정된 factor를 곱한 값	지표 하나와 숫자 하나

입력은 같은 프로젝트의 기본 지표, 즉 위에서 설명한 테이블로 정의된 종류의 지표여야 합니다. 파생 지표는 다른 파생 지표로 만들 수 없으며 같은 입력을 두 번 사용할 수 없습니다.

어시스턴트에게 요청하십시오.

“Sales 프로젝트에서 Net Revenue와 Headcount (FTE) 의 비율로 Net Revenue per FTE라는 지표를 정의해 주세요.”

REST API에서는 definition이 입력을 ID로 지정하며, ID는 metric_find 또는 정의 목록에서 확인할 수 있습니다. 순서가 중요합니다. 첫 번째 ID는 ratio의 분자이고 subtract에서는 피감수가 되는 지표입니다.

{
  "kind": "derived",
  "op": "ratio",
  "inputs": ["<Net Revenue metric_id>", "<Headcount (FTE) metric_id>"]
}

scale은 입력 하나와 factor를 받습니다. {"kind": "derived", "op": "scale", "inputs": ["<Monthly Run Rate metric_id>"], "factor": 12}는 월간 수치를 연간 수치로 환산합니다.

계산 방식. 각 입력은 요청한 세분화 기준과 사용자의 행 접근 권한에 따라 개별적으로 계산되며, 그 결과가 세분화 값별로 결합됩니다. 입력을 결합하기 전에 각각 합계를 내기 때문에 두 테이블의 비율이 정확하게 유지됩니다. 행을 먼저 조인하면 반대편에서 만난 행의 수만큼 한 행이 여러 번 계산됩니다. 어떤 세분화 값에서 한 입력에 행이 없으면 그 값의 파생 값은 비어 있으며, 분모가 0인 비율도 마찬가지입니다. 어느 쪽도 0으로 보고되지 않습니다.

세분화 열은 선언되는 것이 아니라 계산됩니다. 파생 지표는 모든 입력이 허용하는 열로만 세분화할 수 있으며, 그 목록은 정의 옆에 표시됩니다. 파생 지표를 지역별로 질문하려면 각 입력에 region_lookup.region을 같은 표기로 세분화 열로 지정하십시오. 입력들이 공유하는 세분화 열이 없으면 파생 지표는 단일 합계로만 답합니다. 다른 항목으로 그룹화하거나 필터링하는 질문은 다른 지표와 마찬가지로 거부됩니다. 파생 지표 옆의 목록이 비어 있으면 입력 중 하나가 폐기되었거나 없어져 더 이상 사용할 수 없다는 뜻입니다.

저장할 때 입력을 검사합니다. 파생 지표는 각 입력이 존재하고, 폐기되지 않았으며, 그 자체가 파생 지표가 아닐 때만 저장할 수 있습니다. 독자와 아키텍트 모두 항상 각 입력과 파생 지표의 현재 버전을 받습니다. 입력은 특정 버전에 고정되지 않으므로 입력의 이후 버전이 저장되면 파생 지표의 수치도 함께 바뀝니다.

파생 지표가 사용하는 동안 입력은 계속 사용 상태로 유지됩니다. 입력을 폐기할 수 없고 파생 지표로 바꿀 수도 없으며, 거부 메시지에는 이를 사용하는 지표가 표시됩니다. 입력을 폐기하려면 먼저 파생 지표를 폐기하거나, 해당 입력을 사용하지 않는 버전을 저장하십시오.

지표에 대해 질문하기

프로젝트를 읽을 수 있는 사람은 누구나 PlaidCloud 기본 제공 AI 어시스턴트 또는 MCP로 연결된 어시스턴트에게 질문할 수 있습니다.

“FY26 지역별 순매출은 얼마였나요?”

어시스턴트는 이름이나 동의어 중 하나로 지표를 인식하고(조회는 대소문자를 무시하고 이름의 일부와도 일치하므로 revenue로 Net Revenue를 찾을 수 있습니다), 질문에서 세분화 기준과 필터를 가져와 정의를 실행합니다. 질문은 지표의 세분화 열로만 그룹화하거나 필터링할 수 있으며, 그 밖의 항목을 요청하면 추측으로 답하는 대신 거부됩니다. 저장된 이후 테이블에서 열이 사라진 지표도 마찬가지입니다. 이 경우 거부 메시지에 지표와 해당 버전이 표시되며, 아키텍트가 정의를 수정해야 합니다.

질문의 단어는 차원을 통해 열의 값이 됩니다. 아키텍트가 세분화 열을 차원에 연결해 두었으면 어시스턴트는 질문의 단어를 해당 차원의 멤버 이름 및 별칭과 대소문자를 무시하고 대조합니다. 하나의 멤버를 가리키는 단어는 그 멤버의 값이 됩니다. 리프는 자기 자신이 값이고, EMEA 같은 상위 멤버는 그 아래의 모든 리프로 확장되므로 “EMEA의 순매출”은 EMEA의 모든 지역으로 필터링됩니다. 어떤 멤버도 가리키지 않거나 둘 이상을 가리키는 단어(Seaboard가 두 멤버의 별칭일 수 있음)이면서 그중 어느 것도 사용자가 쓴 표기와 정확히 일치하지 않으면, 어시스턴트가 사용자에게 되물을 후보 목록으로 반환됩니다. 어시스턴트가 대신 하나를 고르는 일은 없습니다. 차원에서 단어를 조회하려면 PlaidCloud의 다른 곳에서 차원을 읽을 때와 마찬가지로 차원을 읽을 권한이 필요합니다.

어시스턴트가 사용하는 결과에는 지표와 그 버전이 명시되고 행 접근 권한이 적용되었는지 표시됩니다. 답변에 어떤 지표를 사용했는지 나와 있지 않으면 물어보십시오. PlaidCloud 기본 제공 AI 어시스턴트에서는 수치가 ✓ 표시가 있는 별도 카드에 나타납니다. 지표에서 가져온 수치를 참조하십시오. PlaidCloud가 AI 답변에 등급을 매기고 주의 사항을 덧붙이는 방식에 대한 전반적인 내용은 신뢰할 수 있는 답변을 참조하십시오.

행 접근 권한은 지표가 읽는 모든 테이블에 적용됩니다. 소스와 각 룩업 모두 마찬가지입니다. 룩업 행은 숨겨져 있지만 그 룩업 행이 레이블을 붙이는 소스 행은 보이는 경우, 해당 소스 행은 계속 집계됩니다. 예를 들어 지역 APAC의 룩업 행은 볼 수 없지만 해당 매출은 볼 수 있다면, 그 매출은 합계에 포함되고 지역별 세분화에서는 빈 지역 아래에 나타나며, 지역으로 필터링하거나 지표 자체가 룩업 열로 필터링하는 경우에는 대개 제외됩니다.

행 접근 권한은 룩업에도 영향을 줍니다. 세분화 열이 거버넌스 대상이면 접근 권한이 허용하는 값만 제안됩니다. 볼 수 있는 하위 항목이 없는 멤버는 값으로도 후보로도 제안되지 않으며, 상위 멤버는 볼 수 있는 리프로만 확장됩니다. 모든 행을 읽는 아키텍트는 모든 멤버를 봅니다.

아키텍트는 프로젝트의 다른 모든 곳에서와 마찬가지로 모든 행을 읽습니다.

비교, 순위 및 비중

지표에 대한 질문에서는 비교 하나, 순위 하나, 전체 대비 비중을 함께 요청할 수도 있습니다. 각각 지표 자체의 수치에 대한 고정된 계산이며 질문한 사람의 행 접근 권한이 적용되고, 어시스턴트가 직접 계산하는 것은 없습니다.

요청	반환되는 내용	API에서
예산 대비 차이	세분화 값별로 실적 수치, 예산 수치, 차이(value), 예산 크기에 대한 백분율로 나타낸 차이(pct)입니다. 예산이 음수여도 차이의 부호는 유지됩니다.	compare: "variance"
전체 대비 비중	각 행의 수치를 세분화의 모든 행에 대한 합계로 나눈 값(share), 또는 지정한 within 열이 같은 행들에 대한 합계로 나눈 값입니다.	share: {"within": ["region"]}, 전체 합계는 {}
상위 또는 하위 N	가장 높은 N개 수치, 또는 order: "asc"일 때 가장 낮은 N개 수치와 해당 rank입니다. within 열을 지정하면 그룹별로 계산합니다. 동률인 행은 순위를 공유하며 모두 유지되므로 N개보다 많을 수 있습니다. 비용 지표에서 예산을 가장 많이 초과한 항목은 차이의 상위 N이고, 매출 지표에서는 하위 N입니다.	top: {"n": 10, "within": [], "order": "desc"}

“Finance 프로젝트에서 예산을 가장 많이 초과한 비용 센터 다섯 곳은 어디인가요?”

“각 지역이 전체 지출에서 차지하는 비중은 얼마이고, 가장 큰 지역은 어디인가요?”

차이를 계산하려면 시나리오가 있는 지표가 필요합니다. 시나리오가 없는 지표나 파생 지표는 이를 거부합니다. 각 쪽은 비교하기 전에 개별적으로 합산됩니다. 예산 행이나 실적 행이 없는 세분화 값은 0이 아니라 빈 차이를 표시하며(단일 합계로 요청한 count 지표는 예외로, 행이 없는 쪽은 0으로 계산됩니다), 예산이 0인 경우의 백분율도 마찬가지입니다.

순위와 비중은 지표의 수치에 대해, 또는 차이나 시간에 따른 비교를 요청한 경우 그 차이에 대해 계산되므로, *“초과 지출의 대부분을 차지하는 비용 센터는 어디인가”*는 비중과 순위가 있는 차이 계산입니다. pct는 백분율이므로 12는 12%를 뜻하고, share는 분수입니다. 비중은 상위 N이 일부를 남기기 전에 세분화의 모든 행에 대해 계산되므로, 반환되는 행의 비중을 합해도 1이 되지 않을 수 있습니다. 비어 있는 수치는 어떤 순서를 요청하든 마지막 순위가 되며 비중도 비어 있습니다. 합계가 0인 경우의 비중도 마찬가지입니다.

비중은 사용자가 볼 수 있는 범위에 대한 것입니다. 행 접근 권한이 EMEA로 제한된 사람은 EMEA의 비용 센터를 EMEA 합계에 대한 비중으로 받으며, 결과에는 행 접근 권한이 적용되었다고 표시됩니다. 비중이나 순위의 within 열은 요청한 세분화 열 중에 있어야 합니다. 또한 결과의 자체 열과 같은 이름의 열(value, 그리고 해당 연산자를 요청한 경우 actual, budget, current, prior, pct, share, rank, year, period, cumulative)로 그룹화하는 질문은 거부됩니다. 비교가 둘이거나 순위가 둘인 질문도 거부됩니다.

시간에 따라 비교하기

정의에 시간 열(API에서는 time)이 있는 지표는 특정 회계 기간 하나를 질문하고, 그 이전 기간과 비교하고, 기간별로 누계를 낼 수 있습니다. 시간 열은 각 행이 회계 달력에서 어디에 위치하는지를 두 가지 방식 중 하나로 알려 줍니다.

• 날짜 열과 fiscal_year_start(회계 연도가 시작되는 달력상의 월이며 기본값은 1월을 뜻하는 1)를 사용합니다. 기간은 시작 월부터 번호를 매긴 회계 연도의 월입니다. 연도가 10월에 시작하면 1기간은 10월이고 7기간은 4월입니다. 분기는 세 개의 기간입니다. 1월에 시작하지 않는 회계 연도는 기본적으로 그 연도가 끝나는 달력 연도로 이름이 붙습니다(fiscal_year_label이 ending). fiscal_year_label을 starting으로 설정하면 시작하는 연도로 이름이 붙습니다. 10월 시작인 경우 2025년 10월부터 2026년 9월까지는 기본적으로 FY2026이고, starting에서는 FY2025입니다. 행은 날짜 범위로 읽으므로 큰 테이블에서도 질문이 빠르게 처리됩니다.
• 회계 연도 열과 기간 열은 둘 다 회계 연도(26이 아니라 2026)와 그 안의 기간을 1부터 번호를 매긴 정수로 담으며, periods_per_year를 함께 사용합니다. 기본값은 12이고, 13기간 달력은 13, 주 단위는 52, 분기 단위는 4입니다. 분기는 기간이 4로 나누어질 때만 존재합니다. 53주 연도가 있는 달력은 53을 설정할 수 있지만 분기를 쓸 수 없게 됩니다. 두 열 중 하나라도 2024-01이나 FY26처럼 정수가 아닌 값을 가지고 있으면 저장이 거부되며, 거부 메시지에는 열과 값이 표시됩니다. 07처럼 텍스트로 저장된 숫자는 허용되며, 원장의 0기간이나 13기간처럼 연도를 벗어난 기간도 허용됩니다. 특정 기간에 대한 질문은 이러한 행을 제외합니다.

그러면 질문은 기간을 지정합니다. 회계 연도 또는 그 안의 한 분기나 한 기간입니다. 누계(to date)는 이를 연초까지 확장하므로, 4월 누계는 해당 연도의 첫 달부터 4월까지입니다.

“FY2026 1분기 지역별 매출은 얼마였고, 직전 분기와 비교하면 어떤가요?”

“4월까지의 연초 대비 매출을 작년 같은 달과 비교해 주세요.”

“FY2026 월별 매출을 누적 합계로 보여 주세요.”

요청	반환되는 내용	API에서
한 기간	해당 기간만의 지표이며 일반적인 세분화, 비중, 순위를 포함합니다. 예산 대비 차이는 해당 기간에 대해 두 시나리오를 모두 읽습니다.	period: {"year": 2026}, {"year": 2026, "quarter": 1}, {"year": 2026, "period": 7}
전년 동기 대비	세분화 값별로 해당 기간의 수치(current), 1년 전 같은 기간의 수치(prior), 차이(value), pct입니다. 답변에 이전 기간이 명시됩니다.	period와 함께 compare: "yoy"
전 분기 대비	같은 항목을 직전 분기와 비교합니다. 첫 번째 분기는 전년도 4분기와 비교됩니다.	compare: "qoq", period에 quarter가 지정되어야 함
전 기간 대비	같은 항목을 직전 기간과 비교합니다. 첫 번째 기간은 전년도의 마지막 기간과 비교됩니다. 12기간 달력에서는 월 대비 월이며, 이름이 여기서 유래했습니다.	compare: "mom", period에 period가 지정되어야 함
연초 누계	연초부터 지정한 분기 또는 기간의 끝까지이며, 단독으로 사용하거나 yoy와 함께 사용하면 전년 같은 달과 비교합니다. qoq 또는 mom과 함께 사용하면 거부됩니다.	period에 "to_date": true
누적 합계	요청한 기간 안의 회계 연도와 기간마다 한 행으로, 해당 기간의 수치(value)와 지금까지의 합계(cumulative)를 보여 줍니다. 기간이 없으면 여러 해에 걸쳐 첫 행부터 마지막 행까지 계산합니다. 비교, 비중, 순위는 적용되지 않습니다.	cumulative: true

pct는 이전 수치의 크기에 대한 백분율로 나타낸 차이이며, 차이 계산과 마찬가지로 이전 수치가 음수여도 차이의 부호를 유지합니다. 두 기간은 각각 개별적으로 합산되고 두 합계는 세분화 값으로 짝지어지며, 인접한 행에서 읽어 오는 것은 없습니다. 따라서 작년에 행이 없는 달은 행이 있던 가장 가까운 달이 아니라 빈 값으로 비교되고, 두 기간 중 한쪽에만 행이 있는 세분화 값은 다른 쪽, 차이, pct를 0이 아닌 빈 값으로 표시합니다.

누적 합계는 sum 및 count 지표용입니다. 평균, 고유 개수, 최솟값, 최댓값은 시간에 따라 누적되지 않으므로 거부됩니다. 행이 없는 기간은 누적 합계에 행이 생기지 않으며, 합계는 그 기간을 지나서도 이어집니다.

기간을 지정하거나, 시간에 따라 비교하거나, 누적 합계를 요청하는 질문에서는 시간 열로 필터링하거나 그룹화할 수 없습니다. 시간 열이 어떤 행을 읽을지와 행이 어디에 놓일지를 결정하기 때문입니다. 이 중 어느 것도 하지 않는 질문은 다른 세분화 열과 마찬가지로 시간 열로 필터링하고 그룹화할 수 있습니다. 또한 연도를 넘어가는 기간(12기간 달력의 13기간), 분기가 없는 달력의 분기, 파생 지표에 대한 시간 비교 또는 누적 합계, 비교에 필요한 기간 종류를 지정하지 않은 질문도 거부됩니다. 파생 지표는 모든 입력에 같은 회계 달력의 시간 열이 있을 때 한 기간을 질문할 수 있으며, 이 경우에도 그 열들은 필터링하거나 그룹화할 수 없습니다. 시간 비교는 질문의 유일한 비교이므로 예산 대비 차이와 함께 사용할 수 없지만, 비중과 순위는 그 차이에 계속 적용할 수 있습니다.

지표 폐기하기

지표를 폐기하면 영구적으로 사용이 중단됩니다. 프로젝트를 읽는 사람에게는 더 이상 보이지 않고, 아키텍트에게는 이력과 함께 폐기됨으로 표시되며, 더 이상 편집하거나 실행할 수 없습니다. 아키텍트는 어시스턴트에게 요청하거나 POST /rest/v1/analyze/metric/retire로 폐기합니다. 파생 지표의 바탕이 되는 지표는 해당 파생 지표를 폐기하거나 이 입력을 더 이상 사용하지 않는 버전을 저장하기 전에는 폐기할 수 없습니다. 폐기한 지표를 대체하려면 새 지표를 정의하십시오.

MCP 및 REST API

작업	MCP 도구	REST
프로젝트의 지표를 전체 정의와 함께 나열합니다. q는 이름이나 동의어에 해당 문자열이 포함된 지표만 남깁니다	metric_find	GET /rest/v1/analyze/metric/definitions?project_id=&q=
질문의 단어를 세분화 열의 값으로 변환합니다	column과 words가 있는 metric_values	GET /rest/v1/analyze/metric/values?project_id=&metric_id=&column=&words=
지표 하나를 읽습니다		GET /rest/v1/analyze/metric/definition?project_id=&metric_id=
정의 또는 편집	metric_upsert	POST / PUT /rest/v1/analyze/metric/definition
폐기	action: retire가 있는 metric_review	POST /rest/v1/analyze/metric/retire
실행	group_by, filters, 선택적 period, compare, share, top, cumulative가 있는 metric_run	같은 필드가 있는 POST /rest/v1/analyze/metric/run
이전 버전(아키텍트 전용)		GET /rest/v1/analyze/metric/flashback-versions

metric_upsert는 {name, memo, synonyms, definition} 형식의 spec을 받으며, 저장하지 않고 정의를 검사하는 dry_run을 지원합니다. 기본 지표의 definition은 {source, joins, measure, filters, grain, dimensions, scenario, time}이며, dimensions는 {<breakdown column>: <dimension id>}, measure는 {agg, column} 또는 {agg: "weighted_avg", column, weight}, scenario는 {column, actual, budget}, time은 {column, fiscal_year_start, fiscal_year_label} 또는 {year_column, period_column, periods_per_year}입니다. 파생 지표의 definition은 {kind, op, inputs, factor}이며, 계산된 세분화 열은 정의 옆에 grain으로 반환됩니다.

관련 문서

• 분석 경로 — 사람들이 질문하는 테이블에 이름을 붙이고, 어시스턴트에게 각 경로의 고정 필터와 용어를 제공합니다
• 신뢰할 수 있는 답변 — PlaidCloud가 모든 AI 답변에 등급을 매기고 주의 사항을 덧붙이는 방식
• 데이터 접근 제어 — 지표가 실행되는 기준이 되는 행 접근 권한