Redis ZRANGEBYSCOREコマンドの使い方 – スコア範囲を指定してソート済みセットの要素を昇順に取得する方法

このチュートリアルでは、RedisのZRANGEBYSCOREコマンドを使用して、指定したスコア範囲内にあるソート済みセット(sorted set)のすべての要素を、スコアの昇順で取得する方法について解説します。

ZRANGEBYSCOREコマンドとは

ZRANGEBYSCOREコマンドは、引数として渡されたmin(最小値)以上かつmax(最大値)以下のスコアを持つ、ソート済みセット内のすべての要素を返します。返される要素はスコアの昇順に並べられ、同じスコアを持つ要素同士は辞書順(レキシコグラフィカル順)で昇順に配置されます。

デフォルトではminとmaxは閉区間(境界値を含む)として扱われますが、値の先頭に(を付けることで、開区間(境界値を含まない)として指定することも可能です。例えば、以下のコマンドは

ZRANGEBYSCORE set (1 5

「1 < スコア <= 5」を満たすすべての要素を返します。一方、次のコマンドは

ZRANGEBYSCORE zset (5 (10

「5 < スコア < 10」を満たすすべての要素を返します(5と10は含まれません)。

さらに、minとmaxにはそれぞれ-inf(負の無限大)と+inf(正の無限大)を指定できます。これにより、セット内の最高スコアや最低スコアを事前に把握していなくても、「あるスコアまで」「あるスコア以降」といった条件ですべての要素を柔軟に取得できます。

オプション引数

RedisのZRANGEBYSCOREコマンドでは、次のオプション引数が利用できます。

1. WITHSCORES : 要素と一緒にそのスコアも返します。この場合、戻り値の配列は value1, …, valueN ではなく value1, score1, …, valueN, scoreN の形式になります。
2. LIMIT : offset で指定した位置から count 件の一致する要素を返します。count に負の値を指定すると、offset 以降のすべての要素が返されます。ページネーションのような用途に便利です。

なお、キーが存在しない場合は空のセットが返され、キーは存在するものの格納されている値がソート済みセット型ではない場合はエラーが返されます。

構文

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

出力

- (array) reply : 指定した範囲内のソート済みセットの要素を表す配列
- 空のセット    : キーが存在しない場合
- エラー        : キーは存在するが、格納された値がソート済みセットではない場合

使用例

補足 : より新しい代替コマンド

ZRANGEBYSCOREは長年広く使われてきたコマンドですが、Redis 6.2以降ではZRANGEコマンドにBYSCOREオプションを組み合わせる方法が推奨されています。例えば「ZRANGE key min max BYSCORE」のように記述でき、既存のZRANGEBYSCOREと同等の動作を実現できます。新規開発ではこちらの利用を検討するとよいでしょう。

参考資料

1. ZRANGEBYSCORE 公式ドキュメント(Redis公式サイト)

以上が、Redisデータストアに保存されたソート済みセットから、特定のスコア範囲内の要素をスコアの昇順ですべて取得する方法の解説でした。この記事がお役に立ちましたら、コメント欄でぜひご意見をお聞かせください。また、周りの方へのシェアも歓迎します。