콘텐츠로 이동

시맨틱 지표 ​

시맨틱 모델은 어떤 숫자가 무엇을 뜻하는지 한 번만 정해 둡니다. 무엇을 오류로 셀지, 어떤 호출이 권한 변경인지, 두 테이블을 어떻게 조인할지. DuckLocal은 Apache Ossie 파일 model.ossie.yaml에서 모델을 읽고, 각 요청(이 지표들을, 이 필드별로, 이 조건에서)을 하나의 DuckDB SELECT로 컴파일합니다. 같은 모델에 대한 같은 요청은 항상 같은 SQL로 컴파일되므로, error_rate를 쓰는 모든 차트, 답변, 에이전트가 같은 것을 뜻하게 됩니다.

지표는 창의 사이드바에서 실행할 수도 있고, 명령줄에서 ducklocal metrics로 실행할 수도 있습니다. 공식 스킬을 설치한 에이전트는 SQL을 직접 쓰는 대신 지표로 질문합니다.

0.4.1보다 새로운 기능

시맨틱 지표는 DuckLocal의 main 브랜치에 있으며 다음 릴리스에 포함됩니다. 0.4.1에는 없습니다.

모델 작성하기 ​

model.ossie.yaml을 프로젝트 루트, 즉 대시보드와 같은 위치나 그 위에 둡니다. DuckLocal은 평평한 Ossie 0.2 형식을 읽습니다:

  • datasets: 각각 source(테이블이나 뷰의 이름), 선택 항목인 primary_key, fields를 가집니다. dimension: {is_time: true}가 붙은 필드는 시간 필드입니다.
  • relationships: from, to, from_columns, to_columns.
  • metrics: 모델 루트나 데이터셋 아래에 둡니다. 데이터셋 아래에 두면 이름은 dataset.metric이 됩니다.

모든 식은 SQL 방언별로 적습니다. DuckLocal은 DUCKDB, OSSIE_SQL_2026, ANSI_SQL 중 그 식에 있는 첫 번째 방언을 쓰고, DuckDB 자체 파서로 읽습니다. 아래의 축약한 모델은 CloudTrail 예제에서 가져온 것으로, 예제 대시보드가 정의하는 events 뷰를 셉니다:

yaml
version: 0.2.0.dev0
name: cloudtrail
ai_context:
  instructions: >
    event_time is UTC. A NULL error_code means the call succeeded.
datasets:
- name: events
  source: events
  fields:
  - name: event_time
    expression: {dialects: [{dialect: ANSI_SQL, expression: event_time}]}
    dimension: {is_time: true}
  - name: ip
    expression: {dialects: [{dialect: ANSI_SQL, expression: ip}]}
    dimension: {is_time: false}
    ai_context: {synonyms: [source_ip, address]}
metrics:
- name: event_count
  description: API calls.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.event_time)}]}
- name: error_count
  description: Calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: COUNT(events.error_code)}]}
- name: error_rate
  description: The share of calls that were refused or failed.
  expression: {dialects: [{dialect: ANSI_SQL, expression: "error_count * 1.0 / NULLIF(event_count, 0)"}]}

error_rate처럼 지표는 다른 지표로 만들 수 있습니다. 쓸 수 있는 방언이 없거나 DuckDB가 파싱할 수 없는 필드나 지표는 문제와 함께 목록에 나오고, 모델의 나머지는 그대로 동작합니다. 이름이 중복되거나, 존재하지 않는 데이터셋으로의 관계가 있거나, source가 테이블 이름이 아닌 모델은 전체가 거부됩니다.

사이드바의 스키마 탭에는 대시보드 아래에 지표 섹션이 있습니다. 최근에 연 대시보드 옆에서 찾은 모델을 나열합니다:

  • DuckLocal은 각 대시보드의 폴더와 그 위로 최대 세 단계까지 model.ossie.yaml을 찾습니다. 이동 가능한 프로젝트를 표시하는 ducklocal-project.json이 있는 폴더에서 멈춥니다. 여러 대시보드에서 같은 모델을 찾더라도 한 번만 나열됩니다.
  • 각 모델 아래에 지표마다 한 행이 있습니다. 모델에 마우스를 올리면 경로와, 데이터셋이 정의된 대시보드가 보입니다. 지표에 마우스를 올리면 설명과 동의어가 보입니다.
  • 쿼리할 수 없는 지표는 쿼리 불가로 표시됩니다. 마우스를 올리면 이유가 보입니다.

지표나 그 ▶ 버튼을 클릭하면 DuckLocal이 지표를 컴파일하고, SQL을 활성 쿼리 에디터에 넣어 실행합니다. 📈 버튼은 지표가 세는 데이터셋의 첫 번째 시간 필드를 기준으로 일별로 나누어 실행합니다.

SQL의 첫 줄에는 숫자의 출처가 적힙니다. 예: -- Metric error_count, from model cloudtrail (model.ossie.yaml, sha256 …). 모델의 데이터셋이 대시보드의 source와 view 블록에서 오면, 그 블록들이 CTE로 쿼리 앞에 붙습니다. 그래서 쿼리는 대시보드가 열려 있든 아니든 창 자체의 연결에서 실행되고, 다른 쿼리처럼 편집할 수 있습니다.

