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

# 필드 매핑

> 데이터 가져오기 시 필드 매핑이 작동하는 방식.

export const VimeoEmbed = ({videoId, title = 'Video'}) => <div style={{
  padding: '69.01% 0 0 0',
  position: 'relative',
  margin: '32px 0px'
}}>
    <iframe src={`https://player.vimeo.com/video/${videoId}?autoplay=1&loop=1&autopause=0&background=1&app_id=58479`} frameBorder="0" allow="autoplay; fullscreen; picture-in-picture; clipboard-write" style={{
  position: 'absolute',
  top: 0,
  left: 0,
  width: '100%',
  height: '100%',
  borderRadius: '16px',
  border: '2px solid black'
}} title={title} />
  </div>;

## 필드 매핑 작동 방식

파일을 업로드하면 Twenty가 열을 분석하여 기존 필드와 일치시키려고 시도합니다.

### 자동 매핑

Twenty는 다음을 기준으로 열을 일치시키려고 시도합니다:

* 열 헤더 이름(정확 또는 유사 일치)
* 데이터 유형 감지(날짜, 숫자, 이메일)
* 일반적인 필드 패턴

<Note>**빠른 팁:** 가져오려는 객체에서 몇 행을 내보내세요. 내보낸 파일에는 Twenty가 기대하는 정확한 열 이름이 포함되어, 가져오는 동안 자동 매핑이 원활해집니다.</Note>

### 수동 매핑 옵션

각 열에 대해 다음을 수행할 수 있습니다:

* **필드에 매핑**: 드롭다운에서 일치하는 Twenty 필드를 선택
* **매핑하지 않음**: 해당 열을 완전히 건너뜁니다(데이터가 가져오지 않습니다)

<Note>**가져오기 전에 필드가 존재해야 합니다.** 가져오기는 필드가 아니라 레코드를 생성합니다. 가져오기 전에 **설정 → 데이터 모델**에서 사용자 지정 필드를 생성하세요.</Note>

## 필드 유형 호환성

데이터 모델에서 제공되는 모든 필드 유형이 가져오기를 지원합니다.

`id` 값을 가져와 새 레코드에 특정 ID를 지정하거나 기존 레코드를 업데이트할 수도 있습니다.

<img src="https://mintcdn.com/clara-1b8b12e1/nw6qFuBqeI4qyyh5/images/user-guide/fields/all-field-types.png?fit=max&auto=format&n=nw6qFuBqeI4qyyh5&q=85&s=4368be756f037abf78410c741132b0c6" style={{width:'100%'}} width="535" height="669" data-path="images/user-guide/fields/all-field-types.png" />

## 데이터 형식 요구 사항

<Note>**일부 필드는 특별한 구문이 있습니다.** 가져오기를 준비하기 전에 샘플 파일을 다운로드하여 각 필드 유형에 필요한 구문을 확인하는 것을 권장합니다.</Note>

### 주소 필드

Address는 여러 열로 구성된 중첩 필드입니다. 일부는 비워 둘 수 있습니다.

* **Address / Address 1**: 주소 1행
* **Address / Address 2**: 주소 2행
* **Address / City**: 도시 이름
* **Address / State**: 주 또는 도
* **Address / Country**: 국가 이름
* **Address / Post Code**: 우편번호/ZIP 코드

### 배열 필드

다음 형식을 사용하세요:

```
[\"value1\",\"value2\"]
```

### 부울 필드

`TRUE` 또는 `FALSE`(대문자) - `true`나 `false`는 사용하지 마세요

### 통화 필드

통화는 두 개의 열이 있는 중첩 필드이며, **두 열 모두** 채워야 합니다:

* **Amount / Amount**: 숫자 값(예: `1234.56`)
* **Amount / Currency**: 통화 코드(예: `USD`, `EUR`)

### 날짜 필드

지원되는 형식:

* `YYYY-MM-DD`(권장)
* `MM/DD/YYYY`
* `DD/MM/YYYY`
* ISO 8601 형식

### 도메인 필드

* 중복 생성을 방지하려면 `https://domain.com` 형식 사용을 권장합니다. 이 형식은 메일박스 및 캘린더 동기화로 생성되는 Companies 객체에 사용됩니다.
* `Domain Label`과 `Domain URL`을 모두 채울 수 있습니다. 모범 사례는 라벨에는 `domain.com`, URL에는 `https://domain.com`을 입력하는 것입니다.
* 도메인은 Companies 객체 내에서 고유해야 합니다
* **가져올 파일 내에서도 도메인은 고유해야 합니다**

