Commands & codecs

Call a Redis command as a client method such as client.get, or build a command value such as Commands.get. Use client methods for direct calls. You can store or reuse a command value and include it in a pipeline or transaction.

Commands as values

A Command[Out] describes a server command without running it. Client methods call run internally, so the following forms are equivalent.

Ox

// per-command sugar
val greeting = client.get[String]("greeting")

// the same command, built as a value and run explicitly
val same = client.run(Commands.get[String, String]("greeting"))

ZIO · Cats Effect · Kyo · Pekko

for {
  greeting <- client.get[String]("greeting")
  // the same command, built as a value and run explicitly
  same     <- client.run(Commands.get[String, String]("greeting"))
} yield (greeting, same)

You can store a Command, pass it to a function, and reuse it. You can also include any command value in a pipeline or transaction.

Command families

Commands use the same groups and names as the Redis commands they send:

• Strings (get, set, incr, incrBy, append, …)
• Keys (del, exists, expire, ttl, scan, …)
• Hashes (hSet, hGet, hGetAll, …)
• Lists (lPush, rPush, lRange, blPop, …)
• Sets and Sorted sets (sAdd, sMembers, zAdd, zRange, …)
• HyperLogLog, Bitmaps, Geo, Streams
• Pub/Sub, Scripting, Functions
• Server, Connection, ACL

Every command is available on both the client and Commands. The API docs list every method with its signature.

In a cluster, Sage uses a command's key to choose the correct slot. A command without a key either runs on every master or on a single node. See commands that run on every master.

Typed keys and values

Keys and values are typed. A codec converts each value to and from bytes. The client fixes the key type. The default SageClient uses String keys, so a command call needs only the value type.

client.set("user:1", 42)            // value inferred as Int
val n = client.get[Int]("user:1")   // value Int; the key is the client's String

A read like get returns the value, so its type cannot be inferred and is named explicitly; a write infers the value from its argument and needs no type parameter.

Sage uses two separate typeclasses:

• KeyCodec[A] for key and hash-field positions (identifiers into the keyspace or a hash).
• ValueCodec[A] for payloads.

They are separate because keys need cluster-slot hashing, while values do not.

Non-String keys

Redis keys are binary-safe, so any type with a KeyCodec (Int, Long, raw bytes, your own newtype) is a valid key. Use as[K] to view the client with a different key type. It reuses the same connection:

val binary = client.as[Array[Byte]]
binary.set(idBytes, 42)
val n = binary.get[Int](idBytes)

The client returned by as[K] uses K for keys in commands, pipelines, transactions, subscriptions, and streaming helpers (scanAll, hScanAll, and so on). You can also use it inside a transaction (tx.as[Array[Byte]].get(k)). When building commands for a pipeline, specify both type parameters (Commands.get[K, V]) because Commands does not have a fixed key type.

Built-in codecs

Type	ValueCodec	KeyCodec
String (UTF-8)	yes	yes
Int, Long	yes	yes
Bytes, Array[Byte]	yes	yes
Double, Float	yes	no
Boolean	yes	no

Double, Float, and Boolean are intentionally missing as key codecs: their formatting is representation-sensitive, and two writers must never silently address different keys or fields.

All built-in codecs decode strictly. Bytes outside the type's canonical form cause a DecodeError instead of a conversion. For example, "x" is not a Long, and "2" is not a Boolean.

Writing your own codec

Define a ValueCodec to read and write your own types. Build one from an existing codec with imap for a total, lossless mapping. Use emap when decoding can fail, and return Left for invalid input.

Use imap for a newtype:

final case class UserId(value: Long)

given KeyCodec[UserId] = KeyCodec[Long].imap(UserId(_))(_.value)

Use emap when decoding can fail. Here User encodes as name|age and rejects anything that does not have that format:

final case class User(name: String, age: Int)

object User {
  given ValueCodec[User] =
    ValueCodec[String].emap { raw =>
      raw.lastIndexOf('|') match {
        case -1 => Left(SageException.DecodeError("User(name|age)", raw))
        case i  =>
          raw.drop(i + 1).toIntOption
            .map(User(raw.take(i), _))
            .toRight(SageException.DecodeError("User(name|age)", raw))
      }
    }(user => s"${user.name}|${user.age}")
}

With that given in scope, a User is read and written exactly like a String:

client.set("user:ada", User("Ada", 36))
val ada = client.get[User]("user:ada") // Some(User("Ada", 36))

You can also build a codec from scratch with ValueCodec.from (or KeyCodec.from), supplying an encode function and a decode that returns Either.

Next steps

• Pipelines & transactions compose Command values into one round-trip
• Client-side caching opts individual reads into a local cache