명령줄에서 지표 실행하기 ​

bash
ducklocal metrics                       # 현재 폴더의 모델
ducklocal metrics compile --metric error_count,event_count --by events.ip \
  --where "events.user_name = 'ci-deploy'"
ducklocal metrics query --metric event_count --by events.event_time:day \
  --views reports/investigation.dash --restricted --allow-read data

첫 번째 인수는 모델 파일이나 model.ossie.yaml이 있는 폴더입니다. 생략하면 현재 폴더를 씁니다.

  • ducklocal metrics는 모델의 어휘를 JSON으로 출력합니다:
    • model. sha256과 ai_context를 포함합니다.
    • 각 지표. description, synonyms, queryable을 포함합니다. 쿼리할 수 있는 지표는 세는 데이터셋을 base로 알려 주고, 쿼리할 수 없는 지표는 problem에 이유를 적습니다.
    • 각 필드. dataset.field 형태이며 is_time을 포함합니다.
    • 관계와 그 cardinality. to_columns가 to의 키이면 many_to_one, 아니면 unknown입니다.
  • metrics compile은 요청에 대한 SQL을 열, 기준 데이터셋, 조인, SQL의 sql_sha256과 함께 출력합니다. 데이터는 읽지 않습니다.
  • metrics query는 요청을 컴파일하고 ducklocal query처럼 SQL을 실행합니다. query의 --database, --format, --restricted 옵션을 받고, 컴파일된 SQL, 요청, 모델의 sha256을 담은 semantic 객체를 덧붙입니다. 결과를 인용할 때는 이것을 인용하세요. --views FILE.dash는 그 대시보드의 source와 view 블록을 SQL 앞에 둡니다. 데이터셋이 그곳에 정의된 모델에 씁니다.

요청은 다음으로 이루어집니다:

옵션뜻
--metric NAME[,NAME]계산할 지표. 반복할 수 있습니다
--by REF[,REF]나눌 기준 필드. dataset.field로 씁니다. 그 필드를 가진 데이터셋이 하나뿐이면 필드 이름만 써도 됩니다. dataset.field:GRAIN은 시간 필드를 second, minute, hour, day, week, month, quarter, year 중 하나로 자릅니다. 반복할 수 있습니다
--where SQL조건 하나. 필드만 쓰는 조건은 행을 거르고(WHERE), "error_count > 5"처럼 지표 이름을 쓰는 조건은 그룹을 거릅니다(HAVING). 반복할 수 있고 모두 적용됩니다
--order-by NAME[:desc]출력 열, 또는 그 열이 나온 dataset.field. 기본값은 --by 열의 오름차순입니다
--limit N최대 N행

요청이 SQL이 되는 방식 ​

컴파일된 SQL은 지표가 세는 데이터셋에 대한 하나의 SELECT입니다. 다대일 관계를 따라 요청이 언급한 각 데이터셋으로 LEFT JOIN되므로, 일치하지 않는 행도 NULL 아래에서 셉니다. 출력 열은 필드(ip, 단위가 있으면 event_time_day)나 지표 이름을 따릅니다. 두 이름이 겹치면 한정됩니다(events.user_name). 필드 조건은 WHERE로, 지표 조건은 HAVING으로 갑니다. 각 --where는 식 하나여야 합니다. 서브쿼리, 두 번째 문, 식 바깥의 내용은 거부됩니다.

요청이 거부될 때 ​

DuckLocal은 정확히 답할 수 없는 요청을, 틀릴 수도 있는 숫자를 돌려주는 대신 거부합니다. 거부되면 종료 코드는 2이고 오류에 kind가 붙습니다:

Kind이유
metric_unknown_name그 이름의 지표나 필드가 없습니다. hint가 가장 가까운 이름을 알려 줍니다
metric_fanout필드가 관계의 '다' 쪽에 있어, 조인하면 행이 여러 번 셈해집니다. 지표 자신의 데이터셋 필드로 나누세요
metric_multi_grain지표들이 서로 다른 데이터셋을 셉니다. 각각 따로 쿼리하세요
metric_ambiguous_path, metric_no_path모델이 데이터셋을 조인하는 방법을 정확히 하나로 정해 두지 않았습니다
metric_window_unsupported, metric_nested_aggregate, metric_not_aggregate지표가 윈도 함수이거나, 집계를 중첩하거나, 집계가 아닙니다
metric_no_dialect지표에 DuckLocal이 읽을 수 있는 방언의 식이 없습니다
metric_bad_grain시간 필드가 아닌 필드에 단위를 지정했습니다
metric_filter_refused--where가 식 하나가 아닙니다
metric_missing--metric이 주어지지 않았습니다
metric_no_dataset요청의 어떤 지표도 열을 읽지 않아 셀 데이터셋이 없습니다. 모델의 집계를 한정하세요: COUNT(*)가 아니라 COUNT(events.event_id)
model_invalid모델 자체가 잘못되었습니다. 모델 작성하기를 참고하세요

모델 파일을 읽을 수 없으면 종료 코드 1, kind model_not_found입니다. 모델로 표현할 수 없는 SQL이 필요한 질문은 ducklocal query로 작성하고, 그 숫자가 모델의 지표가 아니라고 밝히세요.

Apache-2.0 라이선스로 공개되었습니다.