diff --git a/content/develop/reference/protocol-spec.md b/content/develop/reference/protocol-spec.md index f3f7436cf2..e948cca11a 100644 --- a/content/develop/reference/protocol-spec.md +++ b/content/develop/reference/protocol-spec.md @@ -131,6 +131,7 @@ The following table summarizes the RESP data types that Redis supports: | [Bulk errors](#bulk-errors) | RESP3 | Aggregate | `!` | | [Verbatim strings](#verbatim-strings) | RESP3 | Aggregate | `=` | | [Maps](#maps) | RESP3 | Aggregate | `%` | +| [Attributes](#attributes) | RESP3 | Aggregate | `|` | | [Sets](#sets) | RESP3 | Aggregate | `~` | | [Pushes](#pushes) | RESP3 | Aggregate | `>` | @@ -530,6 +531,54 @@ The first element is a key, followed by the corresponding value, then the next k `key1, value1, key2, value2, ...`. {{% /alert %}} + + +### Attributes + +The attribute type is exactly like the Map type, but instead of a `%` character as the first byte, the `|` character is used. Attributes describe a dictionary exactly like the Map type. However the client should not consider such a dictionary part of the reply, but as auxiliary data that augments the reply. + +For example, newer versions of Redis may include the ability to report the popularity of keys for every executed command. The reply to the command `MGET a b` may be the following: + + |1 + +key-popularity + %2 + $1 + a + ,0.1923 + $1 + b + ,0.0012 + *2 + :2039123 + :9543892 + +The actual reply to `MGET` is just the two item array `[2039123, 9543892]`. The returned attributes specify the popularity, or frequency of requests, given as floating point numbers ranging from `0.0` to `1.0`, of the keys mentioned in the original command. Note: the actual implementation in Redis may differ. + +When a client reads a reply and encounters an attribute type, it should read the attribute, and continue reading the reply. The attribute reply should be accumulated separately, and the user should have a way to access such attributes. For instance, if we imagine a session in an higher level language, something like this could happen: + +```python +> r = Redis.new +# +> r.mget("a","b") +# +> r +[2039123,9543892] +> r.attribs +{:key-popularity => {:a => 0.1923, :b => 0.0012}} +``` + +Attributes can appear anywhere before a valid part of the protocol identifying a given type, and supply information only about the part of the reply that immediately follows. For example: + + *3 + :1 + :2 + |1 + +ttl + :3600 + :3 + +In the above example the third element of the array has associated auxiliary information of `{ttl:3600}`. Note that it's not up to the client library to interpret the attributes, but it should pass them to the caller in a sensible way. + ### Sets