이 튜토리얼에서는 Redis에 저장된 지리 공간 값(geospatial value) 중에서 특정 영역에 속한 요소들을 조회하는 방법을 알아봅니다. 이를 위해 Redis의 GEORADIUSBYMEMBER 명령어를 사용합니다.
GEORADIUSBYMEMBER 명령어란?
GEORADIUSBYMEMBER 명령어는 키에 저장된 지리 공간 값(정렬된 집합, Sorted Set)의 멤버 중에서, 지정된 멤버의 경도·위도 값을 중심으로 하고 반지름 인자로 계산된 원형 영역 내부에 있는 하나 이상의 멤버를 반환하는 명령어입니다.
쉽게 말해, 지정된 멤버의 경도와 위도를 원의 중심 좌표로 삼고, 지정된 단위의 반지름을 원의 반경으로 하여 해당 범위 안에 포함된 요소들을 찾아줍니다.
반지름 단위
반지름은 다음 네 가지 단위 중 하나로 지정할 수 있습니다.
- m : 미터 (기본값)
- km : 킬로미터
- mi : 마일
- ft : 피트
선택적 인자 (Optional Arguments)
Redis GEORADIUSBYMEMBER 명령어는 다음과 같은 선택적 인자를 지원합니다.
- WITHDIST : 반환되는 각 요소가 원의 중심으로부터 얼마나 떨어져 있는지 그 거리를 함께 반환합니다. 거리의 단위는 radius 인자에 지정한 단위와 동일합니다.
- WITHCOORD : 반환되는 모든 요소의 경도(longitude)와 위도(latitude) 좌표를 함께 반환합니다.
- WITHHASH : 반환되는 모든 요소의 원시 Geohash 문자열(52비트 부호 없는 정수)을 함께 반환합니다. 이 Geohash 값은 정렬된 집합에서 해당 요소의 score입니다.
- ASC : 중심을 기준으로 가장 가까운 요소부터 가장 먼 요소 순으로 정렬하여 반환합니다. 옵션을 지정하지 않으면 기본적으로 정렬되지 않은 순서로 반환됩니다.
- DESC : 중심을 기준으로 가장 먼 요소부터 가장 가까운 요소 순으로 정렬하여 반환합니다.
- COUNT <count> : 일치하는 요소 중 처음 count개만 잘라서 반환합니다. 옵션을 지정하지 않으면 일치하는 모든 요소가 반환됩니다.
반환 값 (Return Values)
이 명령어는 다음과 같은 유형의 배열 응답(array reply)을 반환합니다.
- [WITH] 계열 선택적 인자를 지정하지 않은 경우 : 요소의 이름만 담고 있는 배열을 반환합니다.
- WITHCOORD, WITHDIST, WITHHASH 옵션을 지정한 경우 : 배열 안에 배열이 중첩된 형태로 반환되며, 각 하위 배열은 하나의 요소를 나타냅니다. 하위 배열의 첫 번째 항목은 항상 해당 요소의 이름이며, 나머지 정보는 다음 순서로 추가됩니다.
- 중심으로부터의 거리 — 반지름에 지정된 단위와 동일한 단위의 부동 소수점 숫자
- Geohash 정수
- 좌표 — 경도, 위도 두 항목으로 구성된 x, y 배열
키가 존재하지 않으면 nil이 반환되며, 키는 존재하지만 저장된 값이 GEOADD 명령어로 생성된 정렬된 집합(Sorted Set) 타입이 아닌 경우에는 에러가 반환됩니다.
문법 (Syntax)
redis host:post> GEORADIUSBYMEMBER <keyname> <member> <radius> [UNIT] [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC] [STORE key] [STOREDIST key]
출력 (Output)
- (array) reply : 지리 공간 값의 요소들을 나타내는 배열 - Nil : 키가 존재하지 않는 경우 - Error : 키는 존재하지만 저장된 값이 GEOADD로 생성된 정렬된 집합이 아닌 경우
예제 (Example)
참고 자료 (References)
- Redis GEORADIUSBYMEMBER 공식 문서 (Command Docs)
지금까지 Redis 데이터 스토어에 저장된 지리 공간 값 중에서 특정 영역에 속한 요소를 조회하는 방법을 살펴보았습니다. 이 글이 도움이 되었다면 댓글로 의견을 남겨주시고, 주변에도 널리 공유해 주세요!