# 시맨틱 지표

> Apache Ossie 모델에 지표를 한 번 정의하고 DuckLocal 사이드바나 ducklocal metrics CLI에서 실행합니다. 하나의 DuckDB SELECT로 컴파일됩니다.

Source: https://ducklocal.app/docs/ko/metrics

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

지표는 창의 사이드바에서 실행할 수도 있고, 명령줄에서 `ducklocal metrics`로 실행할 수도 있습니다. [공식 스킬](cli.md#install-the-official-skill)을 설치한 에이전트는 SQL을 직접 쓰는 대신 지표로 질문합니다.

::: info 0.4.1보다 새로운 기능
시맨틱 지표는 DuckLocal의 `main` 브랜치에 있으며 다음 릴리스에 포함됩니다. 0.4.1에는 없습니다.
:::

## 모델 작성하기 {#write-a-model}

`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 예제](example-cloudtrail.md)에서 가져온 것으로, 예제 대시보드가 정의하는 `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`가 테이블 이름이 아닌 모델은 전체가 거부됩니다.

## 사이드바에서 지표 실행하기 {#sidebar}

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

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

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

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

## 명령줄에서 지표 실행하기 {#cli}

```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`](cli.md#query-options)처럼 SQL을 실행합니다. `query`의 `--database`, `--format`, [`--restricted`](agent-workflows.md) 옵션을 받고, 컴파일된 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이 되는 방식 {#compiled-sql}

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

## 요청이 거부될 때 {#refusals}

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` | 모델 자체가 잘못되었습니다. [모델 작성하기](#write-a-model)를 참고하세요 |

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