From 389e3c397428eb696501a1e314c55d9feb9de1b0 Mon Sep 17 00:00:00 2001 From: "David W. Dougherty" Date: Mon, 30 Sep 2024 12:56:16 -0700 Subject: [PATCH 1/3] DEV: add attribute type to the RESP3 spec. --- content/develop/reference/protocol-spec.md | 49 ++++++++++++++++++++++ 1 file changed, 49 insertions(+) diff --git a/content/develop/reference/protocol-spec.md b/content/develop/reference/protocol-spec.md index f3f7436cf2..49b12826f4 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 `|` byte 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 is used in order to augment the reply. + +For instance newer versions of Redis may include the ability to report, for every executed command, the popularity of keys. 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` was 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 will inform only 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, it just needs to be passed to the caller in a sensible way. + ### Sets From 3f580752c2c8adf21d934ef2d6cad2fd97570999 Mon Sep 17 00:00:00 2001 From: David Dougherty Date: Mon, 30 Sep 2024 13:06:32 -0700 Subject: [PATCH 2/3] Update protocol-spec.md --- content/develop/reference/protocol-spec.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/content/develop/reference/protocol-spec.md b/content/develop/reference/protocol-spec.md index 49b12826f4..898f36d794 100644 --- a/content/develop/reference/protocol-spec.md +++ b/content/develop/reference/protocol-spec.md @@ -537,7 +537,7 @@ The first element is a key, followed by the corresponding value, then the next k The attribute type is exactly like the Map type, but instead of a `%` character as the first byte, the `|` byte 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 is used in order to augment the reply. -For instance newer versions of Redis may include the ability to report, for every executed command, the popularity of keys. The reply to the command `MGET a b` may be the following: +For exampl, 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 From 39a15e249b82f08dde5dbba608aa1dcb0e0f1131 Mon Sep 17 00:00:00 2001 From: David Dougherty Date: Tue, 1 Oct 2024 06:36:43 -0700 Subject: [PATCH 3/3] Apply suggestions from code review Thank you, @andy-stark-redis! Co-authored-by: andy-stark-redis <164213578+andy-stark-redis@users.noreply.github.com> --- content/develop/reference/protocol-spec.md | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/content/develop/reference/protocol-spec.md b/content/develop/reference/protocol-spec.md index 898f36d794..e948cca11a 100644 --- a/content/develop/reference/protocol-spec.md +++ b/content/develop/reference/protocol-spec.md @@ -535,9 +535,9 @@ The first element is a key, followed by the corresponding value, then the next k ### Attributes -The attribute type is exactly like the Map type, but instead of a `%` character as the first byte, the `|` byte 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 is used in order to augment the reply. +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 exampl, 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: +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 @@ -552,7 +552,7 @@ For exampl, newer versions of Redis may include the ability to report the popula :2039123 :9543892 -The actual reply to `MGET` was 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. +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: @@ -567,7 +567,7 @@ When a client reads a reply and encounters an attribute type, it should read the {:key-popularity => {:a => 0.1923, :b => 0.0012}} ``` -Attributes can appear anywhere before a valid part of the protocol identifying a given type, and will inform only the part of the reply that immediately follows. For example: +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 @@ -577,7 +577,7 @@ Attributes can appear anywhere before a valid part of the protocol identifying a :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, it just needs to be passed to the caller in a sensible way. +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.