Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

Binary data and typed command arguments

Redis keys and most data arguments are byte strings. They are not required to be UTF-8. redis-tower-commands uses CommandArg for binary-safe typed inputs wherever Redis treats an argument as opaque data: keys, stored values, fields, members, patterns, script arguments, channels, and module payloads.

use bytes::Bytes;
use redis_tower::commands::{Get, HSet, Set, XAdd};

let string_key = b"user:\xff".as_slice();
let hash_key = b"profile:\xff".as_slice();
let stream_key = b"events:\xff".as_slice();

client
    .execute(Set::new(string_key, vec![0x00, 0xfe, 0xff]))
    .await?;
let value: Option<Bytes> = client.execute(Get::new(string_key)).await?;

client
    .execute(HSet::new(
        hash_key,
        b"embedding".as_slice(),
        vector_bytes,
    ))
    .await?;
client
    .execute(XAdd::new(stream_key).field(b"payload", payload))
    .await?;

Ownership and compatibility

CommandArg owns shared Bytes storage so command values remain Send + 'static and can be cloned for Tower middleware. Conversions behave as follows:

InputStorage behavior
Bytesshares the existing allocation
Vec<u8>takes ownership without copying the payload
Stringtakes ownership without copying the UTF-8 payload
&[u8], byte arrays, &str, &Stringcopies once into owned storage
CommandArgmoves the value; cloning shares storage

Ordinary string calls such as Get::new("key") and Set::new(String::from("k"), "v") remain direct. Generic wrappers that want to accept both text and bytes should use impl Into<CommandArg>. A wrapper intentionally restricted to text can retain impl Into<String> and pass value.into() to a builder. As with the old impl Into<String> API, avoid an unnecessary .into() on a literal at the call site because an impl Trait parameter gives the conversion no unique target; pass the literal directly or use CommandArg::from(...).

The standard inputs accepted through Into<String> remain accepted directly, including Box<str>, char, and &mut str. A downstream newtype that only implemented Into<String> is the direct source-compatibility exception: either convert it to String before calling the builder or implement From<YourType> for CommandArg. This intentional break must not ship in a 0.1.x patch release. It requires redis-tower-commands 0.2.0 and redis-tower 0.2.0, with workspace and downstream dependency requirements updated when that release is prepared.

Stream field names and stream names in XREAD/XREADGROUP results are now Bytes, as are StreamMessage.stream and its field names. The previous String representation used lossy UTF-8 conversion and could not round-trip an input that the builder now accepts. Consumer and group names in stream metadata are also Bytes. Stream IDs remain String because Redis defines their grammar as decimal numbers separated by -.

Semantic inventory

The table is an argument-semantic inventory, not a search for Rust String fields. “Text” means Redis assigns grammar or an encoding to the value; “opaque” means Redis compares, stores, hashes, or routes the exact bytes.

FamilyOpaque inputsDeliberately structured/text inputsTyped status
Stringskeys and stored values, comparison valuesinteger/float increments, expiry numbers, digest syntaxCommandArg throughout
Hasheskeys, field names, field valuesincrements and expiry numbersCommandArg throughout
Lists and non-blocking multi-list commandskeys, elements, pivotsindexes, counts, LEFT/RIGHT and BEFORE/AFTER tokensCommandArg throughout
Setskeys and memberscounts and limitsCommandArg throughout
Sorted setskeys and members; lex bounds contain a binary member after their Redis prefixscores, rank indexes, aggregation and direction tokensall builder byte strings use CommandArg; Redis validates bound grammar
Streamsstream keys, field names/values, group and consumer namesentry IDs/cursors, trim thresholds and option tokensbuilder byte strings use CommandArg; stream keys and field names decode as Bytes
Keys and key lifecyclekeys, rename/copy destinations, patterns, serialized RESTORE payloadTTLs, database numbers, SORT grammaropaque positions use CommandArg throughout
Blocking commandslist/zset keystimeouts and direction tokenskeys use CommandArg throughout
Scancollection keys and glob patternscursors, count, TYPE tokenkeys/patterns use CommandArg; results are Bytes
Scripting and functionsscript bodies, KEYS and ARGV, function payloadsSHA-1 hex digests, function/library names and subcommand grammaropaque positions use CommandArg; cached Script helpers also provide binary argument methods
Pub/Sub commands and sessionschannels, patterns, payloadsPUBSUB subcommandstyped commands and dedicated sessions are binary-safe
Geo and HyperLogLogkeys, members/elementscoordinates, unitsopaque positions use CommandArg throughout
Bitmap, transaction, diagnostics, and server helperskeys, WATCH keys, tracking prefixes and data-bearing argumentsnumeric offsets plus administrative grammaropaque positions use CommandArg; PING/ECHO echo responses are exact Bytes
ACL and cluster administrationACL passwords and simulated command arguments; keys supplied to CLUSTER KEYSLOTACL usernames/rules/categories, node IDs, addresses, command grammar and numeric slotsdeliberate split: opaque data uses CommandArg; operational identifiers remain text-first
Redis 8.8 arrayskeys, values, predicatesindexes and option grammaralready binary-safe
Bloom/Cuckoo, sketches, t-digestkeys and item payloadscapacities, probabilities and numeric observationsopaque positions use CommandArg throughout
JSONkeysJSONPath and serialized JSON syntaxkeys use CommandArg; structured JSON interfaces stay text/serde-oriented
Searchdocument keys, suggestion payloads, tag values and vector blobsindex/schema/query syntax and autocomplete suggestion textopaque inputs and outputs preserve bytes; Redis Search can terminate NUL-containing suggestions and normalize malformed UTF-8
Time serieskeys and label names/valuestimestamps, reducers and retention/configurationopaque inputs and returned keys/labels preserve bytes
Vector setskeys and element names; vector bytesJSON attributes and filter/query expression grammarkeys/elements use CommandArg; returned elements are Bytes

RawCommand::arg remains the universal escape hatch for commands or extension syntax outside the typed surface. It accepts AsRef<[u8]>, can retain a typed response with .query::<T>(), and does not perform lossy conversion.

Response decoding

Responses corresponding to opaque values preserve exact bytes. This includes keys, members, stream names/fields, Search documents/suggestions/payloads/tag values, TimeSeries keys/labels, Vector Set elements, TopK items, and echoed PING/ECHO messages.

Redis-defined textual metadata remains String: scan cursors, stream IDs, SHA-1 digests, JSON text, query plans, server diagnostic reports, ACL usernames and rules, Cluster node descriptions and IDs, addresses, and command/config names. Some of these existing metadata parsers use UTF-8 replacement for a malformed server reply; that behavior cannot affect an opaque value because those positions are classified separately above.

ACL usernames/rules/categories and Cluster node IDs/addresses intentionally remain text-first. Redis exposes them as operational configuration grammar, not application key/value payloads. In contrast, ACL passwords and ACL DRYRUN arguments, and the key accepted by CLUSTER KEYSLOT, preserve exact bytes.

The client serializes Search suggestion strings as exact bulk-string bytes, but Redis Search implements them as text: an embedded NUL is a terminator and malformed UTF-8 can be normalized. Suggestion dictionary keys and payloads remain binary-safe. Suggestion responses preserve the exact bytes returned by the server rather than applying another client-side conversion.

Cluster routing

Typed commands serialize a CommandArg directly into RESP bulk strings. The Cluster key extractor reads those same frame bytes, so slot hashing and hash-tag extraction happen before any decoding and use the exact key bytes. Braces inside invalid UTF-8 keys therefore have the same routing meaning as braces in an ASCII key.