> ## Documentation Index
> Fetch the complete documentation index at: https://docs.aftersell.com/llms.txt
> Use this file to discover all available pages before exploring further.

# AftersellQL (AQL) 참조

> AftersellQL 쿼리 언어 참조: 사용 가능한 지표와 차원, 예시가 포함된 AQL 절 구문, Explorer의 시간대 규칙을 확인하세요.

[Explorer](/ko/aftersell/reports_explorer)에서 만드는 모든 쿼리는 **AftersellQL (AQL)** 문이에요. 대부분의 경우 쿼리를 시각적으로 만들기 때문에 AQL을 직접 작성할 일은 없어요. 이 페이지는 선택할 수 있는 지표와 차원, AQL 텍스트 형식, 시간대 규칙에 대한 참조 문서예요.

<div id="available-metrics">
  ## 사용 가능한 지표
</div>

선택할 수 있는 지표들로, 지표 선택기와 같은 방식으로 그룹화되어 있어요.

<div id="revenue-profit">
  ### 수익 및 이익
</div>

| 지표 | 설명 |
| - | - |
| **Revenue** | 스토어 기본 통화 기준 업셀 수익. |
| **Revenue (USD)** | 통화 간 비교를 위해 USD로 환산한 업셀 수익. |
| **Revenue Per Visit** | 노출 세션당 업셀 수익. 상품, 플레이스먼트, 퍼널, 기기별로 세분화할 수 없어요. |
| **Avg. Conversion Value** | 수락된 오퍼당 수익. 평균 업셀 금액(Average Upsell Value)이라고도 해요. |
| **Upsell Revenue Per Order** | 업셀 수익(USD)을 총 주문 수로 나눈 값. 스토어 수준에서만 사용 가능해요. |
| **Product Profit** | 업셀된 상품의 수익에서 매출 원가(COGS)를 뺀 값. 판매자가 설정한 COGS에 의존하므로 추정치로 취급하세요. 비용이 추적되지 않는 상품은 수익이 이익으로 보고되며, 비용 커버리지는 스토어마다 달라요. 상품 단위에서만 사용 가능하며 퍼널, 플레이스먼트, 기기별로 세분화할 수 없어요. |

<div id="conversions">
  ### 전환
</div>

| 지표 | 설명 |
| - | - |
| **Conversions** | 오퍼 수락 이벤트 수. 수락된 오퍼 하나가 전환 하나이므로, 두 개의 오퍼를 수락한 세션은 두 번 집계돼요. |
| **Accept Rate** | 세션 기반: 오퍼를 보고 하나 이상 수락한 세션의 비율. Conversions와는 별도의 롤업에서 독립적으로 계산되므로 Conversions ÷ Impressions와 같지 않아요. |
| **Units Sold** | 업셀 오퍼를 통해 판매된 총 수량. |
| **Decline Rate** | 명시적으로 거절된 구매 후 오퍼의 비율. 구매 후에만 해당돼요. |

<div id="engagement">
  ### 참여
</div>

| 지표 | 설명 |
| - | - |
| **Impressions** | 오퍼를 본 고유 세션 수. |
| **Show Rate** | 노출로 이어진 결정의 비율. |

<div id="store-performance">
  ### 스토어 성과
</div>

| 지표 | 설명 |
| - | - |
| **Total Store Revenue** | Shopify에서 결제된 주문의 총 수익. 스토어 수준에서만 사용 가능하며 서피스, 퍼널, 플레이스먼트, 기기별로 세분화할 수 없어요. |
| **Orders** | Shopify에서 결제된 총 주문 수. 스토어 수준에서만 사용 가능해요. |
| **Average Total Order Value** | 스토어 수익을 주문 수로 나눈 값. 스토어 수준의 평균 주문 금액이에요. |

<div id="rokt-network">
  ### Rokt 네트워크
</div>

| 지표 | 설명 |
| - | - |
| **Rokt Revenue** | 스토어에 귀속된 Rokt 네트워크 수익. |
| **Rokt Transactions** | 스토어의 Rokt 네트워크 거래 수. |
| **Rokt Revenue / Transaction** | 시간 버킷별 Rokt 수익을 거래 수로 나눈 값. |
| **Rokt Impressions** | 스토어 플레이스먼트 전반의 총 Rokt 네트워크 노출 수. 업셀 **Impressions**와는 별개예요. |
| **Rokt Referrals** | Rokt 네트워크 추천 수로, 쇼핑객을 Rokt 파트너로 보낸 긍정적 참여예요. |

<div id="dimensions">
  ## 차원
</div>

