From af1734cafec11cd9bb67afc9f48fa876a66f7465 Mon Sep 17 00:00:00 2001 From: Savannah Date: Tue, 18 Jul 2023 12:48:22 -0400 Subject: [PATCH 1/4] Update lists.md update lists data type page to include short codes for tabbed examples. updated some text to reflect changes. --- docs/data-types/lists.md | 240 ++++++++++++++++++++++----------------- 1 file changed, 135 insertions(+), 105 deletions(-) diff --git a/docs/data-types/lists.md b/docs/data-types/lists.md index a73f676d7a..587547703a 100644 --- a/docs/data-types/lists.md +++ b/docs/data-types/lists.md @@ -35,60 +35,60 @@ See the [complete series of list commands](https://redis.io/commands/?group=list ## Examples * Treat a list like a queue (first in, first out): -``` -> LPUSH work:queue:ids 101 +{{< clients-example list_tutorial queue >}} +> LPUSH bikes:repairs bike:1 (integer) 1 -> LPUSH work:queue:ids 237 +> LPUSH bikes:repairs bike:2 (integer) 2 -> RPOP work:queue:ids -"101" -> RPOP work:queue:ids -"237" -``` +> RPOP bikes:repairs +"bike:1" +> RPOP bikes:repairs +"bike:2" +{{< /clients-example >}} * Treat a list like a stack (first in, last out): -``` -> LPUSH work:queue:ids 101 +{{< clients-example list_tutorial stack >}} +> LPUSH bikes:repairs bike:1 (integer) 1 -> LPUSH work:queue:ids 237 +> LPUSH bikes:repairs bike:2 (integer) 2 -> LPOP work:queue:ids -"237" -> LPOP work:queue:ids -"101" -``` +> LPOP bikes:repairs +"bike:2" +> LPOP bikes:repairs +"bike:1" +{{< /clients-example >}} * Check the length of a list: -``` -> LLEN work:queue:ids +{{< clients-example list_tutorial llen >}} +> LLEN bikes:repairs (integer) 0 -``` +{{< /clients-example >}} * Atomically pop an element from one list and push to another: -``` -> LPUSH board:todo:ids 101 +{{< clients-example list_tutorial lmove_lrange >}} +> LPUSH bikes:repairs bike:1 (integer) 1 -> LPUSH board:todo:ids 273 +> LPUSH bikes:repairs bike:2 (integer) 2 -> LMOVE board:todo:ids board:in-progress:ids LEFT LEFT -"273" -> LRANGE board:todo:ids 0 -1 -1) "101" -> LRANGE board:in-progress:ids 0 -1 -1) "273" -``` - -* To create a capped list that never grows beyond 100 elements, you can call `LTRIM` after each call to `LPUSH`: -``` -> LPUSH notifications:user:1 "You've got mail!" -(integer) 1 -> LTRIM notifications:user:1 0 99 -OK -> LPUSH notifications:user:1 "Your package will be delivered at 12:01 today." -(integer) 2 -> LTRIM notifications:user:1 0 99 -OK -``` +> LMOVE bikes:repairs bikes:finished LEFT LEFT +"bike:2" +> LRANGE bikes:repairs 0 -1 +1) "bike:1" +> LRANGE bikes:finished 0 -1 +1) "bike:2" +{{< /clients-example >}} + +* To limit the length of a list you can call `LTRIM`: +{{< clients-example list_tutorial ltrim >}} + > lpush bikes:repairs:priority bike:1 bike:2 bike:3 bike:4 bike:5 + (integer) 5 + > ltrim bikes:repairs 0 2 + OK + > lrange bikes:repairs 0 -1 + 1) "bike:5" + 2) "bike:4" + 3) "bike:3" +{{< /clients-example >}} ### What are Lists? To explain the List data type it's better to start with a little bit of theory, @@ -130,16 +130,18 @@ left (at the head), while the `RPUSH` command adds a new element into a list, on the right (at the tail). Finally the `LRANGE` command extracts ranges of elements from lists: - > rpush mylist A +{{< clients-example list_tutorial lpush_rpush >}} + > rpush bikes:repairs bike:1 (integer) 1 - > rpush mylist B + > rpush bikes:repairs bike:2 (integer) 2 - > lpush mylist first + > lpush bikes:repairs bike:important_bike (integer) 3 - > lrange mylist 0 -1 - 1) "first" - 2) "A" - 3) "B" + > lrange bikes:repairs 0 -1 + 1) "bike:important_bike" + 2) "bike:1" + 3) "bike:2" +{{< /clients-example >}} Note that `LRANGE` takes two indexes, the first and the last element of the range to return. Both the indexes can be negative, telling Redis @@ -152,40 +154,38 @@ the final `LPUSH` appended the element on the left. Both commands are *variadic commands*, meaning that you are free to push multiple elements into a list in a single call: - > rpush mylist 1 2 3 4 5 "foo bar" - (integer) 9 +{{< clients-example list_tutorial variadic >}} + > rpush bikes:repairs bike:1 bike:2 bike:3 + (integer) 3 + > lpush bikes:repairs bike:important_bike bike:very_important_bike > lrange mylist 0 -1 - 1) "first" - 2) "A" - 3) "B" - 4) "1" - 5) "2" - 6) "3" - 7) "4" - 8) "5" - 9) "foo bar" + 1) "bike:very_important_bike" + 2) "bike:important_bike" + 3) "bike:1" + 4) "bike:2" + 5) "bike:3" +{{< /clients-example >}} An important operation defined on Redis lists is the ability to *pop elements*. Popping elements is the operation of both retrieving the element from the list, and eliminating it from the list, at the same time. You can pop elements from left and right, similarly to how you can push elements in both sides -of the list: - - > rpush mylist a b c - (integer) 3 - > rpop mylist - "c" - > rpop mylist - "b" - > rpop mylist - "a" - -We added three elements and popped three elements, so at the end of this +of the list. We'll add three elements and popp three elements, so at the end of this sequence of commands the list is empty and there are no more elements to -pop. If we try to pop yet another element, this is the result we get: +pop: - > rpop mylist +{{< clients-example list_tutorial lpop_rpop >}} + > rpush bikes:repairs bike:1 bike:2 bike:3 + (integer) 3 + > rpop bikes:repairs + "bike:3" + > lpop bikes:repairs + "bike:1" + > rpop bikes:repairs + "bike:2" + > rpop bikes:repairs (nil) +{{< /clients-example >}} Redis returned a NULL value to signal that there are no elements in the list. @@ -223,26 +223,38 @@ The `LTRIM` command is similar to `LRANGE`, but **instead of displaying the specified range of elements** it sets this range as the new list value. All the elements outside the given range are removed. -An example will make it more clear: +For example, if you're adding bikes on the end of a list of repairs, but only +want to worry about the 3 that have been on the list the longest: - > rpush mylist 1 2 3 4 5 +{{< clients-example list_tutorial ltrim >}} + > rpush bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 (integer) 5 - > ltrim mylist 0 2 + > ltrim bikes:repairs 0 2 OK - > lrange mylist 0 -1 - 1) "1" - 2) "2" - 3) "3" + > lrange bikes:repairs 0 -1 + 1) "bike:1" + 2) "bike:2" + 3) "bike:3" +{{< /clients-example >}} The above `LTRIM` command tells Redis to keep just list elements from index 0 to 2, everything else will be discarded. This allows for a very simple but useful pattern: doing a List push operation + a List trim operation together -in order to add a new element and discard elements exceeding a limit: +in order to add a new element and discard elements exceeding a limit. Using +`LTRIM` with negative indices can then be used to keep only the 3 most recently added: - LPUSH mylist - LTRIM mylist 0 999 +{{< clients-example list_tutorial ltrim_end_of_list >}} + > rpush bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 + (integer) 5 + > ltrim bikes:repairs -3 -1 + OK + > lrange bikes:repairs 0 -1 + 1) "bike:3" + 2) "bike:4" + 3) "bike:5" +{{< /clients-example >}} -The above combination adds a new element and keeps only the 1000 +The above combination adds new elements and keeps only the 3 newest elements into the list. With `LRANGE` you can access the top items without any need to remember very old data. @@ -279,9 +291,19 @@ timeout is reached. This is an example of a `BRPOP` call we could use in the worker: - > brpop tasks 5 - 1) "tasks" - 2) "do_something" +{{< clients-example list_tutorial brpop >}} + > rpush bikes:repairs bike:1 bike:2 + (integer) 5 + > brpop bikes:repairs 1 + 1) "bikes:repairs" + 2) "bike:2" + > brpop bikes:repairs 1 + 1) "bikes:repairs" + 2) "bike:1" + > brpop bikes:repairs 1 + (nil) + (2.01s) +{{< /clients-example >}} It means: "wait for elements in the list `tasks`, but return if after 5 seconds no element is available". @@ -322,45 +344,53 @@ Basically we can summarize the behavior with three rules: Examples of rule 1: - > del mylist +{{< clients-example list_tutorial rule_1 >}} + > del new_bikes (integer) 1 - > lpush mylist 1 2 3 + > lpush new_bikes bike:1 bike:2 bike:3 (integer) 3 +{{< /clients-example >}} However we can't perform operations against the wrong type if the key exists: - > set foo bar +{{< clients-example list_tutorial rule_1.1 >}} + > set new_bikes bike:1 OK - > lpush foo 1 2 3 - (error) WRONGTYPE Operation against a key holding the wrong kind of value - > type foo + > type new_bikes string + > lpush new_bikes bike:2 bike:3 + (error) WRONGTYPE Operation against a key holding the wrong kind of value +{{< /clients-example >}} Example of rule 2: - > lpush mylist 1 2 3 +{{< clients-example list_tutorial rule_2 >}} + > rpush bikes:repairs bike:1 bike:2 bike:3 (integer) 3 - > exists mylist + > exists bikes:repairs (integer) 1 - > lpop mylist - "3" - > lpop mylist - "2" - > lpop mylist - "1" - > exists mylist + > lpop bikes:repairs + "bike:3" + > lpop bikes:repairs + "bike:2" + > lpop bikes:repairs + "bike:1" + > exists bikes:repairs (integer) 0 +{{< /clients-example >}} The key no longer exists after all the elements are popped. Example of rule 3: - > del mylist +{{< clients-example list_tutorial rule_3 >}} + > del bikes:repairs (integer) 0 - > llen mylist + > llen bikes:repairs (integer) 0 - > lpop mylist + > lpop bikes:repairs (nil) +{{< /clients-example >}} ## Limits From e5cf15572abe67cb0db5882e012a56889f7d1f92 Mon Sep 17 00:00:00 2001 From: Savannah Date: Tue, 18 Jul 2023 13:39:50 -0400 Subject: [PATCH 2/4] fix popp -> pop --- docs/data-types/lists.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/data-types/lists.md b/docs/data-types/lists.md index 587547703a..5918d63c67 100644 --- a/docs/data-types/lists.md +++ b/docs/data-types/lists.md @@ -170,7 +170,7 @@ An important operation defined on Redis lists is the ability to *pop elements*. Popping elements is the operation of both retrieving the element from the list, and eliminating it from the list, at the same time. You can pop elements from left and right, similarly to how you can push elements in both sides -of the list. We'll add three elements and popp three elements, so at the end of this +of the list. We'll add three elements and pop three elements, so at the end of this sequence of commands the list is empty and there are no more elements to pop: From a605fed208d5f53d43c4b4445ada587af1ac2de1 Mon Sep 17 00:00:00 2001 From: Savannah Date: Tue, 18 Jul 2023 17:09:10 -0400 Subject: [PATCH 3/4] update dt_list capitalize CLI commands - remove whitespace - fix example being used twice not rendering --- docs/data-types/lists.md | 186 +++++++++++++++++++-------------------- 1 file changed, 93 insertions(+), 93 deletions(-) diff --git a/docs/data-types/lists.md b/docs/data-types/lists.md index 5918d63c67..3597d81f74 100644 --- a/docs/data-types/lists.md +++ b/docs/data-types/lists.md @@ -79,15 +79,15 @@ See the [complete series of list commands](https://redis.io/commands/?group=list {{< /clients-example >}} * To limit the length of a list you can call `LTRIM`: -{{< clients-example list_tutorial ltrim >}} - > lpush bikes:repairs:priority bike:1 bike:2 bike:3 bike:4 bike:5 - (integer) 5 - > ltrim bikes:repairs 0 2 - OK - > lrange bikes:repairs 0 -1 - 1) "bike:5" - 2) "bike:4" - 3) "bike:3" +{{< clients-example list_tutorial ltrim.1 >}} +> RPUSH bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 +(integer) 5 +> LTRIM bikes:repairs 0 2 +OK +> LRANGE bikes:repairs 0 -1 +1) "bike:1" +2) "bike:2" +3) "bike:3" {{< /clients-example >}} ### What are Lists? @@ -131,16 +131,16 @@ element into a list, on the right (at the tail). Finally the `LRANGE` command extracts ranges of elements from lists: {{< clients-example list_tutorial lpush_rpush >}} - > rpush bikes:repairs bike:1 - (integer) 1 - > rpush bikes:repairs bike:2 - (integer) 2 - > lpush bikes:repairs bike:important_bike - (integer) 3 - > lrange bikes:repairs 0 -1 - 1) "bike:important_bike" - 2) "bike:1" - 3) "bike:2" +> RPUSH bikes:repairs bike:1 +(integer) 1 +> RPUSH bikes:repairs bike:2 +(integer) 2 +> LPUSH bikes:repairs bike:important_bike +(integer) 3 +> LRANGE bikes:repairs 0 -1 +1) "bike:important_bike" +2) "bike:1" +3) "bike:2" {{< /clients-example >}} Note that `LRANGE` takes two indexes, the first and the last @@ -155,15 +155,15 @@ Both commands are *variadic commands*, meaning that you are free to push multiple elements into a list in a single call: {{< clients-example list_tutorial variadic >}} - > rpush bikes:repairs bike:1 bike:2 bike:3 - (integer) 3 - > lpush bikes:repairs bike:important_bike bike:very_important_bike - > lrange mylist 0 -1 - 1) "bike:very_important_bike" - 2) "bike:important_bike" - 3) "bike:1" - 4) "bike:2" - 5) "bike:3" +> RPUSH bikes:repairs bike:1 bike:2 bike:3 +(integer) 3 +> LPUSH bikes:repairs bike:important_bike bike:very_important_bike +> LRANGE mylist 0 -1 +1) "bike:very_important_bike" +2) "bike:important_bike" +3) "bike:1" +4) "bike:2" +5) "bike:3" {{< /clients-example >}} An important operation defined on Redis lists is the ability to *pop elements*. @@ -175,16 +175,16 @@ sequence of commands the list is empty and there are no more elements to pop: {{< clients-example list_tutorial lpop_rpop >}} - > rpush bikes:repairs bike:1 bike:2 bike:3 - (integer) 3 - > rpop bikes:repairs - "bike:3" - > lpop bikes:repairs - "bike:1" - > rpop bikes:repairs - "bike:2" - > rpop bikes:repairs - (nil) +> RPUSH bikes:repairs bike:1 bike:2 bike:3 +(integer) 3 +> RPOP bikes:repairs +"bike:3" +> LPOP bikes:repairs +"bike:1" +> RPOP bikes:repairs +"bike:2" +> RPOP bikes:repairs +(nil) {{< /clients-example >}} Redis returned a NULL value to signal that there are no elements in the @@ -227,14 +227,14 @@ For example, if you're adding bikes on the end of a list of repairs, but only want to worry about the 3 that have been on the list the longest: {{< clients-example list_tutorial ltrim >}} - > rpush bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 - (integer) 5 - > ltrim bikes:repairs 0 2 - OK - > lrange bikes:repairs 0 -1 - 1) "bike:1" - 2) "bike:2" - 3) "bike:3" +> RPUSH bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 +(integer) 5 +> LTRIM bikes:repairs 0 2 +OK +> LRANGE bikes:repairs 0 -1 +1) "bike:1" +2) "bike:2" +3) "bike:3" {{< /clients-example >}} The above `LTRIM` command tells Redis to keep just list elements from index @@ -244,14 +244,14 @@ in order to add a new element and discard elements exceeding a limit. Using `LTRIM` with negative indices can then be used to keep only the 3 most recently added: {{< clients-example list_tutorial ltrim_end_of_list >}} - > rpush bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 - (integer) 5 - > ltrim bikes:repairs -3 -1 - OK - > lrange bikes:repairs 0 -1 - 1) "bike:3" - 2) "bike:4" - 3) "bike:5" +> RPUSH bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5 +(integer) 5 +> LTRIM bikes:repairs -3 -1 +OK +> LRANGE bikes:repairs 0 -1 +1) "bike:3" +2) "bike:4" +3) "bike:5" {{< /clients-example >}} The above combination adds new elements and keeps only the 3 @@ -292,17 +292,17 @@ timeout is reached. This is an example of a `BRPOP` call we could use in the worker: {{< clients-example list_tutorial brpop >}} - > rpush bikes:repairs bike:1 bike:2 - (integer) 5 - > brpop bikes:repairs 1 - 1) "bikes:repairs" - 2) "bike:2" - > brpop bikes:repairs 1 - 1) "bikes:repairs" - 2) "bike:1" - > brpop bikes:repairs 1 - (nil) - (2.01s) +> RPUSH bikes:repairs bike:1 bike:2 +(integer) 5 +> BRPOP bikes:repairs 1 +1) "bikes:repairs" +2) "bike:2" +> BRPOP bikes:repairs 1 +1) "bikes:repairs" +2) "bike:1" +> BRPOP bikes:repairs 1 +(nil) +(2.01s) {{< /clients-example >}} It means: "wait for elements in the list `tasks`, but return if after 5 seconds @@ -345,38 +345,38 @@ Basically we can summarize the behavior with three rules: Examples of rule 1: {{< clients-example list_tutorial rule_1 >}} - > del new_bikes - (integer) 1 - > lpush new_bikes bike:1 bike:2 bike:3 - (integer) 3 +> DEL new_bikes +(integer) 1 +> LPUSH new_bikes bike:1 bike:2 bike:3 +(integer) 3 {{< /clients-example >}} However we can't perform operations against the wrong type if the key exists: {{< clients-example list_tutorial rule_1.1 >}} - > set new_bikes bike:1 - OK - > type new_bikes - string - > lpush new_bikes bike:2 bike:3 - (error) WRONGTYPE Operation against a key holding the wrong kind of value +> SET new_bikes bike:1 +OK +> TYPE new_bikes +string +> LPUSH new_bikes bike:2 bike:3 +(error) WRONGTYPE Operation against a key holding the wrong kind of value {{< /clients-example >}} Example of rule 2: {{< clients-example list_tutorial rule_2 >}} - > rpush bikes:repairs bike:1 bike:2 bike:3 - (integer) 3 - > exists bikes:repairs - (integer) 1 - > lpop bikes:repairs - "bike:3" - > lpop bikes:repairs - "bike:2" - > lpop bikes:repairs - "bike:1" - > exists bikes:repairs - (integer) 0 +> RPUSH bikes:repairs bike:1 bike:2 bike:3 +(integer) 3 +> EXISTS bikes:repairs +(integer) 1 +> LPOP bikes:repairs +"bike:3" +> LPOP bikes:repairs +"bike:2" +> LPOP bikes:repairs +"bike:1" +> EXISTS bikes:repairs +(integer) 0 {{< /clients-example >}} The key no longer exists after all the elements are popped. @@ -384,12 +384,12 @@ The key no longer exists after all the elements are popped. Example of rule 3: {{< clients-example list_tutorial rule_3 >}} - > del bikes:repairs - (integer) 0 - > llen bikes:repairs - (integer) 0 - > lpop bikes:repairs - (nil) +> DEL bikes:repairs +(integer) 0 +> LLEN bikes:repairs +(integer) 0 +> LPOP bikes:repairs +(nil) {{< /clients-example >}} From bca8041ba40fdc5858d5040e7c734653ed31a9bd Mon Sep 17 00:00:00 2001 From: Savannah Date: Tue, 25 Jul 2023 14:37:22 -0400 Subject: [PATCH 4/4] indices -> indexes, remove extra words --- docs/data-types/lists.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/data-types/lists.md b/docs/data-types/lists.md index 3597d81f74..a91cd40c40 100644 --- a/docs/data-types/lists.md +++ b/docs/data-types/lists.md @@ -239,9 +239,9 @@ OK The above `LTRIM` command tells Redis to keep just list elements from index 0 to 2, everything else will be discarded. This allows for a very simple but -useful pattern: doing a List push operation + a List trim operation together -in order to add a new element and discard elements exceeding a limit. Using -`LTRIM` with negative indices can then be used to keep only the 3 most recently added: +useful pattern: doing a List push operation + a List trim operation together +to add a new element and discard elements exceeding a limit. Using +`LTRIM` with negative indexes can then be used to keep only the 3 most recently added: {{< clients-example list_tutorial ltrim_end_of_list >}} > RPUSH bikes:repairs bike:1 bike:2 bike:3 bike:4 bike:5