Skip to main content
Version: 2.x

Keys

Key commands work on keys regardless of the type of value they hold. This page lists every key command on the Redis service, grouped by purpose, with the option types they take.

Inspecting Keysโ€‹

These commands check whether keys exist and what they hold:

CommandResultDescription
Redis#existsLongCounts how many of the given keys exist
Redis#typeOfRedisTypeReturns the type of the value stored at a key
Redis#randomKeyOption[A]Returns a random key, or None when the database is empty
Redis#touchLongUpdates the last access time of the given keys

Redis#exists counts a key once for every time it is listed, so exists("a", "a") returns 2 when a exists. Redis#typeOf returns a RedisType, which has the cases String, List, Set, SortedSet, Hash and Stream. To check a key and branch on its type:

import zio._
import zio.redis._

def describe(redis: Redis): IO[RedisError, String] =
redis.typeOf("user:1").map {
case RedisType.Hash => "a hash"
case other => s"something else: $other"
}

Redis#randomKey needs a result type like any command that returns a key. To pick any key:

import zio._
import zio.redis._

def anyKey(redis: Redis): IO[RedisError, Option[String]] =
redis.randomKey.returning[String]

Deleting Keysโ€‹

Both commands take one key and any number of extra keys, and return how many were removed:

CommandResultDescription
Redis#delLongRemoves the keys and frees their memory immediately
Redis#unlinkLongRemoves the keys and frees their memory in a background thread

Redis#unlink is the better choice for large values because it does not block the server. To delete several keys:

import zio._
import zio.redis._

def cleanup(redis: Redis): IO[RedisError, Long] =
redis.unlink("cache:a", "cache:b", "cache:c")

Redis#flushall deletes every key in every database. Its sync parameter defaults to false, which sends ASYNC, and true sends SYNC:

import zio._
import zio.redis._

def reset(redis: Redis): IO[RedisError, Unit] =
redis.flushall(sync = true)

Expirationโ€‹

Expiry commands set, read and clear the time to live of a key:

CommandResultDescription
Redis#expireBooleanExpires the key after a Duration, in seconds
Redis#pExpireBooleanExpires the key after a Duration, in milliseconds
Redis#expireAtBooleanExpires the key at an Instant, in seconds
Redis#pExpireAtBooleanExpires the key at an Instant, in milliseconds
Redis#persistBooleanRemoves the expiry from the key
Redis#ttlDurationReturns the remaining time to live, in seconds
Redis#pTtlDurationReturns the remaining time to live, in milliseconds

The setters return false when the key does not exist, and Redis#persist returns false when the key has no expiry. To expire a key in an hour and read what is left:

import zio._
import zio.redis._

def expireInAnHour(redis: Redis): IO[RedisError, Duration] =
for {
_ <- redis.expire("session:1", 1.hour)
remaining <- redis.ttl("session:1")
} yield remaining

To expire a key at a fixed point in time with millisecond precision:

import zio._
import zio.redis._
import java.time.Instant

def expireAtMidnight(redis: Redis, midnight: Instant): IO[RedisError, Boolean] =
redis.pExpireAt("daily:report", midnight)

Renaming and Movingโ€‹

These commands change the name or location of a key:

CommandResultDescription
Redis#renameUnitRenames a key and overwrites the target; fails if the key is missing
Redis#renameNxBooleanRenames a key only when the new name does not exist
Redis#copyBooleanCopies a value to another key, optionally into another database
Redis#moveBooleanMoves a key to another database by index

Redis#copy takes two optional parameters: database: Option[Long] selects the target database, and replace: Option[Replace] overwrites an existing target. Replace is a single case object. To copy a key and overwrite the target:

import zio._
import zio.redis._

def duplicate(redis: Redis): IO[RedisError, Boolean] =
redis.copy("template", "instance", replace = Some(Replace))

Searching and Scanningโ€‹

Redis#keys returns every key that matches a glob-style pattern, while Redis#scan walks the key space in small steps:

CommandResultDescription
Redis#keysChunk[A]Returns all keys matching a pattern
Redis#scan(Long, Chunk[A])Returns the next cursor and one batch of keys

Redis#keys blocks the server while it scans everything, so prefer Redis#scan on large databases. Redis#scan takes a cursor and these optional parameters:

ParameterTypeEffect
patternOption[String]Keeps only keys that match the pattern
countOption[Count]Hints how many keys to return per call
typeOption[RedisType]Keeps only keys that hold the given type