차원은 속성별로 지표를 세분화해요. 모든 차원이 모든 지표와 호환되는 것은 아니며, Explorer는 호환되지 않는 조합을 자동으로 방지해요(예: **Decline rate**와 **Show rate**는 **Currency**별로 세분화할 수 없어요).

<div id="available-dimensions">
  ### 사용 가능한 차원
</div>

| 차원 | 설명 |
| - | - |
| **Date** | 결과를 일, 주, 월 단위로 그룹화해요. |
| **Surface** | 업셀 서피스: PPU(구매 후), Checkout, Thank You Page, Cart. |
| **Funnel** | 오퍼가 속한 특정 퍼널. |
| **Product** | 업셀된 상품. |
| **Placement** | 퍼널 내 플레이스먼트. |
| **Device** | 기기 유형: Mobile, Desktop, Unknown. 태블릿 값은 별도로 없어요. |
| **Currency** | ISO 통화 코드(예: USD, EUR, GBP). 다중 통화 스토어에 유용해요. |

<div id="unavailable-dimensions">
  ### 사용할 수 없는 차원
</div>

다음 차원은 아직 개발 중이에요. 선택기에 표시되지만 구현될 때까지 모든 지표에 대해 'Not compatible'로 표시돼요.

| 차원 | 설명 |
| - | - |
| **Flow type** | 업셀 플로우 유형. |
| **Experiment** | A/B 테스트 또는 실험 변형. |
| **Outcome** | 결정 결과(예: eligible, out of stock). |
| **Reason code** | 결정 결과의 사유. |
| **Scope** | 결정 범위(Flow, Experience, Placement, ItemSlot). |
| **Response type** | 오퍼 응답(Accepted, Declined, Timeout). |

<div id="aql-statement-syntax">
  ## AQL 문 구문
</div>

AQL 문은 여러 절로 구성된 하나의 질문이에요. `SELECT`와 시간 범위(`SINCE`)만 필수이고 나머지는 모두 선택 사항이에요. 선택 절을 포함할 때는 다음 순서로 작성해야 해요:

```text theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT    <metrics>                    -- what to measure (required)
WHERE     <filters>                    -- narrow the data
GROUP BY  <dimensions>                 -- break the numbers down
SINCE     <time range>                 -- the period to cover (required)
GRAIN     <time grain>                 -- bucket size for time series
COMPARE   <comparison>                 -- compare against another period
CHART     <visualization>              -- how to display the result
TIMEZONE  "<timezone>"                 -- timezone for date buckets
ORDER BY  <field> <direction>          -- sort the results
LIMIT     <number>                     -- cap the number of rows
```

최소 예시로, 지난 30일간의 일별 업셀 수익과 수락률은 다음과 같아요:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
```

<Note>
  키워드는 대소문자를 구분하지 않으며(`SELECT`와 `select` 모두 작동), 문은 세미콜론으로 끝나지 않아요. 문자열 값은 큰따옴표로 감싸고, 숫자와 목록은 감싸지 않아요.
</Note>

<div id="select-and-group-by">
  ### SELECT와 GROUP BY
</div>

* \*\*`SELECT`\*\*는 측정할 지표를 쉼표로 구분해 나열해요. 예: `SELECT revenue, impressions, accept_rate`.
* \*\*`GROUP BY`\*\*는 `date`, `device`, `surface`, `funnel` 같은 하나 이상의 차원으로 지표를 세분화해요. `GROUP BY`가 없으면 전체 기간에 대한 단일 합계가 나와요.

<div id="filtering-with-where">
  ### WHERE로 필터링하기
</div>

`WHERE`는 측정 전에 데이터를 좁혀요. 조건은 `AND`로 결합하세요.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT revenue
WHERE device = "mobile"
GROUP BY date
SINCE last_month
GRAIN day
```

<Warning>
  `impressions`, `accept_rate`, `rpv`는 기기, 퍼널, 플레이스먼트, 상품별로 필터링하거나 그룹화할 수 **없어요**. 해당 소스 롤업에 그런 열이 없기 때문이에요. 이 중 하나를 선택하는 쿼리에 `WHERE device = "mobile"`을 추가하면 `metric "impressions" cannot be filtered by "device"` 오류와 함께 거부돼요.
</Warning>

