{"id":27201095,"url":"https://github.com/gregl83/redis-commands","last_synced_at":"2025-04-09T21:55:08.552Z","repository":{"id":30931089,"uuid":"34489072","full_name":"gregl83/redis-commands","owner":"gregl83","description":"Redis Lua Script Commands","archived":false,"fork":false,"pushed_at":"2016-01-13T03:55:55.000Z","size":44,"stargazers_count":19,"open_issues_count":0,"forks_count":2,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-04-09T21:55:03.536Z","etag":null,"topics":["lua","nodejs","redis","redis-command"],"latest_commit_sha":null,"homepage":"","language":"Lua","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/gregl83.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-04-24T00:31:00.000Z","updated_at":"2023-12-06T12:33:06.000Z","dependencies_parsed_at":"2022-09-20T22:11:47.625Z","dependency_job_id":null,"html_url":"https://github.com/gregl83/redis-commands","commit_stats":null,"previous_names":[],"tags_count":7,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregl83%2Fredis-commands","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregl83%2Fredis-commands/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregl83%2Fredis-commands/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/gregl83%2Fredis-commands/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/gregl83","download_url":"https://codeload.github.com/gregl83/redis-commands/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248119394,"owners_count":21050754,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["lua","nodejs","redis","redis-command"],"created_at":"2025-04-09T21:55:07.939Z","updated_at":"2025-04-09T21:55:08.537Z","avatar_url":"https://github.com/gregl83.png","language":"Lua","funding_links":[],"categories":["Lua"],"sub_categories":[],"readme":"# redis-commands\n\nRedis provides a lot of functionality for data types \"out of the box.\" Additional functions can be written via Lua scripts for cases where there isn't \na \"vanilla\" function that fits. Redis also uses the Lua interpreter to execute it's native commands. Scripts are executed atomically (blocking).\n\nFor more information on executing Lua scripts with Redis see the [Eval Command Documentation](http://redis.io/commands/eval).\n\nPerformance is an important consideration when designing software around a data store. Redis has been built as a high performance data store. When\nintroducing any IO calls into software it's very important to understand the cost of that functionality. Redis documentation includes a *Time complexity* \nfactor for each native command so an evaluation can be performed when deciding which commands and data type should be used to solve a problem. Introducing \ncustom functionality or commands should be done so with an equal understanding of their cost. Redis Lua scripts are atomically executed so other commands\ncannot execute until the script has finished executing. Redis provides a benchmark tool *redis-benchmark* that has been used to test all the commands in \nthis package.\n\nFor more information on Redis benchmarks see the [Benchmarks Documentation](http://redis.io/topics/benchmarks).\n\n## Usage\n\nRedis Lua scripts are located in the `./src` directory.\n\nUse them directly or use a language/environment implementation.\n\n### Language/Environment Documentation\n\n- [NodeJS](docs/nodejs.md)\n\n## Commands\n\nRedis Lua scripts provided by this package.\n\n### Priority Lists\n\nCustom Redis data type that is comprised of a keyspace of lists that are ordered by priority. Priority lists (plist) are native Redis Lists with all the \nstandard [List Commands](http://redis.io/commands#list).\n\n#### PLPUSH key plist value [value ...]\n\nInsert all the specified values at the head of the plist stored at key:plist. If key:plist does not exist, it is created as an empty list before performing \nthe push operations. When key:plist holds a value that is not a list, an error is returned.\n\nIt is possible to push multiple elements using a single command call just specifying multiple arguments at the end of the command. Elements are inserted \none after the other to the head of the list, from the leftmost element to the rightmost element. So for instance the command PLPUSH mylist high a b c will result \ninto a list containing c as first element, b as second element and a as third element.\n\n**Time complexity**\n\nO(1)\n\n**Return values**\n\n[Integer reply](http://redis.io/topics/protocol#integer-reply): the length of the list after the push operations.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/plpush.lua)\"\n\"da39a3ee5e6b4b0d3255bfef95601890afd80709\"\nredis\u003e EVALSHA da39a3ee5e6b4b0d3255bfef95601890afd80709 2 mylist high \"hello\"\n(integer) 1\nredis\u003e EVALSHA da39a3ee5e6b4b0d3255bfef95601890afd80709 2 mylist high \"world\"\n(integer) 1\nredis\u003e LRANGE mylist:high 0 -1\n1) \"hello\"\n2) \"world\"\n```\n\n#### PLLEN key plist [plist ...]\n\nReturns the lengths of the plist(s) for each key:plist. If key:plist does not exist, it is interpreted as an empty plist and 0 is returned. An error is returned when the value stored at key:plist is not a list.\n\n**Time complexity**\n\nO(1 * N) where N is the number of priority lists to try by the operation.\n\n**Return values**\n\n[Array reply](http://redis.io/topics/protocol#array-reply): list of plist(s) in the specified order with list length.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/pllen.lua)\"\n\"09ca92a0ded4a33398413bb4a22a3f1ef45c0c89\"\nredis\u003e LPUSH mylist:critical \"hello\"\n(integer) 1\nredis\u003e LPUSH mylist:low \"world\"\n(integer) 1\nredis\u003e EVALSHA 09ca92a0ded4a33398413bb4a22a3f1ef45c0c89 5 mylist critical high medium low\n1) \"critical\"\n2) (integer) 1\n3) \"high\"\n4) (integer) 0\n5) \"medium\"\n6) (integer) 0\n7) \"low\"\n8) (integer) 1\n```\n\n#### PLREMLPUSH source destination plist count value\n\nRemoves the first count occurrences of elements equal to value from the plist stored at source:plist and pushes the elements at the head of the plist stored \nat destination:plist.\n\nThe count argument influences the operation in the following ways:\n\n- count \u003e 0: Remove elements equal to value moving from head to tail.\n- count \u003c 0: Remove elements equal to value moving from tail to head.\n- count = 0: Remove all elements equal to value.\n\nFor example, PLREMLPUSH source destination medium -2 \"hello\" will remove the last two occurrences of \"hello\" in the plist stored at source:plist and push them at the head of plist at \ndestination:plist.\n\nNote that non-existing keys are treated like empty plists, so when key does not exist, the command will always return 0.\n\n**Time complexity**\n\nO(N) where N is the length of the list.\n\n**Return values**\n\n[Integer reply](http://redis.io/topics/protocol#integer-reply): the number of removed elements.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/plremlpush.lua)\"\n\"58076efaa93d06bd0d68688c9bab745696d5cb18\"\nredis\u003e LPUSH source:critical \"string\"\n(integer) 1\nredis\u003e LPUSH source:medium \"string\"\n(integer) 1\nredis\u003e LPUSH source:critical \"string\"\n(integer) 2\nredis\u003e EVALSHA 58076efaa93d06bd0d68688c9bab745696d5cb18 3 source destination critical 0 \"string\"\n(integer) 2\nredis\u003e LLEN source:critical\n(integer) 0\nredis\u003e LLEN destination:critical\n(integer) 2\n```\n\n#### PRPOPLPUSH source destination plist [plist ...]\n\nAtomically returns and removes the last element (tail) of the priority list (plist) stored at source:plist, and pushes the element at the first element (head) of the plist stored at \ndestination:plist.\n\nFor example: consider source holding the plist critical a,b,c, and destination holding the list critical x,y,z. Executing PRPOPLPUSH results in source:critical holding a,b and \ndestination:critical holding c,x,y,z.\n\nIf source does not exist, the value nil is returned and no operation is performed. If source and destination are the same, the operation is equivalent to removing the last element from the \nlist and pushing it as first element of the list, so it can be considered as a list rotation command.\n\nMost use cases will provide multiple plists in which case executing PRPOPLPUSH will attempt the operation on each plist in order until success.\n\n**Time complexity**\n\nO(1 * N) where N is the number of priority lists to try by the operation.\n\n**Return values**\n\n[Bulk string reply](http://redis.io/topics/protocol#bulk-string-reply): the element being popped and pushed.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/prpoplpush.lua)\"\n\"958b2c29c81d76dc6d5978e5255a16a9782e6a76\"\n\u003e redis-cli\nredis\u003e LPUSH source:high \"one\"\n(integer) 1\nredis\u003e LPUSH source:medium \"two\"\n(integer) 1\nredis\u003e LLEN source:high\n(integer) 1\nredis\u003e LLEN source:medium\n(integer) 1\nredis\u003e LLEN destination:high\n(integer) 0\nredis\u003e LLEN destination:medium\n(integer) 0\nredis\u003e EVALSHA 958b2c29c81d76dc6d5978e5255a16a9782e6a76 6 source destination critical high medium low\n\"one\"\nredis\u003e EVALSHA 958b2c29c81d76dc6d5978e5255a16a9782e6a76 6 source destination critical high medium low\n\"two\"\nredis\u003e LLEN source:high\n(integer) 0\nredis\u003e LLEN source:medium\n(integer) 0\nredis\u003e LLEN destination:high\n(integer) 1\nredis\u003e LLEN destination:medium\n(integer) 1\n```\n\n### Hashes\n\nNative Redis data type. [Hash Commands](http://redis.io/commands#hash).\n\n#### HGETRAND key\n\nReturns a random value in the hash stored at key.\n\n**Time complexity**\n\nO(N) where N is the size of the hash.\n\n**Return value**\n\n[Bulk string reply](http://redis.io/topics/protocol#bulk-string-reply): the random value, or nil when key does not exist.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/hgetrand.lua)\"\n\"0565bb477f320b323aaea486befebd3f9a079176\"\n\u003e redis-cli\nredis\u003e HMSET myhash one \"alpha\" two \"beta\" three \"charlie\"\nOK\nredis\u003e EVALSHA 0565bb477f320b323aaea486befebd3f9a079176 1 myhash\n\"beta\"\n```\n\n#### HMGETRAND key count\n\nReturns a list of random values in the hash stored at key.\n\nList size equals count or hash length when count is greater than hash length.\n\n**Return value**\n\n[Array reply](http://redis.io/topics/protocol#array-reply): list of random values.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/hmgetrand.lua)\"\n\"e8ac5ad65be171300c60f830dc6c974d524129bc\"\n\u003e redis-cli\nredis\u003e HMSET myhash one \"alpha\" two \"beta\" three \"charlie\"\nOK\nredis\u003e EVALSHA e8ac5ad65be171300c60f830dc6c974d524129bc 1 myhash 3\n1) \"charlie\"\n2) \"beta\"\n3) \"alpha\"\n```\n\n### Sorted Sets\n\nNative Redis data type. [Sorted Set Commands](http://redis.io/commands#sorted_set).\n\n#### ZRANGEINCRBY key start stop increment [WITHSCORES]\n\nReturns the specified range of elements in the sorted set stored at key after incrementing the score. The elements are considered to be ordered from the lowest to the highest score. Lexicographical order is used for elements with equal score.\n\nBoth start and stop are zero-based indexes, where 0 is the first element, 1 is the next element and so on. They can also be negative numbers indicating offsets from the end of the sorted set, with -1 being the last element of the sorted set, -2 the penultimate element and so on.\n\nstart and stop are inclusive ranges, so for example `ZRANGEINCRBY myzset 0 1 4` will return both the first and the second element of the sorted set after incrementing their scores by four.\n\nOut of range indexes will not produce an error. If start is larger than the largest index in the sorted set, or start \u003e stop, an empty list is returned. If stop is larger than the end of the sorted set Redis will treat it like it is the last element of the sorted set.\n\nIt is possible to pass the WITHSCORES option in order to return the new scores of the elements together with the elements. The returned list will contain value1,score1,...,valueN,scoreN instead of value1,...,valueN. Client libraries are free to return a more appropriate data type (suggestion: an array with (value, score) arrays/tuples).\n\n**Time complexity**\n\nO(log(N)+M) with N being the number of elements in the sorted set and M the number of elements returned.\n\n**Return value**\n\n[Array reply](http://redis.io/topics/protocol#array-reply): list of elements in the specified range (optionally with their scores, in case the WITHSCORES option is given).\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/zrangeincrby.lua)\"\n\"009e91e9caab43c31bcc48843ca05d8bb951eb7d\"\n\u003e redis-cli\nredis\u003e ZADD myzset 1 \"one\"\n(integer) 1\nredis\u003e ZADD myzset 2 \"two\"\n(integer) 1\nredis\u003e ZRANGE myzset 0 1 WITHSCORES\n1) \"one\"\n2) \"1\"\n3) \"two\"\n4) \"2\"\nredis\u003e EVALSHA 009e91e9caab43c31bcc48843ca05d8bb951eb7d 1 myzset 0 0 1 WITHSCORES\n1) \"one\"\n2) \"2\"\nredis\u003e ZRANGE myzset 0 1 WITHSCORES\n1) \"one\"\n2) \"2\"\n3) \"two\"\n4) \"2\"\n```\n\n#### ZLPOPRPUSH source destination\n\nAtomically returns and removes the first element (head) of the sorted set stored at source, and pushes the element at the last element (tail) of the sorted set stored \nat destination. Sorted Set rules still apply.\n\nFor example: consider source holding the sorted set a 1, b 2, c 3, and destination holding the sorted set x 4, y 5, z 6. Executing ZLPOPRPUSH results in source holding b 2, c 3 and destination \nholding a 1, x 4, y 5, z 6.\n\nIf source does not exist, the value nil is returned and no operation is performed. If source and destination are the same, the operation is equivalent to \nremoving the first element from the sorted set and pushing it as last element of the sorted set, so it can be considered as a sorted set rotation command.\n\nNote: Testing revealed that when compared to the O(1) RPOPLPUSH List function with 10M member sets requests per second was reduced by 66%\n\n**Return value**\n\n[Array reply](http://redis.io/topics/protocol#array-reply): element popped and pushed with score.\n\n**Examples**\n\n```\n\u003e redis-cli script load \"$(cat /path/to/redis-commands/src/zlpoprpush.lua)\"\n\"a34f28bab1fdcd6ca9effe3ce21f797c4873024f\"\n\u003e redis-cli\nredis\u003e ZADD source 1 \"one\"\n(integer) 1\nredis\u003e ZADD source 2 \"two\"\n(integer) 1\nredis\u003e ZCARD source\n(integer) 2\nredis\u003e ZCARD destination\n(integer) 0\nredis\u003e EVALSHA a34f28bab1fdcd6ca9effe3ce21f797c4873024f 2 source destination\n1) \"one\"\n2) \"1\"\nredis\u003e EVALSHA a34f28bab1fdcd6ca9effe3ce21f797c4873024f 2 source destination\n1) \"two\"\n2) \"2\"\nredis\u003e ZCARD source\n(integer) 0\nredis\u003e ZCARD destination\n(integer) 2\n```\n\n## Command Requests\n\nCannot find the command you need?\n\n[File an Enhancement/Issue](https://github.com/gregl83/redis-commands/issues).\n\n## License\n\nMIT","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregl83%2Fredis-commands","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fgregl83%2Fredis-commands","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fgregl83%2Fredis-commands/lists"}