> 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/en/catalog/create.md).

# Create a Catalog

There are two ways to create a Catalog. **Both produce the same field list**, so choose the method that fits the data you currently have.

<table><thead><tr><th width="125.6640625"></th><th>Start by uploading a CSV</th><th>Create manually</th></tr></thead><tbody><tr><td>When to use</td><td>You already have a CSV file, such as a product list</td><td>You don't have a data file yet<br>and want to design the schema first</td></tr><tr><td>How it works</td><td>Reads the CSV columns to create field candidates, and you specify (map) a type for each column</td><td>You define each field name and type one by one</td></tr><tr><td>Advantage</td><td>You can choose types while looking at actual sample values, so there are fewer mistakes</td><td>Prepare the structure first, even without data</td></tr></tbody></table>

## Start by uploading a CSV

### Step 1. Select a file

1. Click **Create** and select **Start by uploading a CSV**.
2. Drag your CSV file in, or click **Select file** to upload it. You can upload only 1 file at a time.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-b3b026d18c801b3c32a10283c35f0cac2ab90045%2Fscreenshot-2026-09-21-am-11.56.55.png?alt=media" alt=""><figcaption></figcaption></figure>

#### CSV file preparation checklist <a href="#csv-checklist" id="csv-checklist"></a>

Before uploading, make sure your file meets all of the conditions below. If even one is missing, the upload fails or values are uploaded empty.

<table><thead><tr><th width="153.296875">Item</th><th>Requirement</th></tr></thead><tbody><tr><td>Header</td><td>The first row contains the field names. These names become the Catalog's field names as they are.<br>Field names are recommended to use only letters, numbers, <code>-</code>, and <code>_</code>.</td></tr><tr><td><code>id</code> column</td><td>Required. The name must be exactly <code>id</code>, and the column order does not matter.</td></tr><tr><td><code>id</code> value</td><td>No duplicates · up to 300 characters · only letters, numbers, <code>-</code>, and <code>_</code></td></tr><tr><td>Number of columns</td><td>Up to 50</td></tr><tr><td>Value format</td><td>The values in each column must match the type (string, number, boolean, time).<br>Number columns must not contain units or commas, and date columns must be in ISO 8601 format with a time zone offset.</td></tr><tr><td>Undefined values</td><td>Empty cells are allowed.<br>Values such as <code>NULL</code>, <code>null</code>, and <code>-</code> are stored as text, not as empty values, so leave the cell blank instead.</td></tr><tr><td>File format</td><td>CSV, UTF-8 encoding</td></tr><tr><td>File size</td><td>Up to 500MB</td></tr><tr><td>Number of items</td><td>Up to 1 million (based on <code>id</code>)</td></tr></tbody></table>

#### Catalog data types <a href="#catalog-data-types" id="catalog-data-types"></a>

Catalogs support a variety of data types that help you organize and structure your data effectively.

<table><thead><tr><th width="98.30078125">Data type</th><th width="168.7890625">Format</th><th>Description</th><th>Example</th></tr></thead><tbody><tr><td>String</td><td>Text</td><td>Free-form text. Korean characters, special characters, and spaces are allowed (up to 750 characters)</td><td><code>"Hello World"</code></td></tr><tr><td>Number</td><td>Integer or decimal</td><td>A number you can calculate with. Integers, decimals, and signs are allowed (20 digits for the integer part · 10 digits for the decimal part)</td><td><code>42000</code> or <code>19.99</code></td></tr><tr><td>Boolean</td><td><code>true</code> or <code>false</code></td><td>A value that is one of two. true/false (case-insensitive) or 1/0</td><td><code>true</code></td></tr><tr><td>Time</td><td>ISO 8601</td><td>A date and time value in the specified ISO 8601 format</td><td><code>"2026-09-15T09:00:00Z"</code></td></tr></tbody></table>

### Step 2. Define fields

If there is no problem with the uploaded file, you move on to the \[Define fields] step. The columns of the attached CSV are shown as a list. Refer to the data examples below each column name to select a type for each column. A field type cannot be changed after the Catalog is created.

{% hint style="warning" %}
If there are values that do not match the type, the file cannot be uploaded. Be sure to select the same type as the values in the file.
{% endhint %}

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-715caa9b7086ab1b49b384977b3a3f3169c9dc44%2Fscreenshot-2026-09-21-pm-1.53.58.png?alt=media" alt=""><figcaption></figcaption></figure>

