이 튜토리얼에서는 Redis에 저장된 지리 공간(geospatial) 값 중에서 특정 영역 안에 속한 요소들을 조회하는 방법을 알아봅니다. 이를 위해 Redis의 GEORADIUS 명령어를 사용합니다.
GEORADIUS 명령어란?
GEORADIUS 명령어는 키에 저장된 지리 공간 값(정렬된 집합, Sorted Set) 중에서 지정한 경도, 위도, 반지름으로 계산되는 원형 영역 내부에 있는 하나 이상의 멤버를 반환합니다. 여기서 원의 중심은 지정한 경도와 위도 값이 되고, 원의 반지름은 지정한 단위로 입력한 반지름 값이 됩니다.
반지름은 아래 네 가지 단위 중 하나를 사용해 지정할 수 있습니다.
- m – 미터(meter, 기본값)
- km – 킬로미터(kilometer)
- mi – 마일(mile)
- ft – 피트(feet)
선택적 인자(Options)
Redis GEORADIUS 명령어는 다음과 같은 선택적 인자를 지원합니다.
- WITHDIST : 반환되는 각 요소가 원의 중심으로부터 얼마나 떨어져 있는지 거리를 함께 반환합니다. 거리의 단위는 반지름 인자에 사용한 단위와 동일합니다.
- WITHCOORD : 반환되는 모든 요소의 경도(longitude), 위도(latitude) 좌표를 함께 반환합니다.
- WITHHASH : 반환되는 모든 요소의 원시 Geohash 문자열(52비트 부호 없는 정수)을 함께 반환합니다. 이 Geohash 값은 정렬된 집합에서 해당 요소의 점수(score)입니다.
- ASC : 원의 중심을 기준으로 가장 가까운 요소부터 가장 먼 요소 순으로 정렬하여 반환합니다. 기본적으로는 정렬되지 않은 순서로 반환됩니다.
- DESC : 원의 중심을 기준으로 가장 먼 요소부터 가장 가까운 요소 순으로 정렬하여 반환합니다.
- COUNT <count> : 조건에 맞는 요소 중 처음 count개만큼만 제한하여 반환합니다. 기본값은 일치하는 모든 요소를 반환하는 것입니다.
반환 값
이 명령어는 다음과 같은 형태의 배열(array) 응답을 반환합니다.
- [WITH] 계열의 선택적 인자를 지정하지 않은 경우, 요소 이름만 담긴 배열을 반환합니다.
- WITHCOORD, WITHDIST, WITHHASH 옵션을 지정한 경우, 배열 안에 배열이 포함된 형태로 반환됩니다. 각 하위 배열은 하나의 요소를 나타내며, 첫 번째 항목은 항상 해당 요소의 이름이고 나머지 정보는 다음 순서로 반환됩니다.
- 원의 중심까지의 거리 (부동 소수점 숫자, 반지름에 지정한 단위와 동일)
- Geohash 정수 값
- 좌표 정보 (x, y 두 항목으로 구성된 배열, 즉 경도·위도 순)
키가 존재하지 않으면 Nil이 반환되며, 키는 존재하지만 저장된 값이 GEOADD 명령어로 생성된 정렬된 집합 타입이 아닐 경우에는 오류(error)가 반환됩니다.
문법(Syntax)
redis host:port> GEORADIUS <keyname> <longitude> <latitude> <radius> [UNIT] [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC] [STORE key] [STOREDIST key]
출력(Output)
- (array) reply : 지리 공간 값의 요소들을 담은 배열 - Nil : 키가 존재하지 않는 경우 - Error : 키가 존재하지만 값이 GEOADD로 생성된 정렬된 집합이 아닌 경우
예제(Example)
실전 활용 팁
GEORADIUS는 매장 찾기, 배달 반경 계산, 근처 사용자 검색 등 위치 기반 서비스(LBS)에서 널리 활용됩니다. 대량의 위치 데이터를 다룰 때는 COUNT 옵션과 ASC/DESC 정렬을 함께 사용하면 필요한 결과만 빠르게 가져올 수 있습니다. 참고로 Redis 6.2 버전부터는 GEORADIUS가 deprecated 상태가 되었으며, 확장성이 더 좋은 GEOSEARCH/GEOSEARCHSTORE 명령어 사용이 권장됩니다.
참고 자료(References)
- Redis GEORADIUS 공식 문서
지금까지 Redis 데이터 스토어에 저장된 지리 공간 값 중 특정 영역에 속한 요소들을 조회하는 방법을 알아보았습니다. 도움이 되셨다면 댓글로 의견을 남겨주시고, 주변에도 공유해 주세요!