사용자 속성 업로드 (CSV Import)

CSV 파일을 업로드하여 여러 사용자의 속성(커스텀 속성)을 한 번에 생성하거나 업데이트할 수 있습니다.

userId를 기준으로 기존 사용자는 속성이 갱신되고, 존재하지 않는 사용자는 새로 생성(upsert)됩니다. 대량의 사용자 속성을 개별 입력 없이 일괄로 반영할 때 유용합니다. (이벤트 데이터는 대상이 아니며, 사용자 속성만 지원합니다.)

업로드하는 CSV 파일은 다음 포맷을 따라야 합니다.

첫 행은 헤더입니다.
- 헤더의 각 컬럼명이 업데이트할 속성의 key로 사용됩니다.
첫 번째 컬럼은 반드시 userId(식별자)여야 합니다.
- 나머지 컬럼은 모두 사용자 속성 key로 처리됩니다.
userId 외 속성 컬럼을 1개 이상 포함해야 합니다.
컬럼 이름 (속성명)은 중복될 수 없습니다.
- 모든 속성명은 대소문자를 구분합니다.
모든 값은 문자열(String)로 저장됩니다.
- 속성에는 타입 개념이 없어 타입 지정이나 캐스팅이 적용되지 않습니다.
- 날짜를 다루려면 20260708처럼 문자열/숫자 비교가 가능한 형태로 입력하는 것을 권장합니다.
배열·객체 형식은 지원하지 않습니다.
- 값은 항상 단일 문자열이어야 합니다.
모든 속성은 덮어쓰기($set)로 반영됩니다.
- 빈 값은 무시되어 기존 값을 덮어쓰지 않습니다.
인코딩은 UTF-8을 사용하며, RFC 4180 규칙(쉼표·따옴표·줄바꿈 처리)을 따릅니다.

대시보드 내 샘플 템플릿(userId, <key1>, <key2> ...)을 다운로드하여 형식에 맞게 작성할 수 있습니다.

일부 행이 실패하는 경우

전체 업로드는 진행되지만, 아래에 해당하는 개별 행은 반영되지 않고 실패 건수로 집계됩니다.

업로드 전체가 실패하는 경우

다음과 같은 경우에는 파일이 처리되지 않고 요청 전체가 실패합니다. 안내 메시지에 따라 파일을 수정한 뒤 다시 업로드해 주세요.

상황

안내

첫 번째 컬럼이 userId가 아님(빈 파일 포함)

첫 번째 컬럼을 userId로 지정한 뒤 다시 업로드해 주세요.

컬럼 이름이 중복됨

컬럼 이름이 겹치지 않도록 수정한 뒤 다시 업로드해 주세요.

속성 컬럼이 하나도 없음

userId 외 속성 컬럼을 1개 이상 추가해 주세요.

업로드 건수가 100만 건을 초과

최대 100만 건까지 업로드할 수 있어요. 건수를 확인해 주세요.

파일 크기가 100MB를 초과

파일 크기를 100MB 이하로 줄인 뒤 다시 업로드해 주세요.

업로드 후 반영 시점

업로드 완료 시점에는 "대기중"으로만 기록되고, 실제 반영은 10분 주기로 도는 배치가 처리합니다. 따라서 업로드 직후 바로 반영되지 않으며, 대기 시간(최대 10분) + 처리 시간이 걸립니다.

한 번에 최대 100만 건까지 업로드할 수 있습니다.
파일 크기는 최대 100MB까지 지원합니다.
userId 앞뒤 공백이나 줄바꿈은 자동으로 정리(제거)됩니다.
- 예시) " user_123 " 는 "user_123" 로 자동 변경됩니다.

Q) 동시에 여러 CSV 업로드 요청을 하면 순서가 보장되나요?
- A) 보장되지 않습니다. 요청 간 순서가 중요하다면 하나의 요청이 처리완료되면 다음 요청을 하기를 권장드립니다.
Q) 한 CSV 파일 안에서 같은 userId를 갖고 있는 row는 순서가 보장되나요?
- A) 보장되지 않습니다. 순서가 중요하다면 한 파일 안에서 같은 userId를 여러개 넣지 않는 것을 권장드립니다.

마지막 업데이트 13일 전