> For the complete documentation index, see [llms.txt](https://docs.hackle.io/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hackle.io/catalog/create.md).

# 카탈로그 생성하기

카탈로그를 만드는 방법은 두 가지입니다. **결과는 같은 필드 목록**이므로, 지금 가진 데이터 상황에 맞는 방법을 고르면 됩니다.

<table><thead><tr><th width="125.6640625"></th><th>CSV 업로드로 시작하기</th><th>직접 만들기</th></tr></thead><tbody><tr><td>이런 경우에</td><td>상품 목록 등 CSV 파일이 이미 있는 경우</td><td>아직 데이터 파일이 없고,<br>스키마부터 설계하려는 경우</td></tr><tr><td>방식</td><td>CSV의 컬럼을 읽어 필드 후보를 만들고, 컬럼마다 타입을 지정(매핑)</td><td>필드 이름과 타입을 하나씩 직접 정의</td></tr><tr><td>장점</td><td>실제 샘플 값을 보면서 타입을 정할 수 있어 실수가 적음</td><td>데이터 없이도 구조를 먼저 준비</td></tr></tbody></table>

## CSV 업로드로 시작하기

### Step 1. 파일 선택

1. **생성하기**를 누르고 **CSV 업로드로 시작하기**를 선택합니다.
2. 준비한 CSV 파일을 드래그하거나 **직접 선택**을 눌러 올립니다. 파일은 한 번에 1개만 올릴 수 있습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FSNCliq9GHqJBVS7oQZJW%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%8C%E1%85%A5%E1%86%AB%2011.56.55.png?alt=media&amp;token=711f6266-023e-466b-84a8-bad693a2575f" alt=""><figcaption></figcaption></figure>

#### CSV 파일 준비 체크리스트 <a href="#csv-checklist" id="csv-checklist"></a>

업로드 전에 파일이 아래 조건을 모두 만족하는지 확인하세요. 하나라도 빠지면 업로드가 실패하거나 값이 비어서 올라갑니다.

<table><thead><tr><th width="153.296875">확인 항목</th><th>요건</th></tr></thead><tbody><tr><td>헤더</td><td>첫 행은 필드 이름입니다. 이 이름이 그대로 카탈로그의 필드명이 됩니다.<br>필드명은 영문·숫자·<code>-</code>·<code>_</code>만 권장합니다.</td></tr><tr><td><code>id</code> 컬럼</td><td>반드시 있어야 합니다. 이름은 정확히 <code>id</code>여야 하며, 컬럼 순서는 상관없습니다.</td></tr><tr><td><code>id</code> 값</td><td>중복 없음 · 최대 300자 · 영문·숫자·<code>-</code>·<code>_</code>만 사용</td></tr><tr><td>컬럼 수</td><td>최대 50개</td></tr><tr><td>값 형식</td><td>각 컬럼의 값이 타입(string·number·boolean·time)에 맞아야 합니다.<br>숫자 컬럼에는 단위나 콤마가 없어야 하고, 날짜 컬럼은 시간대 오프셋이 있는 ISO 8601 형식이어야 합니다.</td></tr><tr><td>미정의 값</td><td>빈 셀은 허용됩니다.<br><code>NULL</code>, <code>null</code>, <code>-</code> 같은 값은 빈 값이 아니라 문자로 저장되니 비워 두세요.</td></tr><tr><td>파일 형식</td><td>CSV, UTF-8 인코딩</td></tr><tr><td>파일 크기</td><td>최대 500MB</td></tr><tr><td>아이템 수</td><td>최대 100만 개 (<code>id</code> 기준)</td></tr></tbody></table>

#### 카탈로그 데이터 유형 <a href="#catalog-data-types" id="catalog-data-types"></a>

카탈로그는 데이터를 효과적으로 구성하고 체계화하는 데 도움이 되는 다양한 데이터 유형을 지원합니다.

<table><thead><tr><th width="98.30078125">데이터 유형</th><th width="168.7890625">형식</th><th>설명</th><th>예시</th></tr></thead><tbody><tr><td>String</td><td>텍스트</td><td>자유로운 텍스트. 한글·특수문자·공백 허용 (최대 750자)</td><td><code>"Hello World"</code></td></tr><tr><td>Number</td><td>정수 또는 소수</td><td>계산할 수 있는 숫자. 정수·소수·부호 허용 (정수부 20자리 · 소수부 10자리)</td><td><code>42000</code> 또는 <code>19.99</code></td></tr><tr><td>Boolean</td><td><code>true</code> 또는 <code>false</code></td><td>둘 중 하나인 값. true/false(대소문자 무관) 또는 1/0</td><td><code>true</code></td></tr><tr><td>Time</td><td>ISO 8601</td><td>ISO 8601 형식이 지정된 날짜 및 시간 값</td><td><code>"2026-09-15T09:00:00Z"</code></td></tr></tbody></table>

### Step 2. 필드 정의

업로드한 파일에 문제가 없는 경우, \[필드 정의] 단계로 넘어갑니다. 첨부한 CSV의 컬럼이 목록으로 보입니다. 컬럼명 하단의 데이터 예시를 참고하여 각 컬럼의 타입을 선택하세요. 필드 타입은 카탈로그를 만든 뒤에는 바꿀 수 없습니다.

{% hint style="warning" %}
타입과 맞지 않는 값이 있으면 파일을 업로드할 수 없습니다. 반드시 파일의 값과 같은 타입을 선택해 주세요.
{% endhint %}

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FUloAUCzPltYaIDu24JYb%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%201.53.58.png?alt=media&amp;token=d02221b4-0e7c-4e59-9a40-cc0ca27f76fd" alt=""><figcaption></figcaption></figure>

### Step 3. 이름 및 설명

**카탈로그 이름**

* 생성 후 수정할 수 없으며, 영문·숫자·하이픈(-)·밑줄(\_)만 쓸 수 있습니다.
* 이후 메시지에서 이 이름으로 참조합니다. 예. `{% catalog_items products … %}`

## 직접 만들기

구조를 먼저 잡고 아이템은 나중에 넣고 싶을 때 사용합니다. 아이템이 몇 개 안 되는 소규모 카탈로그에 적합합니다.

### Step 1. 카탈로그와 필드 만들기

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2F6voX7kS4G2u2P0NAH0p3%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%201.26.29.png?alt=media&amp;token=22870fae-2e8f-48fb-b7fc-98e515b9c015" alt=""><figcaption></figcaption></figure>

1. **생성하기 > 직접 만들기**를 선택합니다.
2. 카탈로그 이름과 설명을 입력합니다.
3. 필드를 추가합니다. 필드마다 이름과 타입을 정합니다. `id` 필드는 기본으로 포함되어 있습니다.
4. **생성**을 누르면 아이템이 0개인 카탈로그가 만들어집니다.

#### 필드 추가하기

필드는 카탈로그를 만든 뒤에도 **필드 탭**에서 더 추가할 수 있습니다. CSV로 만든 카탈로그도 같습니다.\
단, 한 번 만든 필드는 이름과 타입을 바꿀 수 없고 설명만 고칠 수 있습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FSS165LZpiPQwBZEYzBDE%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%204.29.47.png?alt=media&amp;token=bb6b090d-83f3-46be-8db2-c9b70e2f1224" alt=""><figcaption><p>카탈로그에 필요한 필드를 추가해주세요</p></figcaption></figure>

필드 추가시 반드시 각 필드 값에 맞는 타입을 선택해주세요 (참고 : [카탈로그 데이터 유형](https://app.gitbook.com/o/hce9SZBAnfzHNtKkCvSW/sites/site_g8pQT/s/LHRZjjknm5KdNgPtDsbl/~/edit/~/changes/248/catalog/undefined-1#catalog-data-types))\
타입과 맞지 않는 값을 포함한 아이템은 추가할 수 없습니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FFFy5GTLRIpyCmRduu617%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.25.37.png?alt=media&amp;token=ce211839-c031-4fff-bb5a-5b3dc6121288" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**필드를 편집시 주의하세요**

필드를 추가하면 기존 아이템은 그 필드가 빈 값으로 채워집니다.\
필드를 삭제하면 그 필드를 쓰고 있는 메시지에서 값이 비어서 발송될 수 있습니다.
{% endhint %}

### Step 2. 아이템 추가

아이템은 두 가지 방법으로 넣습니다. 몇 개만 넣거나 고칠 때는 **직접 추가**, 여러 개를 한 번에 다룰 때는 **CSV 업로드**를 사용합니다. 둘 다 **아이템 탭 > 아이템 편집** 버튼에서 시작합니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FwToxLuKOLEI2BIdjTktI%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.26.48.png?alt=media&amp;token=a87e1361-9ae6-45b8-a54d-b26032a9323f" alt=""><figcaption></figcaption></figure>

#### 직접 추가하기

1. **아이템 편집 > 직접 추가하기**를 선택합니다. 오른쪽에 입력 패널이 열립니다.
2. 필드마다 값을 입력합니다. `id`는 필수이며 이미 있는 아이템과 중복될 수 없습니다.
3. **저장하기**를 누르면 목록에 바로 반영됩니다.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2Fs4lJlKR4m8qyQYyLdUOJ%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.27.35.png?alt=media&amp;token=b3020ad1-a2c4-41b2-9155-753b18a3a9ad" alt=""><figcaption></figcaption></figure>

#### CSV 업로드

이미 있는 카탈로그에 CSV를 올리면 필드는 그대로 두고 아이템만 바꿉니다. 파일 요건은 카탈로그를 처음 만들 때와 같습니다 (참고 : [CSV 파일 준비 체크리스트](https://app.gitbook.com/o/hce9SZBAnfzHNtKkCvSW/sites/site_g8pQT/s/LHRZjjknm5KdNgPtDsbl/~/edit/~/changes/248/catalog/undefined-1#csv-checklist))

한 가지 다른 점은 컬럼 이름이 카탈로그에 이미 있는 필드명과 정확히 같아야 한다는 것입니다. 순서는 상관없지만, 카탈로그에 없는 컬럼이 있으면 업로드되지 않습니다. 새 필드가 필요하면 **필드 탭 > 추가하기**로 먼저 필드를 만든 뒤 올리세요.

<figure><img src="https://2738466581-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FLHRZjjknm5KdNgPtDsbl%2Fuploads%2FWSqJgIRBIzr7RzpJF4nJ%2F%E1%84%89%E1%85%B3%E1%84%8F%E1%85%B3%E1%84%85%E1%85%B5%E1%86%AB%E1%84%89%E1%85%A3%E1%86%BA%202026-09-21%20%E1%84%8B%E1%85%A9%E1%84%92%E1%85%AE%205.31.04.png?alt=media&amp;token=53921901-bfb7-462d-bfaa-dc51e7610de3" alt=""><figcaption></figcaption></figure>

1. **아이템 편집 > CSV 업로드**를 선택합니다.
2. **업로드 방식**을 고르고 다음을 누릅니다. CSV의 `id`가 카탈로그에 이미 있는지에 따라 동작이 달라집니다.

| 업로드 방식     | 이런 때 (예시)          | id가 카탈로그에 이미 있으면 | id가 카탈로그에 없으면 |
| ---------- | ------------------ | ---------------- | ------------- |
| 새 아이템만 추가  | 신상품을 붙일 때          | 건너뜀 (기존 값 유지)    | 추가            |
| 기존 아이템만 수정 | 가격·재고를 갱신할 때       | CSV 내용으로 덮어씁     | 건너뜀           |
| 추가하고 수정    | 전체 목록을 최신으로 맞출 때   | CSV 내용으로 덮어씁     | 추가            |
| 아이템 삭제     | 단종·판매 종료 상품을 정리할 때 | 삭제               | 건너뜀           |

3. 파일을 올리고 **업로드**를 누릅니다.


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://docs.hackle.io/catalog/create.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.