Redis ZRANGEBYSCORE 명령어 완벽 가이드 – 점수 범위로 정렬된 집합의 요소 조회하기

이 튜토리얼에서는 Redis에서 특정 점수 범위에 속하는 정렬된 집합(Sorted Set)의 모든 요소를 점수 기준 오름차순으로 조회하는 방법을 알아봅니다. 이를 위해 ZRANGEBYSCORE 명령어를 사용합니다.

ZRANGEBYSCORE 명령어란?

ZRANGEBYSCORE 명령어는 인자로 전달된 min(최솟값) 이상이면서 max(최댓값) 이하인 점수를 가진 정렬된 집합의 모든 요소를 반환합니다. 반환되는 요소들은 점수를 기준으로 오름차순으로 정렬되며, 점수가 동일한 요소들 사이에는 사전순(lexicographical order)으로 정렬됩니다.

기본적으로 min과 max는 닫힌 구간(경계값 포함)으로 처리되지만, 값 앞에 ( 문자를 붙이면 열린 구간(경계값 제외)으로 지정할 수 있습니다.

예를 들어 다음 명령어는:

ZRANGEBYSCORE set (1 5

점수가 1보다 크고 5 이하인(1 < score <= 5) 모든 요소를 반환합니다. 반면 아래 명령어는:

ZRANGEBYSCORE zset (5 (10

점수가 5보다 크고 10보다 작은(5 < score < 10) 모든 요소를 반환하며, 5와 10은 결과에서 제외됩니다.

또한 min과 max 인자에는 각각 -inf(음의 무한대)와 +inf(양의 무한대) 값을 사용할 수 있습니다. 덕분에 정렬된 집합 내 최고 점수나 최저 점수를 미리 알지 못해도, 특정 점수까지 또는 특정 점수부터 시작하는 모든 요소를 손쉽게 조회할 수 있습니다.

선택적 인자(Optional Arguments)

Redis의 ZRANGEBYSCORE 명령어는 다음과 같은 선택적 인자를 지원합니다.

WITHSCORES : 요소와 함께 해당 요소의 점수도 함께 반환합니다. 이 옵션을 사용하면 반환되는 배열이 value1, …, valueN 형태 대신 value1, score1, …, valueN, scoreN 형태로 구성됩니다.
LIMIT offset count : offset 위치부터 시작하여 일치하는 요소 중 count개만 반환합니다. 만약 count 값이 음수라면, offset 위치부터 나머지 모든 요소를 반환합니다.

키가 존재하지 않으면 빈 집합(empty set)이 반환되며, 키는 존재하지만 저장된 값이 정렬된 집합 타입이 아니라면 에러가 반환됩니다.

명령어 문법(Syntax)

redis host:post> ZRANGEBYSCORE <keyname> <min> <max> [WITHSCORES] [LIMIT offset count]

반환값(Output)

- (array) reply : 지정된 범위 내 정렬된 집합의 요소 목록
- 빈 집합(Empty Set) : 키가 존재하지 않는 경우
- 에러(Error) : 키는 존재하지만 저장된 값이 정렬된 집합 타입이 아닌 경우

사용 예제(Example)

실제 Redis CLI 환경에서 ZADD 명령어로 정렬된 집합을 먼저 생성한 뒤, ZRANGEBYSCORE 명령어를 실행하면 지정한 점수 범위에 맞는 요소들이 오름차순으로 출력되는 것을 확인할 수 있습니다. WITHSCORES 옵션을 함께 사용하면 각 요소의 점수도 함께 확인할 수 있으며, LIMIT 옵션을 활용하면 대량의 데이터 중 필요한 만큼만 페이지네이션 방식으로 가져올 수 있습니다.

참고 자료(References)

Redis 공식 문서 – ZRANGEBYSCORE Command Docs

지금까지 Redis 데이터 저장소에 저장된 정렬된 집합에서 특정 점수 범위에 속하는 모든 요소를 점수 기준 오름차순으로 조회하는 ZRANGEBYSCORE 명령어의 사용법을 살펴보았습니다. 이 글이 도움이 되었다면 댓글로 의견을 남겨주시고, 주변에도 널리 공유해 주세요!