지원되는 비교 연산자는 `=`, `!=`, `IN`, `NOT IN`, `>`, `<`, `>=`, `<=`예요. 여러 값을 일치시키려면 `IN`과 목록을 사용하세요:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
WHERE surface IN ["PPU", "Checkout"]
```

`experiment`는 필터링 가능한 필드가 **아니에요**. 롤업 소스가 없으므로 `WHERE experiment IN [...]`은 `filters on "experiment" are not supported.` 오류와 함께 거부돼요.

**funnel** 필터는 다중 선택을 지원해요. **is one of**(`IN`)는 선택한 퍼널만 포함하고, **is not one of**(`NOT IN`)는 선택한 퍼널을 제외해요. **Funnel**로 그룹화하고 **is one of** 필터를 적용하면 차트에 선택한 퍼널마다 하나의 선이 표시되며, "Other"로 합쳐지지 않아요.

<div id="time-ranges-and-comparisons">
  ### 시간 범위와 비교
</div>

모든 쿼리에는 `SINCE`로 설정하는 시간 범위가 필요해요:

| 형식 | 예시 | 의미 |
| - | - | - |
| 프리셋 | `SINCE last_30d` | **어제**(UTC)에 끝나는 롤링 기간. 진행 중인 오늘은 의도적으로 제외되므로 `last_1d`는 어제만 의미하고, `this_month`는 1일부터 어제까지예요. |
| 사용자 지정 기간 | `SINCE 2026-07-02 UNTIL 2026-07-05` | ISO 날짜(`YYYY-MM-DD`)를 사용하는 고정 범위. |

사용 가능한 프리셋: `last_1d`, `last_7d`, `last_30d`, `last_90d`, `this_month`, `last_month`, `this_year`.

* \*\*`GRAIN`\*\*은 시계열의 버킷 크기를 설정해요: `day`, `week`, `month`. (`hour`는 구문 분석되지만 시간별 데이터를 제공하는 롤업이 없으므로 이러한 쿼리는 `group_by / time_grain combination is not supported.` 오류와 함께 거부돼요.)
* \*\*`COMPARE`\*\*는 두 번째 기간을 겹쳐 표시해요. 바로 직전의 같은 길이 기간인 `previous_period`를 사용하세요. `previous_year`는 웨어하우스에 2026년 2월 이전 데이터가 없기 때문에 Compare 선택기에서 숨겨져 있어요. 이전에 저장된 쿼리가 계속 구문 분석되도록 AQL에서만 입력할 수 있어요.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- A four-day sale vs the four days immediately before it
SELECT revenue, impressions, accept_rate
GROUP BY date
SINCE 2026-07-02 UNTIL 2026-07-05
GRAIN day
COMPARE previous_period
```

<Note>
  보고 데이터는 **2026년 2월**부터 시작되므로, 그보다 이전 기간은 두 기간 모두 빈 결과를 반환해요.
</Note>

<div id="choosing-a-chart">
  ### 차트 선택하기
</div>