### 이메일 필드

* 유효한 이메일 형식이어야 합니다
* 이메일은 People 객체 내에서 고유해야 합니다
* **가져올 파일 내에서도 이메일은 고유해야 합니다**
* 추가 이메일의 경우: 기본 이메일은 **Emails / Primary Email**을 사용하고, **Emails / Additional Emails**에는 다음 형식을 사용하세요:

```
[\"jane@twenty.com\",\"jane.doe@twenty.com\"]
```

### ID 필드

가져오기 중 `id`를 지정하는 것은 선택 사항입니다. 제공하지 않으면 Twenty가 ID를 자동으로 생성합니다.

`id` 열을 매핑하는 사용 사례:

* **특정 ID 설정**: 새로 생성될 레코드에 사용할 UUID를 선택
* **기존 레코드 업데이트**: 중복 생성 대신 기존 레코드와 일치시켜 업데이트 이 경우 다른 고유 필드는 매핑하지 않는 것을 권장합니다. 고유 필드를 하나만 매핑하면 가져오기가 더 원활합니다.

<Note>`id`를 제공하는 경우 UUID 형식이어야 합니다(예: `c776ee49-f608-4a77-8cc8-6fe96ae1e43f`).</Note>

### JSON 필드

유효한 JSON 형식을 사용하세요:

```
{\"key\":\"value\",\"key2\":\"value2\"}
```

### 링크 필드

도메인 필드와 유사합니다:

* 라벨과 URL 두 열을 모두 채우세요: **Links / Link URL** 및 **Links / Link Label**
* 전체 URL 형식을 사용하세요: `https://example.com`
* 보조 링크의 경우 **Links / Secondary Links** 열을 사용하고 다음 형식을 사용하세요:

```
[{\"url\":\"https://twenty.com\",\"label\":\"Twenty\"}]
```

### 다중 선택 필드

표시 라벨이 아니라 **API 이름**을 다음 형식으로 사용하세요:

```
[\"VALUE1\",\"VALUE2\"]
```

API 이름을 찾는 위치는 [여기](#finding-api-names-for-select-fields)를 참고하세요.

<Note>새 선택 옵션은 가져오기로 자동 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가해야 합니다.</Note>

<Warning>
  **가져오기는 추가하지 않고 덮어씁니다.**

  레코드에 이미 `VALUE2`와 `VALUE3`가 선택되어 있고 `[\"VALUE1\"]`을 가져오면, 가져온 후 해당 레코드에는 `VALUE1`만 남습니다. 이전 선택 항목은 병합되지 않고 대체됩니다.
</Warning>

### 숫자 필드

* 숫자만 입력
* 소수점은 점을 사용합니다: `1234.56`
* 천 단위 구분 기호 사용 금지

### 전화 필드

전화는 여러 열로 구성된 중첩 필드이며 **반드시 채워야 합니다**

* **Phones / Primary Phone Number**: 전화번호(예: `4159095555`)
* **Phones / Primary Phone Country Code**: 국가 코드(예: `US`)
* **Phones / Primary Phone Calling Code**: 전화 걸기 코드(예: `+1`)

### 평점 필드

API 이름 형식을 사용하세요: `RATING_1`, `RATING_2`, `RATING_3`, `RATING_4`, `RATING_5`

### 관계 필드

전용 문서를 참고하세요: [객체 간 관계 가져오기](/l/ko/user-guide/data-migration/capabilities/import-relations)

### 선택 필드

표시 라벨이 아니라 옵션의 **API 이름**을 사용하세요:

```
VALUE1
```

API 이름을 찾는 위치는 [여기](#finding-api-names-for-select-fields)를 참고하세요.
<Note>새 선택 옵션은 가져오기로 자동 생성되지 않습니다. 가져오기 전에 **설정 → 데이터 모델**에서 추가해야 합니다.</Note>

### 텍스트 필드

* 특별한 형식 지정은 필요하지 않습니다
* 앞뒤 공백은 제거됩니다

## API 이름 찾기

사전 정의된 옵션이 있는 Select, Multi-Select, Array 필드의 경우 표시 레이블이 아니라 반드시 **API 이름**을 사용해야 합니다.

### API 이름을 찾는 방법

1. **설정 → 데이터 모델**로 이동
2. 객체와 필드를 선택하세요
3. **고급 모드**를 활성화하세요(설정 페이지 오른쪽 하단의 토글)
4. 각 옵션의 API 이름을 확인하세요

<VimeoEmbed videoId="1144910809" title="동영상 시연" />