redis-set-batch
입력 행마다 값 필드의 값을 키 필드의 키에 Redis 접속 프로파일로 저장(SET)합니다.
문법
redis-set-batch profile=STRING key=STRING value=STRING [ex=INT] [keep-ttl=BOOL]
옵션
- profile=STRING
- 필수 옵션. Redis 접속 프로파일 이름. Redis 클라이언트 (Standalone) 또는 Redis 클라이언트 (Sentinel) 타입의 프로파일을 지정합니다. 예: profile=my_redis
- key=STRING
- 필수 옵션. Redis 키가 담긴 입력 필드명. 예: key=user_id
- value=STRING
- 필수 옵션. SET할 값이 담긴 입력 필드명. 예: value=name
- ex=INT
- 선택 옵션. 만료 시간(초). 1 이상의 정수. keep-ttl과 함께 사용할 수 없다.
- keep-ttl=BOOL
- 선택 옵션. 키의 기존 TTL을 유지한다. t로 지정한다. Redis 6.0 이상에서 동작하며 ex와 함께 사용할 수 없다.
입력 필드
| 필드 | 타입 | 필수 | 설명 |
|---|---|---|---|
| key 옵션에 지정한 필드 | 문자열 | Y | Redis 키 |
| value 옵션에 지정한 필드 | 문자열 | Y | 저장할 값. 문자열로 변환되어 저장됨 |
출력 필드
| 필드 | 타입 | 이름 | 설명 |
|---|---|---|---|
| _error | 문자열 | 에러 | 해당 행의 SET 실패 에러 메시지. 성공 시 없음 |
입력 행의 모든 필드가 그대로 전달되며, 실패한 행에만 _error 필드가 추가됩니다.
오류 코드
파싱 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| 사용 가능한 Redis 프로파일이 없습니다. | profile 옵션에 지정한 이름의 프로파일이 없거나 현재 계정에 사용 권한이 없습니다. | 프로파일 이름을 확인하고 해당 프로파일의 사용 권한을 부여합니다. |
| profile 옵션을 지정해야 합니다. | profile 옵션이 없거나 비어 있습니다. | profile=프로파일명 을 지정합니다. |
| key 옵션을 지정해야 합니다. | key 옵션이 없거나 비어 있습니다. | key=필드명 을 지정합니다. |
| value 옵션을 지정해야 합니다. | value 옵션이 없거나 비어 있습니다. | value=필드명 을 지정합니다. |
| ex 옵션은 양의 정수여야 합니다. | ex 값이 정수가 아니거나 0 이하입니다. | 1 이상의 정수를 지정합니다. |
| ex와 keep-ttl은 함께 사용할 수 없습니다. | 두 옵션을 동시에 지정했습니다. | 둘 중 하나만 지정합니다. |
런타임 오류
| 오류 메시지 | 원인 | 해결 |
|---|---|---|
| (출력 행의 _error 필드) | Redis 접속 실패, 인증 실패, 타임아웃, WRONGTYPE 등 행 처리 오류가 발생했습니다. 쿼리는 중단되지 않고 해당 행에 _error 필드가 추가됩니다. 접속에 실패하면 모든 행에 같은 오류가 기록됩니다. | _error 필드의 메시지를 확인하고 접속 정보와 키 타입을 점검합니다. |
| missing 필드명(key) field | key 옵션에 지정한 필드가 입력 행에 없습니다. | 입력 행에 해당 필드가 있는지 확인합니다. |
| missing 필드명(value) field | value 옵션에 지정한 필드가 입력 행에 없습니다. | 입력 행에 해당 필드가 있는지 확인합니다. |
설명
파이프로 들어온 행마다 key 필드의 값을 키로, value 필드의 값을 문자열로 변환해 Redis SET 명령으로 저장합니다. 쿼리 시작 시 접속을 한 번 맺고 모든 행에 재사용합니다. 기존 값은 덮어씁니다.
ex를 지정하면 SET EX로 만료 시간을 설정하고, keep-ttl=t를 지정하면 기존 TTL을 유지합니다. 둘 다 없으면 만료 없이 저장하며 기존 TTL은 제거됩니다. 한 행이 실패해도 쿼리는 계속되고 해당 행에 _error가 기록됩니다.
Note
keep-ttl 옵션은 Redis 6.0 이상에서만 동작합니다.
사용 예
예시: 사용자 이름 캐시 저장
상황: 사용자 ID별 이름을 1시간 동안만 유지되도록 Redis에 저장합니다.
json "{}"
| eval user_id="user01", name="Alice"
| redis-set-batch profile=my_redis key=user_id value=name ex=3600
예상 결과:
| user_id | name |
|---|---|
| user01 | Alice |
결과 해석: _error 필드가 없는 행은 저장에 성공한 것입니다.