Iteration starts with cursor 0 and ends when the server returns cursor 0. To collect every hash key whose name starts with user::

import zio._
import zio.redis._

def allUsers(redis: Redis): IO[RedisError, Chunk[String]] = {
def loop(cursor: Long, acc: Chunk[String]): IO[RedisError, Chunk[String]] =
redis
.scan(cursor, Some("user:*"), Some(Count(100L)), Some(RedisType.Hash))
.returning[String]
.flatMap { case (next, keys) =>
val all = acc ++ keys
if (next == 0L) ZIO.succeed(all) else loop(next, all)
}

loop(0L, Chunk.empty)
}

Sortingโ€‹

Redis#sort sorts a list, set or sorted set and returns the values. Redis#sortStore runs the same command but stores the result under a key and returns how many values it stored. Both take these parameters:

ParameterTypeEffect
byOption[String]Sorts by the values of external keys that match a pattern
limitOption[Limit]Takes Limit(offset, count) values from the sorted result
orderOrderOrder.Ascending (default) or Order.Descending
getOption[(String, List[String])]Returns the values of external keys instead of the elements
alphaOption[Alpha]Sorts alphabetically instead of numerically

Redis#sortStore takes an extra storeAt: Store after the key, where Store(key) names the target key. To sort a list of names alphabetically and keep the first ten:

import zio._
import zio.redis._

def topNames(redis: Redis): IO[RedisError, Chunk[String]] =
redis
.sort("names", limit = Some(Limit(0L, 10L)), order = Order.Descending, alpha = Some(Alpha))
.returning[String]

To store the sorted result under another key:

import zio._
import zio.redis._

def storeSorted(redis: Redis): IO[RedisError, Long] =
redis.sortStore("scores", Store("scores:sorted"))

Serialization and Migrationโ€‹

Redis#dump and Redis#restore copy a value as an opaque, Redis-specific byte string, and Redis#migrate moves keys to another server:

CommandResultDescription
Redis#dumpChunk[Byte]Returns the serialized value of a key
Redis#restoreUnitCreates a key from a serialized value
Redis#migrateStringTransfers one or more keys to another instance

Redis#restore takes the time to live as a Long in milliseconds, where 0 means no expiry, and these optional parameters:

ParameterTypeEffect
replaceOption[Replace]Overwrites an existing key
absTtlOption[AbsTtl]Treats the time to live as an absolute Unix time in ms
idleTimeOption[IdleTime]Sets the idle time, with IdleTime(seconds)
freqOption[Freq]Sets the access frequency, with Freq(frequency)

To copy a value through a dump and restore it under another key:

import zio._
import zio.redis._

def cloneValue(redis: Redis): IO[RedisError, Unit] =
for {
bytes <- redis.dump("source")
_ <- redis.restore("target", 0L, bytes, replace = Some(Replace))
} yield ()

Redis#migrate takes the remote host, port, key, destinationDb and timeout. Its optional parameters are auth: Option[Auth], copy: Option[Copy] and replace: Option[Replace]. Auth(username, password) carries an optional username. The last parameter, keys: Option[(K, List[K])], has no default and must always be passed. To send one key to another server and keep the local copy:

import zio._
import zio.redis._

def migrateKey(redis: Redis): IO[RedisError, String] =
redis.migrate(
host = "replica.example.com",
port = 6379L,
key = "report",
destinationDb = 0L,
timeout = 5.seconds,
auth = Some(Auth(None, "secret")),
copy = Some(Copy),
keys = None
)

Waiting for Replicasโ€‹

Redis#wait_ blocks until previous writes reach a number of replicas, or until the timeout passes. The method name ends in an underscore because wait is reserved on Object. It returns how many replicas acknowledged the writes. A Duration.Zero timeout blocks forever. To wait for two replicas for at most a second:

import zio._
import zio.redis._

def replicated(redis: Redis): IO[RedisError, Long] =
for {
_ <- redis.set("important", "value")
replicas <- redis.wait_(2L, 1.second)
} yield replicas

ZIO Chat

๐ŸŽ‰ Hey there, ZIO aficionado! ๐ŸŽ‰ Step into the ZIO wonderland with me as your guide. Whether you're a functional fanatic or just dipping your toes into the ZIO ecosystem, I'm here to make your journey smooth. Got ZIO questions? I've got answers! Let's navigate the ZIO universe together and unlock its infinite possibilities!