* \*\*`CHART`\*\*는 결과 표시 방식을 설정해요: `scorecard`, `line_chart`, `bar_chart`, `area_chart`, `funnel_chart`, `table`.
* \*\*`TIMEZONE`\*\*은 날짜 버킷에 사용할 시간대를 따옴표로 감싼 IANA 이름으로 설정해요. 예: `TIMEZONE "America/New_York"`. 기본값은 UTC예요([시간대](#timezones) 참조).

`funnel_chart` 유형에는 특정 요구 사항이 있어요:

* **플레이스먼트 모드.** `placement`로 그룹화하고 지표 하나를 선택하세요. 단계는 표준 플레이스먼트 순서(기본 업셀, 다운셀, 추가 업셀 순)로 정렬돼요. 첫 번째 지표만 표시되며, 추가 지표는 각주에 표시돼요.
* **지표 모드.** `GROUP BY` 없이 두 개 이상의 지표를 선택하세요. 각 지표가 쿼리 순서대로 퍼널 단계가 돼요(예: `SELECT impressions, conversions`는 노출에서 전환으로의 이탈을 보여줘요). 모든 지표는 같은 단위를 사용해야 해요.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Placement funnel: conversion drop-off across placements
SELECT conversions
GROUP BY placement
SINCE last_30d
CHART funnel_chart
```

<Warning>
  플레이스먼트 모드에는 플레이스먼트별로 세분화할 수 있는 지표가 필요해요. `impressions`, `accept_rate`, `rpv`는 세분화할 수 없으므로, 이들에 대해서는 퍼널 차트에 "These metrics can't be grouped by placement"가 표시돼요.
</Warning>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Metric funnel: impressions to conversions drop-off
SELECT impressions, conversions
SINCE last_30d
CHART funnel_chart
```

<div id="sorting-and-limiting">
  ### 정렬 및 제한
</div>

* \*\*`ORDER BY`\*\*는 지표나 차원을 기준으로 `ASC` 또는 `DESC`로 결과를 정렬해요.
* \*\*`LIMIT`\*\*은 반환되는 행 수를 제한하며, "상위 N개" 질문에 유용해요.

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Top 20 products by upsell revenue this month
SELECT revenue, conversions, avg_conversion_value
GROUP BY product
SINCE this_month
ORDER BY revenue DESC
LIMIT 20
```

<div id="more-examples">
  ### 추가 예시
</div>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Daily performance vs the previous period
SELECT revenue, impressions, conversions, accept_rate
GROUP BY date
SINCE last_30d
GRAIN day
COMPARE previous_period
```

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Mobile vs desktop revenue over the last 90 days
SELECT revenue
GROUP BY device
SINCE last_90d
ORDER BY revenue DESC
```

<Note>
  `impressions`, `accept_rate`, `rpv`는 기기별로 세분화할 수 없어요. 이들의 롤업은 스토어 × 서피스 × 일 단위이며 기기 열이 없어요. 기기 비교에는 `revenue`(또는 전환 기반의 다른 지표)를 사용하세요.
</Note>

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
-- Which surface is driving the most revenue?
SELECT revenue, impressions, accept_rate
GROUP BY surface
SINCE last_30d
ORDER BY revenue DESC
```

<div id="timezones">
  ## 시간대
</div>

기본적으로 쿼리는 UTC로 실행돼요. 날짜 버킷 결과가 현지 시간을 반영하도록 시간대를 재정의할 수 있어요(툴바 단계는 [시간대 설정하기](/ko/aftersell/reports_explorer#setting-a-timezone) 참조).

<Note>
  **Impressions**, **Accept Rate**, **Revenue Per Visit**가 포함된 쿼리는 선택한 시간대와 관계없이 항상 UTC로 날짜를 버킷화해요. 이 지표들은 UTC 기준 일 단위로 보고되는 일별 롤업에서 가져오기 때문이에요. 쿼리에 이 중 하나와 다른 지표가 섞여 있으면 날짜 버킷이 맞춰지도록 전체 결과 집합이 UTC로 대체돼요.
</Note>

<div id="the-timezone-clause">
  ### TIMEZONE 절
</div>

`CHART`와 `ORDER BY` 사이에 위치하는 `TIMEZONE` 절로 AQL에서 직접 시간대를 지정하세요:

```aql theme={"theme":{"light":"snazzy-light","dark":"github-dark"}}
SELECT ...
CHART ...
TIMEZONE "Asia/Tokyo"
ORDER BY ...
```

이 절이 있으면 해당 쿼리에 대해 툴바 선택을 재정의하며, 저장 후 다시 불러올 때도 유지돼요.

<div id="available-timezones">
  ### 사용 가능한 시간대
</div>

선택기(및 `TIMEZONE` 절)는 정해진 10개 시간대만 허용해요. 그 외의 IANA 시간대는 지원되지 않는 것으로 거부돼요.

| 시간대 | 예시 위치 |
| - | - |
| UTC | 협정 세계시 |
| America/New\_York | 뉴욕 (ET) |
| America/Chicago | 시카고 (CT) |
| America/Denver | 덴버 (MT) |
| America/Los\_Angeles | 로스앤젤레스 (PT) |
| Europe/London | 런던 (GMT/BST) |
| Europe/Paris | 파리 (CET/CEST) |
| Asia/Tokyo | 도쿄 (JST) |
| Asia/Singapore | 싱가포르 (SGT) |
| Australia/Sydney | 시드니 (AEST/AEDT) |

<div id="account-default-and-how-timezone-affects-results">
  ### 계정 기본값과 시간대가 결과에 미치는 영향
</div>

애널리틱스 설정에서 **Lock reporting timezone**이 활성화되어 있으면 **Account default**를 선택할 때 고정된 시간대가 사용돼요(툴바에 확인된 시간대가 표시돼요. 예: **Timezone: Account default (Paris (CET))**). 애널리틱스 설정 페이지는 전체 IANA 목록을 허용하지만 Reports는 위의 10개 시간대만 지원해요. 고정된 시간대가 그중 하나가 아니면 **Account default**는 별도 안내 없이 UTC로 처리돼요. **Lock reporting timezone**이 활성화되어 있지 않으면 **Account default**는 UTC로 대체돼요.

시간대가 설정되면 날짜 버킷화에 UTC 대신 현지 시간이 사용돼요. 예를 들어 `2026-03-29T01:30:00Z`에 발생한 이벤트는 뉴욕(ET)에서는 3월 28일, 파리(CET)에서는 3월 29일에 해당해요. 이전에 저장된 쿼리를 포함해 시간대가 없는 쿼리는 계속 UTC로 실행돼요.