### Step 3. Name and description

**Catalog name**

* It cannot be changed after creation, and only letters, numbers, hyphens (-), and underscores (\_) can be used.
* Messages later reference the Catalog by this name. Example: `{% catalog_items products … %}`

## Create manually

Use this when you want to set up the structure first and add items later. It suits small Catalogs with only a few items.

### Step 1. Create the Catalog and fields

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-e71dae03929c23fbe5f6763793b0d591565d55aa%2Fscreenshot-2026-09-21-pm-1.26.29.png?alt=media" alt=""><figcaption></figcaption></figure>

1. Select **Create > Create manually**.
2. Enter the Catalog name and description.
3. Add fields. Specify a name and a type for each field. The `id` field is included by default.
4. Click **Create** to create a Catalog with 0 items.

#### Add fields

You can add more fields in the **Fields tab** even after creating the Catalog. This is the same for Catalogs created from a CSV.\
However, once a field is created, you cannot change its name or type; you can only edit its description.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-c071453e297ee1a991ac0192df437353a9843c6c%2Fscreenshot-2026-09-21-pm-4.29.47.png?alt=media" alt=""><figcaption><p>Add the fields you need for the Catalog</p></figcaption></figure>

When adding a field, be sure to select the type that matches the field's values (see: [Catalog data types](#catalog-data-types))\
Items containing values that do not match the type cannot be added.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-c8f072b30d40b2ce0f94b6c6f6f67502007d4300%2Fscreenshot-2026-09-21-pm-5.25.37.png?alt=media" alt=""><figcaption></figcaption></figure>

{% hint style="warning" %}
**Be careful when editing fields**

When you add a field, existing items are filled with an empty value for that field.\
When you delete a field, messages that use that field may be sent with the value empty.
{% endhint %}

### Step 2. Add items

There are two ways to add items. Use **Add manually** to add or edit a few items, and **CSV upload** to handle many at once. Both start from the **Items tab > Edit items** button.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-84cdfe30cb6a55bd253bcb7930ac94c5f5d0d6bd%2Fscreenshot-2026-09-21-pm-5.26.48.png?alt=media" alt=""><figcaption></figcaption></figure>

#### Add manually

1. Select **Edit items > Add manually**. An input panel opens on the right.
2. Enter a value for each field. `id` is required and cannot duplicate an existing item.
3. Click **Save** and it is reflected in the list right away.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-2cd6fbb51493864f275e3653a33a995db6a98da7%2Fscreenshot-2026-09-21-pm-5.27.35.png?alt=media" alt=""><figcaption></figcaption></figure>

#### CSV upload

When you upload a CSV to an existing Catalog, the fields stay as they are and only the items change. The file requirements are the same as when you first create a Catalog (see: [CSV file preparation checklist](#csv-checklist))

One difference is that the column names must exactly match the field names already in the Catalog. The order does not matter, but if there is a column that is not in the Catalog, the upload fails. If you need a new field, first create it with **Fields tab > Add**, and then upload.

<figure><img src="https://143363954-files.gitbook.io/~/files/v0/b/gitbook-x-prod.appspot.com/o/spaces%2FyAVlNQhS253reum0Ce94%2Fuploads%2Fgit-blob-0991fa8662759a872a8707d768a1cbb55a352a76%2Fscreenshot-2026-09-21-pm-5.31.04.png?alt=media" alt=""><figcaption></figcaption></figure>

1. Select **Edit items > CSV upload**.
2. Choose an **upload method** and click Next. The behavior differs depending on whether the CSV `id` already exists in the Catalog.

| Upload method              | When to use (example)                    | If the id already exists in the Catalog | If the id does not exist in the Catalog |
| -------------------------- | ---------------------------------------- | --------------------------------------- | --------------------------------------- |
| Add new items only         | When adding new products                 | Skipped (existing values kept)          | Added                                   |
| Update existing items only | When updating prices or stock            | Overwritten with the CSV content        | Skipped                                 |
| Add and update             | When syncing the full list to the latest | Overwritten with the CSV content        | Added                                   |
| Delete items               | When cleaning up discontinued products   | Deleted                                 | Skipped                                 |

3. Upload the file and click **Upload**.


---

# 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/en/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.
