

Redis
=====

  ACL CAT
========

  Lists the ACL categories, or the commands inside a category. 

  [Read more](acl-cat/index)   ACL DELUSER
============

  Deletes ACL users, and terminates their connections. 

  [Read more](acl-deluser/index)   ACL DRYRUN
===========

  Simulates the execution of a command by a user, without executing the command. 

  [Read more](acl-dryrun/index)   ACL GENPASS
============

  Generates a pseudorandom, secure password that can be used to identify ACL users. 

  [Read more](acl-genpass/index)   ACL GETUSER
============

  Lists the ACL rules of a user. 

  [Read more](acl-getuser/index)   ACL LIST
=========

  Dumps the effective rules in ACL file format. 

  [Read more](acl-list/index)   ACL LOAD
=========

  Reloads the rules from the configured ACL file. 

  [Read more](acl-load/index)   ACL LOG
========

  Lists recent security events generated due to ACL rules. 

  [Read more](acl-log/index)   ACL SAVE
=========

  Saves the effective ACL rules in the configured ACL file. 

  [Read more](acl-save/index)   ACL SETUSER
============

  Creates and modifies an ACL user and its rules. 

  [Read more](acl-setuser/index)   ACL USERS
==========

  Lists all ACL users. 

  [Read more](acl-users/index)   ACL WHOAMI
===========

  Returns the authenticated username of the current connection. 

  [Read more](acl-whoami/index)   APPEND
=======

  Appends a string to the value of a key. Creates the key if it doesn't exist. 

  [Read more](append/index)   ASKING
=======

  Signals that a cluster client is following an -ASK redirect. 

  [Read more](asking/index)   AUTH
=====

  Authenticates the connection. 

  [Read more](auth/index)   BF.ADD
=======

  Adds an item to a Bloom Filter 

  [Read more](bf.add/index)   BF.CARD
========

  Returns the cardinality of a Bloom filter 

  [Read more](bf.card/index)   BF.EXISTS
==========

  Checks whether an item exists in a Bloom Filter 

  [Read more](bf.exists/index)   BF.INFO
========

  Returns information about a Bloom Filter 

  [Read more](bf.info/index)   BF.INSERT
==========

  Adds one or more items to a Bloom Filter. A filter will be created if it does not exist 

  [Read more](bf.insert/index)   BF.LOADCHUNK
=============

  Restores a filter previously saved using SCANDUMP 

  [Read more](bf.loadchunk/index)   BF.MADD
========

  Adds one or more items to a Bloom Filter. A filter will be created if it does not exist 

  [Read more](bf.madd/index)   BF.MEXISTS
===========

  Checks whether one or more items exist in a Bloom Filter 

  [Read more](bf.mexists/index)   BF.RESERVE
===========

  Creates a new Bloom Filter 

  [Read more](bf.reserve/index)   BF.SCANDUMP
============

  Begins an incremental save of the bloom filter 

  [Read more](bf.scandump/index)   BGREWRITEAOF
=============

  Asynchronously rewrites the append-only file to disk. 

  [Read more](bgrewriteaof/index)   BGSAVE
=======

  Asynchronously saves the database(s) to disk. 

  [Read more](bgsave/index)   BITCOUNT
=========

  Counts the number of set bits (population counting) in a string. 

  [Read more](bitcount/index)   BITFIELD
=========

  Performs arbitrary bitfield integer operations on strings. 

  [Read more](bitfield/index)   BITFIELD\_RO
=============

  Performs arbitrary read-only bitfield integer operations on strings. 

  [Read more](bitfield_ro/index)   BITOP
======

  Performs bitwise operations on multiple strings, and stores the result. 

  [Read more](bitop/index)   BITPOS
=======

  Finds the first set (1) or clear (0) bit in a string. 

  [Read more](bitpos/index)   BLMOVE
=======

  Pops an element from a list, pushes it to another list and returns it. Blocks until an element is available otherwise. Deletes the list if the last element was moved. 

  [Read more](blmove/index)   BLMPOP
=======

  Pops the first element from one of multiple lists. Blocks until an element is available otherwise. Deletes the list if the last element was popped. 

  [Read more](blmpop/index)   BLPOP
======

  Removes and returns the first element in a list. Blocks until an element is available otherwise. Deletes the list if the last element was popped. 

  [Read more](blpop/index)   BRPOP
======

  Removes and returns the last element in a list. Blocks until an element is available otherwise. Deletes the list if the last element was popped. 

  [Read more](brpop/index)   BRPOPLPUSH
===========

  Pops an element from a list, pushes it to another list and returns it. Block until an element is available otherwise. Deletes the list if the last element was popped. 

  [Read more](brpoplpush/index)   BZMPOP
=======

  Removes and returns a member by score from one or more sorted sets. Blocks until a member is available otherwise. Deletes the sorted set if the last element was popped. 

  [Read more](bzmpop/index)   BZPOPMAX
=========

  Removes and returns the member with the highest score from one or more sorted sets. Blocks until a member available otherwise. Deletes the sorted set if the last element was popped. 

  [Read more](bzpopmax/index)   BZPOPMIN
=========

  Removes and returns the member with the lowest score from one or more sorted sets. Blocks until a member is available otherwise. Deletes the sorted set if the last element was popped. 

  [Read more](bzpopmin/index)   CF.ADD
=======

  Adds an item to a Cuckoo Filter 

  [Read more](cf.add/index)   CF.ADDNX
=========

  Adds an item to a Cuckoo Filter if the item did not exist previously. 

  [Read more](cf.addnx/index)   CF.COUNT
=========

  Return the number of times an item might be in a Cuckoo Filter 

  [Read more](cf.count/index)   CF.DEL
=======

  Deletes an item from a Cuckoo Filter 

  [Read more](cf.del/index)   CF.EXISTS
==========

  Checks whether one or more items exist in a Cuckoo Filter 

  [Read more](cf.exists/index)   CF.INFO
========

  Returns information about a Cuckoo Filter 

  [Read more](cf.info/index)   CF.INSERT
==========

  Adds one or more items to a Cuckoo Filter. A filter will be created if it does not exist 

  [Read more](cf.insert/index)   CF.INSERTNX
============

  Adds one or more items to a Cuckoo Filter if the items did not exist previously. A filter will be created if it does not exist 

  [Read more](cf.insertnx/index)   CF.LOADCHUNK
=============

  Restores a filter previously saved using SCANDUMP 

  [Read more](cf.loadchunk/index)   CF.MEXISTS
===========

  Checks whether one or more items exist in a Cuckoo Filter 

  [Read more](cf.mexists/index)   CF.RESERVE
===========

  Creates a new Cuckoo Filter 

  [Read more](cf.reserve/index)   CF.SCANDUMP
============

  Begins an incremental save of the bloom filter 

  [Read more](cf.scandump/index)   CLIENT CACHING
===============

  Instructs the server whether to track the keys in the next request. 

  [Read more](client-caching/index)   CLIENT GETNAME
===============

  Returns the name of the connection. 

  [Read more](client-getname/index)   CLIENT GETREDIR
================

  Returns the client ID to which the connection's tracking notifications are redirected. 

  [Read more](client-getredir/index)   CLIENT ID
==========

  Returns the unique client ID of the connection. 

  [Read more](client-id/index)   CLIENT INFO
============

  Returns information about the connection. 

  [Read more](client-info/index)   CLIENT KILL
============

  Terminates open connections. 

  [Read more](client-kill/index)   CLIENT LIST
============

  Lists open connections. 

  [Read more](client-list/index)   CLIENT NO-EVICT
================

  Sets the client eviction mode of the connection. 

  [Read more](client-no-evict/index)   CLIENT NO-TOUCH
================

  Controls whether commands sent by the client affect the LRU/LFU of accessed keys. 

  [Read more](client-no-touch/index)   CLIENT PAUSE
=============

  Suspends commands processing. 

  [Read more](client-pause/index)   CLIENT REPLY
=============

  Instructs the server whether to reply to commands. 

  [Read more](client-reply/index)   CLIENT SETINFO
===============

  Sets information specific to the client or connection. 

  [Read more](client-setinfo/index)   CLIENT SETNAME
===============

  Sets the connection name. 

  [Read more](client-setname/index)   CLIENT TRACKING
================

  Controls server-assisted client-side caching for the connection. 

  [Read more](client-tracking/index)   CLIENT TRACKINGINFO
====================

  Returns information about server-assisted client-side caching for the connection. 

  [Read more](client-trackinginfo/index)   CLIENT UNBLOCK
===============

  Unblocks a client blocked by a blocking command from a different connection. 

  [Read more](client-unblock/index)   CLIENT UNPAUSE
===============

  Resumes processing commands from paused clients. 

  [Read more](client-unpause/index)   CLUSTER ADDSLOTS
=================

  Assigns new hash slots to a node. 

  [Read more](cluster-addslots/index)   CLUSTER ADDSLOTSRANGE
======================

  Assigns new hash slot ranges to a node. 

  [Read more](cluster-addslotsrange/index)   CLUSTER BUMPEPOCH
==================

  Advances the cluster config epoch. 

  [Read more](cluster-bumpepoch/index)   CLUSTER COUNT-FAILURE-REPORTS
==============================

  Returns the number of active failure reports active for a node. 

  [Read more](cluster-count-failure-reports/index)   CLUSTER COUNTKEYSINSLOT
========================

  Returns the number of keys in a hash slot. 

  [Read more](cluster-countkeysinslot/index)   CLUSTER DELSLOTS
=================

  Sets hash slots as unbound for a node. 

  [Read more](cluster-delslots/index)   CLUSTER DELSLOTSRANGE
======================

  Sets hash slot ranges as unbound for a node. 

  [Read more](cluster-delslotsrange/index)   CLUSTER FAILOVER
=================

  Forces a replica to perform a manual failover of its master. 

  [Read more](cluster-failover/index)   CLUSTER FLUSHSLOTS
===================

  Deletes all slots information from a node. 

  [Read more](cluster-flushslots/index)   CLUSTER FORGET
===============

  Removes a node from the nodes table. 

  [Read more](cluster-forget/index)   CLUSTER GETKEYSINSLOT
======================

  Returns the key names in a hash slot. 

  [Read more](cluster-getkeysinslot/index)   CLUSTER INFO
=============

  Returns information about the state of a node. 

  [Read more](cluster-info/index)   CLUSTER KEYSLOT
================

  Returns the hash slot for a key. 

  [Read more](cluster-keyslot/index)   CLUSTER LINKS
==============

  Returns a list of all TCP links to and from peer nodes. 

  [Read more](cluster-links/index)   CLUSTER MEET
=============

  Forces a node to handshake with another node. 

  [Read more](cluster-meet/index)   CLUSTER MYID
=============

  Returns the ID of a node. 

  [Read more](cluster-myid/index)   CLUSTER MYSHARDID
==================

  Returns the shard ID of a node. 

  [Read more](cluster-myshardid/index)   CLUSTER NODES
==============

  Returns the cluster configuration for a node. 

  [Read more](cluster-nodes/index)   CLUSTER REPLICAS
=================

  Lists the replica nodes of a master node. 

  [Read more](cluster-replicas/index)   CLUSTER REPLICATE
==================

  Configure a node as replica of a master node. 

  [Read more](cluster-replicate/index)   CLUSTER RESET
==============

  Resets a node. 

  [Read more](cluster-reset/index)   CLUSTER SAVECONFIG
===================

  Forces a node to save the cluster configuration to disk. 

  [Read more](cluster-saveconfig/index)   CLUSTER SET-CONFIG-EPOCH
=========================

  Sets the configuration epoch for a new node. 

  [Read more](cluster-set-config-epoch/index)   CLUSTER SETSLOT
================

  Binds a hash slot to a node. 

  [Read more](cluster-setslot/index)   CLUSTER SHARDS
===============

  Returns the mapping of cluster slots to shards. 

  [Read more](cluster-shards/index)   CLUSTER SLAVES
===============

  Lists the replica nodes of a master node. 

  [Read more](cluster-slaves/index)   CLUSTER SLOTS
==============

  Returns the mapping of cluster slots to nodes. 

  [Read more](cluster-slots/index)   CMS.INCRBY
===========

  Increases the count of one or more items by increment 

  [Read more](cms.incrby/index)   CMS.INFO
=========

  Returns information about a sketch 

  [Read more](cms.info/index)   CMS.INITBYDIM
==============

  Initializes a Count-Min Sketch to dimensions specified by user 

  [Read more](cms.initbydim/index)   CMS.INITBYPROB
===============

  Initializes a Count-Min Sketch to accommodate requested tolerances. 

  [Read more](cms.initbyprob/index)   CMS.MERGE
==========

  Merges several sketches into one sketch 

  [Read more](cms.merge/index)   CMS.QUERY
==========

  Returns the count for one or more items in a sketch 

  [Read more](cms.query/index)   COMMAND
========

  Returns detailed information about all commands. 

  [Read more](command/index)   COMMAND COUNT
==============

  Returns a count of commands. 

  [Read more](command-count/index)   COMMAND DOCS
=============

  Returns documentary information about a command. 

  [Read more](command-docs/index)   COMMAND GETKEYS
================

  Extracts the key names from an arbitrary command. 

  [Read more](command-getkeys/index)   COMMAND GETKEYSANDFLAGS
========================

  Extracts the key names and access flags for an arbitrary command. 

  [Read more](command-getkeysandflags/index)   COMMAND INFO
=============

  Returns information about one, multiple or all commands. 

  [Read more](command-info/index)   COMMAND LIST
=============

  Returns a list of command names. 

  [Read more](command-list/index)   CONFIG GET
===========

  Returns the effective values of configuration parameters. 

  [Read more](config-get/index)   CONFIG RESETSTAT
=================

  Resets the server's statistics. 

  [Read more](config-resetstat/index)   CONFIG REWRITE
===============

  Persists the effective configuration to file. 

  [Read more](config-rewrite/index)   CONFIG SET
===========

  Sets configuration parameters in-flight. 

  [Read more](config-set/index)   COPY
=====

  Copies the value of a key to a new key. 

  [Read more](copy/index)   DBSIZE
=======

  Returns the number of keys in the database. 

  [Read more](dbsize/index)   DECR
=====

  Decrements the integer value of a key by one. Uses 0 as initial value if the key doesn't exist. 

  [Read more](decr/index)   DECRBY
=======

  Decrements a number from the integer value of a key. Uses 0 as initial value if the key doesn't exist. 

  [Read more](decrby/index)   DEL
====

  Deletes one or more keys. 

  [Read more](del/index)   DISCARD
========

  Discards a transaction. 

  [Read more](discard/index)   DUMP
=====

  Returns a serialized representation of the value stored at a key. 

  [Read more](dump/index)   ECHO
=====

  Returns the given string. 

  [Read more](echo/index)   EVAL
=====

  Executes a server-side Lua script. 

  [Read more](eval/index)   EVAL\_RO
=========

  Executes a read-only server-side Lua script. 

  [Read more](eval_ro/index)   EVALSHA
========

  Executes a server-side Lua script by SHA1 digest. 

  [Read more](evalsha/index)   EVALSHA\_RO
============

  Executes a read-only server-side Lua script by SHA1 digest. 

  [Read more](evalsha_ro/index)   EXEC
=====

  Executes all commands in a transaction. 

  [Read more](exec/index)   EXISTS
=======

  Determines whether one or more keys exist. 

  [Read more](exists/index)   EXPIRE
=======

  Sets the expiration time of a key in seconds. 

  [Read more](expire/index)   EXPIREAT
=========

  Sets the expiration time of a key to a Unix timestamp. 

  [Read more](expireat/index)   EXPIRETIME
===========

  Returns the expiration time of a key as a Unix timestamp. 

  [Read more](expiretime/index)   FAILOVER
=========

  Starts a coordinated failover from a server to one of its replicas. 

  [Read more](failover/index)   FCALL
======

  Invokes a function. 

  [Read more](fcall/index)   FCALL\_RO
==========

  Invokes a read-only function. 

  [Read more](fcall_ro/index)   FLUSHALL
=========

  Removes all keys from all databases. 

  [Read more](flushall/index)   FLUSHDB
========

  Remove all keys from the current database. 

  [Read more](flushdb/index)   FT.\_LIST
==========

  Returns a list of all existing indexes 

  [Read more](ft._list/index)   FT.AGGREGATE
=============

  Run a search query on an index and perform aggregate transformations on the results 

  [Read more](ft.aggregate/index)   FT.ALIASADD
============

  Adds an alias to the index 

  [Read more](ft.aliasadd/index)   FT.ALIASDEL
============

  Deletes an alias from the index 

  [Read more](ft.aliasdel/index)   FT.ALIASUPDATE
===============

  Adds or updates an alias to the index 

  [Read more](ft.aliasupdate/index)   FT.ALTER
=========

  Adds a new field to the index 

  [Read more](ft.alter/index)   FT.CONFIG GET
==============

  Retrieves runtime configuration options 

  [Read more](ft.config-get/index)   FT.CONFIG SET
==============

  Sets runtime configuration options 

  [Read more](ft.config-set/index)   FT.CREATE
==========

  Creates an index with the given spec 

  [Read more](ft.create/index)   FT.CURSOR DEL
==============

  Deletes a cursor 

  [Read more](ft.cursor-del/index)   FT.CURSOR READ
===============

  Reads from a cursor 

  [Read more](ft.cursor-read/index)   FT.DICTADD
===========

  Adds terms to a dictionary 

  [Read more](ft.dictadd/index)   FT.DICTDEL
===========

  Deletes terms from a dictionary 

  [Read more](ft.dictdel/index)   FT.DICTDUMP
============

  Dumps all terms in the given dictionary 

  [Read more](ft.dictdump/index)   FT.DROPINDEX
=============

  Deletes the index 

  [Read more](ft.dropindex/index)   FT.EXPLAIN
===========

  Returns the execution plan for a complex query 

  [Read more](ft.explain/index)   FT.EXPLAINCLI
==============

  Returns the execution plan for a complex query 

  [Read more](ft.explaincli/index)   FT.INFO
========

  Returns information and statistics on the index 

  [Read more](ft.info/index)   FT.PROFILE
===========

  Performs a `FT.SEARCH` or `FT.AGGREGATE` command and collects performance information 

  [Read more](ft.profile/index)   FT.SEARCH
==========

  Searches the index with a textual query, returning either documents or just ids 

  [Read more](ft.search/index)   FT.SPELLCHECK
==============

  Performs spelling correction on a query, returning suggestions for misspelled terms 

  [Read more](ft.spellcheck/index)   FT.SUGADD
==========

  Adds a suggestion string to an auto-complete suggestion dictionary 

  [Read more](ft.sugadd/index)   FT.SUGDEL
==========

  Deletes a string from a suggestion index 

  [Read more](ft.sugdel/index)   FT.SUGGET
==========

  Gets completion suggestions for a prefix 

  [Read more](ft.sugget/index)   FT.SUGLEN
==========

  Gets the size of an auto-complete suggestion dictionary 

  [Read more](ft.suglen/index)   FT.SYNDUMP
===========

  Dumps the contents of a synonym group 

  [Read more](ft.syndump/index)   FT.SYNUPDATE
=============

  Creates or updates a synonym group with additional terms 

  [Read more](ft.synupdate/index)   FT.TAGVALS
===========

  Returns the distinct tags indexed in a Tag field 

  [Read more](ft.tagvals/index)   FUNCTION DELETE
================

  Deletes a library and its functions. 

  [Read more](function-delete/index)   FUNCTION DUMP
==============

  Dumps all libraries into a serialized binary payload. 

  [Read more](function-dump/index)   FUNCTION FLUSH
===============

  Deletes all libraries and functions. 

  [Read more](function-flush/index)   FUNCTION KILL
==============

  Terminates a function during execution. 

  [Read more](function-kill/index)   FUNCTION LIST
==============

  Returns information about all libraries. 

  [Read more](function-list/index)   FUNCTION LOAD
==============

  Creates a library. 

  [Read more](function-load/index)   FUNCTION RESTORE
=================

  Restores all libraries from a payload. 

  [Read more](function-restore/index)   FUNCTION STATS
===============

  Returns information about a function during execution. 

  [Read more](function-stats/index)   GEOADD
=======

  Adds one or more members to a geospatial index. The key is created if it doesn't exist. 

  [Read more](geoadd/index)   GEODIST
========

  Returns the distance between two members of a geospatial index. 

  [Read more](geodist/index)   GEOHASH
========

  Returns members from a geospatial index as geohash strings. 

  [Read more](geohash/index)   GEOPOS
=======

  Returns the longitude and latitude of members from a geospatial index. 

  [Read more](geopos/index)   GEORADIUS
==========

  Queries a geospatial index for members within a distance from a coordinate, optionally stores the result. 

  [Read more](georadius/index)   GEORADIUS\_RO
==============

  Returns members from a geospatial index that are within a distance from a coordinate. 

  [Read more](georadius_ro/index)   GEORADIUSBYMEMBER
==================

  Queries a geospatial index for members within a distance from a member, optionally stores the result. 

  [Read more](georadiusbymember/index)   GEORADIUSBYMEMBER\_RO
======================

  Returns members from a geospatial index that are within a distance from a member. 

  [Read more](georadiusbymember_ro/index)   GEOSEARCH
==========

  Queries a geospatial index for members inside an area of a box or a circle. 

  [Read more](geosearch/index)   GEOSEARCHSTORE
===============

  Queries a geospatial index for members inside an area of a box or a circle, optionally stores the result. 

  [Read more](geosearchstore/index)   GET
====

  Returns the string value of a key. 

  [Read more](get/index)   GETBIT
=======

  Returns a bit value by offset. 

  [Read more](getbit/index)   GETDEL
=======

  Returns the string value of a key after deleting the key. 

  [Read more](getdel/index)   GETEX
======

  Returns the string value of a key after setting its expiration time. 

  [Read more](getex/index)   GETRANGE
=========

  Returns a substring of the string stored at a key. 

  [Read more](getrange/index)   GETSET
=======

  Returns the previous string value of a key after setting it to a new value. 

  [Read more](getset/index)   GRAPH.CONFIG GET
=================

  Retrieves a RedisGraph configuration 

  [Read more](graph.config-get/index)   GRAPH.CONFIG SET
=================

  Updates a RedisGraph configuration 

  [Read more](graph.config-set/index)   GRAPH.CONSTRAINT CREATE
========================

  Creates a constraint on specified graph 

  [Read more](graph.constraint-create/index)   GRAPH.CONSTRAINT DROP
======================

  Deletes a constraint from specified graph 

  [Read more](graph.constraint-drop/index)   GRAPH.DELETE
=============

  Completely removes the graph and all of its entities 

  [Read more](graph.delete/index)   GRAPH.EXPLAIN
==============

  Returns a query execution plan without running the query 

  [Read more](graph.explain/index)   GRAPH.LIST
===========

  Lists all graph keys in the keyspace 

  [Read more](graph.list/index)   GRAPH.PROFILE
==============

  Executes a query and returns an execution plan augmented with metrics for each operation's execution 

  [Read more](graph.profile/index)   GRAPH.QUERY
============

  Executes the given query against a specified graph 

  [Read more](graph.query/index)   GRAPH.RO\_QUERY
================

  Executes a given read only query against a specified graph 

  [Read more](graph.ro_query/index)   GRAPH.SLOWLOG
==============

  Returns a list containing up to 10 of the slowest queries issued against the given graph 

  [Read more](graph.slowlog/index)   HDEL
=====

  Deletes one or more fields and their values from a hash. Deletes the hash if no fields remain. 

  [Read more](hdel/index)   HELLO
======

  Handshakes with the Redis server. 

  [Read more](hello/index)   HEXISTS
========

  Determines whether a field exists in a hash. 

  [Read more](hexists/index)   HGET
=====

  Returns the value of a field in a hash. 

  [Read more](hget/index)   HGETALL
========

  Returns all fields and values in a hash. 

  [Read more](hgetall/index)   HINCRBY
========

  Increments the integer value of a field in a hash by a number. Uses 0 as initial value if the field doesn't exist. 

  [Read more](hincrby/index)   HINCRBYFLOAT
=============

  Increments the floating point value of a field by a number. Uses 0 as initial value if the field doesn't exist. 

  [Read more](hincrbyfloat/index)   HKEYS
======

  Returns all fields in a hash. 

  [Read more](hkeys/index)   HLEN
=====

  Returns the number of fields in a hash. 

  [Read more](hlen/index)   HMGET
======

  Returns the values of all fields in a hash. 

  [Read more](hmget/index)   HMSET
======

  Sets the values of multiple fields. 

  [Read more](hmset/index)   HRANDFIELD
===========

  Returns one or more random fields from a hash. 

  [Read more](hrandfield/index)   HSCAN
======

  Iterates over fields and values of a hash. 

  [Read more](hscan/index)   HSET
=====

  Creates or modifies the value of a field in a hash. 

  [Read more](hset/index)   HSETNX
=======

  Sets the value of a field in a hash only when the field doesn't exist. 

  [Read more](hsetnx/index)   HSTRLEN
========

  Returns the length of the value of a field. 

  [Read more](hstrlen/index)   HVALS
======

  Returns all values in a hash. 

  [Read more](hvals/index)   INCR
=====

  Increments the integer value of a key by one. Uses 0 as initial value if the key doesn't exist. 

  [Read more](incr/index)   INCRBY
=======

  Increments the integer value of a key by a number. Uses 0 as initial value if the key doesn't exist. 

  [Read more](incrby/index)   INCRBYFLOAT
============

  Increment the floating point value of a key by a number. Uses 0 as initial value if the key doesn't exist. 

  [Read more](incrbyfloat/index)   INFO
=====

  Returns information and statistics about the server. 

  [Read more](info/index)   JSON.ARRAPPEND
===============

  Append one or more json values into the array at path after the last element in it. 

  [Read more](json.arrappend/index)   JSON.ARRINDEX
==============

  Returns the index of the first occurrence of a JSON scalar value in the array at path 

  [Read more](json.arrindex/index)   JSON.ARRINSERT
===============

  Inserts the JSON scalar(s) value at the specified index in the array at path 

  [Read more](json.arrinsert/index)   JSON.ARRLEN
============

  Returns the length of the array at path 

  [Read more](json.arrlen/index)   JSON.ARRPOP
============

  Removes and returns the element at the specified index in the array at path 

  [Read more](json.arrpop/index)   JSON.ARRTRIM
=============

  Trims the array at path to contain only the specified inclusive range of indices from start to stop 

  [Read more](json.arrtrim/index)   JSON.CLEAR
===========

  Clears all values from an array or an object and sets numeric values to `0` 

  [Read more](json.clear/index)   JSON.DEBUG
===========

  Debugging container command 

  [Read more](json.debug/index)   JSON.DEBUG MEMORY
==================

  Reports the size in bytes of a key 

  [Read more](json.debug-memory/index)   JSON.DEL
=========

  Deletes a value 

  [Read more](json.del/index)   JSON.FORGET
============

  Deletes a value 

  [Read more](json.forget/index)   JSON.GET
=========

  Gets the value at one or more paths in JSON serialized form 

  [Read more](json.get/index)   JSON.MGET
==========

  Returns the values at a path from one or more keys 

  [Read more](json.mget/index)   JSON.NUMINCRBY
===============

  Increments the numeric value at path by a value 

  [Read more](json.numincrby/index)   JSON.NUMMULTBY
===============

  Multiplies the numeric value at path by a value 

  [Read more](json.nummultby/index)   JSON.OBJKEYS
=============

  Returns the JSON keys of the object at path 

  [Read more](json.objkeys/index)   JSON.OBJLEN
============

  Returns the number of keys of the object at path 

  [Read more](json.objlen/index)   JSON.RESP
==========

  Returns the JSON value at path in Redis Serialization Protocol (RESP) 

  [Read more](json.resp/index)   JSON.SET
=========

  Sets or updates the JSON value at a path 

  [Read more](json.set/index)   JSON.STRAPPEND
===============

  Appends a string to a JSON string value at path 

  [Read more](json.strappend/index)   JSON.STRLEN
============

  Returns the length of the JSON String at path in key 

  [Read more](json.strlen/index)   JSON.TOGGLE
============

  Toggles a boolean value 

  [Read more](json.toggle/index)   JSON.TYPE
==========

  Returns the type of the JSON value at path 

  [Read more](json.type/index)   KEYS
=====

  Returns all key names that match a pattern. 

  [Read more](keys/index)   LASTSAVE
=========

  Returns the Unix timestamp of the last successful save to disk. 

  [Read more](lastsave/index)   LATENCY DOCTOR
===============

  Returns a human-readable latency analysis report. 

  [Read more](latency-doctor/index)   LATENCY GRAPH
==============

  Returns a latency graph for an event. 

  [Read more](latency-graph/index)   LATENCY HISTOGRAM
==================

  Returns the cumulative distribution of latencies of a subset or all commands. 

  [Read more](latency-histogram/index)   LATENCY HISTORY
================

  Returns timestamp-latency samples for an event. 

  [Read more](latency-history/index)   LATENCY LATEST
===============

  Returns the latest latency samples for all events. 

  [Read more](latency-latest/index)   LATENCY RESET
==============

  Resets the latency data for one or more events. 

  [Read more](latency-reset/index)   LCS
====

  Finds the longest common substring. 

  [Read more](lcs/index)   LINDEX
=======

  Returns an element from a list by its index. 

  [Read more](lindex/index)   LINSERT
========

  Inserts an element before or after another element in a list. 

  [Read more](linsert/index)   LLEN
=====

  Returns the length of a list. 

  [Read more](llen/index)   LMOVE
======

  Returns an element after popping it from one list and pushing it to another. Deletes the list if the last element was moved. 

  [Read more](lmove/index)   LMPOP
======

  Returns multiple elements from a list after removing them. Deletes the list if the last element was popped. 

  [Read more](lmpop/index)   LOLWUT
=======

  Displays computer art and the Redis version 

  [Read more](lolwut/index)   LPOP
=====

  Returns the first elements in a list after removing it. Deletes the list if the last element was popped. 

  [Read more](lpop/index)   LPOS
=====

  Returns the index of matching elements in a list. 

  [Read more](lpos/index)   LPUSH
======

  Prepends one or more elements to a list. Creates the key if it doesn't exist. 

  [Read more](lpush/index)   LPUSHX
=======

  Prepends one or more elements to a list only when the list exists. 

  [Read more](lpushx/index)   LRANGE
=======

  Returns a range of elements from a list. 

  [Read more](lrange/index)   LREM
=====

  Removes elements from a list. Deletes the list if the last element was removed. 

  [Read more](lrem/index)   LSET
=====

  Sets the value of an element in a list by its index. 

  [Read more](lset/index)   LTRIM
======

  Removes elements from both ends a list. Deletes the list if all elements were trimmed. 

  [Read more](ltrim/index)   MEMORY DOCTOR
==============

  Outputs a memory problems report. 

  [Read more](memory-doctor/index)   MEMORY MALLOC-STATS
====================

  Returns the allocator statistics. 

  [Read more](memory-malloc-stats/index)   MEMORY PURGE
=============

  Asks the allocator to release memory. 

  [Read more](memory-purge/index)   MEMORY STATS
=============

  Returns details about memory usage. 

  [Read more](memory-stats/index)   MEMORY USAGE
=============

  Estimates the memory usage of a key. 

  [Read more](memory-usage/index)   MGET
=====

  Atomically returns the string values of one or more keys. 

  [Read more](mget/index)   MIGRATE
========

  Atomically transfers a key from one Redis instance to another. 

  [Read more](migrate/index)   MODULE LIST
============

  Returns all loaded modules. 

  [Read more](module-list/index)   MODULE LOAD
============

  Loads a module. 

  [Read more](module-load/index)   MODULE LOADEX
==============

  Loads a module using extended parameters. 

  [Read more](module-loadex/index)   MODULE UNLOAD
==============

  Unloads a module. 

  [Read more](module-unload/index)   MONITOR
========

  Listens for all requests received by the server in real-time. 

  [Read more](monitor/index)   MOVE
=====

  Moves a key to another database. 

  [Read more](move/index)   MSET
=====

  Atomically creates or modifies the string values of one or more keys. 

  [Read more](mset/index)   MSETNX
=======

  Atomically modifies the string values of one or more keys only when all keys don't exist. 

  [Read more](msetnx/index)   MULTI
======

  Starts a transaction. 

  [Read more](multi/index)   OBJECT ENCODING
================

  Returns the internal encoding of a Redis object. 

  [Read more](object-encoding/index)   OBJECT FREQ
============

  Returns the logarithmic access frequency counter of a Redis object. 

  [Read more](object-freq/index)   OBJECT IDLETIME
================

  Returns the time since the last access to a Redis object. 

  [Read more](object-idletime/index)   OBJECT REFCOUNT
================

  Returns the reference count of a value of a key. 

  [Read more](object-refcount/index)   PERSIST
========

  Removes the expiration time of a key. 

  [Read more](persist/index)   PEXPIRE
========

  Sets the expiration time of a key in milliseconds. 

  [Read more](pexpire/index)   PEXPIREAT
==========

  Sets the expiration time of a key to a Unix milliseconds timestamp. 

  [Read more](pexpireat/index)   PEXPIRETIME
============

  Returns the expiration time of a key as a Unix milliseconds timestamp. 

  [Read more](pexpiretime/index)   PFADD
======

  Adds elements to a HyperLogLog key. Creates the key if it doesn't exist. 

  [Read more](pfadd/index)   PFCOUNT
========

  Returns the approximated cardinality of the set(s) observed by the HyperLogLog key(s). 

  [Read more](pfcount/index)   PFDEBUG
========

  Internal commands for debugging HyperLogLog values. 

  [Read more](pfdebug/index)   PFMERGE
========

  Merges one or more HyperLogLog values into a single key. 

  [Read more](pfmerge/index)   PFSELFTEST
===========

  An internal command for testing HyperLogLog values. 

  [Read more](pfselftest/index)   PING
=====

  Returns the server's liveliness response. 

  [Read more](ping/index)   PSETEX
=======

  Sets both string value and expiration time in milliseconds of a key. The key is created if it doesn't exist. 

  [Read more](psetex/index)   PSUBSCRIBE
===========

  Listens for messages published to channels that match one or more patterns. 

  [Read more](psubscribe/index)   PSYNC
======

  An internal command used in replication. 

  [Read more](psync/index)   PTTL
=====

  Returns the expiration time in milliseconds of a key. 

  [Read more](pttl/index)   PUBLISH
========

  Posts a message to a channel. 

  [Read more](publish/index)   PUBSUB CHANNELS
================

  Returns the active channels. 

  [Read more](pubsub-channels/index)   PUBSUB NUMPAT
==============

  Returns a count of unique pattern subscriptions. 

  [Read more](pubsub-numpat/index)   PUBSUB NUMSUB
==============

  Returns a count of subscribers to channels. 

  [Read more](pubsub-numsub/index)   PUBSUB SHARDCHANNELS
=====================

  Returns the active shard channels. 

  [Read more](pubsub-shardchannels/index)   PUBSUB SHARDNUMSUB
===================

  Returns the count of subscribers of shard channels. 

  [Read more](pubsub-shardnumsub/index)   PUNSUBSCRIBE
=============

  Stops listening to messages published to channels that match one or more patterns. 

  [Read more](punsubscribe/index)   QUIT
=====

  Closes the connection. 

  [Read more](quit/index)   RANDOMKEY
==========

  Returns a random key name from the database. 

  [Read more](randomkey/index)   READONLY
=========

  Enables read-only queries for a connection to a Redis Cluster replica node. 

  [Read more](readonly/index)   READWRITE
==========

  Enables read-write queries for a connection to a Reids Cluster replica node. 

  [Read more](readwrite/index)   RENAME
=======

  Renames a key and overwrites the destination. 

  [Read more](rename/index)   RENAMENX
=========

  Renames a key only when the target key name doesn't exist. 

  [Read more](renamenx/index)   REPLCONF
=========

  An internal command for configuring the replication stream. 

  [Read more](replconf/index)   REPLICAOF
==========

  Configures a server as replica of another, or promotes it to a master. 

  [Read more](replicaof/index)   RESET
======

  Resets the connection. 

  [Read more](reset/index)   RESTORE
========

  Creates a key from the serialized representation of a value. 

  [Read more](restore/index)   RESTORE-ASKING
===============

  An internal command for migrating keys in a cluster. 

  [Read more](restore-asking/index)   ROLE
=====

  Returns the replication role. 

  [Read more](role/index)   RPOP
=====

  Returns and removes the last elements of a list. Deletes the list if the lst element was popped. 

  [Read more](rpop/index)   RPOPLPUSH
==========

  Returns the last element of a list after removing and pushing it to another list. Deletes the list if the lst element was popped. 

  [Read more](rpoplpush/index)   RPUSH
======

  Appends one or more elements to a list. Creates the key if it doesn't exist. 

  [Read more](rpush/index)   RPUSHX
=======

  Appends an element to a list only when the list exists. 

  [Read more](rpushx/index)   SADD
=====

  Adds one or more members to a set. Creates the key if it doesn't exist. 

  [Read more](sadd/index)   SAVE
=====

  Synchronously saves the database(s) to disk. 

  [Read more](save/index)   SCAN
=====

  Iterates over the key names in the database. 

  [Read more](scan/index)   SCARD
======

  Returns the number of members in a set. 

  [Read more](scard/index)   SCRIPT DEBUG
=============

  Sets the debug mode of server-side Lua scripts. 

  [Read more](script-debug/index)   SCRIPT EXISTS
==============

  Determines whether server-side Lua scripts exist in the script cache. 

  [Read more](script-exists/index)   SCRIPT FLUSH
=============

  Removes all server-side Lua scripts from the script cache. 

  [Read more](script-flush/index)   SCRIPT KILL
============

  Terminates a server-side Lua script during execution. 

  [Read more](script-kill/index)   SCRIPT LOAD
============

  Loads a server-side Lua script to the script cache. 

  [Read more](script-load/index)   SDIFF
======

  Returns the difference of multiple sets. 

  [Read more](sdiff/index)   SDIFFSTORE
===========

  Stores the difference of multiple sets in a key. 

  [Read more](sdiffstore/index)   SELECT
=======

  Changes the selected database. 

  [Read more](select/index)   SET
====

  Sets the string value of a key, ignoring its type. The key is created if it doesn't exist. 

  [Read more](set/index)   SETBIT
=======

  Sets or clears the bit at offset of the string value. Creates the key if it doesn't exist. 

  [Read more](setbit/index)   SETEX
======

  Sets the string value and expiration time of a key. Creates the key if it doesn't exist. 

  [Read more](setex/index)   SETNX
======

  Set the string value of a key only when the key doesn't exist. 

  [Read more](setnx/index)   SETRANGE
=========

  Overwrites a part of a string value with another by an offset. Creates the key if it doesn't exist. 

  [Read more](setrange/index)   SHUTDOWN
=========

  Synchronously saves the database(s) to disk and shuts down the Redis server. 

  [Read more](shutdown/index)   SINTER
=======

  Returns the intersect of multiple sets. 

  [Read more](sinter/index)   SINTERCARD
===========

  Returns the number of members of the intersect of multiple sets. 

  [Read more](sintercard/index)   SINTERSTORE
============

  Stores the intersect of multiple sets in a key. 

  [Read more](sinterstore/index)   SISMEMBER
==========

  Determines whether a member belongs to a set. 

  [Read more](sismember/index)   SLAVEOF
========

  Sets a Redis server as a replica of another, or promotes it to being a master. 

  [Read more](slaveof/index)   SLOWLOG GET
============

  Returns the slow log's entries. 

  [Read more](slowlog-get/index)   SLOWLOG LEN
============

  Returns the number of entries in the slow log. 

  [Read more](slowlog-len/index)   SLOWLOG RESET
==============

  Clears all entries from the slow log. 

  [Read more](slowlog-reset/index)   SMEMBERS
=========

  Returns all members of a set. 

  [Read more](smembers/index)   SMISMEMBER
===========

  Determines whether multiple members belong to a set. 

  [Read more](smismember/index)   SMOVE
======

  Moves a member from one set to another. 

  [Read more](smove/index)   SORT
=====

  Sorts the elements in a list, a set, or a sorted set, optionally storing the result. 

  [Read more](sort/index)   SORT\_RO
=========

  Returns the sorted elements of a list, a set, or a sorted set. 

  [Read more](sort_ro/index)   SPOP
=====

  Returns one or more random members from a set after removing them. Deletes the set if the last member was popped. 

  [Read more](spop/index)   SPUBLISH
=========

  Post a message to a shard channel 

  [Read more](spublish/index)   SRANDMEMBER
============

  Get one or multiple random members from a set 

  [Read more](srandmember/index)   SREM
=====

  Removes one or more members from a set. Deletes the set if the last member was removed. 

  [Read more](srem/index)   SSCAN
======

  Iterates over members of a set. 

  [Read more](sscan/index)   SSUBSCRIBE
===========

  Listens for messages published to shard channels. 

  [Read more](ssubscribe/index)   STRLEN
=======

  Returns the length of a string value. 

  [Read more](strlen/index)   SUBSCRIBE
==========

  Listens for messages published to channels. 

  [Read more](subscribe/index)   SUBSTR
=======

  Returns a substring from a string value. 

  [Read more](substr/index)   SUNION
=======

  Returns the union of multiple sets. 

  [Read more](sunion/index)   SUNIONSTORE
============

  Stores the union of multiple sets in a key. 

  [Read more](sunionstore/index)   SUNSUBSCRIBE
=============

  Stops listening to messages posted to shard channels. 

  [Read more](sunsubscribe/index)   SWAPDB
=======

  Swaps two Redis databases. 

  [Read more](swapdb/index)   SYNC
=====

  An internal command used in replication. 

  [Read more](sync/index)   TDIGEST.ADD
============

  Adds one or more observations to a t-digest sketch 

  [Read more](tdigest.add/index)   TDIGEST.BYRANK
===============

  Returns, for each input rank, an estimation of the value (floating-point) with that rank 

  [Read more](tdigest.byrank/index)   TDIGEST.BYREVRANK
==================

  Returns, for each input reverse rank, an estimation of the value (floating-point) with that reverse rank 

  [Read more](tdigest.byrevrank/index)   TDIGEST.CDF
============

  Returns, for each input value, an estimation of the fraction (floating-point) of (observations smaller than the given value + half the observations equal to the given value) 

  [Read more](tdigest.cdf/index)   TDIGEST.CREATE
===============

  Allocates memory and initializes a new t-digest sketch 

  [Read more](tdigest.create/index)   TDIGEST.INFO
=============

  Returns information and statistics about a t-digest sketch 

  [Read more](tdigest.info/index)   TDIGEST.MAX
============

  Returns the maximum observation value from a t-digest sketch 

  [Read more](tdigest.max/index)   TDIGEST.MERGE
==============

  Merges multiple t-digest sketches into a single sketch 

  [Read more](tdigest.merge/index)   TDIGEST.MIN
============

  Returns the minimum observation value from a t-digest sketch 

  [Read more](tdigest.min/index)   TDIGEST.QUANTILE
=================

  Returns, for each input fraction, an estimation of the value (floating point) that is smaller than the given fraction of observations 

  [Read more](tdigest.quantile/index)   TDIGEST.RANK
=============

  Returns, for each input value (floating-point), the estimated rank of the value (the number of observations in the sketch that are smaller than the value + half the number of observations that are equal to the value) 

  [Read more](tdigest.rank/index)   TDIGEST.RESET
==============

  Resets a t-digest sketch: empty the sketch and re-initializes it. 

  [Read more](tdigest.reset/index)   TDIGEST.REVRANK
================

  Returns, for each input value (floating-point), the estimated reverse rank of the value (the number of observations in the sketch that are larger than the value + half the number of observations that are equal to the value) 

  [Read more](tdigest.revrank/index)   TDIGEST.TRIMMED\_MEAN
======================

  Returns an estimation of the mean value from the sketch, excluding observation values outside the low and high cutoff quantiles 

  [Read more](tdigest.trimmed_mean/index)   TIME
=====

  Returns the server time. 

  [Read more](time/index)   TOPK.ADD
=========

  Increases the count of one or more items by increment 

  [Read more](topk.add/index)   TOPK.COUNT
===========

  Return the count for one or more items are in a sketch 

  [Read more](topk.count/index)   TOPK.INCRBY
============

  Increases the count of one or more items by increment 

  [Read more](topk.incrby/index)   TOPK.INFO
==========

  Returns information about a sketch 

  [Read more](topk.info/index)   TOPK.LIST
==========

  Return full list of items in Top K list 

  [Read more](topk.list/index)   TOPK.QUERY
===========

  Checks whether one or more items are in a sketch 

  [Read more](topk.query/index)   TOPK.RESERVE
=============

  Initializes a TopK with specified parameters 

  [Read more](topk.reserve/index)   TOUCH
======

  Returns the number of existing keys out of those specified after updating the time they were last accessed. 

  [Read more](touch/index)   TS.ADD
=======

  Append a sample to a time series 

  [Read more](ts.add/index)   TS.ALTER
=========

  Update the retention, chunk size, duplicate policy, and labels of an existing time series 

  [Read more](ts.alter/index)   TS.CREATE
==========

  Create a new time series 

  [Read more](ts.create/index)   TS.CREATERULE
==============

  Create a compaction rule 

  [Read more](ts.createrule/index)   TS.DECRBY
==========

  Decrease the value of the sample with the maximal existing timestamp, or create a new sample with a value equal to the value of the sample with the maximal existing timestamp with a given decrement 

  [Read more](ts.decrby/index)   TS.DEL
=======

  Delete all samples between two timestamps for a given time series 

  [Read more](ts.del/index)   TS.DELETERULE
==============

  Delete a compaction rule 

  [Read more](ts.deleterule/index)   TS.GET
=======

  Get the sample with the highest timestamp from a given time series 

  [Read more](ts.get/index)   TS.INCRBY
==========

  Increase the value of the sample with the maximal existing timestamp, or create a new sample with a value equal to the value of the sample with the maximal existing timestamp with a given increment 

  [Read more](ts.incrby/index)   TS.INFO
========

  Returns information and statistics for a time series 

  [Read more](ts.info/index)   TS.MADD
========

  Append new samples to one or more time series 

  [Read more](ts.madd/index)   TS.MGET
========

  Get the sample with the highest timestamp from each time series matching a specific filter 

  [Read more](ts.mget/index)   TS.MRANGE
==========

  Query a range across multiple time series by filters in forward direction 

  [Read more](ts.mrange/index)   TS.MREVRANGE
=============

  Query a range across multiple time-series by filters in reverse direction 

  [Read more](ts.mrevrange/index)   TS.QUERYINDEX
==============

  Get all time series keys matching a filter list 

  [Read more](ts.queryindex/index)   TS.RANGE
=========

  Query a range in forward direction 

  [Read more](ts.range/index)   TS.REVRANGE
============

  Query a range in reverse direction 

  [Read more](ts.revrange/index)   TTL
====

  Returns the expiration time in seconds of a key. 

  [Read more](ttl/index)   TYPE
=====

  Determines the type of value stored at a key. 

  [Read more](type/index)   UNLINK
=======

  Asynchronously deletes one or more keys. 

  [Read more](unlink/index)   UNSUBSCRIBE
============

  Stops listening to messages posted to channels. 

  [Read more](unsubscribe/index)   UNWATCH
========

  Forgets about watched keys of a transaction. 

  [Read more](unwatch/index)   WAIT
=====

  Blocks until the asynchronous replication of all preceding write commands sent by the connection is completed. 

  [Read more](wait/index)   WAITAOF
========

  Blocks until all of the preceding write commands sent by the connection are written to the append-only file of the master and/or replicas. 

  [Read more](waitaof/index)   WATCH
======

  Monitors changes to keys to determine the execution of a transaction. 

  [Read more](watch/index)   XACK
=====

  Returns the number of messages that were successfully acknowledged by the consumer group member of a stream. 

  [Read more](xack/index)   XADD
=====

  Appends a new message to a stream. Creates the key if it doesn't exist. 

  [Read more](xadd/index)   XAUTOCLAIM
===========

  Changes, or acquires, ownership of messages in a consumer group, as if the messages were delivered to as consumer group member. 

  [Read more](xautoclaim/index)   XCLAIM
=======

  Changes, or acquires, ownership of a message in a consumer group, as if the message was delivered a consumer group member. 

  [Read more](xclaim/index)   XDEL
=====

  Returns the number of messages after removing them from a stream. 

  [Read more](xdel/index)   XGROUP CREATE
==============

  Creates a consumer group. 

  [Read more](xgroup-create/index)   XGROUP CREATECONSUMER
======================

  Creates a consumer in a consumer group. 

  [Read more](xgroup-createconsumer/index)   XGROUP DELCONSUMER
===================

  Deletes a consumer from a consumer group. 

  [Read more](xgroup-delconsumer/index)   XGROUP DESTROY
===============

  Destroys a consumer group. 

  [Read more](xgroup-destroy/index)   XGROUP SETID
=============

  Sets the last-delivered ID of a consumer group. 

  [Read more](xgroup-setid/index)   XINFO CONSUMERS
================

  Returns a list of the consumers in a consumer group. 

  [Read more](xinfo-consumers/index)   XINFO GROUPS
=============

  Returns a list of the consumer groups of a stream. 

  [Read more](xinfo-groups/index)   XINFO STREAM
=============

  Returns information about a stream. 

  [Read more](xinfo-stream/index)   XLEN
=====

  Return the number of messages in a stream. 

  [Read more](xlen/index)   XPENDING
=========

  Returns the information and entries from a stream consumer group's pending entries list. 

  [Read more](xpending/index)   XRANGE
=======

  Returns the messages from a stream within a range of IDs. 

  [Read more](xrange/index)   XREAD
======

  Returns messages from multiple streams with IDs greater than the ones requested. Blocks until a message is available otherwise. 

  [Read more](xread/index)   XREADGROUP
===========

  Returns new or historical messages from a stream for a consumer in agroup. Blocks until a message is available otherwise. 

  [Read more](xreadgroup/index)   XREVRANGE
==========

  Returns the messages from a stream within a range of IDs in reverse order. 

  [Read more](xrevrange/index)   XSETID
=======

  An internal command for replicating stream values. 

  [Read more](xsetid/index)   XTRIM
======

  Deletes messages from the beginning of a stream. 

  [Read more](xtrim/index)   ZADD
=====

  Adds one or more members to a sorted set, or updates their scores. Creates the key if it doesn't exist. 

  [Read more](zadd/index)   ZCARD
======

  Returns the number of members in a sorted set. 

  [Read more](zcard/index)   ZCOUNT
=======

  Returns the count of members in a sorted set that have scores within a range. 

  [Read more](zcount/index)   ZDIFF
======

  Returns the difference between multiple sorted sets. 

  [Read more](zdiff/index)   ZDIFFSTORE
===========

  Stores the difference of multiple sorted sets in a key. 

  [Read more](zdiffstore/index)   ZINCRBY
========

  Increments the score of a member in a sorted set. 

  [Read more](zincrby/index)   ZINTER
=======

  Returns the intersect of multiple sorted sets. 

  [Read more](zinter/index)   ZINTERCARD
===========

  Returns the number of members of the intersect of multiple sorted sets. 

  [Read more](zintercard/index)   ZINTERSTORE
============

  Stores the intersect of multiple sorted sets in a key. 

  [Read more](zinterstore/index)   ZLEXCOUNT
==========

  Returns the number of members in a sorted set within a lexicographical range. 

  [Read more](zlexcount/index)   ZMPOP
======

  Returns the highest- or lowest-scoring members from one or more sorted sets after removing them. Deletes the sorted set if the last member was popped. 

  [Read more](zmpop/index)   ZMSCORE
========

  Returns the score of one or more members in a sorted set. 

  [Read more](zmscore/index)   ZPOPMAX
========

  Returns the highest-scoring members from a sorted set after removing them. Deletes the sorted set if the last member was popped. 

  [Read more](zpopmax/index)   ZPOPMIN
========

  Returns the lowest-scoring members from a sorted set after removing them. Deletes the sorted set if the last member was popped. 

  [Read more](zpopmin/index)   ZRANDMEMBER
============

  Returns one or more random members from a sorted set. 

  [Read more](zrandmember/index)   ZRANGE
=======

  Returns members in a sorted set within a range of indexes. 

  [Read more](zrange/index)   ZRANGEBYLEX
============

  Returns members in a sorted set within a lexicographical range. 

  [Read more](zrangebylex/index)   ZRANGEBYSCORE
==============

  Returns members in a sorted set within a range of scores. 

  [Read more](zrangebyscore/index)   ZRANGESTORE
============

  Stores a range of members from sorted set in a key. 

  [Read more](zrangestore/index)   ZRANK
======

  Returns the index of a member in a sorted set ordered by ascending scores. 

  [Read more](zrank/index)   ZREM
=====

  Removes one or more members from a sorted set. Deletes the sorted set if all members were removed. 

  [Read more](zrem/index)   ZREMRANGEBYLEX
===============

  Removes members in a sorted set within a lexicographical range. Deletes the sorted set if all members were removed. 

  [Read more](zremrangebylex/index)   ZREMRANGEBYRANK
================

  Removes members in a sorted set within a range of indexes. Deletes the sorted set if all members were removed. 

  [Read more](zremrangebyrank/index)   ZREMRANGEBYSCORE
=================

  Removes members in a sorted set within a range of scores. Deletes the sorted set if all members were removed. 

  [Read more](zremrangebyscore/index)   ZREVRANGE
==========

  Returns members in a sorted set within a range of indexes in reverse order. 

  [Read more](zrevrange/index)   ZREVRANGEBYLEX
===============

  Returns members in a sorted set within a lexicographical range in reverse order. 

  [Read more](zrevrangebylex/index)   ZREVRANGEBYSCORE
=================

  Returns members in a sorted set within a range of scores in reverse order. 

  [Read more](zrevrangebyscore/index)   ZREVRANK
=========

  Returns the index of a member in a sorted set ordered by descending scores. 

  [Read more](zrevrank/index)   ZSCAN
======

  Iterates over members and scores of a sorted set. 

  [Read more](zscan/index)   ZSCORE
=======

  Returns the score of a member in a sorted set. 

  [Read more](zscore/index)   ZUNION
=======

  Returns the union of multiple sorted sets. 

  [Read more](zunion/index)   ZUNIONSTORE
============

  Stores the union of multiple sorted sets in a key. 

  [Read more](zunionstore/index) 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands>

ACL
===



```
ACL CAT
```
 Syntax 
```
ACL CAT [category]
```
  Available since: 6.0.0 Time complexity: O(1) since the categories and commands are a fixed set. ACL categories:  `@slow`,   The command shows the available ACL categories if called without arguments. If a category name is given, the command shows all the Redis commands in the specified category.

 ACL categories are very useful in order to create ACL rules that include or exclude a large set of commands at once, without specifying every single command. For instance, the following rule will let the user `karin` perform everything but the most dangerous operations that may affect the server stability:

 
```
ACL SETUSER karin on +@all -@dangerous

```
 We first add all the commands to the set of commands that `karin` is able to execute, but then we remove all the dangerous commands.

 Checking for all the available categories is as simple as:

 
```
> ACL CAT
 1) "keyspace"
 2) "read"
 3) "write"
 4) "set"
 5) "sortedset"
 6) "list"
 7) "hash"
 8) "string"
 9) "bitmap"
10) "hyperloglog"
11) "geo"
12) "stream"
13) "pubsub"
14) "admin"
15) "fast"
16) "slow"
17) "blocking"
18) "dangerous"
19) "connection"
20) "transaction"
21) "scripting"

```

Then we may want to know what commands are part of a given category:

 
```
> ACL CAT dangerous
 1) "flushdb"
 2) "acl"
 3) "slowlog"
 4) "debug"
 5) "role"
 6) "keys"
 7) "pfselftest"
 8) "client"
 9) "bgrewriteaof"
10) "replicaof"
11) "monitor"
12) "restore-asking"
13) "latency"
14) "replconf"
15) "pfdebug"
16) "bgsave"
17) "sync"
18) "config"
19) "flushall"
20) "cluster"
21) "info"
22) "lastsave"
23) "slaveof"
24) "swapdb"
25) "module"
26) "restore"
27) "migrate"
28) "save"
29) "shutdown"
30) "psync"
31) "sort"

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of ACL categories or a list of commands inside a given category. The command may return an error if an invalid category name is given as argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-cat/>

ASKING
======



```
ASKING
```
 Syntax 
```
ASKING
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   When a cluster client receives an `-ASK` redirect, the `ASKING` command is sent to the target node followed by the command which was redirected. This is normally done automatically by cluster clients.

 If an `-ASK` redirect is received during a transaction, only one ASKING command needs to be sent to the target node before sending the complete transaction to the target node.

 See [ASK redirection in the Redis Cluster Specification](https://redis.io/topics/cluster-spec#ask-redirection) for details.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/asking/>

BF.EXISTS
=========



```
BF.EXISTS
```
 Syntax 
```
BF.EXISTS key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k), where k is the number of hash functions used by the last sub-filter  Determines whether an item may exist in the Bloom Filter or not.

 ### Parameters

 * **key**: The name of the filter
* **item**: The item to check for

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - where "1" value means the item may exist in the filter, and a "0" value means it does not exist in the filter.

 Examples
--------

 
```
redis> BF.EXISTS bf item1
(integer) 1
redis> BF.EXISTS bf item_new
(integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.exists/>

ACL
===



```
ACL LIST
```
 Syntax 
```
ACL LIST
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of configured users. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command shows the currently active ACL rules in the Redis server. Each line in the returned array defines a different user, and the format is the same used in the redis.conf file or the external ACL file, so you can cut and paste what is returned by the ACL LIST command directly inside a configuration file if you wish (but make sure to check [`ACL SAVE`](../acl-save)).

 Return
------

 An array of strings.

 Examples
--------

 
```
> ACL LIST
1) "user antirez on #9f86d081884c7d659a2feaa0c55ad015a3bf4f1b2b0b822cd15d6c15b0f00a08 ~objects:* &* +@all -@admin -@dangerous"
2) "user default on nopass ~* &* +@all"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-list/>

BF.CARD
=======



```
BF.CARD
```
 Syntax 
```
BF.CARD key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.4](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns the cardinality of a Bloom filter - number of items that were added to a Bloom filter and detected as unique (items that caused at least one bit to be set in at least one sub-filter)

 (since RedisBloom 2.4.4)

 ### Parameters

 * **key**: The name of the filter

 Return
------

 * [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - the number of items that were added to this Bloom filter and detected as unique (items that caused at least one bit to be set in at least one sub-filter).
* 0 when `key` does not exist.
* Error when `key` is of a type other than Bloom filter.

 Note: when `key` exists - return the same value as `BF.INFO key ITEMS`.

 Examples
--------

 
```
redis> BF.ADD bf1 item_foo
(integer) 1
redis> BF.CARD bf1
(integer) 1
redis> BF.CARD bf_new
(integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.card/>

BF.INSERT
=========



```
BF.INSERT
```
 Syntax 
```
BF.INSERT key [CAPACITY capacity] [ERROR error]
  [EXPANSION expansion] [NOCREATE] [NONSCALING] ITEMS item [item
  ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k \* n), where k is the number of hash functions and n is the number of items  BF.INSERT is a sugarcoated combination of BF.RESERVE and BF.ADD. It creates a new filter if the `key` does not exist using the relevant arguments (see BF.RESERVE). Next, all `ITEMS` are inserted.

 ### Parameters

 * **key**: The name of the filter
* **item**: One or more items to add. The `ITEMS` keyword must precede the list of items to add.

 Optional parameters:

 * **NOCREATE**: (Optional) Indicates that the filter should not be created if it does not already exist. If the filter does not yet exist, an error is returned rather than creating it automatically. This may be used where a strict separation between filter creation and filter addition is desired. It is an error to specify `NOCREATE` together with either `CAPACITY` or `ERROR`.
* **capacity**: (Optional) Specifies the desired `capacity` for the filter to be created. This parameter is ignored if the filter already exists. If the filter is automatically created and this parameter is absent, then the module-level `capacity` is used. See [`BF.RESERVE`](../bf.reserve) for more information about the impact of this value.
* **error**: (Optional) Specifies the `error` ratio of the newly created filter if it does not yet exist. If the filter is automatically created and `error` is not specified then the module-level error rate is used. See [`BF.RESERVE`](../bf.reserve) for more information about the format of this value.
* **NONSCALING**: Prevents the filter from creating additional sub-filters if initial capacity is reached. Non-scaling filters require slightly less memory than their scaling counterparts. The filter returns an error when `capacity` is reached.
* **expansion**: When `capacity` is reached, an additional sub-filter is created. The size of the new sub-filter is the size of the last sub-filter multiplied by `expansion`. If the number of elements to be stored in the filter is unknown, we recommend that you use an `expansion` of 2 or more to reduce the number of sub-filters. Otherwise, we recommend that you use an `expansion` of 1 to reduce memory consumption. The default expansion value is 2.

 Return
------

 An array of booleans (integers). Each element is either true or false depending on whether the corresponding input element was newly added to the filter or may have previously existed.

 Examples
--------

 Add three items to a filter with default parameters if the filter does not already exist:

 
```
BF.INSERT filter ITEMS foo bar baz

```

Add one item to a filter with a capacity of 10000 if the filter does not already exist:

 
```
BF.INSERT filter CAPACITY 10000 ITEMS hello

```

Add 2 items to a filter with an error if the filter does not already exist:

 
```
BF.INSERT filter NOCREATE ITEMS foo bar

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.insert/>

BF.INFO
=======



```
BF.INFO
```
 Syntax 
```
BF.INFO key [CAPACITY | SIZE | FILTERS | ITEMS | EXPANSION]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Return information about a Bloom filter.

 ### Parameters

 * **key**: key name for an existing Bloom filter.

 Optional parameters:

 * `CAPACITY` Number of unique items that can be stored in this Bloom filter before scaling would be required (including already added items)
* `SIZE` Memory size: number of bytes allocated for this Bloom filter
* `FILTERS` Number of sub-filters
* `ITEMS` Number of items that were added to this Bloom filter and detected as unique (items that caused at least one bit to be set in at least one sub-filter)
* `EXPANSION` Expansion rate

 When no optional parameter is specified: return all information fields.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information about the Bloom filter.

 Error when `key` does not exist.

 Error when `key` is of a type other than Bloom filter.

 Examples
--------

 
```
redis>BF.ADDbf1observation1(integer)1redis>BF.INFObf11)Capacity2)(integer)1003)Size4)(integer)2405)Numberoffilters6)(integer)17)Numberofitemsinserted8)(integer)19)Expansionrate10)(integer)2redis>BF.INFObf1CAPACITY1)(integer)100
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.info/>

ACL
===



```
ACL WHOAMI
```
 Syntax 
```
ACL WHOAMI
```
  Available since: 6.0.0 Time complexity: O(1) ACL categories:  `@slow`,   Return the username the current connection is authenticated with. New connections are authenticated with the "default" user. They can change user using [`AUTH`](../auth).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the username of the current connection.

 Examples
--------

 
```
> ACL WHOAMI
"default"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-whoami/>

APPEND
======



```
APPEND
```
 Syntax 
```
APPEND key value
```
  Available since: 2.0.0 Time complexity: O(1). The amortized time complexity is O(1) assuming the appended value is small and the already present value is of any size, since the dynamic string library used by Redis will double the free space available on every reallocation. ACL categories:  `@write`, `@string`, `@fast`,   If `key` already exists and is a string, this command appends the `value` at the end of the string. If `key` does not exist it is created and set as an empty string, so `APPEND` will be similar to [`SET`](../set) in this special case.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the string after the append operation.

 Examples
--------

 
```

EXISTS mykey
APPEND mykey "Hello"
APPEND mykey " World"
GET mykey

```
 Pattern: Time series
--------------------

 The `APPEND` command can be used to create a very compact representation of a list of fixed-size samples, usually referred as *time series*. Every time a new sample arrives we can store it using the command

 
```
APPEND timeseries "fixed-size sample"

```

Accessing individual elements in the time series is not hard:

 * [`STRLEN`](../strlen) can be used in order to obtain the number of samples.
* [`GETRANGE`](../getrange) allows for random access of elements. If our time series have associated time information we can easily implement a binary search to get range combining [`GETRANGE`](../getrange) with the Lua scripting engine available in Redis 2.6.
* [`SETRANGE`](../setrange) can be used to overwrite an existing time series.

 The limitation of this pattern is that we are forced into an append-only mode of operation, there is no way to cut the time series to a given size easily because Redis currently lacks a command able to trim string objects. However the space efficiency of time series stored in this way is remarkable.

 Hint: it is possible to switch to a different key based on the current Unix time, in this way it is possible to have just a relatively small amount of samples per key, to avoid dealing with very big keys, and to make this pattern more friendly to be distributed across many Redis instances.

 An example sampling the temperature of a sensor using fixed-size strings (using a binary format is better in real implementations).

 
```

APPEND ts "0043"
APPEND ts "0035"
GETRANGE ts 0 3
GETRANGE ts 4 7

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/append/>

BF.LOADCHUNK
============



```
BF.LOADCHUNK
```
 Syntax 
```
BF.LOADCHUNK key iterator data
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n), where n is the capacity  Restores a filter previously saved using `SCANDUMP`. See the `SCANDUMP` command for example usage.

 This command overwrites any bloom filter stored under `key`. Make sure that the bloom filter is not be changed between invocations.

 ### Parameters

 * **key**: Name of the key to restore
* **iter**: Iterator value associated with `data` (returned by `SCANDUMP`)
* **data**: Current data chunk (returned by `SCANDUMP`)

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 See BF.SCANDUMP for an example.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.loadchunk/>

BF.SCANDUMP
===========



```
BF.SCANDUMP
```
 Syntax 
```
BF.SCANDUMP key iterator
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n), where n is the capacity  Begins an incremental save of the bloom filter. This is useful for large bloom filters which cannot fit into the normal [`DUMP`](../dump) and [`RESTORE`](../restore) model.

 The first time this command is called, the value of `iter` should be 0. This command returns successive `(iter, data)` pairs until `(0, NULL)` to indicate completion.

 ### Parameters

 * **key**: Name of the filter
* **iter**: Iterator value; either 0 or the iterator from a previous invocation of this command

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) (*Iterator*) and [] (*Data*). The Iterator is passed as input to the next invocation of `SCANDUMP`. If *Iterator* is 0, then it means iteration has completed.

 The iterator-data pair should also be passed to `LOADCHUNK` when restoring the filter.

 @example

 
```
redis> BF.RESERVE bf 0.1 10
OK
redis> BF.ADD bf item1
1) (integer) 1
redis> BF.SCANDUMP bf 0
1) (integer) 1
2) "\x01\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x05\x00\x00\x00\x02\x00\x00\x00\b\x00\x00\x00\x00\x00\x00\x00@\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x9a\x99\x99\x99\x99\x99\xa9?J\xf7\xd4\x9e\xde\xf0\x18@\x05\x00\x00\x00\n\x00\x00\x00\x00\x00\x00\x00\x00"
redis> BF.SCANDUMP bf 1
1) (integer) 9
2) "\x01\b\x00\x80\x00\x04 \x00"
redis> BF.SCANDUMP bf 9
1) (integer) 0
2) ""
redis> FLUSHALL
OK
redis> BF.LOADCHUNK bf 1 "\x01\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x05\x00\x00\x00\x02\x00\x00\x00\b\x00\x00\x00\x00\x00\x00\x00@\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x9a\x99\x99\x99\x99\x99\xa9?J\xf7\xd4\x9e\xde\xf0\x18@\x05\x00\x00\x00\n\x00\x00\x00\x00\x00\x00\x00\x00"
OK
redis> BF.LOADCHUNK bf 9 "\x01\b\x00\x80\x00\x04 \x00"
OK
redis> BF.EXISTS bf item1
(integer) 1

```

python code:

 
```
chunks = []
iter = 0
while True:
    iter, data = BF.SCANDUMP(key, iter)
    if iter == 0:
        break
    else:
        chunks.append([iter, data])

# Load it back
for chunk in chunks:
    iter, data = chunk
    BF.LOADCHUNK(key, iter, data)

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.scandump/>

ACL
===



```
ACL GETUSER
```
 Syntax 
```
ACL GETUSER username
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of password, command and pattern rules that the user has. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command returns all the rules defined for an existing ACL user.

 Specifically, it lists the user's ACL flags, password hashes, commands, key patterns, channel patterns (Added in version 6.2) and selectors (Added in version 7.0). Additional information may be returned in the future if more metadata is added to the user.

 Command rules are always returned in the same format as the one used in the [`ACL SETUSER`](../acl-setuser) command. Before version 7.0, keys and channels were returned as an array of patterns, however in version 7.0 later they are now also returned in same format as the one used in the [`ACL SETUSER`](../acl-setuser) command. Note: This description of command rules reflects the user's effective permissions, so while it may not be identical to the set of rules used to configure the user, it is still functionally identical.

 Selectors are listed in the order they were applied to the user, and include information about commands, key patterns, and channel patterns.

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of ACL rule definitions for the user.

 If `user` does not exist a [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) is returned.

 Examples
--------

 Here's an example configuration for a user

 
```
> ACL SETUSER sample on nopass +GET allkeys &* (+SET ~key2)
"OK"
> ACL GETUSER sample
1) "flags"
2) 1) "on"
   2) "allkeys"
   3) "nopass"
3) "passwords"
4) (empty array)
5) "commands"
6) "+@all"
7) "keys"
8) "~*"
9) "channels"
10) "&*"
11) "selectors"
12) 1) 1) "commands"
       6) "+SET"
       7) "keys"
       8) "~key2"
       9) "channels"
       10) "&*"

```
 History
-------

 * Starting with Redis version 6.2.0: Added Pub/Sub channel patterns.
* Starting with Redis version 7.0.0: Added selectors and changed the format of key and channel patterns from a list to their rule representation.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-getuser/>

BF.MEXISTS
==========



```
BF.MEXISTS
```
 Syntax 
```
BF.MEXISTS key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k \* n), where k is the number of hash functions and n is the number of items  Determines if one or more items may exist in the filter or not.

 ### Parameters

 * **key**: The name of the filter
* **items**: One or more items to check

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - for each item where "1" value means the corresponding item may exist in the filter, and a "0" value means it does not exist in the filter.

 Examples
--------

 
```
redis> BF.MEXISTS bf item1 item_new
1) (integer) 1
2) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.mexists/>

BF.MADD
=======



```
BF.MADD
```
 Syntax 
```
BF.MADD key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k \* n), where k is the number of hash functions and n is the number of items  Adds one or more items to the Bloom Filter and creates the filter if it does not exist yet. This command operates identically to [`BF.ADD`](../bf.add) except that it allows multiple inputs and returns multiple values.

 ### Parameters

 * **key**: The name of the filter
* **item**: One or more items to add

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - for each item which is either "1" or "0" depending on whether the corresponding input element was newly added to the filter or may have previously existed.

 Examples
--------

 
```
redis> BF.MADD bf item1 item2
1) (integer) 0
2) (integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.madd/>

BF.RESERVE
==========



```
BF.RESERVE
```
 Syntax 
```
BF.RESERVE key error_rate capacity [EXPANSION expansion]
  [NONSCALING]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Creates an empty Bloom Filter with a single sub-filter for the initial capacity requested and with an upper bound `error_rate`. By default, the filter auto-scales by creating additional sub-filters when `capacity` is reached. The new sub-filter is created with size of the previous sub-filter multiplied by `expansion`.

 Though the filter can scale up by creating sub-filters, it is recommended to reserve the estimated required `capacity` since maintaining and querying sub-filters requires additional memory (each sub-filter uses an extra bits and hash function) and consume further CPU time than an equivalent filter that had the right capacity at creation time.

 The number of hash functions is `-log(error)/ln(2)^2`. The number of bits per item is `-log(error)/ln(2)` ≈ 1.44.

 * **1%** error rate requires 7 hash functions and 10.08 bits per item.
* **0.1%** error rate requires 10 hash functions and 14.4 bits per item.
* **0.01%** error rate requires 14 hash functions and 20.16 bits per item.

 ### Parameters:

 * **key**: The key under which the filter is found
* **error\_rate**: The desired probability for false positives. The rate is a decimal value between 0 and 1. For example, for a desired false positive rate of 0.1% (1 in 1000), error\_rate should be set to 0.001.
* **capacity**: The number of entries intended to be added to the filter. If your filter allows scaling, performance will begin to degrade after adding more items than this number. The actual degradation depends on how far the limit has been exceeded. Performance degrades linearly with the number of `sub-filters`.

 Optional parameters:

 * **NONSCALING**: Prevents the filter from creating additional sub-filters if initial capacity is reached. Non-scaling filters requires slightly less memory than their scaling counterparts. The filter returns an error when `capacity` is reached.
* **EXPANSION**: When `capacity` is reached, an additional sub-filter is created. The size of the new sub-filter is the size of the last sub-filter multiplied by `expansion`. If the number of elements to be stored in the filter is unknown, we recommend that you use an `expansion` of 2 or more to reduce the number of sub-filters. Otherwise, we recommend that you use an `expansion` of 1 to reduce memory consumption. The default expansion value is 2.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> BF.RESERVE bf 0.01 1000
OK

```


```
redis> BF.RESERVE bf 0.01 1000
(error) ERR item exists

```


```
redis> BF.RESERVE bf_exp 0.01 1000 EXPANSION 2
OK

```


```
redis> BF.RESERVE bf_non 0.01 1000 NONSCALING
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.reserve/>

ACL
===



```
ACL DELUSER
```
 Syntax 
```
ACL DELUSER username [username ...]
```
  Available since: 6.0.0 Time complexity: O(1) amortized time considering the typical user. ACL categories:  `@admin`, `@slow`, `@dangerous`,   Delete all the specified ACL users and terminate all the connections that are authenticated with such users. Note: the special `default` user cannot be removed from the system, this is the default user that every new connection is authenticated with. The list of users may include usernames that do not exist, in such case no operation is performed for the non existing users.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of users that were deleted. This number will not always match the number of arguments since certain users may not exist.

 Examples
--------

 
```
> ACL DELUSER antirez
1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-deluser/>

BITCOUNT
========



```
BITCOUNT
```
 Syntax 
```
BITCOUNT key [start end [BYTE | BIT]]
```
  Available since: 2.6.0 Time complexity: O(N) ACL categories:  `@read`, `@bitmap`, `@slow`,   Count the number of set bits (population counting) in a string.

 By default all the bytes contained in the string are examined. It is possible to specify the counting operation only in an interval passing the additional arguments *start* and *end*.

 Like for the [`GETRANGE`](../getrange) command start and end can contain negative values in order to index bytes starting from the end of the string, where -1 is the last byte, -2 is the penultimate, and so forth.

 Non-existent keys are treated as empty strings, so the command will return zero.

 By default, the additional arguments *start* and *end* specify a byte index. We can use an additional argument `BIT` to specify a bit index. So 0 is the first bit, 1 is the second bit, and so forth. For negative values, -1 is the last bit, -2 is the penultimate, and so forth.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The number of bits set to 1.

 Examples
--------

 
```

SET mykey "foobar"
BITCOUNT mykey
BITCOUNT mykey 0 0
BITCOUNT mykey 1 1
BITCOUNT mykey 1 1 BYTE
BITCOUNT mykey 5 30 BIT

```
 Pattern: real-time metrics using bitmaps
----------------------------------------

 Bitmaps are a very space-efficient representation of certain kinds of information. One example is a Web application that needs the history of user visits, so that for instance it is possible to determine what users are good targets of beta features.

 Using the [`SETBIT`](../setbit) command this is trivial to accomplish, identifying every day with a small progressive integer. For instance day 0 is the first day the application was put online, day 1 the next day, and so forth.

 Every time a user performs a page view, the application can register that in the current day the user visited the web site using the [`SETBIT`](../setbit) command setting the bit corresponding to the current day.

 Later it will be trivial to know the number of single days the user visited the web site simply calling the `BITCOUNT` command against the bitmap.

 A similar pattern where user IDs are used instead of days is described in the article called "[Fast easy realtime metrics using Redis bitmaps](http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps)".

 Performance considerations
--------------------------

 In the above example of counting days, even after 10 years the application is online we still have just `365*10` bits of data per user, that is just 456 bytes per user. With this amount of data `BITCOUNT` is still as fast as any other O(1) Redis command like [`GET`](../get) or [`INCR`](../incr).

 When the bitmap is big, there are two alternatives:

 * Taking a separated key that is incremented every time the bitmap is modified. This can be very efficient and atomic using a small Redis Lua script.
* Running the bitmap incrementally using the `BITCOUNT` *start* and *end* optional parameters, accumulating the results client-side, and optionally caching the result into a key.

 History
-------

 * Starting with Redis version 7.0.0: Added the `BYTE|BIT` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bitcount/>

BGSAVE
======



```
BGSAVE
```
 Syntax 
```
BGSAVE [SCHEDULE]
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Save the DB in background.

 Normally the OK code is immediately returned. Redis forks, the parent continues to serve the clients, the child saves the DB on disk then exits.

 An error is returned if there is already a background save running or if there is another non-background-save process running, specifically an in-progress AOF rewrite.

 If `BGSAVE SCHEDULE` is used, the command will immediately return `OK` when an AOF rewrite is in progress and schedule the background save to run at the next opportunity.

 A client may be able to check if the operation succeeded using the [`LASTSAVE`](../lastsave) command.

 Please refer to the [persistence documentation](https://redis.io/topics/persistence) for detailed information.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `Background saving started` if `BGSAVE` started correctly or `Background saving scheduled` when used with the `SCHEDULE` subcommand.

 History
-------

 * Starting with Redis version 3.2.2: Added the `SCHEDULE` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bgsave/>

BITFIELD\_RO
============



```
BITFIELD_RO
```
 Syntax 
```
BITFIELD_RO key [GET encoding offset [GET encoding offset ...]]
```
  Available since: 6.0.0 Time complexity: O(1) for each subcommand specified ACL categories:  `@read`, `@bitmap`, `@fast`,   Read-only variant of the [`BITFIELD`](../bitfield) command. It is like the original [`BITFIELD`](../bitfield) but only accepts `GET` subcommand and can safely be used in read-only replicas.

 Since the original [`BITFIELD`](../bitfield) has `SET` and `INCRBY` options it is technically flagged as a writing command in the Redis command table. For this reason read-only replicas in a Redis Cluster will redirect it to the master instance even if the connection is in read-only mode (see the [`READONLY`](../readonly) command of Redis Cluster).

 Since Redis 6.2, the `BITFIELD_RO` variant was introduced in order to allow [`BITFIELD`](../bitfield) behavior in read-only replicas without breaking compatibility on command flags.

 See original [`BITFIELD`](../bitfield) for more details.

 Examples
--------

 
```
BITFIELD_RO hello GET i8 16

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): An array with each entry being the corresponding result of the subcommand given at the same position.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bitfield_ro/>

BGREWRITEAOF
============



```
BGREWRITEAOF
```
 Syntax 
```
BGREWRITEAOF
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Instruct Redis to start an [Append Only File](https://redis.io/topics/persistence#append-only-file) rewrite process. The rewrite will create a small optimized version of the current Append Only File.

 If `BGREWRITEAOF` fails, no data gets lost as the old AOF will be untouched.

 The rewrite will be only triggered by Redis if there is not already a background process doing persistence.

 Specifically:

 * If a Redis child is creating a snapshot on disk, the AOF rewrite is *scheduled* but not started until the saving child producing the RDB file terminates. In this case the `BGREWRITEAOF` will still return a positive status reply, but with an appropriate message. You can check if an AOF rewrite is scheduled looking at the [`INFO`](../info) command as of Redis 2.6 or successive versions.
* If an AOF rewrite is already in progress the command returns an error and no AOF rewrite will be scheduled for a later time.
* If the AOF rewrite could start, but the attempt at starting it fails (for instance because of an error in creating the child process), an error is returned to the caller.

 Since Redis 2.4 the AOF rewrite is automatically triggered by Redis, however the `BGREWRITEAOF` command can be used to trigger a rewrite at any time.

 Please refer to the [persistence documentation](https://redis.io/topics/persistence) for detailed information.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): A simple string reply indicating that the rewriting started or is about to start ASAP, when the call is executed with success.

 The command may reply with an error in certain cases, as documented above.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bgrewriteaof/>

ACL
===



```
ACL SETUSER
```
 Syntax 
```
ACL SETUSER username [rule [rule ...]]
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of rules provided. ACL categories:  `@admin`, `@slow`, `@dangerous`,   Create an ACL user with the specified rules or modify the rules of an existing user.

 Manipulate Redis ACL users interactively. If the username does not exist, the command creates the username without any privilege. It then reads from left to right all the [rules](#acl-rules) provided as successive arguments, setting the user ACL rules as specified. If the user already exists, the provided ACL rules are simply applied *in addition* to the rules already set. For example:

 
```
ACL SETUSER virginia on allkeys +set

```
 The above command creates a user called `virginia` who is active(the *on* rule), can access any key (*allkeys* rule), and can call the set command (*+set* rule). Then, you can use another `ACL SETUSER` call to modify the user rules:

 
```
ACL SETUSER virginia +get

```
 The above rule applies the new rule to the user `virginia`, so other than [`SET`](../set), the user `virginia` can now also use the [`GET`](../get) command.

 Starting from Redis 7.0, ACL rules can also be grouped into multiple distinct sets of rules, called *selectors*. Selectors are added by wrapping the rules in parentheses and providing them just like any other rule. In order to execute a command, either the root permissions (rules defined outside of parenthesis) or any of the selectors (rules defined inside parenthesis) must match the given command. For example:

 
```
ACL SETUSER virginia on +GET allkeys (+SET ~app1*)

```
 This sets a user with two sets of permissions, one defined on the user and one defined with a selector. The root user permissions only allow executing the get command, but can be executed on any keys. The selector then grants a secondary set of permissions: access to the [`SET`](../set) command to be executed on any key that starts with `app1`. Using multiple selectors allows you to grant permissions that are different depending on what keys are being accessed.

 When we want to be sure to define a user from scratch, without caring if it had previously defined rules associated, we can use the special rule `reset` as first rule, in order to flush all the other existing rules:

 
```
ACL SETUSER antirez reset [... other rules ...]

```
 After resetting a user, its ACL rules revert to the default: inactive, passwordless, can't execute any command nor access any key or channel:

 
```
> ACL SETUSER antirez reset
+OK
> ACL LIST
1) "user antirez off -@all"

```
 ACL rules are either words like "on", "off", "reset", "allkeys", or are special rules that start with a special character, and are followed by another string (without any space in between), like "+SET".

 The following documentation is a reference manual about the capabilities of this command, however our [ACL tutorial](https://redis.io/topics/acl) may be a more gentle introduction to how the ACL system works in general.

 ACL rules
---------

 Redis ACL rules are split into two categories: rules that define command permissions or *command rules*, and rules that define the user state or *user management rules*. This is a list of all the supported Redis ACL rules:

 ### Command rules

 * `~<pattern>`: Adds the specified key pattern (glob style pattern, like in the [`KEYS`](../keys) command), to the list of key patterns accessible by the user. This grants both read and write permissions to keys that match the pattern. You can add multiple key patterns to the same user. Example: `~objects:*`
* `%R~<pattern>`: (Available in Redis 7.0 and later) Adds the specified read key pattern. This behaves similar to the regular key pattern but only grants permission to read from keys that match the given pattern. See [key permissions](https://redis.io/topics/acl#key-permissions) for more information.
* `%W~<pattern>`: (Available in Redis 7.0 and later) Adds the specified write key pattern. This behaves similar to the regular key pattern but only grants permission to write to keys that match the given pattern. See [key permissions](https://redis.io/topics/acl#key-permissions) for more information.
* `%RW~<pattern>`: (Available in Redis 7.0 and later) Alias for `~<pattern>`.
* `allkeys`: Alias for `~*`, it allows the user to access all the keys.
* `resetkeys`: Removes all the key patterns from the list of key patterns the user can access.
* `&<pattern>`: (Available in Redis 6.2 and later) Adds the specified glob style pattern to the list of Pub/Sub channel patterns accessible by the user. You can add multiple channel patterns to the same user. Example: `&chatroom:*`
* `allchannels`: Alias for `&*`, it allows the user to access all Pub/Sub channels.
* `resetchannels`: Removes all channel patterns from the list of Pub/Sub channel patterns the user can access.
* `+<command>`: Adds the command to the list of commands the user can call. Can be used with `|` for allowing subcommands (e.g "+config|get").
* `+@<category>`: Adds all the commands in the specified category to the list of commands the user is able to execute. Example: `+@string` (adds all the string commands). For a list of categories, check the [`ACL CAT`](../acl-cat) command.
* `+<command>|first-arg`: Allows a specific first argument of an otherwise disabled command. It is only supported on commands with no sub-commands, and is not allowed as negative form like -SELECT|1, only additive starting with "+". This feature is deprecated and may be removed in the future.
* `allcommands`: Alias of `+@all`. Adds all the commands there are in the server, including *future commands* loaded via module, to be executed by this user.
* `-<command>`: Remove the command to the list of commands the user can call. Starting Redis 7.0, it can be used with `|` for blocking subcommands (e.g., "-config|set").
* `-@<category>`: Like `+@<category>` but removes all the commands in the category instead of adding them.
* `nocommands`: Alias for `-@all`. Removes all the commands, and the user is no longer able to execute anything.

 ### User management rules

 * `on`: Set the user as active, it will be possible to authenticate as this user using `AUTH <username> <password>`.
* `off`: Set user as not active, it will be impossible to log as this user. Please note that if a user gets disabled (set to off) after there are connections already authenticated with such a user, the connections will continue to work as expected. To also kill the old connections you can use [`CLIENT KILL`](../client-kill) with the user option. An alternative is to delete the user with [`ACL DELUSER`](../acl-deluser), that will result in all the connections authenticated as the deleted user to be disconnected.
* `nopass`: The user is set as a *no password* user. It means that it will be possible to authenticate as such user with any password. By default, the `default` special user is set as "nopass". The `nopass` rule will also reset all the configured passwords for the user.
* `>password`: Adds the specified clear text password as a hashed password in the list of the users passwords. Every user can have many active passwords, so that password rotation will be simpler. The specified password is not stored as clear text inside the server. Example: `>mypassword`.
* `#<hashedpassword>`: Adds the specified hashed password to the list of user passwords. A Redis hashed password is hashed with SHA256 and translated into a hexadecimal string. Example: `#c3ab8ff13720e8ad9047dd39466b3c8974e592c2fa383d4a3960714caef0c4f2`.
* `<password`: Like `>password` but removes the password instead of adding it.
* `!<hashedpassword>`: Like `#<hashedpassword>` but removes the password instead of adding it.
* `(<rule list>)`: (Available in Redis 7.0 and later) Creates a new selector to match rules against. Selectors are evaluated after the user permissions, and are evaluated according to the order they are defined. If a command matches either the user permissions or any selector, it is allowed. See [selectors](https://redis.io/docs/management/security/acl#selectors) for more information.
* `clearselectors`: (Available in Redis 7.0 and later) Deletes all of the selectors attached to the user.
* `reset`: Removes any capability from the user. They are set to off, without passwords, unable to execute any command, unable to access any key.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success.

 If the rules contain errors, the error is returned.

 Examples
--------

 
```
> ACL SETUSER alan allkeys +@string +@set -SADD >alanpassword
+OK

> ACL SETUSER antirez heeyyyy
(error) ERR Error in ACL SETUSER modifier 'heeyyyy': Syntax error

```
 History
-------

 * Starting with Redis version 6.2.0: Added Pub/Sub channel patterns.
* Starting with Redis version 7.0.0: Added selectors and key based permissions.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-setuser/>

BITOP
=====



```
BITOP
```
 Syntax 
```
BITOP <AND | OR | XOR | NOT> destkey key [key ...]
```
  Available since: 2.6.0 Time complexity: O(N) ACL categories:  `@write`, `@bitmap`, `@slow`,   Perform a bitwise operation between multiple keys (containing string values) and store the result in the destination key.

 The `BITOP` command supports four bitwise operations: **AND**, **OR**, **XOR** and **NOT**, thus the valid forms to call the command are:

 * `BITOP AND destkey srckey1 srckey2 srckey3 ... srckeyN`
* `BITOP OR destkey srckey1 srckey2 srckey3 ... srckeyN`
* `BITOP XOR destkey srckey1 srckey2 srckey3 ... srckeyN`
* `BITOP NOT destkey srckey`

 As you can see **NOT** is special as it only takes an input key, because it performs inversion of bits so it only makes sense as a unary operator.

 The result of the operation is always stored at `destkey`.

 Handling of strings with different lengths
------------------------------------------

 When an operation is performed between strings having different lengths, all the strings shorter than the longest string in the set are treated as if they were zero-padded up to the length of the longest string.

 The same holds true for non-existent keys, that are considered as a stream of zero bytes up to the length of the longest string.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The size of the string stored in the destination key, that is equal to the size of the longest input string.

 Examples
--------

 
```

SET key1 "foobar"
SET key2 "abcdef"
BITOP AND dest key1 key2
GET dest

```
 Pattern: real time metrics using bitmaps
----------------------------------------

 `BITOP` is a good complement to the pattern documented in the [`BITCOUNT`](../bitcount) command documentation. Different bitmaps can be combined in order to obtain a target bitmap where the population counting operation is performed.

 See the article called "[Fast easy realtime metrics using Redis bitmaps](http://blog.getspool.com/2011/11/29/fast-easy-realtime-metrics-using-redis-bitmaps)" for an interesting use cases.

 Performance considerations
--------------------------

 `BITOP` is a potentially slow command as it runs in O(N) time. Care should be taken when running it against long input strings.

 For real-time metrics and statistics involving large inputs a good approach is to use a replica (with replica-read-only option enabled) where the bit-wise operations are performed to avoid blocking the master instance.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bitop/>

BITPOS
======



```
BITPOS
```
 Syntax 
```
BITPOS key bit [start [end [BYTE | BIT]]]
```
  Available since: 2.8.7 Time complexity: O(N) ACL categories:  `@read`, `@bitmap`, `@slow`,   Return the position of the first bit set to 1 or 0 in a string.

 The position is returned, thinking of the string as an array of bits from left to right, where the first byte's most significant bit is at position 0, the second byte's most significant bit is at position 8, and so forth.

 The same bit position convention is followed by [`GETBIT`](../getbit) and [`SETBIT`](../setbit).

 By default, all the bytes contained in the string are examined. It is possible to look for bits only in a specified interval passing the additional arguments *start* and *end* (it is possible to just pass *start*, the operation will assume that the end is the last byte of the string. However there are semantic differences as explained later). By default, the range is interpreted as a range of bytes and not a range of bits, so `start=0` and `end=2` means to look at the first three bytes.

 You can use the optional `BIT` modifier to specify that the range should be interpreted as a range of bits. So `start=0` and `end=2` means to look at the first three bits.

 Note that bit positions are returned always as absolute values starting from bit zero even when *start* and *end* are used to specify a range.

 Like for the [`GETRANGE`](../getrange) command start and end can contain negative values in order to index bytes starting from the end of the string, where -1 is the last byte, -2 is the penultimate, and so forth. When `BIT` is specified, -1 is the last bit, -2 is the penultimate, and so forth.

 Non-existent keys are treated as empty strings.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The command returns the position of the first bit set to 1 or 0 according to the request.

 If we look for set bits (the bit argument is 1) and the string is empty or composed of just zero bytes, -1 is returned.

 If we look for clear bits (the bit argument is 0) and the string only contains bit set to 1, the function returns the first bit not part of the string on the right. So if the string is three bytes set to the value `0xff` the command `BITPOS key 0` will return 24, since up to bit 23 all the bits are 1.

 Basically, the function considers the right of the string as padded with zeros if you look for clear bits and specify no range or the *start* argument **only**.

 However, this behavior changes if you are looking for clear bits and specify a range with both **start** and **end**. If no clear bit is found in the specified range, the function returns -1 as the user specified a clear range and there are no 0 bits in that range.

 Examples
--------

 
```

SET mykey "\xff\xf0\x00"
BITPOS mykey 0
SET mykey "\x00\xff\xf0"
BITPOS mykey 1 0
BITPOS mykey 1 2
BITPOS mykey 1 2 -1 BYTE
BITPOS mykey 1 7 15 BIT
set mykey "\x00\x00\x00"
BITPOS mykey 1
BITPOS mykey 1 7 -3 BIT

```
 History
-------

 * Starting with Redis version 7.0.0: Added the `BYTE|BIT` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bitpos/>

ACL
===



```
ACL LOG
```
 Syntax 
```
ACL LOG [count | RESET]
```
  Available since: 6.0.0 Time complexity: O(N) with N being the number of entries shown. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command shows a list of recent ACL security events:

 1. Failures to authenticate their connections with [`AUTH`](../auth) or [`HELLO`](../hello).
2. Commands denied because against the current ACL rules.
3. Commands denied because accessing keys not allowed in the current ACL rules.

 The optional argument specifies how many entries to show. By default up to ten failures are returned. The special [`RESET`](../reset) argument clears the log. Entries are displayed starting from the most recent.

 Return
------

 When called to show security events:

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of ACL security events.

 When called with [`RESET`](../reset):

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the security log was cleared.

 Examples
--------

 
```
> AUTH someuser wrongpassword
(error) WRONGPASS invalid username-password pair
> ACL LOG 1
1)  1) "count"
    2) (integer) 1
    3) "reason"
    4) "auth"
    5) "context"
    6) "toplevel"
    7) "object"
    8) "AUTH"
    9) "username"
   10) "someuser"
   11) "age-seconds"
   12) "8.038"
   13) "client-info"
   14) "id=3 addr=127.0.0.1:57275 laddr=127.0.0.1:6379 fd=8 name= age=16 idle=0 flags=N db=0 sub=0 psub=0 ssub=0 multi=-1 qbuf=48 qbuf-free=16842 argv-mem=25 multi-mem=0 rbs=1024 rbp=0 obl=0 oll=0 omem=0 tot-mem=18737 events=r cmd=auth user=default redir=-1 resp=2"
   15) "entry-id"
   16) (integer) 0
   17) "timestamp-created"
   18) (integer) 1675361492408
   19) "timestamp-last-updated"
   20) (integer) 1675361492408

```

Each log entry is composed of the following fields:

 1. `count`: The number of security events detected within a 60 second period that are represented by this entry.
2. `reason`: The reason that the security events were logged. Either `command`, `key`, `channel`, or `auth`.
3. `context`: The context that the security events were detected in. Either `toplevel`, `multi`, `lua`, or `module`.
4. `object`: The resource that the user had insufficient permissions to access. `auth` when the reason is `auth`.
5. `username`: The username that executed the command that caused the security events or the username that had a failed authentication attempt.
6. `age-seconds`: Age of the log entry in seconds.
7. `client-info`: Displays the client info of a client which caused one of the security events.
8. `entry-id`: The sequence number of the entry (starting at 0) since the server process started. Can also be used to check if items were “lost”, if they fell between periods.
9. `timestamp-created`: A UNIX timestamp in `milliseconds` at the time the entry was first created.
10. `timestamp-last-updated`: A UNIX timestamp in `milliseconds` at the time the entry was last updated.

 History
-------

 * Starting with Redis version 7.2.0: Added entry ID, timestamp created, and timestamp last updated.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-log/>

ACL
===



```
ACL SAVE
```
 Syntax 
```
ACL SAVE
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of configured users. ACL categories:  `@admin`, `@slow`, `@dangerous`,   When Redis is configured to use an ACL file (with the `aclfile` configuration option), this command will save the currently defined ACLs from the server memory to the ACL file.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success.

 The command may fail with an error for several reasons: if the file cannot be written or if the server is not configured to use an external ACL file.

 Examples
--------

 
```
> ACL SAVE
+OK

> ACL SAVE
-ERR There was an error trying to save the ACLs. Please check the server logs for more information

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-save/>

BF.ADD
======



```
BF.ADD
```
 Syntax 
```
BF.ADD key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k), where k is the number of hash functions used by the last sub-filter  Creates an empty Bloom Filter with a single sub-filter for the initial capacity requested and with an upper bound `error_rate`. By default, the filter auto-scales by creating additional sub-filters when `capacity` is reached. The new sub-filter is created with size of the previous sub-filter multiplied by `expansion`.

 Though the filter can scale up by creating sub-filters, it is recommended to reserve the estimated required `capacity` since maintaining and querying sub-filters requires additional memory (each sub-filter uses an extra bits and hash function) and consume further CPU time than an equivalent filter that had the right capacity at creation time.

 The number of hash functions is `-log(error)/ln(2)^2`. The number of bits per item is `-log(error)/ln(2)` ≈ 1.44.

 * **1%** error rate requires 7 hash functions and 10.08 bits per item.
* **0.1%** error rate requires 10 hash functions and 14.4 bits per item.
* **0.01%** error rate requires 14 hash functions and 20.16 bits per item.

 ### Parameters:

 * **key**: The key under which the filter is found
* **error\_rate**: The desired probability for false positives. The rate is a decimal value between 0 and 1. For example, for a desired false positive rate of 0.1% (1 in 1000), error\_rate should be set to 0.001.
* **capacity**: The number of entries intended to be added to the filter. If your filter allows scaling, performance will begin to degrade after adding more items than this number. The actual degradation depends on how far the limit has been exceeded. Performance degrades linearly with the number of `sub-filters`.

 Optional parameters:

 * **NONSCALING**: Prevents the filter from creating additional sub-filters if initial capacity is reached. Non-scaling filters requires slightly less memory than their scaling counterparts. The filter returns an error when `capacity` is reached.
* **EXPANSION**: When `capacity` is reached, an additional sub-filter is created. The size of the new sub-filter is the size of the last sub-filter multiplied by `expansion`. If the number of elements to be stored in the filter is unknown, we recommend that you use an `expansion` of 2 or more to reduce the number of sub-filters. Otherwise, we recommend that you use an `expansion` of 1 to reduce memory consumption. The default expansion value is 2.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - "1" if such item did not exist in the filter, "0" if such item was likely added to the filter before (false positives are possible).

 Examples
--------

 
```
redis> BF.ADD bf item1
(integer) 0
redis> BF.ADD bf item_new
(integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bf.add/>

BLMOVE
======



```
BLMOVE
```
 Syntax 
```
BLMOVE source destination <LEFT | RIGHT> <LEFT | RIGHT> timeout
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@write`, `@list`, `@slow`, `@blocking`,   `BLMOVE` is the blocking variant of [`LMOVE`](../lmove). When `source` contains elements, this command behaves exactly like [`LMOVE`](../lmove). When used inside a [`MULTI`](../multi)/[`EXEC`](../exec) block, this command behaves exactly like [`LMOVE`](../lmove). When `source` is empty, Redis will block the connection until another client pushes to it or until `timeout` (a double value specifying the maximum number of seconds to block) is reached. A `timeout` of zero can be used to block indefinitely.

 This command comes in place of the now deprecated [`BRPOPLPUSH`](../brpoplpush). Doing `BLMOVE RIGHT LEFT` is equivalent.

 See [`LMOVE`](../lmove) for more information.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the element being popped from `source` and pushed to `destination`. If `timeout` is reached, a [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) is returned.

 Pattern: Reliable queue
-----------------------

 Please see the pattern description in the [`LMOVE`](../lmove) documentation.

 Pattern: Circular list
----------------------

 Please see the pattern description in the [`LMOVE`](../lmove) documentation.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/blmove/>

BLMPOP
======



```
BLMPOP
```
 Syntax 
```
BLMPOP timeout numkeys key [key ...] <LEFT | RIGHT> [COUNT count]
```
  Available since: 7.0.0 Time complexity: O(N+M) where N is the number of provided keys and M is the number of elements returned. ACL categories:  `@write`, `@list`, `@slow`, `@blocking`,   `BLMPOP` is the blocking variant of [`LMPOP`](../lmpop).

 When any of the lists contains elements, this command behaves exactly like [`LMPOP`](../lmpop). When used inside a [`MULTI`](../multi)/[`EXEC`](../exec) block, this command behaves exactly like [`LMPOP`](../lmpop). When all lists are empty, Redis will block the connection until another client pushes to it or until the `timeout` (a double value specifying the maximum number of seconds to block) elapses. A `timeout` of zero can be used to block indefinitely.

 See [`LMPOP`](../lmpop) for more information.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` when no element could be popped, and timeout is reached.
* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/blmpop/>

AUTH
====



```
AUTH
```
 Syntax 
```
AUTH [username] password
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of passwords defined for the user ACL categories:  `@fast`, `@connection`,   The AUTH command authenticates the current connection in two cases:

 1. If the Redis server is password protected via the `requirepass` option.
2. A Redis 6.0 instance, or greater, is using the [Redis ACL system](https://redis.io/topics/acl).

 Redis versions prior of Redis 6 were only able to understand the one argument version of the command:

 
```
AUTH <password>

```
 This form just authenticates against the password set with `requirepass`. In this configuration Redis will deny any command executed by the just connected clients, unless the connection gets authenticated via `AUTH`.

 If the password provided via AUTH matches the password in the configuration file, the server replies with the `OK` status code and starts accepting commands. Otherwise, an error is returned and the clients needs to try a new password.

 When Redis ACLs are used, the command should be given in an extended way:

 
```
AUTH <username> <password>

```
 In order to authenticate the current connection with one of the connections defined in the ACL list (see [`ACL SETUSER`](../acl-setuser)) and the official [ACL guide](https://redis.io/topics/acl) for more information.

 When ACLs are used, the single argument form of the command, where only the password is specified, assumes that the implicit username is "default".

 Security notice
---------------

 Because of the high performance nature of Redis, it is possible to try a lot of passwords in parallel in very short time, so make sure to generate a strong and very long password so that this attack is infeasible. A good way to generate strong passwords is via the [`ACL GENPASS`](../acl-genpass) command.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) or an error if the password, or username/password pair, is invalid.

 History
-------

 * Starting with Redis version 6.0.0: Added ACL style (username and password).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/auth/>

BRPOPLPUSH
==========



```
BRPOPLPUSH (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`BLMOVE`](../blmove) with the `RIGHT` and `LEFT` arguments when migrating or writing new code.

  Syntax 
```
BRPOPLPUSH source destination timeout
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@write`, `@list`, `@slow`, `@blocking`,   `BRPOPLPUSH` is the blocking variant of [`RPOPLPUSH`](../rpoplpush). When `source` contains elements, this command behaves exactly like [`RPOPLPUSH`](../rpoplpush). When used inside a [`MULTI`](../multi)/[`EXEC`](../exec) block, this command behaves exactly like [`RPOPLPUSH`](../rpoplpush). When `source` is empty, Redis will block the connection until another client pushes to it or until `timeout` is reached. A `timeout` of zero can be used to block indefinitely.

 See [`RPOPLPUSH`](../rpoplpush) for more information.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the element being popped from `source` and pushed to `destination`. If `timeout` is reached, a [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) is returned.

 Pattern: Reliable queue
-----------------------

 Please see the pattern description in the [`RPOPLPUSH`](../rpoplpush) documentation.

 Pattern: Circular list
----------------------

 Please see the pattern description in the [`RPOPLPUSH`](../rpoplpush) documentation.

 History
-------

 * Starting with Redis version 6.0.0: `timeout` is interpreted as a double instead of an integer.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/brpoplpush/>

BITFIELD
========



```
BITFIELD
```
 Syntax 
```
BITFIELD key [GET encoding offset | [OVERFLOW <WRAP | SAT | FAIL>]
  <SET encoding offset value | INCRBY encoding offset increment>
  [GET encoding offset | [OVERFLOW <WRAP | SAT | FAIL>]
  <SET encoding offset value | INCRBY encoding offset increment>
  ...]]
```
  Available since: 3.2.0 Time complexity: O(1) for each subcommand specified ACL categories:  `@write`, `@bitmap`, `@slow`,   The command treats a Redis string as an array of bits, and is capable of addressing specific integer fields of varying bit widths and arbitrary non (necessary) aligned offset. In practical terms using this command you can set, for example, a signed 5 bits integer at bit offset 1234 to a specific value, retrieve a 31 bit unsigned integer from offset 4567. Similarly the command handles increments and decrements of the specified integers, providing guaranteed and well specified overflow and underflow behavior that the user can configure.

 `BITFIELD` is able to operate with multiple bit fields in the same command call. It takes a list of operations to perform, and returns an array of replies, where each array matches the corresponding operation in the list of arguments.

 For example the following command increments a 5 bit signed integer at bit offset 100, and gets the value of the 4 bit unsigned integer at bit offset 0:

 
```
> BITFIELD mykey INCRBY i5 100 1 GET u4 0
1) (integer) 1
2) (integer) 0

```
 Note that:

 1. Addressing with `GET` bits outside the current string length (including the case the key does not exist at all), results in the operation to be performed like the missing part all consists of bits set to 0.
2. Addressing with `SET` or `INCRBY` bits outside the current string length will enlarge the string, zero-padding it, as needed, for the minimal length needed, according to the most far bit touched.

 Supported subcommands and integer encoding
------------------------------------------

 The following is the list of supported commands.

 * **GET** `<encoding>` `<offset>` -- Returns the specified bit field.
* **SET** `<encoding>` `<offset>` `<value>` -- Set the specified bit field and returns its old value.
* **INCRBY** `<encoding>` `<offset>` `<increment>` -- Increments or decrements (if a negative increment is given) the specified bit field and returns the new value.

 There is another subcommand that only changes the behavior of successive `INCRBY` and `SET` subcommands calls by setting the overflow behavior:

 * **OVERFLOW** `[WRAP|SAT|FAIL]`

 Where an integer encoding is expected, it can be composed by prefixing with `i` for signed integers and `u` for unsigned integers with the number of bits of our integer encoding. So for example `u8` is an unsigned integer of 8 bits and `i16` is a signed integer of 16 bits.

 The supported encodings are up to 64 bits for signed integers, and up to 63 bits for unsigned integers. This limitation with unsigned integers is due to the fact that currently the Redis protocol is unable to return 64 bit unsigned integers as replies.

 Bits and positional offsets
---------------------------

 There are two ways in order to specify offsets in the bitfield command. If a number without any prefix is specified, it is used just as a zero based bit offset inside the string.

 However if the offset is prefixed with a `#` character, the specified offset is multiplied by the integer encoding's width, so for example:

 
```
BITFIELD mystring SET i8 #0 100 SET i8 #1 200

```
 Will set the first i8 integer at offset 0 and the second at offset 8. This way you don't have to do the math yourself inside your client if what you want is a plain array of integers of a given size.

 Overflow control
----------------

 Using the `OVERFLOW` command the user is able to fine-tune the behavior of the increment or decrement overflow (or underflow) by specifying one of the following behaviors:

 * **WRAP**: wrap around, both with signed and unsigned integers. In the case of unsigned integers, wrapping is like performing the operation modulo the maximum value the integer can contain (the C standard behavior). With signed integers instead wrapping means that overflows restart towards the most negative value and underflows towards the most positive ones, so for example if an `i8` integer is set to the value 127, incrementing it by 1 will yield `-128`.
* **SAT**: uses saturation arithmetic, that is, on underflows the value is set to the minimum integer value, and on overflows to the maximum integer value. For example incrementing an `i8` integer starting from value 120 with an increment of 10, will result into the value 127, and further increments will always keep the value at 127. The same happens on underflows, but towards the value is blocked at the most negative value.
* **FAIL**: in this mode no operation is performed on overflows or underflows detected. The corresponding return value is set to NULL to signal the condition to the caller.

 Note that each `OVERFLOW` statement only affects the `INCRBY` and `SET` commands that follow it in the list of subcommands, up to the next `OVERFLOW` statement.

 By default, **WRAP** is used if not otherwise specified.

 
```
> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) (integer) 1
2) (integer) 1
> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) (integer) 2
2) (integer) 2
> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) (integer) 3
2) (integer) 3
> BITFIELD mykey incrby u2 100 1 OVERFLOW SAT incrby u2 102 1
1) (integer) 0
2) (integer) 3

```
 Return value
------------

 The command returns an array with each entry being the corresponding result of the sub command given at the same position. `OVERFLOW` subcommands don't count as generating a reply.

 The following is an example of `OVERFLOW FAIL` returning NULL.

 
```
> BITFIELD mykey OVERFLOW FAIL incrby u2 102 1
1) (nil)

```
 Motivations
-----------

 The motivation for this command is that the ability to store many small integers as a single large bitmap (or segmented over a few keys to avoid having huge keys) is extremely memory efficient, and opens new use cases for Redis to be applied, especially in the field of real time analytics. This use cases are supported by the ability to specify the overflow in a controlled way.

 Fun fact: Reddit's 2017 April fools' project [r/place](https://reddit.com/r/place) was [built using the Redis BITFIELD command](https://redditblog.com/2017/04/13/how-we-built-rplace/) in order to take an in-memory representation of the collaborative canvas.

 Performance considerations
--------------------------

 Usually `BITFIELD` is a fast command, however note that addressing far bits of currently short strings will trigger an allocation that may be more costly than executing the command on bits already existing.

 Orders of bits
--------------

 The representation used by `BITFIELD` considers the bitmap as having the bit number 0 to be the most significant bit of the first byte, and so forth, so for example setting a 5 bits unsigned integer to value 23 at offset 7 into a bitmap previously set to all zeroes, will produce the following representation:

 
```
+--------+--------+
|00000001|01110000|
+--------+--------+

```
 When offsets and integer sizes are aligned to bytes boundaries, this is the same as big endian, however when such alignment does not exist, its important to also understand how the bits inside a byte are ordered.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bitfield/>

ACL
===



```
ACL GENPASS
```
 Syntax 
```
ACL GENPASS [bits]
```
  Available since: 6.0.0 Time complexity: O(1) ACL categories:  `@slow`,   ACL users need a solid password in order to authenticate to the server without security risks. Such password does not need to be remembered by humans, but only by computers, so it can be very long and strong (unguessable by an external attacker). The `ACL GENPASS` command generates a password starting from /dev/urandom if available, otherwise (in systems without /dev/urandom) it uses a weaker system that is likely still better than picking a weak password by hand.

 By default (if /dev/urandom is available) the password is strong and can be used for other uses in the context of a Redis application, for instance in order to create unique session identifiers or other kind of unguessable and not colliding IDs. The password generation is also very cheap because we don't really ask /dev/urandom for bits at every execution. At startup Redis creates a seed using /dev/urandom, then it will use SHA256 in counter mode, with HMAC-SHA256(seed,counter) as primitive, in order to create more random bytes as needed. This means that the application developer should be feel free to abuse `ACL GENPASS` to create as many secure pseudorandom strings as needed.

 The command output is a hexadecimal representation of a binary string. By default it emits 256 bits (so 64 hex characters). The user can provide an argument in form of number of bits to emit from 1 to 1024 to change the output length. Note that the number of bits provided is always rounded to the next multiple of 4. So for instance asking for just 1 bit password will result in 4 bits to be emitted, in the form of a single hex character.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): by default 64 bytes string representing 256 bits of pseudorandom data. Otherwise if an argument if needed, the output string length is the number of specified bits (rounded to the next multiple of 4) divided by 4.

 Examples
--------

 
```
> ACL GENPASS
"dd721260bfe1b3d9601e7fbab36de6d04e2e67b0ef1c53de59d45950db0dd3cc"

> ACL GENPASS 32
"355ef3dd"

> ACL GENPASS 5
"90"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-genpass/>

ACL
===



```
ACL USERS
```
 Syntax 
```
ACL USERS
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of configured users. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command shows a list of all the usernames of the currently configured users in the Redis ACL system.

 Return
------

 An array of strings.

 Examples
--------

 
```
> ACL USERS
1) "anna"
2) "antirez"
3) "default"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-users/>

ACL
===



```
ACL DRYRUN
```
 Syntax 
```
ACL DRYRUN username command [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: O(1). ACL categories:  `@admin`, `@slow`, `@dangerous`,   Simulate the execution of a given command by a given user. This command can be used to test the permissions of a given user without having to enable the user or cause the side effects of running the command.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success. [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): An error describing why the user can't execute the command.

 Examples
--------

 
```
> ACL SETUSER VIRGINIA +SET ~*
"OK"
> ACL DRYRUN VIRGINIA SET foo bar
"OK"
> ACL DRYRUN VIRGINIA GET foo bar
"This user has no permissions to run the 'GET' command"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-dryrun/>

ACL
===



```
ACL LOAD
```
 Syntax 
```
ACL LOAD
```
  Available since: 6.0.0 Time complexity: O(N). Where N is the number of configured users. ACL categories:  `@admin`, `@slow`, `@dangerous`,   When Redis is configured to use an ACL file (with the `aclfile` configuration option), this command will reload the ACLs from the file, replacing all the current ACL rules with the ones defined in the file. The command makes sure to have an *all or nothing* behavior, that is:

 * If every line in the file is valid, all the ACLs are loaded.
* If one or more line in the file is not valid, nothing is loaded, and the old ACL rules defined in the server memory continue to be used.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success.

 The command may fail with an error for several reasons: if the file is not readable, if there is an error inside the file, and in such case the error will be reported to the user in the error. Finally the command will fail if the server is not configured to use an external ACL file.

 Examples
--------

 
```
> ACL LOAD
+OK

> ACL LOAD
-ERR /tmp/foo:1: Unknown command or category name in ACL...

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/acl-load/>

BLPOP
=====



```
BLPOP
```
 Syntax 
```
BLPOP key [key ...] timeout
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of provided keys. ACL categories:  `@write`, `@list`, `@slow`, `@blocking`,   `BLPOP` is a blocking list pop primitive. It is the blocking version of [`LPOP`](../lpop) because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the head of the first list that is non-empty, with the given keys being checked in the order that they are given.

 Non-blocking behavior
---------------------

 When `BLPOP` is called, if at least one of the specified keys contains a non-empty list, an element is popped from the head of the list and returned to the caller together with the `key` it was popped from.

 Keys are checked in the order that they are given. Let's say that the key `list1` doesn't exist and `list2` and `list3` hold non-empty lists. Consider the following command:

 
```
BLPOP list1 list2 list3 0

```

`BLPOP` guarantees to return an element from the list stored at `list2` (since it is the first non empty list when checking `list1`, `list2` and `list3` in that order).

 Blocking behavior
-----------------

 If none of the specified keys exist, `BLPOP` blocks the connection until another client performs an [`LPUSH`](../lpush) or [`RPUSH`](../rpush) operation against one of the keys.

 Once new data is present on one of the lists, the client returns with the name of the key unblocking it and the popped value.

 When `BLPOP` causes a client to block and a non-zero timeout is specified, the client will unblock returning a `nil` multi-bulk value when the specified timeout has expired without a push operation against at least one of the specified keys.

 **The timeout argument is interpreted as a double value specifying the maximum number of seconds to block**. A timeout of zero can be used to block indefinitely.

 What key is served first? What client? What element? Priority ordering details.
-------------------------------------------------------------------------------

 * If the client tries to blocks for multiple keys, but at least one key contains elements, the returned key / element pair is the first key from left to right that has one or more elements. In this case the client is not blocked. So for instance `BLPOP key1 key2 key3 key4 0`, assuming that both `key2` and `key4` are non-empty, will always return an element from `key2`.
* If multiple clients are blocked for the same key, the first client to be served is the one that was waiting for more time (the first that blocked for the key). Once a client is unblocked it does not retain any priority, when it blocks again with the next call to `BLPOP` it will be served accordingly to the number of clients already blocked for the same key, that will all be served before it (from the first to the last that blocked).
* When a client is blocking for multiple keys at the same time, and elements are available at the same time in multiple keys (because of a transaction or a Lua script added elements to multiple lists), the client will be unblocked using the first key that received a push operation (assuming it has enough elements to serve our client, as there may be other clients as well waiting for this key). Basically after the execution of every command Redis will run a list of all the keys that received data AND that have at least a client blocked. The list is ordered by new element arrival time, from the first key that received data to the last. For every key processed, Redis will serve all the clients waiting for that key in a FIFO fashion, as long as there are elements in this key. When the key is empty or there are no longer clients waiting for this key, the next key that received new data in the previous command / transaction / script is processed, and so forth.

 Behavior of `BLPOP` when multiple elements are pushed inside a list.
--------------------------------------------------------------------

 There are times when a list can receive multiple elements in the context of the same conceptual command:

 * Variadic push operations such as `LPUSH mylist a b c`.
* After an [`EXEC`](../exec) of a [`MULTI`](../multi) block with multiple push operations against the same list.
* Executing a Lua Script with Redis 2.6 or newer.

 When multiple elements are pushed inside a list where there are clients blocking, the behavior is different for Redis 2.4 and Redis 2.6 or newer.

 For Redis 2.6 what happens is that the command performing multiple pushes is executed, and *only after* the execution of the command the blocked clients are served. Consider this sequence of commands.

 
```
Client A:   BLPOP foo 0
Client B:   LPUSH foo a b c

```
 If the above condition happens using a Redis 2.6 server or greater, Client **A** will be served with the `c` element, because after the [`LPUSH`](../lpush) command the list contains `c,b,a`, so taking an element from the left means to return `c`.

 Instead Redis 2.4 works in a different way: clients are served *in the context* of the push operation, so as long as `LPUSH foo a b c` starts pushing the first element to the list, it will be delivered to the Client **A**, that will receive `a` (the first element pushed).

 The behavior of Redis 2.4 creates a lot of problems when replicating or persisting data into the AOF file, so the much more generic and semantically simpler behavior was introduced into Redis 2.6 to prevent problems.

 Note that for the same reason a Lua script or a `MULTI/EXEC` block may push elements into a list and afterward **delete the list**. In this case the blocked clients will not be served at all and will continue to be blocked as long as no data is present on the list after the execution of a single command, transaction, or script.

 
`BLPOP` inside a `MULTI` / `EXEC` transaction
----------------------------------------------

 `BLPOP` can be used with pipelining (sending multiple commands and reading the replies in batch), however this setup makes sense almost solely when it is the last command of the pipeline.

 Using `BLPOP` inside a [`MULTI`](../multi) / [`EXEC`](../exec) block does not make a lot of sense as it would require blocking the entire server in order to execute the block atomically, which in turn does not allow other clients to perform a push operation. For this reason the behavior of `BLPOP` inside [`MULTI`](../multi) / [`EXEC`](../exec) when the list is empty is to return a `nil` multi-bulk reply, which is the same thing that happens when the timeout is reached.

 If you like science fiction, think of time flowing at infinite speed inside a [`MULTI`](../multi) / [`EXEC`](../exec) block...

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` multi-bulk when no element could be popped and the timeout expired.
* A two-element multi-bulk with the first element being the name of the key where an element was popped and the second element being the value of the popped element.

 Examples
--------

 
```
redis> DEL list1 list2
(integer) 0
redis> RPUSH list1 a b c
(integer) 3
redis> BLPOP list1 list2 0
1) "list1"
2) "a"

```

Reliable queues
---------------

 When `BLPOP` returns an element to the client, it also removes the element from the list. This means that the element only exists in the context of the client: if the client crashes while processing the returned element, it is lost forever.

 This can be a problem with some application where we want a more reliable messaging system. When this is the case, please check the [`BRPOPLPUSH`](../brpoplpush) command, that is a variant of `BLPOP` that adds the returned element to a target list before returning it to the client.

 Pattern: Event notification
---------------------------

 Using blocking list operations it is possible to mount different blocking primitives. For instance for some application you may need to block waiting for elements into a Redis Set, so that as far as a new element is added to the Set, it is possible to retrieve it without resort to polling. This would require a blocking version of [`SPOP`](../spop) that is not available, but using blocking list operations we can easily accomplish this task.

 The consumer will do:

 
```
LOOP forever
    WHILE SPOP(key) returns elements
        ... process elements ...
    END
    BRPOP helper_key
END

```

While in the producer side we'll use simply:

 
```
MULTI
SADD key element
LPUSH helper_key x
EXEC

```
 History
-------

 * Starting with Redis version 6.0.0: `timeout` is interpreted as a double instead of an integer.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/blpop/>

BRPOP
=====



```
BRPOP
```
 Syntax 
```
BRPOP key [key ...] timeout
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of provided keys. ACL categories:  `@write`, `@list`, `@slow`, `@blocking`,   `BRPOP` is a blocking list pop primitive. It is the blocking version of [`RPOP`](../rpop) because it blocks the connection when there are no elements to pop from any of the given lists. An element is popped from the tail of the first list that is non-empty, with the given keys being checked in the order that they are given.

 See the [BLPOP documentation](../blpop) for the exact semantics, since `BRPOP` is identical to [`BLPOP`](../blpop) with the only difference being that it pops elements from the tail of a list instead of popping from the head.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` multi-bulk when no element could be popped and the timeout expired.
* A two-element multi-bulk with the first element being the name of the key where an element was popped and the second element being the value of the popped element.

 Examples
--------

 
```
redis> DEL list1 list2
(integer) 0
redis> RPUSH list1 a b c
(integer) 3
redis> BRPOP list1 list2 0
1) "list1"
2) "c"

```
 History
-------

 * Starting with Redis version 6.0.0: `timeout` is interpreted as a double instead of an integer.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/brpop/>

CF.ADDNX
========



```
CF.ADDNX
```
 Syntax 
```
CF.ADDNX key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k + i), where k is the number of sub-filters and i is maxIterations  Adds an item to a cuckoo filter if the item did not exist previously. See documentation on [`CF.ADD`](../cf.add) for more information on this command.

 This command is equivalent to a [`CF.EXISTS`](../cf.exists) + [`CF.ADD`](../cf.add) command. It does not insert an element into the filter if its fingerprint already exists in order to use the available capacity more efficiently. However, deleting elements can introduce **false negative** error rate!

 Note that this command is slower than [`CF.ADD`](../cf.add) because it first checks whether the item exists.

 ### Parameters

 * **key**: The name of the filter
* **item**: The item to add

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - where "1" means the item has been added to the filter, and "0" mean, the item already existed.

 Examples
--------

 
```
redis> CF.ADDNX cf item1
(integer) 0
redis> CF.ADDNX cf item_new
(integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.addnx/>

CF.LOADCHUNK
============



```
CF.LOADCHUNK
```
 Syntax 
```
CF.LOADCHUNK key iterator data
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n), where n is the capacity  Restores a filter previously saved using `SCANDUMP`. See the `SCANDUMP` command for example usage.

 This command overwrites any cuckoo filter stored under `key`. Make sure that the cuckoo filter is not be modified between invocations.

 ### Parameters

 * **key**: Name of the key to restore
* **iter**: Iterator value associated with `data` (returned by `SCANDUMP`)
* **data**: Current data chunk (returned by `SCANDUMP`)

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 See BF.SCANDUMP for an example.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.loadchunk/>

CF.ADD
======



```
CF.ADD
```
 Syntax 
```
CF.ADD key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k + i), where k is the number of sub-filters and i is maxIterations  Adds an item to the cuckoo filter, creating the filter if it does not exist.

 Cuckoo filters can contain the same item multiple times, and consider each insert as separate. You can use [`CF.ADDNX`](../cf.addnx) to only add the item if it does not exist yet. Keep in mind that deleting an element inserted using [`CF.ADDNX`](../cf.addnx) may cause false-negative errors.

 ### Parameters

 * **key**: The name of the filter
* **item**: The item to add

 ### Complexity

 O(n + i), where n is the number of `sub-filters` and i is `maxIterations`. Adding items requires up to 2 memory accesses per `sub-filter`. But as the filter fills up, both locations for an item might be full. The filter attempts to `Cuckoo` swap items up to `maxIterations` times.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - "1" if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 
```
redis> CF.ADD cf item
(integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.add/>

CF.INSERTNX
===========



```
CF.INSERTNX
```
 Syntax 
```
CF.INSERTNX key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n \* (k + i)), where n is the number of items, k is the number of sub-filters and i is maxIterations  CF.INSERT
---------

 CF.INSERTNX
-----------

 Note: `CF.INSERTNX` is an advanced command that can have unintended impact if used incorrectly.

 
```
CF.INSERT {key} [CAPACITY {capacity}] [NOCREATE] ITEMS {item ...}
CF.INSERTNX {key} [CAPACITY {capacity}] [NOCREATE] ITEMS {item ...}

```

### Description

 Adds one or more items to a cuckoo filter, allowing the filter to be created with a custom capacity if it does not exist yet.

 This command is equivalent to a [`CF.EXISTS`](../cf.exists) + [`CF.ADD`](../cf.add) command. It does not insert an element into the filter if its fingerprint already exists and therefore better utilizes the available capacity. However, if you delete elements it might introduce **false negative** error rate!

 These commands offers more flexibility over the `ADD` and `ADDNX` commands, at the cost of more verbosity.

 ### Parameters

 * **key**: The name of the filter
* **capacity**: Specifies the desired capacity of the new filter, if this filter does not exist yet. If the filter already exists, then this parameter is ignored. If the filter does not exist yet and this parameter is *not* specified, then the filter is created with the module-level default capacity which is 1024. See [`CF.RESERVE`](../cf.reserve) for more information on cuckoo filter capacities.
* **NOCREATE**: If specified, prevents automatic filter creation if the filter does not exist. Instead, an error is returned if the filter does not already exist. This option is mutually exclusive with `CAPACITY`.
* **item**: One or more items to add. The `ITEMS` keyword must precede the list of items to add.

 ### Complexity

 O(n + i), where n is the number of `sub-filters` and i is `maxIterations`. Adding items requires up to 2 memory accesses per `sub-filter`. But as the filter fills up, both locations for an item might be full. The filter attempts to `Cuckoo` swap items up to `maxIterations` times.

 ### Returns

 An array of booleans (as integers) corresponding to the items specified. Possible values for each element are:

 * `> 0` if the item was successfully inserted
* `0` if the item already existed *and* `INSERTNX` is used.
* `<0` if an error occurred

 Note that for [`CF.INSERT`](../cf.insert), the return value is always be an array of `>0` values, unless an error occurs.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - where "1" means the item has been added to the filter, and "0" mean, the item already existed. [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) when filter parameters are erroneous

 Examples
--------

 
```
redis> CF.INSERTNX cf CAPACITY 1000 ITEMS item1 item2 
1) (integer) 1
2) (integer) 1

```


```
redis> CF.INSERTNX cf CAPACITY 1000 ITEMS item1 item2 item3
1) (integer) 0
2) (integer) 0
3) (integer) 1

```


```
redis> CF.INSERTNX cf_new CAPACITY 1000 NOCREATE ITEMS item1 item2 
(error) ERR not found

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.insertnx/>

CLIENT
======



```
CLIENT CACHING
```
 Syntax 
```
CLIENT CACHING <YES | NO>
```
  Available since: 6.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   This command controls the tracking of the keys in the next command executed by the connection, when tracking is enabled in `OPTIN` or `OPTOUT` mode. Please check the [client side caching documentation](https://redis.io/topics/client-side-caching) for background information.

 When tracking is enabled Redis, using the [`CLIENT TRACKING`](../client-tracking) command, it is possible to specify the `OPTIN` or `OPTOUT` options, so that keys in read only commands are not automatically remembered by the server to be invalidated later. When we are in `OPTIN` mode, we can enable the tracking of the keys in the next command by calling `CLIENT CACHING yes` immediately before it. Similarly when we are in `OPTOUT` mode, and keys are normally tracked, we can avoid the keys in the next command to be tracked using `CLIENT CACHING no`.

 Basically the command sets a state in the connection, that is valid only for the next command execution, that will modify the behavior of client tracking.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` or an error if the argument is not yes or no.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-caching/>

CF.EXISTS
=========



```
CF.EXISTS
```
 Syntax 
```
CF.EXISTS key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k), where k is the number of sub-filters  Check if an `item` exists in a Cuckoo Filter `key`

 ### Parameters

 * **key**: The name of the filter
* **item**: The item to check for

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - where "1" value means the item may exist in the filter, and a "0" value means it does not exist in the filter.

 Examples
--------

 
```
redis> CF.EXISTS cf item1
(integer) 1

```


```
redis> CF.EXISTS cf item_new
(integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.exists/>

CF.COUNT
========



```
CF.COUNT
```
 Syntax 
```
CF.COUNT key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k), where k is the number of sub-filters  Returns the number of times an item may be in the filter. Because this is a probabilistic data structure, this may not necessarily be accurate.

 If you just want to know if an item exists in the filter, use [`CF.EXISTS`](../cf.exists) because it is more efficient for that purpose.

 ### Parameters

 * **key**: The name of the filter
* **item**: The item to count

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - with the count of possible matching copies of the item in the filter.

 Examples
--------

 
```
redis> CF.COUNT cf item1
(integer) 42

```


```
redis> CF.COUNT cf item_new
(integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.count/>

CF.SCANDUMP
===========



```
CF.SCANDUMP
```
 Syntax 
```
CF.SCANDUMP key iterator
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n), where n is the capacity  Begins an incremental save of the cuckoo filter. This is useful for large cuckoo filters which cannot fit into the normal [`DUMP`](../dump) and [`RESTORE`](../restore) model.

 The first time this command is called, the value of `iter` should be 0. This command returns successive `(iter, data)` pairs until `(0, NULL)` indicates completion.

 ### Parameters

 * **key**: Name of the filter
* **iter**: Iterator value. This is either 0, or the iterator from a previous invocation of this command

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) (*Iterator*) and [] (*Data*). The Iterator is passed as input to the next invocation of `SCANDUMP`. If *Iterator* is 0, then it means iteration has completed.

 The iterator-data pair should also be passed to `LOADCHUNK` when restoring the filter.

 @exmaples

 
```
redis> CF.RESERVE cf 8
OK
redis> CF.ADD cf item1
(integer) 1
redis> CF.SCANDUMP cf 0
1) (integer) 1
2) "\x01\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x02\x00\x14\x00\x01\x008\x9a\xe0\xd8\xc3\x7f\x00\x00"
redis> CF.SCANDUMP cf 1
1) (integer) 9
2) "\x00\x00\x00\x00\a\x00\x00\x00"
redis> CF.SCANDUMP cf 9
1) (integer) 0
2) (nil)
redis> FLUSHALL
OK
redis> CF.LOADCHUNK cf 1 "\x01\x00\x00\x00\x00\x00\x00\x00\x04\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x00\x01\x00\x00\x00\x00\x00\x00\x00\x02\x00\x14\x00\x01\x008\x9a\xe0\xd8\xc3\x7f\x00\x00"
OK
redis> CF.LOADCHUNK cf 9 "\x00\x00\x00\x00\a\x00\x00\x00"
OK
redis> CF.EXISTS cf item1
(integer) 1

```

python code:

 
```
chunks = []
iter = 0
while True:
    iter, data = CF.SCANDUMP(key, iter)
    if iter == 0:
        break
    else:
        chunks.append([iter, data])

# Load it back
for chunk in chunks:
    iter, data = chunk
    CF.LOADCHUNK(key, iter, data)

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.scandump/>

CLIENT
======



```
CLIENT ID
```
 Syntax 
```
CLIENT ID
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   The command just returns the ID of the current connection. Every connection ID has certain guarantees:

 1. It is never repeated, so if `CLIENT ID` returns the same number, the caller can be sure that the underlying client did not disconnect and reconnect the connection, but it is still the same connection.
2. The ID is monotonically incremental. If the ID of a connection is greater than the ID of another connection, it is guaranteed that the second connection was established with the server at a later time.

 This command is especially useful together with [`CLIENT UNBLOCK`](../client-unblock) which was introduced also in Redis 5 together with `CLIENT ID`. Check the [`CLIENT UNBLOCK`](../client-unblock) command page for a pattern involving the two commands.

 Examples
--------

 
```

CLIENT ID

```
 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The id of the client.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-id/>

CF.DEL
======



```
CF.DEL
```
 Syntax 
```
CF.DEL key item
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k), where k is the number of sub-filters  Deletes an item once from the filter. If the item exists only once, it will be removed from the filter. If the item was added multiple times, it will still be present.

  Warning Deleting elements that are not in the filter may delete a different item, resulting in false negatives.

  ### Parameters

 * **key**: The name of the filter
* **item**: The item to delete from the filter

 ### Complexity

 O(n), where n is the number of `sub-filters`. Both alternative locations are checked on all `sub-filters`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - where "1" means the item has been deleted from the filter, and "0" mean, the item was not found.

 Examples
--------

 
```
redis> CF.DEL cf item1
(integer) 1

```


```
redis> CF.DEL cf item_new
(integer) 0

```


```
redis> CF.DEL cf1 item_new
(error) Not found

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.del/>

BZPOPMAX
========



```
BZPOPMAX
```
 Syntax 
```
BZPOPMAX key [key ...] timeout
```
  Available since: 5.0.0 Time complexity: O(log(N)) with N being the number of elements in the sorted set. ACL categories:  `@write`, `@sortedset`, `@fast`, `@blocking`,   `BZPOPMAX` is the blocking variant of the sorted set [`ZPOPMAX`](../zpopmax) primitive.

 It is the blocking version because it blocks the connection when there are no members to pop from any of the given sorted sets. A member with the highest score is popped from first sorted set that is non-empty, with the given keys being checked in the order that they are given.

 The `timeout` argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

 See the [BZPOPMIN documentation](../bzpopmin) for the exact semantics, since `BZPOPMAX` is identical to [`BZPOPMIN`](../bzpopmin) with the only difference being that it pops members with the highest scores instead of popping the ones with the lowest scores.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` multi-bulk when no element could be popped and the timeout expired.
* A three-element multi-bulk with the first element being the name of the key where a member was popped, the second element is the popped member itself, and the third element is the score of the popped element.

 Examples
--------

 
```
redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMAX zset1 zset2 0
1) "zset1"
2) "c"
3) "2"

```
 History
-------

 * Starting with Redis version 6.0.0: `timeout` is interpreted as a double instead of an integer.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bzpopmax/>

CF.INFO
=======



```
CF.INFO
```
 Syntax 
```
CF.INFO key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Return information about `key`

 ### Parameters

 * **key**: Name of the key to restore

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information of the filter.

 @example

 
```
redis> CF.INFO cf
 1) Size
 2) (integer) 1080
 3) Number of buckets
 4) (integer) 512
 5) Number of filter
 6) (integer) 1
 7) Number of items inserted
 8) (integer) 0
 9) Number of items deleted
10) (integer) 0
11) Bucket size
12) (integer) 2
13) Expansion rate
14) (integer) 1
15) Max iteration
16) (integer) 20

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.info/>

CLIENT
======



```
CLIENT INFO
```
 Syntax 
```
CLIENT INFO
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   The command returns information and statistics about the current client connection in a mostly human readable format.

 The reply format is identical to that of [`CLIENT LIST`](../client-list), and the content consists only of information about the current client.

 Examples
--------

 
```

CLIENT INFO

```
 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): a unique string, as described at the [`CLIENT LIST`](../client-list) page, for the current client.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-info/>

BZPOPMIN
========



```
BZPOPMIN
```
 Syntax 
```
BZPOPMIN key [key ...] timeout
```
  Available since: 5.0.0 Time complexity: O(log(N)) with N being the number of elements in the sorted set. ACL categories:  `@write`, `@sortedset`, `@fast`, `@blocking`,   `BZPOPMIN` is the blocking variant of the sorted set [`ZPOPMIN`](../zpopmin) primitive.

 It is the blocking version because it blocks the connection when there are no members to pop from any of the given sorted sets. A member with the lowest score is popped from first sorted set that is non-empty, with the given keys being checked in the order that they are given.

 The `timeout` argument is interpreted as a double value specifying the maximum number of seconds to block. A timeout of zero can be used to block indefinitely.

 See the [BLPOP documentation](../blpop) for the exact semantics, since `BZPOPMIN` is identical to [`BLPOP`](../blpop) with the only difference being the data structure being popped from.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` multi-bulk when no element could be popped and the timeout expired.
* A three-element multi-bulk with the first element being the name of the key where a member was popped, the second element is the popped member itself, and the third element is the score of the popped element.

 Examples
--------

 
```
redis> DEL zset1 zset2
(integer) 0
redis> ZADD zset1 0 a 1 b 2 c
(integer) 3
redis> BZPOPMIN zset1 zset2 0
1) "zset1"
2) "a"
3) "0"

```
 History
-------

 * Starting with Redis version 6.0.0: `timeout` is interpreted as a double instead of an integer.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bzpopmin/>

CF.RESERVE
==========



```
CF.RESERVE
```
 Syntax 
```
CF.RESERVE key capacity [BUCKETSIZE bucketsize]
  [MAXITERATIONS maxiterations] [EXPANSION expansion]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Create a Cuckoo Filter as `key` with a single sub-filter for the initial amount of `capacity` for items. Because of how Cuckoo Filters work, the filter is likely to declare itself full before `capacity` is reached and therefore fill rate will likely never reach 100%. The fill rate can be improved by using a larger `bucketsize` at the cost of a higher error rate. When the filter self-declare itself `full`, it will auto-expand by generating additional sub-filters at the cost of reduced performance and increased error rate. The new sub-filter is created with size of the previous sub-filter multiplied by `expansion`. Like bucket size, additional sub-filters grow the error rate linearly. The size of the new sub-filter is the size of the last sub-filter multiplied by `expansion`.

 The minimal false positive error rate is 2/255 ≈ 0.78% when bucket size of 1 is used. Larger buckets increase the error rate linearly (for example, a bucket size of 3 yields a 2.35% error rate) but improve the fill rate of the filter.

 `maxiterations` dictates the number of attempts to find a slot for the incoming fingerprint. Once the filter gets full, high `maxIterations` value will slow down insertions.

 Unused capacity in prior sub-filters is automatically used when possible. The filter can grow up to 32 times.

 Parameters:
-----------

 * **key**: The key under which the filter is found.
* **capacity**: Estimated capacity for the filter. Capacity is rounded to the next `2^n` number. The filter will likely not fill up to 100% of it's capacity. Make sure to reserve extra capacity if you want to avoid expansions.

 Optional parameters:

 * **bucketsize**: Number of items in each bucket. A higher bucket size value improves the fill rate but also causes a higher error rate and slightly slower performance. The default value is 2.
* **maxiterations**: Number of attempts to swap items between buckets before declaring filter as full and creating an additional filter. A low value is better for performance and a higher number is better for filter fill rate. The default value is 20.
* **expansion**: When a new filter is created, its size is the size of the current filter multiplied by `expansion`. Expansion is rounded to the next `2^n` number. The default value is 1.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> CF.RESERVE cf 1000
OK

```


```
redis> CF.RESERVE cf 1000
(error) ERR item exists

```


```
redis> CF.RESERVE cf_params 1000 BUCKETSIZE 8 MAXITERATIONS 20 EXPANSION 2
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.reserve/>

CF.MEXISTS
==========



```
CF.MEXISTS
```
 Syntax 
```
CF.MEXISTS key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k \* n), where k is the number of sub-filters and n is the number of items  Check if one or more `items` exists in a Cuckoo Filter `key`

 ### Parameters

 * **key**: The name of the filter
* **items**: The item to check for

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - for each item where "1" value means the corresponding item may exist in the filter, and a "0" value means it does not exist in the filter.

 Examples
--------

 
```
redis> CF.MEXISTS cf item1 item_new
1) (integer) 1
2) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.mexists/>

CF.INSERT
=========



```
CF.INSERT
```
 Syntax 
```
CF.INSERT key [CAPACITY capacity] [NOCREATE] ITEMS item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 1.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n \* (k + i)), where n is the number of items, k is the number of sub-filters and i is maxIterations  Adds one or more items to a cuckoo filter, allowing the filter to be created with a custom capacity if it does not exist yet.

 These commands offers more flexibility over the `ADD` command, at the cost of more verbosity.

 ### Parameters

 * **key**: The name of the filter
* **capacity**: Specifies the desired capacity of the new filter, if this filter does not exist yet. If the filter already exists, then this parameter is ignored. If the filter does not exist yet and this parameter is *not* specified, then the filter is created with the module-level default capacity which is 1024. See [`CF.RESERVE`](../cf.reserve) for more information on cuckoo filter capacities.
* **NOCREATE**: If specified, prevents automatic filter creation if the filter does not exist. Instead, an error is returned if the filter does not already exist. This option is mutually exclusive with `CAPACITY`.
* **item**: One or more items to add. The `ITEMS` keyword must precede the list of items to add.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - "1" if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> CF.INSERT cf CAPACITY 1000 ITEMS item1 item2 
1) (integer) 1
2) (integer) 1

```


```
redis> CF.INSERT cf1 CAPACITY 1000 NOCREATE ITEMS item1 item2 
(error) ERR not found

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cf.insert/>

CLIENT
======



```
CLIENT LIST
```
 Syntax 
```
CLIENT LIST [TYPE <NORMAL | MASTER | REPLICA | PUBSUB>]
  [ID client-id [client-id ...]]
```
  Available since: 2.4.0 Time complexity: O(N) where N is the number of client connections ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   The `CLIENT LIST` command returns information and statistics about the client connections server in a mostly human readable format.

 You can use one of the optional subcommands to filter the list. The `TYPE type` subcommand filters the list by clients' type, where *type* is one of `normal`, `master`, `replica`, and `pubsub`. Note that clients blocked by the [`MONITOR`](../monitor) command belong to the `normal` class.

 The `ID` filter only returns entries for clients with IDs matching the `client-id` arguments.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): a unique string, formatted as follows:

 * One client connection per line (separated by LF)
* Each line is composed of a succession of `property=value` fields separated by a space character.

 Here is the meaning of the fields:

 * `id`: a unique 64-bit client ID
* `addr`: address/port of the client
* `laddr`: address/port of local address client connected to (bind address)
* `fd`: file descriptor corresponding to the socket
* `name`: the name set by the client with [`CLIENT SETNAME`](../client-setname)
* `age`: total duration of the connection in seconds
* `idle`: idle time of the connection in seconds
* `flags`: client flags (see below)
* `db`: current database ID
* `sub`: number of channel subscriptions
* `psub`: number of pattern matching subscriptions
* `ssub`: number of shard channel subscriptions. Added in Redis 7.0.3
* `multi`: number of commands in a MULTI/EXEC context
* `qbuf`: query buffer length (0 means no query pending)
* `qbuf-free`: free space of the query buffer (0 means the buffer is full)
* `argv-mem`: incomplete arguments for the next command (already extracted from query buffer)
* `multi-mem`: memory is used up by buffered multi commands. Added in Redis 7.0
* `obl`: output buffer length
* `oll`: output list length (replies are queued in this list when the buffer is full)
* `omem`: output buffer memory usage
* `tot-mem`: total memory consumed by this client in its various buffers
* `events`: file descriptor events (see below)
* `cmd`: last command played
* `user`: the authenticated username of the client
* `redir`: client id of current client tracking redirection
* `resp`: client RESP protocol version. Added in Redis 7.0

 The client flags can be a combination of:

 
```
A: connection to be closed ASAP
b: the client is waiting in a blocking operation
c: connection to be closed after writing entire reply
d: a watched keys has been modified - EXEC will fail
i: the client is waiting for a VM I/O (deprecated)
M: the client is a master
N: no specific flag set
O: the client is a client in MONITOR mode
P: the client is a Pub/Sub subscriber
r: the client is in readonly mode against a cluster node
S: the client is a replica node connection to this instance
u: the client is unblocked
U: the client is connected via a Unix domain socket
x: the client is in a MULTI/EXEC context
t: the client enabled keys tracking in order to perform client side caching
R: the client tracking target client is invalid
B: the client enabled broadcast tracking mode 

```

The file descriptor events can be:

 
```
r: the client socket is readable (event loop)
w: the client socket is writable (event loop)

```

Notes
-----

 New fields are regularly added for debugging purpose. Some could be removed in the future. A version safe Redis client using this command should parse the output accordingly (i.e. handling gracefully missing fields, skipping unknown fields).

 History
-------

 * Starting with Redis version 2.8.12: Added unique client `id` field.
* Starting with Redis version 5.0.0: Added optional `TYPE` filter.
* Starting with Redis version 6.0.0: Added `user` field.
* Starting with Redis version 6.2.0: Added `argv-mem`, `tot-mem`, `laddr` and `redir` fields and the optional `ID` filter.
* Starting with Redis version 7.0.0: Added `resp`, `multi-mem`, `rbs` and `rbp` fields.
* Starting with Redis version 7.0.3: Added `ssub` field.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-list/>

CLIENT
======



```
CLIENT GETREDIR
```
 Syntax 
```
CLIENT GETREDIR
```
  Available since: 6.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   This command returns the client ID we are redirecting our [tracking](https://redis.io/topics/client-side-caching) notifications to. We set a client to redirect to when using [`CLIENT TRACKING`](../client-tracking) to enable tracking. However in order to avoid forcing client libraries implementations to remember the ID notifications are redirected to, this command exists in order to improve introspection and allow clients to check later if redirection is active and towards which client ID.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the ID of the client we are redirecting the notifications to. The command returns `-1` if client tracking is not enabled, or `0` if client tracking is enabled but we are not redirecting the notifications to any client.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-getredir/>

CLIENT
======



```
CLIENT KILL
```
 Syntax 
```
CLIENT KILL <ip:port | <[ID client-id] | [TYPE <NORMAL | MASTER |
  SLAVE | REPLICA | PUBSUB>] | [USER username] | [ADDR ip:port] |
  [LADDR ip:port] | [SKIPME <YES | NO>] [[ID client-id] |
  [TYPE <NORMAL | MASTER | SLAVE | REPLICA | PUBSUB>] |
  [USER username] | [ADDR ip:port] | [LADDR ip:port] | [SKIPME <YES
  | NO>] ...]>>
```
  Available since: 2.4.0 Time complexity: O(N) where N is the number of client connections ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   The `CLIENT KILL` command closes a given client connection. This command support two formats, the old format:

 
```
CLIENT KILL addr:port

```
 The `ip:port` should match a line returned by the [`CLIENT LIST`](../client-list) command (`addr` field).

 The new format:

 
```
CLIENT KILL <filter> <value> ... ... <filter> <value>

```
 With the new form it is possible to kill clients by different attributes instead of killing just by address. The following filters are available:

 * `CLIENT KILL ADDR ip:port`. This is exactly the same as the old three-arguments behavior.
* `CLIENT KILL LADDR ip:port`. Kill all clients connected to specified local (bind) address.
* `CLIENT KILL ID client-id`. Allows to kill a client by its unique `ID` field. Client `ID`'s are retrieved using the [`CLIENT LIST`](../client-list) command.
* `CLIENT KILL TYPE type`, where *type* is one of `normal`, `master`, `replica` and `pubsub`. This closes the connections of **all the clients** in the specified class. Note that clients blocked into the [`MONITOR`](../monitor) command are considered to belong to the `normal` class.
* `CLIENT KILL USER username`. Closes all the connections that are authenticated with the specified [ACL](https://redis.io/topics/acl) username, however it returns an error if the username does not map to an existing ACL user.
* `CLIENT KILL SKIPME yes/no`. By default this option is set to `yes`, that is, the client calling the command will not get killed, however setting this option to `no` will have the effect of also killing the client calling the command.

 It is possible to provide multiple filters at the same time. The command will handle multiple filters via logical AND. For example:

 
```
CLIENT KILL addr 127.0.0.1:12345 type pubsub

```
 is valid and will kill only a pubsub client with the specified address. This format containing multiple filters is rarely useful currently.

 When the new form is used the command no longer returns `OK` or an error, but instead the number of killed clients, that may be zero.

 CLIENT KILL and Redis Sentinel
------------------------------

 Recent versions of Redis Sentinel (Redis 2.8.12 or greater) use CLIENT KILL in order to kill clients when an instance is reconfigured, in order to force clients to perform the handshake with one Sentinel again and update its configuration.

 Notes
-----

 Due to the single-threaded nature of Redis, it is not possible to kill a client connection while it is executing a command. From the client point of view, the connection can never be closed in the middle of the execution of a command. However, the client will notice the connection has been closed only when the next command is sent (and results in network error).

 Return
------

 When called with the three arguments format:

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the connection exists and has been closed

 When called with the filter / value format:

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of clients killed.

 History
-------

 * Starting with Redis version 2.8.12: Added new filter format.
* Starting with Redis version 2.8.12: `ID` option.
* Starting with Redis version 3.2.0: Added `master` type in for `TYPE` option.
* Starting with Redis version 5.0.0: Replaced `slave` `TYPE` with `replica`. `slave` still supported for backward compatibility.
* Starting with Redis version 6.2.0: `LADDR` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-kill/>

CLIENT
======



```
CLIENT GETNAME
```
 Syntax 
```
CLIENT GETNAME
```
  Available since: 2.6.9 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   The `CLIENT GETNAME` returns the name of the current connection as set by [`CLIENT SETNAME`](../client-setname). Since every new connection starts without an associated name, if no name was assigned a null bulk reply is returned.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): The connection name, or a null bulk reply if no name is set.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-getname/>

CLIENT
======



```
CLIENT SETNAME
```
 Syntax 
```
CLIENT SETNAME connection-name
```
  Available since: 2.6.9 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   The `CLIENT SETNAME` command assigns a name to the current connection.

 The assigned name is displayed in the output of [`CLIENT LIST`](../client-list) so that it is possible to identify the client that performed a given connection.

 For instance when Redis is used in order to implement a queue, producers and consumers of messages may want to set the name of the connection according to their role.

 There is no limit to the length of the name that can be assigned if not the usual limits of the Redis string type (512 MB). However it is not possible to use spaces in the connection name as this would violate the format of the [`CLIENT LIST`](../client-list) reply.

 It is possible to entirely remove the connection name setting it to the empty string, that is not a valid connection name since it serves to this specific purpose.

 The connection name can be inspected using [`CLIENT GETNAME`](../client-getname).

 Every new connection starts without an assigned name.

 Tip: setting names to connections is a good way to debug connection leaks due to bugs in the application using Redis.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the connection name was successfully set.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-setname/>

CLIENT
======



```
CLIENT NO-EVICT
```
 Syntax 
```
CLIENT NO-EVICT <ON | OFF>
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   The `CLIENT NO-EVICT` command sets the [client eviction](https://redis.io/topics/clients#client-eviction) mode for the current connection.

 When turned on and client eviction is configured, the current connection will be excluded from the client eviction process even if we're above the configured client eviction threshold.

 When turned off, the current client will be re-included in the pool of potential clients to be evicted (and evicted if needed).

 See [client eviction](https://redis.io/topics/clients#client-eviction) for more details.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-no-evict/>

CLUSTER
=======



```
CLUSTER DELSLOTS
```
 Syntax 
```
CLUSTER DELSLOTS slot [slot ...]
```
  Available since: 3.0.0 Time complexity: O(N) where N is the total number of hash slot arguments ACL categories:  `@admin`, `@slow`, `@dangerous`,   In Redis Cluster, each node keeps track of which master is serving a particular hash slot.

 The `CLUSTER DELSLOTS` command asks a particular Redis Cluster node to forget which master is serving the hash slots specified as arguments.

 In the context of a node that has received a `CLUSTER DELSLOTS` command and has consequently removed the associations for the passed hash slots, we say those hash slots are *unbound*. Note that the existence of unbound hash slots occurs naturally when a node has not been configured to handle them (something that can be done with the [`CLUSTER ADDSLOTS`](../cluster-addslots) command) and if it has not received any information about who owns those hash slots (something that it can learn from heartbeat or update messages).

 If a node with unbound hash slots receives a heartbeat packet from another node that claims to be the owner of some of those hash slots, the association is established instantly. Moreover, if a heartbeat or update message is received with a configuration epoch greater than the node's own, the association is re-established.

 However, note that:

 1. The command only works if all the specified slots are already associated with some node.
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, the node may go into *down* state because not all hash slots are covered.

 Example
-------

 The following command removes the association for slots 5000 and 5001 from the node receiving the command:

 
```
> CLUSTER DELSLOTS 5000 5001
OK

```
 Usage in Redis Cluster
----------------------

 This command only works in cluster mode and may be useful for debugging and in order to manually orchestrate a cluster configuration when a new cluster is created. It is currently not used by `redis-cli`, and mainly exists for API completeness.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-delslots/>

CLIENT
======



```
CLIENT PAUSE
```
 Syntax 
```
CLIENT PAUSE timeout [WRITE | ALL]
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   `CLIENT PAUSE` is a connections control command able to suspend all the Redis clients for the specified amount of time (in milliseconds).

 The command performs the following actions:

 * It stops processing all the pending commands from normal and pub/sub clients for the given mode. However interactions with replicas will continue normally. Note that clients are formally paused when they try to execute a command, so no work is taken on the server side for inactive clients.
* However it returns OK to the caller ASAP, so the `CLIENT PAUSE` command execution is not paused by itself.
* When the specified amount of time has elapsed, all the clients are unblocked: this will trigger the processing of all the commands accumulated in the query buffer of every client during the pause.

 Client pause currently supports two modes:

 * `ALL`: This is the default mode. All client commands are blocked.
* `WRITE`: Clients are only blocked if they attempt to execute a write command.

 For the `WRITE` mode, some commands have special behavior:

 * [`EVAL`](../eval)/[`EVALSHA`](../evalsha): Will block client for all scripts.
* [`PUBLISH`](../publish): Will block client.
* [`PFCOUNT`](../pfcount): Will block client.
* [`WAIT`](../wait): Acknowledgments will be delayed, so this command will appear blocked.

 This command is useful as it makes able to switch clients from a Redis instance to another one in a controlled way. For example during an instance upgrade the system administrator could do the following:

 * Pause the clients using `CLIENT PAUSE`
* Wait a few seconds to make sure the replicas processed the latest replication stream from the master.
* Turn one of the replicas into a master.
* Reconfigure clients to connect with the new master.

 Since Redis 6.2, the recommended mode for client pause is `WRITE`. This mode will stop all replication traffic, can be aborted with the [`CLIENT UNPAUSE`](../client-unpause) command, and allows reconfiguring the old master without risking accepting writes after the failover. This is also the mode used during cluster failover.

 For versions before 6.2, it is possible to send `CLIENT PAUSE` in a MULTI/EXEC block together with the `INFO replication` command in order to get the current master offset at the time the clients are blocked. This way it is possible to wait for a specific offset in the replica side in order to make sure all the replication stream was processed.

 Since Redis 3.2.10 / 4.0.0, this command also prevents keys to be evicted or expired during the time clients are paused. This way the dataset is guaranteed to be static not just from the point of view of clients not being able to write, but also from the point of view of internal operations.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The command returns OK or an error if the timeout is invalid.

 Behavior change history
-----------------------

 * `>= 3.2.0`: Client pause prevents client pause and key eviction as well.

 History
-------

 * Starting with Redis version 6.2.0: `CLIENT PAUSE WRITE` mode added along with the `mode` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-pause/>

CLIENT
======



```
CLIENT REPLY
```
 Syntax 
```
CLIENT REPLY <ON | OFF | SKIP>
```
  Available since: 3.2.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   Sometimes it can be useful for clients to completely disable replies from the Redis server. For example when the client sends fire and forget commands or performs a mass loading of data, or in caching contexts where new data is streamed constantly. In such contexts to use server time and bandwidth in order to send back replies to clients, which are going to be ignored, is considered wasteful.

 The `CLIENT REPLY` command controls whether the server will reply the client's commands. The following modes are available:

 * `ON`. This is the default mode in which the server returns a reply to every command.
* `OFF`. In this mode the server will not reply to client commands.
* `SKIP`. This mode skips the reply of command immediately after it.

 Return
------

 When called with either `OFF` or `SKIP` subcommands, no reply is made. When called with `ON`:

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-reply/>

CLIENT
======



```
CLIENT UNBLOCK
```
 Syntax 
```
CLIENT UNBLOCK client-id [TIMEOUT | ERROR]
```
  Available since: 5.0.0 Time complexity: O(log N) where N is the number of client connections ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   This command can unblock, from a different connection, a client blocked in a blocking operation, such as for instance [`BRPOP`](../brpop) or [`XREAD`](../xread) or [`WAIT`](../wait).

 By default the client is unblocked as if the timeout of the command was reached, however if an additional (and optional) argument is passed, it is possible to specify the unblocking behavior, that can be **TIMEOUT** (the default) or **ERROR**. If **ERROR** is specified, the behavior is to unblock the client returning as error the fact that the client was force-unblocked. Specifically the client will receive the following error:

 
```
-UNBLOCKED client unblocked via CLIENT UNBLOCK

```
 Note: of course as usually it is not guaranteed that the error text remains the same, however the error code will remain `-UNBLOCKED`.

 This command is useful especially when we are monitoring many keys with a limited number of connections. For instance we may want to monitor multiple streams with [`XREAD`](../xread) without using more than N connections. However at some point the consumer process is informed that there is one more stream key to monitor. In order to avoid using more connections, the best behavior would be to stop the blocking command from one of the connections in the pool, add the new key, and issue the blocking command again.

 To obtain this behavior the following pattern is used. The process uses an additional *control connection* in order to send the `CLIENT UNBLOCK` command if needed. In the meantime, before running the blocking operation on the other connections, the process runs [`CLIENT ID`](../client-id) in order to get the ID associated with that connection. When a new key should be added, or when a key should no longer be monitored, the relevant connection blocking command is aborted by sending `CLIENT UNBLOCK` in the control connection. The blocking command will return and can be finally reissued.

 This example shows the application in the context of Redis streams, however the pattern is a general one and can be applied to other cases.

 Examples
--------

 
```
Connection A (blocking connection):
> CLIENT ID
2934
> BRPOP key1 key2 key3 0
(client is blocked)

... Now we want to add a new key ...

Connection B (control connection):
> CLIENT UNBLOCK 2934
1

Connection A (blocking connection):
... BRPOP reply with timeout ...
NULL
> BRPOP key1 key2 key3 key4 0
(client is blocked again)

```

Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the client was unblocked successfully.
* `0` if the client wasn't unblocked.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-unblock/>

CLUSTER
=======



```
CLUSTER ADDSLOTS
```
 Syntax 
```
CLUSTER ADDSLOTS slot [slot ...]
```
  Available since: 3.0.0 Time complexity: O(N) where N is the total number of hash slot arguments ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command is useful in order to modify a node's view of the cluster configuration. Specifically it assigns a set of hash slots to the node receiving the command. If the command is successful, the node will map the specified hash slots to itself, and will start broadcasting the new configuration.

 However note that:

 1. The command only works if all the specified slots are, from the point of view of the node receiving the command, currently not assigned. A node will refuse to take ownership for slots that already belong to some other node (including itself).
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, if a slot among the ones specified as argument is set as `importing`, this state gets cleared once the node assigns the (previously unbound) slot to itself.

 Example
-------

 For example the following command assigns slots 1 2 3 to the node receiving the command:

 
```
> CLUSTER ADDSLOTS 1 2 3
OK

```
 However trying to execute it again results into an error since the slots are already assigned:

 
```
> CLUSTER ADDSLOTS 1 2 3
ERR Slot 1 is already busy

```
 Usage in Redis Cluster
----------------------

 This command only works in cluster mode and is useful in the following Redis Cluster operations:

 1. To create a new cluster ADDSLOTS is used in order to initially setup master nodes splitting the available hash slots among them.
2. In order to fix a broken cluster where certain slots are unassigned.

 Information about slots propagation and warnings
------------------------------------------------

 Note that once a node assigns a set of slots to itself, it will start propagating this information in heartbeat packet headers. However the other nodes will accept the information only if they have the slot as not already bound with another node, or if the configuration epoch of the node advertising the new hash slot, is greater than the node currently listed in the table.

 This means that this command should be used with care only by applications orchestrating Redis Cluster, like `redis-cli`, and the command if used out of the right context can leave the cluster in a wrong state or cause data loss.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-addslots/>

CLIENT
======



```
CLIENT TRACKINGINFO
```
 Syntax 
```
CLIENT TRACKINGINFO
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   The command returns information about the current client connection's use of the [server assisted client side caching](https://redis.io/topics/client-side-caching) feature.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of tracking information sections and their respective values, specifically:

 * **flags**: A list of tracking flags used by the connection. The flags and their meanings are as follows:
	+ `off`: The connection isn't using server assisted client side caching.
	+ `on`: Server assisted client side caching is enabled for the connection.
	+ `bcast`: The client uses broadcasting mode.
	+ `optin`: The client does not cache keys by default.
	+ `optout`: The client caches keys by default.
	+ `caching-yes`: The next command will cache keys (exists only together with `optin`).
	+ `caching-no`: The next command won't cache keys (exists only together with `optout`).
	+ `noloop`: The client isn't notified about keys modified by itself.
	+ `broken_redirect`: The client ID used for redirection isn't valid anymore.
* **redirect**: The client ID used for notifications redirection, or -1 when none.
* **prefixes**: A list of key prefixes for which notifications are sent to the client.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-trackinginfo/>

CLIENT
======



```
CLIENT TRACKING
```
 Syntax 
```
CLIENT TRACKING <ON | OFF> [REDIRECT client-id] [PREFIX prefix
  [PREFIX prefix ...]] [BCAST] [OPTIN] [OPTOUT] [NOLOOP]
```
  Available since: 6.0.0 Time complexity: O(1). Some options may introduce additional complexity. ACL categories:  `@slow`, `@connection`,   This command enables the tracking feature of the Redis server, that is used for [server assisted client side caching](https://redis.io/topics/client-side-caching).

 When tracking is enabled Redis remembers the keys that the connection requested, in order to send later invalidation messages when such keys are modified. Invalidation messages are sent in the same connection (only available when the RESP3 protocol is used) or redirected in a different connection (available also with RESP2 and Pub/Sub). A special *broadcasting* mode is available where clients participating in this protocol receive every notification just subscribing to given key prefixes, regardless of the keys that they requested. Given the complexity of the argument please refer to [the main client side caching documentation](https://redis.io/topics/client-side-caching) for the details. This manual page is only a reference for the options of this subcommand.

 In order to enable tracking, use:

 
```
CLIENT TRACKING on ... options ...

```
 The feature will remain active in the current connection for all its life, unless tracking is turned off with `CLIENT TRACKING off` at some point.

 The following are the list of options that modify the behavior of the command when enabling tracking:

 * `REDIRECT <id>`: send invalidation messages to the connection with the specified ID. The connection must exist. You can get the ID of a connection using [`CLIENT ID`](../client-id). If the connection we are redirecting to is terminated, when in RESP3 mode the connection with tracking enabled will receive `tracking-redir-broken` push messages in order to signal the condition.
* `BCAST`: enable tracking in broadcasting mode. In this mode invalidation messages are reported for all the prefixes specified, regardless of the keys requested by the connection. Instead when the broadcasting mode is not enabled, Redis will track which keys are fetched using read-only commands, and will report invalidation messages only for such keys.
* `PREFIX <prefix>`: for broadcasting, register a given key prefix, so that notifications will be provided only for keys starting with this string. This option can be given multiple times to register multiple prefixes. If broadcasting is enabled without this option, Redis will send notifications for every key. You can't delete a single prefix, but you can delete all prefixes by disabling and re-enabling tracking. Using this option adds the additional time complexity of O(N^2), where N is the total number of prefixes tracked.
* `OPTIN`: when broadcasting is NOT active, normally don't track keys in read only commands, unless they are called immediately after a `CLIENT CACHING yes` command.
* `OPTOUT`: when broadcasting is NOT active, normally track keys in read only commands, unless they are called immediately after a `CLIENT CACHING no` command.
* `NOLOOP`: don't send notifications about keys modified by this connection itself.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the connection was successfully put in tracking mode or if the tracking mode was successfully disabled. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-tracking/>

CLUSTER
=======



```
CLUSTER FORGET
```
 Syntax 
```
CLUSTER FORGET node-id
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command is used in order to remove a node, specified via its node ID, from the set of *known nodes* of the Redis Cluster node receiving the command. In other words the specified node is removed from the *nodes table* of the node receiving the command.

 Because when a given node is part of the cluster, all the other nodes participating in the cluster knows about it, in order for a node to be completely removed from a cluster, the `CLUSTER FORGET` command must be sent to all the remaining nodes, regardless of the fact they are masters or replicas.

 However the command cannot simply drop the node from the internal node table of the node receiving the command, it also implements a ban-list, not allowing the same node to be added again as a side effect of processing the *gossip section* of the heartbeat packets received from other nodes.

 Details on why the ban-list is needed
-------------------------------------

 In the following example we'll show why the command must not just remove a given node from the nodes table, but also prevent it for being re-inserted again for some time.

 Let's assume we have four nodes, A, B, C and D. In order to end with just a three nodes cluster A, B, C we may follow these steps:

 1. Reshard all the hash slots from D to nodes A, B, C.
2. D is now empty, but still listed in the nodes table of A, B and C.
3. We contact A, and send `CLUSTER FORGET D`.
4. B sends node A a heartbeat packet, where node D is listed.
5. A does no longer known node D (see step 3), so it starts a handshake with D.
6. D ends re-added in the nodes table of A.

 As you can see in this way removing a node is fragile, we need to send `CLUSTER FORGET` commands to all the nodes ASAP hoping there are no gossip sections processing in the meantime. Because of this problem the command implements a ban-list with an expire time for each entry.

 So what the command really does is:

 1. The specified node gets removed from the nodes table.
2. The node ID of the removed node gets added to the ban-list, for 1 minute.
3. The node will skip all the node IDs listed in the ban-list when processing gossip sections received in heartbeat packets from other nodes.

 This way we have a 60 second window to inform all the nodes in the cluster that we want to remove a node.

 Special conditions not allowing the command execution
-----------------------------------------------------

 The command does not succeed and returns an error in the following cases:

 1. The specified node ID is not found in the nodes table.
2. The node receiving the command is a replica, and the specified node ID identifies its current master.
3. The node ID identifies the same node we are sending the command to.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was executed successfully, otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-forget/>

CLUSTER
=======



```
CLUSTER BUMPEPOCH
```
 Syntax 
```
CLUSTER BUMPEPOCH
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Advances the cluster config epoch.

 The `CLUSTER BUMPEPOCH` command triggers an increment to the cluster's config epoch from the connected node. The epoch will be incremented if the node's config epoch is zero, or if it is less than the cluster's greatest epoch.

 **Note:** config epoch management is performed internally by the cluster, and relies on obtaining a consensus of nodes. The `CLUSTER BUMPEPOCH` attempts to increment the config epoch **WITHOUT** getting the consensus, so using it may violate the "last failover wins" rule. Use it with caution.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `BUMPED` if the epoch was incremented, or `STILL` if the node already has the greatest config epoch in the cluster.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-bumpepoch/>

BZMPOP
======



```
BZMPOP
```
 Syntax 
```
BZMPOP timeout numkeys key [key ...] <MIN | MAX> [COUNT count]
```
  Available since: 7.0.0 Time complexity: O(K) + O(M\*log(N)) where K is the number of provided keys, N being the number of elements in the sorted set, and M being the number of elements popped. ACL categories:  `@write`, `@sortedset`, `@slow`, `@blocking`,   `BZMPOP` is the blocking variant of [`ZMPOP`](../zmpop).

 When any of the sorted sets contains elements, this command behaves exactly like [`ZMPOP`](../zmpop). When used inside a [`MULTI`](../multi)/[`EXEC`](../exec) block, this command behaves exactly like [`ZMPOP`](../zmpop). When all sorted sets are empty, Redis will block the connection until another client adds members to one of the keys or until the `timeout` (a double value specifying the maximum number of seconds to block) elapses. A `timeout` of zero can be used to block indefinitely.

 See [`ZMPOP`](../zmpop) for more information.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` when no element could be popped.
* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of the popped elements. Every entry in the elements array is also an array that contains the member and its score.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/bzmpop/>

CLIENT
======



```
CLIENT UNPAUSE
```
 Syntax 
```
CLIENT UNPAUSE
```
  Available since: 6.2.0 Time complexity: O(N) Where N is the number of paused clients ACL categories:  `@admin`, `@slow`, `@dangerous`, `@connection`,   `CLIENT UNPAUSE` is used to resume command processing for all clients that were paused by [`CLIENT PAUSE`](../client-pause).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The command returns `OK`



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/client-unpause/>

CLUSTER
=======



```
CLUSTER FAILOVER
```
 Syntax 
```
CLUSTER FAILOVER [FORCE | TAKEOVER]
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command, that can only be sent to a Redis Cluster replica node, forces the replica to start a manual failover of its master instance.

 A manual failover is a special kind of failover that is usually executed when there are no actual failures, but we wish to swap the current master with one of its replicas (which is the node we send the command to), in a safe way, without any window for data loss. It works in the following way:

 1. The replica tells the master to stop processing queries from clients.
2. The master replies to the replica with the current *replication offset*.
3. The replica waits for the replication offset to match on its side, to make sure it processed all the data from the master before it continues.
4. The replica starts a failover, obtains a new configuration epoch from the majority of the masters, and broadcasts the new configuration.
5. The old master receives the configuration update: unblocks its clients and starts replying with redirection messages so that they'll continue the chat with the new master.

 This way clients are moved away from the old master to the new master atomically and only when the replica that is turning into the new master has processed all of the replication stream from the old master.

 FORCE option: manual failover when the master is down
-----------------------------------------------------

 The command behavior can be modified by two options: **FORCE** and **TAKEOVER**.

 If the **FORCE** option is given, the replica does not perform any handshake with the master, that may be not reachable, but instead just starts a failover ASAP starting from point 4. This is useful when we want to start a manual failover while the master is no longer reachable.

 However using **FORCE** we still need the majority of masters to be available in order to authorize the failover and generate a new configuration epoch for the replica that is going to become master.

 TAKEOVER option: manual failover without cluster consensus
----------------------------------------------------------

 There are situations where this is not enough, and we want a replica to failover without any agreement with the rest of the cluster. A real world use case for this is to mass promote replicas in a different data center to masters in order to perform a data center switch, while all the masters are down or partitioned away.

 The **TAKEOVER** option implies everything **FORCE** implies, but also does not uses any cluster authorization in order to failover. A replica receiving `CLUSTER FAILOVER TAKEOVER` will instead:

 1. Generate a new `configEpoch` unilaterally, just taking the current greatest epoch available and incrementing it if its local configuration epoch is not already the greatest.
2. Assign itself all the hash slots of its master, and propagate the new configuration to every node which is reachable ASAP, and eventually to every other node.

 Note that **TAKEOVER violates the last-failover-wins principle** of Redis Cluster, since the configuration epoch generated by the replica violates the normal generation of configuration epochs in several ways:

 1. There is no guarantee that it is actually the higher configuration epoch, since, for example, we can use the **TAKEOVER** option within a minority, nor any message exchange is performed to generate the new configuration epoch.
2. If we generate a configuration epoch which happens to collide with another instance, eventually our configuration epoch, or the one of another instance with our same epoch, will be moved away using the *configuration epoch collision resolution algorithm*.

 Because of this the **TAKEOVER** option should be used with care.

 Implementation details and notes
--------------------------------

 * `CLUSTER FAILOVER`, unless the **TAKEOVER** option is specified, does not execute a failover synchronously. It only *schedules* a manual failover, bypassing the failure detection stage.
* An `OK` reply is no guarantee that the failover will succeed.
* A replica can only be promoted to a master if it is known as a replica by a majority of the masters in the cluster. If the replica is a new node that has just been added to the cluster (for example after upgrading it), it may not yet be known to all the masters in the cluster. To check that the masters are aware of a new replica, you can send [`CLUSTER NODES`](../cluster-nodes) or [`CLUSTER REPLICAS`](../cluster-replicas) to each of the master nodes and check that it appears as a replica, before sending `CLUSTER FAILOVER` to the replica.
* To check that the failover has actually happened you can use [`ROLE`](../role), `INFO REPLICATION` (which indicates "role:master" after successful failover), or [`CLUSTER NODES`](../cluster-nodes) to verify that the state of the cluster has changed sometime after the command was sent.
* To check if the failover has failed, check the replica's log for "Manual failover timed out", which is logged if the replica has given up after a few seconds.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was accepted and a manual failover is going to be attempted. An error if the operation cannot be executed, for example if we are talking with a node which is already a master.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-failover/>

CLUSTER
=======



```
CLUSTER ADDSLOTSRANGE
```
 Syntax 
```
CLUSTER ADDSLOTSRANGE start-slot end-slot [start-slot end-slot ...]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the total number of the slots between the start slot and end slot arguments. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `CLUSTER ADDSLOTSRANGE` is similar to the [`CLUSTER ADDSLOTS`](../cluster-addslots) command in that they both assign hash slots to nodes.

 The difference between the two commands is that `ADDSLOTS` takes a list of slots to assign to the node, while `ADDSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to assign to the node.

 Example
-------

 To assign slots 1 2 3 4 5 to the node, the `ADDSLOTS` command is:

 
```
> CLUSTER ADDSLOTS 1 2 3 4 5
OK

```
 The same operation can be completed with the following `ADDSLOTSRANGE` command:

 
```
> CLUSTER ADDSLOTSRANGE 1 5
OK

```
 Usage in Redis Cluster
----------------------

 This command only works in cluster mode and is useful in the following Redis Cluster operations:

 1. To create a new cluster ADDSLOTSRANGE is used in order to initially setup master nodes splitting the available hash slots among them.
2. In order to fix a broken cluster where certain slots are unassigned.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-addslotsrange/>

CLUSTER
=======



```
CLUSTER COUNT-FAILURE-REPORTS
```
 Syntax 
```
CLUSTER COUNT-FAILURE-REPORTS node-id
```
  Available since: 3.0.0 Time complexity: O(N) where N is the number of failure reports ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command returns the number of *failure reports* for the specified node. Failure reports are the way Redis Cluster uses in order to promote a `PFAIL` state, that means a node is not reachable, to a `FAIL` state, that means that the majority of masters in the cluster agreed within a window of time that the node is not reachable.

 A few more details:

 * A node flags another node with `PFAIL` when the node is not reachable for a time greater than the configured *node timeout*, which is a fundamental configuration parameter of a Redis Cluster.
* Nodes in `PFAIL` state are provided in gossip sections of heartbeat packets.
* Every time a node processes gossip packets from other nodes, it creates (and refreshes the TTL if needed) **failure reports**, remembering that a given node said another given node is in `PFAIL` condition.
* Each failure report has a time to live of two times the *node timeout* time.
* If at a given time a node has another node flagged with `PFAIL`, and at the same time collected the majority of other master nodes *failure reports* about this node (including itself if it is a master), then it elevates the failure state of the node from `PFAIL` to `FAIL`, and broadcasts a message forcing all the nodes that can be reached to flag the node as `FAIL`.

 This command returns the number of failure reports for the current node which are currently not expired (so received within two times the *node timeout* time). The count does not include what the node we are asking this count believes about the node ID we pass as argument, the count *only* includes the failure reports the node received from other nodes.

 This command is mainly useful for debugging, when the failure detector of Redis Cluster is not operating as we believe it should.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of active failure reports for the node.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-count-failure-reports/>

CLUSTER
=======



```
CLUSTER DELSLOTSRANGE
```
 Syntax 
```
CLUSTER DELSLOTSRANGE start-slot end-slot [start-slot end-slot ...]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the total number of the slots between the start slot and end slot arguments. ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `CLUSTER DELSLOTSRANGE` command is similar to the [`CLUSTER DELSLOTS`](../cluster-delslots) command in that they both remove hash slots from the node. The difference is that [`CLUSTER DELSLOTS`](../cluster-delslots) takes a list of hash slots to remove from the node, while `CLUSTER DELSLOTSRANGE` takes a list of slot ranges (specified by start and end slots) to remove from the node.

 Example
-------

 To remove slots 1 2 3 4 5 from the node, the [`CLUSTER DELSLOTS`](../cluster-delslots) command is:

 
```
> CLUSTER DELSLOTS 1 2 3 4 5
OK

```
 The same operation can be completed with the following `CLUSTER DELSLOTSRANGE` command:

 
```
> CLUSTER DELSLOTSRANGE 1 5
OK

```
 However, note that:

 1. The command only works if all the specified slots are already associated with the node.
2. The command fails if the same slot is specified multiple times.
3. As a side effect of the command execution, the node may go into *down* state because not all hash slots are covered.

 Usage in Redis Cluster
----------------------

 This command only works in cluster mode and may be useful for debugging and in order to manually orchestrate a cluster configuration when a new cluster is created. It is currently not used by `redis-cli`, and mainly exists for API completeness.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-delslotsrange/>

CLUSTER
=======



```
CLUSTER GETKEYSINSLOT
```
 Syntax 
```
CLUSTER GETKEYSINSLOT slot count
```
  Available since: 3.0.0 Time complexity: O(N) where N is the number of requested keys ACL categories:  `@slow`,   The command returns an array of keys names stored in the contacted node and hashing to the specified hash slot. The maximum number of keys to return is specified via the `count` argument, so that it is possible for the user of this API to batch-processing keys.

 The main usage of this command is during rehashing of cluster slots from one node to another. The way the rehashing is performed is exposed in the Redis Cluster specification, or in a more simple to digest form, as an appendix of the [`CLUSTER SETSLOT`](../cluster-setslot) command documentation.

 
```
> CLUSTER GETKEYSINSLOT 7000 3
1) "key_39015"
2) "key_89793"
3) "key_92937"

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): From 0 to *count* key names in a Redis array reply.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-getkeysinslot/>

CLUSTER
=======



```
CLUSTER COUNTKEYSINSLOT
```
 Syntax 
```
CLUSTER COUNTKEYSINSLOT slot
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@slow`,   Returns the number of keys in the specified Redis Cluster hash slot. The command only queries the local data set, so contacting a node that is not serving the specified hash slot will always result in a count of zero being returned.

 
```
> CLUSTER COUNTKEYSINSLOT 7000
(integer) 50341

```

Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of keys in the specified hash slot, or an error if the hash slot is invalid.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-countkeysinslot/>

CLUSTER
=======



```
CLUSTER MYID
```
 Syntax 
```
CLUSTER MYID
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@slow`,   Returns the node's id.

 The `CLUSTER MYID` command returns the unique, auto-generated identifier that is associated with the connected cluster node.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): The node id.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-myid/>

CLUSTER
=======



```
CLUSTER KEYSLOT
```
 Syntax 
```
CLUSTER KEYSLOT key
```
  Available since: 3.0.0 Time complexity: O(N) where N is the number of bytes in the key ACL categories:  `@slow`,   Returns an integer identifying the hash slot the specified key hashes to. This command is mainly useful for debugging and testing, since it exposes via an API the underlying Redis implementation of the hashing algorithm. Example use cases for this command:

 1. Client libraries may use Redis in order to test their own hashing algorithm, generating random keys and hashing them with both their local implementation and using Redis `CLUSTER KEYSLOT` command, then checking if the result is the same.
2. Humans may use this command in order to check what is the hash slot, and then the associated Redis Cluster node, responsible for a given key.

 Example
-------

 
```
> CLUSTER KEYSLOT somekey
(integer) 11058
> CLUSTER KEYSLOT foo{hash_tag}
(integer) 2515
> CLUSTER KEYSLOT bar{hash_tag}
(integer) 2515

```

Note that the command implements the full hashing algorithm, including support for **hash tags**, that is the special property of Redis Cluster key hashing algorithm, of hashing just what is between `{` and `}` if such a pattern is found inside the key name, in order to force multiple keys to be handled by the same node.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The hash slot number.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-keyslot/>

CLUSTER
=======



```
CLUSTER LINKS
```
 Syntax 
```
CLUSTER LINKS
```
  Available since: 7.0.0 Time complexity: O(N) where N is the total number of Cluster nodes ACL categories:  `@slow`,   Each node in a Redis Cluster maintains a pair of long-lived TCP link with each peer in the cluster: One for sending outbound messages towards the peer and one for receiving inbound messages from the peer.

 `CLUSTER LINKS` outputs information of all such peer links as an array, where each array element is a map that contains attributes and their values for an individual link.

 Examples
--------

 The following is an example output:

 
```
> CLUSTER LINKS
1)  1) "direction"
    2) "to"
    3) "node"
    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
    5) "create-time"
    6) (integer) 1639442739375
    7) "events"
    8) "rw"
    9) "send-buffer-allocated"
   10) (integer) 4512
   11) "send-buffer-used"
   12) (integer) 0
2)  1) "direction"
    2) "from"
    3) "node"
    4) "8149d745fa551e40764fecaf7cab9dbdf6b659ae"
    5) "create-time"
    6) (integer) 1639442739411
    7) "events"
    8) "r"
    9) "send-buffer-allocated"
   10) (integer) 0
   11) "send-buffer-used"
   12) (integer) 0

```

Each map is composed of the following attributes of the corresponding cluster link and their values:

 1. `direction`: This link is established by the local node `to` the peer, or accepted by the local node `from` the peer.
2. `node`: The node id of the peer.
3. `create-time`: Creation time of the link. (In the case of a `to` link, this is the time when the TCP link is created by the local node, not the time when it is actually established.)
4. `events`: Events currently registered for the link. `r` means readable event, `w` means writable event.
5. `send-buffer-allocated`: Allocated size of the link's send buffer, which is used to buffer outgoing messages toward the peer.
6. `send-buffer-used`: Size of the portion of the link's send buffer that is currently holding data(messages).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): An array of maps where each map contains various attributes and their values of a cluster link.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-links/>

CLUSTER
=======



```
CLUSTER MEET
```
 Syntax 
```
CLUSTER MEET ip port [cluster-bus-port]
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   `CLUSTER MEET` is used in order to connect different Redis nodes with cluster support enabled, into a working cluster.

 The basic idea is that nodes by default don't trust each other, and are considered unknown, so that it is unlikely that different cluster nodes will mix into a single one because of system administration errors or network addresses modifications.

 So in order for a given node to accept another one into the list of nodes composing a Redis Cluster, there are only two ways:

 1. The system administrator sends a `CLUSTER MEET` command to force a node to meet another one.
2. An already known node sends a list of nodes in the gossip section that we are not aware of. If the receiving node trusts the sending node as a known node, it will process the gossip section and send a handshake to the nodes that are still not known.

 Note that Redis Cluster needs to form a full mesh (each node is connected with each other node), but in order to create a cluster, there is no need to send all the `CLUSTER MEET` commands needed to form the full mesh. What matter is to send enough `CLUSTER MEET` messages so that each node can reach each other node through a *chain of known nodes*. Thanks to the exchange of gossip information in heartbeat packets, the missing links will be created.

 So, if we link node A with node B via `CLUSTER MEET`, and B with C, A and C will find their ways to handshake and create a link.

 Another example: if we imagine a cluster formed of the following four nodes called A, B, C and D, we may send just the following set of commands to A:

 1. `CLUSTER MEET B-ip B-port`
2. `CLUSTER MEET C-ip C-port`
3. `CLUSTER MEET D-ip D-port`

 As a side effect of `A` knowing and being known by all the other nodes, it will send gossip sections in the heartbeat packets that will allow each other node to create a link with each other one, forming a full mesh in a matter of seconds, even if the cluster is large.

 Moreover `CLUSTER MEET` does not need to be reciprocal. If I send the command to A in order to join B, I don't need to also send it to B in order to join A.

 If the optional `cluster_bus_port` argument is not provided, the default of port + 10000 will be used.

 Implementation details: MEET and PING packets
---------------------------------------------

 When a given node receives a `CLUSTER MEET` message, the node specified in the command still does not know the node we sent the command to. So in order for the node to force the receiver to accept it as a trusted node, it sends a `MEET` packet instead of a [`PING`](../ping) packet. The two packets have exactly the same format, but the former forces the receiver to acknowledge the node as trusted.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. If the address or port specified are invalid an error is returned.

 History
-------

 * Starting with Redis version 4.0.0: Added the optional `cluster_bus_port` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-meet/>

CLUSTER
=======



```
CLUSTER INFO
```
 Syntax 
```
CLUSTER INFO
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@slow`,   `CLUSTER INFO` provides [`INFO`](../info) style information about Redis Cluster vital parameters. The following fields are always present in the reply:

 
```
cluster_state:ok
cluster_slots_assigned:16384
cluster_slots_ok:16384
cluster_slots_pfail:0
cluster_slots_fail:0
cluster_known_nodes:6
cluster_size:3
cluster_current_epoch:6
cluster_my_epoch:2
cluster_stats_messages_sent:1483972
cluster_stats_messages_received:1483968
total_cluster_links_buffer_limit_exceeded:0

```

* `cluster_state`: State is `ok` if the node is able to receive queries. `fail` if there is at least one hash slot which is unbound (no node associated), in error state (node serving it is flagged with FAIL flag), or if the majority of masters can't be reached by this node.
* `cluster_slots_assigned`: Number of slots which are associated to some node (not unbound). This number should be 16384 for the node to work properly, which means that each hash slot should be mapped to a node.
* `cluster_slots_ok`: Number of hash slots mapping to a node not in `FAIL` or `PFAIL` state.
* `cluster_slots_pfail`: Number of hash slots mapping to a node in `PFAIL` state. Note that those hash slots still work correctly, as long as the `PFAIL` state is not promoted to `FAIL` by the failure detection algorithm. `PFAIL` only means that we are currently not able to talk with the node, but may be just a transient error.
* `cluster_slots_fail`: Number of hash slots mapping to a node in `FAIL` state. If this number is not zero the node is not able to serve queries unless `cluster-require-full-coverage` is set to `no` in the configuration.
* `cluster_known_nodes`: The total number of known nodes in the cluster, including nodes in `HANDSHAKE` state that may not currently be proper members of the cluster.
* `cluster_size`: The number of master nodes serving at least one hash slot in the cluster.
* `cluster_current_epoch`: The local `Current Epoch` variable. This is used in order to create unique increasing version numbers during fail overs.
* `cluster_my_epoch`: The `Config Epoch` of the node we are talking with. This is the current configuration version assigned to this node.
* `cluster_stats_messages_sent`: Number of messages sent via the cluster node-to-node binary bus.
* `cluster_stats_messages_received`: Number of messages received via the cluster node-to-node binary bus.
* `total_cluster_links_buffer_limit_exceeded`: Accumulated count of cluster links freed due to exceeding the `cluster-link-sendbuf-limit` configuration.

 The following message-related fields may be included in the reply if the value is not 0: Each message type includes statistics on the number of messages sent and received. Here are the explanation of these fields:

 * `cluster_stats_messages_ping_sent` and `cluster_stats_messages_ping_received`: Cluster bus PING (not to be confused with the client command [`PING`](../ping)).
* `cluster_stats_messages_pong_sent` and `cluster_stats_messages_pong_received`: PONG (reply to PING).
* `cluster_stats_messages_meet_sent` and `cluster_stats_messages_meet_received`: Handshake message sent to a new node, either through gossip or [`CLUSTER MEET`](../cluster-meet).
* `cluster_stats_messages_fail_sent` and `cluster_stats_messages_fail_received`: Mark node xxx as failing.
* `cluster_stats_messages_publish_sent` and `cluster_stats_messages_publish_received`: Pub/Sub Publish propagation, see [Pubsub](https://redis.io/topics/pubsub#pubsub).
* `cluster_stats_messages_auth-req_sent` and `cluster_stats_messages_auth-req_received`: Replica initiated leader election to replace its master.
* `cluster_stats_messages_auth-ack_sent` and `cluster_stats_messages_auth-ack_received`: Message indicating a vote during leader election.
* `cluster_stats_messages_update_sent` and `cluster_stats_messages_update_received`: Another node slots configuration.
* `cluster_stats_messages_mfstart_sent` and `cluster_stats_messages_mfstart_received`: Pause clients for manual failover.
* `cluster_stats_messages_module_sent` and `cluster_stats_messages_module_received`: Module cluster API message.
* `cluster_stats_messages_publishshard_sent` and `cluster_stats_messages_publishshard_received`: Pub/Sub Publish shard propagation, see [Sharded Pubsub](https://redis.io/topics/pubsub#sharded-pubsub).

 More information about the Current Epoch and Config Epoch variables are available in the [Redis Cluster specification document](https://redis.io/topics/cluster-spec#cluster-current-epoch).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): A map between named fields and values in the form of `<field>:<value>` lines separated by newlines composed by the two bytes `CRLF`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-info/>

CLUSTER
=======



```
CLUSTER FLUSHSLOTS
```
 Syntax 
```
CLUSTER FLUSHSLOTS
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Deletes all slots from a node.

 The `CLUSTER FLUSHSLOTS` deletes all information about slots from the connected node. It can only be called when the database is empty.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-flushslots/>

CLUSTER
=======



```
CLUSTER NODES
```
 Syntax 
```
CLUSTER NODES
```
  Available since: 3.0.0 Time complexity: O(N) where N is the total number of Cluster nodes ACL categories:  `@slow`,   Each node in a Redis Cluster has its view of the current cluster configuration, given by the set of known nodes, the state of the connection we have with such nodes, their flags, properties and assigned slots, and so forth.

 `CLUSTER NODES` provides all this information, that is, the current cluster configuration of the node we are contacting, in a serialization format which happens to be exactly the same as the one used by Redis Cluster itself in order to store on disk the cluster state (however the on disk cluster state has a few additional info appended at the end).

 Note that normally clients willing to fetch the map between Cluster hash slots and node addresses should use [`CLUSTER SLOTS`](../cluster-slots) instead. `CLUSTER NODES`, that provides more information, should be used for administrative tasks, debugging, and configuration inspections. It is also used by `redis-cli` in order to manage a cluster.

 Serialization format
--------------------

 The output of the command is just a space-separated CSV string, where each line represents a node in the cluster. Starting from 7.2.0, the output of the command always contains a new auxiliary field called shard-id. The following is an example of output on Redis 7.2.0.

 
```
07c37dfeb235213a872192d90877d0cd55635b91 127.0.0.1:30004@31004,,shard-id=69bc080733d1355567173199cff4a6a039a2f024 slave e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 0 1426238317239 4 connected
67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 127.0.0.1:30002@31002,,shard-id=114f6674a35b84949fe567f5dfd41415ee776261 master - 0 1426238316232 2 connected 5461-10922
292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 127.0.0.1:30003@31003,,shard-id=fdb36c73e72dd027bc19811b7c219ef6e55c550e master - 0 1426238318243 3 connected 10923-16383
6ec23923021cf3ffec47632106199cb7f496ce01 127.0.0.1:30005@31005,,shard-id=114f6674a35b84949fe567f5dfd41415ee776261 slave 67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1 0 1426238316232 5 connected
824fe116063bc5fcf9f4ffd895bc17aee7731ac3 127.0.0.1:30006@31006,,shard-id=fdb36c73e72dd027bc19811b7c219ef6e55c550e slave 292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f 0 1426238317741 6 connected
e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca 127.0.0.1:30001@31001,,shard-id=69bc080733d1355567173199cff4a6a039a2f024 myself,master - 0 0 1 connected 0-5460

```

Each line is composed of the following fields:

 
```
<id> <ip:port@cport[,hostname[,auxiliary_field=value]*]> <flags> <master> <ping-sent> <pong-recv> <config-epoch> <link-state> <slot> <slot> ... <slot>

```

The meaning of each filed is the following:

 1. `id`: The node ID, a 40-character globally unique string generated when a node is created and never changed again (unless `CLUSTER RESET HARD` is used).
2. `ip:port@cport`: The node address that clients should contact to run queries.
3. `hostname`: A human readable string that can be configured via the `cluster-annouce-hostname` setting. The max length of the string is 256 characters, excluding the null terminator. The name can contain ASCII alphanumeric characters, '-', and '.' only.
4. `[,auxiliary_field=value]*`: A list of comma-separated key-value pairs that represent various node properties, such as `shard-id`. There is no intrinsic order among auxiliary fields. The auxiliary fields can appear at different position in the list from release to release. Both the key name and value can contain ASCII alphanumeric characters and the characters in `!#$%&()*+-.:;<>?@[]^_{|}~` only. Auxiliary fields are explained in detail in the section below.
5. `flags`: A list of comma separated flags: `myself`, `master`, `slave`, `fail?`, `fail`, `handshake`, `noaddr`, `nofailover`, `noflags`. Flags are explained below.
6. `master`: If the node is a replica, and the primary is known, the primary node ID, otherwise the "-" character.
7. `ping-sent`: Unix time at which the currently active ping was sent, or zero if there are no pending pings, in milliseconds.
8. `pong-recv`: Unix time the last pong was received, in milliseconds.
9. `config-epoch`: The configuration epoch (or version) of the current node (or of the current primary if the node is a replica). Each time there is a failover, a new, unique, monotonically increasing configuration epoch is created. If multiple nodes claim to serve the same hash slots, the one with the higher configuration epoch wins.
10. `link-state`: The state of the link used for the node-to-node cluster bus. Use this link to communicate with the node. Can be `connected` or `disconnected`.
11. `slot`: A hash slot number or range. Starting from argument number 9, but there may be up to 16384 entries in total (limit never reached). This is the list of hash slots served by this node. If the entry is just a number, it is parsed as such. If it is a range, it is in the form `start-end`, and means that the node is responsible for all the hash slots from `start` to `end` including the start and end values.

 Auxiliary fields are:

 * `shard-id`: a 40-character globally unique string generated when a node is created. A node's shard id changes only when the node joins a different shard via `cluster replicate` and there the node's shard id is updated to its primary's.

 Flags are:

 * `myself`: The node you are contacting.
* `master`: Node is a primary.
* `slave`: Node is a replica.
* `fail?`: Node is in `PFAIL` state. Not reachable for the node you are contacting, but still logically reachable (not in `FAIL` state).
* `fail`: Node is in `FAIL` state. It was not reachable for multiple nodes that promoted the `PFAIL` state to `FAIL`.
* `handshake`: Untrusted node, we are handshaking.
* `noaddr`: No address known for this node.
* `nofailover`: Replica will not try to failover.
* `noflags`: No flags at all.

 Notes on published config epochs
--------------------------------

 Replicas broadcast their primary's config epochs (in order to get an `UPDATE` message if they are found to be stale), so the real config epoch of the replica (which is meaningless more or less, since they don't serve hash slots) can be only obtained checking the node flagged as `myself`, which is the entry of the node we are asking to generate `CLUSTER NODES` output. The other replicas epochs reflect what they publish in heartbeat packets, which is, the configuration epoch of the primaries they are currently replicating.

 Special slot entries
--------------------

 Normally hash slots associated to a given node are in one of the following formats, as already explained above:

 1. Single number: 3894
2. Range: 3900-4000

 However node hash slots can be in a special state, used in order to communicate errors after a node restart (mismatch between the keys in the AOF/RDB file, and the node hash slots configuration), or when there is a resharding operation in progress. This two states are **importing** and **migrating**.

 The meaning of the two states is explained in the Redis Specification, however the gist of the two states is the following:

 * **Importing** slots are yet not part of the nodes hash slot, there is a migration in progress. The node will accept queries about these slots only if the `ASK` command is used.
* **Migrating** slots are assigned to the node, but are being migrated to some other node. The node will accept queries if all the keys in the command exist already, otherwise it will emit what is called an **ASK redirection**, to force new keys creation directly in the importing node.

 Importing and migrating slots are emitted in the `CLUSTER NODES` output as follows:

 * **Importing slot:** `[slot_number-<-importing_from_node_id]`
* **Migrating slot:** `[slot_number->-migrating_to_node_id]`

 The following are a few examples of importing and migrating slots:

 * `[93-<-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`
* `[1002-<-67ed2db8d677e59ec4a4cefb06858cf2a1a89fa1]`
* `[77->-e7d1eecce10fd6bb5eb35b9f99a514335d9ba9ca]`
* `[16311->-292f8b365bb7edb5e285caf0b7e6ddc7265d2f4f]`

 Note that the format does not have any space, so `CLUSTER NODES` output format is plain CSV with space as separator even when this special slots are emitted. However a complete parser for the format should be able to handle them.

 Note that:

 1. Migration and importing slots are only added to the node flagged as `myself`. This information is local to a node, for its own slots.
2. Importing and migrating slots are provided as **additional info**. If the node has a given hash slot assigned, it will be also a plain number in the list of hash slots, so clients that don't have a clue about hash slots migrations can just skip this special fields.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): The serialized cluster configuration.

 **A note about the word slave used in this man page and command name**: Starting with Redis 5, if not for backward compatibility, the Redis project no longer uses the word slave. Unfortunately in this command the word slave is part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-nodes/>

CLUSTER
=======



```
CLUSTER REPLICAS
```
 Syntax 
```
CLUSTER REPLICAS node-id
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command provides a list of replica nodes replicating from the specified master node. The list is provided in the same format used by [`CLUSTER NODES`](../cluster-nodes) (please refer to its documentation for the specification of the format).

 The command will fail if the specified node is not known or if it is not a master according to the node table of the node receiving the command.

 Note that if a replica is added, moved, or removed from a given master node, and we ask `CLUSTER REPLICAS` to a node that has not yet received the configuration update, it may show stale information. However eventually (in a matter of seconds if there are no network partitions) all the nodes will agree about the set of nodes associated with a given master.

 Return
------

 The command returns data in the same format as [`CLUSTER NODES`](../cluster-nodes).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-replicas/>

CLUSTER
=======



```
CLUSTER RESET
```
 Syntax 
```
CLUSTER RESET [HARD | SOFT]
```
  Available since: 3.0.0 Time complexity: O(N) where N is the number of known nodes. The command may execute a FLUSHALL as a side effect. ACL categories:  `@admin`, `@slow`, `@dangerous`,   Reset a Redis Cluster node, in a more or less drastic way depending on the reset type, that can be **hard** or **soft**. Note that this command **does not work for masters if they hold one or more keys**, in that case to completely reset a master node keys must be removed first, e.g. by using [`FLUSHALL`](../flushall) first, and then `CLUSTER RESET`.

 Effects on the node:

 1. All the other nodes in the cluster are forgotten.
2. All the assigned / open slots are reset, so the slots-to-nodes mapping is totally cleared.
3. If the node is a replica it is turned into an (empty) master. Its dataset is flushed, so at the end the node will be an empty master.
4. **Hard reset only**: a new Node ID is generated.
5. **Hard reset only**: `currentEpoch` and `configEpoch` vars are set to 0.
6. The new configuration is persisted on disk in the node cluster configuration file.

 This command is mainly useful to re-provision a Redis Cluster node in order to be used in the context of a new, different cluster. The command is also extensively used by the Redis Cluster testing framework in order to reset the state of the cluster every time a new test unit is executed.

 If no reset type is specified, the default is **soft**.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was successful. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-reset/>

CMS.INITBYPROB
==============



```
CMS.INITBYPROB
```
 Syntax 
```
CMS.INITBYPROB key error probability
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Initializes a Count-Min Sketch to accommodate requested tolerances.

 ### Parameters:

 * **key**: The name of the sketch.
* **error**: Estimate size of error. The error is a percent of total counted items. This effects the width of the sketch.
* **probability**: The desired probability for inflated count. This should be a decimal value between 0 and 1. This effects the depth of the sketch. For example, for a desired false positive rate of 0.1% (1 in 1000), error\_rate should be set to 0.001. The closer this number is to zero, the greater the memory consumption per item and the more CPU usage per operation.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> CMS.INITBYPROB test 0.001 0.01
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.initbyprob/>

CLUSTER
=======



```
CLUSTER SHARDS
```
 Syntax 
```
CLUSTER SHARDS
```
  Available since: 7.0.0 Time complexity: O(N) where N is the total number of cluster nodes ACL categories:  `@slow`,   `CLUSTER SHARDS` returns details about the shards of the cluster. A shard is defined as a collection of nodes that serve the same set of slots and that replicate from each other. A shard may only have a single master at a given time, but may have multiple or no replicas. It is possible for a shard to not be serving any slots while still having replicas.

 This command replaces the [`CLUSTER SLOTS`](../cluster-slots) command, by providing a more efficient and extensible representation of the cluster.

 The command is suitable to be used by Redis Cluster client libraries in order to understand the topology of the cluster. A client should issue this command on startup in order to retrieve the map associating cluster *hash slots* with actual node information. This map should be used to direct commands to the node that is likely serving the slot associated with a given command. In the event the command is sent to the wrong node, in that it received a '-MOVED' redirect, this command can then be used to update the topology of the cluster.

 The command returns an array of shards, with each shard containing two fields, 'slots' and 'nodes'.

 The 'slots' field is a list of slot ranges served by this shard, stored as pair of integers representing the inclusive start and end slots of the ranges. For example, if a node owns the slots 1, 2, 3, 5, 7, 8 and 9, the slots ranges would be stored as [1-3], [5-5], [7-9]. The slots field would therefore be represented by the following list of integers.

 
```
1) 1) "slots"
   2) 1) (integer) 1
      2) (integer) 3
      3) (integer) 5
      4) (integer) 5
      5) (integer) 7
      6) (integer) 9

```

The 'nodes' field contains a list of all nodes within the shard. Each individual node is a map of attributes that describe the node. Some attributes are optional and more attributes may be added in the future. The current list of attributes:

 * id: The unique node id for this particular node.
* endpoint: The preferred endpoint to reach the node, see below for more information about the possible values of this field.
* ip: The IP address to send requests to for this node.
* hostname (optional): The announced hostname to send requests to for this node.
* port (optional): The TCP (non-TLS) port of the node. At least one of port or tls-port will be present.
* tls-port (optional): The TLS port of the node. At least one of port or tls-port will be present.
* role: The replication role of this node.
* replication-offset: The replication offset of this node. This information can be used to send commands to the most up to date replicas.
* health: Either `online`, `failed`, or `loading`. This information should be used to determine which nodes should be sent traffic. The `loading` health state should be used to know that a node is not currently eligible to serve traffic, but may be eligible in the future.

 The endpoint, along with the port, defines the location that clients should use to send requests for a given slot. A NULL value for the endpoint indicates the node has an unknown endpoint and the client should connect to the same endpoint it used to send the `CLUSTER SHARDS` command but with the port returned from the command. This unknown endpoint configuration is useful when the Redis nodes are behind a load balancer that Redis doesn't know the endpoint of. Which endpoint is set is determined by the `cluster-preferred-endpoint-type` config.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): nested list of a map of hash ranges and shard nodes.

 Examples
--------

 
```
> CLUSTER SHARDS
1) 1) "slots"
   2) 1) (integer) 0
      2) (integer) 5460
   3) "nodes"
   4) 1)  1) "id"
          2) "e10b7051d6bf2d5febd39a2be297bbaea6084111"
          3) "port"
          4) (integer) 30001
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "1901f5962d865341e81c85f9f596b1e7160c35ce"
          3) "port"
          4) (integer) 30006
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
2) 1) "slots"
   2) 1) (integer) 10923
      2) (integer) 16383
   3) "nodes"
   4) 1)  1) "id"
          2) "fd20502fe1b32fc32c15b69b0a9537551f162f1f"
          3) "port"
          4) (integer) 30003
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "6daa25c08025a0c7e4cc0d1ab255949ce6cee902"
          3) "port"
          4) (integer) 30005
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
3) 1) "slots"
   2) 1) (integer) 5461
      2) (integer) 10922
   3) "nodes"
   4) 1)  1) "id"
          2) "a4a3f445ead085eb3eb9ee7d8c644ec4481ec9be"
          3) "port"
          4) (integer) 30002
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "master"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"
      2)  1) "id"
          2) "da6d5847aa019e9b9d2a8aa24a75f856fd3456cc"
          3) "port"
          4) (integer) 30004
          5) "ip"
          6) "127.0.0.1"
          7) "endpoint"
          8) "127.0.0.1"
          9) "role"
         10) "replica"
         11) "replication-offset"
         12) (integer) 72156
         13) "health"
         14) "online"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-shards/>

CLUSTER
=======



```
CLUSTER SLOTS (deprecated)
```
  As of Redis version 7.0.0, this command is regarded as deprecated.

 It can be replaced by [`CLUSTER SHARDS`](../cluster-shards) when migrating or writing new code.

  Syntax 
```
CLUSTER SLOTS
```
  Available since: 3.0.0 Time complexity: O(N) where N is the total number of Cluster nodes ACL categories:  `@slow`,   `CLUSTER SLOTS` returns details about which cluster slots map to which Redis instances. The command is suitable to be used by Redis Cluster client libraries implementations in order to retrieve (or update when a redirection is received) the map associating cluster *hash slots* with actual nodes network information, so that when a command is received, it can be sent to what is likely the right instance for the keys specified in the command.

 The networking information for each node is an array containing the following elements:

 * Preferred endpoint (Either an IP address, hostname, or NULL)
* Port number
* The node ID
* A map of additional networking metadata

 The preferred endpoint, along with the port, defines the location that clients should use to send requests for a given slot. A NULL value for the endpoint indicates the node has an unknown endpoint and the client should connect to the same endpoint it used to send the `CLUSTER SLOTS` command but with the port returned from the command. This unknown endpoint configuration is useful when the Redis nodes are behind a load balancer that Redis doesn't know the endpoint of. Which endpoint is set as preferred is determined by the `cluster-preferred-endpoint-type` config.

 Additional networking metadata is provided as a map on the fourth argument for each node. The following networking metadata may be returned:

 * IP: When the preferred endpoint is not set to IP.
* Hostname: When a node has an announced hostname but the primary endpoint is not set to hostname.

 Nested Result Array
-------------------

 Each nested result is:

 * Start slot range
* End slot range
* Master for slot range represented as nested networking information
* First replica of master for slot range
* Second replica
* ...continues until all replicas for this master are returned.

 Each result includes all active replicas of the master instance for the listed slot range. Failed replicas are not returned.

 The third nested reply is guaranteed to be the networking information of the master instance for the slot range. All networking information after the third nested reply are replicas of the master.

 If a cluster instance has non-contiguous slots (e.g. 1-400,900,1800-6000) then master and replica networking information results will be duplicated for each top-level slot range reply.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): nested list of slot ranges with networking information.

 Examples
--------

 
```
> CLUSTER SLOTS
1) 1) (integer) 0
   2) (integer) 5460
   3) 1) "127.0.0.1"
      2) (integer) 30001
      3) "09dbe9720cda62f7865eabc5fd8857c5d2678366"
      4) 1) hostname
         2) "host-1.redis.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30004
      3) "821d8ca00d7ccf931ed3ffc7e3db0599d2271abf"
      4) 1) hostname
         2) "host-2.redis.example.com"
2) 1) (integer) 5461
   2) (integer) 10922
   3) 1) "127.0.0.1"
      2) (integer) 30002
      3) "c9d93d9f2c0c524ff34cc11838c2003d8c29e013"
      4) 1) hostname
         2) "host-3.redis.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30005
      3) "faadb3eb99009de4ab72ad6b6ed87634c7ee410f"
      4) 1) hostname
         2) "host-4.redis.example.com"
3) 1) (integer) 10923
   2) (integer) 16383
   3) 1) "127.0.0.1"
      2) (integer) 30003
      3) "044ec91f325b7595e76dbcb18cc688b6a5b434a1"
      4) 1) hostname
         2) "host-5.redis.example.com"
   4) 1) "127.0.0.1"
      2) (integer) 30006
      3) "58e6e48d41228013e5d9c1c37c5060693925e97e"
      4) 1) hostname
         2) "host-6.redis.example.com"

```

**Warning:** In future versions there could be more elements describing the node better. In general a client implementation should just rely on the fact that certain parameters are at fixed positions as specified, but more parameters may follow and should be ignored. Similarly a client library should try if possible to cope with the fact that older versions may just have the primary endpoint and port parameter.

 Behavior change history
-----------------------

 * `>= 7.0.0`: Added support for hostnames and unknown endpoints in first field of node response.

 History
-------

 * Starting with Redis version 4.0.0: Added node IDs.
* Starting with Redis version 7.0.0: Added additional networking metadata field.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-slots/>

CLUSTER
=======



```
CLUSTER REPLICATE
```
 Syntax 
```
CLUSTER REPLICATE node-id
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command reconfigures a node as a replica of the specified master. If the node receiving the command is an *empty master*, as a side effect of the command, the node role is changed from master to replica.

 Once a node is turned into the replica of another master node, there is no need to inform the other cluster nodes about the change: heartbeat packets exchanged between nodes will propagate the new configuration automatically.

 A replica will always accept the command, assuming that:

 1. The specified node ID exists in its nodes table.
2. The specified node ID does not identify the instance we are sending the command to.
3. The specified node ID is a master.

 If the node receiving the command is not already a replica, but is a master, the command will only succeed, and the node will be converted into a replica, only if the following additional conditions are met:

 1. The node is not serving any hash slots.
2. The node is empty, no keys are stored at all in the key space.

 If the command succeeds the new replica will immediately try to contact its master in order to replicate from it.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was executed successfully, otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-replicate/>

CMS.INCRBY
==========



```
CMS.INCRBY
```
 Syntax 
```
CMS.INCRBY key item increment [item increment ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n) where n is the number of items  Increases the count of item by increment. Multiple items can be increased with one call.

 ### Parameters:

 * **key**: The name of the sketch.
* **item**: The item which counter is to be increased.
* **increment**: Amount by which the item counter is to be increased.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) with an updated min-count of each of the items in the sketch.

 Count of each item after increment.

 Examples
--------

 
```
redis> CMS.INCRBY test foo 10 bar 42
1) (integer) 10
2) (integer) 42

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.incrby/>

CMS.INFO
========



```
CMS.INFO
```
 Syntax 
```
CMS.INFO key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns width, depth and total count of the sketch.

 ### Parameters:

 * **key**: The name of the sketch.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information of the filter.

 Examples
--------

 
```
redis> CMS.INFO test
 1) width
 2) (integer) 2000
 3) depth
 4) (integer) 7
 5) count
 6) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.info/>

CLUSTER
=======



```
CLUSTER SAVECONFIG
```
 Syntax 
```
CLUSTER SAVECONFIG
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Forces a node to save the `nodes.conf` configuration on disk. Before to return the command calls `fsync(2)` in order to make sure the configuration is flushed on the computer disk.

 This command is mainly used in the event a `nodes.conf` node state file gets lost / deleted for some reason, and we want to generate it again from scratch. It can also be useful in case of mundane alterations of a node cluster configuration via the [`CLUSTER`](../cluster) command in order to ensure the new configuration is persisted on disk, however all the commands should normally be able to auto schedule to persist the configuration on disk when it is important to do so for the correctness of the system in the event of a restart.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` or an error if the operation fails.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-saveconfig/>

CLUSTER
=======



```
CLUSTER SLAVES (deprecated)
```
  As of Redis version 5.0.0, this command is regarded as deprecated.

 It can be replaced by [`CLUSTER REPLICAS`](../cluster-replicas) when migrating or writing new code.

  Syntax 
```
CLUSTER SLAVES node-id
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   **A note about the word slave used in this man page and command name**: starting with Redis version 5, if not for backward compatibility, the Redis project no longer uses the word slave. Please use the new command [`CLUSTER REPLICAS`](../cluster-replicas). The command `CLUSTER SLAVES` will continue to work for backward compatibility.

 The command provides a list of replica nodes replicating from the specified master node. The list is provided in the same format used by [`CLUSTER NODES`](../cluster-nodes) (please refer to its documentation for the specification of the format).

 The command will fail if the specified node is not known or if it is not a master according to the node table of the node receiving the command.

 Note that if a replica is added, moved, or removed from a given master node, and we ask `CLUSTER SLAVES` to a node that has not yet received the configuration update, it may show stale information. However eventually (in a matter of seconds if there are no network partitions) all the nodes will agree about the set of nodes associated with a given master.

 Return
------

 The command returns data in the same format as [`CLUSTER NODES`](../cluster-nodes).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-slaves/>

COMMAND
=======



```
COMMAND INFO
```
 Syntax 
```
COMMAND INFO [command-name [command-name ...]]
```
  Available since: 2.8.13 Time complexity: O(N) where N is the number of commands to look up ACL categories:  `@slow`, `@connection`,   Returns [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of details about multiple Redis commands.

 Same result format as [`COMMAND`](../command) except you can specify which commands get returned.

 If you request details about non-existing commands, their return position will be nil.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): nested list of command details.

 Examples
--------

 
```

COMMAND INFO get set eval
COMMAND INFO foo evalsha config bar

```
 History
-------

 * Starting with Redis version 7.0.0: Allowed to be called with no argument to get info on all commands.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-info/>

CMS.QUERY
=========



```
CMS.QUERY
```
 Syntax 
```
CMS.QUERY key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n) where n is the number of items  Returns the count for one or more items in a sketch.

 ### Parameters:

 * **key**: The name of the sketch.
* **item**: One or more items for which to return the count.

 Return
------

 Count of one or more items

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) with a min-count of each of the items in the sketch.

 Examples
--------

 
```
redis> CMS.QUERY test foo bar
1) (integer) 10
2) (integer) 42

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.query/>

CLUSTER
=======



```
CLUSTER SET-CONFIG-EPOCH
```
 Syntax 
```
CLUSTER SET-CONFIG-EPOCH config-epoch
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command sets a specific *config epoch* in a fresh node. It only works when:

 1. The nodes table of the node is empty.
2. The node current *config epoch* is zero.

 These prerequisites are needed since usually, manually altering the configuration epoch of a node is unsafe, we want to be sure that the node with the higher configuration epoch value (that is the last that failed over) wins over other nodes in claiming the hash slots ownership.

 However there is an exception to this rule, and it is when a new cluster is created from scratch. Redis Cluster *config epoch collision resolution* algorithm can deal with new nodes all configured with the same configuration at startup, but this process is slow and should be the exception, only to make sure that whatever happens, two more nodes eventually always move away from the state of having the same configuration epoch.

 So, using `CLUSTER SET-CONFIG-EPOCH`, when a new cluster is created, we can assign a different progressive configuration epoch to each node before joining the cluster together.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was executed successfully, otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-set-config-epoch/>

CMS.MERGE
=========



```
CMS.MERGE
```
 Syntax 
```
CMS.MERGE destination numKeys source [source ...] [WEIGHTS weight
  [weight ...]]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n) where n is the number of sketches  Merges several sketches into one sketch. All sketches must have identical width and depth. Weights can be used to multiply certain sketches. Default weight is 1.

 ### Parameters:

 * **dest**: The name of destination sketch. Must be initialized.
* **numKeys**: Number of sketches to be merged.
* **src**: Names of source sketches to be merged.
* **weight**: Multiple of each sketch. Default =1.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> CMS.MERGE dest 2 test1 test2 WEIGHTS 1 3
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.merge/>

COMMAND
=======



```
COMMAND
```
 Syntax 
```
COMMAND
```
  Available since: 2.8.13 Time complexity: O(N) where N is the total number of Redis commands ACL categories:  `@slow`, `@connection`,   Return an array with details about every Redis command.

 The `COMMAND` command is introspective. Its reply describes all commands that the server can process. Redis clients can call it to obtain the server's runtime capabilities during the handshake.

 `COMMAND` also has several subcommands. Please refer to its subcommands for further details.

 **Cluster note:** this command is especially beneficial for cluster-aware clients. Such clients must identify the names of keys in commands to route requests to the correct shard. Although most commands accept a single key as their first argument, there are many exceptions to this rule. You can call `COMMAND` and then keep the mapping between commands and their respective key specification rules cached in the client.

 The reply it returns is an array with an element per command. Each element that describes a Redis command is represented as an array by itself.

 The command's array consists of a fixed number of elements. The exact number of elements in the array depends on the server's version.

 1. Name
2. Arity
3. Flags
4. First key
5. Last key
6. Step
7. [ACL categories](https://redis.io/topics/acl) (as of Redis 6.0)
8. [Tips](https://redis.io/topics/command-tips) (as of Redis 7.0)
9. [Key specifications](https://redis.io/topics/key-specs) (as of Redis 7.0)
10. Subcommands (as of Redis 7.0)

 Name
----

 This is the command's name in lowercase.

 **Note:** Redis command names are case-insensitive.

 Arity
-----

 Arity is the number of arguments a command expects. It follows a simple pattern:

 * A positive integer means a fixed number of arguments.
* A negative integer means a minimal number of arguments.

 Command arity *always includes* the command's name itself (and the subcommand when applicable).

 Examples:

 * [`GET`](../get)'s arity is *2* since the command only accepts one argument and always has the format `GET _key_`.
* [`MGET`](../mget)'s arity is *-2* since the command accepts at least one argument, but possibly multiple ones: `MGET _key1_ [key2] [key3] ...`.

 Flags
-----

 Command flags are an array. It can contain the following simple strings (status reply):

 * **admin:** the command is an administrative command.
* **asking:** the command is allowed even during hash slot migration. This flag is relevant in Redis Cluster deployments.
* **blocking:** the command may block the requesting client.
* **denyoom**: the command is rejected if the server's memory usage is too high (see the *maxmemory* configuration directive).
* **fast:** the command operates in constant or log(N) time. This flag is used for monitoring latency with the [`LATENCY`](../latency) command.
* **loading:** the command is allowed while the database is loading.
* **movablekeys:** the *first key*, *last key*, and *step* values don't determine all key positions. Clients need to use [`COMMAND GETKEYS`](../command-getkeys) or [key specifications](https://redis.io/topics/key-specs) in this case. See below for more details.
* **no\_auth:** executing the command doesn't require authentication.
* **no\_async\_loading:** the command is denied during asynchronous loading (that is when a replica uses disk-less `SWAPDB SYNC`, and allows access to the old dataset).
* **no\_mandatory\_keys:** the command may accept key name arguments, but these aren't mandatory.
* **no\_multi:** the command isn't allowed inside the context of a [transaction](https://redis.io/topics/transactions).
* **noscript:** the command can't be called from [scripts](https://redis.io/topics/eval-intro) or [functions](https://redis.io/topics/functions-intro).
* **pubsub:** the command is related to [Redis Pub/Sub](https://redis.io/topics/pubsub).
* **random**: the command returns random results, which is a concern with verbatim script replication. As of Redis 7.0, this flag is a [command tip](https://redis.io/topics/command-tips).
* **readonly:** the command doesn't modify data.
* **sort\_for\_script:** the command's output is sorted when called from a script.
* **skip\_monitor:** the command is not shown in [`MONITOR`](../monitor)'s output.
* **skip\_slowlog:** the command is not shown in [`SLOWLOG`](../slowlog)'s output. As of Redis 7.0, this flag is a [command tip](https://redis.io/topics/command-tips).
* **stale:** the command is allowed while a replica has stale data.
* **write:** the command may modify data.

 ### Movablekeys

 Consider [`SORT`](../sort):

 
```
1) 1) "sort"
   2) (integer) -2
   3) 1) write
      2) denyoom
      3) movablekeys
   4) (integer) 1
   5) (integer) 1
   6) (integer) 1
   ...

```

Some Redis commands have no predetermined key locations or are not easy to find. For those commands, the *movablekeys* flag indicates that the *first key*, *last key*, and *step* values are insufficient to find all the keys.

 Here are several examples of commands that have the *movablekeys* flag:

 * [`SORT`](../sort): the optional *STORE*, *BY*, and *GET* modifiers are followed by names of keys.
* [`ZUNION`](../zunion): the *numkeys* argument specifies the number key name arguments.
* [`MIGRATE`](../migrate): the keys appear *KEYS* keyword and only when the second argument is the empty string.

 Redis Cluster clients need to use other measures, as follows, to locate the keys for such commands.

 You can use the [`COMMAND GETKEYS`](../command-getkeys) command and have your Redis server report all keys of a given command's invocation.

 As of Redis 7.0, clients can use the [key specifications](#key-specifications) to identify the positions of key names. The only commands that require using [`COMMAND GETKEYS`](../command-getkeys) are [`SORT`](../sort) and [`MIGRATE`](../migrate) for clients that parse keys' specifications.

 For more information, please refer to the [key specifications page](https://redis.io/topics/key-specs).

 First key
---------

 The position of the command's first key name argument. For most commands, the first key's position is 1. Position 0 is always the command name itself.

 Last key
--------

 The position of the command's last key name argument. Redis commands usually accept one, two or multiple number of keys.

 Commands that accept a single key have both *first key* and *last key* set to 1.

 Commands that accept two key name arguments, e.g. [`BRPOPLPUSH`](../brpoplpush), [`SMOVE`](../smove) and [`RENAME`](../rename), have this value set to the position of their second key.

 Multi-key commands that accept an arbitrary number of keys, such as [`MSET`](../mset), use the value -1.

 Step
----

 The step, or increment, between the *first key* and the position of the next key.

 Consider the following two examples:

 
```
1) 1) "mset"
   2) (integer) -3
   3) 1) write
      2) denyoom
   4) (integer) 1
   5) (integer) -1
   6) (integer) 2
   ...

```


```
1) 1) "mget"
   2) (integer) -2
   3) 1) readonly
      2) fast
   4) (integer) 1
   5) (integer) -1
   6) (integer) 1
   ...

```

The step count allows us to find keys' positions. For example [`MSET`](../mset): Its syntax is `MSET _key1_ _val1_ [key2] [val2] [key3] [val3]...`, so the keys are at every other position (step value of *2*). Unlike [`MGET`](../mget), which uses a step value of *1*.

 ACL categories
--------------

 This is an array of simple strings that are the ACL categories to which the command belongs. Please refer to the [Access Control List](https://redis.io/topics/acl) page for more information.

 Command tips
------------

 Helpful information about the command. To be used by clients/proxies.

 Please check the [Command tips](https://redis.io/topics/command-tips) page for more information.

 Key specifications
------------------

 This is an array consisting of the command's key specifications. Each element in the array is a map describing a method for locating keys in the command's arguments.

 For more information please check the [key specifications page](https://redis.io/topics/key-specs).

 Subcommands
-----------

 This is an array containing all of the command's subcommands, if any. Some Redis commands have subcommands (e.g., the `REWRITE` subcommand of [`CONFIG`](../config)). Each element in the array represents one subcommand and follows the same specifications as those of `COMMAND`'s reply.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a nested list of command details.

 The order of commands in the array is random.

 Examples
--------

 The following is `COMMAND`'s output for the [`GET`](../get) command:

 
```
1)  1) "get"
    2) (integer) 2
    3) 1) readonly
       2) fast
    4) (integer) 1
    5) (integer) 1
    6) (integer) 1
    7) 1) @read
       2) @string
       3) @fast
    8) (empty array)
    9) 1) 1) "flags"
          2) 1) read
          3) "begin_search"
          4) 1) "type"
             2) "index"
             3) "spec"
             4) 1) "index"
                2) (integer) 1
          5) "find_keys"
          6) 1) "type"
             2) "range"
             3) "spec"
             4) 1) "lastkey"
                2) (integer) 0
                3) "keystep"
                4) (integer) 1
                5) "limit"
                6) (integer) 0
   10) (empty array)
...

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command/>

COMMAND
=======



```
COMMAND COUNT
```
 Syntax 
```
COMMAND COUNT
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   Returns [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) of number of total commands in this Redis server.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): number of commands returned by [`COMMAND`](../command)

 Examples
--------

 
```

COMMAND COUNT

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-count/>

COMMAND
=======



```
COMMAND DOCS
```
 Syntax 
```
COMMAND DOCS [command-name [command-name ...]]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of commands to look up ACL categories:  `@slow`, `@connection`,   Return documentary information about commands.

 By default, the reply includes all of the server's commands. You can use the optional *command-name* argument to specify the names of one or more commands.

 The reply includes a map for each returned command. The following keys may be included in the mapped reply:

 * **summary:** short command description.
* **since:** the Redis version that added the command (or for module commands, the module version).
* **group:** the functional group to which the command belongs. Possible values are:
	+ *bitmap*
	+ *cluster*
	+ *connection*
	+ *generic*
	+ *geo*
	+ *hash*
	+ *hyperloglog*
	+ *list*
	+ *module*
	+ *pubsub*
	+ *scripting*
	+ *sentinel*
	+ *server*
	+ *set*
	+ *sorted-set*
	+ *stream*
	+ *string*
	+ *transactions*
* **complexity:** a short explanation about the command's time complexity.
* **doc\_flags:** an array of documentation flags. Possible values are:
	+ *deprecated:* the command is deprecated.
	+ *syscmd:* a system command that isn't meant to be called by users.
* **deprecated\_since:** the Redis version that deprecated the command (or for module commands, the module version)..
* **replaced\_by:** the alternative for a deprecated command.
* **history:** an array of historical notes describing changes to the command's behavior or arguments. Each entry is an array itself, made up of two elements:
	1. The Redis version that the entry applies to.
	2. The description of the change.
* **arguments:** an array of maps that describe the command's arguments. Please refer to the [Redis command arguments](https://redis.io/topics/command-arguments) page for more information.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a map as a flattened array as described above.

 Examples
--------

 
```

COMMAND DOCS SET

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-docs/>

DBSIZE
======



```
DBSIZE
```
 Syntax 
```
DBSIZE
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   Return the number of keys in the currently-selected database.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/dbsize/>

CONFIG
======



```
CONFIG GET
```
 Syntax 
```
CONFIG GET parameter [parameter ...]
```
  Available since: 2.0.0 Time complexity: O(N) when N is the number of configuration parameters provided ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `CONFIG GET` command is used to read the configuration parameters of a running Redis server. Not all the configuration parameters are supported in Redis 2.4, while Redis 2.6 can read the whole configuration of a server using this command.

 The symmetric command used to alter the configuration at run time is `CONFIG SET`.

 `CONFIG GET` takes multiple arguments, which are glob-style patterns. Any configuration parameter matching any of the patterns are reported as a list of key-value pairs. Example:

 
```
redis> config get *max-*-entries* maxmemory
 1) "maxmemory"
 2) "0"
 3) "hash-max-listpack-entries"
 4) "512"
 5) "hash-max-ziplist-entries"
 6) "512"
 7) "set-max-intset-entries"
 8) "512"
 9) "zset-max-listpack-entries"
10) "128"
11) "zset-max-ziplist-entries"
12) "128"

```

You can obtain a list of all the supported configuration parameters by typing `CONFIG GET *` in an open `redis-cli` prompt.

 All the supported parameters have the same meaning of the equivalent configuration parameter used in the [redis.conf](http://github.com/redis/redis/raw/unstable/redis.conf) file:

 Note that you should look at the redis.conf file relevant to the version you're working with as configuration options might change between versions. The link above is to the latest development version.

 Return
------

 The return type of the command is a [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays).

 History
-------

 * Starting with Redis version 7.0.0: Added the ability to pass multiple pattern parameters in one call



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/config-get/>

COMMAND
=======



```
COMMAND GETKEYSANDFLAGS
```
 Syntax 
```
COMMAND GETKEYSANDFLAGS command [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of arguments to the command ACL categories:  `@slow`, `@connection`,   Returns [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of keys from a full Redis command and their usage flags.

 `COMMAND GETKEYSANDFLAGS` is a helper command to let you find the keys from a full Redis command together with flags indicating what each key is used for.

 [`COMMAND`](../command) provides information on how to find the key names of each command (see `firstkey`, [key specifications](https://redis.io/topics/key-specs#logical-operation-flags), and `movablekeys`), but in some cases it's not possible to find keys of certain commands and then the entire command must be parsed to discover some / all key names. You can use [`COMMAND GETKEYS`](../command-getkeys) or `COMMAND GETKEYSANDFLAGS` to discover key names directly from how Redis parses the commands.

 Refer to [key specifications](https://redis.io/topics/key-specs#logical-operation-flags) for information about the meaning of the key flags.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of keys from your command. Each element of the array is an array containing key name in the first entry, and flags in the second.

 Examples
--------

 
```

COMMAND GETKEYS MSET a b c d e f
COMMAND GETKEYS EVAL "not consulted" 3 key1 key2 key3 arg1 arg2 arg3 argN
COMMAND GETKEYSANDFLAGS LMOVE mylist1 mylist2 left left

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-getkeysandflags/>

DEL
===



```
DEL
```
 Syntax 
```
DEL key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of keys that will be removed. When a key to remove holds a value other than a string, the individual complexity for this key is O(M) where M is the number of elements in the list, set, sorted set or hash. Removing a single key that holds a string value is O(1). ACL categories:  `@keyspace`, `@write`, `@slow`,   Removes the specified keys. A key is ignored if it does not exist.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of keys that were removed.

 Examples
--------

 
```

SET key1 "Hello"
SET key2 "World"
DEL key1 key2 key3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/del/>

DECR
====



```
DECR
```
 Syntax 
```
DECR key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Decrements the number stored at `key` by one. If the key does not exist, it is set to `0` before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to **64 bit signed integers**.

 See [`INCR`](../incr) for extra information on increment/decrement operations.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the value of `key` after the decrement

 Examples
--------

 
```

SET mykey "10"
DECR mykey
SET mykey "234293482390480948029348230948"
DECR mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/decr/>

COMMAND
=======



```
COMMAND GETKEYS
```
 Syntax 
```
COMMAND GETKEYS command [arg [arg ...]]
```
  Available since: 2.8.13 Time complexity: O(N) where N is the number of arguments to the command ACL categories:  `@slow`, `@connection`,   Returns [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of keys from a full Redis command.

 `COMMAND GETKEYS` is a helper command to let you find the keys from a full Redis command.

 [`COMMAND`](../command) provides information on how to find the key names of each command (see `firstkey`, [key specifications](https://redis.io/topics/key-specs#logical-operation-flags), and `movablekeys`), but in some cases it's not possible to find keys of certain commands and then the entire command must be parsed to discover some / all key names. You can use `COMMAND GETKEYS` or [`COMMAND GETKEYSANDFLAGS`](../command-getkeysandflags) to discover key names directly from how Redis parses the commands.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of keys from your command.

 Examples
--------

 
```

COMMAND GETKEYS MSET a b c d e f
COMMAND GETKEYS EVAL "not consulted" 3 key1 key2 key3 arg1 arg2 arg3 argN
COMMAND GETKEYS SORT mylist ALPHA STORE outlist

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-getkeys/>

DECRBY
======



```
DECRBY
```
 Syntax 
```
DECRBY key decrement
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Decrements the number stored at `key` by `decrement`. If the key does not exist, it is set to `0` before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.

 See [`INCR`](../incr) for extra information on increment/decrement operations.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the value of `key` after the decrement

 Examples
--------

 
```

SET mykey "10"
DECRBY mykey 3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/decrby/>

CONFIG
======



```
CONFIG RESETSTAT
```
 Syntax 
```
CONFIG RESETSTAT
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Resets the statistics reported by Redis using the [`INFO`](../info) and [`LATENCY HISTOGRAM`](../latency-histogram) commands.

 The following is a non-exhaustive list of values that are reset:

 * Keyspace hits and misses
* Number of expired keys
* Command and error statistics
* Connections received, rejected and evicted
* Persistence statistics
* Active defragmentation statistics

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/config-resetstat/>

COMMAND
=======



```
COMMAND LIST
```
 Syntax 
```
COMMAND LIST [FILTERBY <MODULE module-name | ACLCAT category |
  PATTERN pattern>]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the total number of Redis commands ACL categories:  `@slow`, `@connection`,   Return an array of the server's command names.

 You can use the optional *FILTERBY* modifier to apply one of the following filters:

 * **MODULE module-name**: get the commands that belong to the module specified by *module-name*.
* **ACLCAT category**: get the commands in the [ACL category](https://redis.io/docs/management/security/acl/#command-categories) specified by *category*.
* **PATTERN pattern**: get the commands that match the given glob-like *pattern*.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of command names.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/command-list/>

CONFIG
======



```
CONFIG SET
```
 Syntax 
```
CONFIG SET parameter value [parameter value ...]
```
  Available since: 2.0.0 Time complexity: O(N) when N is the number of configuration parameters provided ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `CONFIG SET` command is used in order to reconfigure the server at run time without the need to restart Redis. You can change both trivial parameters or switch from one to another persistence option using this command.

 The list of configuration parameters supported by `CONFIG SET` can be obtained issuing a `CONFIG GET *` command, that is the symmetrical command used to obtain information about the configuration of a running Redis instance.

 All the configuration parameters set using `CONFIG SET` are immediately loaded by Redis and will take effect starting with the next command executed.

 All the supported parameters have the same meaning of the equivalent configuration parameter used in the [redis.conf](http://github.com/redis/redis/raw/unstable/redis.conf) file.

 Note that you should look at the redis.conf file relevant to the version you're working with as configuration options might change between versions. The link above is to the latest development version.

 It is possible to switch persistence from RDB snapshotting to append-only file (and the other way around) using the `CONFIG SET` command. For more information about how to do that please check the [persistence page](https://redis.io/topics/persistence).

 In general what you should know is that setting the `appendonly` parameter to `yes` will start a background process to save the initial append-only file (obtained from the in memory data set), and will append all the subsequent commands on the append-only file, thus obtaining exactly the same effect of a Redis server that started with AOF turned on since the start.

 You can have both the AOF enabled with RDB snapshotting if you want, the two options are not mutually exclusive.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` when the configuration was set properly. Otherwise an error is returned.

 History
-------

 * Starting with Redis version 7.0.0: Added the ability to set multiple parameters in one call.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/config-set/>

CLUSTER
=======



```
CLUSTER SETSLOT
```
 Syntax 
```
CLUSTER SETSLOT slot <IMPORTING node-id | MIGRATING node-id |
  NODE node-id | STABLE>
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   `CLUSTER SETSLOT` is responsible of changing the state of a hash slot in the receiving node in different ways. It can, depending on the subcommand used:

 1. `MIGRATING` subcommand: Set a hash slot in *migrating* state.
2. `IMPORTING` subcommand: Set a hash slot in *importing* state.
3. `STABLE` subcommand: Clear any importing / migrating state from hash slot.
4. `NODE` subcommand: Bind the hash slot to a different node.

 The command with its set of subcommands is useful in order to start and end cluster live resharding operations, which are accomplished by setting a hash slot in migrating state in the source node, and importing state in the destination node.

 Each subcommand is documented below. At the end you'll find a description of how live resharding is performed using this command and other related commands.

 CLUSTER SETSLOT `<slot>` MIGRATING `<destination-node-id>`
----------------------------------------------------------

 This subcommand sets a slot to *migrating* state. In order to set a slot in this state, the node receiving the command must be the hash slot owner, otherwise an error is returned.

 When a slot is set in migrating state, the node changes behavior in the following way:

 1. If a command is received about an existing key, the command is processed as usually.
2. If a command is received about a key that does not exists, an `ASK` redirection is emitted by the node, asking the client to retry only that specific query into `destination-node`. In this case the client should not update its hash slot to node mapping.
3. If the command contains multiple keys, in case none exist, the behavior is the same as point 2, if all exist, it is the same as point 1, however if only a partial number of keys exist, the command emits a `TRYAGAIN` error in order for the keys interested to finish being migrated to the target node, so that the multi keys command can be executed.

 CLUSTER SETSLOT `<slot>` IMPORTING `<source-node-id>`
-----------------------------------------------------

 This subcommand is the reverse of `MIGRATING`, and prepares the destination node to import keys from the specified source node. The command only works if the node is not already owner of the specified hash slot.

 When a slot is set in importing state, the node changes behavior in the following way:

 1. Commands about this hash slot are refused and a `MOVED` redirection is generated as usually, but in the case the command follows an [`ASKING`](../asking) command, in this case the command is executed.

 In this way when a node in migrating state generates an `ASK` redirection, the client contacts the target node, sends [`ASKING`](../asking), and immediately after sends the command. This way commands about non-existing keys in the old node or keys already migrated to the target node are executed in the target node, so that:

 1. New keys are always created in the target node. During a hash slot migration we'll have to move only old keys, not new ones.
2. Commands about keys already migrated are correctly processed in the context of the node which is the target of the migration, the new hash slot owner, in order to guarantee consistency.
3. Without [`ASKING`](../asking) the behavior is the same as usually. This guarantees that clients with a broken hash slots mapping will not write for error in the target node, creating a new version of a key that has yet to be migrated.

 CLUSTER SETSLOT `<slot>` STABLE
-------------------------------

 This subcommand just clears migrating / importing state from the slot. It is mainly used to fix a cluster stuck in a wrong state by `redis-cli --cluster fix`. Normally the two states are cleared automatically at the end of the migration using the `SETSLOT ... NODE ...` subcommand as explained in the next section.

 CLUSTER SETSLOT `<slot>` NODE `<node-id>`
-----------------------------------------

 The `NODE` subcommand is the one with the most complex semantics. It associates the hash slot with the specified node, however the command works only in specific situations and has different side effects depending on the slot state. The following is the set of pre-conditions and side effects of the command:

 1. If the current hash slot owner is the node receiving the command, but for effect of the command the slot would be assigned to a different node, the command will return an error if there are still keys for that hash slot in the node receiving the command.
2. If the slot is in *migrating* state, the state gets cleared when the slot is assigned to another node.
3. If the slot was in *importing* state in the node receiving the command, and the command assigns the slot to this node (which happens in the target node at the end of the resharding of a hash slot from one node to another), the command has the following side effects: A) the *importing* state is cleared. B) If the node config epoch is not already the greatest of the cluster, it generates a new one and assigns the new config epoch to itself. This way its new hash slot ownership will win over any past configuration created by previous failovers or slot migrations.

 It is important to note that step 3 is the only time when a Redis Cluster node will create a new config epoch without agreement from other nodes. This only happens when a manual configuration is operated. However it is impossible that this creates a non-transient setup where two nodes have the same config epoch, since Redis Cluster uses a config epoch collision resolution algorithm.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): All the subcommands return `OK` if the command was successful. Otherwise an error is returned.

 Redis Cluster live resharding explained
---------------------------------------

 The `CLUSTER SETSLOT` command is an important piece used by Redis Cluster in order to migrate all the keys contained in one hash slot from one node to another. This is how the migration is orchestrated, with the help of other commands as well. We'll call the node that has the current ownership of the hash slot the `source` node, and the node where we want to migrate the `destination` node.

 1. Set the destination node slot to *importing* state using `CLUSTER SETSLOT <slot> IMPORTING <source-node-id>`.
2. Set the source node slot to *migrating* state using `CLUSTER SETSLOT <slot> MIGRATING <destination-node-id>`.
3. Get keys from the source node with [`CLUSTER GETKEYSINSLOT`](../cluster-getkeysinslot) command and move them into the destination node using the [`MIGRATE`](../migrate) command.
4. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the destination node.
5. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the source node.
6. Send `CLUSTER SETSLOT <slot> NODE <destination-node-id>` to the other master nodes (optional).

 Notes:

 * The order of step 1 and 2 is important. We want the destination node to be ready to accept `ASK` redirections when the source node is configured to redirect.
* The order of step 4 and 5 is important. The destination node is responsible for propagating the change to the rest of the cluster. If the source node is informed before the destination node and the destination node crashes before it is set as new slot owner, the slot is left with no owner, even after a successful failover.
* Step 6, sending `SETSLOT` to the nodes not involved in the resharding, is not technically necessary since the configuration will eventually propagate itself. However, it is a good idea to do so in order to stop nodes from pointing to the wrong node for the hash slot moved as soon as possible, resulting in less redirections to find the right node.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cluster-setslot/>

CONFIG
======



```
CONFIG REWRITE
```
 Syntax 
```
CONFIG REWRITE
```
  Available since: 2.8.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `CONFIG REWRITE` command rewrites the `redis.conf` file the server was started with, applying the minimal changes needed to make it reflect the configuration currently used by the server, which may be different compared to the original one because of the use of the [`CONFIG SET`](../config-set) command.

 The rewrite is performed in a very conservative way:

 * Comments and the overall structure of the original redis.conf are preserved as much as possible.
* If an option already exists in the old redis.conf file, it will be rewritten at the same position (line number).
* If an option was not already present, but it is set to its default value, it is not added by the rewrite process.
* If an option was not already present, but it is set to a non-default value, it is appended at the end of the file.
* Non used lines are blanked. For instance if you used to have multiple `save` directives, but the current configuration has fewer or none as you disabled RDB persistence, all the lines will be blanked.

 CONFIG REWRITE is also able to rewrite the configuration file from scratch if the original one no longer exists for some reason. However if the server was started without a configuration file at all, the CONFIG REWRITE will just return an error.

 Atomic rewrite process
----------------------

 In order to make sure the redis.conf file is always consistent, that is, on errors or crashes you always end with the old file, or the new one, the rewrite is performed with a single `write(2)` call that has enough content to be at least as big as the old file. Sometimes additional padding in the form of comments is added in order to make sure the resulting file is big enough, and later the file gets truncated to remove the padding at the end.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` when the configuration was rewritten properly. Otherwise an error is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/config-rewrite/>

COPY
====



```
COPY
```
 Syntax 
```
COPY source destination [DB destination-db] [REPLACE]
```
  Available since: 6.2.0 Time complexity: O(N) worst case for collections, where N is the number of nested items. O(1) for string values. ACL categories:  `@keyspace`, `@write`, `@slow`,   This command copies the value stored at the `source` key to the `destination` key.

 By default, the `destination` key is created in the logical database used by the connection. The `DB` option allows specifying an alternative logical database index for the destination key.

 The command returns an error when the `destination` key already exists. The `REPLACE` option removes the `destination` key before copying the value to it.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if `source` was copied.
* `0` if `source` was not copied.

 Examples
--------

 
```
SET dolly "sheep"
COPY dolly clone
GET clone

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/copy/>

DISCARD
=======



```
DISCARD
```
 Syntax 
```
DISCARD
```
  Available since: 2.0.0 Time complexity: O(N), when N is the number of queued commands ACL categories:  `@fast`, `@transaction`,   Flushes all previously queued commands in a [transaction](https://redis.io/topics/transactions) and restores the connection state to normal.

 If [`WATCH`](../watch) was used, `DISCARD` unwatches all keys watched by the connection.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/discard/>

CMS.INITBYDIM
=============



```
CMS.INITBYDIM
```
 Syntax 
```
CMS.INITBYDIM key width depth
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Initializes a Count-Min Sketch to dimensions specified by user.

 ### Parameters:

 * **key**: The name of the sketch.
* **width**: Number of counters in each array. Reduces the error size.
* **depth**: Number of counter-arrays. Reduces the probability for an error of a certain size (percentage of total count).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> CMS.INITBYDIM test 2000 5
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/cms.initbydim/>

EXEC
====



```
EXEC
```
 Syntax 
```
EXEC
```
  Available since: 1.2.0 Time complexity: Depends on commands in the transaction ACL categories:  `@slow`, `@transaction`,   Executes all previously queued commands in a [transaction](https://redis.io/topics/transactions) and restores the connection state to normal.

 When using [`WATCH`](../watch), `EXEC` will execute commands only if the watched keys were not modified, allowing for a [check-and-set mechanism](https://redis.io/topics/transactions#cas).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): each element being the reply to each of the commands in the atomic transaction.

 When using [`WATCH`](../watch), `EXEC` can return a [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) if the execution was aborted.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/exec/>

EVAL
====



```
EVAL
```
 Syntax 
```
EVAL script numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 2.6.0 Time complexity: Depends on the script that is executed. ACL categories:  `@slow`, `@scripting`,   Invoke the execution of a server-side Lua script.

 The first argument is the script's source code. Scripts are written in [Lua](https://lua.org) and executed by the embedded [Lua 5.1](https://redis.io/topics/lua-api) interpreter in Redis.

 The second argument is the number of input key name arguments, followed by all the keys accessed by the script. These names of input keys are available to the script as the [*KEYS* global runtime variable](https://redis.io/topics/lua-api#the-keys-global-variable) Any additional input arguments **should not** represent names of keys.

 **Important:** to ensure the correct execution of scripts, both in standalone and clustered deployments, all names of keys that a script accesses must be explicitly provided as input key arguments. The script **should only** access keys whose names are given as input arguments. Scripts **should never** access keys with programmatically-generated names or based on the contents of data structures stored in the database.

 Please refer to the [Redis Programmability](https://redis.io/topics/programmability) and [Introduction to Eval Scripts](https://redis.io/topics/eval-intro) for more information about Lua scripts.

 Examples
--------

 The following example will run a script that returns the first argument that it gets.

 
```
> EVAL "return ARGV[1]" 0 hello
"hello"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/eval/>

EVALSHA\_RO
===========



```
EVALSHA_RO
```
 Syntax 
```
EVALSHA_RO sha1 numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: Depends on the script that is executed. ACL categories:  `@slow`, `@scripting`,   This is a read-only variant of the [`EVALSHA`](../evalsha) command that cannot execute commands that modify data.

 For more information about when to use this command vs [`EVALSHA`](../evalsha), please refer to [Read-only scripts](https://redis.io/docs/manual/programmability/#read-only_scripts).

 For more information about [`EVALSHA`](../evalsha) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/evalsha_ro/>

ECHO
====



```
ECHO
```
 Syntax 
```
ECHO message
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Returns `message`.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)

 Examples
--------

 
```

ECHO "Hello World!"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/echo/>

EXISTS
======



```
EXISTS
```
 Syntax 
```
EXISTS key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of keys to check. ACL categories:  `@keyspace`, `@read`, `@fast`,   Returns if `key` exists.

 The user should be aware that if the same existing key is mentioned in the arguments multiple times, it will be counted multiple times. So if `somekey` exists, `EXISTS somekey somekey` will return 2.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically the number of keys that exist from those specified as arguments.

 Examples
--------

 
```

SET key1 "Hello"
EXISTS key1
EXISTS nosuchkey
SET key2 "World"
EXISTS key1 key2 nosuchkey

```
 History
-------

 * Starting with Redis version 3.0.3: Accepts multiple `key` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/exists/>

EXPIRE
======



```
EXPIRE
```
 Syntax 
```
EXPIRE key seconds [NX | XX | GT | LT]
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   Set a timeout on `key`. After the timeout has expired, the key will automatically be deleted. A key with an associated timeout is often said to be *volatile* in Redis terminology.

 The timeout will only be cleared by commands that delete or overwrite the contents of the key, including [`DEL`](../del), [`SET`](../set), [`GETSET`](../getset) and all the `*STORE` commands. This means that all the operations that conceptually *alter* the value stored at the key without replacing it with a new one will leave the timeout untouched. For instance, incrementing the value of a key with [`INCR`](../incr), pushing a new value into a list with [`LPUSH`](../lpush), or altering the field value of a hash with [`HSET`](../hset) are all operations that will leave the timeout untouched.

 The timeout can also be cleared, turning the key back into a persistent key, using the [`PERSIST`](../persist) command.

 If a key is renamed with [`RENAME`](../rename), the associated time to live is transferred to the new key name.

 If a key is overwritten by [`RENAME`](../rename), like in the case of an existing key `Key_A` that is overwritten by a call like `RENAME Key_B Key_A`, it does not matter if the original `Key_A` had a timeout associated or not, the new key `Key_A` will inherit all the characteristics of `Key_B`.

 Note that calling `EXPIRE`/[`PEXPIRE`](../pexpire) with a non-positive timeout or [`EXPIREAT`](../expireat)/[`PEXPIREAT`](../pexpireat) with a time in the past will result in the key being [deleted](../del) rather than expired (accordingly, the emitted [key event](https://redis.io/topics/notifications) will be `del`, not `expired`).

 Options
-------

 The `EXPIRE` command supports a set of options:

 * `NX` -- Set expiry only when the key has no expiry
* `XX` -- Set expiry only when the key has an existing expiry
* `GT` -- Set expiry only when the new expiry is greater than current one
* `LT` -- Set expiry only when the new expiry is less than current one

 A non-volatile key is treated as an infinite TTL for the purpose of `GT` and `LT`. The `GT`, `LT` and `NX` options are mutually exclusive.

 Refreshing expires
------------------

 It is possible to call `EXPIRE` using as argument a key that already has an existing expire set. In this case the time to live of a key is *updated* to the new value. There are many useful applications for this, an example is documented in the *Navigation session* pattern section below.

 Differences in Redis prior 2.1.3
--------------------------------

 In Redis versions prior **2.1.3** altering a key with an expire set using a command altering its value had the effect of removing the key entirely. This semantics was needed because of limitations in the replication layer that are now fixed.

 `EXPIRE` would return 0 and not alter the timeout for a key with a timeout set.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the timeout was set.
* `0` if the timeout was not set. e.g. key doesn't exist, or operation skipped due to the provided arguments.

 Examples
--------

 
```

SET mykey "Hello"
EXPIRE mykey 10
TTL mykey
SET mykey "Hello World"
TTL mykey
EXPIRE mykey 10 XX
TTL mykey
EXPIRE mykey 10 NX
TTL mykey

```
 Pattern: Navigation session
---------------------------

 Imagine you have a web service and you are interested in the latest N pages *recently* visited by your users, such that each adjacent page view was not performed more than 60 seconds after the previous. Conceptually you may consider this set of page views as a *Navigation session* of your user, that may contain interesting information about what kind of products he or she is looking for currently, so that you can recommend related products.

 You can easily model this pattern in Redis using the following strategy: every time the user does a page view you call the following commands:

 
```
MULTI
RPUSH pagewviews.user:<userid> http://.....
EXPIRE pagewviews.user:<userid> 60
EXEC

```

If the user will be idle more than 60 seconds, the key will be deleted and only subsequent page views that have less than 60 seconds of difference will be recorded.

 This pattern is easily modified to use counters using [`INCR`](../incr) instead of lists using [`RPUSH`](../rpush).

 Appendix: Redis expires
=======================

 Keys with an expire
-------------------

 Normally Redis keys are created without an associated time to live. The key will simply live forever, unless it is removed by the user in an explicit way, for instance using the [`DEL`](../del) command.

 The `EXPIRE` family of commands is able to associate an expire to a given key, at the cost of some additional memory used by the key. When a key has an expire set, Redis will make sure to remove the key when the specified amount of time elapsed.

 The key time to live can be updated or entirely removed using the `EXPIRE` and [`PERSIST`](../persist) command (or other strictly related commands).

 Expire accuracy
---------------

 In Redis 2.4 the expire might not be pin-point accurate, and it could be between zero to one seconds out.

 Since Redis 2.6 the expire error is from 0 to 1 milliseconds.

 Expires and persistence
-----------------------

 Keys expiring information is stored as absolute Unix timestamps (in milliseconds in case of Redis version 2.6 or greater). This means that the time is flowing even when the Redis instance is not active.

 For expires to work well, the computer time must be taken stable. If you move an RDB file from two computers with a big desync in their clocks, funny things may happen (like all the keys loaded to be expired at loading time).

 Even running instances will always check the computer clock, so for instance if you set a key with a time to live of 1000 seconds, and then set your computer time 2000 seconds in the future, the key will be expired immediately, instead of lasting for 1000 seconds.

 How Redis expires keys
----------------------

 Redis keys are expired in two ways: a passive way, and an active way.

 A key is passively expired simply when some client tries to access it, and the key is found to be timed out.

 Of course this is not enough as there are expired keys that will never be accessed again. These keys should be expired anyway, so periodically Redis tests a few keys at random among keys with an expire set. All the keys that are already expired are deleted from the keyspace.

 Specifically this is what Redis does 10 times per second:

 1. Test 20 random keys from the set of keys with an associated expire.
2. Delete all the keys found expired.
3. If more than 25% of keys were expired, start again from step 1.

 This is a trivial probabilistic algorithm, basically the assumption is that our sample is representative of the whole key space, and we continue to expire until the percentage of keys that are likely to be expired is under 25%

 This means that at any given moment the maximum amount of keys already expired that are using memory is at max equal to max amount of write operations per second divided by 4.

 How expires are handled in the replication link and AOF file
------------------------------------------------------------

 In order to obtain a correct behavior without sacrificing consistency, when a key expires, a [`DEL`](../del) operation is synthesized in both the AOF file and gains all the attached replicas nodes. This way the expiration process is centralized in the master instance, and there is no chance of consistency errors.

 However while the replicas connected to a master will not expire keys independently (but will wait for the [`DEL`](../del) coming from the master), they'll still take the full state of the expires existing in the dataset, so when a replica is elected to master it will be able to expire the keys independently, fully acting as a master.

 History
-------

 * Starting with Redis version 7.0.0: Added options: `NX`, `XX`, `GT` and `LT`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/expire/>

DUMP
====



```
DUMP
```
 Syntax 
```
DUMP key
```
  Available since: 2.6.0 Time complexity: O(1) to access the key and additional O(N\*M) to serialize it, where N is the number of Redis objects composing the value and M their average size. For small string values the time complexity is thus O(1)+O(1\*M) where M is small, so simply O(1). ACL categories:  `@keyspace`, `@read`, `@slow`,   Serialize the value stored at key in a Redis-specific format and return it to the user. The returned value can be synthesized back into a Redis key using the [`RESTORE`](../restore) command.

 The serialization format is opaque and non-standard, however it has a few semantic characteristics:

 * It contains a 64-bit checksum that is used to make sure errors will be detected. The [`RESTORE`](../restore) command makes sure to check the checksum before synthesizing a key using the serialized value.
* Values are encoded in the same format used by RDB.
* An RDB version is encoded inside the serialized value, so that different Redis versions with incompatible RDB formats will refuse to process the serialized value.

 The serialized value does NOT contain expire information. In order to capture the time to live of the current value the [`PTTL`](../pttl) command should be used.

 If `key` does not exist a nil bulk reply is returned.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the serialized value.

 Examples
--------

 
```
> SET mykey 10
OK
> DUMP mykey
"\x00\xc0\n\n\x00n\x9fWE\x0e\xaec\xbb"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/dump/>

EVAL\_RO
========



```
EVAL_RO
```
 Syntax 
```
EVAL_RO script numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: Depends on the script that is executed. ACL categories:  `@slow`, `@scripting`,   This is a read-only variant of the [`EVAL`](../eval) command that cannot execute commands that modify data.

 For more information about when to use this command vs [`EVAL`](../eval), please refer to [Read-only scripts](https://redis.io/docs/manual/programmability/#read-only_scripts).

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Examples
--------

 
```
> SET mykey "Hello"
OK

> EVAL_RO "return redis.call('GET', KEYS[1])" 1 mykey
"Hello"

> EVAL_RO "return redis.call('DEL', KEYS[1])" 1 mykey
(error) ERR Error running script (call to b0d697da25b13e49157b2c214a4033546aba2104): @user_script:1: @user_script: 1: Write commands are not allowed from read-only scripts.

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/eval_ro/>

FT.ALIASADD
===========



```
FT.ALIASADD
```
 Syntax 
```
FT.ALIASADD alias index

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Add an alias to an index

 [Examples](#examples)

 Required arguments
------------------

  `alias index` is alias to be added to an index.

  Indexes can have more than one alias, but an alias cannot refer to another alias.

 FT.ALISSADD allows administrators to transparently redirect application queries to alternative indexes.

 Return
------

 FT.ALIASADD returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Add an alias to an index** Add an alias to an index.

 
```
127.0.0.1:6379> FT.ALIASADD alias idx
OK
```
 Attempting to add the same alias returns a message that the alias already exists.

 
```
127.0.0.1:6379> FT.ALIASADD alias idx
(error) Alias already exists
```
  See also
--------

 [`FT.ALIASDEL`](../ft.aliasdel) | [`FT.ALIASUPDATE`](../ft.aliasupdate)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.aliasadd/>

EVALSHA
=======



```
EVALSHA
```
 Syntax 
```
EVALSHA sha1 numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 2.6.0 Time complexity: Depends on the script that is executed. ACL categories:  `@slow`, `@scripting`,   Evaluate a script from the server's cache by its SHA1 digest.

 The server caches scripts by using the [`SCRIPT LOAD`](../script-load) command. The command is otherwise identical to [`EVAL`](../eval).

 Please refer to the [Redis Programmability](https://redis.io/topics/programmability) and [Introduction to Eval Scripts](https://redis.io/topics/eval-intro) for more information about Lua scripts.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/evalsha/>

FAILOVER
========



```
FAILOVER
```
 Syntax 
```
FAILOVER [TO host port [FORCE]] [ABORT] [TIMEOUT milliseconds]
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command will start a coordinated failover between the currently-connected-to master and one of its replicas. The failover is not synchronous, instead a background task will handle coordinating the failover. It is designed to limit data loss and unavailability of the cluster during the failover. This command is analogous to the [`CLUSTER FAILOVER`](../cluster-failover) command for non-clustered Redis and is similar to the failover support provided by sentinel.

 The specific details of the default failover flow are as follows:

 1. The master will internally start a `CLIENT PAUSE WRITE`, which will pause incoming writes and prevent the accumulation of new data in the replication stream.
2. The master will monitor its replicas, waiting for a replica to indicate that it has fully consumed the replication stream. If the master has multiple replicas, it will only wait for the first replica to catch up.
3. The master will then demote itself to a replica. This is done to prevent any dual master scenarios. NOTE: The master will not discard its data, so it will be able to rollback if the replica rejects the failover request in the next step.
4. The previous master will send a special PSYNC request to the target replica, `PSYNC FAILOVER`, instructing the target replica to become a master.
5. Once the previous master receives acknowledgement the `PSYNC FAILOVER` was accepted it will unpause its clients. If the PSYNC request is rejected, the master will abort the failover and return to normal.

 The field `master_failover_state` in `INFO replication` can be used to track the current state of the failover, which has the following values:

 * `no-failover`: There is no ongoing coordinated failover.
* `waiting-for-sync`: The master is waiting for the replica to catch up to its replication offset.
* `failover-in-progress`: The master has demoted itself, and is attempting to hand off ownership to a target replica.

 If the previous master had additional replicas attached to it, they will continue replicating from it as chained replicas. You will need to manually execute a [`REPLICAOF`](../replicaof) on these replicas to start replicating directly from the new master.

 Optional arguments
------------------

 The following optional arguments exist to modify the behavior of the failover flow:

 * `TIMEOUT` *milliseconds* -- This option allows specifying a maximum time a master will wait in the `waiting-for-sync` state before aborting the failover attempt and rolling back. This is intended to set an upper bound on the write outage the Redis cluster can experience. Failovers typically happen in less than a second, but could take longer if there is a large amount of write traffic or the replica is already behind in consuming the replication stream. If this value is not specified, the timeout can be considered to be "infinite".
* `TO` *HOST* *PORT* -- This option allows designating a specific replica, by its host and port, to failover to. The master will wait specifically for this replica to catch up to its replication offset, and then failover to it.
* `FORCE` -- If both the `TIMEOUT` and `TO` options are set, the force flag can also be used to designate that that once the timeout has elapsed, the master should failover to the target replica instead of rolling back. This can be used for a best-effort attempt at a failover without data loss, but limiting write outage.

 NOTE: The master will always rollback if the `PSYNC FAILOVER` request is rejected by the target replica.

 Failover abort
--------------

 The failover command is intended to be safe from data loss and corruption, but can encounter some scenarios it can not automatically remediate from and may get stuck. For this purpose, the `FAILOVER ABORT` command exists, which will abort an ongoing failover and return the master to its normal state. The command has no side effects if issued in the `waiting-for-sync` state but can introduce multi-master scenarios in the `failover-in-progress` state. If a multi-master scenario is encountered, you will need to manually identify which master has the latest data and designate it as the master and have the other replicas.

 NOTE: [`REPLICAOF`](../replicaof) is disabled while a failover is in progress, this is to prevent unintended interactions with the failover that might cause data loss.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if the command was accepted and a coordinated failover is in progress. An error if the operation cannot be executed.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/failover/>

EXPIREAT
========



```
EXPIREAT
```
 Syntax 
```
EXPIREAT key unix-time-seconds [NX | XX | GT | LT]
```
  Available since: 1.2.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   `EXPIREAT` has the same effect and semantic as [`EXPIRE`](../expire), but instead of specifying the number of seconds representing the TTL (time to live), it takes an absolute [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time) (seconds since January 1, 1970). A timestamp in the past will delete the key immediately.

 Please for the specific semantics of the command refer to the documentation of [`EXPIRE`](../expire).

 Background
----------

 `EXPIREAT` was introduced in order to convert relative timeouts to absolute timeouts for the AOF persistence mode. Of course, it can be used directly to specify that a given key should expire at a given time in the future.

 Options
-------

 The `EXPIREAT` command supports a set of options:

 * `NX` -- Set expiry only when the key has no expiry
* `XX` -- Set expiry only when the key has an existing expiry
* `GT` -- Set expiry only when the new expiry is greater than current one
* `LT` -- Set expiry only when the new expiry is less than current one

 A non-volatile key is treated as an infinite TTL for the purpose of `GT` and `LT`. The `GT`, `LT` and `NX` options are mutually exclusive.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the timeout was set.
* `0` if the timeout was not set. e.g. key doesn't exist, or operation skipped due to the provided arguments.

 Examples
--------

 
```

SET mykey "Hello"
EXISTS mykey
EXPIREAT mykey 1293840000
EXISTS mykey

```
 History
-------

 * Starting with Redis version 7.0.0: Added options: `NX`, `XX`, `GT` and `LT`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/expireat/>

FCALL\_RO
=========



```
FCALL_RO
```
 Syntax 
```
FCALL_RO function numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: Depends on the function that is executed. ACL categories:  `@slow`, `@scripting`,   This is a read-only variant of the [`FCALL`](../fcall) command that cannot execute commands that modify data.

 For more information about when to use this command vs [`FCALL`](../fcall), please refer to [Read-only scripts](https://redis.io/docs/manual/programmability/#read-only_scripts).

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/fcall_ro/>

FCALL
=====



```
FCALL
```
 Syntax 
```
FCALL function numkeys [key [key ...]] [arg [arg ...]]
```
  Available since: 7.0.0 Time complexity: Depends on the function that is executed. ACL categories:  `@slow`, `@scripting`,   Invoke a function.

 Functions are loaded to the server with the [`FUNCTION LOAD`](../function-load) command. The first argument is the name of a loaded function.

 The second argument is the number of input key name arguments, followed by all the keys accessed by the function. In Lua, these names of input keys are available to the function as a table that is the callback's first argument.

 **Important:** To ensure the correct execution of functions, both in standalone and clustered deployments, all names of keys that a function accesses must be explicitly provided as input key arguments. The function **should only** access keys whose names are given as input arguments. Functions **should never** access keys with programmatically-generated names or based on the contents of data structures stored in the database.

 Any additional input argument **should not** represent names of keys. These are regular arguments and are passed in a Lua table as the callback's second argument.

 For more information please refer to the [Redis Programmability](https://redis.io/topics/programmability) and [Introduction to Redis Functions](https://redis.io/topics/functions-intro) pages.

 Examples
--------

 The following example will create a library named `mylib` with a single function, `myfunc`, that returns the first argument it gets.

 
```
redis> FUNCTION LOAD "#!lua name=mylib \n redis.register_function('myfunc', function(keys, args) return args[1] end)"
"mylib"
redis> FCALL myfunc 0 hello
"hello"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/fcall/>

FT.CREATE
=========



```
FT.CREATE
```
 Syntax 
```
FT.CREATE index 
  [ON HASH | JSON] 
  [PREFIX count prefix [prefix ...]] 
  [FILTER {filter}]
  [LANGUAGE default_lang] 
  [LANGUAGE_FIELD lang_attribute] 
  [SCORE default_score] 
  [SCORE_FIELD score_attribute] 
  [PAYLOAD_FIELD payload_attribute] 
  [MAXTEXTFIELDS] 
  [TEMPORARY seconds] 
  [NOOFFSETS] 
  [NOHL] 
  [NOFIELDS] 
  [NOFREQS] 
  [STOPWORDS count [stopword ...]] 
  [SKIPINITIALSCAN]
  SCHEMA field_name [AS alias] TEXT | TAG | NUMERIC | GEO | VECTOR [ SORTABLE [UNF]] 
  [NOINDEX] [ field_name [AS alias] TEXT | TAG | NUMERIC | GEO | VECTOR [ SORTABLE [UNF]] [NOINDEX] ...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(K) at creation where K is the number of fields, O(N) if scanning the keyspace is triggered, where N is the number of keys in the keyspace  Description
-----------

 Create an index with the given specification. For usage, see [Examples](#examples).

 Required arguments
------------------

 `index` is index name to create. If it exists, the old specification is overwritten.

 `SCHEMA {identifier} AS {attribute} {attribute type} {options...` after the SCHEMA keyword, declares which fields to index:

 * `{identifier}` for hashes, is a field name within the hash. For JSON, the identifier is a JSON Path expression.
* `AS {attribute}` defines the attribute associated to the identifier. For example, you can use this feature to alias a complex JSONPath expression with more memorable (and easier to type) name.

 Field types are:

 * `TEXT` - Allows full-text search queries against the value in this attribute.
* `TAG` - Allows exact-match queries, such as categories or primary keys, against the value in this attribute. For more information, see [Tag Fields](https://redis.io/docs/stack/search/reference/tags).
* `NUMERIC` - Allows numeric range queries against the value in this attribute. See [query syntax docs](https://redis.io/docs/stack/search/reference/query_syntax) for details on how to use numeric ranges.
* `GEO` - Allows geographic range queries against the value in this attribute. The value of the attribute must be a string containing a longitude (first) and latitude separated by a comma.
* `VECTOR` - Allows vector similarity queries against the value in this attribute. For more information, see [Vector Fields](https://redis.io/docs/stack/search/reference/vectors).

 Field options are:

 * `SORTABLE` - `NUMERIC`, `TAG`, `TEXT`, or `GEO` attributes can have an optional **SORTABLE** argument. As the user [sorts the results by the value of this attribute](https://redis.io/docs/stack/search/reference/sorting), the results are available with very low latency. Note that his adds memory overhead, so consider not declaring it on large text attributes. You can sort an attribute without the `SORTABLE` option, but the latency is not as good as with `SORTABLE`.
* `UNF` - By default, for hashes (not with JSON) `SORTABLE` applies a normalization to the indexed value (characters set to lowercase, removal of diacritics). When using the unnormalized form (UNF), you can disable the normalization and keep the original form of the value. With JSON, `UNF` is implicit with `SORTABLE` (normalization is disabled).
* `NOSTEM` - Text attributes can have the NOSTEM argument that disables stemming when indexing its values. This may be ideal for things like proper names.
* `NOINDEX` - Attributes can have the `NOINDEX` option, which means they will not be indexed. This is useful in conjunction with `SORTABLE`, to create attributes whose update using PARTIAL will not cause full reindexing of the document. If an attribute has NOINDEX and doesn't have SORTABLE, it will just be ignored by the index.
* `PHONETIC {matcher}` - Declaring a text attribute as `PHONETIC` will perform phonetic matching on it in searches by default. The obligatory {matcher} argument specifies the phonetic algorithm and language used. The following matchers are supported:


	+ `dm:en` - Double metaphone for English
	+ `dm:fr` - Double metaphone for French
	+ `dm:pt` - Double metaphone for Portuguese
	+ `dm:es` - Double metaphone for SpanishFor more information, see [Phonetic Matching](https://redis.io/docs/stack/search/reference/phonetic_matching).
* `WEIGHT {weight}` for `TEXT` attributes, declares the importance of this attribute when calculating result accuracy. This is a multiplication factor, and defaults to 1 if not specified.
* `SEPARATOR {sep}` for `TAG` attributes, indicates how the text contained in the attribute is to be split into individual tags. The default is `,`. The value must be a single character.
* `CASESENSITIVE` for `TAG` attributes, keeps the original letter cases of the tags. If not specified, the characters are converted to lowercase.
* `WITHSUFFIXTRIE` for `TEXT` and `TAG` attributes, keeps a suffix trie with all terms which match the suffix. It is used to optimize `contains` (*foo*) and `suffix` (\*foo) queries. Otherwise, a brute-force search on the trie is performed. If suffix trie exists for some fields, these queries will be disabled for other fields.

 Optional arguments
------------------

 `ON {data_type}` currently supports HASH (default) and JSON. To index JSON, you must have the [RedisJSON](https://redis.io/docs/stack/json) module installed.

 `PREFIX {count} {prefix}` tells the index which keys it should index. You can add several prefixes to index. Because the argument is optional, the default is `*` (all keys).

 `FILTER {filter}` is a filter expression with the full RediSearch aggregation expression language. It is possible to use `@__key` to access the key that was just added/changed. A field can be used to set field name by passing `'FILTER @indexName=="myindexname"'`.

 `LANGUAGE {default_lang}` if set, indicates the default language for documents in the index. Default is English.

 `LANGUAGE_FIELD {lang_attribute}` is document attribute set as the document language.

 A stemmer is used for the supplied language during indexing. If an unsupported language is sent, the command returns an error. The supported languages are Arabic, Basque, Catalan, Danish, Dutch, English, Finnish, French, German, Greek, Hungarian, Indonesian, Irish, Italian, Lithuanian, Nepali, Norwegian, Portuguese, Romanian, Russian, Spanish, Swedish, Tamil, Turkish, and Chinese.

 When adding Chinese language documents, set `LANGUAGE chinese` for the indexer to properly tokenize the terms. If you use the default language, then search terms are extracted based on punctuation characters and whitespace. The Chinese language tokenizer makes use of a segmentation algorithm (via [Friso](https://github.com/lionsoul2014/friso)), which segments text and checks it against a predefined dictionary. See [Stemming](https://redis.io/docs/stack/search/reference/stemming) for more information.

 `SCORE {default_score}` is default score for documents in the index. Default score is 1.0.

 `SCORE_FIELD {score_attribute}` is document attribute that you use as the document rank based on the user ranking. Ranking must be between 0.0 and 1.0. If not set, the default score is 1.

 `PAYLOAD_FIELD {payload_attribute}` is document attribute that you use as a binary safe payload string to the document that can be evaluated at query time by a custom scoring function or retrieved to the client.

 `MAXTEXTFIELDS` forces RediSearch to encode indexes as if there were more than 32 text attributes, which allows you to add additional attributes (beyond 32) using [`FT.ALTER`](../ft.alter). For efficiency, RediSearch encodes indexes differently if they are created with less than 32 text attributes.

 `NOOFFSETS` does not store term offsets for documents. It saves memory, but does not allow exact searches or highlighting. It implies `NOHL`.

 `TEMPORARY {seconds}` creates a lightweight temporary index that expires after a specified period of inactivity, in seconds. The internal idle timer is reset whenever the index is searched or added to. Because such indexes are lightweight, you can create thousands of such indexes without negative performance implications and, therefore, you should consider using `SKIPINITIALSCAN` to avoid costly scanning.

  Warning When temporary indexes expire, they drop all the records associated with them. [`FT.DROPINDEX`](../ft.dropindex) was introduced with a default of not deleting docs and a `DD` flag that enforced deletion. However, for temporary indexes, documents are deleted along with the index. Historically, RediSearch used an FT.ADD command, which made a connection between the document and the index. Then, FT.DROP, also a hystoric command, deleted documents by default. In version 2.x, RediSearch indexes hashes and JSONs, and the dependency between the index and documents no longer exists.

  `NOHL` conserves storage space and memory by disabling highlighting support. If set, the corresponding byte offsets for term positions are not stored. `NOHL` is also implied by `NOOFFSETS`.

 `NOFIELDS` does not store attribute bits for each term. It saves memory, but it does not allow filtering by specific attributes.

 `NOFREQS` avoids saving the term frequencies in the index. It saves memory, but does not allow sorting based on the frequencies of a given term within the document.

 `STOPWORDS {count}` sets the index with a custom stopword list, to be ignored during indexing and search time. `{count}` is the number of stopwords, followed by a list of stopword arguments exactly the length of `{count}`.

 If not set, FT.CREATE takes the default list of stopwords. If `{count}` is set to 0, the index does not have stopwords.

 `SKIPINITIALSCAN` if set, does not scan and index.

 **Notes:**

 * **Attribute number limits:** RediSearch supports up to 1024 attributes per schema, out of which at most 128 can be TEXT attributes. On 32 bit builds, at most 64 attributes can be TEXT attributes. The more attributes you have, the larger your index, as each additional 8 attributes require one extra byte per index record to encode. You can always use the `NOFIELDS` option and not encode attribute information into the index, for saving space, if you do not need filtering by text attributes. This will still allow filtering by numeric and geo attributes.
* **Running in clustered databases:** When having several indices in a clustered database, you need to make sure the documents you want to index reside on the same shard as the index. You can achieve this by having your documents tagged by the index name.

 
```
127.0.0.1:6379> HSET doc:1{idx} ...
127.0.0.1:6379> FT.CREATE idx ... PREFIX 1 doc: ...
```
 When Running RediSearch in a clustered database, you can span the index across shards using [RSCoordinator](https://github.com/RedisLabsModules/RSCoordinator). In this case the above does not apply.

 Return
------

 FT.CREATE returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Create an index** Create an index that stores the title, publication date, and categories of blog post hashes whose keys start with `blog:post:` (for example, `blog:post:1`).

 
```
127.0.0.1:6379> FT.CREATE idx ON HASH PREFIX 1 blog:post: SCHEMA title TEXT SORTABLE published\_at NUMERIC SORTABLE category TAG SORTABLE
OK
```
 Index the `sku` attribute from a hash as both a `TAG` and as `TEXT`:

 
```
127.0.0.1:6379> FT.CREATE idx ON HASH PREFIX 1 blog:post: SCHEMA sku AS sku\_text TEXT sku AS sku\_tag TAG SORTABLE
```
 Index two different hashes, one containing author data and one containing books, in the same index:

 
```
127.0.0.1:6379> FT.CREATE author-books-idx ON HASH PREFIX 2 author:details: book:details: SCHEMA
author\_id TAG SORTABLE author\_ids TAG title TEXT name TEXT
```
 In this example, keys for author data use the key pattern `author:details:<id>` while keys for book data use the pattern `book:details:<id>`.

   **Index a JSON document using a JSON Path expression** Index authors whose names start with G.

 
```
127.0.0.1:6379> FT.CREATE g-authors-idx ON HASH PREFIX 1 author:details FILTER 'startswith(@name, "G")' SCHEMA name TEXT
```
 Index only books that have a subtitle.

 
```
127.0.0.1:6379> FT.CREATE subtitled-books-idx ON HASH PREFIX 1 book:details FILTER '@subtitle != ""' SCHEMA title TEXT
```
 Index books that have a "categories" attribute where each category is separated by a `;` character.

 
```
127.0.0.1:6379> FT.CREATE books-idx ON HASH PREFIX 1 book:details FILTER SCHEMA title TEXT categories TAG SEPARATOR ";"
```
 Index a JSON document using a JSON Path expression.

 
```
127.0.0.1:6379> FT.CREATE idx ON JSON SCHEMA $.title AS title TEXT $.categories AS categories TAG
```
  See also
--------

 [`FT.ALTER`](../ft.alter) | [`FT.DROPINDEX`](../ft.dropindex)

 Related topics
--------------

 * [RediSearch](https://redis.io/docs/stack/search)
* [RedisJSON](https://redis.io/docs/stack/json)
* [Friso](https://github.com/lionsoul2014/friso)
* [Stemming](https://redis.io/docs/stack/search/reference/stemming)
* [Phonetic Matching](https://redis.io/docs/stack/search/reference/phonetic_matching)
* [RSCoordinator](https://github.com/RedisLabsModules/RSCoordinator)

 History
-------

 * Starting with Redis version 2.0.0: Added `PAYLOAD_FIELD` argument for backward support of `FT.SEARCH` deprecated `WITHPAYLOADS` argument
* Starting with Redis version 2.0.0: Deprecated `PAYLOAD_FIELD` argument



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.create/>

EXPIRETIME
==========



```
EXPIRETIME
```
 Syntax 
```
EXPIRETIME key
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   Returns the absolute Unix timestamp (since January 1, 1970) in seconds at which the given key will expire.

 See also the [`PEXPIRETIME`](../pexpiretime) command which returns the same information with milliseconds resolution.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): Expiration Unix timestamp in seconds, or a negative value in order to signal an error (see the description below).

 * The command returns `-1` if the key exists but has no associated expiration time.
* The command returns `-2` if the key does not exist.

 Examples
--------

 
```

SET mykey "Hello"
EXPIREAT mykey 33177117420
EXPIRETIME mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/expiretime/>

FLUSHALL
========



```
FLUSHALL
```
 Syntax 
```
FLUSHALL [ASYNC | SYNC]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of keys in all databases ACL categories:  `@keyspace`, `@write`, `@slow`, `@dangerous`,   Delete all the keys of all the existing databases, not just the currently selected one. This command never fails.

 By default, `FLUSHALL` will synchronously flush all the databases. Starting with Redis 6.2, setting the **lazyfree-lazy-user-flush** configuration directive to "yes" changes the default flush mode to asynchronous.

 It is possible to use one of the following modifiers to dictate the flushing mode explicitly:

 * `ASYNC`: flushes the databases asynchronously
* `SYNC`: flushes the databases synchronously

 Note: an asynchronous `FLUSHALL` command only deletes keys that were present at the time the command was invoked. Keys created during an asynchronous flush will be unaffected.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Behavior change history
-----------------------

 * `>= 6.2.0`: Default flush behavior now configurable by the **lazyfree-lazy-user-flush** configuration directive.

 History
-------

 * Starting with Redis version 4.0.0: Added the `ASYNC` flushing mode modifier.
* Starting with Redis version 6.2.0: Added the `SYNC` flushing mode modifier.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/flushall/>

FT.AGGREGATE
============



```
FT.AGGREGATE
```
 Syntax 
```
FT.AGGREGATE index query 
  [VERBATIM] 
  [ LOAD count field [field ...]] 
  [TIMEOUT timeout] 
  [LOAD *] 
  [ GROUPBY nargs property [property ...] [ REDUCE function nargs arg [arg ...] [AS name] [ REDUCE function nargs arg [arg ...] [AS name] ...]] 
  [ GROUPBY nargs property [property ...] [ REDUCE function nargs arg [arg ...] [AS name] [ REDUCE function nargs arg [arg ...] [AS name] ...]] ...]] 
  [ SORTBY nargs [ property ASC | DESC [ property ASC | DESC ...]] [MAX num]] 
  [ APPLY expression AS name [ APPLY expression AS name ...]] 
  [ LIMIT offset num] 
  [FILTER filter] 
  [ WITHCURSOR [COUNT read_size] [MAXIDLE idle_time]] 
  [ PARAMS nargs name value [ name value ...]] 
  [DIALECT dialect]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.1.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Run a search query on an index, and perform aggregate transformations on the results, extracting statistics etc from them

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name against which the query is executed. You must first create the index using [`FT.CREATE`](../ft.create).

   `query` is base filtering query that retrieves the documents. It follows the exact same syntax as the search query, including filters, unions, not, optional, and so on.

  Optional arguments
------------------

  `VERBATIM` if set, does not try to use stemming for query expansion but searches the query terms verbatim.

   `LOAD {nargs} {identifier} AS {property} …` loads document attributes from the source document.

 * `identifier` is either an attribute name for hashes and JSON or a JSON Path expression for JSON.
* `property` is the optional name used in the result. If it is not provided, the `identifier` is used. This should be avoided.
* If `*` is used as `nargs`, all attributes in a document are loaded.

 Attributes needed for aggregations should be stored as `SORTABLE`, where they are available to the aggregation pipeline with very low latency. `LOAD` hurts the performance of aggregate queries considerably because every processed record needs to execute the equivalent of [`HMGET`](../hmget) against a Redis key, which when executed over millions of keys, amounts to high processing times.

  `GROUPBY {nargs} {property}` groups the results in the pipeline based on one or more properties. Each group should have at least one *reducer*, a function that handles the group entries, either counting them, or performing multiple aggregate operations (see below).

  `REDUCE {func} {nargs} {arg} … [AS {name}]` reduces the matching results in each group into a single record, using a reduction function. For example, `COUNT` counts the number of records in the group. The reducers can have their own property names using the `AS {name}` optional argument. If a name is not given, the resulting name will be the name of the reduce function and the group properties. For example, if a name is not given to `COUNT_DISTINCT` by property `@foo`, the resulting name will be `count_distinct(@foo)`.

 See [Supported GROUPBY reducers](https://redis.io/docs/stack/search/reference/aggregations/#supported-groupby-reducers) for more details.

   `SORTBY {nargs} {property} {ASC|DESC} [MAX {num}]` sorts the pipeline up until the point of `SORTBY`, using a list of properties.

 * By default, sorting is ascending, but `ASC` or `DESC`  can be added for each property.
* `nargs` is the number of sorting parameters, including `ASC` and `DESC`, for example, `SORTBY 4 @foo ASC @bar DESC`.
* `MAX` is used to optimized sorting, by sorting only for the n-largest elements. Although it is not connected to `LIMIT`, you usually need just `SORTBY … MAX` for common queries.

 Attributes needed for `SORTBY` should be stored as `SORTABLE` to be available with very low latency.

  `APPLY {expr} AS {name}` applies a 1-to-1 transformation on one or more properties and either stores the result as a new property down the pipeline or replaces any property using this transformation.

 `expr` is an expression that can be used to perform arithmetic operations on numeric properties, or functions that can be applied on properties depending on their types (see below), or any combination thereof. For example, `APPLY "sqrt(@foo)/log(@bar) + 5" AS baz` evaluates this expression dynamically for each record in the pipeline and store the result as a new property called `baz`, which can be referenced by further `APPLY`/`SORTBY`/`GROUPBY`/`REDUCE` operations down the pipeline.

   `LIMIT {offset} {num}` limits the number of results to return just `num` results starting at index `offset` (zero-based). It is much more efficient to use `SORTBY … MAX` if you are interested in just limiting the output of a sort operation. If a key expires during the query, an attempt to `load` the key's value will return a null array.

 However, limit can be used to limit results without sorting, or for paging the n-largest results as determined by `SORTBY MAX`. For example, getting results 50-100 of the top 100 results is most efficiently expressed as `SORTBY 1 @foo MAX 100 LIMIT 50 50`. Removing the `MAX` from `SORTBY` results in the pipeline sorting *all* the records and then paging over results 50-100.

   `FILTER {expr}` filters the results using predicate expressions relating to values in each result. They are applied post query and relate to the current state of the pipeline.

   `WITHCURSOR {COUNT} {read_size} [MAXIDLE {idle_time}]` Scan part of the results with a quicker alternative than `LIMIT`. See [Cursor API](https://redis.io/docs/stack/search/reference/aggregations/#cursor-api) for more details.

   `TIMEOUT {milliseconds}` if set, overrides the timeout parameter of the module.

   `PARAMS {nargs} {name} {value}` defines one or more value parameters. Each parameter has a name and a value.

 You can reference parameters in the `query` by a `$`, followed by the parameter name, for example, `$user`. Each such reference in the search query to a parameter name is substituted by the corresponding parameter value. For example, with parameter definition `PARAMS 4 lon 29.69465 lat 34.95126`, the expression `@loc:[$lon $lat 10 km]` is evaluated to `@loc:[29.69465 34.95126 10 km]`. You cannot reference parameters in the query string where concrete values are not allowed, such as in field names, for example, `@loc`. To use `PARAMS`, set `DIALECT` to `2` or greater than `2`.

   `DIALECT {dialect_version}` selects the dialect version under which to execute the query. If not specified, the query will execute under the default dialect version set during module initial loading or via [`FT.CONFIG SET`](../ft.config-set) command.

  Return
------

 FT.AGGREGATE returns an array reply where each row is an array reply and represents a single aggregate result. The [integer reply](https://redis.io/docs/reference/protocol-spec/#resp-integers) at position `1` does not represent a valid value.

 ### Return multiple values

 See [Return multiple values](../ft.search#return-multiple-values) in [`FT.SEARCH`](../ft.search) The `DIALECT` can be specified as a parameter in the FT.AGGREGATE command. If it is not specified, the `DEFAULT_DIALECT` is used, which can be set using [`FT.CONFIG SET`](../ft.config-set) or by passing it as an argument to the `redisearch` module when it is loaded. For example, with the following document and index:

 
```
127.0.0.1:6379> JSON.SET doc:1 $ '[{"arr": [1, 2, 3]}, {"val": "hello"}, {"val": "world"}]'
OK
127.0.0.1:6379> FT.CREATE idx ON JSON PREFIX 1 doc: SCHEMA $..arr AS arr NUMERIC $..val AS val TEXT
OK

```

Notice the different replies, with and without `DIALECT 3`:

 
```
127.0.0.1:6379> FT.AGGREGATE idx \* LOAD 2 arr val 
1) (integer) 1
2) 1) "arr"
 2) "[1,2,3]"
 3) "val"
 4) "hello"
127.0.0.1:6379> FT.AGGREGATE idx \* LOAD 2 arr val DIALECT 3
1) (integer) 1
2) 1) "arr"
 2) "[[1,2,3]]"
 3) "val"
 4) "[\"hello\",\"world\"]"

```

Complexity
----------

 Non-deterministic. Depends on the query and aggregations performed, but it is usually linear to the number of results returned.

 Examples
--------

  **Sort page visits by day** Find visits to the page `about.html`, group them by the day of the visit, count the number of visits, and sort them by day.

 
```
FT.AGGREGATE idx "@url:\"about.html\""
 APPLY "day(@timestamp)" AS day
 GROUPBY 2 @day @country
 REDUCE count 0 AS num\_visits
 SORTBY 4 @day
```
   **Find most books ever published** Find most books ever published in a single year.

 
```
FT.AGGREGATE books-idx \*
 GROUPBY 1 @published\_year
 REDUCE COUNT 0 AS num\_published
 GROUPBY 0
 REDUCE MAX 1 @num\_published AS max\_books\_published\_per\_year
```
   **Reduce all results** The last example used `GROUPBY 0`. Use `GROUPBY 0` to apply a `REDUCE` function over all results from the last step of an aggregation pipeline -- this works on both the initial query and subsequent `GROUPBY` operations.

 Search for libraries within 10 kilometers of the longitude -73.982254 and latitude 40.753181 then annotate them with the distance between their location and those coordinates.

 
```
 FT.AGGREGATE libraries-idx "@location:[-73.982254 40.753181 10 km]"
 LOAD 1 @location
 APPLY "geodistance(@location, -73.982254, 40.753181)"
```
 Here, we needed to use `LOAD` to pre-load the `@location` attribute because it is a GEO attribute.

 Next, count GitHub events by user (actor), to produce the most active users.

 
```
127.0.0.1:6379> FT.AGGREGATE gh "\*" GROUPBY 1 @actor REDUCE COUNT 0 AS num SORTBY 2 @num DESC MAX 10
 1) (integer) 284784
 2) 1) "actor"
 2) "lombiqbot"
 3) "num"
 4) "22197"
 3) 1) "actor"
 2) "codepipeline-test"
 3) "num"
 4) "17746"
 4) 1) "actor"
 2) "direwolf-github"
 3) "num"
 4) "10683"
 5) 1) "actor"
 2) "ogate"
 3) "num"
 4) "6449"
 6) 1) "actor"
 2) "openlocalizationtest"
 3) "num"
 4) "4759"
 7) 1) "actor"
 2) "digimatic"
 3) "num"
 4) "3809"
 8) 1) "actor"
 2) "gugod"
 3) "num"
 4) "3512"
 9) 1) "actor"
 2) "xdzou"
 3) "num"
 4) "3216"
[10](10)) 1) "actor"
 2) "opstest"
 3) "num"
 4) "2863"
11) 1) "actor"
 2) "jikker"
 3) "num"
 4) "2794"
(0.59s)
```
  See also
--------

 [`FT.CONFIG SET`](../ft.config-set) | [`FT.SEARCH`](../ft.search)

 Related topics
--------------

 * [Aggregations](https://redis.io/docs/stack/search/reference/aggregations)
* [RediSearch](https://redis.io/docs/stack/search)

 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.aggregate/>

FT.\_LIST
=========



```
FT._LIST
```
 Syntax 
```
FT._LIST
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 2.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Returns a list of all existing indexes.

  Temporary command The prefix `_` in the command indicates, this is a temporary command.

 In the future, a [`SCAN`](../scan) type of command will be added, for use when a database contains a large number of indices.

  Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with index names.

 Examples
--------

 
```
FT.\_LIST1)"idx"2)"movies"3)"imdb"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft._list/>

FT.ALTER
========



```
FT.ALTER
```
 Syntax 
```
FT.ALTER {index} [SKIPINITIALSCAN] SCHEMA ADD {attribute} {options} ...

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(N) where N is the number of keys in the keyspace  Add a new attribute to the index. Adding an attribute to the index causes any future document updates to use the new attribute when indexing and reindexing existing documents.

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name to create.

   `SKIPINITIALSCAN` if set, does not scan and index.

   `SCHEMA ADD {attribute} {options} ...` after the SCHEMA keyword, declares which fields to add:

 * `attribute` is attribute to add.
* `options` are attribute options. Refer to [`FT.CREATE`](../ft.create) for more information.

 **Note:**

 Depending on how the index was created, you may be limited by the number of additional text attributes which can be added to an existing index. If the current index contains fewer than 32 text attributes, then `SCHEMA ADD` will only be able to add attributes up to 32 total attributes (meaning that the index will only ever be able to contain 32 total text attributes). If you wish for the index to contain more than 32 attributes, create it with the `MAXTEXTFIELDS` option. 

  Return
------

 FT.CREATE returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Alter an index** 
```
127.0.0.1:6379> FT.ALTER idx SCHEMA ADD id2 NUMERIC SORTABLE
OK
```
  See also
--------

 [`FT.CREATE`](../ft.create)

 Related topics
--------------

 * [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.alter/>

FT.CONFIG
=========



```
FT.CONFIG GET
```
 Syntax 
```
FT.CONFIG GET option

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Retrieve configuration options

 [Examples](#examples)

 Required arguments
------------------

  `option` is name of the configuration option, or '\*' for all.

  Return
------

 FT.CONFIG GET returns an array reply of the configuration name and value.

 Examples
--------

  **Retrieve configuration options** 
```
127.0.0.1:6379> FT.CONFIG GET TIMEOUT
1) 1) TIMEOUT
 2) 42
```
 
```
127.0.0.1:6379> FT.CONFIG GET \*
 1) 1) EXTLOAD
 2) (nil)
 2) 1) SAFEMODE
 2) true
 3) 1) CONCURRENT\_WRITE\_MODE
 2) false
 4) 1) NOGC
 2) false
 5) 1) MINPREFIX
 2) 2
 6) 1) FORKGC\_SLEEP\_BEFORE\_EXIT
 2) 0
 7) 1) MAXDOCTABLESIZE
 2) 1000000
 8) 1) MAXSEARCHRESULTS
 2) 1000000
 9) 1) MAXAGGREGATERESULTS
 2) unlimited
10) 1) MAXEXPANSIONS
 2) 200
11) 1) MAXPREFIXEXPANSIONS
 2) 200
12) 1) TIMEOUT
 2) 42
13) 1) INDEX\_THREADS
 2) 8
14) 1) SEARCH\_THREADS
 2) 20
15) 1) FRISOINI
 2) (nil)
16) 1) ON\_TIMEOUT
 2) return
17) 1) GCSCANSIZE
 2) 100
18) 1) MIN\_PHONETIC\_TERM\_LEN
 2) 3
19) 1) GC\_POLICY
 2) fork
20) 1) FORK\_GC\_RUN\_INTERVAL
 2) 30
21) 1) FORK\_GC\_CLEAN\_THRESHOLD
 2) 100
22) 1) FORK\_GC\_RETRY\_INTERVAL
 2) 5
23) 1) FORK\_GC\_CLEAN\_NUMERIC\_EMPTY\_NODES
 2) true
24) 1) \_FORK\_GC\_CLEAN\_NUMERIC\_EMPTY\_NODES
 2) true
25) 1) \_MAX\_RESULTS\_TO\_UNSORTED\_MODE
 2) 1000
26) 1) UNION\_ITERATOR\_HEAP
 2) 20
27) 1) CURSOR\_MAX\_IDLE
 2) 300000
28) 1) NO\_MEM\_POOLS
 2) false
29) 1) PARTIAL\_INDEXED\_DOCS
 2) false
30) 1) UPGRADE\_INDEX
 2) Upgrade config for upgrading
31) 1) \_NUMERIC\_COMPRESS
 2) false
32) 1) \_FREE\_RESOURCE\_ON\_THREAD
 2) true
33) 1) \_PRINT\_PROFILE\_CLOCK
 2) true
34) 1) RAW\_DOCID\_ENCODING
 2) false
35) 1) \_NUMERIC\_RANGES\_PARENTS
 2) 0
```
  See also
--------

 [`FT.CONFIG SET`](../ft.config-set) | [`FT.CONFIG HELP`](../ft.config-help)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.config-get/>

FT.ALIASUPDATE
==============



```
FT.ALIASUPDATE
```
 Syntax 
```
FT.ALIASUPDATE alias index

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Add an alias to an index. If the alias is already associated with another index, FT.ALIASUPDATE removes the alias association with the previous index.

 [Examples](#examples)

 Required arguments
------------------

  `alias index` is alias to be added to an index.

  Return
------

 FT.ALIASUPDATE returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Update an index alias** Update the alias of an index.

 
```
127.0.0.1:6379> FT.ALIASUPDATE alias idx
OK
```
 See also
--------

 [`FT.ALIASADD`](../ft.aliasadd) | [`FT.ALIASDEL`](../ft.aliasdel)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)

 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.aliasupdate/>

FT.DICTDEL
==========



```
FT.DICTDEL
```
 Syntax 
```
FT.DICTDEL dict term [term ...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.4.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Delete terms from a dictionary

 [Examples](#examples)

 Required arguments
------------------

  `dict` is dictionary name.

   `term` term to delete from the dictionary.

  Return
------

 FT.DICTDEL returns an integer reply, the number of new terms that were deleted.

 Examples
--------

  **Delete terms from a dictionary** 
```
127.0.0.1:6379> FT.DICTDEL dict foo bar "hello world"
(integer) 3
```
  See also
--------

 [`FT.DICTADD`](../ft.dictadd) | [`FT.DICTDUMP`](../ft.dictdump)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.dictdel/>

FT.CONFIG
=========



```
FT.CONFIG SET
```
 Syntax 
```
FT.CONFIG SET option value

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Set the value of a RediSearch configuration parameter.

 Values set using `FT.CONFIG SET` are not persisted after server restart.

 RediSearch configuration parameters are detailed in [Configuration parameters](https://redis.io/docs/stack/search/configuring).

  Note As detailed in the link above, not all RediSearch configuration parameters can be set at runtime.

  [Examples](#examples)

 Required arguments
------------------

  `option` is name of the configuration option, or '\*' for all.

   `value` is value of the configuration option.

  Return
------

 FT.CONFIG SET returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Set runtime configuration options** 
```
127.0.0.1:6379> FT.CONFIG SET TIMEOUT 42
OK
```
  See also
--------

 [`FT.CONFIG GET`](../ft.config-get) | [`FT.CONFIG HELP`](../ft.config-help)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.config-set/>

FT.CURSOR
=========



```
FT.CURSOR READ
```
 Syntax 
```
FT.CURSOR READ index cursor_id [COUNT read_size]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.1.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Read next results from an existing cursor

 [Examples](#examples)

 See [Cursor API](https://redis.io/docs/stack/search/reference/aggregations/#cursor-api) for more details.

 Required arguments
------------------

  `index` is index name.

   `cursor_id` is id of the cursor.

   `[COUNT read_size]` is number of results to read. This parameter overrides `COUNT` specified in [`FT.AGGREGATE`](../ft.aggregate).

  Return
------

 FT.CURSOR DEL returns an array reply where each row is an array reply and represents a single aggregate result.

 Examples
--------

  **Read next results from a cursor** 
```
127.0.0.1:6379> FT.CURSOR READ idx 342459320 COUNT 50
```
  See also
--------

 [`FT.CURSOR DEL`](../ft.cursor-del) | [`FT.AGGREGATE`](../ft.aggregate)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.cursor-read/>

FT.CURSOR
=========



```
FT.CURSOR DEL
```
 Syntax 
```
FT.CURSOR DEL index cursor_id

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.1.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Delete a cursor

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name.

   `cursor_id` is id of the cursor.

  Returns
-------

 FT.CURSOR DEL returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Delete a cursor** 
```
redis> FT.CURSOR DEL idx 342459320
OK
```
 Check that the cursor is deleted.

 
```
127.0.0.1:6379> FT.CURSOR DEL idx 342459320
(error) Cursor does not exist
```
  See also
--------

 [`FT.CURSOR READ`](../ft.cursor-read)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.cursor-del/>

FT.SEARCH
=========



```
FT.SEARCH
```
 Syntax 
```
FT.SEARCH index query 
  [NOCONTENT] 
  [VERBATIM] [NOSTOPWORDS] 
  [WITHSCORES] 
  [WITHPAYLOADS] 
  [WITHSORTKEYS] 
  [FILTER numeric_field min max [ FILTER numeric_field min max ...]] 
  [GEOFILTER geo_field lon lat radius m | km | mi | ft [ GEOFILTER geo_field lon lat radius m | km | mi | ft ...]] 
  [INKEYS count key [key ...]] [ INFIELDS count field [field ...]] 
  [RETURN count identifier [AS property] [ identifier [AS property] ...]] 
  [SUMMARIZE [ FIELDS count field [field ...]] [FRAGS num] [LEN fragsize] [SEPARATOR separator]] 
  [HIGHLIGHT [ FIELDS count field [field ...]] [ TAGS open close]] 
  [SLOP slop] 
  [TIMEOUT timeout] 
  [INORDER] 
  [LANGUAGE language] 
  [EXPANDER expander] 
  [SCORER scorer] 
  [EXPLAINSCORE] 
  [PAYLOAD payload] 
  [SORTBY sortby [ ASC | DESC]] 
  [LIMIT offset num] 
  [PARAMS nargs name value [ name value ...]] 
  [DIALECT dialect]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(N)  Search the index with a textual query, returning either documents or just ids

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name. You must first create the index using [`FT.CREATE`](../ft.create).

   `query` is text query to search. If it's more than a single word, put it in quotes. Refer to [Query syntax](https://redis.io/docs/stack/search/reference/query_syntax) for more details.

  Optional arguments
------------------

  `NOCONTENT` returns the document ids and not the content. This is useful if RediSearch is only an index on an external document collection.

   `VERBATIM` does not try to use stemming for query expansion but searches the query terms verbatim.

   `WITHSCORES` also returns the relative internal score of each document. This can be used to merge results from multiple instances.

   `WITHPAYLOADS` retrieves optional document payloads. See [`FT.CREATE`](../ft.create). The payloads follow the document id and, if `WITHSCORES` is set, the scores.

   `WITHSORTKEYS` returns the value of the sorting key, right after the id and score and/or payload, if requested. This is usually not needed, and exists for distributed search coordination purposes. This option is relevant only if used in conjunction with `SORTBY`.

   `FILTER numeric_attribute min max` limits results to those having numeric values ranging between `min` and `max`, if numeric\_attribute is defined as a numeric attribute in [`FT.CREATE`](../ft.create). `min` and `max` follow [`ZRANGE`](../zrange) syntax, and can be `-inf`, `+inf`, and use `(` for exclusive ranges. Multiple numeric filters for different attributes are supported in one query.

   `GEOFILTER {geo_attribute} {lon} {lat} {radius} m|km|mi|ft` filter the results to a given `radius` from `lon` and `lat`. Radius is given as a number and units. See [`GEORADIUS`](../georadius) for more details.

   `INKEYS {num} {attribute} ...` limits the result to a given set of keys specified in the list. The first argument must be the length of the list and greater than zero. Non-existent keys are ignored, unless all the keys are non-existent.

   `INFIELDS {num} {attribute} ...` filters the results to those appearing only in specific attributes of the document, like `title` or `URL`. You must include `num`, which is the number of attributes you're filtering by. For example, if you request `title` and `URL`, then `num` is 2.

   `RETURN {num} {identifier} AS {property} ...` limits the attributes returned from the document. `num` is the number of attributes following the keyword. If `num` is 0, it acts like `NOCONTENT`. `identifier` is either an attribute name (for hashes and JSON) or a JSON Path expression (for JSON). `property` is an optional name used in the result. If not provided, the `identifier` is used in the result.

   `SUMMARIZE ...` returns only the sections of the attribute that contain the matched text. See [Highlighting](https://redis.io/docs/stack/search/reference/highlight) for more information.

   `HIGHLIGHT ...` formats occurrences of matched text. See [Highlighting](https://redis.io/docs/stack/search/reference/highlight) for more information.

   `SLOP {slop}` is the number of intermediate terms allowed to appear between the terms of the query. Suppose you're searching for a phrase *hello world*. If some terms appear in-between *hello* and *world*, a `SLOP` greater than `0` allows for these text attributes to match. By default, there is no `SLOP` constraint.

   `INORDER` requires the terms in the document to have the same order as the terms in the query, regardless of the offsets between them. Typically used in conjunction with `SLOP`. Default is `false`.

   `LANGUAGE {language}` use a stemmer for the supplied language during search for query expansion. If querying documents in Chinese, set to `chinese` to properly tokenize the query terms. Defaults to English. If an unsupported language is sent, the command returns an error. See [`FT.CREATE`](../ft.create) for the list of languages.

   `EXPANDER {expander}` uses a custom query expander instead of the stemmer. See [Extensions](https://redis.io/docs/stack/search/reference/extensions).

   `SCORER {scorer}` uses a custom scoring function you define. See [Extensions](https://redis.io/docs/stack/search/reference/extensions).

   `EXPLAINSCORE` returns a textual description of how the scores were calculated. Using this option requires `WITHSCORES`.

   `PAYLOAD {payload}` adds an arbitrary, binary safe payload that is exposed to custom scoring functions. See [Extensions](https://redis.io/docs/stack/search/reference/extensions).

   `SORTBY {attribute} [ASC|DESC]` orders the results by the value of this attribute. This applies to both text and numeric attributes. Attributes needed for `SORTBY` should be declared as `SORTABLE` in the index, in order to be available with very low latency. Note that this adds memory overhead.

   `LIMIT first num` limits the results to the offset and number of results given. Note that the offset is zero-indexed. The default is 0 10, which returns 10 items starting from the first result. You can use `LIMIT 0 0` to count the number of documents in the result set without actually returning them.

   `TIMEOUT {milliseconds}` overrides the timeout parameter of the module.

   `PARAMS {nargs} {name} {value}` defines one or more value parameters. Each parameter has a name and a value.

 You can reference parameters in the `query` by a `$`, followed by the parameter name, for example, `$user`. Each such reference in the search query to a parameter name is substituted by the corresponding parameter value. For example, with parameter definition `PARAMS 4 lon 29.69465 lat 34.95126`, the expression `@loc:[$lon $lat 10 km]` is evaluated to `@loc:[29.69465 34.95126 10 km]`. You cannot reference parameters in the query string where concrete values are not allowed, such as in field names, for example, `@loc`. To use `PARAMS`, set `DIALECT` to `2` or greater than `2`.

   `DIALECT {dialect_version}` selects the dialect version under which to execute the query. If not specified, the query will execute under the default dialect version set during module initial loading or via [`FT.CONFIG SET`](../ft.config-set) command.

  Return
------

 FT.SEARCH returns an array reply, where the first element is an integer reply of the total number of results, and then array reply pairs of document ids, and array replies of attribute/value pairs.

  Notes * If `NOCONTENT` is given, an array is returned where the first element is the total number of results, and the rest of the members are document ids.
* If a hash expires after the query process starts, the hash is counted in the total number of results, but the key name and content return as null.

  ### Return multiple values

 When the index is defined `ON JSON`, a reply for a single attribute or a single JSONPath may return multiple values when the JSONPath matches multiple values, or when the JSONPath matches an array.

 Prior to RediSearch v2.6, only the first of the matched values was returned. Starting with RediSearch v2.6, all values are returned, wrapped with a top-level array.

 In order to maintain backward compatibility, the default behavior with RediSearch v2.6 is to return only the first value.

 To return all the values, use `DIALECT` 3 (or greater, when available).

 The `DIALECT` can be specified as a parameter in the FT.SEARCH command. If it is not specified, the `DEFAULT_DIALECT` is used, which can be set using [`FT.CONFIG SET`](../ft.config-set) or by passing it as an argument to the `redisearch` module when it is loaded.

 For example, with the following document and index:

 
```
127.0.0.1:6379> JSON.SET doc:1 $ '[{"arr": [1, 2, 3]}, {"val": "hello"}, {"val": "world"}]'
OK
127.0.0.1:6379> FT.CREATE idx ON JSON PREFIX 1 doc: SCHEMA $..arr AS arr NUMERIC $..val AS val TEXT
OK

```

Notice the different replies, with and without `DIALECT 3`:

 
```
127.0.0.1:6379> FT.SEARCH idx \* RETURN 2 arr val
1) (integer) 1
2) "doc:1"
3) 1) "arr"
 2) "[1,2,3]"
 3) "val"
 4) "hello"
127.0.0.1:6379> FT.SEARCH idx \* RETURN 2 arr val DIALECT 3
1) (integer) 1
2) "doc:1"
3) 1) "arr"
 2) "[[1,2,3]]"
 3) "val"
 4) "[\"hello\",\"world\"]"

```

Complexity
----------

 FT.SEARCH complexity is O(n) for single word queries. `n` is the number of the results in the result set. Finding all the documents that have a specific term is O(1), however, a scan on all those documents is needed to load the documents data from redis hashes and return them.

 The time complexity for more complex queries varies, but in general it's proportional to the number of words, the number of intersection points between them and the number of results in the result set.

 Examples
--------

  **Search for a term in every text attribute** Search for the term "wizard" in every TEXT attribute of an index containing book data.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "wizard"
```
   **Search for a term in title attribute** Search for the term *dogs* in the `title` attribute.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "@title:dogs"
```
   **Search for books from specific years** Search for books published in 2020 or 2021.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "@published\_at:[2020 2021]"
```
   **Search for a restaurant by distance from longitude/latitude** Search for Chinese restaurants within 5 kilometers of longitude -122.41, latitude 37.77 (San Francisco).

 
```
127.0.0.1:6379> FT.SEARCH restaurants-idx "chinese @location:[-122.41 37.77 5 km]"
```
   **Search for a book by terms but boost specific term** Search for the term *dogs* or *cats* in the `title` attribute, but give matches of *dogs* a higher relevance score (also known as *boosting*).

 
```
127.0.0.1:6379> FT.SEARCH books-idx "(@title:dogs | @title:cats) | (@title:dogs) => { $weight: 5.0; }"
```
   **Search for a book by a term and EXPLAINSCORE** Search for books with *dogs* in any TEXT attribute in the index and request an explanation of scoring for each result.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "dogs" WITHSCORES EXPLAINSCORE
```
   **Search for a book by a term and TAG** Search for books with *space* in the title that have `science` in the TAG attribute `categories`.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "@title:space @categories:{science}"
```
   **Search for a book by a term but limit the number** Search for books with *Python* in any `TEXT` attribute, returning 10 results starting with the 11th result in the entire result set (the offset parameter is zero-based), and return only the `title` attribute for each result.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "python" LIMIT 10 10 RETURN 1 title
```
   **Search for a book by a term and price** Search for books with *Python* in any `TEXT` attribute, returning the price stored in the original JSON document.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "python" RETURN 3 $.book.price AS price
```
   **Search for a book by title and distance** Search for books with semantically similar title to *Planet Earth*. Return top 10 results sorted by distance.

 
```
127.0.0.1:6379> FT.SEARCH books-idx "\*=>[KNN 10 @title\_embedding $query\_vec AS title\_score]" PARAMS 2 query\_vec <"Planet Earth" embedding BLOB> SORTBY title\_score DIALECT 2
```
   **Search for a phrase using SLOP** Search for a phrase *hello world*. First, create an index.

 
```
127.0.0.1:6379> FT.CREATE memes SCHEMA phrase TEXT
OK
```
 Add variations of the phrase *hello world*.

 
```
127.0.0.1:6379> HSET s1 phrase "hello world"
(integer) 1
127.0.0.1:6379> HSET s2 phrase "hello simple world"
(integer) 1
127.0.0.1:6379> HSET s3 phrase "hello somewhat less simple world"
(integer) 1
127.0.0.1:6379> HSET s4 phrase "hello complicated yet encouraging problem solving world"
(integer) 1
127.0.0.1:6379> HSET s5 phrase "hello complicated yet amazingly encouraging problem solving world"
(integer) 1
```
 Then, search for the phrase *hello world*. The result returns all documents that contain the phrase.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello world)' NOCONTENT 
1) (integer) 5
2) "s1"
3) "s2"
4) "s3"
5) "s4"
6) "s5"
```
 Now, return all documents that have one of fewer words between *hello* and *world*.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello world)' NOCONTENT SLOP 1
1) (integer) 2
2) "s1"
3) "s2"
```
 Now, return all documents with three or fewer words between *hello* and *world*.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello world)' NOCONTENT SLOP 3
1) (integer) 3
2) "s1"
3) "s2"
4) "s3"
```
 `s5` needs a higher `SLOP` to match, `SLOP 6` or higher, to be exact. See what happens when you set `SLOP` to `5`.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello world)' NOCONTENT SLOP 5
1) (integer) 4
2) "s1"
3) "s2"
4) "s3"
5) "s4"
```
 If you add additional terms (and stemming), you get these results.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello amazing world)' NOCONTENT 
1) (integer) 1
2) "s5"
```
 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello encouraged world)' NOCONTENT SLOP 5
1) (integer) 2
2) "s4"
3) "s5"
```
 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(hello encouraged world)' NOCONTENT SLOP 4
1) (integer) 1
2) "s4"
```
 If you swap the terms, you can still retrieve the correct phrase.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(amazing hello world)' NOCONTENT
1) (integer) 1
2) "s5"
```
 But, if you use `INORDER`, you get zero results.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(amazing hello world)' NOCONTENT INORDER
1) (integer) 0
```
 Likewise, if you use a query attribute `$inorder` set to `true`, `s5` is not retrieved.

 
```
127.0.0.1:6379> FT.SEARCH memes '@phrase:(amazing hello world)=>{$inorder: true;}' NOCONTENT
1) (integer) 0
```
 To sum up, the `INORDER` argument or `$inorder` query attribute require the query terms to match terms with similar ordering.

  See also
--------

 [`FT.CREATE`](../ft.create) | [`FT.AGGREGATE`](../ft.aggregate)

 Related topics
--------------

 * [Extensions](https://redis.io/docs/stack/search/reference/extensions)
* [Highlighting](https://redis.io/docs/stack/search/reference/highlight)
* [Query syntax](https://redis.io/docs/stack/search/reference/query_syntax)
* [RediSearch](https://redis.io/docs/stack/search)

 History
-------

 * Starting with Redis version 2.0.0: Deprecated `WITHPAYLOADS` and `PAYLOAD` arguments



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.search/>

FT.DICTADD
==========



```
FT.DICTADD
```
 Syntax 
```
FT.DICTADD dict term [term ...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.4.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Add terms to a dictionary

 [Examples](#examples)

 Required arguments
------------------

  `dict` is dictionary name.

   `term` term to add to the dictionary.

  Return
------

 FT.DICTADD returns an integer reply, the number of new terms that were added.

 Examples
--------

  **Add terms to a dictionary** 
```
127.0.0.1:6379> FT.DICTADD dict foo bar "hello world"
(integer) 3
```
  See also
--------

 [`FT.DICTDEL`](../ft.dictdel) | [`FT.DICTDUMP`](../ft.dictdump)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.dictadd/>

FT.DICTDUMP
===========



```
FT.DICTDUMP
```
 Syntax 
```
FT.DICTDUMP dict

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.4.0](https://redis.io/docs/stack/search)  Time complexity: O(N), where N is the size of the dictionary  Dump all terms in the given dictionary

 [Examples](#examples)

 Required argumemts
------------------

  `dict` is dictionary name.

  Return
------

 FT.DICTDUMP returns an array, where each element is term (string).

 Examples
--------

  **Dump all terms in the dictionary** 
```
127.0.0.1:6379> FT.DICTDUMP dict
1) "foo"
2) "bar"
3) "hello world"
```
  See also
--------

 [`FT.DICTADD`](../ft.dictadd) | [`FT.DICTDEL`](../ft.dictdel)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.dictdump/>

FT.EXPLAIN
==========



```
FT.EXPLAIN
```
 Syntax 
```
FT.EXPLAIN index query 
  [DIALECT dialect]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Return the execution plan for a complex query

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name. You must first create the index using [`FT.CREATE`](../ft.create).

   `query` is query string, as if sent to FT.SEARCH`.

  Optional arguments
------------------

  `DIALECT {dialect_version}` is dialect version under which to execute the query. If not specified, the query executes under the default dialect version set during module initial loading or via [`FT.CONFIG SET`](../ft.config-set) command.

   Notes * In the returned response, a `+` on a term is an indication of stemming.
* Use `redis-cli --raw` to properly read line-breaks in the returned response.

  Return
------

 FT.EXPLAIN returns a string representing the execution plan.

 Examples
--------

  **Return the execution plan for a complex query** 
```
$ redis-cli --raw
127.0.0.1:6379> FT.EXPLAIN rd "(foo bar)|(hello world) @date:[100 200]|@date:[500 +inf]"
INTERSECT {
 UNION {
 INTERSECT {
 foo
 bar
 }
 INTERSECT {
 hello
 world
 }
 }
 UNION {
 NUMERIC {100.000000 <= x <= 200.000000}
 NUMERIC {500.000000 <= x <= inf}
 }
}
```
  See also
--------

 [`FT.CREATE`](../ft.create) | [`FT.SEARCH`](../ft.search) | [`FT.CONFIG SET`](../ft.config-set)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.explain/>

FT.INFO
=======



```
FT.INFO
```
 Syntax 
```
FT.INFO index

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Return information and statistics on the index

 [Examples](#examples)

 Required arguments
------------------

  `index` is full-text index name. You must first create the index using [`FT.CREATE`](../ft.create).

  Return
------

 FT.INFO returns an array reply with pairs of keys and values.

 Returned values include:

 * `index_definition`: reflection of [`FT.CREATE`](../ft.create) command parameters.
* `fields`: index schema - field names, types, and attributes.
* Number of documents.
* Number of distinct terms.
* Average bytes per record.
* Size and capacity of the index buffers.
* Indexing state and percentage as well as failures:
	+ `indexing`: whether of not the index is being scanned in the background.
	+ `percent_indexed`: progress of background indexing (1 if complete).
	+ `hash_indexing_failures`: number of failures due to operations not compatible with index schema.

 Optional statistics include:

 * `garbage collector` for all options other than NOGC.
* `cursors` if a cursor exists for the index.
* `stopword lists` if a custom stopword list is used.

 Examples
--------

  **Return statistics about an index** 
```
127.0.0.1:6379> FT.INFO idx
1) index\_name
 2) wikipedia
 3) index\_options
 4) (empty array)
 11) score\_field
 12) \_\_score
 13) payload\_field
 14) \_\_payload
 7) fields
 8) 1) 1) title
 2) type
 3) TEXT
 4) WEIGHT
 5) "1"
 6) SORTABLE
 2) 1) body
 2) type
 3) TEXT
 4) WEIGHT
 5) "1"
 3) 1) id
 2) type
 3) NUMERIC
 4) 1) subject location
 2) type
 3) GEO
 9) num\_docs
10) "0"
11) max\_doc\_id
12) "345678"
13) num\_terms
14) "691356"
15) num\_records
16) "0"
17) inverted\_sz\_mb
18) "0"
19) vector\_index\_sz\_mb
20) "0"
21) total\_inverted\_index\_blocks
22) "933290"
23) offset\_vectors\_sz\_mb
24) "0.65932846069335938"
25) doc\_table\_size\_mb
26) "29.893482208251953"
27) sortable\_values\_size\_mb
28) "11.432285308837891"
29) key\_table\_size\_mb
30) "1.239776611328125e-05"
31) records\_per\_doc\_avg
32) "-nan"
33) bytes\_per\_record\_avg
34) "-nan"
35) offsets\_per\_term\_avg
36) "inf"
37) offset\_bits\_per\_record\_avg
38) "8"
39) hash\_indexing\_failures
40) "0"
41) indexing
42) "0"
43) percent\_indexed
44) "1"
45) number\_of\_uses
46) 1
47) gc\_stats
48) 1) bytes\_collected
 2) "4148136"
 3) total\_ms\_run
 4) "14796"
 5) total\_cycles
 6) "1"
 7) average\_cycle\_time\_ms
 8) "14796"
 9) last\_run\_time\_ms
 10) "14796"
 11) gc\_numeric\_trees\_missed
 12) "0"
 13) gc\_blocks\_denied
 14) "0"
49) cursor\_stats
50) 1) global\_idle
 2) (integer) 0
 3) global\_total
 4) (integer) 0
 5) index\_capacity
 6) (integer) 128
 7) index\_total
 8) (integer) 0
51) stopwords\_list
52) 1) "tlv"
 2) "summer"
 3) "2020"
```
  See also
--------

 [`FT.CREATE`](../ft.create) | [`FT.SEARCH`](../ft.search)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.info/>

FT.SUGADD
=========



```
FT.SUGADD
```
 Syntax 
```
FT.SUGADD key string score 
  [INCR] 
  [PAYLOAD payload]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Add a suggestion string to an auto-complete suggestion dictionary

 [Examples](#examples)

 Required arguments
------------------

  `key` is suggestion dictionary key.

   `string` is suggestion string to index.

   `score` is floating point number of the suggestion string's weight.

  The auto-complete suggestion dictionary is disconnected from the index definitions and leaves creating and updating suggestions dictionaries to the user.

 Optional arguments
------------------

  `INCR` increments the existing entry of the suggestion by the given score, instead of replacing the score. This is useful for updating the dictionary based on user queries in real time.

   `PAYLOAD {payload}` saves an extra payload with the suggestion, that can be fetched by adding the `WITHPAYLOADS` argument to [`FT.SUGGET`](../ft.sugget).

  Return
------

 FT.SUGADD returns an integer reply, which is the current size of the suggestion dictionary.

 Examples
--------

  **Add a suggestion string to an auto-complete suggestion dictionary** 
```
127.0.0.1:6379> FT.SUGADD sug "hello world" 1
(integer) 3
```
  See also
--------

 [`FT.SUGGET`](../ft.sugget) | [`FT.SUGDEL`](../ft.sugdel) | [`FT.SUGLEN`](../ft.suglen)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)

 History
-------

 * Starting with Redis version 2.0.0: Deprecated `PAYLOAD` argument



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.sugadd/>

FT.ALIASDEL
===========



```
FT.ALIASDEL
```
 Syntax 
```
FT.ALIASDEL alias

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Remove an alias from an index

 [Examples](#examples)

 Required arguments
------------------

  `alias` is index alias to be removed.

  Return
------

 FT.ALIASDEL returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Remove an alias from an index** Remove an alias from an index.

 
```
127.0.0.1:6379> FT.ALIASDEL alias
OK
```
  See also
--------

 [`FT.ALIASADD`](../ft.aliasadd) | [`FT.ALIASUPDATE`](../ft.aliasupdate)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.aliasdel/>

FT.DROPINDEX
============



```
FT.DROPINDEX
```
 Syntax 
```
FT.DROPINDEX index 
  [DD]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 2.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1) or O(N) if documents are deleted, where N is the number of keys in the keyspace  Delete an index

 [Examples](#examples)

 Required arguments
------------------

  `index` is full-text index name. You must first create the index using [`FT.CREATE`](../ft.create).

  Optional arguments
------------------

  `DD` drop operation that, if set, deletes the actual document hashes.

 By default, FT.DROPINDEX does not delete the documents associated with the index. Adding the `DD` option deletes the documents as well. If an index creation is still running ([`FT.CREATE`](../ft.create) is running asynchronously), only the document hashes that have already been indexed are deleted. The document hashes left to be indexed remain in the database. To check the completion of the indexing, use [`FT.INFO`](../ft.info).

  Return
------

 FT.DROPINDEX returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Delete an index** 
```
127.0.0.1:6379> FT.DROPINDEX idx DD
OK
```
  See also
--------

 [`FT.CREATE`](../ft.create) | [`FT.INFO`](../ft.info)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.dropindex/>

FLUSHDB
=======



```
FLUSHDB
```
 Syntax 
```
FLUSHDB [ASYNC | SYNC]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of keys in the selected database ACL categories:  `@keyspace`, `@write`, `@slow`, `@dangerous`,   Delete all the keys of the currently selected DB. This command never fails.

 By default, `FLUSHDB` will synchronously flush all keys from the database. Starting with Redis 6.2, setting the **lazyfree-lazy-user-flush** configuration directive to "yes" changes the default flush mode to asynchronous.

 It is possible to use one of the following modifiers to dictate the flushing mode explicitly:

 * `ASYNC`: flushes the database asynchronously
* `SYNC`: flushes the database synchronously

 Note: an asynchronous `FLUSHDB` command only deletes keys that were present at the time the command was invoked. Keys created during an asynchronous flush will be unaffected.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Behavior change history
-----------------------

 * `>= 6.2.0`: Default flush behavior now configurable by the **lazyfree-lazy-user-flush** configuration directive.

 History
-------

 * Starting with Redis version 4.0.0: Added the `ASYNC` flushing mode modifier.
* Starting with Redis version 6.2.0: Added the `SYNC` flushing mode modifier.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/flushdb/>

FT.PROFILE
==========



```
FT.PROFILE
```
 Syntax 
```
FT.PROFILE index SEARCH | AGGREGATE [LIMITED] QUERY query

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 2.2.0](https://redis.io/docs/stack/search)  Time complexity: O(N)  Apply [`FT.SEARCH`](../ft.search) or [`FT.AGGREGATE`](../ft.aggregate) command to collect performance details

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name, created using [`FT.CREATE`](../ft.create).

   `SEARCH | AGGREGATE` is difference between [`FT.SEARCH`](../ft.search) and [`FT.AGGREGATE`](../ft.aggregate).

   `LIMITED` removes details of `reader` iterator.

   `QUERY {query}` is query string, sent to [`FT.SEARCH`](../ft.search).

  **Note:** To reduce the size of the output, use `NOCONTENT` or `LIMIT 0 0` to reduce the reply results or `LIMITED` to not reply with details of `reader iterators` inside built-in unions such as `fuzzy` or `prefix`.

 Return
------

 `FT.PROFILE` returns an array reply, with the first array reply identical to the reply of [`FT.SEARCH`](../ft.search) and [`FT.AGGREGATE`](../ft.aggregate) and a second array reply with information of time in milliseconds (ms) used to create the query and time and count of calls of iterators and result-processors.

 Return value has an array with two elements:

 * Results - The normal reply from RediSearch, similar to a cursor.
* Profile - The details in the profile are:
	+ Total profile time - The total runtime of the query, in ms.
	+ Parsing time - Parsing time of the query and parameters into an execution plan, in ms.
	+ Pipeline creation time - Creation time of execution plan including iterators, result processors, and reducers creation, in ms.
	+ Iterators profile - Index iterators information including their type, term, count, and time data. Inverted-index iterators have in addition the number of elements they contain. Hybrid vector iterators returning the top results from the vector index in batches, include the number of batches.
	+ Result processors profile - Result processors chain with type, count, and time data.

 Examples
--------

  **Collect performance information about an index** 
```
127.0.0.1:6379> FT.PROFILE idx SEARCH QUERY "hello world"
1) 1) (integer) 1
 2) "doc1"
 3) 1) "t"
 2) "hello world"
2) 1) 1) Total profile time
 2) "0.47199999999999998"
 2) 1) Parsing time
 2) "0.218"
 3) 1) Pipeline creation time
 2) "0.032000000000000001"
 4) 1) Iterators profile
 2) 1) Type
 2) INTERSECT
 3) Time
 4) "0.025000000000000001"
 5) Counter
 6) (integer) 1
 7) Child iterators
 8) 1) Type
 2) TEXT
 3) Term
 4) hello
 5) Time
 6) "0.0070000000000000001"
 7) Counter
 8) (integer) 1
 9) Size
 10) (integer) 1
 9) 1) Type
 2) TEXT
 3) Term
 4) world
 5) Time
 6) "0.0030000000000000001"
 7) Counter
 8) (integer) 1
 9) Size
 10) (integer) 1
 5) 1) Result processors profile
 2) 1) Type
 2) Index
 3) Time
 4) "0.036999999999999998"
 5) Counter
 6) (integer) 1
 3) 1) Type
 2) Scorer
 3) Time
 4) "0.025000000000000001"
 5) Counter
 6) (integer) 1
 4) 1) Type
 2) Sorter
 3) Time
 4) "0.013999999999999999"
 5) Counter
 6) (integer) 1
 5) 1) Type
 2) Loader
 3) Time
 4) "0.10299999999999999"
 5) Counter
 6) (integer) 1
```
  See also
--------

 [`FT.SEARCH`](../ft.search) | [`FT.AGGREGATE`](../ft.aggregate)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.profile/>

FUNCTION
========



```
FUNCTION DELETE
```
 Syntax 
```
FUNCTION DELETE library-name
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@write`, `@slow`, `@scripting`,   Delete a library and all its functions.

 This command deletes the library called *library-name* and all functions in it. If the library doesn't exist, the server returns an error.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```
redis> FUNCTION LOAD Lua mylib "redis.register_function('myfunc', function(keys, args) return 'hello' end)"
OK
redis> FCALL myfunc 0
"hello"
redis> FUNCTION DELETE mylib
OK
redis> FCALL myfunc 0
(error) ERR Function not found

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-delete/>

FT.EXPLAINCLI
=============



```
FT.EXPLAINCLI
```
 Syntax 
```
FT.EXPLAINCLI index query 
  [DIALECT dialect]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Return the execution plan for a complex query but formatted for easier reading without using `redis-cli --raw`

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name. You must first create the index using [`FT.CREATE`](../ft.create).

   `query` is query string, as if sent to FT.SEARCH`.

  Optional arguments
------------------

  `DIALECT {dialect_version}` is dialect version under which to execute the query. If not specified, the query executes under the default dialect version set during module initial loading or via [`FT.CONFIG SET`](../ft.config-set) command.

  Note In the returned response, a `+` on a term is an indication of stemming.

   Return
------

 FT.EXPLAINCLI returns an array reply with a string representing the execution plan.

 Examples
--------

  **Return the execution plan for a complex query** 
```
$ redis-cli
127.0.0.1:6379> FT.EXPLAINCLI rd "(foo bar)|(hello world) @date:[100 200]|@date:[500 +inf]"
 1) INTERSECT {
 2) UNION {
 3) INTERSECT {
 4) UNION {
 5) foo
 6) +foo(expanded)
 7) }
 8) UNION {
 9) bar
10) +bar(expanded)
11) }
12) }
13) INTERSECT {
14) UNION {
15) hello
16) +hello(expanded)
17) }
18) UNION {
19) world
20) +world(expanded)
21) }
22) }
23) }
24) UNION {
25) NUMERIC {100.000000 <= @date <= 200.000000}
26) NUMERIC {500.000000 <= @date <= inf}
27) }
28) }
29)
```
  See also
--------

 [`FT.CREATE`](../ft.create) | [`FT.SEARCH`](../ft.search) | [`FT.CONFIG SET`](../ft.config-set)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.explaincli/>

FT.SPELLCHECK
=============



```
FT.SPELLCHECK
```
 Syntax 
```
FT.SPELLCHECK index query 
  [DISTANCE distance] 
  [TERMS INCLUDE | EXCLUDE dictionary [terms [terms ...]]] 
  [DIALECT dialect]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.4.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Perform spelling correction on a query, returning suggestions for misspelled terms

 [Examples](#examples)

 Required arguments
------------------

  `index` is index with the indexed terms.

   `query` is search query.

  See [Spellchecking](https://redis.io/docs/stack/search/reference/spellcheck) for more details.

 Optional arguments
------------------

  `TERMS` specifies an inclusion (`INCLUDE`) or exclusion (`EXCLUDE`) of a custom dictionary named `{dict}`. Refer to [`FT.DICTADD`](../ft.dictadd), [`FT.DICTDEL`](../ft.dictdel) and [`FT.DICTDUMP`](../ft.dictdump) about managing custom dictionaries.

   `DISTANCE` is maximum Levenshtein distance for spelling suggestions (default: 1, max: 4).

   `DIALECT {dialect_version}` selects the dialect version under which to execute the query. If not specified, the query will execute under the default dialect version set during module initial loading or via [`FT.CONFIG SET`](../ft.config-set) command.

  Return
------

 FT.SPELLCHECK returns an array reply, in which each element represents a misspelled term from the query. The misspelled terms are ordered by their order of appearance in the query. Each misspelled term, in turn, is a 3-element array consisting of the constant string `TERM`, the term itself and an array of suggestions for spelling corrections. Each element in the spelling corrections array consists of the score of the suggestion and the suggestion itself. The suggestions array, per misspelled term, is ordered in descending order by score. The score is calculated by dividing the number of documents in which the suggested term exists by the total number of documents in the index. Results can be normalized by dividing scores by the highest score.

 Examples
--------

  **Perform spelling correction on a query** 
```
127.0.0.1:6379> FT.SPELLCHECK idx held DISTANCE 2
1) 1) "TERM"
 2) "held"
 3) 1) 1) "0.66666666666666663"
 2) "hello"
 2) 1) "0.33333333333333331"
 2) "help"
```
  See also
--------

 [`FT.CONFIG SET`](../ft.config-set) | [`FT.DICTADD`](../ft.dictadd) | [`FT.DICTDEL`](../ft.dictdel) | [`FT.DICTDUMP`](../ft.dictdump)

 Related topics
--------------

 * [Spellchecking](https://redis.io/docs/stack/search/reference/spellcheck)
* [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.spellcheck/>

FT.SUGGET
=========



```
FT.SUGGET
```
 Syntax 
```
FT.SUGGET key prefix 
  [FUZZY] 
  [WITHSCORES] 
  [WITHPAYLOADS] 
  [MAX max]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Get completion suggestions for a prefix

 Syntax
------

 [Examples](#examples)

 Required arguments
------------------

  `key` is suggestion dictionary key.

   `prefix` is prefix to complete on.

  Optional arguments
------------------

  `FUZZY` performs a fuzzy prefix search, including prefixes at Levenshtein distance of 1 from the prefix sent.

   `MAX num` limits the results to a maximum of `num` (default: 5).

   `WITHSCORES` also returns the score of each suggestion. This can be used to merge results from multiple instances.

   `WITHPAYLOADS` returns optional payloads saved along with the suggestions. If no payload is present for an entry, it returns a null reply.

  Return
------

 FT.SUGGET returns an array reply, which is a list of the top suggestions matching the prefix, optionally with score after each entry.

 Examples
--------

  **Get completion suggestions for a prefix** 
```
127.0.0.1:6379> FT.SUGGET sug hell FUZZY MAX 3 WITHSCORES
1) "hell"
2) "2147483648"
3) "hello"
4) "0.70710676908493042"
```
  See also
--------

 [`FT.SUGADD`](../ft.sugadd) | [`FT.SUGDEL`](../ft.sugdel) | [`FT.SUGLEN`](../ft.suglen)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)

 History
-------

 * Starting with Redis version 2.0.0: Deprecated `WITHPAYLOADS` argument



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.sugget/>

FT.SYNDUMP
==========



```
FT.SYNDUMP
```
 Syntax 
```
FT.SYNDUMP index

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.2.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Dump the contents of a synonym group

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name.

  Use FT.SYNDUMP to dump the synonyms data structure. This command returns a list of synonym terms and their synonym group ids.

 Return
------

 FT.SYNDUMP returns an array reply, with a pair of `term` and an array of synonym groups.

 Examples
--------

  **Return the contents of a synonym group** 
```
127.0.0.1:6379> FT.SYNDUMP idx
1) "shalom"
2) 1) "synonym1"
 2) "synonym2"
3) "hi"
4) 1) "synonym1"
5) "hello"
6) 1) "synonym1"
```
  See also
--------

 [`FT.SYNUPDATE`](../ft.synupdate)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.syndump/>

FT.SYNUPDATE
============



```
FT.SYNUPDATE
```
 Syntax 
```
FT.SYNUPDATE index synonym_group_id 
  [SKIPINITIALSCAN] term [term ...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.2.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Update a synonym group

 [Examples](#examples)

 Required arguments
------------------

  `index` is index name.

   `synonym_group_id` is synonym group to return.

  Use FT.SYNUPDATE to create or update a synonym group with additional terms. The command triggers a scan of all documents.

 Optional parameters
-------------------

  `SKIPINITIALSCAN` does not scan and index, and only documents that are indexed after the update are affected.

  Return
------

 FT.SYNUPDATE returns a simple string reply `OK` if executed correctly, or an error reply otherwise.

 Examples
--------

  **Update a synonym group** 
```
127.0.0.1:6379> FT.SYNUPDATE idx synonym hello hi shalom
OK
```
 
```
127.0.0.1:6379> FT.SYNUPDATE idx synonym SKIPINITIALSCAN hello hi shalom
OK
```
  See also
--------

 [`FT.SYNDUMP`](../ft.syndump)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.synupdate/>

FT.SUGLEN
=========



```
FT.SUGLEN
```
 Syntax 
```
FT.SUGLEN key

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Get the size of an auto-complete suggestion dictionary

 [Examples](#examples)

 Required arguments
------------------

  `key` is suggestion dictionary key.

  Return
------

 FT.SUGLEN returns an integer reply, which is the current size of the suggestion dictionary.

 Examples
--------

  **Get the size of an auto-complete suggestion dictionary** 
```
127.0.0.1:6379> FT.SUGLEN sug
(integer) 2
```
  See also
--------

 [`FT.SUGADD`](../ft.sugadd) | [`FT.SUGDEL`](../ft.sugdel) | [`FT.SUGGET`](../ft.sugget)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.suglen/>

FT.TAGVALS
==========



```
FT.TAGVALS
```
 Syntax 
```
FT.TAGVALS index field_name

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(N)  Return a distinct set of values indexed in a Tag field

 [Examples](#examples)

 Required arguments
------------------

  `index` is full-text index name. You must first create the index using [`FT.CREATE`](../ft.create).

   `field_name` is name of a Tag file defined in the schema.

  Use FT.TAGVALS if your tag indexes things like cities, categories, and so on.

 Limitations
-----------

 FT.TAGVALS provides no paging or sorting, and the tags are not alphabetically sorted. FT.TAGVALS only operates on [tag fields](https://redis.io/docs/stack/search/reference/tags). The returned strings are lowercase with whitespaces removed, but otherwise unchanged.

 Return
------

 FT.TAGVALS returns an array reply of all distinct tags in the tag index.

 Examples
--------

  **Return a set of values indexed in a Tag field** 
```
127.0.0.1:6379> FT.TAGVALS idx myTag
1) "Hello"
2) "World"
```
  See also
--------

 [`FT.CREATE`](../ft.create)

 Related topics
--------------

 * [Tag fields](https://redis.io/docs/stack/search/reference/tags)
* [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.tagvals/>

FT.SUGDEL
=========



```
FT.SUGDEL
```
 Syntax 
```
FT.SUGDEL key string

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Search 1.0.0](https://redis.io/docs/stack/search)  Time complexity: O(1)  Delete a string from a suggestion index

 [Examples](#examples)

 Required arguments
------------------

  `key` is suggestion dictionary key.

   `string` is suggestion string to index.

  Return
------

 FT.SUGDEL returns an integer reply, 1 if the string was found and deleted, 0 otherwise.

 Examples
--------

  **Delete a string from a suggestion index** 
```
127.0.0.1:6379> FT.SUGDEL sug "hello"
(integer) 1
127.0.0.1:6379> FT.SUGDEL sug "hello"
(integer) 0
```
  See also
--------

 [`FT.SUGGET`](../ft.sugget) | [`FT.SUGADD`](../ft.sugadd) | [`FT.SUGLEN`](../ft.suglen)

 Related topics
--------------

 [RediSearch](https://redis.io/docs/stack/search)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ft.sugdel/>

FUNCTION
========



```
FUNCTION DUMP
```
 Syntax 
```
FUNCTION DUMP
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of functions ACL categories:  `@slow`, `@scripting`,   Return the serialized payload of loaded libraries. You can restore the serialized payload later with the [`FUNCTION RESTORE`](../function-restore) command.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the serialized payload

 Examples
--------

 The following example shows how to dump loaded libraries using `FUNCTION DUMP` and then it calls [`FUNCTION FLUSH`](../function-flush) deletes all the libraries. Then, it restores the original libraries from the serialized payload with [`FUNCTION RESTORE`](../function-restore).

 
```
redis> FUNCTION DUMP
"\xf6\x05mylib\x03LUA\x00\xc3@D@J\x1aredis.register_function('my@\x0b\x02', @\x06`\x12\x11keys, args) return`\x0c\a[1] end)\n\x00@\n)\x11\xc8|\x9b\xe4"
redis> FUNCTION FLUSH
OK
redis> FUNCTION RESTORE "\xf6\x05mylib\x03LUA\x00\xc3@D@J\x1aredis.register_function('my@\x0b\x02', @\x06`\x12\x11keys, args) return`\x0c\a[1] end)\n\x00@\n)\x11\xc8|\x9b\xe4"
OK
redis> FUNCTION LIST
1) 1) "library_name"
   2) "mylib"
   3) "engine"
   4) "LUA"
   5) "description"
   6) (nil)
   7) "functions"
   8) 1) 1) "name"
         2) "myfunc"
         3) "description"
         4) (nil)

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-dump/>

FUNCTION
========



```
FUNCTION FLUSH
```
 Syntax 
```
FUNCTION FLUSH [ASYNC | SYNC]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of functions deleted ACL categories:  `@write`, `@slow`, `@scripting`,   Deletes all the libraries.

 Unless called with the optional mode argument, the `lazyfree-lazy-user-flush` configuration directive sets the effective behavior. Valid modes are:

 * `ASYNC`: Asynchronously flush the libraries.
* `SYNC`: Synchronously flush the libraries.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-flush/>

FUNCTION
========



```
FUNCTION LOAD
```
 Syntax 
```
FUNCTION LOAD [REPLACE] function-code
```
  Available since: 7.0.0 Time complexity: O(1) (considering compilation time is redundant) ACL categories:  `@write`, `@slow`, `@scripting`,   Load a library to Redis.

 The command's gets a single mandatory parameter which is the source code that implements the library. The library payload must start with Shebang statement that provides a metadata about the library (like the engine to use and the library name). Shebang format: `#!<engine name> name=<library name>`. Currently engine name must be `lua`.

 For the Lua engine, the implementation should declare one or more entry points to the library with the [`redis.register_function()` API](https://redis.io/topics/lua-api#redis.register_function). Once loaded, you can call the functions in the library with the [`FCALL`](../fcall) (or [`FCALL_RO`](../fcall_ro) when applicable) command.

 When attempting to load a library with a name that already exists, the Redis server returns an error. The `REPLACE` modifier changes this behavior and overwrites the existing library with the new contents.

 The command will return an error in the following circumstances:

 * An invalid *engine-name* was provided.
* The library's name already exists without the `REPLACE` modifier.
* A function in the library is created with a name that already exists in another library (even when `REPLACE` is specified).
* The engine failed in creating the library's functions (due to a compilation error, for example).
* No functions were declared by the library.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 @string - the library name that was loaded

 Examples
--------

 The following example will create a library named `mylib` with a single function, `myfunc`, that returns the first argument it gets.

 
```
redis> FUNCTION LOAD "#!lua name=mylib \n redis.register_function('myfunc', function(keys, args) return args[1] end)"
mylib
redis> FCALL myfunc 0 hello
"hello"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-load/>

GEOHASH
=======



```
GEOHASH
```
 Syntax 
```
GEOHASH key [member [member ...]]
```
  Available since: 3.2.0 Time complexity: O(log(N)) for each member requested, where N is the number of elements in the sorted set. ACL categories:  `@read`, `@geo`, `@slow`,   Return valid [Geohash](https://en.wikipedia.org/wiki/Geohash) strings representing the position of one or more elements in a sorted set value representing a geospatial index (where elements were added using [`GEOADD`](../geoadd)).

 Normally Redis represents positions of elements using a variation of the Geohash technique where positions are encoded using 52 bit integers. The encoding is also different compared to the standard because the initial min and max coordinates used during the encoding and decoding process are different. This command however **returns a standard Geohash** in the form of a string as described in the [Wikipedia article](https://en.wikipedia.org/wiki/Geohash) and compatible with the [geohash.org](http://geohash.org) web site.

 Geohash string properties
-------------------------

 The command returns 11 characters Geohash strings, so no precision is lost compared to the Redis internal 52 bit representation. The returned Geohashes have the following properties:

 1. They can be shortened removing characters from the right. It will lose precision but will still point to the same area.
2. It is possible to use them in `geohash.org` URLs such as `http://geohash.org/<geohash-string>`. This is an [example of such URL](http://geohash.org/sqdtr74hyu0).
3. Strings with a similar prefix are nearby, but the contrary is not true, it is possible that strings with different prefixes are nearby too.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns an array where each element is the Geohash corresponding to each member name passed as argument to the command.

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEOHASH Sicily Palermo Catania

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geohash/>

GEORADIUS
=========



```
GEORADIUS (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`GEOSEARCH`](../geosearch) and [`GEOSEARCHSTORE`](../geosearchstore) with the `BYRADIUS` argument when migrating or writing new code.

  Syntax 
```
GEORADIUS key longitude latitude radius <M | KM | FT | MI>
  [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC]
  [STORE key] [STOREDIST key]
```
  Available since: 3.2.0 Time complexity: O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. ACL categories:  `@write`, `@geo`, `@slow`,   Return the members of a sorted set populated with geospatial information using [`GEOADD`](../geoadd), which are within the borders of the area specified with the center location and the maximum distance from the center (the radius).

 This manual page also covers the [`GEORADIUS_RO`](../georadius_ro) and [`GEORADIUSBYMEMBER_RO`](../georadiusbymember_ro) variants (see the section below for more information).

 The common use case for this command is to retrieve geospatial items near a specified point not farther than a given amount of meters (or other units). This allows, for example, to suggest mobile users of an application nearby places.

 The radius is specified in one of the following units:

 * **m** for meters.
* **km** for kilometers.
* **mi** for miles.
* **ft** for feet.

 The command optionally returns additional information using the following options:

 * `WITHDIST`: Also return the distance of the returned items from the specified center. The distance is returned in the same unit as the unit specified as the radius argument of the command.
* `WITHCOORD`: Also return the longitude,latitude coordinates of the matching items.
* `WITHHASH`: Also return the raw geohash-encoded sorted set score of the item, in the form of a 52 bit unsigned integer. This is only useful for low level hacks or debugging and is otherwise of little interest for the general user.

 The command default is to return unsorted items. Two different sorting methods can be invoked using the following two options:

 * `ASC`: Sort returned items from the nearest to the farthest, relative to the center.
* `DESC`: Sort returned items from the farthest to the nearest, relative to the center.

 By default all the matching items are returned. It is possible to limit the results to the first N matching items by using the **COUNT `<count>`** option. When `ANY` is provided the command will return as soon as enough matches are found, so the results may not be the ones closest to the specified point, but on the other hand, the effort invested by the server is significantly lower. When `ANY` is not provided, the command will perform an effort that is proportional to the number of items matching the specified area and sort them, so to query very large areas with a very small `COUNT` option may be slow even if just a few results are returned.

 By default the command returns the items to the client. It is possible to store the results with one of these options:

 * `STORE`: Store the items in a sorted set populated with their geospatial information.
* `STOREDIST`: Store the items in a sorted set populated with their distance from the center as a floating point number, in the same unit specified in the radius.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 * Without any `WITH` option specified, the command just returns a linear array like ["New York","Milan","Paris"].
* If `WITHCOORD`, `WITHDIST` or `WITHHASH` options are specified, the command returns an array of arrays, where each sub-array represents a single item.

 When additional information is returned as an array of arrays for each item, the first item in the sub-array is always the name of the returned item. The other information is returned in the following order as successive elements of the sub-array.

 1. The distance from the center as a floating point number, in the same unit specified in the radius.
2. The geohash integer.
3. The coordinates as a two items x,y array (longitude,latitude).

 So for example the command `GEORADIUS Sicily 15 37 200 km WITHCOORD WITHDIST` will return each item in the following way:

 
```
["Palermo","190.4424",["13.361389338970184","38.115556395496299"]]

```
 Read-only variants
------------------

 Since `GEORADIUS` and [`GEORADIUSBYMEMBER`](../georadiusbymember) have a `STORE` and `STOREDIST` option they are technically flagged as writing commands in the Redis command table. For this reason read-only replicas will flag them, and Redis Cluster replicas will redirect them to the master instance even if the connection is in read-only mode (see the [`READONLY`](../readonly) command of Redis Cluster).

 Breaking the compatibility with the past was considered but rejected, at least for Redis 4.0, so instead two read-only variants of the commands were added. They are exactly like the original commands but refuse the `STORE` and `STOREDIST` options. The two variants are called [`GEORADIUS_RO`](../georadius_ro) and [`GEORADIUSBYMEMBER_RO`](../georadiusbymember_ro), and can safely be used in replicas.

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEORADIUS Sicily 15 37 200 km WITHDIST
GEORADIUS Sicily 15 37 200 km WITHCOORD
GEORADIUS Sicily 15 37 200 km WITHDIST WITHCOORD

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `ANY` option for `COUNT`.
* Starting with Redis version 7.0.0: Added support for uppercase unit names.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/georadius/>

FUNCTION
========



```
FUNCTION RESTORE
```
 Syntax 
```
FUNCTION RESTORE serialized-value [FLUSH | APPEND | REPLACE]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of functions on the payload ACL categories:  `@write`, `@slow`, `@scripting`,   Restore libraries from the serialized payload.

 You can use the optional *policy* argument to provide a policy for handling existing libraries. The following policies are allowed:

 * **APPEND:** appends the restored libraries to the existing libraries and aborts on collision. This is the default policy.
* **FLUSH:** deletes all existing libraries before restoring the payload.
* **REPLACE:** appends the restored libraries to the existing libraries, replacing any existing ones in case of name collisions. Note that this policy doesn't prevent function name collisions, only libraries.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-restore/>

FUNCTION
========



```
FUNCTION LIST
```
 Syntax 
```
FUNCTION LIST [LIBRARYNAME library-name-pattern] [WITHCODE]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of functions ACL categories:  `@slow`, `@scripting`,   Return information about the functions and libraries.

 You can use the optional `LIBRARYNAME` argument to specify a pattern for matching library names. The optional `WITHCODE` modifier will cause the server to include the libraries source implementation in the reply.

 The following information is provided for each of the libraries in the response:

 * **library\_name:** the name of the library.
* **engine:** the engine of the library.
* **functions:** the list of functions in the library. Each function has the following fields:
	+ **name:** the name of the function.
	+ **description:** the function's description.
	+ **flags:** an array of [function flags](https://redis.io/docs/manual/programmability/functions-intro/#function-flags).
* **library\_code:** the library's source code (when given the `WITHCODE` modifier).

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-list/>

FUNCTION
========



```
FUNCTION STATS
```
 Syntax 
```
FUNCTION STATS
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@scripting`,   Return information about the function that's currently running and information about the available execution engines.

 The reply is map with two keys:

 1. `running_script`: information about the running script. If there's no in-flight function, the server replies with a *nil*. Otherwise, this is a map with the following keys:

 * **name:** the name of the function.
* **command:** the command and arguments used for invoking the function.
* **duration\_ms:** the function's runtime duration in milliseconds.

 2. `engines`: this is a map of maps. Each entry in the map represent a single engine. Engine map contains statistics about the engine like number of functions and number of libraries.

 You can use this command to inspect the invocation of a long-running function and decide whether kill it with the [`FUNCTION KILL`](../function-kill) command.

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-stats/>

GEORADIUS\_RO
=============



```
GEORADIUS_RO (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`GEOSEARCH`](../geosearch) with the `BYRADIUS` argument when migrating or writing new code.

  Syntax 
```
GEORADIUS_RO key longitude latitude radius <M | KM | FT | MI>
  [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC]
```
  Available since: 3.2.10 Time complexity: O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. ACL categories:  `@read`, `@geo`, `@slow`,   Read-only variant of the [`GEORADIUS`](../georadius) command.

 This command is identical to the [`GEORADIUS`](../georadius) command, except that it doesn't support the optional `STORE` and `STOREDIST` parameters.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): An array with each entry being the corresponding result of the subcommand given at the same position.

 History
-------

 * Starting with Redis version 6.2.0: Added the `ANY` option for `COUNT`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/georadius_ro/>

GEOPOS
======



```
GEOPOS
```
 Syntax 
```
GEOPOS key [member [member ...]]
```
  Available since: 3.2.0 Time complexity: O(N) where N is the number of members requested. ACL categories:  `@read`, `@geo`, `@slow`,   Return the positions (longitude,latitude) of all the specified members of the geospatial index represented by the sorted set at *key*.

 Given a sorted set representing a geospatial index, populated using the [`GEOADD`](../geoadd) command, it is often useful to obtain back the coordinates of specified members. When the geospatial index is populated via [`GEOADD`](../geoadd) the coordinates are converted into a 52 bit geohash, so the coordinates returned may not be exactly the ones used in order to add the elements, but small errors may be introduced.

 The command can accept a variable number of arguments so it always returns an array of positions even when a single element is specified.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns an array where each element is a two elements array representing longitude and latitude (x,y) of each member name passed as argument to the command.

 Non existing elements are reported as NULL elements of the array.

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEOPOS Sicily Palermo Catania NonExisting

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geopos/>

GEOSEARCHSTORE
==============



```
GEOSEARCHSTORE
```
 Syntax 
```
GEOSEARCHSTORE destination source <FROMMEMBER member |
  FROMLONLAT longitude latitude> <BYRADIUS radius <M | KM | FT | MI>
  | BYBOX width height <M | KM | FT | MI>> [ASC | DESC] [COUNT count
  [ANY]] [STOREDIST]
```
  Available since: 6.2.0 Time complexity: O(N+log(M)) where N is the number of elements in the grid-aligned bounding box area around the shape provided as the filter and M is the number of items inside the shape ACL categories:  `@write`, `@geo`, `@slow`,   This command is like [`GEOSEARCH`](../geosearch), but stores the result in destination key.

 This command replaces the now deprecated [`GEORADIUS`](../georadius) and [`GEORADIUSBYMEMBER`](../georadiusbymember).

 By default, it stores the results in the `destination` sorted set with their geospatial information.

 When using the `STOREDIST` option, the command stores the items in a sorted set populated with their distance from the center of the circle or box, as a floating-point number, in the same unit specified for that shape.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting set.

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEOADD Sicily 12.758489 38.788135 "edge1"   17.241510 38.788135 "edge2" 
GEOSEARCHSTORE key1 Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC COUNT 3
GEOSEARCH key1 FROMLONLAT 15 37 BYBOX 400 400 km ASC WITHCOORD WITHDIST WITHHASH
GEOSEARCHSTORE key2 Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC COUNT 3 STOREDIST
ZRANGE key2 0 -1 WITHSCORES

```
 History
-------

 * Starting with Redis version 7.0.0: Added support for uppercase unit names.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geosearchstore/>

GETRANGE
========



```
GETRANGE
```
 Syntax 
```
GETRANGE key start end
```
  Available since: 2.4.0 Time complexity: O(N) where N is the length of the returned string. The complexity is ultimately determined by the returned length, but because creating a substring from an existing string is very cheap, it can be considered O(1) for small strings. ACL categories:  `@read`, `@string`, `@slow`,   Returns the substring of the string value stored at `key`, determined by the offsets `start` and `end` (both are inclusive). Negative offsets can be used in order to provide an offset starting from the end of the string. So -1 means the last character, -2 the penultimate and so forth.

 The function handles out of range requests by limiting the resulting range to the actual length of the string.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)

 Examples
--------

 
```

SET mykey "This is a string"
GETRANGE mykey 0 3
GETRANGE mykey -3 -1
GETRANGE mykey 0 -1
GETRANGE mykey 10 100

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/getrange/>

GET
===



```
GET
```
 Syntax 
```
GET key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@read`, `@string`, `@fast`,   Get the value of `key`. If the key does not exist the special value `nil` is returned. An error is returned if the value stored at `key` is not a string, because `GET` only handles string values.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of `key`, or `nil` when `key` does not exist.

 Examples
--------

 
```

GET nonexisting
SET mykey "Hello"
GET mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/get/>

FUNCTION
========



```
FUNCTION KILL
```
 Syntax 
```
FUNCTION KILL
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@scripting`,   Kill a function that is currently executing.

 The `FUNCTION KILL` command can be used only on functions that did not modify the dataset during their execution (since stopping a read-only function does not violate the scripting engine's guaranteed atomicity).

 For more information please refer to [Introduction to Redis Functions](https://redis.io/topics/functions-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/function-kill/>

GEORADIUSBYMEMBER
=================



```
GEORADIUSBYMEMBER (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`GEOSEARCH`](../geosearch) and [`GEOSEARCHSTORE`](../geosearchstore) with the `BYRADIUS` and `FROMMEMBER` arguments when migrating or writing new code.

  Syntax 
```
GEORADIUSBYMEMBER key member radius <M | KM | FT | MI> [WITHCOORD]
  [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC] [STORE key]
  [STOREDIST key]
```
  Available since: 3.2.0 Time complexity: O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. ACL categories:  `@write`, `@geo`, `@slow`,   This command is exactly like [`GEORADIUS`](../georadius) with the sole difference that instead of taking, as the center of the area to query, a longitude and latitude value, it takes the name of a member already existing inside the geospatial index represented by the sorted set.

 The position of the specified member is used as the center of the query.

 Please check the example below and the [`GEORADIUS`](../georadius) documentation for more information about the command and its options.

 Note that [`GEORADIUSBYMEMBER_RO`](../georadiusbymember_ro) is also available since Redis 3.2.10 and Redis 4.0.0 in order to provide a read-only command that can be used in replicas. See the [`GEORADIUS`](../georadius) page for more information.

 Examples
--------

 
```

GEOADD Sicily 13.583333 37.316667 "Agrigento"
GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEORADIUSBYMEMBER Sicily Agrigento 100 km

```
 History
-------

 * Starting with Redis version 7.0.0: Added support for uppercase unit names.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/georadiusbymember/>

GEORADIUSBYMEMBER\_RO
=====================



```
GEORADIUSBYMEMBER_RO (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`GEOSEARCH`](../geosearch) with the `BYRADIUS` and `FROMMEMBER` arguments when migrating or writing new code.

  Syntax 
```
GEORADIUSBYMEMBER_RO key member radius <M | KM | FT | MI>
  [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count [ANY]] [ASC | DESC]
```
  Available since: 3.2.10 Time complexity: O(N+log(M)) where N is the number of elements inside the bounding box of the circular area delimited by center and radius and M is the number of items inside the index. ACL categories:  `@read`, `@geo`, `@slow`,   Read-only variant of the [`GEORADIUSBYMEMBER`](../georadiusbymember) command.

 This command is identical to the [`GEORADIUSBYMEMBER`](../georadiusbymember) command, except that it doesn't support the optional `STORE` and `STOREDIST` parameters.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/georadiusbymember_ro/>

GEOSEARCH
=========



```
GEOSEARCH
```
 Syntax 
```
GEOSEARCH key <FROMMEMBER member | FROMLONLAT longitude latitude>
  <BYRADIUS radius <M | KM | FT | MI> | BYBOX width height <M | KM |
  FT | MI>> [ASC | DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST]
  [WITHHASH]
```
  Available since: 6.2.0 Time complexity: O(N+log(M)) where N is the number of elements in the grid-aligned bounding box area around the shape provided as the filter and M is the number of items inside the shape ACL categories:  `@read`, `@geo`, `@slow`,   Return the members of a sorted set populated with geospatial information using [`GEOADD`](../geoadd), which are within the borders of the area specified by a given shape. This command extends the [`GEORADIUS`](../georadius) command, so in addition to searching within circular areas, it supports searching within rectangular areas.

 This command should be used in place of the deprecated [`GEORADIUS`](../georadius) and [`GEORADIUSBYMEMBER`](../georadiusbymember) commands.

 The query's center point is provided by one of these mandatory options:

 * `FROMMEMBER`: Use the position of the given existing `<member>` in the sorted set.
* `FROMLONLAT`: Use the given `<longitude>` and `<latitude>` position.

 The query's shape is provided by one of these mandatory options:

 * `BYRADIUS`: Similar to [`GEORADIUS`](../georadius), search inside circular area according to given `<radius>`.
* `BYBOX`: Search inside an axis-aligned rectangle, determined by `<height>` and `<width>`.

 The command optionally returns additional information using the following options:

 * `WITHDIST`: Also return the distance of the returned items from the specified center point. The distance is returned in the same unit as specified for the radius or height and width arguments.
* `WITHCOORD`: Also return the longitude and latitude of the matching items.
* `WITHHASH`: Also return the raw geohash-encoded sorted set score of the item, in the form of a 52 bit unsigned integer. This is only useful for low level hacks or debugging and is otherwise of little interest for the general user.

 Matching items are returned unsorted by default. To sort them, use one of the following two options:

 * `ASC`: Sort returned items from the nearest to the farthest, relative to the center point.
* `DESC`: Sort returned items from the farthest to the nearest, relative to the center point.

 All matching items are returned by default. To limit the results to the first N matching items, use the **COUNT `<count>`** option. When the `ANY` option is used, the command returns as soon as enough matches are found. This means that the results returned may not be the ones closest to the specified point, but the effort invested by the server to generate them is significantly less. When `ANY` is not provided, the command will perform an effort that is proportional to the number of items matching the specified area and sort them, so to query very large areas with a very small `COUNT` option may be slow even if just a few results are returned.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 * Without any `WITH` option specified, the command just returns a linear array like ["New York","Milan","Paris"].
* If `WITHCOORD`, `WITHDIST` or `WITHHASH` options are specified, the command returns an array of arrays, where each sub-array represents a single item.

 When additional information is returned as an array of arrays for each item, the first item in the sub-array is always the name of the returned item. The other information is returned in the following order as successive elements of the sub-array.

 1. The distance from the center as a floating point number, in the same unit specified in the shape.
2. The geohash integer.
3. The coordinates as a two items x,y array (longitude,latitude).

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEOADD Sicily 12.758489 38.788135 "edge1"   17.241510 38.788135 "edge2" 
GEOSEARCH Sicily FROMLONLAT 15 37 BYRADIUS 200 km ASC
GEOSEARCH Sicily FROMLONLAT 15 37 BYBOX 400 400 km ASC WITHCOORD WITHDIST

```
 History
-------

 * Starting with Redis version 7.0.0: Added support for uppercase unit names.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geosearch/>

GETEX
=====



```
GETEX
```
 Syntax 
```
GETEX key [EX seconds | PX milliseconds | EXAT unix-time-seconds |
  PXAT unix-time-milliseconds | PERSIST]
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Get the value of `key` and optionally set its expiration. `GETEX` is similar to [`GET`](../get), but is a write command with additional options.

 Options
-------

 The `GETEX` command supports a set of options that modify its behavior:

 * `EX` *seconds* -- Set the specified expire time, in seconds.
* `PX` *milliseconds* -- Set the specified expire time, in milliseconds.
* `EXAT` *timestamp-seconds* -- Set the specified Unix time at which the key will expire, in seconds.
* `PXAT` *timestamp-milliseconds* -- Set the specified Unix time at which the key will expire, in milliseconds.
* [`PERSIST`](../persist) -- Remove the time to live associated with the key.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of `key`, or `nil` when `key` does not exist.

 Examples
--------

 
```

SET mykey "Hello"
GETEX mykey
TTL mykey
GETEX mykey EX 60
TTL mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/getex/>

GETDEL
======



```
GETDEL
```
 Syntax 
```
GETDEL key
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Get the value of `key` and delete the key. This command is similar to [`GET`](../get), except for the fact that it also deletes the key on success (if and only if the key's value type is a string).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of `key`, `nil` when `key` does not exist, or an error if the key's value type isn't a string.

 Examples
--------

 
```

SET mykey "Hello"
GETDEL mykey
GET mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/getdel/>

GETSET
======



```
GETSET (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`SET`](../set) with the `GET` argument when migrating or writing new code.

  Syntax 
```
GETSET key value
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Atomically sets `key` to `value` and returns the old value stored at `key`. Returns an error when `key` exists but does not hold a string value. Any previous time to live associated with the key is discarded on successful [`SET`](../set) operation.

 Design pattern
--------------

 `GETSET` can be used together with [`INCR`](../incr) for counting with atomic reset. For example: a process may call [`INCR`](../incr) against the key `mycounter` every time some event occurs, but from time to time we need to get the value of the counter and reset it to zero atomically. This can be done using `GETSET mycounter "0"`:

 
```

INCR mycounter
GETSET mycounter "0"
GET mycounter

```
 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the old value stored at `key`, or `nil` when `key` did not exist.

 Examples
--------

 
```

SET mykey "Hello"
GETSET mykey "World"
GET mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/getset/>

GETBIT
======



```
GETBIT
```
 Syntax 
```
GETBIT key offset
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@read`, `@bitmap`, `@fast`,   Returns the bit value at *offset* in the string value stored at *key*.

 When *offset* is beyond the string length, the string is assumed to be a contiguous space with 0 bits. When *key* does not exist it is assumed to be an empty string, so *offset* is always out of range and the value is also assumed to be a contiguous space with 0 bits.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the bit value stored at *offset*.

 Examples
--------

 
```

SETBIT mykey 7 1
GETBIT mykey 0
GETBIT mykey 7
GETBIT mykey 100

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/getbit/>

GEOADD
======



```
GEOADD
```
 Syntax 
```
GEOADD key [NX | XX] [CH] longitude latitude member [longitude
  latitude member ...]
```
  Available since: 3.2.0 Time complexity: O(log(N)) for each item added, where N is the number of elements in the sorted set. ACL categories:  `@write`, `@geo`, `@slow`,   Adds the specified geospatial items (longitude, latitude, name) to the specified key. Data is stored into the key as a sorted set, in a way that makes it possible to query the items with the [`GEOSEARCH`](../geosearch) command.

 The command takes arguments in the standard format x,y so the longitude must be specified before the latitude. There are limits to the coordinates that can be indexed: areas very near to the poles are not indexable.

 The exact limits, as specified by EPSG:900913 / EPSG:3785 / OSGEO:41001 are the following:

 * Valid longitudes are from -180 to 180 degrees.
* Valid latitudes are from -85.05112878 to 85.05112878 degrees.

 The command will report an error when the user attempts to index coordinates outside the specified ranges.

 **Note:** there is no **GEODEL** command because you can use [`ZREM`](../zrem) to remove elements. The Geo index structure is just a sorted set.

 GEOADD options
--------------

 `GEOADD` also provides the following options:

 * **XX**: Only update elements that already exist. Never add elements.
* **NX**: Don't update already existing elements. Always add new elements.
* **CH**: Modify the return value from the number of new elements added, to the total number of elements changed (CH is an abbreviation of *changed*). Changed elements are **new elements added** and elements already existing for which **the coordinates was updated**. So elements specified in the command line having the same score as they had in the past are not counted. Note: normally, the return value of `GEOADD` only counts the number of new elements added.

 Note: The **XX** and **NX** options are mutually exclusive.

 How does it work?
-----------------

 The way the sorted set is populated is using a technique called [Geohash](https://en.wikipedia.org/wiki/Geohash). Latitude and Longitude bits are interleaved to form a unique 52-bit integer. We know that a sorted set double score can represent a 52-bit integer without losing precision.

 This format allows for bounding box and radius querying by checking the 1+8 areas needed to cover the whole shape and discarding elements outside it. The areas are checked by calculating the range of the box covered, removing enough bits from the less significant part of the sorted set score, and computing the score range to query in the sorted set for each area.

 What Earth model does it use?
-----------------------------

 The model assumes that the Earth is a sphere since it uses the Haversine formula to calculate distance. This formula is only an approximation when applied to the Earth, which is not a perfect sphere. The introduced errors are not an issue when used, for example, by social networks and similar applications requiring this type of querying. However, in the worst case, the error may be up to 0.5%, so you may want to consider other systems for error-critical applications.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * When used without optional arguments, the number of elements added to the sorted set (excluding score updates).
* If the `CH` option is specified, the number of elements that were changed (added or updated).

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEODIST Sicily Palermo Catania
GEORADIUS Sicily 15 37 100 km
GEORADIUS Sicily 15 37 200 km

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `CH`, `NX` and `XX` options.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geoadd/>

GRAPH.CONFIG
============



```
GRAPH.CONFIG GET
```
 Syntax 
```
GRAPH.CONFIG GET name
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.2.11](https://redis.io/docs/stack/graph)  Time complexity:  Retrieves the current value of a RedisGraph configuration parameter.

 RedisGraph configuration parameters are detailed [here](https://redis.io/docs/stack/graph/configuration).

 `*` can be used to retrieve the value of all RedisGraph configuration parameters.

 
```
127.0.0.1:6379> graph.config get *
 1) 1) "TIMEOUT"
    2) (integer) 0
 2) 1) "CACHE_SIZE"
    2) (integer) 25
 3) 1) "ASYNC_DELETE"
    2) (integer) 1
 4) 1) "OMP_THREAD_COUNT"
    2) (integer) 8
 5) 1) "THREAD_COUNT"
    2) (integer) 8
 6) 1) "RESULTSET_SIZE"
    2) (integer) -1
 7) 1) "VKEY_MAX_ENTITY_COUNT"
    2) (integer) 100000
 8) 1) "MAX_QUEUED_QUERIES"
    2) (integer) 4294967295
 9) 1) "QUERY_MEM_CAPACITY"
    2) (integer) 0
10) 1) "DELTA_MAX_PENDING_CHANGES"
    2) (integer) 10000
11) 1) "NODE_CREATION_BUFFER"
    2) (integer) 16384

```


```
127.0.0.1:6379> graph.config get TIMEOUT
1) "TIMEOUT"
2) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.config-get/>

GEODIST
=======



```
GEODIST
```
 Syntax 
```
GEODIST key member1 member2 [M | KM | FT | MI]
```
  Available since: 3.2.0 Time complexity: O(log(N)) ACL categories:  `@read`, `@geo`, `@slow`,   Return the distance between two members in the geospatial index represented by the sorted set.

 Given a sorted set representing a geospatial index, populated using the [`GEOADD`](../geoadd) command, the command returns the distance between the two specified members in the specified unit.

 If one or both the members are missing, the command returns NULL.

 The unit must be one of the following, and defaults to meters:

 * **m** for meters.
* **km** for kilometers.
* **mi** for miles.
* **ft** for feet.

 The distance is computed assuming that the Earth is a perfect sphere, so errors up to 0.5% are possible in edge cases.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), specifically:

 The command returns the distance as a double (represented as a string) in the specified unit, or NULL if one or both the elements are missing.

 Examples
--------

 
```

GEOADD Sicily 13.361389 38.115556 "Palermo" 15.087269 37.502669 "Catania"
GEODIST Sicily Palermo Catania
GEODIST Sicily Palermo Catania km
GEODIST Sicily Palermo Catania mi
GEODIST Sicily Foo Bar

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/geodist/>

GRAPH.EXPLAIN
=============



```
GRAPH.EXPLAIN
```
 Syntax 
```
GRAPH.EXPLAIN graph query
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.0.0](https://redis.io/docs/stack/graph)  Time complexity:  Constructs a query execution plan but does not run it. Inspect this execution plan to better understand how your query will get executed.

 Arguments: `Graph name, Query`

 Returns: `String representation of a query execution plan`

 
```
GRAPH.EXPLAIN us\_government "MATCH (p:President)-[:BORN]->(h:State {name:'Hawaii'}) RETURN p"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.explain/>

GRAPH.CONFIG
============



```
GRAPH.CONFIG SET
```
 Syntax 
```
GRAPH.CONFIG SET name value
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.2.11](https://redis.io/docs/stack/graph)  Time complexity:  Set the value of a RedisGraph configuration parameter.

 Values set using `GRAPH.CONFIG SET` are not persisted after server restart.

 RedisGraph configuration parameters are detailed [here](https://redis.io/docs/stack/graph/configuration).

 Note: As detailed in the link above, not all RedisGraph configuration parameters can be set at run-time.

 
```
127.0.0.1:6379> graph.config get TIMEOUT
1) "TIMEOUT"
2) (integer) 0
127.0.0.1:6379> graph.config set TIMEOUT 10000
OK
127.0.0.1:6379> graph.config get TIMEOUT
1) "TIMEOUT"
2) (integer) 10000

```


```
127.0.0.1:6379> graph.config set THREAD_COUNT 10
(error) This configuration parameter cannot be set at run-time

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.config-set/>

GRAPH.RO\_QUERY
===============



```
GRAPH.RO_QUERY
```
 Syntax 
```
GRAPH.RO_QUERY graph query [TIMEOUT timeout]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.2.8](https://redis.io/docs/stack/graph)  Time complexity:  Executes a given read only query against a specified graph.

 Arguments: `Graph name, Query, Timeout [optional]`

 Returns: [Result set](https://redis.io/docs/stack/graph/design/result_structure) for a read only query or an error if a write query was given.

 
```
GRAPH.RO\_QUERY us\_government "MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"

```

Query-level timeouts can be set as described in [the configuration section](https://redis.io/docs/stack/graph/configuration#timeout).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.ro_query/>

GRAPH.DELETE
============



```
GRAPH.DELETE
```
 Syntax 
```
GRAPH.DELETE graph
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 1.0.0](https://redis.io/docs/stack/graph)  Time complexity:  Completely removes the graph and all of its entities.

 Arguments: `Graph name`

 Returns: `String indicating if operation succeeded or failed.`

 
```
GRAPH.DELETE us\_government

```

Note: To delete a node from the graph (not the entire graph), execute a `MATCH` query and pass the alias to the `DELETE` clause:

 
```
GRAPH.QUERY DEMO_GRAPH "MATCH (x:Y {propname: propvalue}) DELETE x"

```

WARNING: When you delete a node, all of the node's incoming/outgoing relationships are also removed.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.delete/>

HEXISTS
=======



```
HEXISTS
```
 Syntax 
```
HEXISTS key field
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@read`, `@hash`, `@fast`,   Returns if `field` is an existing field in the hash stored at `key`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the hash contains `field`.
* `0` if the hash does not contain `field`, or `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "foo"
HEXISTS myhash field1
HEXISTS myhash field2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hexists/>

HELLO
=====



```
HELLO
```
 Syntax 
```
HELLO [protover [AUTH username password] [SETNAME clientname]]
```
  Available since: 6.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Switch to a different protocol, optionally authenticating and setting the connection's name, or provide a contextual client report.

 Redis version 6 and above supports two protocols: the old protocol, RESP2, and a new one introduced with Redis 6, RESP3. RESP3 has certain advantages since when the connection is in this mode, Redis is able to reply with more semantical replies: for instance, [`HGETALL`](../hgetall) will return a *map type*, so a client library implementation no longer requires to know in advance to translate the array into a hash before returning it to the caller. For a full coverage of RESP3, please check the [RESP3 specification](https://github.com/redis/redis-specifications/blob/master/protocol/RESP3.md).

 In Redis 6 connections start in RESP2 mode, so clients implementing RESP2 do not need to updated or changed. There are no short term plans to drop support for RESP2, although future version may default to RESP3.

 `HELLO` always replies with a list of current server and connection properties, such as: versions, modules loaded, client ID, replication role and so forth. When called without any arguments in Redis 6.2 and its default use of RESP2 protocol, the reply looks like this:

 
```
> HELLO
 1) "server"
 2) "redis"
 3) "version"
 4) "255.255.255"
 5) "proto"
 6) (integer) 2
 7) "id"
 8) (integer) 5
 9) "mode"
10) "standalone"
11) "role"
12) "master"
13) "modules"
14) (empty array)

```
 Clients that want to handshake using the RESP3 mode need to call the `HELLO` command and specify the value "3" as the `protover` argument, like so:

 
```
> HELLO 3
1# "server" => "redis"
2# "version" => "6.0.0"
3# "proto" => (integer) 3
4# "id" => (integer) 10
5# "mode" => "standalone"
6# "role" => "master"
7# "modules" => (empty array)

```
 Because `HELLO` replies with useful information, and given that `protover` is optional or can be set to "2", client library authors may consider using this command instead of the canonical [`PING`](../ping) when setting up the connection.

 When called with the optional `protover` argument, this command switches the protocol to the specified version and also accepts the following options:

 * `AUTH <username> <password>`: directly authenticate the connection in addition to switching to the specified protocol version. This makes calling [`AUTH`](../auth) before `HELLO` unnecessary when setting up a new connection. Note that the `username` can be set to "default" to authenticate against a server that does not use ACLs, but rather the simpler `requirepass` mechanism of Redis prior to version 6.
* `SETNAME <clientname>`: this is the equivalent of calling [`CLIENT SETNAME`](../client-setname).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of server properties. The reply is a map instead of an array when RESP3 is selected. The command returns an error if the `protover` requested does not exist.

 History
-------

 * Starting with Redis version 6.2.0: `protover` made optional; when called without arguments the command reports the current connection's context.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hello/>

GRAPH.PROFILE
=============



```
GRAPH.PROFILE
```
 Syntax 
```
GRAPH.PROFILE graph query [TIMEOUT timeout]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.0.0](https://redis.io/docs/stack/graph)  Time complexity:  Executes a query and produces an execution plan augmented with metrics for each operation's execution.

 Arguments: `Graph name, Query`

 Returns: `String representation of a query execution plan, with details on results produced by and time spent in each operation.`

 `GRAPH.PROFILE` is a parallel entrypoint to [`GRAPH.QUERY`](../graph.query). It accepts and executes the same queries, but it will not emit results, instead returning the operation tree structure alongside the number of records produced and total runtime of each operation.

 It is important to note that this blends elements of [GRAPH.QUERY](../graph.query) and [GRAPH.EXPLAIN](../graph.explain). It is not a dry run and will perform all graph modifications expected of the query, but will not output results produced by a `RETURN` clause or query statistics.

 
```
GRAPH.PROFILE imdb
"MATCH (actor\_a:Actor)-[:ACT]->(:Movie)<-[:ACT]-(actor\_b:Actor)
WHERE actor\_a <> actor\_b
CREATE (actor\_a)-[:COSTARRED\_WITH]->(actor\_b)"
1) "Create | Records produced: 11208, Execution time: 168.208661 ms"
2) " Filter | Records produced: 11208, Execution time: 1.250565 ms"
3) " Conditional Traverse | Records produced: 12506, Execution time: 7.705860 ms"
4) " Node By Label Scan | (actor\_a:Actor) | Records produced: 1317, Execution time: 0.104346 ms"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.profile/>

GRAPH.QUERY
===========



```
GRAPH.QUERY
```
 Syntax 
```
GRAPH.QUERY graph query [TIMEOUT timeout]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 1.0.0](https://redis.io/docs/stack/graph)  Time complexity:  Executes the given query against a specified graph.

 Arguments: `Graph name, Query, Timeout [optional]`

 Returns: [Result set](https://redis.io/docs/stack/graph/design/result_structure)

 ### Queries and Parameterized Queries

 The execution plans of queries, both regular and parameterized, are cached (up to [CACHE\_SIZE](https://redis.io/docs/stack/graph/configuration/#cache_size) unique queries are cached). Therefore, it is recommended to use parametrized queries when executing many queries with the same pattern but different constants.

 Query-level timeouts can be set as described in [the configuration section](https://redis.io/docs/stack/graph/configuration#timeout).

 #### Query structure:

 `GRAPH.QUERY graph_name "query"`

 example:

 
```
GRAPH.QUERY us\_government "MATCH (p:president)-[:born]->(:state {name:'Hawaii'}) RETURN p"

```

#### Parametrized query structure:

 `GRAPH.QUERY graph_name "CYPHER param=val [param=val ...] query"`

 example:

 
```
GRAPH.QUERY us\_government "CYPHER state\_name='Hawaii' MATCH (p:president)-[:born]->(:state {name:$state\_name}) RETURN p"

```

### Query language

 The syntax is based on [Cypher](http://www.opencypher.org/). [Most](https://redis.io/docs/stack/graph/cypher_support/) of the language is supported. RedisGraph-specific extensions are also described below.

 1. [Clauses](#query-structure)
2. [Functions](#functions)

 ### Query structure

 * [MATCH](#match)
* [OPTIONAL MATCH](#optional-match)
* [WHERE](#where)
* [RETURN](#return)
* [ORDER BY](#order-by)
* [SKIP](#skip)
* [LIMIT](#limit)
* [CREATE](#create)
* [MERGE](#merge)
* [DELETE](#delete)
* [SET](#set)
* [WITH](#with)
* [UNION](#union)
* [UNWIND](#unwind)
* [FOREACH](#foreach)

 #### MATCH

 Match describes the relationship between queried entities, using ascii art to represent pattern(s) to match against.

 Nodes are represented by parentheses `()`, and Relationships are represented by brackets `[]`.

 Each graph entity node/relationship can contain an alias and a label/relationship type, but both can be left empty if necessary.

 Entity structure: `alias:label {filters}`.

 Alias, label/relationship type, and filters are all optional.

 Example:

 
```
(a:Actor)-[:ACT]->(m:Movie {title:"straight outta compton"})

```

`a` is an alias for the source node, which we'll be able to refer to at different places within our query.

 `Actor` is the label under which this node is marked.

 `ACT` is the relationship type.

 `m` is an alias for the destination node.

 `Movie` destination node is of "type" movie.

 `{title:"straight outta compton"}` requires the node's title attribute to equal "straight outta compton".

 In this example, we're interested in actor entities which have the relation "act" with **the** entity representing the "straight outta compton" movie.

 It is possible to describe broader relationships by composing a multi-hop query such as:

 
```
(me {name:'swilly'})-[:FRIENDS\_WITH]->()-[:FRIENDS\_WITH]->(foaf)

```

Here we're interested in finding out who my friends' friends are.

 Nodes can have more than one relationship coming in or out of them, for instance:

 
```
(me {name:'swilly'})-[:VISITED]->(c:Country)<-[:VISITED]-(friend)<-[:FRIENDS\_WITH]-(me)

```

Here we're interested in knowing which of my friends have visited at least one country I've been to.

 ##### Variable length relationships

 Nodes that are a variable number of relationship→node hops away can be found using the following syntax:

 
```
-[:TYPE\*minHops..maxHops]->

```

[`TYPE`](../type), `minHops` and `maxHops` are all optional and default to type agnostic, 1 and infinity, respectively.

 When no bounds are given the dots may be omitted. The dots may also be omitted when setting only one bound and this implies a fixed length pattern.

 Example:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (charlie:Actor { name: 'Charlie Sheen' })-[:PLAYED\_WITH\*1..3]->(colleague:Actor)
RETURN colleague"

```

Returns all actors related to 'Charlie Sheen' by 1 to 3 hops.

 ##### Bidirectional path traversal

 If a relationship pattern does not specify a direction, it will match regardless of which node is the source and which is the destination:

 
```
-[:TYPE]-

```

Example:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (person\_a:Person)-[:KNOWS]-(person\_b:Person)
RETURN person\_a, person\_b"

```

Returns all pairs of people connected by a `KNOWS` relationship. Note that each pair will be returned twice, once with each node in the `person_a` field and once in the `person_b` field.

 The syntactic sugar `(person_a)<-[:KNOWS]->(person_b)` will return the same results.

 The bracketed edge description can be omitted if all relations should be considered: `(person_a)--(person_b)`.

 ##### Named paths

 Named path variables are created by assigning a path in a MATCH clause to a single alias with the syntax: `MATCH named_path = (path)-[to]->(capture)`

 The named path includes all entities in the path, regardless of whether they have been explicitly aliased. Named paths can be accessed using [designated built-in functions](#path-functions) or returned directly if using a language-specific client.

 Example:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH p=(charlie:Actor { name: 'Charlie Sheen' })-[:PLAYED\_WITH\*1..3]->(:Actor)
RETURN nodes(p) as actors"

```

This query will produce all the paths matching the pattern contained in the named path `p`. All of these paths will share the same starting point, the actor node representing Charlie Sheen, but will otherwise vary in length and contents. Though the variable-length traversal and `(:Actor)` endpoint are not explicitly aliased, all nodes and edges traversed along the path will be included in `p`. In this case, we are only interested in the nodes of each path, which we'll collect using the built-in function `nodes()`. The returned value will contain, in order, Charlie Sheen, between 0 and 2 intermediate nodes, and the unaliased endpoint.

 ##### All shortest paths

 The `allShortestPaths` function returns all the shortest paths between a pair of entities.

 `allShortestPaths()` is a MATCH mode in which only the shortest paths matching all criteria are captured. Both the source and the target nodes must be bound in an earlier WITH-demarcated scope to invoke `allShortestPaths()`.

 A minimal length (must be 1) and maximal length (must be at least 1) for the search may be specified. Zero or more relationship types may be specified (e.g. [:R|Q\*1..3]). No property filters may be introduced in the pattern.

 `allShortestPaths()` can have any number of hops for its minimum and maximum, including zero. This number represents how many edges can be traversed in fulfilling the pattern, with a value of 0 entailing that the source node will be included in the returned path.

 Filters on properties are supported, and any number of labels may be specified.

 Example:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (charlie:Actor {name: 'Charlie Sheen'}), (kevin:Actor {name: 'Kevin Bacon'})
WITH charlie, kevin
MATCH p=allShortestPaths((charlie)-[:PLAYED\_WITH\*]->(kevin))
RETURN nodes(p) as actors"

```

This query will produce all paths of the minimum length connecting the actor node representing Charlie Sheen to the one representing Kevin Bacon. There are several 2-hop paths between the two actors, and all of these will be returned. The computation of paths then terminates, as we are not interested in any paths of length greater than 2.

 ##### Single-Pair minimal-weight bounded-cost bounded-length paths

 (Since RedisGraph v2.10)

 The `algo.SPpaths` procedure returns one, *n*, or all minimal-weight, [optionally] bounded-cost, [optionally] bounded-length distinct paths between a pair of entities. Each path is a sequence of distinct nodes connected by distinct edges.

 `algo.SPpaths()` is a MATCH mode in which only the paths matching all criteria are captured. Both the source and the target nodes must be bound in an earlier WITH-demarcated scope to invoke `algo.SPpaths()`.

 Input arguments:

 * A map containing:
	+ `sourceNode`: Mandatory. Must be of type node
	+ `targetNode`: Mandatory. Must be of type node
	+ `relTypes`: Optional. Array of zero or more relationship types. A relationship must have one of these types to be part of the path. If not specified or empty: the path may contain any relationship.
	+ `relDirection`: Optional. string. one of `'incoming'`, `'outgoing'`, `'both'`. If not specified: `'outgoing'`.
	+ `pathCount`: Optional. Number of minimal-weight paths to retrieve. Non-negative integer. If not specified: 1
	
	
		- `0`: retrieve all minimal-weight paths (all reported paths have the same weight)
		
		 Order: 1st : minimal cost, 2nd: minimal length.
		- `1`: retrieve a single minimal-weight path
		
		 When multiple equal-weight paths exist: (preferences: 1st : minimal cost, 2nd: minimal length)
		- *n* > 1: retrieve up to *n* minimal-weight paths (reported paths may have different weights)
		
		 When multiple equal-weight paths exist: (preferences: 1st : minimal cost, 2nd: minimal length)
	+ `weightProp`: Optional. If not specified: use the default weight: 1 for each relationship.
	
	 The name of the property that represents the weight of each relationship (integer / float)
	
	 If such property doesn’t exist, of if its value is not a positive numeric - use the default weight: 1
	
	 Note: when all weights are equal: minimal-weight ≡ shortest-path.
	+ `costProp`: Optional. If not specified: use the default cost: 1 for each relationship.
	
	 The name of the property that represents the cost of each relationship (integer / float)
	
	 If such property doesn't exist, or if its value is not a positive numeric - use the default cost: 1
	+ `maxLen`: Optional. Maximal path length (number of relationships along the path). Positive integer.
	
	 If not specified: no maximal length constraint.
	+ `maxCost`: Optional. Positive numeric. If not specified: no maximal cost constraint.
	
	 The maximal cumulative cost for the relationships along the path.

 Result:

 * Paths conforming to the input arguments. For each reported path:


	+ `path` - the path
	+ `pathWeight` - the path’s weight
	+ `pathCost` - the path’s costTo retrieve additional information:


	+ The path’s length can be retrieved with `length(path)`
	+ An array of the nodes along the path can be retrieved with `nodes(path)`
	+ The path’s first node can be retrieved with `nodes(path)[0]`
	+ The path’s last node can be retrieved with `nodes(path)[-1]`
	+ An array of the relationship's costs along the path can be retrieved with `[r in relationships(path) | r.cost]` where cost is the name of the cost property
	+ An array of the relationship's weights along the path can be retrieved with `[r in relationships(path) | r.weight]` where weight is the name of the weight property

 Behavior in presence on multiple-edges:

 * multi-edges are two or more edges connecting the same pair of vertices (possibly with different weights and costs).
* All matching edges are considered. Paths with identical vertices and different edges are different paths. The following are 3 different paths ('n1', 'n2', and 'n3' are nodes; 'e1', 'e2', 'e3', and 'e4' are edges): (n1)-[e1]-(n2)-[e2]-(n3), (n1)-[e1]-(n2)-[e3]-(n3), (n1)-[e4]-(n2)-[e3]-(n3)

 Example:

 
```
GRAPH.QUERY DEMO\_GRAPH 
"MATCH (s:Actor {name: 'Charlie Sheen'}), (t:Actor {name: 'Kevin Bacon'}) 
CALL algo.SPpaths( {sourceNode: s, targetNode: t, relTypes: ['r1', 'r2', 'r3'], relDirection: 'outgoing', pathCount: 1, weightProp: 'weight', costProp: 'cost', maxLen: 3, maxCost: 100} ) 
YIELD path, pathCost, pathWeight
RETURN path ORDER BY pathCost"

```

##### Single-Source minimal-weight bounded-cost bounded-length paths

 (Since RedisGraph v2.10)

 The `algo.SSpaths` procedure returns one, *n*, or all minimal-weight, [optionally] bounded-cost, [optionally] bounded-length distinct paths from a given entity. Each path is a sequence of distinct nodes connected by distinct edges.

 `algo.SSpaths()` is a MATCH mode in which only the paths matching all criteria are captured. The source node must be bound in an earlier WITH-demarcated scope to invoke `algo.SSpaths()`.

 Input arguments:

 * A map containing:
	+ `sourceNode`: Mandatory. Must be of type node
	+ `relTypes`: Optional. Array of zero or more relationship types. A relationship must have one of these types to be part of the path. If not specified or empty: the path may contain any relationship.
	+ `relDirection`: Optional. string. one of `'incoming'`, `'outgoing'`, `'both'`. If not specified: `'outgoing'`.
	+ `pathCount`: Optional. Number of minimal-weight paths to retrieve. Non-negative integer. If not specified: 1
	
	 This number is global (not per source-target pair); all returned paths may be with the same target.
	
	
		- `0`: retrieve all minimal-weight paths (all reported paths have the same weight)
		
		 Order: 1st : minimal cost, 2nd: minimal length.
		- `1`: retrieve a single minimal-weight path
		
		 When multiple equal-weight paths exist: (preferences: 1st : minimal cost, 2nd: minimal length)
		- *n* > 1: retrieve up to *n* minimal-weight paths (reported paths may have different weights)
		
		 When multiple equal-weight paths exist: (preferences: 1st : minimal cost, 2nd: minimal length)
	+ `weightProp`: Optional. If not specified: use the default weight: 1 for each relationship.
	
	 The name of the property that represents the weight of each relationship (integer / float)
	
	 If such property doesn’t exist, of if its value is not a positive numeric - use the default weight: 1
	
	 Note: when all weights are equal: minimal-weight ≡ shortest-path.
	+ `costProp`: Optional. If not specified: use the default cost: 1 for each relationship.
	
	 The name of the property that represents the cost of each relationship (integer / float)
	
	 If such property doesn't exist, or if its value is not a positive numeric - use the default cost: 1
	+ `maxLen`: Optional. Maximal path length (number of relationships along the path). Positive integer.
	
	 If not specified: no maximal length constraint.
	+ `maxCost`: Optional. Positive numeric. If not specified: no maximal cost constraint.
	
	 The maximal cumulative cost for the relationships along the path.

 Result:

 * Paths conforming to the input arguments. For each reported path:


	+ `path` - the path
	+ `pathWeight` - the path’s weight
	+ `pathCost` - the path’s costTo retrieve additional information:


	+ The path’s length can be retrieved with `length(path)`
	+ An array of the nodes along the path can be retrieved with `nodes(path)`
	+ The path’s first node can be retrieved with `nodes(path)[0]`
	+ The path’s last node can be retrieved with `nodes(path)[-1]`
	+ An array of the relationship's costs along the path can be retrieved with `[r in relationships(path) | r.cost]` where cost is the name of the cost property
	+ An array of the relationship's weights along the path can be retrieved with `[r in relationships(path) | r.weight]` where weight is the name of the weight property

 Behavior in presence on multiple-edges:

 * multi-edges are two or more edges connecting the same pair of vertices (possibly with different weights and costs).
* All matching edges are considered. Paths with identical vertices and different edges are different paths. The following are 3 different paths ('n1', 'n2', and 'n3' are nodes; 'e1', 'e2', 'e3', and 'e4' are edges): (n1)-[e1]-(n2)-[e2]-(n3), (n1)-[e1]-(n2)-[e3]-(n3), (n1)-[e4]-(n2)-[e3]-(n3)

 Example:

 
```
GRAPH.QUERY DEMO\_GRAPH 
"MATCH (s:Actor {name: 'Charlie Sheen'})
CALL algo.SSpaths( {sourceNode: s, relTypes: ['r1', 'r2', 'r3'], relDirection: 'outgoing', pathCount: 1, weightProp: 'weight', costProp: 'cost', maxLen: 3, maxCost: 100} ) 
YIELD path, pathCost, pathWeight
RETURN path ORDER BY pathCost"

```

#### OPTIONAL MATCH

 The OPTIONAL MATCH clause is a MATCH variant that produces null values for elements that do not match successfully, rather than the all-or-nothing logic for patterns in MATCH clauses.

 It can be considered to fill the same role as LEFT/RIGHT JOIN does in SQL, as MATCH entities must be resolved but nodes and edges introduced in OPTIONAL MATCH will be returned as nulls if they cannot be found.

 OPTIONAL MATCH clauses accept the same patterns as standard MATCH clauses, and may similarly be modified by WHERE clauses.

 Multiple MATCH and OPTIONAL MATCH clauses can be chained together, though a mandatory MATCH cannot follow an optional one.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS\_AT]->(c:Company)
WHERE w.start\_date > 2016
RETURN p, w, c"

```

All `Person` nodes are returned, as well as any `WORKS_AT` relations and `Company` nodes that can be resolved and satisfy the `start_date` constraint. For each `Person` that does not resolve the optional pattern, the person will be returned as normal and the non-matching elements will be returned as null.

 Cypher is lenient in its handling of null values, so actions like property accesses and function calls on null values will return null values rather than emit errors.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS\_AT]->(c:Company)
RETURN p, w.department, ID(c) as ID"

```

In this case, `w.department` and `ID` will be returned if the OPTIONAL MATCH was successful, and will be null otherwise.

 Clauses like SET, CREATE, MERGE, and DELETE will ignore null inputs and perform the expected updates on real inputs. One exception to this is that attempting to create a relation with a null endpoint will cause an error:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (p:Person) OPTIONAL MATCH (p)-[w:WORKS\_AT]->(c:Company)
CREATE (c)-[:NEW\_RELATION]->(:NEW\_NODE)"

```

If `c` is null for any record, this query will emit an error. In this case, no changes to the graph are committed, even if some values for `c` were resolved.

 #### WHERE

 This clause is not mandatory, but if you want to filter results, you can specify your predicates here.

 Supported operations:

 * `=`
* `<>`
* `<`
* `<=`
* `>`
* `>=`
* `CONTAINS`
* `ENDS WITH`
* `IN`
* `STARTS WITH`

 Predicates can be combined using AND / OR / NOT.

 Be sure to wrap predicates within parentheses to control precedence.

 Examples:

 
```
WHERE (actor.name = "john doe" OR movie.rating > 8.8) AND movie.votes <= 250)

```


```
WHERE actor.age >= director.age AND actor.age > 32

```

It is also possible to specify equality predicates within nodes using the curly braces as such:

 
```
(:President {name:"Jed Bartlett"})-[:WON]->(:State)

```

Here we've required that the president node's name will have the value "Jed Bartlett".

 There's no difference between inline predicates and predicates specified within the WHERE clause.

 It is also possible to filter on graph patterns. The following queries, which return all presidents and the states they won in, produce the same results:

 
```
MATCH (p:President), (s:State) WHERE (p)-[:WON]->(s) RETURN p, s

```

and

 
```
MATCH (p:President)-[:WON]->(s:State) RETURN p, s

```

Pattern predicates can be also negated and combined with the logical operators AND, OR, and NOT. The following query returns all the presidents that did not win in the states where they were governors:

 
```
MATCH (p:President), (s:State) WHERE NOT (p)-[:WON]->(s) AND (p)->[:governor]->(s) RETURN p, s

```

Nodes can also be filtered by label:

 
```
MATCH (n)-[:R]->() WHERE n:L1 OR n:L2 RETURN n 

```

When possible, it is preferable to specify the label in the node pattern of the MATCH clause.

 #### RETURN

 In its simple form, Return defines which properties the returned result-set will contain.

 Its structure is a list of `alias.property` separated by commas.

 For convenience, it's possible to specify the alias only when you're interested in every attribute an entity possesses, and don't want to specify each attribute individually. For example:

 
```
RETURN movie.title, actor

```

Use the DISTINCT keyword to remove duplications within the result-set:

 
```
RETURN DISTINCT friend\_of\_friend.name

```

In the above example, suppose we have two friends, Joe and Miesha, and both know Dominick.

 DISTINCT will make sure Dominick will only appear once in the final result set.

 Return can also be used to aggregate data, similar to group by in SQL.

 Once an aggregation function is added to the return list, all other "none" aggregated values are considered as group keys, for example:

 
```
RETURN movie.title, MAX(actor.age), MIN(actor.age)

```

Here we group data by movie title and for each movie, and we find its youngest and oldest actor age.

 #### Aggregations

 Supported aggregation functions include:

 * `avg`
* `collect`
* `count`
* `max`
* `min`
* `percentileCont`
* `percentileDisc`
* `stDev`
* `sum`

 #### ORDER BY

 Order by specifies that the output be sorted and how.

 You can order by multiple properties by stating each variable in the ORDER BY clause.

 Each property may specify its sort order with `ASC`/`ASCENDING` or `DESC`/`DESCENDING`. If no order is specified, it defaults to ascending.

 The result will be sorted by the first variable listed.

 For equal values, it will go to the next property in the ORDER BY clause, and so on.

 
```
ORDER BY <alias.property [ASC/DESC] list>

```

Below we sort our friends by height. For equal heights, weight is used to break ties.

 
```
ORDER BY friend.height, friend.weight DESC

```

#### SKIP

 The optional skip clause allows a specified number of records to be omitted from the result set.

 
```
SKIP <number of records to skip>

```

This can be useful when processing results in batches. A query that would examine the second 100-element batch of nodes with the label `Person`, for example, would be:

 
```
GRAPH.QUERY DEMO\_GRAPH "MATCH (p:Person) RETURN p ORDER BY p.name SKIP 100 LIMIT 100"

```

#### LIMIT

 Although not mandatory, you can use the limit clause to limit the number of records returned by a query:

 
```
LIMIT <max records to return>

```

If not specified, there's no limit to the number of records returned by a query.

 #### CREATE

 CREATE is used to introduce new nodes and relationships.

 The simplest example of CREATE would be a single node creation:

 
```
CREATE (n)

```

It's possible to create multiple entities by separating them with a comma.

 
```
CREATE (n),(m)

```


```
CREATE (:Person {name: 'Kurt', age: 27})

```

To add relations between nodes, in the following example we first find an existing source node. After it's found, we create a new relationship and destination node.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (a:Person)
WHERE a.name = 'Kurt'
CREATE (a)-[:MEMBER]->(:Band {name:'Nirvana'})"

```

Here the source node is a bounded node, while the destination node is unbounded.

 As a result, a new node is created representing the band Nirvana and a new relation connects Kurt to the band.

 Lastly we create a complete pattern.

 All entities within the pattern which are not bounded will be created.

 
```
GRAPH.QUERY DEMO\_GRAPH
"CREATE (jim:Person{name:'Jim', age:29})-[:FRIENDS]->(pam:Person {name:'Pam', age:27})-[:WORKS]->(:Employer {name:'Dunder Mifflin'})"

```

This query will create three nodes and two relationships.

 #### DELETE

 DELETE is used to remove both nodes and relationships.

 Note that deleting a node also deletes all of its incoming and outgoing relationships.

 To delete a node and all of its relationships:

 
```
GRAPH.QUERY DEMO\_GRAPH "MATCH (p:Person {name:'Jim'}) DELETE p"

```

To delete relationship:

 
```
GRAPH.QUERY DEMO\_GRAPH "MATCH (:Person {name:'Jim'})-[r:FRIENDS]->() DELETE r"

```

This query will delete all `friend` outgoing relationships from the node with the name 'Jim'.

 #### SET

 SET is used to create or update properties on nodes and relationships.

 To set a property on a node, use [`SET`](../set).

 
```
GRAPH.QUERY DEMO\_GRAPH "MATCH (n { name: 'Jim' }) SET n.name = 'Bob'"

```

If you want to set multiple properties in one go, simply separate them with a comma to set multiple properties using a single SET clause.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (n { name: 'Jim', age:32 })
SET n.age = 33, n.name = 'Bob'"

```

The same can be accomplished by setting the graph entity variable to a map:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (n { name: 'Jim', age:32 })
SET n = {age: 33, name: 'Bob'}"

```

Using `=` in this way replaces all of the entity's previous properties, while `+=` will only set the properties it explicitly mentions.

 In the same way, the full property set of a graph entity can be assigned or merged:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (jim {name: 'Jim'}), (pam {name: 'Pam'})
SET jim = pam"

```

After executing this query, the `jim` node will have the same property set as the `pam` node.

 To remove a node's property, simply set property value to NULL.

 
```
GRAPH.QUERY DEMO\_GRAPH "MATCH (n { name: 'Jim' }) SET n.name = NULL"

```

#### MERGE

 The MERGE clause ensures that a path exists in the graph (either the path already exists, or it needs to be created).

 MERGE either matches existing nodes and binds them, or it creates new data and binds that.

 It’s like a combination of MATCH and CREATE that also allows you to specify what happens if the data was matched or created.

 For example, you can specify that the graph must contain a node for a user with a certain name.

 If there isn’t a node with the correct name, a new node will be created and its name property set.

 Any aliases in the MERGE path that were introduced by earlier clauses can only be matched; MERGE will not create them.

 When the MERGE path doesn't rely on earlier clauses, the whole path will always either be matched or created.

 If all path elements are introduced by MERGE, a match failure will cause all elements to be created, even if part of the match succeeded.

 The MERGE path can be followed by ON MATCH SET and ON CREATE SET directives to conditionally set properties depending on whether or not the match succeeded.

 **Merging nodes**

 To merge a single node with a label:

 
```
GRAPH.QUERY DEMO\_GRAPH "MERGE (robert:Critic)"

```

To merge a single node with properties:

 
```
GRAPH.QUERY DEMO\_GRAPH "MERGE (charlie { name: 'Charlie Sheen', age: 10 })"

```

To merge a single node, specifying both label and property:

 
```
GRAPH.QUERY DEMO\_GRAPH "MERGE (michael:Person { name: 'Michael Douglas' })"

```

**Merging paths**

 Because MERGE either matches or creates a full path, it is easy to accidentally create duplicate nodes.

 For example, if we run the following query on our sample graph:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MERGE (charlie { name: 'Charlie Sheen '})-[r:ACTED\_IN]->(wallStreet:Movie { name: 'Wall Street' })"

```

Even though a node with the name 'Charlie Sheen' already exists, the full pattern does not match, so 1 relation and 2 nodes - including a duplicate 'Charlie Sheen' node - will be created.

 We should use multiple MERGE clauses to merge a relation and only create non-existent endpoints:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MERGE (charlie { name: 'Charlie Sheen' })
 MERGE (wallStreet:Movie { name: 'Wall Street' })
 MERGE (charlie)-[r:ACTED\_IN]->(wallStreet)"

```

If we don't want to create anything if pattern elements don't exist, we can combine MATCH and MERGE clauses. The following query merges a relation only if both of its endpoints already exist:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (charlie { name: 'Charlie Sheen' })
 MATCH (wallStreet:Movie { name: 'Wall Street' })
 MERGE (charlie)-[r:ACTED\_IN]->(wallStreet)"

```

**On Match and On Create directives**

 Using ON MATCH and ON CREATE, MERGE can set properties differently depending on whether a pattern is matched or created.

 In this query, we'll merge paths based on a list of properties and conditionally set a property when creating new entities:

 
```
GRAPH.QUERY DEMO\_GRAPH
"UNWIND ['Charlie Sheen', 'Michael Douglas', 'Tamara Tunie'] AS actor\_name
 MATCH (movie:Movie { name: 'Wall Street' })
 MERGE (person {name: actor\_name})-[:ACTED\_IN]->(movie)
 ON CREATE SET person.first\_role = movie.name"

```

#### WITH

 The WITH clause allows parts of queries to be independently executed and have their results handled uniquely.

 This allows for more flexible query composition as well as data manipulations that would otherwise not be possible in a single query.

 If, for example, we wanted to find all children in our graph who are above the average age of all people:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (p:Person) WITH AVG(p.age) AS average\_age MATCH (:Person)-[:PARENT\_OF]->(child:Person) WHERE child.age > average\_age return child

```

This also allows us to use modifiers like `DISTINCT`, `SKIP`, `LIMIT`, and `ORDER` that otherwise require `RETURN` clauses.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (u:User) WITH u AS nonrecent ORDER BY u.lastVisit LIMIT 3 SET nonrecent.should\_contact = true"

```

#### UNWIND

 The UNWIND clause breaks down a given list into a sequence of records; each contains a single element in the list.

 The order of the records preserves the original list order.

 
```
GRAPH.QUERY DEMO\_GRAPH
"CREATE (p {array:[1,2,3]})"

```


```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (p) UNWIND p.array AS y RETURN y"

```

#### FOREACH

 (Since RedisGraph v2.12)

 The `FOREACH` clause feeds the components of a list to a sub-query comprised of **updating clauses only** (`CREATE`, `MERGE`, [`SET`](../set), `REMOVE`, `DELETE` and `FOREACH`), while passing on the records it receives without change.

 The clauses within the sub-query recognize the bound variables defined prior to the `FOREACH` clause, but are local in the sense that later clauses are not aware of the variables defined inside them. In other words, `FOREACH` uses the current context, and does not affect it.

 The `FOREACH` clause can be used for numerous purposes, such as: Updating and creating graph entities in a concise manner, marking nodes\edges that satisfy some condition or are part of a path of interest and performing conditional queries.

 We show examples of queries performing the above 3 use-cases.

 The following query will create 5 nodes, each with property `v` with the values from 0 to 4 corresponding to the appropriate index in the list.

 
```
GRAPH.QUERY DEMO\_GRAPH
"FOREACH(i in [1, 2, 3, 4] | CREATE (n:N {v: i}))"

```

The following query marks the nodes of all paths of length up to 15 km from a hotel in Toronto to a steakhouse with at least 2 Michelin stars.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH p = (hotel:HOTEL {City: 'Toronto'})-[r:ROAD\*..5]->(rest:RESTAURANT {type: 'Steakhouse'}) WHERE sum(r.length) <= 15 AND hotel.stars >= 4 AND rest.Michelin\_stars >= 2
FOREACH(n in nodes(p) | SET n.part\_of\_path = true)"

```

The following query searches for all the hotels, checks whether they buy directly from a bakery, and if not - makes sure they are marked as buying from a supplier that supplies bread, and that they do not buy directly from a bakery.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (h:HOTEL) OPTIONAL MATCH (h)-[b:BUYS\_FROM]->(bakery:BAKERY)
FOREACH(do\_perform IN CASE WHEN b = NULL THEN [1] ELSE [] END | MERGE (h)-[b2:BUYS\_FROM]->(s:SUPPLIER {supplies\_bread: true}) SET b2.direct = false)"

```

#### UNION

 The UNION clause is used to combine the result of multiple queries.

 UNION combines the results of two or more queries into a single result set that includes all the rows that belong to all queries in the union.

 The number and the names of the columns must be identical in all queries combined by using UNION.

 To keep all the result rows, use UNION ALL.

 Using just UNION will combine and remove duplicates from the result set.

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (n:Actor) RETURN n.name AS name
UNION ALL
MATCH (n:Movie) RETURN n.title AS name"

```

### Functions

 This section contains information on all supported functions from the Cypher query language.

 * [Predicate functions](#predicate-functions)
* [Scalar functions](#scalar-functions)
* [Aggregating functions](#aggregating-functions)
* [List functions](#list-functions)
* [Mathematical operators](#mathematical-operators)
* [Mathematical functions](#mathematical-functions)
* [Trigonometric functions](#trigonometric-functions)
* [String functions](#string-functions)
* [Point functions](#point-functions)
* [Type conversion functions](#type-conversion-functions)
* [Node functions](#node-functions)
* [Path functions](#path-functions)

 Predicate functions
-------------------

 

| Function | Description |
| --- | --- |
| [all(*var* IN *list* WHERE *predicate*)](#existential-comprehension-functions) | Returns true when *predicate* holds true for all elements in *list* |
| [any(*var* IN *list* WHERE *predicate*)](#existential-comprehension-functions) | Returns true when *predicate* holds true for at least one element in *list* |
| exists(*pattern*) | Returns true when at least one match for *pattern* exists |
| isEmpty(*list*|*map*|*string*) | Returns true if the input list or map contains no elements or if the input string contains no characters  Returns null when the input evaluates to null |
| [none(*var* IN *list* WHERE *predicate*)](#existential-comprehension-functions) | Returns true when *predicate* holds false for all elements in *list* |
| [single(*var* IN *list* WHERE *predicate*)](#existential-comprehension-functions) | Returns true when *predicate* holds true for exactly one element in *list* |

 Scalar functions
----------------

 

| Function | Description |
| --- | --- |
| coalesce(*expr*[, expr...]) | Returns the evaluation of the first argument that evaluates to a non-null value  Returns null when all arguments evaluate to null |
| endNode(*relationship*) | Returns the destination node of a relationship  Returns null when *relationship* evaluates to null |
| hasLabels(*node*, *labelsList*) \* | Returns true when *node* contains all labels in *labelsList*, otherwise false  Return true when *labelsList* evaluates to an empty list |
| id(*node*|*relationship*) | Returns the internal ID of a node or relationship (which is not immutable) |
| labels(*node*) | Returns a list of strings: all labels of *node*  Returns null when *node* evaluates to null |
| properties(*expr*) | When *expr* is a node or relationship: Returns a map containing all the properties of the given node or relationship  When *expr* evaluates to a map: Returns *expr* unchanged  Returns null when *expr* evaluates to null |
| randomUUID() | Returns a random UUID (Universal Unique IDentifier) |
| startNode(*relationship*) | Returns the source node of a relationship  Returns null when *relationship* evaluates to null |
| timestamp() | Returns the current system timestamp (milliseconds since epoch) |
| type(*relationship*) | Returns a string: the type of *relationship*  Returns null when *relationship* evaluates to null |
| typeOf(*expr*) \* | (Since RedisGraph v2.12)  Returns a string: the type of a literal, an expression's evaluation, an alias, a node's property, or a relationship's property  Return value is one of `Map`, `String`, `Integer`, `Boolean`, `Float`, `Node`, `Edge`, `List`, `Path`, `Point`, or `Null` |

 \* RedisGraph-specific extensions to Cypher

 Aggregating functions
---------------------

 

| Function | Description |
| --- | --- |
| avg(*expr*) | Returns the average of a set of numeric values. null values are ignored  Returns null when *expr* has no evaluations |
| collect(*expr*) | Returns a list containing all non-null elements which evaluated from a given expression |
| count(*expr*|\*) | When argument is *expr*: returns the number of non-null evaluations of *expr*  When argument is `*`: returns the total number of evaluations (including nulls) |
| max(*expr*) | Returns the maximum value in a set of values (taking into account type ordering). null values are ignored  Returns null when *expr* has no evaluations |
| min(*expr*) | Returns the minimum value in a set of values (taking into account type ordering). null values are ignored  Returns null when *expr* has no evaluations |
| percentileCont(*expr*, *percentile*) | Returns a linear-interpolated percentile (between 0.0 and 1.0) over a set of numeric values. null values are ignored  Returns null when *expr* has no evaluations |
| percentileDisc(*expr*, *percentile*) | Returns a nearest-value percentile (between 0.0 and 1.0) over a set of numeric values. null values are ignored  Returns null when *expr* has no evaluations |
| stDev(*expr*) | Returns the sample standard deviation over a set of numeric values. null values are ignored  Returns null when *expr* has no evaluations |
| stDevP(*expr*) | Returns the population standard deviation over a set of numeric values. null values are ignored  Returns null when *expr* has no evaluations |
| sum(*expr*) | Returns the sum of a set of numeric values. null values are ignored  Returns 0 when *expr* has no evaluations |

 List functions
--------------

 

| Function | Description |
| --- | --- |
| head(*expr*) | Returns the first element of a list  Returns null when *expr* evaluates to null or an empty list |
| keys(*expr*) | Returns a list of strings: all key names for given map or all property names for a given node or edge  Returns null when *expr* evaluates to null |
| last(*expr*) | Returns the last element of a list  Returns null when *expr* evaluates to null or an empty list |
| list.dedup(*list*) \* | (Since RedisGraph v2.12)  Given a list, returns a similar list after removing duplicate elements  Order is preserved, duplicates are removed from the end of the list  Returns null when *list* evaluates to null  Emit an error when *list* does not evaluate to a list or to null |
| list.insert(*list*, *idx*, *val*[, *dups* = TRUE]) \* | (Since RedisGraph v2.12)  Given a list, returns a list after inserting a given value at a given index  *idx* is 0-based when non-negative, or from the end of the list when negative  Returns null when *list* evaluates to null  Returns *list* when *val* evaluates to null  Returns *list* when *idx* evaluates to an integer not in [-NumItems-1 .. NumItems]  When *dups* evaluats to FALSE: returns *list* when *val* evaluates to a value that is already an element of *list*  Emit an error when *list* does not evaluate to a list or to null  Emit an error when *idx* does not evaluate to an integer  Emit an error when *dups*, if specified, does not evaluate to a Boolean |
| list.insertListElements(*list*, *list2*, *idx*[, *dups* = TRUE]) \* | (Since RedisGraph v2.12)  Given a list, returns a list after inserting the elements of a second list at a given index  *idx* is 0-based when non-negative, or from the end of the list when negative  Returns null when *list* evaluates to null  Returns *list* when *list2* evaluates to null  Returns *list* when *idx* evaluates to an integer not in [-NumItems-1 .. NumItems]  When *dups* evaluates to FALSE: If an element of *list2* evaluates to an element of *list* it would be skipped; If multiple elements of *list2* evaluate to the same value - this value would be inserted at most once to *list*  Emit an error when *list* does not evaluate to a list or to null  Emit an error when *list2* does not evaluate to a list or to null  Emit an error when *idx* does not evaluate to an integer  Emit an error when *dups*, if specified, does not evaluate to a Boolean |
| list.remove(*list*, *idx*[, *count* = 1]) \* | (Since RedisGraph v2.12)  Given a list, returns a list after removing a given number of consecutive elements (or less, if the end of the list has been reached). starting at a given index.  *idx* is 0-based when non-negative, or from the end of the list when negative  Returns *null* when *list* evaluates to null  Returns *list* when *idx* evaluates to an integer not in [-NumItems .. NumItems-1]  Returns *list* when *count* evaluates to a non-positive integer  Emit an error when *list* does not evaluate to a list or to null  Emit an error when *idx* does not evaluate to an integer  Emit an error when *count*, if specified, does not evaluate to an integer |
| list.sort(*list*[, *ascending* = TRUE]) \* | (Since RedisGraph v2.12)  Given a list, returns a list with similar elements, but sorted (inversely-sorted if *ascending* is evaluated to FALSE)  Returns null when *list* evaluates to null  Emit an error when *list* does not evaluate to a list or to null  Emit an error when *ascending*, if specified, does not evaluate to a Boolean |
| range(*first*, *last*[, *step* = 1]) | Returns a list of integers in the range of [start, end]. *step*, an optional integer argument, is the increment between consequtive elements |
| size(*expr*) | Returns the number of elements in a list  Returns null with *expr* evaluates to null |
| tail(*expr*) | Returns a sublist of a list, which contains all its elements except the first  Returns an empty list when *expr* containst less than 2 elements.  Returns null when *expr* evaluates to null |
| [reduce(...)](#reduce) | Returns a scalar produced by evaluating an expression against each list member |

 \* RedisGraph-specific extensions to Cypher

 Mathematical operators
----------------------

 

| Function | Description |
| --- | --- |
| + | Add two values |
| - | Subtract second value from first |
| \* | Multiply two values |
| / | Divide first value by the second |
| ^ | Raise the first value to the power of the second |
| % | Perform modulo division of the first value by the second |

 Mathematical functions
----------------------

 

| Function | Description |
| --- | --- |
| abs(*expr*) | Returns the absolute value of a numeric value  Returns null when *expr* evaluates to null |
| ceil(*expr*) \*\* | When *expr* evaluates to an integer: returns its evaluation  When *expr* evaluates to floating point: returns a floating point equals to the smallest integer greater than or equal to *expr*  Returns null when *expr* evaluates to null |
| e() | Returns the constant *e*, the base of the natural logarithm |
| exp(*expr*) | Returns *e*^*expr*, where *e* is the base of the natural logarithm  Returns null when *expr* evaluates to null |
| floor(*expr*) \*\* | When *expr* evaluates to an integer: returns its evaluation  When *expr* evaluates to a floating point: returns a floating point equals to the greatest integer less than or equal to *expr*  Returns null when *expr* evaluates to null |
| log(*expr*) | Returns the natural logarithm of a numeric value  Returns nan when *expr* evaluates to a negative numeric value, -inf when *expr* evaluates to 0, and null when *expr* evaluates to null |
| log10(*expr*) | Returns the base-10 logarithm of a numeric value  Returns nan when *expr* evaluates to a negative numeric value, -inf when *expr* evaluates to 0, and null when *expr* evaluates to null |
| pow(*base*, *exponent*) \* | Returns *base* raised to the power of *exponent* (equivalent to *base*^*exponent*)  Returns null when either evaluates to null |
| rand() | Returns a random floating point in the range [0,1] |
| round(*expr*) \*\* \*\*\* | When *expr* evaluates to an integer: returns its evaluation  When *expr* evaluates to a floating point: returns a floating point equals to the integer closest to *expr*  Returns null when *expr* evaluates to null |
| sign(*expr*) | Returns the signum of a numeric value: 0 when *expr* evaluates to 0, -1 when *expr* evaluates to a negative numeric value, and 1 when *expr* evaluates to a positive numeric value  Returns null when *expr* evaluates to null |
| sqrt(*expr*) | Returns the square root of a numeric value  Returns nan when *expr* evaluates to a negative value and null when *expr* evaluates to null |

 \* RedisGraph-specific extensions to Cypher

 \*\* RedisGraph-specific behavior: to avoid possible loss of precision, when *expr* evaluates to an integer - the result is an integer as well

 \*\*\* RedisGraph-specific behavior: tie-breaking method is "half away from zero"

 Trigonometric functions
-----------------------

 

| Function | Description |
| --- | --- |
| acos(*expr*) | Returns the arccosine, in radians, of a numeric value  Returns nan when *expr* evaluates to a numeric value not in [-1, 1] and null when *expr* evaluates to null |
| asin(*expr*) | Returns the arcsine, in radians, of a numeric value  Returns nan when *expr* evaluates to a numeric value not in [-1, 1] and null when *expr* evaluates to null |
| atan(*expr*) | Returns the arctangent, in radians, of a numeric value  Returns null when *expr* evaluates to null |
| atan2(*expr*, *expr*) | Returns the 2-argument arctangent, in radians, of a pair of numeric values (Cartesian coordinates)  Returns 0 when both expressions evaluate to 0  Returns null when either expression evaluates to null |
| cos(*expr*) | Returns the cosine of a numeric value that represents an angle in radians  Returns null when *expr* evaluates to null |
| cot(*expr*) | Returns the cotangent of a numeric value that represents an angle in radians  Returns inf when *expr* evaluates to 0 and null when *expr* evaluates to null |
| degrees(*expr*) | Converts a numeric value from radians to degrees  Returns null when *expr* evaluates to null |
| haversin(*expr*) | Returns half the versine of a numeric value that represents an angle in radians  Returns null when *expr* evaluates to null |
| pi() | Returns the mathematical constant *pi* |
| radians(*expr*) | Converts a numeric value from degrees to radians  Returns null when *expr* evaluates to null |
| sin(*expr*) | Returns the sine of a numeric value that represents an angle in radians  Returns null when *expr* evaluates to null |
| tan(*expr*) | Returns the tangent of a numeric value that represents an angle in radians  Returns null when *expr* evaluates to null |

 String functions
----------------

 

| Function | Description |
| --- | --- |
| left(*str*, *len*) | Returns a string containing the *len* leftmost characters of *str*  Returns null when *str* evaluates to null, otherwise emit an error if *len* evaluates to null |
| lTrim(*str*) | Returns *str* with leading whitespace removed  Returns null when *str* evaluates to null |
| replace(*str*, *search*, *replace*) | Returns *str* with all occurrences of *search* replaced with *replace*  Returns null when any argument evaluates to null |
| reverse(*str*) | Returns a string in which the order of all characters in *str* are reversed  Returns null when *str* evaluates to null |
| right(*str*, *len*) | Returns a string containing the *len* rightmost characters of *str*  Returns null when *str* evaluates to null, otherwise emit an error if *len* evaluates to null |
| rTrim(*str*) | Returns *str* with trailing whitespace removed  Returns null when *str* evaluates to null |
| split(*str*, *delimiter*) | Returns a list of strings from splitting *str* by *delimiter*  Returns null when any argument evaluates to null |
| string.join(*strList*[, *delimiter* = '']) \* | (Since RedisGraph v2.12)  Returns a concatenation of a list of strings using a given delimiter  Returns null when *strList* evaluates to null  Returns null when *delimiter*, if specified, evaluates to null  Emit an error when *strList* does not evaluate to a list or to null  Emit an error when an element of *strList* does not evaluate to a string  Emit an error when *delimiter*, if specified, does not evaluate to a string or to null |
| string.matchRegEx(*str*, *regex*) \* | (Since RedisGraph v2.12)  Given a string and a regular expression, returns a list of all matches and matching regions  Returns an empty list when *str* evaluates to null  Returns an empty list when *regex* evaluates to null  Emit an error when *str* does not evaluate to a string or to null  Emit an error when *regex* does not evaluate to a valid regex string or to null |
| string.replaceRegEx(*str*, *regex*, *replacement*) \* | (Since RedisGraph v2.12)  Given a string and a regular expression, returns a string after replacing each regex match with a given replacement  Returns null when *str* evaluates to null  Returns null when *regex* evaluates to null  Returns null when *replacement* evaluates to null  Emit an error when *str* does not evaluate to a string or to null  Emit an error when *regex* does not evaluate to a valid regex string or to null  Emit an error when *replacement* does not evaluate to a string or to null |
| substring(*str*, *start*[, *len*]) | When *len* is specified: returns a substring of *str* beginning with a 0-based index *start* and with length *len*  When *len* is not specified: returns a substring of *str* beginning with a 0-based index *start* and extending to the end of *str*  Returns null when *str* evaluates to null  Emit an error when *start* or *len* evaluate to null |
| toLower(*str*) | Returns *str* in lowercase  Returns null when *str* evaluates to null |
| toJSON(*expr*) \* | Returns a [JSON representation](#json-format) of a value  Returns null when *expr* evaluates to null |
| toUpper(*str*) | Returns *str* in uppercase  Returns null when *str* evaluates to null |
| trim(*str*) | Returns *str* with leading and trailing whitespace removed  Returns null when *str* evaluates to null |
| size(*str*) | Returns the number of characters in *str*  Returns null when *str* evaluates to null |

 \* RedisGraph-specific extensions to Cypher

 Point functions
---------------

 

| Function | Description |
| --- | --- |
| [point(*map*)](#point) | Returns a Point representing a lat/lon coordinates |
| distance(*point1*, *point2*) | Returns the distance in meters between the two given points  Returns null when either evaluates to null |

 Type conversion functions
-------------------------

 

| Function | Description |
| --- | --- |
| toBoolean(*expr*) | Returns a Boolean when *expr* evaluates to a Boolean  Converts a string to Boolean (`"true"` (case insensitive) to true, `"false"` (case insensitive) to false, any other value to null)  Converts an integer to Boolean (0 to `false`, any other values to `true`)  Returns null when *expr* evaluates to null  Emit an error on other types |
| toBooleanList(*exprList*) | Converts a list to a list of Booleans. Each element in the list is converted using toBooleanOrNull() |
| toBooleanOrNull(*expr*) | Returns a Boolean when *expr* evaluates to a Boolean  Converts a string to Boolean (`"true"` (case insensitive) to true, `"false"` (case insensitive) to false, any other value to null)  Converts an integer to Boolean (0 to `false`, any other values to `true`)  Returns null when *expr* evaluates to null  Returns null for other types |
| toFloat(*expr*) | Returns a floating point when *expr* evaluates to a floating point  Converts an integer to a floating point  Converts a string to a floating point or null  Returns null when *expr* evaluates to null  Emit an error on other types |
| toFloatList(*exprList*) | Converts a list to a list of floating points. Each element in the list is converted using toFloatOrNull() |
| toFloatOrNull(*expr*) | Returns a floating point when *expr* evaluates to a floating point  Converts an integer to a floating point  Converts a string to a floating point or null  Returns null when *expr* evaluates to null  Returns null for other types |
| toInteger(*expr*) \* | Returns an integer when *expr* evaluates to an integer  Converts a floating point to integer  Converts a string to an integer or null  Converts a Boolean to an integer (false to 0, true to 1) (Since RedisGraph v2.10.8)  Returns null when *expr* evaluates to null  Emit an error on other types |
| toIntegerList(*exprList*) \* | Converts a list to a list of integer values. Each element in the list is converted using toIntegerOrNull() |
| toIntegerOrNull(*expr*) \* | Returns an integer when *expr* evaluates to an integer  Converts a floating point to integer  Converts a string to an integer or null  Converts a Boolean to an integer (false to 0, true to 1) (Since RedisGraph v2.10.8)  Returns null when *expr* evaluates to null  Returns null for other types |
| toString(*expr*) | Returns a string when *expr* evaluates to a string  Converts an integer, float, Boolean, string, or point to a string representation  Returns null when *expr* evaluates to null  Emit an error on other types |
| toStringList(*exprList*) | Converts a list to a list of strings. Each element in the list is converted using toStringOrNull() |
| toStringOrNull(*expr*) | Returns a string when *expr* evaluates to a string  Converts an integer, float, Boolean, string, or point to a string representation  Returns null when *expr* evaluates to null  Returns null for other types |

 \* RedisGraph-specific behavior: rounding method when converting a floating point to an integer is "toward negative infinity (floor)"

 Node functions
--------------

 

| Function | Description |
| --- | --- |
| indegree(*node* [, *reltype* ...]) \*  indegree(*node* [, *reltypeList*]) \* | When no relationship types are specified: Returns the number of *node*'s incoming edges  When one or more relationship types are specified: Returns the number of *node's* incoming edges with one of the given relationship types  Return null when *node* evaluates to null  the *reltypeList* syntax is supported since RedisGraph v2.10.8 |
| outdegree(*node* [, *reltype* ...]) \*  outdegree(*node* [, *reltypeList*]) \* | When no relationship types are specified: Returns the number of *node*'s outgoing edges  When one or more relationship types are specified: Returns the number of *node's* outgoing edges with one of the given relationship types  Return null when *node* evaluates to null  the *reltypeList* syntax is supported since RedisGraph v2.10.8 |

 \* RedisGraph-specific extensions to Cypher

 Path functions
--------------

 

| Function | Description |
| --- | --- |
| nodes(*path*) | Returns a list containing all the nodes in *path*  Returns null if *path* evaluates to null |
| relationships(*path*) | Returns a list containing all the relationships in *path*  Returns null if *path* evaluates to null |
| length(*path*) | Return the length (number of edges) of *path*  Returns null if *path* evaluates to null |
| [shortestPath(...)](#shortestPath) \* | Return the shortest path that resolves the given pattern |

 \* RedisGraph-specific extensions to Cypher

 ### List comprehensions

 List comprehensions are a syntactical construct that accepts an array and produces another based on the provided map and filter directives.

 They are a common construct in functional languages and modern high-level languages. In Cypher, they use the syntax:

 
```
[element IN array WHERE condition | output elem]

```

* `array` can be any expression that produces an array: a literal, a property reference, or a function call.
* `WHERE condition` is an optional argument to only project elements that pass a certain criteria. If omitted, all elements in the array will be represented in the output.
* `| output elem` is an optional argument that allows elements to be transformed in the output array. If omitted, the output elements will be the same as their corresponding inputs.

 The following query collects all paths of any length, then for each produces an array containing the `name` property of every node with a `rank` property greater than 10:

 
```
MATCH p=()-[\*]->() RETURN [node IN nodes(p) WHERE node.rank > 10 | node.name]

```

#### Existential comprehension functions

 The functions `any()`, `all()`, `single()` and `none()` use a simplified form of the list comprehension syntax and return a boolean value.

 
```
any(element IN array WHERE condition)

```

They can operate on any form of input array, but are particularly useful for path filtering. The following query collects all paths of any length in which all traversed edges have a weight less than 3:

 
```
MATCH p=()-[\*]->() WHERE all(edge IN relationships(p) WHERE edge.weight < 3) RETURN p

```

### Pattern comprehensions

 Pattern comprehensions are a method of producing a list composed of values found by performing the traversal of a given graph pattern.

 The following query returns the name of a `Person` node and a list of all their friends' ages:

 
```
MATCH (n:Person)
RETURN
n.name,
[(n)-[:FRIEND\_OF]->(f:Person) | f.age]

```

Optionally, a `WHERE` clause may be embedded in the pattern comprehension to filter results. In this query, all friends' ages will be gathered for friendships that started before 2010:

 
```
MATCH (n:Person)
RETURN
n.name,
[(n)-[e:FRIEND\_OF]->(f:Person) WHERE e.since < 2010 | f.age]

```

### CASE WHEN

 The case statement comes in two variants. Both accept an input argument and evaluates it against one or more expressions. The first `WHEN` argument that specifies a value matching the result will be accepted, and the value specified by the corresponding `THEN` keyword will be returned.

 Optionally, an `ELSE` argument may also be specified to indicate what to do if none of the `WHEN` arguments match successfully.

 In its simple form, there is only one expression to evaluate and it immediately follows the `CASE` keyword:

 
```
MATCH (n)
RETURN
CASE n.title
WHEN 'Engineer' THEN 100
WHEN 'Scientist' THEN 80
ELSE n.privileges
END

```

In its generic form, no expression follows the `CASE` keyword. Instead, each `WHEN` statement specifies its own expression:

 
```
MATCH (n)
RETURN
CASE
WHEN n.age < 18 THEN '0-18'
WHEN n.age < 30 THEN '18-30'
ELSE '30+'
END

```

#### Reduce

 The `reduce()` function accepts a starting value and updates it by evaluating an expression against each element of the list:

 
```
RETURN reduce(sum = 0, n IN [1,2,3] | sum + n)

```

`sum` will successively have the values 0, 1, 3, and 6, with 6 being the output of the function call.

 ### Point

 The `point()` function expects one map argument of the form:

 
```
RETURN point({latitude: lat\_value, longitude: lon\_val})

```

The key names `latitude` and `longitude` are case-sensitive.

 The point constructed by this function can be saved as a node/relationship property or used within the query, such as in a `distance` function call.

 ### shortestPath

 The `shortestPath()` function is invoked with the form:

 
```
MATCH (a {v: 1}), (b {v: 4}) RETURN shortestPath((a)-[:L\*]->(b))

```

The sole `shortestPath` argument is a traversal pattern. This pattern's endpoints must be resolved prior to the function call, and no property filters may be introduced in the pattern. The relationship pattern may specify any number of relationship types (including zero) to be considered. If a minimum number of edges to traverse is specified, it may only be 0 or 1, while any number may be used for the maximum. If 0 is specified as the minimum, the source node will be included in the returned path. If no shortest path can be found, NULL is returned.

 ### JSON format

 `toJSON()` returns the input value in JSON formatting. For primitive data types and arrays, this conversion is conventional. Maps and map projections (`toJSON(node { .prop} )`) are converted to JSON objects, as are nodes and relationships.

 The format for a node object in JSON is:

 
```
{
 "type": "node",
 "id": id(int),
 "labels": [label(string) X N],
 "properties": {
 property\_key(string): property\_value X N
 }
}

```

The format for a relationship object in JSON is:

 
```
{
 "type": "relationship",
 "id": id(int),
 "relationship": type(string),
 "properties": {
 property\_key(string): property\_value X N
 }
 "start": src\_node(node),
 "end": dest\_node(node)
}

```

Procedures
----------

 Procedures are invoked using the syntax:

 
```
GRAPH.QUERY social "CALL db.labels()"

```

Or the variant:

 
```
GRAPH.QUERY social "CALL db.labels() YIELD label"

```

YIELD modifiers are only required if explicitly specified; by default the value in the 'Yields' column will be emitted automatically.

 

| Procedure | Arguments | Yields | Description |
| --- | --- | --- | --- |
| db.labels | none | `label` | Yields all node labels in the graph. |
| db.relationshipTypes | none | `relationshipType` | Yields all relationship types in the graph. |
| db.propertyKeys | none | `propertyKey` | Yields all property keys in the graph. |
| db.indexes | none | `type`, `label`, `properties`, `language`, `stopwords`, `entitytype`, `info` | Yield all indexes in the graph, denoting whether they are exact-match or full-text and which label and properties each covers and whether they are indexing node or relationship attributes. |
| db.constraints | none | `type`, `label`, `properties`, `entitytype`, `status` | Yield all constraints in the graph, denoting constraint type (UNIQIE/MANDATORY), which label/relationship-type and properties each enforces. |
| db.idx.fulltext.createNodeIndex | `label`, `property` [, `property` ...] | none | Builds a full-text searchable index on a label and the 1 or more specified properties. |
| db.idx.fulltext.drop | `label` | none | Deletes the full-text index associated with the given label. |
| db.idx.fulltext.queryNodes | `label`, `string` | `node`, `score` | Retrieve all nodes that contain the specified string in the full-text indexes on the given label. |
| algo.pageRank | `label`, `relationship-type` | `node`, `score` | Runs the pagerank algorithm over nodes of given label, considering only edges of given relationship type. |
| [algo.BFS](#BFS) | `source-node`, `max-level`, `relationship-type` | `nodes`, `edges` | Performs BFS to find all nodes connected to the source. A `max level` of 0 indicates unlimited and a non-NULL `relationship-type` defines the relationship type that may be traversed. |
| dbms.procedures() | none | `name`, `mode` | List all procedures in the DBMS, yields for every procedure its name and mode (read/write). |

 ### Algorithms

 #### BFS

 The breadth-first-search algorithm accepts 4 arguments:

 `source-node (node)` - The root of the search.

 `max-level (integer)` - If greater than zero, this argument indicates how many levels should be traversed by BFS. 1 would retrieve only the source's neighbors, 2 would retrieve all nodes within 2 hops, and so on.

 `relationship-type (string)` - If this argument is NULL, all relationship types will be traversed. Otherwise, it specifies a single relationship type to perform BFS over.

 It can yield two outputs:

 `nodes` - An array of all nodes connected to the source without violating the input constraints.

 `edges` - An array of all edges traversed during the search. This does not necessarily contain all edges connecting nodes in the tree, as cycles or multiple edges connecting the same source and destination do not have a bearing on the reachability this algorithm tests for. These can be used to construct the directed acyclic graph that represents the BFS tree. Emitting edges incurs a small performance penalty.

 Indexing
--------

 RedisGraph supports single-property indexes for node labels and for relationship type. String, numeric, and geospatial data types can be indexed.

 ### Creating an index for a node label

 For a node label, the index creation syntax is:

 
```
GRAPH.QUERY DEMO\_GRAPH "CREATE INDEX FOR (p:Person) ON (p.age)"

```

An old syntax is also supported:

 
```
GRAPH.QUERY DEMO\_GRAPH "CREATE INDEX ON :Person(age)"

```

After an index is explicitly created, it will automatically be used by queries that reference that label and any indexed property in a filter.

 
```
GRAPH.EXPLAIN DEMO\_GRAPH "MATCH (p:Person) WHERE p.age > 80 RETURN p"
1) "Results"
2) " Project"
3) " Index Scan | (p:Person)"

```

This can significantly improve the runtime of queries with very specific filters. An index on `:employer(name)`, for example, will dramatically benefit the query:

 
```
GRAPH.QUERY DEMO\_GRAPH
"MATCH (:Employer {name: 'Dunder Mifflin'})-[:EMPLOYS]->(p:Person) RETURN p"

```

An example of utilizing a geospatial index to find `Employer` nodes within 5 kilometers of Scranton is:

 
```
GRAPH.QUERY DEMO\_GRAPH
"WITH point({latitude:41.4045886, longitude:-75.6969532}) AS scranton MATCH (e:Employer) WHERE distance(e.location, scranton) < 5000 RETURN e"

```

Geospatial indexes can currently only be leveraged with `<` and `<=` filters; matching nodes outside of the given radius is performed using conventional matching.

 ### Creating an index for a relationship type

 For a relationship type, the index creation syntax is:

 
```
GRAPH.QUERY DEMO\_GRAPH "CREATE INDEX FOR ()-[f:FOLLOW]-() ON (f.created\_at)"

```

Then the execution plan for using the index:

 
```
GRAPH.EXPLAIN DEMO\_GRAPH "MATCH (p:Person {id: 0})-[f:FOLLOW]->(fp) WHERE 0 < f.created\_at AND f.created\_at < 1000 RETURN fp"
1) "Results"
2) " Project"
3) " Edge By Index Scan | [f:FOLLOW]"
4) " Node By Index Scan | (p:Person)"

```

This can significantly improve the runtime of queries that traverse super nodes or when we want to start traverse from relationships.

 ### Deleting an index for a node label

 For a node label, the index deletion syntax is:

 
```
GRAPH.QUERY DEMO\_GRAPH "DROP INDEX ON :Person(age)"

```

### Deleting an index for a relationship type

 For a relationship type, the index deletion syntax is:

 
```
GRAPH.QUERY DEMO\_GRAPH "DROP INDEX ON :FOLLOW(created\_at)"

```

Full-text indexing
------------------

 RedisGraph leverages the indexing capabilities of [RediSearch](https://redis.io/docs/stack/search/index.html) to provide full-text indices through procedure calls.

 ### Creating a full-text index for a node label

 To construct a full-text index on the `title` property of all nodes with label `Movie`, use the syntax:

 
```
GRAPH.QUERY DEMO\_GRAPH "CALL db.idx.fulltext.createNodeIndex('Movie', 'title')"

```

More properties can be added to this index by adding their names to the above set of arguments, or using this syntax again with the additional names.

 
```
GRAPH.QUERY DEMO\_GRAPH "CALL db.idx.fulltext.createNodeIndex('Person', 'firstName', 'lastName')"

```

RediSearch provide 2 index configuration options:

 1. Language - Define which language to use for stemming text which is adding the base form of a word to the index. This allows the query for "going" to also return results for "go" and "gone", for example.
2. Stopwords - These are words that are usually so common that they do not add much information to search, but take up a lot of space and CPU time in the index.

 To construct a full-text index on the `title` property using `German` language and using custom stopwords of all nodes with label `Movie`, use the syntax:

 
```
GRAPH.QUERY DEMO\_GRAPH "CALL db.idx.fulltext.createNodeIndex({ label: 'Movie', language: 'German', stopwords: ['a', 'ab'] }, 'title')"

```

RediSearch provide 3 additional field configuration options:

 1. Weight - The importance of the text in the field
2. Nostem - Skip stemming when indexing text
3. Phonetic - Enable phonetic search on the text

 To construct a full-text index on the `title` property with phonetic search of all nodes with label `Movie`, use the syntax:

 
```
GRAPH.QUERY DEMO\_GRAPH "CALL db.idx.fulltext.createNodeIndex('Movie', {field: 'title', phonetic: 'dm:en'})"

```

### Utilizing a full-text index for a node label

 An index can be invoked to match any whole words contained within:

 
```
GRAPH.QUERY DEMO\_GRAPH
"CALL db.idx.fulltext.queryNodes('Movie', 'Book') YIELD node RETURN node.title"
1) 1) "node.title"
2) 1) 1) "The Jungle Book"
 2) 1) "The Book of Life"
3) 1) "Query internal execution time: 0.927409 milliseconds"

```

This CALL clause can be interleaved with other Cypher clauses to perform more elaborate manipulations:

 
```
GRAPH.QUERY DEMO\_GRAPH
"CALL db.idx.fulltext.queryNodes('Movie', 'Book') YIELD node AS m
WHERE m.genre = 'Adventure'
RETURN m ORDER BY m.rating"
1) 1) "m"
2) 1) 1) 1) 1) "id"
 2) (integer) 1168
 2) 1) "labels"
 2) 1) "Movie"
 3) 1) "properties"
 2) 1) 1) "genre"
 2) "Adventure"
 2) 1) "rating"
 2) "7.6"
 3) 1) "votes"
 2) (integer) 151342
 4) 1) "year"
 2) (integer) 2016
 5) 1) "title"
 2) "The Jungle Book"
3) 1) "Query internal execution time: 0.226914 milliseconds"

```

In addition to yielding matching nodes, full-text index scans will return the score of each node. This is the [TF-IDF](https://redis.io/docs/stack/search/reference/scoring/#tfidf-default) score of the node, which is informed by how many times the search terms appear in the node and how closely grouped they are. This can be observed in the example:

 
```
GRAPH.QUERY DEMO\_GRAPH
"CALL db.idx.fulltext.queryNodes('Node', 'hello world') YIELD node, score RETURN score, node.val"
1) 1) "score"
 2) "node.val"
2) 1) 1) "2"
 2) "hello world"
 2) 1) "1"
 2) "hello to a different world"
3) 1) "Cached execution: 1"
 2) "Query internal execution time: 0.335401 milliseconds"

```

### Deleting a full-text index for a node label

 For a node label, the full-text index deletion syntax is:

 
```
GRAPH.QUERY DEMO_GRAPH "CALL db.idx.fulltext.drop('Movie')"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.query/>

GRAPH.LIST
==========



```
GRAPH.LIST
```
 Syntax 
```
GRAPH.LIST
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.4.3](https://redis.io/docs/stack/graph)  Time complexity:  Lists all graph keys in the keyspace.

 
```
127.0.0.1:6379> GRAPH.LIST
2) G
3) resources
4) players

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.list/>

GRAPH.SLOWLOG
=============



```
GRAPH.SLOWLOG
```
 Syntax 
```
GRAPH.SLOWLOG graph
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Graph 2.0.12](https://redis.io/docs/stack/graph)  Time complexity:  Returns a list containing up to 10 of the slowest queries issued against the given graph ID.

 Each item in the list has the following structure:

 1. A Unix timestamp at which the log entry was processed.
2. The issued command.
3. The issued query.
4. The amount of time needed for its execution, in milliseconds.

 
```
GRAPH.SLOWLOG graph\_id
 1) 1) "1581932396"
 2) "GRAPH.QUERY"
 3) "MATCH (a:Person)-[:FRIEND]->(e) RETURN e.name"
 4) "0.831"
 2) 1) "1581932396"
 2) "GRAPH.QUERY"
 3) "MATCH (me:Person)-[:FRIEND]->(:Person)-[:FRIEND]->(fof:Person) RETURN fof.name"
 4) "0.288"

```

To reset a graph's slowlog issue the following command:

 
```
GRAPH.SLOWLOG graph\_id RESET

```

Once cleared the information is lost forever.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/graph.slowlog/>

HDEL
====



```
HDEL
```
 Syntax 
```
HDEL key field [field ...]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of fields to be removed. ACL categories:  `@write`, `@hash`, `@fast`,   Removes the specified fields from the hash stored at `key`. Specified fields that do not exist within this hash are ignored. If `key` does not exist, it is treated as an empty hash and this command returns `0`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of fields that were removed from the hash, not including specified but non existing fields.

 Examples
--------

 
```

HSET myhash field1 "foo"
HDEL myhash field1
HDEL myhash field2

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple `field` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hdel/>

HGETALL
=======



```
HGETALL
```
 Syntax 
```
HGETALL key
```
  Available since: 2.0.0 Time complexity: O(N) where N is the size of the hash. ACL categories:  `@read`, `@hash`, `@slow`,   Returns all fields and values of the hash stored at `key`. In the returned value, every field name is followed by its value, so the length of the reply is twice the size of the hash.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of fields and their values stored in the hash, or an empty list when `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "Hello"
HSET myhash field2 "World"
HGETALL myhash

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hgetall/>

HINCRBY
=======



```
HINCRBY
```
 Syntax 
```
HINCRBY key field increment
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@write`, `@hash`, `@fast`,   Increments the number stored at `field` in the hash stored at `key` by `increment`. If `key` does not exist, a new key holding a hash is created. If `field` does not exist the value is set to `0` before the operation is performed.

 The range of values supported by `HINCRBY` is limited to 64 bit signed integers.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the value at `field` after the increment operation.

 Examples
--------

 Since the `increment` argument is signed, both increment and decrement operations can be performed:

 
```

HSET myhash field 5
HINCRBY myhash field 1
HINCRBY myhash field -1
HINCRBY myhash field -10

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hincrby/>

HLEN
====



```
HLEN
```
 Syntax 
```
HLEN key
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@read`, `@hash`, `@fast`,   Returns the number of fields contained in the hash stored at `key`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): number of fields in the hash, or `0` when `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "Hello"
HSET myhash field2 "World"
HLEN myhash

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hlen/>

HGET
====



```
HGET
```
 Syntax 
```
HGET key field
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@read`, `@hash`, `@fast`,   Returns the value associated with `field` in the hash stored at `key`.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value associated with `field`, or `nil` when `field` is not present in the hash or `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "foo"
HGET myhash field1
HGET myhash field2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hget/>

HSCAN
=====



```
HSCAN
```
 Syntax 
```
HSCAN key cursor [MATCH pattern] [COUNT count]
```
  Available since: 2.8.0 Time complexity: O(1) for every call. O(N) for a complete iteration, including enough command calls for the cursor to return back to 0. N is the number of elements inside the collection. ACL categories:  `@read`, `@hash`, `@slow`,   See [`SCAN`](../scan) for `HSCAN` documentation.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hscan/>

HINCRBYFLOAT
============



```
HINCRBYFLOAT
```
 Syntax 
```
HINCRBYFLOAT key field increment
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@write`, `@hash`, `@fast`,   Increment the specified `field` of a hash stored at `key`, and representing a floating point number, by the specified `increment`. If the increment value is negative, the result is to have the hash field value **decremented** instead of incremented. If the field does not exist, it is set to `0` before performing the operation. An error is returned if one of the following conditions occur:

 * The field contains a value of the wrong type (not a string).
* The current field content or the specified increment are not parsable as a double precision floating point number.

 The exact behavior of this command is identical to the one of the [`INCRBYFLOAT`](../incrbyfloat) command, please refer to the documentation of [`INCRBYFLOAT`](../incrbyfloat) for further information.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of `field` after the increment.

 Examples
--------

 
```

HSET mykey field 10.50
HINCRBYFLOAT mykey field 0.1
HINCRBYFLOAT mykey field -5
HSET mykey field 5.0e3
HINCRBYFLOAT mykey field 2.0e2

```
 Implementation details
----------------------

 The command is always propagated in the replication link and the Append Only File as a [`HSET`](../hset) operation, so that differences in the underlying floating point math implementation will not be sources of inconsistency.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hincrbyfloat/>

INCR
====



```
INCR
```
 Syntax 
```
INCR key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Increments the number stored at `key` by one. If the key does not exist, it is set to `0` before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.

 **Note**: this is a string operation because Redis does not have a dedicated integer type. The string stored at the key is interpreted as a base-10 **64 bit signed integer** to execute the operation.

 Redis stores integers in their integer representation, so for string values that actually hold an integer, there is no overhead for storing the string representation of the integer.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the value of `key` after the increment

 Examples
--------

 
```

SET mykey "10"
INCR mykey
GET mykey

```
 Pattern: Counter
----------------

 The counter pattern is the most obvious thing you can do with Redis atomic increment operations. The idea is simply send an `INCR` command to Redis every time an operation occurs. For instance in a web application we may want to know how many page views this user did every day of the year.

 To do so the web application may simply increment a key every time the user performs a page view, creating the key name concatenating the User ID and a string representing the current date.

 This simple pattern can be extended in many ways:

 * It is possible to use `INCR` and [`EXPIRE`](../expire) together at every page view to have a counter counting only the latest N page views separated by less than the specified amount of seconds.
* A client may use GETSET in order to atomically get the current counter value and reset it to zero.
* Using other atomic increment/decrement commands like [`DECR`](../decr) or [`INCRBY`](../incrby) it is possible to handle values that may get bigger or smaller depending on the operations performed by the user. Imagine for instance the score of different users in an online game.

 Pattern: Rate limiter
---------------------

 The rate limiter pattern is a special counter that is used to limit the rate at which an operation can be performed. The classical materialization of this pattern involves limiting the number of requests that can be performed against a public API.

 We provide two implementations of this pattern using `INCR`, where we assume that the problem to solve is limiting the number of API calls to a maximum of *ten requests per second per IP address*.

 Pattern: Rate limiter 1
-----------------------

 The more simple and direct implementation of this pattern is the following:

 
```
FUNCTION LIMIT_API_CALL(ip)
ts = CURRENT_UNIX_TIME()
keyname = ip+":"+ts
MULTI
    INCR(keyname)
    EXPIRE(keyname,10)
EXEC
current = RESPONSE_OF_INCR_WITHIN_MULTI
IF current > 10 THEN
    ERROR "too many requests per second"
ELSE
    PERFORM_API_CALL()
END

```

Basically we have a counter for every IP, for every different second. But this counters are always incremented setting an expire of 10 seconds so that they'll be removed by Redis automatically when the current second is a different one.

 Note the used of [`MULTI`](../multi) and [`EXEC`](../exec) in order to make sure that we'll both increment and set the expire at every API call.

 Pattern: Rate limiter 2
-----------------------

 An alternative implementation uses a single counter, but is a bit more complex to get it right without race conditions. We'll examine different variants.

 
```
FUNCTION LIMIT_API_CALL(ip):
current = GET(ip)
IF current != NULL AND current > 10 THEN
    ERROR "too many requests per second"
ELSE
    value = INCR(ip)
    IF value == 1 THEN
        EXPIRE(ip,1)
    END
    PERFORM_API_CALL()
END

```

The counter is created in a way that it only will survive one second, starting from the first request performed in the current second. If there are more than 10 requests in the same second the counter will reach a value greater than 10, otherwise it will expire and start again from 0.

 **In the above code there is a race condition**. If for some reason the client performs the `INCR` command but does not perform the [`EXPIRE`](../expire) the key will be leaked until we'll see the same IP address again.

 This can be fixed easily turning the `INCR` with optional [`EXPIRE`](../expire) into a Lua script that is send using the [`EVAL`](../eval) command (only available since Redis version 2.6).

 
```
local current
current = redis.call("incr",KEYS[1])
if current == 1 then
    redis.call("expire",KEYS[1],1)
end

```

There is a different way to fix this issue without using scripting, by using Redis lists instead of counters. The implementation is more complex and uses more advanced features but has the advantage of remembering the IP addresses of the clients currently performing an API call, that may be useful or not depending on the application.

 
```
FUNCTION LIMIT_API_CALL(ip)
current = LLEN(ip)
IF current > 10 THEN
    ERROR "too many requests per second"
ELSE
    IF EXISTS(ip) == FALSE
        MULTI
            RPUSH(ip,ip)
            EXPIRE(ip,1)
        EXEC
    ELSE
        RPUSHX(ip,ip)
    END
    PERFORM_API_CALL()
END

```

The [`RPUSHX`](../rpushx) command only pushes the element if the key already exists.

 Note that we have a race here, but it is not a problem: [`EXISTS`](../exists) may return false but the key may be created by another client before we create it inside the [`MULTI`](../multi) / [`EXEC`](../exec) block. However this race will just miss an API call under rare conditions, so the rate limiting will still work correctly.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/incr/>

HMSET
=====



```
HMSET (deprecated)
```
  As of Redis version 4.0.0, this command is regarded as deprecated.

 It can be replaced by [`HSET`](../hset) with multiple field-value pairs when migrating or writing new code.

  Syntax 
```
HMSET key field value [field value ...]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of fields being set. ACL categories:  `@write`, `@hash`, `@fast`,   Sets the specified fields to their respective values in the hash stored at `key`. This command overwrites any specified fields already existing in the hash. If `key` does not exist, a new key holding a hash is created.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```

HMSET myhash field1 "Hello" field2 "World"
HGET myhash field1
HGET myhash field2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hmset/>

HSTRLEN
=======



```
HSTRLEN
```
 Syntax 
```
HSTRLEN key field
```
  Available since: 3.2.0 Time complexity: O(1) ACL categories:  `@read`, `@hash`, `@fast`,   Returns the string length of the value associated with `field` in the hash stored at `key`. If the `key` or the `field` do not exist, 0 is returned.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the string length of the value associated with `field`, or zero when `field` is not present in the hash or `key` does not exist at all.

 Examples
--------

 
```

HMSET myhash f1 HelloWorld f2 99 f3 -256
HSTRLEN myhash f1
HSTRLEN myhash f2
HSTRLEN myhash f3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hstrlen/>

INCRBYFLOAT
===========



```
INCRBYFLOAT
```
 Syntax 
```
INCRBYFLOAT key increment
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Increment the string representing a floating point number stored at `key` by the specified `increment`. By using a negative `increment` value, the result is that the value stored at the key is decremented (by the obvious properties of addition). If the key does not exist, it is set to `0` before performing the operation. An error is returned if one of the following conditions occur:

 * The key contains a value of the wrong type (not a string).
* The current key content or the specified increment are not parsable as a double precision floating point number.

 If the command is successful the new incremented value is stored as the new value of the key (replacing the old one), and returned to the caller as a string.

 Both the value already contained in the string key and the increment argument can be optionally provided in exponential notation, however the value computed after the increment is stored consistently in the same format, that is, an integer number followed (if needed) by a dot, and a variable number of digits representing the decimal part of the number. Trailing zeroes are always removed.

 The precision of the output is fixed at 17 digits after the decimal point regardless of the actual internal precision of the computation.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of `key` after the increment.

 Examples
--------

 
```

SET mykey 10.50
INCRBYFLOAT mykey 0.1
INCRBYFLOAT mykey -5
SET mykey 5.0e3
INCRBYFLOAT mykey 2.0e2

```
 Implementation details
----------------------

 The command is always propagated in the replication link and the Append Only File as a [`SET`](../set) operation, so that differences in the underlying floating point math implementation will not be sources of inconsistency.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/incrbyfloat/>

HSET
====



```
HSET
```
 Syntax 
```
HSET key field value [field value ...]
```
  Available since: 2.0.0 Time complexity: O(1) for each field/value pair added, so O(N) to add N field/value pairs when the command is called with multiple field/value pairs. ACL categories:  `@write`, `@hash`, `@fast`,   Sets the specified fields to their respective values in the hash stored at `key`.

 This command overwrites the values of specified fields that exist in the hash. If `key` doesn't exist, a new key holding a hash is created.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of fields that were added.

 Examples
--------

 
```

HSET myhash field1 "Hello"
HGET myhash field1
HSET myhash field2 "Hi" field3 "World"
HGET myhash field2
HGET myhash field3
HGETALL myhash

```
 History
-------

 * Starting with Redis version 4.0.0: Accepts multiple `field` and `value` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hset/>

HRANDFIELD
==========



```
HRANDFIELD
```
 Syntax 
```
HRANDFIELD key [count [WITHVALUES]]
```
  Available since: 6.2.0 Time complexity: O(N) where N is the number of fields returned ACL categories:  `@read`, `@hash`, `@slow`,   When called with just the `key` argument, return a random field from the hash value stored at `key`.

 If the provided `count` argument is positive, return an array of **distinct fields**. The array's length is either `count` or the hash's number of fields ([`HLEN`](../hlen)), whichever is lower.

 If called with a negative `count`, the behavior changes and the command is allowed to return the **same field multiple times**. In this case, the number of returned fields is the absolute value of the specified `count`.

 The optional `WITHVALUES` modifier changes the reply so it includes the respective values of the randomly selected hash fields.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): without the additional `count` argument, the command returns a Bulk Reply with the randomly selected field, or `nil` when `key` does not exist.

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): when the additional `count` argument is passed, the command returns an array of fields, or an empty array when `key` does not exist. If the `WITHVALUES` modifier is used, the reply is a list fields and their values from the hash.

 Examples
--------

 
```

HMSET coin heads obverse tails reverse edge null
HRANDFIELD coin
HRANDFIELD coin
HRANDFIELD coin -5 WITHVALUES

```
 Specification of the behavior when count is passed
--------------------------------------------------

 When the `count` argument is a positive value this command behaves as follows:

 * No repeated fields are returned.
* If `count` is bigger than the number of fields in the hash, the command will only return the whole hash without additional fields.
* The order of fields in the reply is not truly random, so it is up to the client to shuffle them if needed.

 When the `count` is a negative value, the behavior changes as follows:

 * Repeating fields are possible.
* Exactly `count` fields, or an empty array if the hash is empty (non-existing key), are always returned.
* The order of fields in the reply is truly random.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hrandfield/>

HSETNX
======



```
HSETNX
```
 Syntax 
```
HSETNX key field value
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@write`, `@hash`, `@fast`,   Sets `field` in the hash stored at `key` to `value`, only if `field` does not yet exist. If `key` does not exist, a new key holding a hash is created. If `field` already exists, this operation has no effect.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if `field` is a new field in the hash and `value` was set.
* `0` if `field` already exists in the hash and no operation was performed.

 Examples
--------

 
```

HSETNX myhash field "Hello"
HSETNX myhash field "World"
HGET myhash field

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hsetnx/>

HVALS
=====



```
HVALS
```
 Syntax 
```
HVALS key
```
  Available since: 2.0.0 Time complexity: O(N) where N is the size of the hash. ACL categories:  `@read`, `@hash`, `@slow`,   Returns all values in the hash stored at `key`.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of values in the hash, or an empty list when `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "Hello"
HSET myhash field2 "World"
HVALS myhash

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hvals/>

HKEYS
=====



```
HKEYS
```
 Syntax 
```
HKEYS key
```
  Available since: 2.0.0 Time complexity: O(N) where N is the size of the hash. ACL categories:  `@read`, `@hash`, `@slow`,   Returns all field names in the hash stored at `key`.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of fields in the hash, or an empty list when `key` does not exist.

 Examples
--------

 
```

HSET myhash field1 "Hello"
HSET myhash field2 "World"
HKEYS myhash

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hkeys/>

INCRBY
======



```
INCRBY
```
 Syntax 
```
INCRBY key increment
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Increments the number stored at `key` by `increment`. If the key does not exist, it is set to `0` before performing the operation. An error is returned if the key contains a value of the wrong type or contains a string that can not be represented as integer. This operation is limited to 64 bit signed integers.

 See [`INCR`](../incr) for extra information on increment/decrement operations.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the value of `key` after the increment

 Examples
--------

 
```

SET mykey "10"
INCRBY mykey 5

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/incrby/>

HMGET
=====



```
HMGET
```
 Syntax 
```
HMGET key field [field ...]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of fields being requested. ACL categories:  `@read`, `@hash`, `@fast`,   Returns the values associated with the specified `fields` in the hash stored at `key`.

 For every `field` that does not exist in the hash, a `nil` value is returned. Because non-existing keys are treated as empty hashes, running `HMGET` against a non-existing `key` will return a list of `nil` values.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of values associated with the given fields, in the same order as they are requested.

 
```

HSET myhash field1 "Hello"
HSET myhash field2 "World"
HMGET myhash field1 field2 nofield

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/hmget/>

JSON.ARRAPPEND
==============



```
JSON.ARRAPPEND
```
 Syntax 
```
JSON.ARRAPPEND key [path] value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Append the `json` values into the array at `path` after the last element in it

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `value` is one or more values to append to one or more arrays.

  About using strings with JSON commands To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).

   Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return value
------------

 `JSON.ARRAPEND` returns an [array](https://redis.io/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the array's new size, or `nil`, if the matching JSON value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Add a new color to a list of product colors** Create a document for noise-cancelling headphones in black and silver colors.

 
```
127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK
```
 Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.

 
```
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3
```
 Return the new length of the `colors` array.

 
```
127.0.0.1:6379> JSON.GET item:1
"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
```
  See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrappend/>

JSON.CLEAR
==========



```
JSON.CLEAR
```
 Syntax 
```
JSON.CLEAR key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 2.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the values, O(N) when path is evaluated to multiple values, where N is the size of the key  Clear container values (arrays/objects) and set numeric values to `0`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Nonexisting paths are ignored.

  Return
------

 JSON.CLEAR returns an integer reply specified as the number of values cleared. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

  Note Already cleared values are ignored for empty containers and zero numbers.

  Examples
--------

  **Clear container values and set numeric values to `0`** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET doc $ '{"obj":{"a":1, "b":2}, "arr":[1,2,3], "str": "foo", "bool": true, "int": 42, "float": 3.14}'
OK
```
 Clear all container values. This returns the number of objects with cleared values.

 
```
127.0.0.1:6379> JSON.CLEAR doc $.\*
(integer) 4
```
 Get the updated document. Note that numeric values have been set to `0`.

 
```
127.0.0.1:6379> JSON.GET doc $
"[{\"obj\":{},\"arr\":[],\"str\":\"foo\",\"bool\":true,\"int\":0,\"float\":0}]"
```
  See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.clear/>

INFO
====



```
INFO
```
 Syntax 
```
INFO [section [section ...]]
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@dangerous`,   The `INFO` command returns information and statistics about the server in a format that is simple to parse by computers and easy to read by humans.

 The optional parameter can be used to select a specific section of information:

 * `server`: General information about the Redis server
* `clients`: Client connections section
* `memory`: Memory consumption related information
* `persistence`: RDB and AOF related information
* `stats`: General statistics
* `replication`: Master/replica replication information
* `cpu`: CPU consumption statistics
* `commandstats`: Redis command statistics
* `latencystats`: Redis command latency percentile distribution statistics
* `sentinel`: Redis Sentinel section (only applicable to Sentinel instances)
* `cluster`: Redis Cluster section
* `modules`: Modules section
* `keyspace`: Database related statistics
* `modules`: Module related sections
* `errorstats`: Redis error statistics

 It can also take the following values:

 * `all`: Return all sections (excluding module generated ones)
* `default`: Return only the default set of sections
* `everything`: Includes `all` and `modules`

 When no parameter is provided, the `default` option is assumed.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): as a collection of text lines.

 Lines can contain a section name (starting with a # character) or a property. All the properties are in the form of `field:value` terminated by `\r\n`.

 
```

INFO

```
 Notes
-----

 Please note depending on the version of Redis some of the fields have been added or removed. A robust client application should therefore parse the result of this command by skipping unknown properties, and gracefully handle missing fields.

 Here is the description of fields for Redis >= 2.4.

 Here is the meaning of all fields in the **server** section:

 * `redis_version`: Version of the Redis server
* `redis_git_sha1`: Git SHA1
* `redis_git_dirty`: Git dirty flag
* `redis_build_id`: The build id
* `redis_mode`: The server's mode ("standalone", "sentinel" or "cluster")
* `os`: Operating system hosting the Redis server
* `arch_bits`: Architecture (32 or 64 bits)
* `multiplexing_api`: Event loop mechanism used by Redis
* `atomicvar_api`: Atomicvar API used by Redis
* `gcc_version`: Version of the GCC compiler used to compile the Redis server
* `process_id`: PID of the server process
* `process_supervised`: Supervised system ("upstart", "systemd", "unknown" or "no")
* `run_id`: Random value identifying the Redis server (to be used by Sentinel and Cluster)
* `tcp_port`: TCP/IP listen port
* `server_time_usec`: Epoch-based system time with microsecond precision
* `uptime_in_seconds`: Number of seconds since Redis server start
* `uptime_in_days`: Same value expressed in days
* `hz`: The server's current frequency setting
* `configured_hz`: The server's configured frequency setting
* `lru_clock`: Clock incrementing every minute, for LRU management
* `executable`: The path to the server's executable
* `config_file`: The path to the config file
* `io_threads_active`: Flag indicating if I/O threads are active
* `shutdown_in_milliseconds`: The maximum time remaining for replicas to catch up the replication before completing the shutdown sequence. This field is only present during shutdown.

 Here is the meaning of all fields in the **clients** section:

 * `connected_clients`: Number of client connections (excluding connections from replicas)
* `cluster_connections`: An approximation of the number of sockets used by the cluster's bus
* `maxclients`: The value of the `maxclients` configuration directive. This is the upper limit for the sum of `connected_clients`, `connected_slaves` and `cluster_connections`.
* `client_recent_max_input_buffer`: Biggest input buffer among current client connections
* `client_recent_max_output_buffer`: Biggest output buffer among current client connections
* `blocked_clients`: Number of clients pending on a blocking call ([`BLPOP`](../blpop), [`BRPOP`](../brpop), [`BRPOPLPUSH`](../brpoplpush), [`BLMOVE`](../blmove), [`BZPOPMIN`](../bzpopmin), [`BZPOPMAX`](../bzpopmax))
* `tracking_clients`: Number of clients being tracked ([`CLIENT TRACKING`](../client-tracking))
* `clients_in_timeout_table`: Number of clients in the clients timeout table

 Here is the meaning of all fields in the **memory** section:

 * `used_memory`: Total number of bytes allocated by Redis using its allocator (either standard **libc**, **jemalloc**, or an alternative allocator such as [**tcmalloc**](http://code.google.com/p/google-perftools/))
* `used_memory_human`: Human readable representation of previous value
* `used_memory_rss`: Number of bytes that Redis allocated as seen by the operating system (a.k.a resident set size). This is the number reported by tools such as `top(1)` and `ps(1)`
* `used_memory_rss_human`: Human readable representation of previous value
* `used_memory_peak`: Peak memory consumed by Redis (in bytes)
* `used_memory_peak_human`: Human readable representation of previous value
* `used_memory_peak_perc`: The percentage of `used_memory_peak` out of `used_memory`
* `used_memory_overhead`: The sum in bytes of all overheads that the server allocated for managing its internal data structures
* `used_memory_startup`: Initial amount of memory consumed by Redis at startup in bytes
* `used_memory_dataset`: The size in bytes of the dataset (`used_memory_overhead` subtracted from `used_memory`)
* `used_memory_dataset_perc`: The percentage of `used_memory_dataset` out of the net memory usage (`used_memory` minus `used_memory_startup`)
* `total_system_memory`: The total amount of memory that the Redis host has
* `total_system_memory_human`: Human readable representation of previous value
* `used_memory_lua`: Number of bytes used by the Lua engine
* `used_memory_lua_human`: Human readable representation of previous value
* `used_memory_scripts`: Number of bytes used by cached Lua scripts
* `used_memory_scripts_human`: Human readable representation of previous value
* `maxmemory`: The value of the `maxmemory` configuration directive
* `maxmemory_human`: Human readable representation of previous value
* `maxmemory_policy`: The value of the `maxmemory-policy` configuration directive
* `mem_fragmentation_ratio`: Ratio between `used_memory_rss` and `used_memory`. Note that this doesn't only includes fragmentation, but also other process overheads (see the `allocator_*` metrics), and also overheads like code, shared libraries, stack, etc.
* `mem_fragmentation_bytes`: Delta between `used_memory_rss` and `used_memory`. Note that when the total fragmentation bytes is low (few megabytes), a high ratio (e.g. 1.5 and above) is not an indication of an issue.
* `allocator_frag_ratio:`: Ratio between `allocator_active` and `allocator_allocated`. This is the true (external) fragmentation metric (not `mem_fragmentation_ratio`).
* `allocator_frag_bytes` Delta between `allocator_active` and `allocator_allocated`. See note about `mem_fragmentation_bytes`.
* `allocator_rss_ratio`: Ratio between `allocator_resident` and `allocator_active`. This usually indicates pages that the allocator can and probably will soon release back to the OS.
* `allocator_rss_bytes`: Delta between `allocator_resident` and `allocator_active`
* `rss_overhead_ratio`: Ratio between `used_memory_rss` (the process RSS) and `allocator_resident`. This includes RSS overheads that are not allocator or heap related.
* `rss_overhead_bytes`: Delta between `used_memory_rss` (the process RSS) and `allocator_resident`
* `allocator_allocated`: Total bytes allocated form the allocator, including internal-fragmentation. Normally the same as `used_memory`.
* `allocator_active`: Total bytes in the allocator active pages, this includes external-fragmentation.
* `allocator_resident`: Total bytes resident (RSS) in the allocator, this includes pages that can be released to the OS (by [`MEMORY PURGE`](../memory-purge), or just waiting).
* `mem_not_counted_for_evict`: Used memory that's not counted for key eviction. This is basically transient replica and AOF buffers.
* `mem_clients_slaves`: Memory used by replica clients - Starting Redis 7.0, replica buffers share memory with the replication backlog, so this field can show 0 when replicas don't trigger an increase of memory usage.
* `mem_clients_normal`: Memory used by normal clients
* `mem_cluster_links`: Memory used by links to peers on the cluster bus when cluster mode is enabled.
* `mem_aof_buffer`: Transient memory used for AOF and AOF rewrite buffers
* `mem_replication_backlog`: Memory used by replication backlog
* `mem_total_replication_buffers`: Total memory consumed for replication buffers - Added in Redis 7.0.
* `mem_allocator`: Memory allocator, chosen at compile time.
* `active_defrag_running`: When `activedefrag` is enabled, this indicates whether defragmentation is currently active, and the CPU percentage it intends to utilize.
* `lazyfree_pending_objects`: The number of objects waiting to be freed (as a result of calling [`UNLINK`](../unlink), or [`FLUSHDB`](../flushdb) and [`FLUSHALL`](../flushall) with the **ASYNC** option)
* `lazyfreed_objects`: The number of objects that have been lazy freed.

 Ideally, the `used_memory_rss` value should be only slightly higher than `used_memory`. When rss >> used, a large difference may mean there is (external) memory fragmentation, which can be evaluated by checking `allocator_frag_ratio`, `allocator_frag_bytes`. When used >> rss, it means part of Redis memory has been swapped off by the operating system: expect some significant latencies.

 Because Redis does not have control over how its allocations are mapped to memory pages, high `used_memory_rss` is often the result of a spike in memory usage.

 When Redis frees memory, the memory is given back to the allocator, and the allocator may or may not give the memory back to the system. There may be a discrepancy between the `used_memory` value and memory consumption as reported by the operating system. It may be due to the fact memory has been used and released by Redis, but not given back to the system. The `used_memory_peak` value is generally useful to check this point.

 Additional introspective information about the server's memory can be obtained by referring to the [`MEMORY STATS`](../memory-stats) command and the [`MEMORY DOCTOR`](../memory-doctor).

 Here is the meaning of all fields in the **persistence** section:

 * `loading`: Flag indicating if the load of a dump file is on-going
* `async_loading`: Currently loading replication data-set asynchronously while serving old data. This means `repl-diskless-load` is enabled and set to `swapdb`. Added in Redis 7.0.
* `current_cow_peak`: The peak size in bytes of copy-on-write memory while a child fork is running
* `current_cow_size`: The size in bytes of copy-on-write memory while a child fork is running
* `current_cow_size_age`: The age, in seconds, of the `current_cow_size` value.
* `current_fork_perc`: The percentage of progress of the current fork process. For AOF and RDB forks it is the percentage of `current_save_keys_processed` out of `current_save_keys_total`.
* `current_save_keys_processed`: Number of keys processed by the current save operation
* `current_save_keys_total`: Number of keys at the beginning of the current save operation
* `rdb_changes_since_last_save`: Number of changes since the last dump
* `rdb_bgsave_in_progress`: Flag indicating a RDB save is on-going
* `rdb_last_save_time`: Epoch-based timestamp of last successful RDB save
* `rdb_last_bgsave_status`: Status of the last RDB save operation
* `rdb_last_bgsave_time_sec`: Duration of the last RDB save operation in seconds
* `rdb_current_bgsave_time_sec`: Duration of the on-going RDB save operation if any
* `rdb_last_cow_size`: The size in bytes of copy-on-write memory during the last RDB save operation
* `rdb_last_load_keys_expired`: Number of volatile keys deleted during the last RDB loading. Added in Redis 7.0.
* `rdb_last_load_keys_loaded`: Number of keys loaded during the last RDB loading. Added in Redis 7.0.
* `aof_enabled`: Flag indicating AOF logging is activated
* `aof_rewrite_in_progress`: Flag indicating a AOF rewrite operation is on-going
* `aof_rewrite_scheduled`: Flag indicating an AOF rewrite operation will be scheduled once the on-going RDB save is complete.
* `aof_last_rewrite_time_sec`: Duration of the last AOF rewrite operation in seconds
* `aof_current_rewrite_time_sec`: Duration of the on-going AOF rewrite operation if any
* `aof_last_bgrewrite_status`: Status of the last AOF rewrite operation
* `aof_last_write_status`: Status of the last write operation to the AOF
* `aof_last_cow_size`: The size in bytes of copy-on-write memory during the last AOF rewrite operation
* `module_fork_in_progress`: Flag indicating a module fork is on-going
* `module_fork_last_cow_size`: The size in bytes of copy-on-write memory during the last module fork operation
* `aof_rewrites`: Number of AOF rewrites performed since startup
* `rdb_saves`: Number of RDB snapshots performed since startup

 `rdb_changes_since_last_save` refers to the number of operations that produced some kind of changes in the dataset since the last time either [`SAVE`](../save) or [`BGSAVE`](../bgsave) was called.

 If AOF is activated, these additional fields will be added:

 * `aof_current_size`: AOF current file size
* `aof_base_size`: AOF file size on latest startup or rewrite
* `aof_pending_rewrite`: Flag indicating an AOF rewrite operation will be scheduled once the on-going RDB save is complete.
* `aof_buffer_length`: Size of the AOF buffer
* `aof_rewrite_buffer_length`: Size of the AOF rewrite buffer. Note this field was removed in Redis 7.0
* `aof_pending_bio_fsync`: Number of fsync pending jobs in background I/O queue
* `aof_delayed_fsync`: Delayed fsync counter

 If a load operation is on-going, these additional fields will be added:

 * `loading_start_time`: Epoch-based timestamp of the start of the load operation
* `loading_total_bytes`: Total file size
* `loading_rdb_used_mem`: The memory usage of the server that had generated the RDB file at the time of the file's creation
* `loading_loaded_bytes`: Number of bytes already loaded
* `loading_loaded_perc`: Same value expressed as a percentage
* `loading_eta_seconds`: ETA in seconds for the load to be complete

 Here is the meaning of all fields in the **stats** section:

 * `total_connections_received`: Total number of connections accepted by the server
* `total_commands_processed`: Total number of commands processed by the server
* `instantaneous_ops_per_sec`: Number of commands processed per second
* `total_net_input_bytes`: The total number of bytes read from the network
* `total_net_output_bytes`: The total number of bytes written to the network
* `total_net_repl_input_bytes`: The total number of bytes read from the network for replication purposes
* `total_net_repl_output_bytes`: The total number of bytes written to the network for replication purposes
* `instantaneous_input_kbps`: The network's read rate per second in KB/sec
* `instantaneous_output_kbps`: The network's write rate per second in KB/sec
* `instantaneous_input_repl_kbps`: The network's read rate per second in KB/sec for replication purposes
* `instantaneous_output_repl_kbps`: The network's write rate per second in KB/sec for replication purposes
* `rejected_connections`: Number of connections rejected because of `maxclients` limit
* `sync_full`: The number of full resyncs with replicas
* `sync_partial_ok`: The number of accepted partial resync requests
* `sync_partial_err`: The number of denied partial resync requests
* `expired_keys`: Total number of key expiration events
* `expired_stale_perc`: The percentage of keys probably expired
* `expired_time_cap_reached_count`: The count of times that active expiry cycles have stopped early
* `expire_cycle_cpu_milliseconds`: The cumulative amount of time spend on active expiry cycles
* `evicted_keys`: Number of evicted keys due to `maxmemory` limit
* `evicted_clients`: Number of evicted clients due to `maxmemory-clients` limit. Added in Redis 7.0.
* `total_eviction_exceeded_time`: Total time `used_memory` was greater than `maxmemory` since server startup, in milliseconds
* `current_eviction_exceeded_time`: The time passed since `used_memory` last rose above `maxmemory`, in milliseconds
* `keyspace_hits`: Number of successful lookup of keys in the main dictionary
* `keyspace_misses`: Number of failed lookup of keys in the main dictionary
* `pubsub_channels`: Global number of pub/sub channels with client subscriptions
* `pubsub_patterns`: Global number of pub/sub pattern with client subscriptions
* `pubsubshard_channels`: Global number of pub/sub shard channels with client subscriptions. Added in Redis 7.0.3
* `latest_fork_usec`: Duration of the latest fork operation in microseconds
* `total_forks`: Total number of fork operations since the server start
* `migrate_cached_sockets`: The number of sockets open for [`MIGRATE`](../migrate) purposes
* `slave_expires_tracked_keys`: The number of keys tracked for expiry purposes (applicable only to writable replicas)
* `active_defrag_hits`: Number of value reallocations performed by active the defragmentation process
* `active_defrag_misses`: Number of aborted value reallocations started by the active defragmentation process
* `active_defrag_key_hits`: Number of keys that were actively defragmented
* `active_defrag_key_misses`: Number of keys that were skipped by the active defragmentation process
* `total_active_defrag_time`: Total time memory fragmentation was over the limit, in milliseconds
* `current_active_defrag_time`: The time passed since memory fragmentation last was over the limit, in milliseconds
* `tracking_total_keys`: Number of keys being tracked by the server
* `tracking_total_items`: Number of items, that is the sum of clients number for each key, that are being tracked
* `tracking_total_prefixes`: Number of tracked prefixes in server's prefix table (only applicable for broadcast mode)
* `unexpected_error_replies`: Number of unexpected error replies, that are types of errors from an AOF load or replication
* `total_error_replies`: Total number of issued error replies, that is the sum of rejected commands (errors prior command execution) and failed commands (errors within the command execution)
* `dump_payload_sanitizations`: Total number of dump payload deep integrity validations (see `sanitize-dump-payload` config).
* `total_reads_processed`: Total number of read events processed
* `total_writes_processed`: Total number of write events processed
* `io_threaded_reads_processed`: Number of read events processed by the main and I/O threads
* `io_threaded_writes_processed`: Number of write events processed by the main and I/O threads
* `acl_access_denied_auth`: Number of authentication failures
* `acl_access_denied_cmd`: Number of commands rejected because of access denied to the command
* `acl_access_denied_key`: Number of commands rejected because of access denied to a key
* `acl_access_denied_channel`: Number of commands rejected because of access denied to a channel

 Here is the meaning of all fields in the **replication** section:

 * `role`: Value is "master" if the instance is replica of no one, or "slave" if the instance is a replica of some master instance. Note that a replica can be master of another replica (chained replication).
* `master_failover_state`: The state of an ongoing failover, if any.
* `master_replid`: The replication ID of the Redis server.
* `master_replid2`: The secondary replication ID, used for PSYNC after a failover.
* `master_repl_offset`: The server's current replication offset
* `second_repl_offset`: The offset up to which replication IDs are accepted
* `repl_backlog_active`: Flag indicating replication backlog is active
* `repl_backlog_size`: Total size in bytes of the replication backlog buffer
* `repl_backlog_first_byte_offset`: The master offset of the replication backlog buffer
* `repl_backlog_histlen`: Size in bytes of the data in the replication backlog buffer

 If the instance is a replica, these additional fields are provided:

 * `master_host`: Host or IP address of the master
* `master_port`: Master listening TCP port
* `master_link_status`: Status of the link (up/down)
* `master_last_io_seconds_ago`: Number of seconds since the last interaction with master
* `master_sync_in_progress`: Indicate the master is syncing to the replica
* `slave_read_repl_offset`: The read replication offset of the replica instance.
* `slave_repl_offset`: The replication offset of the replica instance
* `slave_priority`: The priority of the instance as a candidate for failover
* `slave_read_only`: Flag indicating if the replica is read-only
* `replica_announced`: Flag indicating if the replica is announced by Sentinel.

 If a SYNC operation is on-going, these additional fields are provided:

 * `master_sync_total_bytes`: Total number of bytes that need to be transferred. this may be 0 when the size is unknown (for example, when the `repl-diskless-sync` configuration directive is used)
* `master_sync_read_bytes`: Number of bytes already transferred
* `master_sync_left_bytes`: Number of bytes left before syncing is complete (may be negative when `master_sync_total_bytes` is 0)
* `master_sync_perc`: The percentage `master_sync_read_bytes` from `master_sync_total_bytes`, or an approximation that uses `loading_rdb_used_mem` when `master_sync_total_bytes` is 0
* `master_sync_last_io_seconds_ago`: Number of seconds since last transfer I/O during a SYNC operation

 If the link between master and replica is down, an additional field is provided:

 * `master_link_down_since_seconds`: Number of seconds since the link is down

 The following field is always provided:

 * `connected_slaves`: Number of connected replicas

 If the server is configured with the `min-slaves-to-write` (or starting with Redis 5 with the `min-replicas-to-write`) directive, an additional field is provided:

 * `min_slaves_good_slaves`: Number of replicas currently considered good

 For each replica, the following line is added:

 * `slaveXXX`: id, IP address, port, state, offset, lag

 Here is the meaning of all fields in the **cpu** section:

 * `used_cpu_sys`: System CPU consumed by the Redis server, which is the sum of system CPU consumed by all threads of the server process (main thread and background threads)
* `used_cpu_user`: User CPU consumed by the Redis server, which is the sum of user CPU consumed by all threads of the server process (main thread and background threads)
* `used_cpu_sys_children`: System CPU consumed by the background processes
* `used_cpu_user_children`: User CPU consumed by the background processes
* `used_cpu_sys_main_thread`: System CPU consumed by the Redis server main thread
* `used_cpu_user_main_thread`: User CPU consumed by the Redis server main thread

 The **commandstats** section provides statistics based on the command type, including the number of calls that reached command execution (not rejected), the total CPU time consumed by these commands, the average CPU consumed per command execution, the number of rejected calls (errors prior command execution), and the number of failed calls (errors within the command execution).

 For each command type, the following line is added:

 * `cmdstat_XXX`: `calls=XXX,usec=XXX,usec_per_call=XXX,rejected_calls=XXX,failed_calls=XXX`

 The **latencystats** section provides latency percentile distribution statistics based on the command type.

 By default, the exported latency percentiles are the p50, p99, and p999. If you need to change the exported percentiles, use `CONFIG SET latency-tracking-info-percentiles "50.0 99.0 99.9"`.

 This section requires the extended latency monitoring feature to be enabled (by default it's enabled). If you need to enable it, use `CONFIG SET latency-tracking yes`.

 For each command type, the following line is added:

 * `latency_percentiles_usec_XXX: p<percentile 1>=<percentile 1 value>,p<percentile 2>=<percentile 2 value>,...`

 The **errorstats** section enables keeping track of the different errors that occurred within Redis, based upon the reply error prefix ( The first word after the "-", up to the first space. Example: `ERR` ).

 For each error type, the following line is added:

 * `errorstat_XXX`: `count=XXX`

 The **sentinel** section is only available in Redis Sentinel instances. It consists of the following fields:

 * `sentinel_masters`: Number of Redis masters monitored by this Sentinel instance
* `sentinel_tilt`: A value of 1 means this sentinel is in TILT mode
* `sentinel_tilt_since_seconds`: Duration in seconds of current TILT, or -1 if not TILTed. Added in Redis 7.0.0
* `sentinel_running_scripts`: The number of scripts this Sentinel is currently executing
* `sentinel_scripts_queue_length`: The length of the queue of user scripts that are pending execution
* `sentinel_simulate_failure_flags`: Flags for the `SENTINEL SIMULATE-FAILURE` command

 The **cluster** section currently only contains a unique field:

 * `cluster_enabled`: Indicate Redis cluster is enabled

 The **modules** section contains additional information about loaded modules if the modules provide it. The field part of properties lines in this section is always prefixed with the module's name.

 The **keyspace** section provides statistics on the main dictionary of each database. The statistics are the number of keys, and the number of keys with an expiration.

 For each database, the following line is added:

 * `dbXXX`: `keys=XXX,expires=XXX`

 **A note about the word slave used in this man page**: Starting with Redis 5, if not for backward compatibility, the Redis project no longer uses the word slave. Unfortunately in this command the word slave is part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated.

 **Modules generated sections**: Starting with Redis 6, modules can inject their info into the `INFO` command, these are excluded by default even when the `all` argument is provided (it will include a list of loaded modules but not their generated info fields). To get these you must use either the `modules` argument or `everything`.,

 History
-------

 * Starting with Redis version 7.0.0: Added support for taking multiple section arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/info/>

JSON.ARRPOP
===========



```
JSON.ARRPOP
```
 Syntax 
```
JSON.ARRPOP key [path [index]]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the array and the specified index is not the last element, O(1) when path is evaluated to a single value and the specified index is the last element, or O(N) when path is evaluated to multiple values, where N is the size of the key  Remove and return an element from the index in the array

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `index` is position in the array to start popping from. Default is `-1`, meaning the last element. Out-of-range indexes round to their respective array ends. Popping an empty array returns null.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return
------

 `JSON.ARRPOP` returns an [array](https://redis.io/docs/reference/protocol-spec/#resp-arrays) of bulk string replies for each path, each reply is the popped JSON value, or `nil`, if the matching JSON value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Pop a value from an index and insert a new value** Create two headphone products with maximum sound levels.

 
```
127.0.0.1:6379> JSON.SET key $ '[{"name":"Healthy headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"],"max\_level":[60,70,80]},{"name":"Noisy headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"],"max\_level":[80,90,100,120]}]'
OK
```
 Get all maximum values for the second product.

 
```
127.0.0.1:6379> JSON.GET key $.[1].max\_level
"[[80,90,100,120]]"
```
 Update the `max_level` field of the product: remove an unavailable value and add a newly available value.

 
```
127.0.0.1:6379> JSON.ARRPOP key $.[1].max\_level 0
1) "80"
```
 Get the updated array.

 
```
127.0.0.1:6379> JSON.GET key $.[1].max\_level
"[[90,100,120]]"
```
 Now insert a new lowest value.

 
```
127.0.0.1:6379> JSON.ARRINSERT key $.[1].max\_level 0 85
1) (integer) 4
```
 Get the updated array.

 
```
127.0.0.1:6379> JSON.GET key $.[1].max\_level
"[[85,90,100,120]]"
```
  See also
--------

 [`JSON.ARRAPPEND`](../json.arrappend) | [`JSON.ARRINDEX`](../json.arrindex)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrpop/>

JSON.NUMMULTBY
==============



```
JSON.NUMMULTBY (deprecated)
```
  As of Redis version 2.0, this command is regarded as deprecated.

  Syntax 
```
JSON.NUMMULTBY key path value
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Multiply the number value stored at `path` by `number`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `value` is number value to multiply.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return
------

 JSON.NUMMULTBY returns a bulk string reply specified as a stringified new values for each path, or `nil` element if the matching JSON value is not a number. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK
127.0.0.1:6379> JSON.NUMMULTBY doc $.a 2
"[null]"
127.0.0.1:6379> JSON.NUMMULTBY doc $..a 2
"[null,4,10,null]"
```
 See also
--------

 [`JSON.NUMINCRBY`](../json.numincrby) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.nummultby/>

JSON.ARRINSERT
==============



```
JSON.ARRINSERT
```
 Syntax 
```
JSON.ARRINSERT key path index value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the array, O(N) when path is evaluated to multiple values, where N is the size of the key  Insert the `json` values into the array at `path` before the `index` (shifts to the right)

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `value` is one or more values to insert in one or more arrays.

  About using strings with JSON commands To specify a string as an array value to insert, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).

   `index` is position in the array where you want to insert a value. The index must be in the array's range. Inserting at `index` 0 prepends to the array. Negative index values start from the end of the array.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return value
------------

 `JSON.ARRINSERT` returns an [array](https://redis.io/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the array's new size, or `nil`, if the matching JSON value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Add new colors to a specific place in a list of product colors** Create a document for noise-cancelling headphones in black and silver colors.

 
```
127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK
```
 Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.

 
```
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3
```
 Return the new length of the `colors` array.

 
```
JSON.GET item:1
"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
```
 Get the list of colors for the product.

 
```
127.0.0.1:6379> JSON.GET item:1 '$.colors[\*]'
"[\"black\",\"silver\",\"blue\"]"
```
 Insert two more colors after the second color. You now have five colors.

 
```
127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
1) (integer) 5
```
 Get the updated list of colors.

 
```
127.0.0.1:6379> JSON.GET item:1 $.colors
"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
```
  See also
--------

 [`JSON.ARRAPPEND`](../json.arrappend) | [`JSON.ARRINDEX`](../json.arrindex)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrinsert/>

JSON.ARRLEN
===========



```
JSON.ARRLEN
```
 Syntax 
```
JSON.ARRLEN key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) where path is evaluated to a single value, O(N) where path is evaluated to multiple values, where N is the size of the key  Report the length of the JSON array at `path` in `key`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`, if not provided. Returns null if the `key` or `path` do not exist.

  Return
------

 `JSON.ARRLEN` returns an [array](https://redis.io/docs/reference/protocol-spec/#resp-arrays) of integer replies, an integer for each matching value, each is the array's length, or `nil`, if the matching value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Get lengths of JSON arrays in a document** Create a document for wireless earbuds.

 
```
127.0.0.1:6379> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max\_level":[80, 100, 120]}'
OK
```
 Find lengths of arrays in all objects of the document.

 
```
127.0.0.1:6379> JSON.ARRLEN item:2 '$.[\*]'
1) (nil)
2) (nil)
3) (nil)
4) (nil)
5) (nil)
6) (integer) 2
7) (integer) 3
```
 Return the length of the `max_level` array.

 
```
127.0.0.1:6379> JSON.ARRLEN item:2 '$..max\_level'
1) (integer) 3
```
 Get all the maximum level values.

 
```
127.0.0.1:6379> JSON.GET item:2 '$..max\_level'
"[[80,100,120]]"
```
  See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrlen/>

JSON.ARRINDEX
=============



```
JSON.ARRINDEX
```
 Syntax 
```
JSON.ARRINDEX key path value [start [stop]]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the array, O(N) when path is evaluated to multiple values, where N is the size of the key  Search for the first occurrence of a JSON value in an array

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  `path` is JSONPath to specify.

  `value` is value to find its index in one or more arrays.

  About using strings with JSON commands To specify a string as an array value to index, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).

   Optional arguments
------------------

 `start` is inclusive start value to specify in a slice of the array to search. Default is `0`.

  `stop` is exclusive stop value to specify in a slice of the array to search, including the last element. Default is `0`. Negative values are interpreted as starting from the end.

   About out-of-range indexes Out-of-range indexes round to the array's start and end. An inverse index range (such as the range from 1 to 0) returns unfound or `-1`.

  Return value
------------

 `JSON.ARRINDEX` returns an [array](https://redis.io/docs/reference/protocol-spec/#resp-arrays) of integer replies for each path, the first position in the array of each JSON value that matches the path, `-1` if unfound in the array, or `nil`, if the matching JSON value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Find the specific place of a color in a list of product colors** Create a document for noise-cancelling headphones in black and silver colors.

 
```
127.0.0.1:6379> JSON.SET item:1 $ '{"name":"Noise-cancelling Bluetooth headphones","description":"Wireless Bluetooth headphones with noise-cancelling technology","connection":{"wireless":true,"type":"Bluetooth"},"price":99.98,"stock":25,"colors":["black","silver"]}'
OK
```
 Add color `blue` to the end of the `colors` array. `JSON.ARRAPEND` returns the array's new size.

 
```
127.0.0.1:6379> JSON.ARRAPPEND item:1 $.colors '"blue"'
1) (integer) 3
```
 Return the new length of the `colors` array.

 
```
JSON.GET item:1
"{\"name\":\"Noise-cancelling Bluetooth headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\",\"blue\"]}"
```
 Get the list of colors for the product.

 
```
127.0.0.1:6379> JSON.GET item:1 '$.colors[\*]'
"[\"black\",\"silver\",\"blue\"]"
```
 Insert two more colors after the second color. You now have five colors.

 
```
127.0.0.1:6379> JSON.ARRINSERT item:1 $.colors 2 '"yellow"' '"gold"'
1) (integer) 5
```
 Get the updated list of colors.

 
```
127.0.0.1:6379> JSON.GET item:1 $.colors
"[[\"black\",\"silver\",\"yellow\",\"gold\",\"blue\"]]"
```
 Find the place where color `silver` is located.

 
```
127.0.0.1:6379> JSON.ARRINDEX item:1 $..colors '"silver"'
1) (integer) 1
```
  See also
--------

 [`JSON.ARRAPPEND`](../json.arrappend) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrindex/>

JSON.ARRTRIM
============



```
JSON.ARRTRIM
```
 Syntax 
```
JSON.ARRTRIM key path start stop
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the array, O(N) when path is evaluated to multiple values, where N is the size of the key  Trim an array so that it contains only the specified inclusive range of elements

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  `start` is index of the first element to keep (previous elements are trimmed). Default is 0.

  `stop` is the index of the last element to keep (following elements are trimmed), including the last element. Default is 0. Negative values are interpreted as starting from the end.

   About out-of-range indexes JSON.ARRTRIM is extremely forgiving, and using it with out-of-range indexes does not produce an error. Note a few differences between how RedisJSON v2.0 and legacy versions handle out-of-range indexes.

 Behavior as of RedisJSON v2.0:

 * If `start` is larger than the array's size or `start` > `stop`, returns 0 and an empty array.
* If `start` is < 0, then start from the end of the array.
* If `stop` is larger than the end of the array, it is treated like the last element.

  Return
------

 JSON.ARRTRIM returns an array of integer replies for each path, the array's new size, or `nil`, if the matching JSON value is not an array. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Trim an array to a specific set of values** Create two headphone products with maximum sound levels.

 
```
127.0.0.1:6379> JSON.GET key $
"[[{\"name\":\"Healthy headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"max\_level\":[60,70,80]},{\"name\":\"Noisy headphones\",\"description\":\"Wireless Bluetooth headphones with noise-cancelling technology\",\"connection\":{\"wireless\":true,\"type\":\"Bluetooth\"},\"price\":99.98,\"stock\":25,\"colors\":[\"black\",\"silver\"],\"max\_level\":[85,90,100,120]}]]"
OK
```
 Add new sound level values to the second product.

 
```
127.0.0.1:6379> JSON.ARRAPPEND key $.[1].max\_level 140 160 180 200 220 240 260 280
1) (integer) 12
```
 Get the updated array.

 
```
127.0.0.1:6379> JSON.GET key $.[1].max\_level
"[[85,90,100,120,140,160,180,200,220,240,260,280]]"
```
 Keep only the values between the fifth and the ninth element, inclusive of that last element.

 
```
127.0.0.1:6379> JSON.ARRTRIM key $.[1].max\_level 4 8
1) (integer) 5
```
 Get the updated array.

 
```
127.0.0.1:6379> JSON.GET key $.[1].max\_level
"[[140,160,180,200,220]]"
```
  See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.arrtrim/>

JSON.DEBUG
==========



```
JSON.DEBUG MEMORY
```
 Syntax 
```
JSON.DEBUG MEMORY key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value, where N is the size of the value, O(N) when path is evaluated to multiple values, where N is the size of the key  Report a value's memory usage in bytes

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return
------

 JSON.DEBUG MEMORY returns an integer reply specified as the value size in bytes. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Report a value's memory usage in bytes** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max\_level":[80, 100, 120]}'
OK
```
 Get the values' memory usage in bytes.

 
```
127.0.0.1:6379> JSON.DEBUG MEMORY item:2
(integer) 253
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.ARRLEN`](../json.arrlen)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.debug-memory/>

JSON.DEL
========



```
JSON.DEL
```
 Syntax 
```
JSON.DEL key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the deleted value, O(N) when path is evaluated to multiple values, where N is the size of the key  Delete a value

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Nonexisting paths are ignored.

  Note Deleting an object's root is equivalent to deleting the key from Redis.

   Return
------

 JSON.DEL returns an integer reply specified as the number of paths deleted (0 or more). For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Delete a value** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a": 1, "nested": {"a": 2, "b": 3}}'
OK
```
 Delete specified values.

 
```
127.0.0.1:6379> JSON.DEL doc $..a
(integer) 2
```
 Get the updated document.

 
```
127.0.0.1:6379> JSON.GET doc $
"[{\"nested\":{\"b\":3}}]"
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.ARRLEN`](../json.arrlen)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.del/>

JSON.GET
========



```
JSON.GET
```
 Syntax 
```
JSON.GET key [INDENT indent] [NEWLINE newline] [SPACE space] [path
  [path ...]]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the value, O(N) when path is evaluated to multiple values, where N is the size of the key  Return the value at `path` in JSON serialized form

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. JSON.GET accepts multiple `path` arguments.

  Note When using a single JSONPath, the root of the matching values is a JSON string with a top-level **array** of serialized JSON value. In contrast, a legacy path returns a single value.

 When using multiple JSONPath arguments, the root of the matching values is a JSON string with a top-level **object**, with each object value being a top-level array of serialized JSON value. In contrast, if all paths are legacy paths, each object value is a single serialized JSON value. If there are multiple paths that include both legacy path and JSONPath, the returned value conforms to the JSONPath version (an array of values).

   `INDENT` sets the indentation string for nested levels.

  `NEWLINE` sets the string that's printed at the end of each line.

  `SPACE` sets the string that's put between a key and a value.

   Note Produce pretty-formatted JSON with `redis-cli` by following this example:

 
```
~/$ redis-cli --raw
127.0.0.1:6379> JSON.GET myjsonkey INDENT "\t" NEWLINE "\n" SPACE " " path.to.value[1]
```
  Return
------

 JSON.GET returns a bulk string representing a JSON array of string replies. Each string is the JSON serialization of each JSON value that matches a path. Using multiple paths, JSON.GET returns a bulk string representing a JSON object with string values. Each string value is an array of the JSON serialization of each JSON value that matches a path. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Return the value at `path` in JSON serialized form** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":2, "b": 3, "nested": {"a": 4, "b": null}}'
OK
```
 With a single JSONPath (JSON array bulk string):

 
```
127.0.0.1:6379> JSON.GET doc $..b
"[3,null]"
```
 Using multiple paths with at least one JSONPath returns a JSON string with a top-level object with an array of JSON values per path:

 
```
127.0.0.1:6379> JSON.GET doc ..a $..b
"{\"$..b\":[3,null],\"..a\":[2,4]}"
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.MGET`](../json.mget)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.get/>

JSON.DEBUG
==========



```
JSON.DEBUG
```
 Syntax 
```
JSON.DEBUG
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: N/A  This is a container command for debugging related tasks.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.debug/>

JSON.STRAPPEND
==============



```
JSON.STRAPPEND
```
 Syntax 
```
JSON.STRAPPEND key [path] value
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Append the `json-string` values to the string at `path`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `value` is value to append to one or more strings.

  About using strings with JSON commands To specify a string as an array value to append, wrap the quoted string with an additional set of single quotes. Example: `'"silver"'`. For more detailed use, see [Examples](#examples).

   Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return value
------------

 JSON.STRAPPEND returns an array of integer replies for each path, the string's new length, or `nil`, if the matching JSON value is not a string. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
127.0.0.1:6379> JSON.STRAPPEND doc $..a '"baz"'
1) (integer) 6
2) (integer) 8
3) (nil)
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":\"foobaz\",\"nested\":{\"a\":\"hellobaz\"},\"nested2\":{\"a\":31}}]"
```
 See also
--------

 `JSON.ARRAPEND` | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.strappend/>

JSON.FORGET
===========



```
JSON.FORGET
```
 Syntax 
```
JSON.FORGET key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value where N is the size of the deleted value, O(N) when path is evaluated to multiple values, where N is the size of the key  See [`JSON.DEL`](../json.del).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.forget/>

JSON.NUMINCRBY
==============



```
JSON.NUMINCRBY
```
 Syntax 
```
JSON.NUMINCRBY key path value
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Increment the number value stored at `path` by `number`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `path` is JSONPath to specify.

  `value` is number value to increment.

  Return
------

 JSON.NUMINCRBY returns a bulk string reply specified as a stringified new value for each path, or `nil`, if the matching JSON value is not a number. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Increment number values** Create a document.

 
```
127.0.0.1:6379> JSON.SET doc . '{"a":"b","b":[{"a":2}, {"a":5}, {"a":"c"}]}'
OK
```
 Increment a value of `a` object by 2. The command fails to find a number and returns `null`.

 
```
127.0.0.1:6379> JSON.NUMINCRBY doc $.a 2
"[null]"
```
 Recursively find and increment a value of all `a` objects. The command increments numbers it finds and returns `null` for nonnumber values.

 
```
127.0.0.1:6379> JSON.NUMINCRBY doc $..a 2
"[null,4,7,null]"
```
  See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.numincrby/>

JSON.OBJKEYS
============



```
JSON.OBJKEYS
```
 Syntax 
```
JSON.OBJKEYS key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value, where N is the number of keys in the object, O(N) when path is evaluated to multiple values, where N is the size of the key  Return the keys in the object that's referenced by `path`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse. Returns `null` for nonexistent keys.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Returns `null` for nonexistant path.

  Return
------

 JSON.OBJKEYS returns an array of array replies for each path, an array of the key names in the object as a bulk string reply, or `nil` if the matching JSON value is not an object. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": {"b":2, "c": 1}}}'
OK
127.0.0.1:6379> JSON.OBJKEYS doc $..a
1) (nil)
2) 1) "b"
 2) "c"
```
 See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.objkeys/>

JSON.MGET
=========



```
JSON.MGET
```
 Syntax 
```
JSON.MGET key [key ...] path
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(M\*N) when path is evaluated to a single value where M is the number of keys and N is the size of the value, O(N1+N2+...+Nm) when path is evaluated to multiple values where m is the number of keys and Ni is the size of the i-th key  Return the values at `path` from multiple `key` arguments

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse. Returns `null` for nonexistent keys.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Returns `null` for nonexistent paths.

  Return
------

 JSON.MGET returns an array of bulk string replies specified as the JSON serialization of the value at each key's path. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Return the values at `path` from multiple `key` arguments** Create two JSON documents.

 
```
redis> JSON.SET doc1 $ '{"a":1, "b": 2, "nested": {"a": 3}, "c": null}'
OK
redis> JSON.SET doc2 $ '{"a":4, "b": 5, "nested": {"a": 6}, "c": null}'
OK
```
 Get values from all arguments in the documents.

 
```
redis> JSON.MGET doc1 doc2 $..a
1) "[1,3]"
2) "[4,6]"
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.GET`](../json.get)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.mget/>

JSON.TOGGLE
===========



```
JSON.TOGGLE
```
 Syntax 
```
JSON.TOGGLE key path
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 2.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Toggle a Boolean value stored at `path`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`.

  Return
------

 JSON.TOGGLE returns an array of integer replies for each path, the new value (`0` if `false` or `1` if `true`), or `nil` for JSON values matching the path that are not Boolean. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Toogle a Boolean value stored at `path`** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET doc $ '{"bool": true}'
OK
```
 Toggle the Boolean value.

 
```
127.0.0.1:6379> JSON.TOGGLE doc $.bool
1) (integer) 0
```
 Get the updated document.

 
```
127.0.0.1:6379> JSON.GET doc $
"[{\"bool\":false}]"
```
 Toggle the Boolean value.

 
```
127.0.0.1:6379> JSON.TOGGLE doc $.bool
1) (integer) 1
```
 Get the updated document.

 
```
127.0.0.1:6379> JSON.GET doc $
"[{\"bool\":true}]"
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.GET`](../json.get)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.toggle/>

KEYS
====



```
KEYS
```
 Syntax 
```
KEYS pattern
```
  Available since: 1.0.0 Time complexity: O(N) with N being the number of keys in the database, under the assumption that the key names in the database and the given pattern have limited length. ACL categories:  `@keyspace`, `@read`, `@slow`, `@dangerous`,   Returns all keys matching `pattern`.

 While the time complexity for this operation is O(N), the constant times are fairly low. For example, Redis running on an entry level laptop can scan a 1 million key database in 40 milliseconds.

 **Warning**: consider `KEYS` as a command that should only be used in production environments with extreme care. It may ruin performance when it is executed against large databases. This command is intended for debugging and special operations, such as changing your keyspace layout. Don't use `KEYS` in your regular application code. If you're looking for a way to find keys in a subset of your keyspace, consider using [`SCAN`](../scan) or [sets](https://redis.io/topics/data-types#sets).

 Supported glob-style patterns:

 * `h?llo` matches `hello`, `hallo` and `hxllo`
* `h*llo` matches `hllo` and `heeeello`
* `h[ae]llo` matches `hello` and `hallo,` but not `hillo`
* `h[^e]llo` matches `hallo`, `hbllo`, ... but not `hello`
* `h[a-b]llo` matches `hallo` and `hbllo`

 Use `\` to escape special characters if you want to match them verbatim.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of keys matching `pattern`.

 Examples
--------

 
```

MSET firstname Jack lastname Stuntman age 35
KEYS *name*
KEYS a??
KEYS *

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/keys/>

JSON.RESP
=========



```
JSON.RESP
```
 Syntax 
```
JSON.RESP key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(N) when path is evaluated to a single value, where N is the size of the value, O(N) when path is evaluated to multiple values, where N is the size of the key  Return the JSON in `key` in [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec) form

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. This command uses the following mapping from JSON to RESP:

 * JSON `null` maps to the bulk string reply.
* JSON `false` and `true` values map to the simple string reply.
* JSON number maps to the integer reply or bulk string reply, depending on type.
* JSON string maps to the bulk string reply.
* JSON array is represented as an array reply in which the first element is the simple string reply `[`, followed by the array's elements.
* JSON object is represented as an array reply in which the first element is the simple string reply `{`. Each successive entry represents a key-value pair as a two-entry array reply of the bulk string reply.

 For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

  Return
------

 JSON.RESP returns an array reply specified as the JSON's RESP form detailed in [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Return an array of RESP details about a document** Create a JSON document.

 
```
127.0.0.1:6379> JSON.SET item:2 $ '{"name":"Wireless earbuds","description":"Wireless Bluetooth in-ear headphones","connection":{"wireless":true,"type":"Bluetooth"},"price":64.99,"stock":17,"colors":["black","white"], "max\_level":[80, 100, 120]}'
OK
```
 Get all RESP details about the document.

 
```
127.0.0.1:6379> JSON.RESP item:2
 1) {
 2) "name"
 3) "Wireless earbuds"
 4) "description"
 5) "Wireless Bluetooth in-ear headphones"
 6) "connection"
 7) 1) {
 2) "wireless"
 3) true
 4) "type"
 5) "Bluetooth"
 8) "price"
 9) "64.989999999999995"
10) "stock"
11) (integer) 17
12) "colors"
13) 1) [
 2) "black"
 3) "white"
14) "max\_level"
15) 1) [
 2) (integer) 80
 3) (integer) 100
 4) (integer) 120
```
  See also
--------

 [`JSON.SET`](../json.set) | [`JSON.ARRLEN`](../json.arrlen)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.resp/>

LATENCY
=======



```
LATENCY DOCTOR
```
 Syntax 
```
LATENCY DOCTOR
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `LATENCY DOCTOR` command reports about different latency-related issues and advises about possible remedies.

 This command is the most powerful analysis tool in the latency monitoring framework, and is able to provide additional statistical data like the average period between latency spikes, the median deviation, and a human-readable analysis of the event. For certain events, like `fork`, additional information is provided, like the rate at which the system forks processes.

 This is the output you should post in the Redis mailing list if you are looking for help about Latency related issues.

 Examples
--------

 
```
127.0.0.1:6379> latency doctor

Dave, I have observed latency spikes in this Redis instance.
You don't mind talking about it, do you Dave?

1. command: 5 latency spikes (average 300ms, mean deviation 120ms,
    period 73.40 sec). Worst all time event 500ms.

I have a few advices for you:

- Your current Slow Log configuration only logs events that are
    slower than your configured latency monitor threshold. Please
    use 'CONFIG SET slowlog-log-slower-than 1000'.
- Check your Slow Log to understand what are the commands you are
    running which are too slow to execute. Please check
    http://redis.io/commands/slowlog for more information.
- Deleting, expiring or evicting (because of maxmemory policy)
    large objects is a blocking operation. If you have very large
    objects that are often deleted, expired, or evicted, try to
    fragment those objects into multiple smaller objects.

```

**Note:** the doctor has erratic psychological behaviors, so we recommend interacting with it carefully.

 For more information refer to the [Latency Monitoring Framework page](https://redis.io/topics/latency-monitor).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-doctor/>

JSON.TYPE
=========



```
JSON.TYPE
```
 Syntax 
```
JSON.TYPE key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Report the type of JSON value at `path`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Returns null if the `key` or `path` do not exist.

  Return
------

 JSON.TYPE returns an array of string replies for each path, specified as the value's type. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":2, "nested": {"a": true}, "foo": "bar"}'
OK
127.0.0.1:6379> JSON.TYPE doc $..foo
1) "string"
127.0.0.1:6379> JSON.TYPE doc $..a
1) "integer"
2) "boolean"
127.0.0.1:6379> JSON.TYPE doc $..dummy
```
 See also
--------

 [`JSON.SET`](../json.set) | [`JSON.ARRLEN`](../json.arrlen)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.type/>

JSON.STRLEN
===========



```
JSON.STRLEN
```
 Syntax 
```
JSON.STRLEN key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Report the length of the JSON String at `path` in `key`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`, if not provided. Returns null if the `key` or `path` do not exist.

  Return
------

 JSON.STRLEN returns by recursive descent an array of integer replies for each path, the array's length, or `nil`, if the matching JSON value is not a string. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":"foo", "nested": {"a": "hello"}, "nested2": {"a": 31}}'
OK
127.0.0.1:6379> JSON.STRLEN doc $..a
1) (integer) 3
2) (integer) 5
3) (nil)
```
 See also
--------

 [`JSON.ARRLEN`](../json.arrlen) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.strlen/>

LATENCY
=======



```
LATENCY GRAPH
```
 Syntax 
```
LATENCY GRAPH event
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Produces an ASCII-art style graph for the specified event.

 `LATENCY GRAPH` lets you intuitively understand the latency trend of an `event` via state-of-the-art visualization. It can be used for quickly grasping the situation before resorting to means such parsing the raw data from [`LATENCY HISTORY`](../latency-history) or external tooling.

 Valid values for `event` are:

 * `active-defrag-cycle`
* `aof-fsync-always`
* `aof-stat`
* `aof-rewrite-diff-write`
* `aof-rename`
* `aof-write`
* `aof-write-active-child`
* `aof-write-alone`
* `aof-write-pending-fsync`
* `command`
* `expire-cycle`
* `eviction-cycle`
* `eviction-del`
* `fast-command`
* `fork`
* `rdb-unlink-temp-file`

 Examples
--------

 
```
127.0.0.1:6379> latency reset command
(integer) 0
127.0.0.1:6379> debug sleep .1
OK
127.0.0.1:6379> debug sleep .2
OK
127.0.0.1:6379> debug sleep .3
OK
127.0.0.1:6379> debug sleep .5
OK
127.0.0.1:6379> debug sleep .4
OK
127.0.0.1:6379> latency graph command
command - high 500 ms, low 101 ms (all time high 500 ms)
--------------------------------------------------------------------------------
   #_
  _||
 _|||
_||||

11186
542ss
sss

```

The vertical labels under each graph column represent the amount of seconds, minutes, hours or days ago the event happened. For example "15s" means that the first graphed event happened 15 seconds ago.

 The graph is normalized in the min-max scale so that the zero (the underscore in the lower row) is the minimum, and a # in the higher row is the maximum.

 For more information refer to the [Latency Monitoring Framework page](https://redis.io/topics/latency-monitor).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-graph/>

LATENCY
=======



```
LATENCY HISTOGRAM
```
 Syntax 
```
LATENCY HISTOGRAM [command [command ...]]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of commands with latency information being retrieved. ACL categories:  `@admin`, `@slow`, `@dangerous`,   `LATENCY HISTOGRAM` returns a cumulative distribution of commands' latencies in histogram format.

 By default, all available latency histograms are returned. You can filter the reply by providing specific command names.

 Each histogram consists of the following fields:

 * Command name
* The total calls for that command
* A map of time buckets:
	+ Each bucket represents a latency range
	+ Each bucket covers twice the previous bucket's range
	+ Empty buckets are excluded from the reply
	+ The tracked latencies are between 1 microsecond and roughly 1 second
	+ Everything above 1 second is considered +Inf
	+ At max, there will be log2(1,000,000,000)=30 buckets

 This command requires the extended latency monitoring feature to be enabled, which is the default. If you need to enable it, call `CONFIG SET latency-tracking yes`.

 To delete the latency histograms' data use the [`CONFIG RESETSTAT`](../config-resetstat) command.

 Examples
--------

 
```
127.0.0.1:6379> LATENCY HISTOGRAM set
1# "set" =>
   1# "calls" => (integer) 100000
   2# "histogram_usec" =>
      1# (integer) 1 => (integer) 99583
      2# (integer) 2 => (integer) 99852
      3# (integer) 4 => (integer) 99914
      4# (integer) 8 => (integer) 99940
      5# (integer) 16 => (integer) 99968
      6# (integer) 33 => (integer) 100000

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 The command returns a map where each key is a command name. The value is a map with a key for the total calls, and a map of the histogram time buckets.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-histogram/>

LINSERT
=======



```
LINSERT
```
 Syntax 
```
LINSERT key <BEFORE | AFTER> pivot element
```
  Available since: 2.2.0 Time complexity: O(N) where N is the number of elements to traverse before seeing the value pivot. This means that inserting somewhere on the left end on the list (head) can be considered O(1) and inserting somewhere on the right end (tail) is O(N). ACL categories:  `@write`, `@list`, `@slow`,   Inserts `element` in the list stored at `key` either before or after the reference value `pivot`.

 When `key` does not exist, it is considered an empty list and no operation is performed.

 An error is returned when `key` exists but does not hold a list value.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the list length after a successful insert operation, `0` if the `key` doesn't exist, and `-1` when the `pivot` wasn't found.

 Examples
--------

 
```

RPUSH mylist "Hello"
RPUSH mylist "World"
LINSERT mylist BEFORE "World" "There"
LRANGE mylist 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/linsert/>

LASTSAVE
========



```
LASTSAVE
```
 Syntax 
```
LASTSAVE
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@fast`, `@dangerous`,   Return the UNIX TIME of the last DB save executed with success. A client may check if a [`BGSAVE`](../bgsave) command succeeded reading the `LASTSAVE` value, then issuing a [`BGSAVE`](../bgsave) command and checking at regular intervals every N seconds if `LASTSAVE` changed. Redis considers the database saved successfully at startup.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): an UNIX time stamp.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lastsave/>

LMOVE
=====



```
LMOVE
```
 Syntax 
```
LMOVE source destination <LEFT | RIGHT> <LEFT | RIGHT>
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@write`, `@list`, `@slow`,   Atomically returns and removes the first/last element (head/tail depending on the `wherefrom` argument) of the list stored at `source`, and pushes the element at the first/last element (head/tail depending on the `whereto` argument) of the list stored at `destination`.

 For example: consider `source` holding the list `a,b,c`, and `destination` holding the list `x,y,z`. Executing `LMOVE source destination RIGHT LEFT` results in `source` holding `a,b` and `destination` holding `c,x,y,z`.

 If `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 first/last element from the list and pushing it as first/last element of the list, so it can be considered as a list rotation command (or a no-op if `wherefrom` is the same as `whereto`).

 This command comes in place of the now deprecated [`RPOPLPUSH`](../rpoplpush). Doing `LMOVE RIGHT LEFT` is equivalent.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the element being popped and pushed.

 Examples
--------

 
```

RPUSH mylist "one"
RPUSH mylist "two"
RPUSH mylist "three"
LMOVE mylist myotherlist RIGHT LEFT
LMOVE mylist myotherlist LEFT RIGHT
LRANGE mylist 0 -1
LRANGE myotherlist 0 -1

```
 Pattern: Reliable queue
-----------------------

 Redis is often used as a messaging server to implement processing of background jobs or other kinds of messaging tasks. A simple form of queue is often obtained pushing values into a list in the producer side, and waiting for this values in the consumer side using [`RPOP`](../rpop) (using polling), or [`BRPOP`](../brpop) if the client is better served by a blocking operation.

 However in this context the obtained queue is not *reliable* as messages can be lost, for example in the case there is a network problem or if the consumer crashes just after the message is received but it is still to process.

 `LMOVE` (or [`BLMOVE`](../blmove) for the blocking variant) offers a way to avoid this problem: the consumer fetches the message and at the same time pushes it into a *processing* list. It will use the [`LREM`](../lrem) command in order to remove the message from the *processing* list once the message has been processed.

 An additional client may monitor the *processing* list for items that remain there for too much time, and will push those timed out items into the queue again if needed.

 Pattern: Circular list
----------------------

 Using `LMOVE` with the same source and destination key, a client can visit all the elements of an N-elements list, one after the other, in O(N) without transferring the full list from the server to the client using a single [`LRANGE`](../lrange) operation.

 The above pattern works even in the following conditions:

 * There are multiple clients rotating the list: they'll fetch different elements, until all the elements of the list are visited, and the process restarts.
* Even if other clients are actively pushing new items at the end of the list.

 The above makes it very simple to implement a system where a set of items must be processed by N workers continuously as fast as possible. An example is a monitoring system that must check that a set of web sites are reachable, with the smallest delay possible, using a number of parallel workers.

 Note that this implementation of workers is trivially scalable and reliable, because even if a message is lost the item is still in the queue and will be processed at the next iteration.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lmove/>

LLEN
====



```
LLEN
```
 Syntax 
```
LLEN key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@read`, `@list`, `@fast`,   Returns the length of the list stored at `key`. If `key` does not exist, it is interpreted as an empty list and `0` is returned. An error is returned when the value stored at `key` is not a list.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the list at `key`.

 Examples
--------

 
```

LPUSH mylist "World"
LPUSH mylist "Hello"
LLEN mylist

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/llen/>

LINDEX
======



```
LINDEX
```
 Syntax 
```
LINDEX key index
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of elements to traverse to get to the element at index. This makes asking for the first or the last element of the list O(1). ACL categories:  `@read`, `@list`, `@slow`,   Returns the element at index `index` in the list stored at `key`. The index is zero-based, so `0` means the first element, `1` the second element and so on. Negative indices can be used to designate elements starting at the tail of the list. Here, `-1` means the last element, `-2` means the penultimate and so forth.

 When the value at `key` is not a list, an error is returned.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the requested element, or `nil` when `index` is out of range.

 Examples
--------

 
```

LPUSH mylist "World"
LPUSH mylist "Hello"
LINDEX mylist 0
LINDEX mylist -1
LINDEX mylist 3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lindex/>

LATENCY
=======



```
LATENCY LATEST
```
 Syntax 
```
LATENCY LATEST
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `LATENCY LATEST` command reports the latest latency events logged.

 Each reported event has the following fields:

 * Event name.
* Unix timestamp of the latest latency spike for the event.
* Latest event latency in millisecond.
* All-time maximum latency for this event.

 "All-time" means the maximum latency since the Redis instance was started, or the time that events were reset [`LATENCY RESET`](../latency-reset).

 Examples
--------

 
```
127.0.0.1:6379> debug sleep 1
OK
(1.00s)
127.0.0.1:6379> debug sleep .25
OK
127.0.0.1:6379> latency latest
1) 1) "command"
   2) (integer) 1405067976
   3) (integer) 251
   4) (integer) 1001

```

For more information refer to the [Latency Monitoring Framework page](https://redis.io/topics/latency-monitor).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 The command returns an array where each element is a four elements array representing the event's name, timestamp, latest and all-time latency measurements.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-latest/>

JSON.SET
========



```
JSON.SET
```
 Syntax 
```
JSON.SET key path value [NX | XX]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(M+N) when path is evaluated to a single value where M is the size of the original value (if it exists) and N is the size of the new value, O(M+N) when path is evaluated to multiple values where M is the size of the key and N is the size of the new value  Set the JSON value at `path` in `key`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to modify.

  `value` is value to set at the specified path

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. For new Redis keys the `path` must be the root. For existing keys, when the entire `path` exists, the value that it contains is replaced with the `json` value. For existing keys, when the `path` exists, except for the last element, a new child is added with the `json` value.

 Adds a key (with its respective value) to a JSON Object (in a RedisJSON data type key) only if it is the last child in the `path`, or it is the parent of a new child being added in the `path`. Optional arguments `NX` and `XX` modify this behavior for both new RedisJSON data type keys as well as the JSON Object keys in them.

  `NX` sets the key only if it does not already exist.

  `XX` sets the key only if it already exists.

  Return value
------------

 JSET.SET returns a simple string reply: `OK` if executed correctly or `nil` if the specified `NX` or `XX` conditions were not met. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

  **Replace an existing value** 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":2}'
OK
127.0.0.1:6379> JSON.SET doc $.a '3'
OK
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":3}]"
```
   **Add a new value** 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":2}'
OK
127.0.0.1:6379> JSON.SET doc $.b '8'
OK
127.0.0.1:6379> JSON.GET doc $
"[{\"a\":2,\"b\":8}]"
```
   **Update multi-paths** 
```
127.0.0.1:6379> JSON.SET doc $ '{"f1": {"a":1}, "f2":{"a":2}}'
OK
127.0.0.1:6379> JSON.SET doc $..a 3
OK
127.0.0.1:6379> JSON.GET doc
"{\"f1\":{\"a\":3},\"f2\":{\"a\":3}}"
```
  See also
--------

 [`JSON.GET`](../json.get) | [`JSON.MGET`](../json.mget)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.set/>

LATENCY
=======



```
LATENCY RESET
```
 Syntax 
```
LATENCY RESET [event [event ...]]
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `LATENCY RESET` command resets the latency spikes time series of all, or only some, events.

 When the command is called without arguments, it resets all the events, discarding the currently logged latency spike events, and resetting the maximum event time register.

 It is possible to reset only specific events by providing the `event` names as arguments.

 Valid values for `event` are:

 * `active-defrag-cycle`
* `aof-fsync-always`
* `aof-stat`
* `aof-rewrite-diff-write`
* `aof-rename`
* `aof-write`
* `aof-write-active-child`
* `aof-write-alone`
* `aof-write-pending-fsync`
* `command`
* `expire-cycle`
* `eviction-cycle`
* `eviction-del`
* `fast-command`
* `fork`
* `rdb-unlink-temp-file`

 For more information refer to the [Latency Monitoring Framework page](https://redis.io/topics/latency-monitor).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of event time series that were reset.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-reset/>

LREM
====



```
LREM
```
 Syntax 
```
LREM key count element
```
  Available since: 1.0.0 Time complexity: O(N+M) where N is the length of the list and M is the number of elements removed. ACL categories:  `@write`, `@list`, `@slow`,   Removes the first `count` occurrences of elements equal to `element` from the list stored at `key`. The `count` argument influences the operation in the following ways:

 * `count > 0`: Remove elements equal to `element` moving from head to tail.
* `count < 0`: Remove elements equal to `element` moving from tail to head.
* `count = 0`: Remove all elements equal to `element`.

 For example, `LREM list -2 "hello"` will remove the last two occurrences of `"hello"` in the list stored at `list`.

 Note that non-existing keys are treated like empty lists, so when `key` does not exist, the command will always return `0`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of removed elements.

 Examples
--------

 
```

RPUSH mylist "hello"
RPUSH mylist "hello"
RPUSH mylist "foo"
RPUSH mylist "hello"
LREM mylist -2 "hello"
LRANGE mylist 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lrem/>

LCS
===



```
LCS
```
 Syntax 
```
LCS key1 key2 [LEN] [IDX] [MINMATCHLEN min-match-len] [WITHMATCHLEN]
```
  Available since: 7.0.0 Time complexity: O(N\*M) where N and M are the lengths of s1 and s2, respectively ACL categories:  `@read`, `@string`, `@slow`,   The LCS command implements the longest common subsequence algorithm. Note that this is different than the longest common string algorithm, since matching characters in the string does not need to be contiguous.

 For instance the LCS between "foo" and "fao" is "fo", since scanning the two strings from left to right, the longest common set of characters is composed of the first "f" and then the "o".

 LCS is very useful in order to evaluate how similar two strings are. Strings can represent many things. For instance if two strings are DNA sequences, the LCS will provide a measure of similarity between the two DNA sequences. If the strings represent some text edited by some user, the LCS could represent how different the new text is compared to the old one, and so forth.

 Note that this algorithm runs in `O(N*M)` time, where N is the length of the first string and M is the length of the second string. So either spin a different Redis instance in order to run this algorithm, or make sure to run it against very small strings.

 
```
> MSET key1 ohmytext key2 mynewtext
OK
> LCS key1 key2
"mytext"

```

Sometimes we need just the length of the match:

 
```
> LCS key1 key2 LEN
(integer) 6

```

However what is often very useful, is to know the match position in each strings:

 
```
> LCS key1 key2 IDX
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
   2) 1) 1) (integer) 2
         2) (integer) 3
      2) 1) (integer) 0
         2) (integer) 1
3) "len"
4) (integer) 6

```

Matches are produced from the last one to the first one, since this is how the algorithm works, and it more efficient to emit things in the same order. The above array means that the first match (second element of the array) is between positions 2-3 of the first string and 0-1 of the second. Then there is another match between 4-7 and 5-8.

 To restrict the list of matches to the ones of a given minimal length:

 
```
> LCS key1 key2 IDX MINMATCHLEN 4
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
3) "len"
4) (integer) 6

```

Finally to also have the match len:

 
```
> LCS key1 key2 IDX MINMATCHLEN 4 WITHMATCHLEN
1) "matches"
2) 1) 1) 1) (integer) 4
         2) (integer) 7
      2) 1) (integer) 5
         2) (integer) 8
      3) (integer) 4
3) "len"
4) (integer) 6

```

Return
------

 * Without modifiers the string representing the longest common substring is returned.
* When `LEN` is given the command returns the length of the longest common substring.
* When `IDX` is given the command returns an array with the LCS length and all the ranges in both the strings, start and end offset for each string, where there are matches. When `WITHMATCHLEN` is given each array representing a match will also have the length of the match (see examples).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lcs/>

LPUSH
=====



```
LPUSH
```
 Syntax 
```
LPUSH key element [element ...]
```
  Available since: 1.0.0 Time complexity: O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments. ACL categories:  `@write`, `@list`, `@fast`,   Insert all the specified values at the head of the list stored at `key`. If `key` does not exist, it is created as empty list before performing the push operations. When `key` holds a value that is not a list, an error is returned.

 It is possible to push multiple elements using a single command call just specifying multiple arguments at the end of the command. Elements are inserted one after the other to the head of the list, from the leftmost element to the rightmost element. So for instance the command `LPUSH mylist a b c` will result into a list containing `c` as first element, `b` as second element and `a` as third element.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the list after the push operations.

 Examples
--------

 
```

LPUSH mylist "world"
LPUSH mylist "hello"
LRANGE mylist 0 -1

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple `element` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lpush/>

LATENCY
=======



```
LATENCY HISTORY
```
 Syntax 
```
LATENCY HISTORY event
```
  Available since: 2.8.13 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `LATENCY HISTORY` command returns the raw data of the `event`'s latency spikes time series.

 This is useful to an application that wants to fetch raw data in order to perform monitoring, display graphs, and so forth.

 The command will return up to 160 timestamp-latency pairs for the `event`.

 Valid values for `event` are:

 * `active-defrag-cycle`
* `aof-fsync-always`
* `aof-stat`
* `aof-rewrite-diff-write`
* `aof-rename`
* `aof-write`
* `aof-write-active-child`
* `aof-write-alone`
* `aof-write-pending-fsync`
* `command`
* `expire-cycle`
* `eviction-cycle`
* `eviction-del`
* `fast-command`
* `fork`
* `rdb-unlink-temp-file`

 Examples
--------

 
```
127.0.0.1:6379> latency history command
1) 1) (integer) 1405067822
   2) (integer) 251
2) 1) (integer) 1405067941
   2) (integer) 1001

```

For more information refer to the [Latency Monitoring Framework page](https://redis.io/topics/latency-monitor).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 The command returns an array where each element is a two elements array representing the timestamp and the latency of the event.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/latency-history/>

LSET
====



```
LSET
```
 Syntax 
```
LSET key index element
```
  Available since: 1.0.0 Time complexity: O(N) where N is the length of the list. Setting either the first or the last element of the list is O(1). ACL categories:  `@write`, `@list`, `@slow`,   Sets the list element at `index` to `element`. For more information on the `index` argument, see [`LINDEX`](../lindex).

 An error is returned for out of range indexes.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```

RPUSH mylist "one"
RPUSH mylist "two"
RPUSH mylist "three"
LSET mylist 0 "four"
LSET mylist -2 "five"
LRANGE mylist 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lset/>

JSON.OBJLEN
===========



```
JSON.OBJLEN
```
 Syntax 
```
JSON.OBJLEN key [path]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [JSON 1.0.0](https://redis.io/docs/stack/json)  Time complexity: O(1) when path is evaluated to a single value, O(N) when path is evaluated to multiple values, where N is the size of the key  Report the number of keys in the JSON object at `path` in `key`

 [Examples](#examples)

 Required arguments
------------------

 `key` is key to parse. Returns `null` for nonexistent keys.

  Optional arguments
------------------

 `path` is JSONPath to specify. Default is root `$`. Returns `null` for nonexistant path.

  Return
------

 JSON.OBJLEN returns an array of integer replies for each path specified as the number of keys in the object or `nil`, if the matching JSON value is not an object. For more information about replies, see [Redis serialization protocol specification](https://redis.io/docs/reference/protocol-spec).

 Examples
--------

 
```
127.0.0.1:6379> JSON.SET doc $ '{"a":[3], "nested": {"a": {"b":2, "c": 1}}}'
OK
127.0.0.1:6379> JSON.OBJLEN doc $..a
1) (nil)
2) (integer) 2
```
 See also
--------

 [`JSON.ARRINDEX`](../json.arrindex) | [`JSON.ARRINSERT`](../json.arrinsert)

 Related topics
--------------

 * [RedisJSON](https://redis.io/docs/stack/json)
* [Index and search JSON documents](https://redis.io/docs/stack/search/indexing_json)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/json.objlen/>

LMPOP
=====



```
LMPOP
```
 Syntax 
```
LMPOP numkeys key [key ...] <LEFT | RIGHT> [COUNT count]
```
  Available since: 7.0.0 Time complexity: O(N+M) where N is the number of provided keys and M is the number of elements returned. ACL categories:  `@write`, `@list`, `@slow`,   Pops one or more elements from the first non-empty list key from the list of provided key names.

 `LMPOP` and [`BLMPOP`](../blmpop) are similar to the following, more limited, commands:

 * [`LPOP`](../lpop) or [`RPOP`](../rpop) which take only one key, and can return multiple elements.
* [`BLPOP`](../blpop) or [`BRPOP`](../brpop) which take multiple keys, but return only one element from just one key.

 See [`BLMPOP`](../blmpop) for the blocking variant of this command.

 Elements are popped from either the left or right of the first non-empty list based on the passed argument. The number of returned elements is limited to the lower between the non-empty list's length, and the count argument (which defaults to 1).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` when no element could be popped.
* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of elements.

 Examples
--------

 
```

LMPOP 2 non1 non2 LEFT COUNT 10
LPUSH mylist "one" "two" "three" "four" "five"
LMPOP 1 mylist LEFT
LRANGE mylist 0 -1
LMPOP 1 mylist RIGHT COUNT 10
LPUSH mylist "one" "two" "three" "four" "five"
LPUSH mylist2 "a" "b" "c" "d" "e"
LMPOP 2 mylist mylist2 right count 3
LRANGE mylist 0 -1
LMPOP 2 mylist mylist2 right count 5
LMPOP 2 mylist mylist2 right count 10
EXISTS mylist mylist2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lmpop/>

LRANGE
======



```
LRANGE
```
 Syntax 
```
LRANGE key start stop
```
  Available since: 1.0.0 Time complexity: O(S+N) where S is the distance of start offset from HEAD for small lists, from nearest end (HEAD or TAIL) for large lists; and N is the number of elements in the specified range. ACL categories:  `@read`, `@list`, `@slow`,   Returns the specified elements of the list stored at `key`. The offsets `start` and `stop` are zero-based indexes, with `0` being the first element of the list (the head of the list), `1` being the next element and so on.

 These offsets can also be negative numbers indicating offsets starting at the end of the list. For example, `-1` is the last element of the list, `-2` the penultimate, and so on.

 Consistency with range functions in various programming languages
-----------------------------------------------------------------

 Note that if you have a list of numbers from 0 to 100, `LRANGE list 0 10` will return 11 elements, that is, the rightmost item is included. This **may or may not** be consistent with behavior of range-related functions in your programming language of choice (think Ruby's `Range.new`, `Array#slice` or Python's `range()` function).

 Out-of-range indexes
--------------------

 Out of range indexes will not produce an error. If `start` is larger than the end of the list, an empty list is returned. If `stop` is larger than the actual end of the list, Redis will treat it like the last element of the list.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified range.

 Examples
--------

 
```

RPUSH mylist "one"
RPUSH mylist "two"
RPUSH mylist "three"
LRANGE mylist 0 0
LRANGE mylist -3 2
LRANGE mylist -100 100
LRANGE mylist 5 10

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lrange/>

LPOP
====



```
LPOP
```
 Syntax 
```
LPOP key [count]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of elements returned ACL categories:  `@write`, `@list`, `@fast`,   Removes and returns the first elements of the list stored at `key`.

 By default, the command pops a single element from the beginning of the list. When provided with the optional `count` argument, the reply will consist of up to `count` elements, depending on the list's length.

 Return
------

 When called without the `count` argument:

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of the first element, or `nil` when `key` does not exist.

 When called with the `count` argument:

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of popped elements, or `nil` when `key` does not exist.

 Examples
--------

 
```

RPUSH mylist "one" "two" "three" "four" "five"
LPOP mylist
LPOP mylist 2
LRANGE mylist 0 -1

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `count` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lpop/>

LOLWUT
======



```
LOLWUT
```
 Syntax 
```
LOLWUT [VERSION version]
```
  Available since: 5.0.0 Time complexity: ACL categories:  `@read`, `@fast`,   The LOLWUT command displays the Redis version: however as a side effect of doing so, it also creates a piece of generative computer art that is different with each version of Redis. The command was introduced in Redis 5 and announced with this [blog post](http://antirez.com/news/123).

 By default the `LOLWUT` command will display the piece corresponding to the current Redis version, however it is possible to display a specific version using the following form:

 
```
LOLWUT VERSION 5 ... other optional arguments ...

```
 Of course the "5" above is an example. Each LOLWUT version takes a different set of arguments in order to change the output. The user is encouraged to play with it to discover how the output changes adding more numerical arguments.

 LOLWUT wants to be a reminder that there is more in programming than just putting some code together in order to create something useful. Every LOLWUT version should have the following properties:

 1. It should display some computer art. There are no limits as long as the output works well in a normal terminal display. However the output should not be limited to graphics (like LOLWUT 5 and 6 actually do), but can be generative poetry and other non graphical things.
2. LOLWUT output should be completely useless. Displaying some useful Redis internal metrics does not count as a valid LOLWUT.
3. LOLWUT output should be fast to generate so that the command can be called in production instances without issues. It should remain fast even when the user experiments with odd parameters.
4. LOLWUT implementations should be safe and carefully checked for security, and resist to untrusted inputs if they take arguments.
5. LOLWUT must always display the Redis version at the end.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) (or verbatim reply when using the RESP3 protocol): the string containing the generative computer art, and a text with the Redis version.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lolwut/>

LPOS
====



```
LPOS
```
 Syntax 
```
LPOS key element [RANK rank] [COUNT num-matches] [MAXLEN len]
```
  Available since: 6.0.6 Time complexity: O(N) where N is the number of elements in the list, for the average case. When searching for elements near the head or the tail of the list, or when the MAXLEN option is provided, the command may run in constant time. ACL categories:  `@read`, `@list`, `@slow`,   The command returns the index of matching elements inside a Redis list. By default, when no options are given, it will scan the list from head to tail, looking for the first match of "element". If the element is found, its index (the zero-based position in the list) is returned. Otherwise, if no match is found, `nil` is returned.

 
```
> RPUSH mylist a b c 1 2 3 c c
> LPOS mylist c
2

```

The optional arguments and options can modify the command's behavior. The `RANK` option specifies the "rank" of the first element to return, in case there are multiple matches. A rank of 1 means to return the first match, 2 to return the second match, and so forth.

 For instance, in the above example the element "c" is present multiple times, if I want the index of the second match, I'll write:

 
```
> LPOS mylist c RANK 2
6

```

That is, the second occurrence of "c" is at position 6. A negative "rank" as the `RANK` argument tells `LPOS` to invert the search direction, starting from the tail to the head.

 So, we want to say, give me the first element starting from the tail of the list:

 
```
> LPOS mylist c RANK -1
7

```

Note that the indexes are still reported in the "natural" way, that is, considering the first element starting from the head of the list at index 0, the next element at index 1, and so forth. This basically means that the returned indexes are stable whatever the rank is positive or negative.

 Sometimes we want to return not just the Nth matching element, but the position of all the first N matching elements. This can be achieved using the `COUNT` option.

 
```
> LPOS mylist c COUNT 2
[2,6]

```

We can combine `COUNT` and `RANK`, so that `COUNT` will try to return up to the specified number of matches, but starting from the Nth match, as specified by the `RANK` option.

 
```
> LPOS mylist c RANK -1 COUNT 2
[7,6]

```

When `COUNT` is used, it is possible to specify 0 as the number of matches, as a way to tell the command we want all the matches found returned as an array of indexes. This is better than giving a very large `COUNT` option because it is more general.

 
```
> LPOS mylist c COUNT 0
[2,6,7]

```

When `COUNT` is used and no match is found, an empty array is returned. However when `COUNT` is not used and there are no matches, the command returns `nil`.

 Finally, the `MAXLEN` option tells the command to compare the provided element only with a given maximum number of list items. So for instance specifying `MAXLEN 1000` will make sure that the command performs only 1000 comparisons, effectively running the algorithm on a subset of the list (the first part or the last part depending on the fact we use a positive or negative rank). This is useful to limit the maximum complexity of the command. It is also useful when we expect the match to be found very early, but want to be sure that in case this is not true, the command does not take too much time to run.

 When `MAXLEN` is used, it is possible to specify 0 as the maximum number of comparisons, as a way to tell the command we want unlimited comparisons. This is better than giving a very large `MAXLEN` option because it is more general.

 Return
------

 The command returns the integer representing the matching element, or `nil` if there is no match. However, if the `COUNT` option is given the command returns an array (empty if there are no matches).

 Examples
--------

 
```

RPUSH mylist a b c d 1 2 3 4 3 3 3
LPOS mylist 3
LPOS mylist 3 COUNT 0 RANK 2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lpos/>

MONITOR
=======



```
MONITOR
```
 Syntax 
```
MONITOR
```
  Available since: 1.0.0 Time complexity: ACL categories:  `@admin`, `@slow`, `@dangerous`,   `MONITOR` is a debugging command that streams back every command processed by the Redis server. It can help in understanding what is happening to the database. This command can both be used via `redis-cli` and via `telnet`.

 The ability to see all the requests processed by the server is useful in order to spot bugs in an application both when using Redis as a database and as a distributed caching system.

 
```
$ redis-cli monitor
1339518083.107412 [0 127.0.0.1:60866] "keys" "*"
1339518087.877697 [0 127.0.0.1:60866] "dbsize"
1339518090.420270 [0 127.0.0.1:60866] "set" "x" "6"
1339518096.506257 [0 127.0.0.1:60866] "get" "x"
1339518099.363765 [0 127.0.0.1:60866] "eval" "return redis.call('set','x','7')" "0"
1339518100.363799 [0 lua] "set" "x" "7"
1339518100.544926 [0 127.0.0.1:60866] "del" "x"

```

Use `SIGINT` (Ctrl-C) to stop a `MONITOR` stream running via `redis-cli`.

 
```
$ telnet localhost 6379
Trying 127.0.0.1...
Connected to localhost.
Escape character is '^]'.
MONITOR
+OK
+1339518083.107412 [0 127.0.0.1:60866] "keys" "*"
+1339518087.877697 [0 127.0.0.1:60866] "dbsize"
+1339518090.420270 [0 127.0.0.1:60866] "set" "x" "6"
+1339518096.506257 [0 127.0.0.1:60866] "get" "x"
+1339518099.363765 [0 127.0.0.1:60866] "del" "x"
+1339518100.544926 [0 127.0.0.1:60866] "get" "x"
QUIT
+OK
Connection closed by foreign host.

```

Manually issue the [`QUIT`](../quit) or [`RESET`](../reset) commands to stop a `MONITOR` stream running via `telnet`.

 Commands not logged by MONITOR
------------------------------

 Because of security concerns, no administrative commands are logged by `MONITOR`'s output and sensitive data is redacted in the command [`AUTH`](../auth).

 Furthermore, the command [`QUIT`](../quit) is also not logged.

 Cost of running MONITOR
-----------------------

 Because `MONITOR` streams back **all** commands, its use comes at a cost. The following (totally unscientific) benchmark numbers illustrate what the cost of running `MONITOR` can be.

 Benchmark result **without** `MONITOR` running:

 
```
$ src/redis-benchmark -c 10 -n 100000 -q
PING_INLINE: 101936.80 requests per second
PING_BULK: 102880.66 requests per second
SET: 95419.85 requests per second
GET: 104275.29 requests per second
INCR: 93283.58 requests per second

```

Benchmark result **with** `MONITOR` running (`redis-cli monitor > /dev/null`):

 
```
$ src/redis-benchmark -c 10 -n 100000 -q
PING_INLINE: 58479.53 requests per second
PING_BULK: 59136.61 requests per second
SET: 41823.50 requests per second
GET: 45330.91 requests per second
INCR: 41771.09 requests per second

```

In this particular case, running a single `MONITOR` client can reduce the throughput by more than 50%. Running more `MONITOR` clients will reduce throughput even more.

 Return
------

 **Non standard return value**, just dumps the received commands in an infinite flow.

 Behavior change history
-----------------------

 * `>= 6.0.0`: [`AUTH`](../auth) excluded from the command's output.
* `>= 6.2.0`: "[`RESET`](../reset) can be called to exit monitor mode.
* `>= 6.2.4`: "[`AUTH`](../auth), [`HELLO`](../hello), [`EVAL`](../eval), [`EVAL_RO`](../eval_ro), [`EVALSHA`](../evalsha) and [`EVALSHA_RO`](../evalsha_ro) included in the command's output.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/monitor/>

LTRIM
=====



```
LTRIM
```
 Syntax 
```
LTRIM key start stop
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of elements to be removed by the operation. ACL categories:  `@write`, `@list`, `@slow`,   Trim an existing list so that it will contain only the specified range of elements specified. Both `start` and `stop` are zero-based indexes, where `0` is the first element of the list (the head), `1` the next element and so on.

 For example: `LTRIM foobar 0 2` will modify the list stored at `foobar` so that only the first three elements of the list will remain.

 `start` and `end` can also be negative numbers indicating offsets from the end of the list, where `-1` is the last element of the list, `-2` the penultimate element and so on.

 Out of range indexes will not produce an error: if `start` is larger than the end of the list, or `start > end`, the result will be an empty list (which causes `key` to be removed). If `end` is larger than the end of the list, Redis will treat it like the last element of the list.

 A common use of `LTRIM` is together with [`LPUSH`](../lpush) / [`RPUSH`](../rpush). For example:

 
```
LPUSH mylist someelement
LTRIM mylist 0 99

```

This pair of commands will push a new element on the list, while making sure that the list will not grow larger than 100 elements. This is very useful when using Redis to store logs for example. It is important to note that when used in this way `LTRIM` is an O(1) operation because in the average case just one element is removed from the tail of the list.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```

RPUSH mylist "one"
RPUSH mylist "two"
RPUSH mylist "three"
LTRIM mylist 1 -1
LRANGE mylist 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ltrim/>

LPUSHX
======



```
LPUSHX
```
 Syntax 
```
LPUSHX key element [element ...]
```
  Available since: 2.2.0 Time complexity: O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments. ACL categories:  `@write`, `@list`, `@fast`,   Inserts specified values at the head of the list stored at `key`, only if `key` already exists and holds a list. In contrary to [`LPUSH`](../lpush), no operation will be performed when `key` does not yet exist.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the list after the push operation.

 Examples
--------

 
```

LPUSH mylist "World"
LPUSHX mylist "Hello"
LPUSHX myotherlist "Hello"
LRANGE mylist 0 -1
LRANGE myotherlist 0 -1

```
 History
-------

 * Starting with Redis version 4.0.0: Accepts multiple `element` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/lpushx/>

MODULE
======



```
MODULE LOAD
```
 Syntax 
```
MODULE LOAD path [arg [arg ...]]
```
  Available since: 4.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Loads a module from a dynamic library at runtime.

 This command loads and initializes the Redis module from the dynamic library specified by the `path` argument. The `path` should be the absolute path of the library, including the full filename. Any additional arguments are passed unmodified to the module.

 **Note**: modules can also be loaded at server startup with `loadmodule` configuration directive in `redis.conf`.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if module was loaded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/module-load/>

MEMORY
======



```
MEMORY MALLOC-STATS
```
 Syntax 
```
MEMORY MALLOC-STATS
```
  Available since: 4.0.0 Time complexity: Depends on how much memory is allocated, could be slow ACL categories:  `@slow`,   The `MEMORY MALLOC-STATS` command provides an internal statistics report from the memory allocator.

 This command is currently implemented only when using **jemalloc** as an allocator, and evaluates to a benign NOOP for all others.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the memory allocator's internal statistics report



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/memory-malloc-stats/>

MEMORY
======



```
MEMORY STATS
```
 Syntax 
```
MEMORY STATS
```
  Available since: 4.0.0 Time complexity: O(1) ACL categories:  `@slow`,   The `MEMORY STATS` command returns an [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) about the memory usage of the server.

 The information about memory usage is provided as metrics and their respective values. The following metrics are reported:

 * `peak.allocated`: Peak memory consumed by Redis in bytes (see [`INFO`](../info)'s `used_memory_peak`)
* `total.allocated`: Total number of bytes allocated by Redis using its allocator (see [`INFO`](../info)'s `used_memory`)
* `startup.allocated`: Initial amount of memory consumed by Redis at startup in bytes (see [`INFO`](../info)'s `used_memory_startup`)
* `replication.backlog`: Size in bytes of the replication backlog (see [`INFO`](../info)'s `repl_backlog_active`)
* `clients.slaves`: The total size in bytes of all replicas overheads (output and query buffers, connection contexts)
* `clients.normal`: The total size in bytes of all clients overheads (output and query buffers, connection contexts)
* `cluster.links`: Memory usage by cluster links (Added in Redis 7.0, see [`INFO`](../info)'s `mem_cluster_links`).
* `aof.buffer`: The summed size in bytes of AOF related buffers.
* `lua.caches`: the summed size in bytes of the overheads of the Lua scripts' caches
* `dbXXX`: For each of the server's databases, the overheads of the main and expiry dictionaries (`overhead.hashtable.main` and `overhead.hashtable.expires`, respectively) are reported in bytes
* `overhead.total`: The sum of all overheads, i.e. `startup.allocated`, `replication.backlog`, `clients.slaves`, `clients.normal`, `aof.buffer` and those of the internal data structures that are used in managing the Redis keyspace (see [`INFO`](../info)'s `used_memory_overhead`)
* `keys.count`: The total number of keys stored across all databases in the server
* `keys.bytes-per-key`: The ratio between **net memory usage** (`total.allocated` minus `startup.allocated`) and `keys.count`
* `dataset.bytes`: The size in bytes of the dataset, i.e. `overhead.total` subtracted from `total.allocated` (see [`INFO`](../info)'s `used_memory_dataset`)
* `dataset.percentage`: The percentage of `dataset.bytes` out of the net memory usage
* `peak.percentage`: The percentage of `peak.allocated` out of `total.allocated`
* `fragmentation`: See [`INFO`](../info)'s `mem_fragmentation_ratio`

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): nested list of memory usage metrics and their values

 **A note about the word slave used in this man page**: Starting with Redis 5, if not for backward compatibility, the Redis project no longer uses the word slave. Unfortunately in this command the word slave is part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/memory-stats/>

MODULE
======



```
MODULE LOADEX
```
 Syntax 
```
MODULE LOADEX path [CONFIG name value [CONFIG name value ...]]
  [ARGS args [args ...]]
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Loads a module from a dynamic library at runtime with configuration directives.

 This is an extended version of the [`MODULE LOAD`](../module-load) command.

 It loads and initializes the Redis module from the dynamic library specified by the `path` argument. The `path` should be the absolute path of the library, including the full filename.

 You can use the optional `CONFIG` argument to provide the module with configuration directives. Any additional arguments that follow the `ARGS` keyword are passed unmodified to the module.

 **Note**: modules can also be loaded at server startup with `loadmodule` configuration directive in `redis.conf`.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if module was loaded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/module-loadex/>

MEMORY
======



```
MEMORY PURGE
```
 Syntax 
```
MEMORY PURGE
```
  Available since: 4.0.0 Time complexity: Depends on how much memory is allocated, could be slow ACL categories:  `@slow`,   The `MEMORY PURGE` command attempts to purge dirty pages so these can be reclaimed by the allocator.

 This command is currently implemented only when using **jemalloc** as an allocator, and evaluates to a benign NOOP for all others.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/memory-purge/>

MSETNX
======



```
MSETNX
```
 Syntax 
```
MSETNX key value [key value ...]
```
  Available since: 1.0.1 Time complexity: O(N) where N is the number of keys to set. ACL categories:  `@write`, `@string`, `@slow`,   Sets the given keys to their respective values. `MSETNX` will not perform any operation at all even if just a single key already exists.

 Because of this semantic `MSETNX` can be used in order to set different keys representing different fields of a unique logic object in a way that ensures that either all the fields or none at all are set.

 `MSETNX` is atomic, so all given keys are set at once. It is not possible for clients to see that some of the keys were updated while others are unchanged.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the all the keys were set.
* `0` if no key was set (at least one key already existed).

 Examples
--------

 
```

MSETNX key1 "Hello" key2 "there"
MSETNX key2 "new" key3 "world"
MGET key1 key2 key3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/msetnx/>

MEMORY
======



```
MEMORY DOCTOR
```
 Syntax 
```
MEMORY DOCTOR
```
  Available since: 4.0.0 Time complexity: O(1) ACL categories:  `@slow`,   The `MEMORY DOCTOR` command reports about different memory-related issues that the Redis server experiences, and advises about possible remedies.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/memory-doctor/>

MEMORY
======



```
MEMORY USAGE
```
 Syntax 
```
MEMORY USAGE key [SAMPLES count]
```
  Available since: 4.0.0 Time complexity: O(N) where N is the number of samples. ACL categories:  `@read`, `@slow`,   The `MEMORY USAGE` command reports the number of bytes that a key and its value require to be stored in RAM.

 The reported usage is the total of memory allocations for data and administrative overheads that a key its value require.

 For nested data types, the optional `SAMPLES` option can be provided, where `count` is the number of sampled nested values. The samples are averaged to estimate the total size. By default, this option is set to `5`. To sample the all of the nested values, use `SAMPLES 0`.

 Examples
--------

 With Redis v4.0.1 64-bit and **jemalloc**, the empty string measures as follows:

 
```
> SET "" ""
OK
> MEMORY USAGE ""
(integer) 51

```

These bytes are pure overhead at the moment as no actual data is stored, and are used for maintaining the internal data structures of the server. Longer keys and values show asymptotically linear usage.

 
```
> SET foo bar
OK
> MEMORY USAGE foo
(integer) 54
> SET cento 01234567890123456789012345678901234567890123
45678901234567890123456789012345678901234567890123456789
OK
127.0.0.1:6379> MEMORY USAGE cento
(integer) 153

```

Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the memory usage in bytes, or `nil` when the key does not exist.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/memory-usage/>

MIGRATE
=======



```
MIGRATE
```
 Syntax 
```
MIGRATE host port <key | ""> destination-db timeout [COPY] [REPLACE]
  [AUTH password | AUTH2 username password] [KEYS key [key ...]]
```
  Available since: 2.6.0 Time complexity: This command actually executes a DUMP+DEL in the source instance, and a RESTORE in the target instance. See the pages of these commands for time complexity. Also an O(N) data transfer between the two instances is performed. ACL categories:  `@keyspace`, `@write`, `@slow`, `@dangerous`,   Atomically transfer a key from a source Redis instance to a destination Redis instance. On success the key is deleted from the original instance and is guaranteed to exist in the target instance.

 The command is atomic and blocks the two instances for the time required to transfer the key, at any given time the key will appear to exist in a given instance or in the other instance, unless a timeout error occurs. In 3.2 and above, multiple keys can be pipelined in a single call to `MIGRATE` by passing the empty string ("") as key and adding the `KEYS` clause.

 The command internally uses [`DUMP`](../dump) to generate the serialized version of the key value, and [`RESTORE`](../restore) in order to synthesize the key in the target instance. The source instance acts as a client for the target instance. If the target instance returns OK to the [`RESTORE`](../restore) command, the source instance deletes the key using [`DEL`](../del).

 The timeout specifies the maximum idle time in any moment of the communication with the destination instance in milliseconds. This means that the operation does not need to be completed within the specified amount of milliseconds, but that the transfer should make progresses without blocking for more than the specified amount of milliseconds.

 `MIGRATE` needs to perform I/O operations and to honor the specified timeout. When there is an I/O error during the transfer or if the timeout is reached the operation is aborted and the special error - `IOERR` returned. When this happens the following two cases are possible:

 * The key may be on both the instances.
* The key may be only in the source instance.

 It is not possible for the key to get lost in the event of a timeout, but the client calling `MIGRATE`, in the event of a timeout error, should check if the key is *also* present in the target instance and act accordingly.

 When any other error is returned (starting with `ERR`) `MIGRATE` guarantees that the key is still only present in the originating instance (unless a key with the same name was also *already* present on the target instance).

 If there are no keys to migrate in the source instance `NOKEY` is returned. Because missing keys are possible in normal conditions, from expiry for example, `NOKEY` isn't an error.

 Migrating multiple keys with a single command call
--------------------------------------------------

 Starting with Redis 3.0.6 `MIGRATE` supports a new bulk-migration mode that uses pipelining in order to migrate multiple keys between instances without incurring in the round trip time latency and other overheads that there are when moving each key with a single `MIGRATE` call.

 In order to enable this form, the `KEYS` option is used, and the normal *key* argument is set to an empty string. The actual key names will be provided after the `KEYS` argument itself, like in the following example:

 
```
MIGRATE 192.168.1.34 6379 "" 0 5000 KEYS key1 key2 key3

```
 When this form is used the `NOKEY` status code is only returned when none of the keys is present in the instance, otherwise the command is executed, even if just a single key exists.

 Options
-------

 * `COPY` -- Do not remove the key from the local instance.
* `REPLACE` -- Replace existing key on the remote instance.
* `KEYS` -- If the key argument is an empty string, the command will instead migrate all the keys that follow the `KEYS` option (see the above section for more info).
* `AUTH` -- Authenticate with the given password to the remote instance.
* `AUTH2` -- Authenticate with the given username and password pair (Redis 6 or greater ACL auth style).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The command returns OK on success, or `NOKEY` if no keys were found in the source instance.

 History
-------

 * Starting with Redis version 3.0.0: Added the `COPY` and `REPLACE` options.
* Starting with Redis version 3.0.6: Added the `KEYS` option.
* Starting with Redis version 4.0.7: Added the `AUTH` option.
* Starting with Redis version 6.0.0: Added the `AUTH2` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/migrate/>

MODULE
======



```
MODULE UNLOAD
```
 Syntax 
```
MODULE UNLOAD name
```
  Available since: 4.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   Unloads a module.

 This command unloads the module specified by `name`. Note that the module's name is reported by the [`MODULE LIST`](../module-list) command, and may differ from the dynamic library's filename.

 Known limitations:

 * Modules that register custom data types can not be unloaded.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if module was unloaded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/module-unload/>

MOVE
====



```
MOVE
```
 Syntax 
```
MOVE key db
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   Move `key` from the currently selected database (see [`SELECT`](../select)) to the specified destination database. When `key` already exists in the destination database, or it does not exist in the source database, it does nothing. It is possible to use `MOVE` as a locking primitive because of this.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if `key` was moved.
* `0` if `key` was not moved.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/move/>

MGET
====



```
MGET
```
 Syntax 
```
MGET key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of keys to retrieve. ACL categories:  `@read`, `@string`, `@fast`,   Returns the values of all specified keys. For every key that does not hold a string value or does not exist, the special value `nil` is returned. Because of this, the operation never fails.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of values at the specified keys.

 Examples
--------

 
```

SET key1 "Hello"
SET key2 "World"
MGET key1 key2 nonexisting

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/mget/>

MODULE
======



```
MODULE LIST
```
 Syntax 
```
MODULE LIST
```
  Available since: 4.0.0 Time complexity: O(N) where N is the number of loaded modules. ACL categories:  `@admin`, `@slow`, `@dangerous`,   Returns information about the modules loaded to the server.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of loaded modules. Each element in the list represents a module, and is in itself a list of property names and their values. The following properties is reported for each loaded module:

 * `name`: Name of the module
* `ver`: Version of the module



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/module-list/>

MULTI
=====



```
MULTI
```
 Syntax 
```
MULTI
```
  Available since: 1.2.0 Time complexity: O(1) ACL categories:  `@fast`, `@transaction`,   Marks the start of a [transaction](https://redis.io/topics/transactions) block. Subsequent commands will be queued for atomic execution using [`EXEC`](../exec).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/multi/>

MSET
====



```
MSET
```
 Syntax 
```
MSET key value [key value ...]
```
  Available since: 1.0.1 Time complexity: O(N) where N is the number of keys to set. ACL categories:  `@write`, `@string`, `@slow`,   Sets the given keys to their respective values. `MSET` replaces existing values with new values, just as regular [`SET`](../set). See [`MSETNX`](../msetnx) if you don't want to overwrite existing values.

 `MSET` is atomic, so all given keys are set at once. It is not possible for clients to see that some of the keys were updated while others are unchanged.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK` since `MSET` can't fail.

 Examples
--------

 
```

MSET key1 "Hello" key2 "World"
GET key1
GET key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/mset/>

OBJECT
======



```
OBJECT ENCODING
```
 Syntax 
```
OBJECT ENCODING key
```
  Available since: 2.2.3 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@slow`,   Returns the internal encoding for the Redis object stored at `<key>`

 Redis objects can be encoded in different ways:

 * Strings can be encoded as:


	+ `raw`, normal string encoding.
	+ `int`, strings representing integers in a 64-bit signed interval, encoded in this way to save space.
	+ `embstr`, an embedded string, which is an object where the internal simple dynamic string, `sds`, is an unmodifiable string allocated in the same chuck as the object itself. `embstr` can be strings with lengths up to the hardcoded limit of `OBJ_ENCODING_EMBSTR_SIZE_LIMIT` or 44 bytes.
* Lists can be encoded as `ziplist` or `linkedlist`. The `ziplist` is the special representation that is used to save space for small lists.
* Sets can be encoded as `intset` or `hashtable`. The `intset` is a special encoding used for small sets composed solely of integers.
* Hashes can be encoded as `ziplist` or `hashtable`. The `ziplist` is a special encoding used for small hashes.
* Sorted Sets can be encoded as `ziplist` or `skiplist` format. As for the List type small sorted sets can be specially encoded using `ziplist`, while the `skiplist` encoding is the one that works with sorted sets of any size.

 All the specially encoded types are automatically converted to the general type once you perform an operation that makes it impossible for Redis to retain the space saving encoding.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the encoding of the object, or `nil` if the key doesn't exist



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/object-encoding/>

OBJECT
======



```
OBJECT FREQ
```
 Syntax 
```
OBJECT FREQ key
```
  Available since: 4.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@slow`,   This command returns the logarithmic access frequency counter of a Redis object stored at `<key>`.

 The command is only available when the `maxmemory-policy` configuration directive is set to one of the LFU policies.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The counter's value.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/object-freq/>

PERSIST
=======



```
PERSIST
```
 Syntax 
```
PERSIST key
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   Remove the existing timeout on `key`, turning the key from *volatile* (a key with an expire set) to *persistent* (a key that will never expire as no timeout is associated).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the timeout was removed.
* `0` if `key` does not exist or does not have an associated timeout.

 Examples
--------

 
```

SET mykey "Hello"
EXPIRE mykey 10
TTL mykey
PERSIST mykey
TTL mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/persist/>

PEXPIRE
=======



```
PEXPIRE
```
 Syntax 
```
PEXPIRE key milliseconds [NX | XX | GT | LT]
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   This command works exactly like [`EXPIRE`](../expire) but the time to live of the key is specified in milliseconds instead of seconds.

 Options
-------

 The `PEXPIRE` command supports a set of options since Redis 7.0:

 * `NX` -- Set expiry only when the key has no expiry
* `XX` -- Set expiry only when the key has an existing expiry
* `GT` -- Set expiry only when the new expiry is greater than current one
* `LT` -- Set expiry only when the new expiry is less than current one

 A non-volatile key is treated as an infinite TTL for the purpose of `GT` and `LT`. The `GT`, `LT` and `NX` options are mutually exclusive.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the timeout was set.
* `0` if the timeout was not set. e.g. key doesn't exist, or operation skipped due to the provided arguments.

 Examples
--------

 
```

SET mykey "Hello"
PEXPIRE mykey 1500
TTL mykey
PTTL mykey
PEXPIRE mykey 1000 XX
TTL mykey
PEXPIRE mykey 1000 NX
TTL mykey

```
 History
-------

 * Starting with Redis version 7.0.0: Added options: `NX`, `XX`, `GT` and `LT`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pexpire/>

PEXPIREAT
=========



```
PEXPIREAT
```
 Syntax 
```
PEXPIREAT key unix-time-milliseconds [NX | XX | GT | LT]
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   `PEXPIREAT` has the same effect and semantic as [`EXPIREAT`](../expireat), but the Unix time at which the key will expire is specified in milliseconds instead of seconds.

 Options
-------

 The `PEXPIREAT` command supports a set of options since Redis 7.0:

 * `NX` -- Set expiry only when the key has no expiry
* `XX` -- Set expiry only when the key has an existing expiry
* `GT` -- Set expiry only when the new expiry is greater than current one
* `LT` -- Set expiry only when the new expiry is less than current one

 A non-volatile key is treated as an infinite TTL for the purpose of `GT` and `LT`. The `GT`, `LT` and `NX` options are mutually exclusive.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the timeout was set.
* `0` if the timeout was not set. e.g. key doesn't exist, or operation skipped due to the provided arguments.

 Examples
--------

 
```

SET mykey "Hello"
PEXPIREAT mykey 1555555555005
TTL mykey
PTTL mykey

```
 History
-------

 * Starting with Redis version 7.0.0: Added options: `NX`, `XX`, `GT` and `LT`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pexpireat/>

OBJECT
======



```
OBJECT IDLETIME
```
 Syntax 
```
OBJECT IDLETIME key
```
  Available since: 2.2.3 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@slow`,   This command returns the time in seconds since the last access to the value stored at `<key>`.

 The command is only available when the `maxmemory-policy` configuration directive is not set to one of the LFU policies.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The idle time in seconds.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/object-idletime/>

OBJECT
======



```
OBJECT REFCOUNT
```
 Syntax 
```
OBJECT REFCOUNT key
```
  Available since: 2.2.3 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@slow`,   This command returns the reference count of the stored at `<key>`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The number of references.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/object-refcount/>

PFADD
=====



```
PFADD
```
 Syntax 
```
PFADD key [element [element ...]]
```
  Available since: 2.8.9 Time complexity: O(1) to add every element. ACL categories:  `@write`, `@hyperloglog`, `@fast`,   Adds all the element arguments to the HyperLogLog data structure stored at the variable name specified as first argument.

 As a side effect of this command the HyperLogLog internals may be updated to reflect a different estimation of the number of unique items added so far (the cardinality of the set).

 If the approximated cardinality estimated by the HyperLogLog changed after executing the command, `PFADD` returns 1, otherwise 0 is returned. The command automatically creates an empty HyperLogLog structure (that is, a Redis String of a specified length and with a given encoding) if the specified key does not exist.

 To call the command without elements but just the variable name is valid, this will result into no operation performed if the variable already exists, or just the creation of the data structure if the key does not exist (in the latter case 1 is returned).

 For an introduction to HyperLogLog data structure check the [`PFCOUNT`](../pfcount) command page.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * 1 if at least 1 HyperLogLog internal register was altered. 0 otherwise.

 Examples
--------

 
```

PFADD hll a b c d e f g
PFCOUNT hll

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pfadd/>

PSETEX
======



```
PSETEX (deprecated)
```
  As of Redis version 2.6.12, this command is regarded as deprecated.

 It can be replaced by [`SET`](../set) with the `PX` argument when migrating or writing new code.

  Syntax 
```
PSETEX key milliseconds value
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@slow`,   `PSETEX` works exactly like [`SETEX`](../setex) with the sole difference that the expire time is specified in milliseconds instead of seconds.

 Examples
--------

 
```

PSETEX mykey 1000 "Hello"
PTTL mykey
GET mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/psetex/>

PUBLISH
=======



```
PUBLISH
```
 Syntax 
```
PUBLISH channel message
```
  Available since: 2.0.0 Time complexity: O(N+M) where N is the number of clients subscribed to the receiving channel and M is the total number of subscribed patterns (by any client). ACL categories:  `@pubsub`, `@fast`,   Posts a message to the given channel.

 In a Redis Cluster clients can publish to every node. The cluster makes sure that published messages are forwarded as needed, so clients can subscribe to any channel by connecting to any one of the nodes.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of clients that received the message. Note that in a Redis Cluster, only clients that are connected to the same node as the publishing client are included in the count.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/publish/>

PFMERGE
=======



```
PFMERGE
```
 Syntax 
```
PFMERGE destkey [sourcekey [sourcekey ...]]
```
  Available since: 2.8.9 Time complexity: O(N) to merge N HyperLogLogs, but with high constant times. ACL categories:  `@write`, `@hyperloglog`, `@slow`,   Merge multiple HyperLogLog values into a unique value that will approximate the cardinality of the union of the observed Sets of the source HyperLogLog structures.

 The computed merged HyperLogLog is set to the destination variable, which is created if does not exist (defaulting to an empty HyperLogLog).

 If the destination variable exists, it is treated as one of the source sets and its cardinality will be included in the cardinality of the computed HyperLogLog.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The command just returns `OK`.

 Examples
--------

 
```

PFADD hll1 foo bar zap a
PFADD hll2 a b c foo
PFMERGE hll3 hll1 hll2
PFCOUNT hll3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pfmerge/>

PFDEBUG
=======



```
PFDEBUG
```
 Syntax 
```
PFDEBUG subcommand key
```
  Available since: 2.8.9 Time complexity: N/A ACL categories:  `@write`, `@hyperloglog`, `@admin`, `@slow`, `@dangerous`,   The `PFDEBUG` command is an internal command. It is meant to be used for developing and testing Redis.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pfdebug/>

PEXPIRETIME
===========



```
PEXPIRETIME
```
 Syntax 
```
PEXPIRETIME key
```
  Available since: 7.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   `PEXPIRETIME` has the same semantic as [`EXPIRETIME`](../expiretime), but returns the absolute Unix expiration timestamp in milliseconds instead of seconds.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): Expiration Unix timestamp in milliseconds, or a negative value in order to signal an error (see the description below).

 * The command returns `-1` if the key exists but has no associated expiration time.
* The command returns `-2` if the key does not exist.

 Examples
--------

 
```

SET mykey "Hello"
PEXPIREAT mykey 33177117420000
PEXPIRETIME mykey

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pexpiretime/>

PFCOUNT
=======



```
PFCOUNT
```
 Syntax 
```
PFCOUNT key [key ...]
```
  Available since: 2.8.9 Time complexity: O(1) with a very small average constant time when called with a single key. O(N) with N being the number of keys, and much bigger constant times, when called with multiple keys. ACL categories:  `@read`, `@hyperloglog`, `@slow`,   When called with a single key, returns the approximated cardinality computed by the HyperLogLog data structure stored at the specified variable, which is 0 if the variable does not exist.

 When called with multiple keys, returns the approximated cardinality of the union of the HyperLogLogs passed, by internally merging the HyperLogLogs stored at the provided keys into a temporary HyperLogLog.

 The HyperLogLog data structure can be used in order to count **unique** elements in a set using just a small constant amount of memory, specifically 12k bytes for every HyperLogLog (plus a few bytes for the key itself).

 The returned cardinality of the observed set is not exact, but approximated with a standard error of 0.81%.

 For example in order to take the count of all the unique search queries performed in a day, a program needs to call [`PFADD`](../pfadd) every time a query is processed. The estimated number of unique queries can be retrieved with `PFCOUNT` at any time.

 Note: as a side effect of calling this function, it is possible that the HyperLogLog is modified, since the last 8 bytes encode the latest computed cardinality for caching purposes. So `PFCOUNT` is technically a write command.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * The approximated number of unique elements observed via [`PFADD`](../pfadd).

 Examples
--------

 
```

PFADD hll foo bar zap
PFADD hll zap zap zap
PFADD hll foo bar
PFCOUNT hll
PFADD some-other-hll 1 2 3
PFCOUNT hll some-other-hll

```
 Performances
------------

 When `PFCOUNT` is called with a single key, performances are excellent even if in theory constant times to process a dense HyperLogLog are high. This is possible because the `PFCOUNT` uses caching in order to remember the cardinality previously computed, that rarely changes because most [`PFADD`](../pfadd) operations will not update any register. Hundreds of operations per second are possible.

 When `PFCOUNT` is called with multiple keys, an on-the-fly merge of the HyperLogLogs is performed, which is slow, moreover the cardinality of the union can't be cached, so when used with multiple keys `PFCOUNT` may take a time in the order of magnitude of the millisecond, and should be not abused.

 The user should take in mind that single-key and multiple-keys executions of this command are semantically different and have different performances.

 HyperLogLog representation
--------------------------

 Redis HyperLogLogs are represented using a double representation: the *sparse* representation suitable for HLLs counting a small number of elements (resulting in a small number of registers set to non-zero value), and a *dense* representation suitable for higher cardinalities. Redis automatically switches from the sparse to the dense representation when needed.

 The sparse representation uses a run-length encoding optimized to store efficiently a big number of registers set to zero. The dense representation is a Redis string of 12288 bytes in order to store 16384 6-bit counters. The need for the double representation comes from the fact that using 12k (which is the dense representation memory requirement) to encode just a few registers for smaller cardinalities is extremely suboptimal.

 Both representations are prefixed with a 16 bytes header, that includes a magic, an encoding / version field, and the cached cardinality estimation computed, stored in little endian format (the most significant bit is 1 if the estimation is invalid since the HyperLogLog was updated since the cardinality was computed).

 The HyperLogLog, being a Redis string, can be retrieved with [`GET`](../get) and restored with [`SET`](../set). Calling [`PFADD`](../pfadd), `PFCOUNT` or [`PFMERGE`](../pfmerge) commands with a corrupted HyperLogLog is never a problem, it may return random values but does not affect the stability of the server. Most of the times when corrupting a sparse representation, the server recognizes the corruption and returns an error.

 The representation is neutral from the point of view of the processor word size and endianness, so the same representation is used by 32 bit and 64 bit processor, big endian or little endian.

 More details about the Redis HyperLogLog implementation can be found in [this blog post](http://antirez.com/news/75). The source code of the implementation in the `hyperloglog.c` file is also easy to read and understand, and includes a full specification for the exact encoding used for the sparse and dense representations.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pfcount/>

PFSELFTEST
==========



```
PFSELFTEST
```
 Syntax 
```
PFSELFTEST
```
  Available since: 2.8.9 Time complexity: N/A ACL categories:  `@hyperloglog`, `@admin`, `@slow`, `@dangerous`,   The `PFSELFTEST` command is an internal command. It is meant to be used for developing and testing Redis.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pfselftest/>

PING
====



```
PING
```
 Syntax 
```
PING [message]
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Returns `PONG` if no argument is provided, otherwise return a copy of the argument as a bulk. This command is useful for:

 1. Testing whether a connection is still alive.
2. Verifying the server's ability to serve data - an error is returned when this isn't the case (e.g., during load from persistence or accessing a stale replica).
3. Measuring latency.

 If the client is subscribed to a channel or a pattern, it will instead return a multi-bulk with a "pong" in the first position and an empty bulk in the second position, unless an argument is provided in which case it returns a copy of the argument.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings), and specifically `PONG`, when no argument is provided.

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) the argument provided, when applicable.

 Examples
--------

 
```

PING
PING "hello world"



```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ping/>

PUBSUB
======



```
PUBSUB NUMPAT
```
 Syntax 
```
PUBSUB NUMPAT
```
  Available since: 2.8.0 Time complexity: O(1) ACL categories:  `@pubsub`, `@slow`,   Returns the number of unique patterns that are subscribed to by clients (that are performed using the [`PSUBSCRIBE`](../psubscribe) command).

 Note that this isn't the count of clients subscribed to patterns, but the total number of unique patterns all the clients are subscribed to.

 Cluster note: in a Redis Cluster clients can subscribe to every node, and can also publish to every other node. The cluster will make sure that published messages are forwarded as needed. That said, [`PUBSUB`](../pubsub)'s replies in a cluster only report information from the node's Pub/Sub context, rather than the entire cluster.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of patterns all the clients are subscribed to.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pubsub-numpat/>

PSUBSCRIBE
==========



```
PSUBSCRIBE
```
 Syntax 
```
PSUBSCRIBE pattern [pattern ...]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of patterns the client is already subscribed to. ACL categories:  `@pubsub`, `@slow`,   Subscribes the client to the given patterns.

 Supported glob-style patterns:

 * `h?llo` subscribes to `hello`, `hallo` and `hxllo`
* `h*llo` subscribes to `hllo` and `heeeello`
* `h[ae]llo` subscribes to `hello` and `hallo,` but not `hillo`

 Use `\` to escape special characters if you want to match them verbatim.

 Once the client enters the subscribed state it is not supposed to issue any other commands, except for additional [`SUBSCRIBE`](../subscribe), [`SSUBSCRIBE`](../ssubscribe), `PSUBSCRIBE`, [`UNSUBSCRIBE`](../unsubscribe), [`SUNSUBSCRIBE`](../sunsubscribe), [`PUNSUBSCRIBE`](../punsubscribe), [`PING`](../ping), [`RESET`](../reset) and [`QUIT`](../quit) commands. However, if RESP3 is used (see [`HELLO`](../hello)) it is possible for a client to issue any commands while in subscribed state.

 For more information, see [Pub/sub](https://redis.io/docs/manual/pubsub/).

 Return
------

 When successful, this command doesn't return anything. Instead, for each pattern, one message with the first element being the string "psubscribe" is pushed as a confirmation that the command succeeded.

 Behavior change history
-----------------------

 * `>= 6.2.0`: [`RESET`](../reset) can be called to exit subscribed state.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/psubscribe/>

PUBSUB
======



```
PUBSUB CHANNELS
```
 Syntax 
```
PUBSUB CHANNELS [pattern]
```
  Available since: 2.8.0 Time complexity: O(N) where N is the number of active channels, and assuming constant time pattern matching (relatively short channels and patterns) ACL categories:  `@pubsub`, `@slow`,   Lists the currently *active channels*.

 An active channel is a Pub/Sub channel with one or more subscribers (excluding clients subscribed to patterns).

 If no `pattern` is specified, all the channels are listed, otherwise if pattern is specified only channels matching the specified glob-style pattern are listed.

 Cluster note: in a Redis Cluster clients can subscribe to every node, and can also publish to every other node. The cluster will make sure that published messages are forwarded as needed. That said, [`PUBSUB`](../pubsub)'s replies in a cluster only report information from the node's Pub/Sub context, rather than the entire cluster.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of active channels, optionally matching the specified pattern.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pubsub-channels/>

PSYNC
=====



```
PSYNC
```
 Syntax 
```
PSYNC replicationid offset
```
  Available since: 2.8.0 Time complexity: ACL categories:  `@admin`, `@slow`, `@dangerous`,   Initiates a replication stream from the master.

 The `PSYNC` command is called by Redis replicas for initiating a replication stream from the master.

 For more information about replication in Redis please check the [replication page](https://redis.io/topics/replication).

 Return
------

 **Non standard return value**, a bulk transfer of the data followed by [`PING`](../ping) and write requests from the master.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/psync/>

PUBSUB
======



```
PUBSUB SHARDCHANNELS
```
 Syntax 
```
PUBSUB SHARDCHANNELS [pattern]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of active shard channels, and assuming constant time pattern matching (relatively short shard channels). ACL categories:  `@pubsub`, `@slow`,   Lists the currently *active shard channels*.

 An active shard channel is a Pub/Sub shard channel with one or more subscribers.

 If no `pattern` is specified, all the channels are listed, otherwise if pattern is specified only channels matching the specified glob-style pattern are listed.

 The information returned about the active shard channels are at the shard level and not at the cluster level.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of active channels, optionally matching the specified pattern.

 Examples
--------

 
```
> PUBSUB SHARDCHANNELS
1) "orders"
PUBSUB SHARDCHANNELS o*
1) "orders"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pubsub-shardchannels/>

PUBSUB
======



```
PUBSUB SHARDNUMSUB
```
 Syntax 
```
PUBSUB SHARDNUMSUB [shardchannel [shardchannel ...]]
```
  Available since: 7.0.0 Time complexity: O(N) for the SHARDNUMSUB subcommand, where N is the number of requested shard channels ACL categories:  `@pubsub`, `@slow`,   Returns the number of subscribers for the specified shard channels.

 Note that it is valid to call this command without channels, in this case it will just return an empty list.

 Cluster note: in a Redis Cluster, [`PUBSUB`](../pubsub)'s replies in a cluster only report information from the node's Pub/Sub context, rather than the entire cluster.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of channels and number of subscribers for every channel.

 The format is channel, count, channel, count, ..., so the list is flat. The order in which the channels are listed is the same as the order of the shard channels specified in the command call.

 Examples
--------

 
```
> PUBSUB SHARDNUMSUB orders
1) "orders"
2) (integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pubsub-shardnumsub/>

PUNSUBSCRIBE
============



```
PUNSUBSCRIBE
```
 Syntax 
```
PUNSUBSCRIBE [pattern [pattern ...]]
```
  Available since: 2.0.0 Time complexity: O(N+M) where N is the number of patterns the client is already subscribed and M is the number of total patterns subscribed in the system (by any client). ACL categories:  `@pubsub`, `@slow`,   Unsubscribes the client from the given patterns, or from all of them if none is given.

 When no patterns are specified, the client is unsubscribed from all the previously subscribed patterns. In this case, a message for every unsubscribed pattern will be sent to the client.

 Return
------

 When successful, this command doesn't return anything. Instead, for each pattern, one message with the first element being the string "punsubscribe" is pushed as a confirmation that the command succeeded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/punsubscribe/>

REPLICAOF
=========



```
REPLICAOF
```
 Syntax 
```
REPLICAOF host port
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `REPLICAOF` command can change the replication settings of a replica on the fly.

 If a Redis server is already acting as replica, the command `REPLICAOF` NO ONE will turn off the replication, turning the Redis server into a MASTER. In the proper form `REPLICAOF` hostname port will make the server a replica of another server listening at the specified hostname and port.

 If a server is already a replica of some master, `REPLICAOF` hostname port will stop the replication against the old server and start the synchronization against the new one, discarding the old dataset.

 The form `REPLICAOF` NO ONE will stop replication, turning the server into a MASTER, but will not discard the replication. So, if the old master stops working, it is possible to turn the replica into a master and set the application to use this new master in read/write. Later when the other Redis server is fixed, it can be reconfigured to work as a replica.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```
> REPLICAOF NO ONE
"OK"

> REPLICAOF 127.0.0.1 6799
"OK"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/replicaof/>

RPOPLPUSH
=========



```
RPOPLPUSH (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`LMOVE`](../lmove) with the `RIGHT` and `LEFT` arguments when migrating or writing new code.

  Syntax 
```
RPOPLPUSH source destination
```
  Available since: 1.2.0 Time complexity: O(1) ACL categories:  `@write`, `@list`, `@slow`,   Atomically returns and removes the last element (tail) of the list stored at `source`, and pushes the element at the first element (head) of the list stored at `destination`.

 For example: consider `source` holding the list `a,b,c`, and `destination` holding the list `x,y,z`. Executing `RPOPLPUSH` results in `source` holding `a,b` and `destination` holding `c,x,y,z`.

 If `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 list and pushing it as first element of the list, so it can be considered as a list rotation command.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the element being popped and pushed.

 Examples
--------

 
```

RPUSH mylist "one"
RPUSH mylist "two"
RPUSH mylist "three"
RPOPLPUSH mylist myotherlist
LRANGE mylist 0 -1
LRANGE myotherlist 0 -1

```
 Pattern: Reliable queue
-----------------------

 Redis is often used as a messaging server to implement processing of background jobs or other kinds of messaging tasks. A simple form of queue is often obtained pushing values into a list in the producer side, and waiting for this values in the consumer side using [`RPOP`](../rpop) (using polling), or [`BRPOP`](../brpop) if the client is better served by a blocking operation.

 However in this context the obtained queue is not *reliable* as messages can be lost, for example in the case there is a network problem or if the consumer crashes just after the message is received but before it can be processed.

 `RPOPLPUSH` (or [`BRPOPLPUSH`](../brpoplpush) for the blocking variant) offers a way to avoid this problem: the consumer fetches the message and at the same time pushes it into a *processing* list. It will use the [`LREM`](../lrem) command in order to remove the message from the *processing* list once the message has been processed.

 An additional client may monitor the *processing* list for items that remain there for too much time, pushing timed out items into the queue again if needed.

 Pattern: Circular list
----------------------

 Using `RPOPLPUSH` with the same source and destination key, a client can visit all the elements of an N-elements list, one after the other, in O(N) without transferring the full list from the server to the client using a single [`LRANGE`](../lrange) operation.

 The above pattern works even if one or both of the following conditions occur:

 * There are multiple clients rotating the list: they'll fetch different elements, until all the elements of the list are visited, and the process restarts.
* Other clients are actively pushing new items at the end of the list.

 The above makes it very simple to implement a system where a set of items must be processed by N workers continuously as fast as possible. An example is a monitoring system that must check that a set of web sites are reachable, with the smallest delay possible, using a number of parallel workers.

 Note that this implementation of workers is trivially scalable and reliable, because even if a message is lost the item is still in the queue and will be processed at the next iteration.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/rpoplpush/>

PTTL
====



```
PTTL
```
 Syntax 
```
PTTL key
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   Like [`TTL`](../ttl) this command returns the remaining time to live of a key that has an expire set, with the sole difference that [`TTL`](../ttl) returns the amount of remaining time in seconds while `PTTL` returns it in milliseconds.

 In Redis 2.6 or older the command returns `-1` if the key does not exist or if the key exist but has no associated expire.

 Starting with Redis 2.8 the return value in case of error changed:

 * The command returns `-2` if the key does not exist.
* The command returns `-1` if the key exists but has no associated expire.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): TTL in milliseconds, or a negative value in order to signal an error (see the description above).

 Examples
--------

 
```

SET mykey "Hello"
EXPIRE mykey 1
PTTL mykey

```
 History
-------

 * Starting with Redis version 2.8.0: Added the -2 reply.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pttl/>

QUIT
====



```
QUIT (deprecated)
```
  As of Redis version 7.2.0, this command is regarded as deprecated.

 It can be replaced by just closing the connection when migrating or writing new code.

  Syntax 
```
QUIT
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Ask the server to close the connection. The connection is closed as soon as all pending replies have been written to the client.

 **Note:** Clients should not use this command. Instead, clients should simply close the connection when they're not used anymore. Terminating a connection on the client side is preferable, as it eliminates `TIME_WAIT` lingering sockets on the server side.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always OK.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/quit/>

RANDOMKEY
=========



```
RANDOMKEY
```
 Syntax 
```
RANDOMKEY
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@slow`,   Return a random key from the currently selected database.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the random key, or `nil` when the database is empty.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/randomkey/>

RESTORE
=======



```
RESTORE
```
 Syntax 
```
RESTORE key ttl serialized-value [REPLACE] [ABSTTL]
  [IDLETIME seconds] [FREQ frequency]
```
  Available since: 2.6.0 Time complexity: O(1) to create the new key and additional O(N\*M) to reconstruct the serialized value, where N is the number of Redis objects composing the value and M their average size. For small string values the time complexity is thus O(1)+O(1\*M) where M is small, so simply O(1). However for sorted set values the complexity is O(N\*M\*log(N)) because inserting values into sorted sets is O(log(N)). ACL categories:  `@keyspace`, `@write`, `@slow`, `@dangerous`,   Create a key associated with a value that is obtained by deserializing the provided serialized value (obtained via [`DUMP`](../dump)).

 If `ttl` is 0 the key is created without any expire, otherwise the specified expire time (in milliseconds) is set.

 If the `ABSTTL` modifier was used, `ttl` should represent an absolute [Unix timestamp](http://en.wikipedia.org/wiki/Unix_time) (in milliseconds) in which the key will expire.

 For eviction purposes, you may use the `IDLETIME` or `FREQ` modifiers. See [`OBJECT`](../object) for more information.

 `RESTORE` will return a "Target key name is busy" error when `key` already exists unless you use the `REPLACE` modifier.

 `RESTORE` checks the RDB version and data checksum. If they don't match an error is returned.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The command returns OK on success.

 Examples
--------

 
```
redis> DEL mykey
0
redis> RESTORE mykey 0 "\n\x17\x17\x00\x00\x00\x12\x00\x00\x00\x03\x00\
                        x00\xc0\x01\x00\x04\xc0\x02\x00\x04\xc0\x03\x00\
                        xff\x04\x00u#<\xc0;.\xe9\xdd"
OK
redis> TYPE mykey
list
redis> LRANGE mykey 0 -1
1) "1"
2) "2"
3) "3"

```
 History
-------

 * Starting with Redis version 3.0.0: Added the `REPLACE` modifier.
* Starting with Redis version 5.0.0: Added the `ABSTTL` modifier.
* Starting with Redis version 5.0.0: Added the `IDLETIME` and `FREQ` options.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/restore/>

READONLY
========



```
READONLY
```
 Syntax 
```
READONLY
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Enables read queries for a connection to a Redis Cluster replica node.

 Normally replica nodes will redirect clients to the authoritative master for the hash slot involved in a given command, however clients can use replicas in order to scale reads using the `READONLY` command.

 `READONLY` tells a Redis Cluster replica node that the client is willing to read possibly stale data and is not interested in running write queries.

 When the connection is in readonly mode, the cluster will send a redirection to the client only if the operation involves keys not served by the replica's master node. This may happen because:

 1. The client sent a command about hash slots never served by the master of this replica.
2. The cluster was reconfigured (for example resharded) and the replica is no longer able to serve commands for a given hash slot.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/readonly/>

RESTORE-ASKING
==============



```
RESTORE-ASKING
```
 Syntax 
```
RESTORE-ASKING key ttl serialized-value [REPLACE] [ABSTTL]
  [IDLETIME seconds] [FREQ frequency]
```
  Available since: 3.0.0 Time complexity: O(1) to create the new key and additional O(N\*M) to reconstruct the serialized value, where N is the number of Redis objects composing the value and M their average size. For small string values the time complexity is thus O(1)+O(1\*M) where M is small, so simply O(1). However for sorted set values the complexity is O(N\*M\*log(N)) because inserting values into sorted sets is O(log(N)). ACL categories:  `@keyspace`, `@write`, `@slow`, `@dangerous`,   The `RESTORE-ASKING` command is an internal command. It is used by a Redis cluster master during slot migration.

 History
-------

 * Starting with Redis version 3.0.0: Added the `REPLACE` modifier.
* Starting with Redis version 5.0.0: Added the `ABSTTL` modifier.
* Starting with Redis version 5.0.0: Added the `IDLETIME` and `FREQ` options.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/restore-asking/>

READWRITE
=========



```
READWRITE
```
 Syntax 
```
READWRITE
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Disables read queries for a connection to a Redis Cluster replica node.

 Read queries against a Redis Cluster replica node are disabled by default, but you can use the [`READONLY`](../readonly) command to change this behavior on a per- connection basis. The `READWRITE` command resets the readonly mode flag of a connection back to readwrite.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/readwrite/>

RENAMENX
========



```
RENAMENX
```
 Syntax 
```
RENAMENX key newkey
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@fast`,   Renames `key` to `newkey` if `newkey` does not yet exist. It returns an error when `key` does not exist.

 In Cluster mode, both `key` and `newkey` must be in the same **hash slot**, meaning that in practice only keys that have the same hash tag can be reliably renamed in cluster.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if `key` was renamed to `newkey`.
* `0` if `newkey` already exists.

 Examples
--------

 
```

SET mykey "Hello"
SET myotherkey "World"
RENAMENX mykey myotherkey
GET myotherkey

```
 History
-------

 * Starting with Redis version 3.2.0: The command no longer returns an error when source and destination names are the same.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/renamenx/>

PUBSUB
======



```
PUBSUB NUMSUB
```
 Syntax 
```
PUBSUB NUMSUB [channel [channel ...]]
```
  Available since: 2.8.0 Time complexity: O(N) for the NUMSUB subcommand, where N is the number of requested channels ACL categories:  `@pubsub`, `@slow`,   Returns the number of subscribers (exclusive of clients subscribed to patterns) for the specified channels.

 Note that it is valid to call this command without channels. In this case it will just return an empty list.

 Cluster note: in a Redis Cluster clients can subscribe to every node, and can also publish to every other node. The cluster will make sure that published messages are forwarded as needed. That said, [`PUBSUB`](../pubsub)'s replies in a cluster only report information from the node's Pub/Sub context, rather than the entire cluster.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of channels and number of subscribers for every channel.

 The format is channel, count, channel, count, ..., so the list is flat. The order in which the channels are listed is the same as the order of the channels specified in the command call.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/pubsub-numsub/>

RENAME
======



```
RENAME
```
 Syntax 
```
RENAME key newkey
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@write`, `@slow`,   Renames `key` to `newkey`. It returns an error when `key` does not exist. If `newkey` already exists it is overwritten, when this happens `RENAME` executes an implicit [`DEL`](../del) operation, so if the deleted key contains a very big value it may cause high latency even if `RENAME` itself is usually a constant-time operation.

 In Cluster mode, both `key` and `newkey` must be in the same **hash slot**, meaning that in practice only keys that have the same hash tag can be reliably renamed in cluster.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```

SET mykey "Hello"
RENAME mykey myotherkey
GET myotherkey

```
 Behavior change history
-----------------------

 * `>= 3.2.0`: The command no longer returns an error when source and destination names are the same.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/rename/>

RPUSH
=====



```
RPUSH
```
 Syntax 
```
RPUSH key element [element ...]
```
  Available since: 1.0.0 Time complexity: O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments. ACL categories:  `@write`, `@list`, `@fast`,   Insert all the specified values at the tail of the list stored at `key`. If `key` does not exist, it is created as empty list before performing the push operation. When `key` holds a value that is not a list, an error is returned.

 It is possible to push multiple elements using a single command call just specifying multiple arguments at the end of the command. Elements are inserted one after the other to the tail of the list, from the leftmost element to the rightmost element. So for instance the command `RPUSH mylist a b c` will result into a list containing `a` as first element, `b` as second element and `c` as third element.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the list after the push operation.

 Examples
--------

 
```

RPUSH mylist "hello"
RPUSH mylist "world"
LRANGE mylist 0 -1

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple `element` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/rpush/>

REPLCONF
========



```
REPLCONF
```
 Syntax 
```
REPLCONF
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `REPLCONF` command is an internal command. It is used by a Redis master to configure a connected replica.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/replconf/>

RESET
=====



```
RESET
```
 Syntax 
```
RESET
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   This command performs a full reset of the connection's server-side context, mimicking the effect of disconnecting and reconnecting again.

 When the command is called from a regular client connection, it does the following:

 * Discards the current [`MULTI`](../multi) transaction block, if one exists.
* Unwatches all keys [`WATCH`](../watch)ed by the connection.
* Disables [`CLIENT TRACKING`](../client-tracking), if in use.
* Sets the connection to [`READWRITE`](../readwrite) mode.
* Cancels the connection's [`ASKING`](../asking) mode, if previously set.
* Sets [`CLIENT REPLY`](../client-reply) to `ON`.
* Sets the protocol version to RESP2.
* [`SELECT`](../select)s database 0.
* Exits [`MONITOR`](../monitor) mode, when applicable.
* Aborts Pub/Sub's subscription state ([`SUBSCRIBE`](../subscribe) and [`PSUBSCRIBE`](../psubscribe)), when appropriate.
* Deauthenticates the connection, requiring a call [`AUTH`](../auth) to reauthenticate when authentication is enabled.
* Turns off `NO-EVICT` mode.
* Turns off `NO-TOUCH` mode.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always 'RESET'.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/reset/>

SCAN
====



```
SCAN
```
 Syntax 
```
SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]
```
  Available since: 2.8.0 Time complexity: O(1) for every call. O(N) for a complete iteration, including enough command calls for the cursor to return back to 0. N is the number of elements inside the collection. ACL categories:  `@keyspace`, `@read`, `@slow`,   The `SCAN` command and the closely related commands [`SSCAN`](../sscan), [`HSCAN`](../hscan) and [`ZSCAN`](../zscan) are used in order to incrementally iterate over a collection of elements.

 * `SCAN` iterates the set of keys in the currently selected Redis database.
* [`SSCAN`](../sscan) iterates elements of Sets types.
* [`HSCAN`](../hscan) iterates fields of Hash types and their associated values.
* [`ZSCAN`](../zscan) iterates elements of Sorted Set types and their associated scores.

 Since these commands allow for incremental iteration, returning only a small number of elements per call, they can be used in production without the downside of commands like [`KEYS`](../keys) or [`SMEMBERS`](../smembers) that may block the server for a long time (even several seconds) when called against big collections of keys or elements.

 However while blocking commands like [`SMEMBERS`](../smembers) are able to provide all the elements that are part of a Set in a given moment, The SCAN family of commands only offer limited guarantees about the returned elements since the collection that we incrementally iterate can change during the iteration process.

 Note that `SCAN`, [`SSCAN`](../sscan), [`HSCAN`](../hscan) and [`ZSCAN`](../zscan) all work very similarly, so this documentation covers all the four commands. However an obvious difference is that in the case of [`SSCAN`](../sscan), [`HSCAN`](../hscan) and [`ZSCAN`](../zscan) the first argument is the name of the key holding the Set, Hash or Sorted Set value. The `SCAN` command does not need any key name argument as it iterates keys in the current database, so the iterated object is the database itself.

 SCAN basic usage
----------------

 SCAN is a cursor based iterator. This means that at every call of the command, the server returns an updated cursor that the user needs to use as the cursor argument in the next call.

 An iteration starts when the cursor is set to 0, and terminates when the cursor returned by the server is 0. The following is an example of SCAN iteration:

 
```
redis 127.0.0.1:6379> scan 0
1) "17"
2)  1) "key:12"
    2) "key:8"
    3) "key:4"
    4) "key:14"
    5) "key:16"
    6) "key:17"
    7) "key:15"
    8) "key:10"
    9) "key:3"
   10) "key:7"
   11) "key:1"
redis 127.0.0.1:6379> scan 17
1) "0"
2) 1) "key:5"
   2) "key:18"
   3) "key:0"
   4) "key:2"
   5) "key:19"
   6) "key:13"
   7) "key:6"
   8) "key:9"
   9) "key:11"

```

In the example above, the first call uses zero as a cursor, to start the iteration. The second call uses the cursor returned by the previous call as the first element of the reply, that is, 17.

 As you can see the **SCAN return value** is an array of two values: the first value is the new cursor to use in the next call, the second value is an array of elements.

 Since in the second call the returned cursor is 0, the server signaled to the caller that the iteration finished, and the collection was completely explored. Starting an iteration with a cursor value of 0, and calling `SCAN` until the returned cursor is 0 again is called a **full iteration**.

 Scan guarantees
---------------

 The `SCAN` command, and the other commands in the `SCAN` family, are able to provide to the user a set of guarantees associated to full iterations.

 * A full iteration always retrieves all the elements that were present in the collection from the start to the end of a full iteration. This means that if a given element is inside the collection when an iteration is started, and is still there when an iteration terminates, then at some point `SCAN` returned it to the user.
* A full iteration never returns any element that was NOT present in the collection from the start to the end of a full iteration. So if an element was removed before the start of an iteration, and is never added back to the collection for all the time an iteration lasts, `SCAN` ensures that this element will never be returned.

 However because `SCAN` has very little state associated (just the cursor) it has the following drawbacks:

 * A given element may be returned multiple times. It is up to the application to handle the case of duplicated elements, for example only using the returned elements in order to perform operations that are safe when re-applied multiple times.
* Elements that were not constantly present in the collection during a full iteration, may be returned or not: it is undefined.

 Number of elements returned at every SCAN call
----------------------------------------------

 `SCAN` family functions do not guarantee that the number of elements returned per call are in a given range. The commands are also allowed to return zero elements, and the client should not consider the iteration complete as long as the returned cursor is not zero.

 However the number of returned elements is reasonable, that is, in practical terms SCAN may return a maximum number of elements in the order of a few tens of elements when iterating a large collection, or may return all the elements of the collection in a single call when the iterated collection is small enough to be internally represented as an encoded data structure (this happens for small sets, hashes and sorted sets).

 However there is a way for the user to tune the order of magnitude of the number of returned elements per call using the **COUNT** option.

 The COUNT option
----------------

 While `SCAN` does not provide guarantees about the number of elements returned at every iteration, it is possible to empirically adjust the behavior of `SCAN` using the **COUNT** option. Basically with COUNT the user specified the *amount of work that should be done at every call in order to retrieve elements from the collection*. This is **just a hint** for the implementation, however generally speaking this is what you could expect most of the times from the implementation.

 * The default COUNT value is 10.
* When iterating the key space, or a Set, Hash or Sorted Set that is big enough to be represented by a hash table, assuming no **MATCH** option is used, the server will usually return *count* or a bit more than *count* elements per call. Please check the *why SCAN may return all the elements at once* section later in this document.
* When iterating Sets encoded as intsets (small sets composed of just integers), or Hashes and Sorted Sets encoded as ziplists (small hashes and sets composed of small individual values), usually all the elements are returned in the first `SCAN` call regardless of the COUNT value.

 Important: **there is no need to use the same COUNT value** for every iteration. The caller is free to change the count from one iteration to the other as required, as long as the cursor passed in the next call is the one obtained in the previous call to the command.

 The MATCH option
----------------

 It is possible to only iterate elements matching a given glob-style pattern, similarly to the behavior of the [`KEYS`](../keys) command that takes a pattern as its only argument.

 To do so, just append the `MATCH <pattern>` arguments at the end of the `SCAN` command (it works with all the SCAN family commands).

 This is an example of iteration using **MATCH**:

 
```
redis 127.0.0.1:6379> sadd myset 1 2 3 foo foobar feelsgood
(integer) 6
redis 127.0.0.1:6379> sscan myset 0 match f*
1) "0"
2) 1) "foo"
   2) "feelsgood"
   3) "foobar"
redis 127.0.0.1:6379>

```

It is important to note that the **MATCH** filter is applied after elements are retrieved from the collection, just before returning data to the client. This means that if the pattern matches very little elements inside the collection, `SCAN` will likely return no elements in most iterations. An example is shown below:

 
```
redis 127.0.0.1:6379> scan 0 MATCH *11*
1) "288"
2) 1) "key:911"
redis 127.0.0.1:6379> scan 288 MATCH *11*
1) "224"
2) (empty list or set)
redis 127.0.0.1:6379> scan 224 MATCH *11*
1) "80"
2) (empty list or set)
redis 127.0.0.1:6379> scan 80 MATCH *11*
1) "176"
2) (empty list or set)
redis 127.0.0.1:6379> scan 176 MATCH *11* COUNT 1000
1) "0"
2)  1) "key:611"
    2) "key:711"
    3) "key:118"
    4) "key:117"
    5) "key:311"
    6) "key:112"
    7) "key:111"
    8) "key:110"
    9) "key:113"
   10) "key:211"
   11) "key:411"
   12) "key:115"
   13) "key:116"
   14) "key:114"
   15) "key:119"
   16) "key:811"
   17) "key:511"
   18) "key:11"
redis 127.0.0.1:6379>

```

As you can see most of the calls returned zero elements, but the last call where a COUNT of 1000 was used in order to force the command to do more scanning for that iteration.

 The TYPE option
---------------

 You can use the `TYPE` option to ask `SCAN` to only return objects that match a given `type`, allowing you to iterate through the database looking for keys of a specific type. The **TYPE** option is only available on the whole-database `SCAN`, not [`HSCAN`](../hscan) or [`ZSCAN`](../zscan) etc.

 The `type` argument is the same string name that the [`TYPE`](../type) command returns. Note a quirk where some Redis types, such as GeoHashes, HyperLogLogs, Bitmaps, and Bitfields, may internally be implemented using other Redis types, such as a string or zset, so can't be distinguished from other keys of that same type by `SCAN`. For example, a ZSET and GEOHASH:

 
```
redis 127.0.0.1:6379> GEOADD geokey 0 0 value
(integer) 1
redis 127.0.0.1:6379> ZADD zkey 1000 value
(integer) 1
redis 127.0.0.1:6379> TYPE geokey
zset
redis 127.0.0.1:6379> TYPE zkey
zset
redis 127.0.0.1:6379> SCAN 0 TYPE zset
1) "0"
2) 1) "geokey"
   2) "zkey"

```

It is important to note that the **TYPE** filter is also applied after elements are retrieved from the database, so the option does not reduce the amount of work the server has to do to complete a full iteration, and for rare types you may receive no elements in many iterations.

 Multiple parallel iterations
----------------------------

 It is possible for an infinite number of clients to iterate the same collection at the same time, as the full state of the iterator is in the cursor, that is obtained and returned to the client at every call. No server side state is taken at all.

 Terminating iterations in the middle
------------------------------------

 Since there is no state server side, but the full state is captured by the cursor, the caller is free to terminate an iteration half-way without signaling this to the server in any way. An infinite number of iterations can be started and never terminated without any issue.

 Calling SCAN with a corrupted cursor
------------------------------------

 Calling `SCAN` with a broken, negative, out of range, or otherwise invalid cursor, will result in undefined behavior but never in a crash. What will be undefined is that the guarantees about the returned elements can no longer be ensured by the `SCAN` implementation.

 The only valid cursors to use are:

 * The cursor value of 0 when starting an iteration.
* The cursor returned by the previous call to SCAN in order to continue the iteration.

 Guarantee of termination
------------------------

 The `SCAN` algorithm is guaranteed to terminate only if the size of the iterated collection remains bounded to a given maximum size, otherwise iterating a collection that always grows may result into `SCAN` to never terminate a full iteration.

 This is easy to see intuitively: if the collection grows there is more and more work to do in order to visit all the possible elements, and the ability to terminate the iteration depends on the number of calls to `SCAN` and its COUNT option value compared with the rate at which the collection grows.

 Why SCAN may return all the items of an aggregate data type in a single call?
-----------------------------------------------------------------------------

 In the `COUNT` option documentation, we state that sometimes this family of commands may return all the elements of a Set, Hash or Sorted Set at once in a single call, regardless of the `COUNT` option value. The reason why this happens is that the cursor-based iterator can be implemented, and is useful, only when the aggregate data type that we are scanning is represented as a hash table. However Redis uses a [memory optimization](https://redis.io/topics/memory-optimization) where small aggregate data types, until they reach a given amount of items or a given max size of single elements, are represented using a compact single-allocation packed encoding. When this is the case, `SCAN` has no meaningful cursor to return, and must iterate the whole data structure at once, so the only sane behavior it has is to return everything in a call.

 However once the data structures are bigger and are promoted to use real hash tables, the `SCAN` family of commands will resort to the normal behavior. Note that since this special behavior of returning all the elements is true only for small aggregates, it has no effects on the command complexity or latency. However the exact limits to get converted into real hash tables are [user configurable](https://redis.io/topics/memory-optimization), so the maximum number of elements you can see returned in a single call depends on how big an aggregate data type could be and still use the packed representation.

 Also note that this behavior is specific of [`SSCAN`](../sscan), [`HSCAN`](../hscan) and [`ZSCAN`](../zscan). `SCAN` itself never shows this behavior because the key space is always represented by hash tables.

 Return value
------------

 `SCAN`, [`SSCAN`](../sscan), [`HSCAN`](../hscan) and [`ZSCAN`](../zscan) return a two elements multi-bulk reply, where the first element is a string representing an unsigned 64 bit number (the cursor), and the second element is a multi-bulk with an array of elements.

 * `SCAN` array of elements is a list of keys.
* [`SSCAN`](../sscan) array of elements is a list of Set members.
* [`HSCAN`](../hscan) array of elements contain two elements, a field and a value, for every returned element of the Hash.
* [`ZSCAN`](../zscan) array of elements contain two elements, a member and its associated score, for every returned element of the sorted set.

 Additional examples
-------------------

 Iteration of a Hash value.

 
```
redis 127.0.0.1:6379> hmset hash name Jack age 33
OK
redis 127.0.0.1:6379> hscan hash 0
1) "0"
2) 1) "name"
   2) "Jack"
   3) "age"
   4) "33"

```
 History
-------

 * Starting with Redis version 6.0.0: Added the `TYPE` subcommand.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/scan/>

SAVE
====



```
SAVE
```
 Syntax 
```
SAVE
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of keys in all databases ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `SAVE` commands performs a **synchronous** save of the dataset producing a *point in time* snapshot of all the data inside the Redis instance, in the form of an RDB file.

 You almost never want to call `SAVE` in production environments where it will block all the other clients. Instead usually [`BGSAVE`](../bgsave) is used. However in case of issues preventing Redis to create the background saving child (for instance errors in the fork(2) system call), the `SAVE` command can be a good last resort to perform the dump of the latest dataset.

 Please refer to the [persistence documentation](https://redis.io/topics/persistence) for detailed information.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The commands returns OK on success.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/save/>

RPOP
====



```
RPOP
```
 Syntax 
```
RPOP key [count]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of elements returned ACL categories:  `@write`, `@list`, `@fast`,   Removes and returns the last elements of the list stored at `key`.

 By default, the command pops a single element from the end of the list. When provided with the optional `count` argument, the reply will consist of up to `count` elements, depending on the list's length.

 Return
------

 When called without the `count` argument:

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the value of the last element, or `nil` when `key` does not exist.

 When called with the `count` argument:

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of popped elements, or `nil` when `key` does not exist.

 Examples
--------

 
```

RPUSH mylist "one" "two" "three" "four" "five"
RPOP mylist
RPOP mylist 2
LRANGE mylist 0 -1

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `count` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/rpop/>

ROLE
====



```
ROLE
```
 Syntax 
```
ROLE
```
  Available since: 2.8.12 Time complexity: O(1) ACL categories:  `@admin`, `@fast`, `@dangerous`,   Provide information on the role of a Redis instance in the context of replication, by returning if the instance is currently a `master`, `slave`, or `sentinel`. The command also returns additional information about the state of the replication (if the role is master or slave) or the list of monitored master names (if the role is sentinel).

 Output format
-------------

 The command returns an array of elements. The first element is the role of the instance, as one of the following three strings:

 * "master"
* "slave"
* "sentinel"

 The additional elements of the array depends on the role.

 Master output
-------------

 An example of output when `ROLE` is called in a master instance:

 
```
1) "master"
2) (integer) 3129659
3) 1) 1) "127.0.0.1"
      2) "9001"
      3) "3129242"
   2) 1) "127.0.0.1"
      2) "9002"
      3) "3129543"

```

The master output is composed of the following parts:

 1. The string `master`.
2. The current master replication offset, which is an offset that masters and replicas share to understand, in partial resynchronizations, the part of the replication stream the replicas needs to fetch to continue.
3. An array composed of three elements array representing the connected replicas. Every sub-array contains the replica IP, port, and the last acknowledged replication offset.

 Output of the command on replicas
---------------------------------

 An example of output when `ROLE` is called in a replica instance:

 
```
1) "slave"
2) "127.0.0.1"
3) (integer) 9000
4) "connected"
5) (integer) 3167038

```

The replica output is composed of the following parts:

 1. The string `slave`, because of backward compatibility (see note at the end of this page).
2. The IP of the master.
3. The port number of the master.
4. The state of the replication from the point of view of the master, that can be `connect` (the instance needs to connect to its master), `connecting` (the master-replica connection is in progress), `sync` (the master and replica are trying to perform the synchronization), `connected` (the replica is online).
5. The amount of data received from the replica so far in terms of master replication offset.

 Sentinel output
---------------

 An example of Sentinel output:

 
```
1) "sentinel"
2) 1) "resque-master"
   2) "html-fragments-master"
   3) "stats-master"
   4) "metadata-master"

```

The sentinel output is composed of the following parts:

 1. The string `sentinel`.
2. An array of master names monitored by this Sentinel instance.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): where the first element is one of `master`, `slave`, `sentinel` and the additional elements are role-specific as illustrated above.

 Examples
--------

 
```

ROLE

```
 **A note about the word slave used in this man page**: Starting with Redis 5, if not for backward compatibility, the Redis project no longer uses the word slave. Unfortunately in this command the word slave is part of the protocol, so we'll be able to remove such occurrences only when this API will be naturally deprecated.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/role/>

SETEX
=====



```
SETEX (deprecated)
```
  As of Redis version 2.6.12, this command is regarded as deprecated.

 It can be replaced by [`SET`](../set) with the `EX` argument when migrating or writing new code.

  Syntax 
```
SETEX key seconds value
```
  Available since: 2.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@slow`,   Set `key` to hold the string `value` and set `key` to timeout after a given number of seconds. This command is equivalent to:

 
```
SET key value EX seconds

```

An error is returned when `seconds` is invalid.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Examples
--------

 
```

SETEX mykey 10 "Hello"
TTL mykey
GET mykey

```
 See also
--------

 [`TTL`](../ttl)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/setex/>

RPUSHX
======



```
RPUSHX
```
 Syntax 
```
RPUSHX key element [element ...]
```
  Available since: 2.2.0 Time complexity: O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments. ACL categories:  `@write`, `@list`, `@fast`,   Inserts specified values at the tail of the list stored at `key`, only if `key` already exists and holds a list. In contrary to [`RPUSH`](../rpush), no operation will be performed when `key` does not yet exist.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the list after the push operation.

 Examples
--------

 
```

RPUSH mylist "Hello"
RPUSHX mylist "World"
RPUSHX myotherlist "World"
LRANGE mylist 0 -1
LRANGE myotherlist 0 -1

```
 History
-------

 * Starting with Redis version 4.0.0: Accepts multiple `element` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/rpushx/>

SET
===



```
SET
```
 Syntax 
```
SET key value [NX | XX] [GET] [EX seconds | PX milliseconds |
  EXAT unix-time-seconds | PXAT unix-time-milliseconds | KEEPTTL]
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@slow`,   Set `key` to hold the string `value`. If `key` already holds a value, it is overwritten, regardless of its type. Any previous time to live associated with the key is discarded on successful `SET` operation.

 Options
-------

 The `SET` command supports a set of options that modify its behavior:

 * `EX` *seconds* -- Set the specified expire time, in seconds.
* `PX` *milliseconds* -- Set the specified expire time, in milliseconds.
* `EXAT` *timestamp-seconds* -- Set the specified Unix time at which the key will expire, in seconds.
* `PXAT` *timestamp-milliseconds* -- Set the specified Unix time at which the key will expire, in milliseconds.
* `NX` -- Only set the key if it does not already exist.
* `XX` -- Only set the key if it already exist.
* `KEEPTTL` -- Retain the time to live associated with the key.
* `GET` -- Return the old string stored at key, or nil if key did not exist. An error is returned and `SET` aborted if the value stored at key is not a string.

 Note: Since the `SET` command options can replace [`SETNX`](../setnx), [`SETEX`](../setex), [`PSETEX`](../psetex), [`GETSET`](../getset), it is possible that in future versions of Redis these commands will be deprecated and finally removed.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if `SET` was executed correctly.

 [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): `(nil)` if the `SET` operation was not performed because the user specified the `NX` or `XX` option but the condition was not met.

 If the command is issued with the `GET` option, the above does not apply. It will instead reply as follows, regardless if the `SET` was actually performed:

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the old string value stored at key.

 [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): `(nil)` if the key did not exist.

 Examples
--------

 
```

SET mykey "Hello"
GET mykey
SET anotherkey "will expire in a minute" EX 60



```
 Patterns
--------

 **Note:** The following pattern is discouraged in favor of [the Redlock algorithm](https://redis.io/topics/distlock) which is only a bit more complex to implement, but offers better guarantees and is fault tolerant.

 The command `SET resource-name anystring NX EX max-lock-time` is a simple way to implement a locking system with Redis.

 A client can acquire the lock if the above command returns `OK` (or retry after some time if the command returns Nil), and remove the lock just using [`DEL`](../del).

 The lock will be auto-released after the expire time is reached.

 It is possible to make this system more robust modifying the unlock schema as follows:

 * Instead of setting a fixed string, set a non-guessable large random string, called token.
* Instead of releasing the lock with [`DEL`](../del), send a script that only removes the key if the value matches.

 This avoids that a client will try to release the lock after the expire time deleting the key created by another client that acquired the lock later.

 An example of unlock script would be similar to the following:

 
```
if redis.call("get",KEYS[1]) == ARGV[1]
then
    return redis.call("del",KEYS[1])
else
    return 0
end

```
 The script should be called with `EVAL ...script... 1 resource-name token-value`

 History
-------

 * Starting with Redis version 2.6.12: Added the `EX`, `PX`, `NX` and `XX` options.
* Starting with Redis version 6.0.0: Added the `KEEPTTL` option.
* Starting with Redis version 6.2.0: Added the `GET`, `EXAT` and `PXAT` option.
* Starting with Redis version 7.0.0: Allowed the `NX` and `GET` options to be used together.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/set/>

SCRIPT
======



```
SCRIPT KILL
```
 Syntax 
```
SCRIPT KILL
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@slow`, `@scripting`,   Kills the currently executing [`EVAL`](../eval) script, assuming no write operation was yet performed by the script.

 This command is mainly useful to kill a script that is running for too much time(for instance, because it entered an infinite loop because of a bug). The script will be killed, and the client currently blocked into EVAL will see the command returning with an error.

 If the script has already performed write operations, it can not be killed in this way because it would violate Lua's script atomicity contract. In such a case, only `SHUTDOWN NOSAVE` can kill the script, killing the Redis process in a hard way and preventing it from persisting with half-written information.

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/script-kill/>

SADD
====



```
SADD
```
 Syntax 
```
SADD key member [member ...]
```
  Available since: 1.0.0 Time complexity: O(1) for each element added, so O(N) to add N elements when the command is called with multiple arguments. ACL categories:  `@write`, `@set`, `@fast`,   Add the specified members to the set stored at `key`. Specified members that are already a member of this set are ignored. If `key` does not exist, a new set is created before adding the specified members.

 An error is returned when the value stored at `key` is not a set.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements that were added to the set, not including all the elements already present in the set.

 Examples
--------

 
```

SADD myset "Hello"
SADD myset "World"
SADD myset "World"
SMEMBERS myset

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple `member` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sadd/>

SETRANGE
========



```
SETRANGE
```
 Syntax 
```
SETRANGE key offset value
```
  Available since: 2.2.0 Time complexity: O(1), not counting the time taken to copy the new string in place. Usually, this string is very small so the amortized complexity is O(1). Otherwise, complexity is O(M) with M being the length of the value argument. ACL categories:  `@write`, `@string`, `@slow`,   Overwrites part of the string stored at *key*, starting at the specified offset, for the entire length of *value*. If the offset is larger than the current length of the string at *key*, the string is padded with zero-bytes to make *offset* fit. Non-existing keys are considered as empty strings, so this command will make sure it holds a string large enough to be able to set *value* at *offset*.

 Note that the maximum offset that you can set is 2^29 -1 (536870911), as Redis Strings are limited to 512 megabytes. If you need to grow beyond this size, you can use multiple keys.

 **Warning**: When setting the last possible byte and the string value stored at *key* does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time. On a 2010 MacBook Pro, setting byte number 536870911 (512MB allocation) takes ~300ms, setting byte number 134217728 (128MB allocation) takes ~80ms, setting bit number 33554432 (32MB allocation) takes ~30ms and setting bit number 8388608 (8MB allocation) takes ~8ms. Note that once this first allocation is done, subsequent calls to `SETRANGE` for the same *key* will not have the allocation overhead.

 Patterns
--------

 Thanks to `SETRANGE` and the analogous [`GETRANGE`](../getrange) commands, you can use Redis strings as a linear array with O(1) random access. This is a very fast and efficient storage in many real world use cases.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the string after it was modified by the command.

 Examples
--------

 Basic usage:

 
```

SET key1 "Hello World"
SETRANGE key1 6 "Redis"
GET key1

```
 Example of zero padding:

 
```

SETRANGE key2 6 "Redis"
GET key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/setrange/>

SCARD
=====



```
SCARD
```
 Syntax 
```
SCARD key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@read`, `@set`, `@fast`,   Returns the set cardinality (number of elements) of the set stored at `key`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the cardinality (number of elements) of the set, or `0` if `key` does not exist.

 Examples
--------

 
```

SADD myset "Hello"
SADD myset "World"
SCARD myset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/scard/>

SCRIPT
======



```
SCRIPT DEBUG
```
 Syntax 
```
SCRIPT DEBUG <YES | SYNC | NO>
```
  Available since: 3.2.0 Time complexity: O(1) ACL categories:  `@slow`, `@scripting`,   Set the debug mode for subsequent scripts executed with [`EVAL`](../eval). Redis includes a complete Lua debugger, codename LDB, that can be used to make the task of writing complex scripts much simpler. In debug mode Redis acts as a remote debugging server and a client, such as `redis-cli`, can execute scripts step by step, set breakpoints, inspect variables and more - for additional information about LDB refer to the [Redis Lua debugger](https://redis.io/topics/ldb) page.

 **Important note:** avoid debugging Lua scripts using your Redis production server. Use a development server instead.

 LDB can be enabled in one of two modes: asynchronous or synchronous. In asynchronous mode the server creates a forked debugging session that does not block and all changes to the data are **rolled back** after the session finishes, so debugging can be restarted using the same initial state. The alternative synchronous debug mode blocks the server while the debugging session is active and retains all changes to the data set once it ends.

 * `YES`. Enable non-blocking asynchronous debugging of Lua scripts (changes are discarded).
* `SYNC`. Enable blocking synchronous debugging of Lua scripts (saves changes to data).
* `NO`. Disables scripts debug mode.

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/script-debug/>

SELECT
======



```
SELECT
```
 Syntax 
```
SELECT index
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@fast`, `@connection`,   Select the Redis logical database having the specified zero-based numeric index. New connections always use the database 0.

 Selectable Redis databases are a form of namespacing: all databases are still persisted in the same RDB / AOF file. However different databases can have keys with the same name, and commands like [`FLUSHDB`](../flushdb), [`SWAPDB`](../swapdb) or [`RANDOMKEY`](../randomkey) work on specific databases.

 In practical terms, Redis databases should be used to separate different keys belonging to the same application (if needed), and not to use a single Redis instance for multiple unrelated applications.

 When using Redis Cluster, the `SELECT` command cannot be used, since Redis Cluster only supports database zero. In the case of a Redis Cluster, having multiple databases would be useless and an unnecessary source of complexity. Commands operating atomically on a single database would not be possible with the Redis Cluster design and goals.

 Since the currently selected database is a property of the connection, clients should track the currently selected database and re-select it on reconnection. While there is no command in order to query the selected database in the current connection, the [`CLIENT LIST`](../client-list) output shows, for each client, the currently selected database.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/select/>

SCRIPT
======



```
SCRIPT FLUSH
```
 Syntax 
```
SCRIPT FLUSH [ASYNC | SYNC]
```
  Available since: 2.6.0 Time complexity: O(N) with N being the number of scripts in cache ACL categories:  `@slow`, `@scripting`,   Flush the Lua scripts cache.

 By default, `SCRIPT FLUSH` will synchronously flush the cache. Starting with Redis 6.2, setting the **lazyfree-lazy-user-flush** configuration directive to "yes" changes the default flush mode to asynchronous.

 It is possible to use one of the following modifiers to dictate the flushing mode explicitly:

 * `ASYNC`: flushes the cache asynchronously
* `SYNC`: flushes the cache synchronously

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)

 Behavior change history
-----------------------

 * `>= 6.2.0`: Default flush behavior now configurable by the **lazyfree-lazy-user-flush** configuration directive.

 History
-------

 * Starting with Redis version 6.2.0: Added the `ASYNC` and `SYNC` flushing mode modifiers.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/script-flush/>

SCRIPT
======



```
SCRIPT EXISTS
```
 Syntax 
```
SCRIPT EXISTS sha1 [sha1 ...]
```
  Available since: 2.6.0 Time complexity: O(N) with N being the number of scripts to check (so checking a single script is an O(1) operation). ACL categories:  `@slow`, `@scripting`,   Returns information about the existence of the scripts in the script cache.

 This command accepts one or more SHA1 digests and returns a list of ones or zeros to signal if the scripts are already defined or not inside the script cache. This can be useful before a pipelining operation to ensure that scripts are loaded (and if not, to load them using [`SCRIPT LOAD`](../script-load)) so that the pipelining operation can be performed solely using [`EVALSHA`](../evalsha) instead of [`EVAL`](../eval) to save bandwidth.

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) The command returns an array of integers that correspond to the specified SHA1 digest arguments. For every corresponding SHA1 digest of a script that actually exists in the script cache, a 1 is returned, otherwise 0 is returned.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/script-exists/>

SISMEMBER
=========



```
SISMEMBER
```
 Syntax 
```
SISMEMBER key member
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@read`, `@set`, `@fast`,   Returns if `member` is a member of the set stored at `key`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the element is a member of the set.
* `0` if the element is not a member of the set, or if `key` does not exist.

 Examples
--------

 
```

SADD myset "one"
SISMEMBER myset "one"
SISMEMBER myset "two"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sismember/>

SDIFFSTORE
==========



```
SDIFFSTORE
```
 Syntax 
```
SDIFFSTORE destination key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of elements in all given sets. ACL categories:  `@write`, `@set`, `@slow`,   This command is equal to [`SDIFF`](../sdiff), but instead of returning the resulting set, it is stored in `destination`.

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SDIFFSTORE key key1 key2
SMEMBERS key

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sdiffstore/>

SETBIT
======



```
SETBIT
```
 Syntax 
```
SETBIT key offset value
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@write`, `@bitmap`, `@slow`,   Sets or clears the bit at *offset* in the string value stored at *key*.

 The bit is either set or cleared depending on *value*, which can be either 0 or 1.

 When *key* does not exist, a new string value is created. The string is grown to make sure it can hold a bit at *offset*. The *offset* argument is required to be greater than or equal to 0, and smaller than 2^32 (this limits bitmaps to 512MB). When the string at *key* is grown, added bits are set to 0.

 **Warning**: When setting the last possible bit (*offset* equal to 2^32 -1) and the string value stored at *key* does not yet hold a string value, or holds a small string value, Redis needs to allocate all intermediate memory which can block the server for some time. On a 2010 MacBook Pro, setting bit number 2^32 -1 (512MB allocation) takes ~300ms, setting bit number 2^30 -1 (128MB allocation) takes ~80ms, setting bit number 2^28 -1 (32MB allocation) takes ~30ms and setting bit number 2^26 -1 (8MB allocation) takes ~8ms. Note that once this first allocation is done, subsequent calls to `SETBIT` for the same *key* will not have the allocation overhead.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the original bit value stored at *offset*.

 Examples
--------

 
```

SETBIT mykey 7 1
SETBIT mykey 7 0
GET mykey

```
 Pattern: accessing the entire bitmap
------------------------------------

 There are cases when you need to set all the bits of single bitmap at once, for example when initializing it to a default non-zero value. It is possible to do this with multiple calls to the `SETBIT` command, one for each bit that needs to be set. However, so as an optimization you can use a single [`SET`](../set) command to set the entire bitmap.

 Bitmaps are not an actual data type, but a set of bit-oriented operations defined on the String type (for more information refer to the [Bitmaps section of the Data Types Introduction page](https://redis.io/topics/data-types-intro#bitmaps)). This means that bitmaps can be used with string commands, and most importantly with [`SET`](../set) and [`GET`](../get).

 Because Redis' strings are binary-safe, a bitmap is trivially encoded as a bytes stream. The first byte of the string corresponds to offsets 0..7 of the bitmap, the second byte to the 8..15 range, and so forth.

 For example, after setting a few bits, getting the string value of the bitmap would look like this:

 
```
> SETBIT bitmapsarestrings 2 1
> SETBIT bitmapsarestrings 3 1
> SETBIT bitmapsarestrings 5 1
> SETBIT bitmapsarestrings 10 1
> SETBIT bitmapsarestrings 11 1
> SETBIT bitmapsarestrings 14 1
> GET bitmapsarestrings
"42"

```

By getting the string representation of a bitmap, the client can then parse the response's bytes by extracting the bit values using native bit operations in its native programming language. Symmetrically, it is also possible to set an entire bitmap by performing the bits-to-bytes encoding in the client and calling [`SET`](../set) with the resultant string.

 Pattern: setting multiple bits
------------------------------

 `SETBIT` excels at setting single bits, and can be called several times when multiple bits need to be set. To optimize this operation you can replace multiple `SETBIT` calls with a single call to the variadic [`BITFIELD`](../bitfield) command and the use of fields of type `u1`.

 For example, the example above could be replaced by:

 
```
> BITFIELD bitsinabitmap SET u1 2 1 SET u1 3 1 SET u1 5 1 SET u1 10 1 SET u1 11 1 SET u1 14 1

```

Advanced Pattern: accessing bitmap ranges
-----------------------------------------

 It is also possible to use the [`GETRANGE`](../getrange) and [`SETRANGE`](../setrange) string commands to efficiently access a range of bit offsets in a bitmap. Below is a sample implementation in idiomatic Redis Lua scripting that can be run with the [`EVAL`](../eval) command:

 
```
--[[
Sets a bitmap range

Bitmaps are stored as Strings in Redis. A range spans one or more bytes,
so we can call [`SETRANGE`](/commands/setrange) when entire bytes need to be set instead of flipping
individual bits. Also, to avoid multiple internal memory allocations in
Redis, we traverse in reverse.
Expected input:
  KEYS[1] - bitfield key
  ARGV[1] - start offset (0-based, inclusive)
  ARGV[2] - end offset (same, should be bigger than start, no error checking)
  ARGV[3] - value (should be 0 or 1, no error checking)
]]--

-- A helper function to stringify a binary string to semi-binary format
local function tobits(str)
  local r = ''
  for i = 1, string.len(str) do
    local c = string.byte(str, i)
    local b = ' '
    for j = 0, 7 do
      b = tostring(bit.band(c, 1)) .. b
      c = bit.rshift(c, 1)
    end
    r = r .. b
  end
  return r
end

-- Main
local k = KEYS[1]
local s, e, v = tonumber(ARGV[1]), tonumber(ARGV[2]), tonumber(ARGV[3])

-- First treat the dangling bits in the last byte
local ms, me = s % 8, (e + 1) % 8
if me > 0 then
  local t = math.max(e - me + 1, s)
  for i = e, t, -1 do
    redis.call('SETBIT', k, i, v)
  end
  e = t
end

-- Then the danglings in the first byte
if ms > 0 then
  local t = math.min(s - ms + 7, e)
  for i = s, t, 1 do
    redis.call('SETBIT', k, i, v)
  end
  s = t + 1
end

-- Set a range accordingly, if at all
local rs, re = s / 8, (e + 1) / 8
local rl = re - rs
if rl > 0 then
  local b = '\255'
  if 0 == v then
    b = '\0'
  end
  redis.call('SETRANGE', k, rs, string.rep(b, rl))
end

```

**Note:** the implementation for getting a range of bit offsets from a bitmap is left as an exercise to the reader.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/setbit/>

SINTER
======



```
SINTER
```
 Syntax 
```
SINTER key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N\*M) worst case where N is the cardinality of the smallest set and M is the number of sets. ACL categories:  `@read`, `@set`, `@slow`,   Returns the members of the set resulting from the intersection of all the given sets.

 For example:

 
```
key1 = {a,b,c,d}
key2 = {c}
key3 = {a,c,e}
SINTER key1 key2 key3 = {c}

```

Keys that do not exist are considered to be empty sets. With one of the keys being an empty set, the resulting set is also empty (since set intersection with an empty set always results in an empty set).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list with members of the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SINTER key1 key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sinter/>

SINTERSTORE
===========



```
SINTERSTORE
```
 Syntax 
```
SINTERSTORE destination key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N\*M) worst case where N is the cardinality of the smallest set and M is the number of sets. ACL categories:  `@write`, `@set`, `@slow`,   This command is equal to [`SINTER`](../sinter), but instead of returning the resulting set, it is stored in `destination`.

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SINTERSTORE key key1 key2
SMEMBERS key

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sinterstore/>

SETNX
=====



```
SETNX (deprecated)
```
  As of Redis version 2.6.12, this command is regarded as deprecated.

 It can be replaced by [`SET`](../set) with the `NX` argument when migrating or writing new code.

  Syntax 
```
SETNX key value
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@string`, `@fast`,   Set `key` to hold string `value` if `key` does not exist. In that case, it is equal to [`SET`](../set). When `key` already holds a value, no operation is performed. `SETNX` is short for "**SET** if **N**ot e**X**ists".

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the key was set
* `0` if the key was not set

 Examples
--------

 
```

SETNX mykey "Hello"
SETNX mykey "World"
GET mykey

```
 Design pattern: Locking with `SETNX`
------------------------------------

 **Please note that:**

 1. The following pattern is discouraged in favor of [the Redlock algorithm](https://redis.io/topics/distlock) which is only a bit more complex to implement, but offers better guarantees and is fault tolerant.
2. We document the old pattern anyway because certain existing implementations link to this page as a reference. Moreover it is an interesting example of how Redis commands can be used in order to mount programming primitives.
3. Anyway even assuming a single-instance locking primitive, starting with 2.6.12 it is possible to create a much simpler locking primitive, equivalent to the one discussed here, using the [`SET`](../set) command to acquire the lock, and a simple Lua script to release the lock. The pattern is documented in the [`SET`](../set) command page.

 That said, `SETNX` can be used, and was historically used, as a locking primitive. For example, to acquire the lock of the key `foo`, the client could try the following:

 
```
SETNX lock.foo <current Unix time + lock timeout + 1>

```

If `SETNX` returns `1` the client acquired the lock, setting the `lock.foo` key to the Unix time at which the lock should no longer be considered valid. The client will later use `DEL lock.foo` in order to release the lock.

 If `SETNX` returns `0` the key is already locked by some other client. We can either return to the caller if it's a non blocking lock, or enter a loop retrying to hold the lock until we succeed or some kind of timeout expires.

 ### Handling deadlocks

 In the above locking algorithm there is a problem: what happens if a client fails, crashes, or is otherwise not able to release the lock? It's possible to detect this condition because the lock key contains a UNIX timestamp. If such a timestamp is equal to the current Unix time the lock is no longer valid.

 When this happens we can't just call [`DEL`](../del) against the key to remove the lock and then try to issue a `SETNX`, as there is a race condition here, when multiple clients detected an expired lock and are trying to release it.

 * C1 and C2 read `lock.foo` to check the timestamp, because they both received `0` after executing `SETNX`, as the lock is still held by C3 that crashed after holding the lock.
* C1 sends `DEL lock.foo`
* C1 sends `SETNX lock.foo` and it succeeds
* C2 sends `DEL lock.foo`
* C2 sends `SETNX lock.foo` and it succeeds
* **ERROR**: both C1 and C2 acquired the lock because of the race condition.

 Fortunately, it's possible to avoid this issue using the following algorithm. Let's see how C4, our sane client, uses the good algorithm:

 * C4 sends `SETNX lock.foo` in order to acquire the lock
* The crashed client C3 still holds it, so Redis will reply with `0` to C4.
* C4 sends `GET lock.foo` to check if the lock expired. If it is not, it will sleep for some time and retry from the start.
* Instead, if the lock is expired because the Unix time at `lock.foo` is older than the current Unix time, C4 tries to perform:

 
```
GETSET lock.foo <current Unix timestamp + lock timeout + 1>

```
* Because of the [`GETSET`](../getset) semantic, C4 can check if the old value stored at `key` is still an expired timestamp. If it is, the lock was acquired.
* If another client, for instance C5, was faster than C4 and acquired the lock with the [`GETSET`](../getset) operation, the C4 [`GETSET`](../getset) operation will return a non expired timestamp. C4 will simply restart from the first step. Note that even if C4 set the key a bit a few seconds in the future this is not a problem.

 In order to make this locking algorithm more robust, a client holding a lock should always check the timeout didn't expire before unlocking the key with [`DEL`](../del) because client failures can be complex, not just crashing but also blocking a lot of time against some operations and trying to issue [`DEL`](../del) after a lot of time (when the LOCK is already held by another client).



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/setnx/>

SINTERCARD
==========



```
SINTERCARD
```
 Syntax 
```
SINTERCARD numkeys key [key ...] [LIMIT limit]
```
  Available since: 7.0.0 Time complexity: O(N\*M) worst case where N is the cardinality of the smallest set and M is the number of sets. ACL categories:  `@read`, `@set`, `@slow`,   This command is similar to [`SINTER`](../sinter), but instead of returning the result set, it returns just the cardinality of the result. Returns the cardinality of the set which would result from the intersection of all the given sets.

 Keys that do not exist are considered to be empty sets. With one of the keys being an empty set, the resulting set is also empty (since set intersection with an empty set always results in an empty set).

 By default, the command calculates the cardinality of the intersection of all given sets. When provided with the optional `LIMIT` argument (which defaults to 0 and means unlimited), if the intersection cardinality reaches limit partway through the computation, the algorithm will exit and yield limit as the cardinality. Such implementation ensures a significant speedup for queries where the limit is lower than the actual intersection cardinality.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting intersection.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key1 "d"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SINTER key1 key2
SINTERCARD 2 key1 key2
SINTERCARD 2 key1 key2 LIMIT 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sintercard/>

SCRIPT
======



```
SCRIPT LOAD
```
 Syntax 
```
SCRIPT LOAD script
```
  Available since: 2.6.0 Time complexity: O(N) with N being the length in bytes of the script body. ACL categories:  `@slow`, `@scripting`,   Load a script into the scripts cache, without executing it. After the specified command is loaded into the script cache it will be callable using [`EVALSHA`](../evalsha) with the correct SHA1 digest of the script, exactly like after the first successful invocation of [`EVAL`](../eval).

 The script is guaranteed to stay in the script cache forever (unless `SCRIPT FLUSH` is called).

 The command works in the same way even if the script was already present in the script cache.

 For more information about [`EVAL`](../eval) scripts please refer to [Introduction to Eval Scripts](https://redis.io/topics/eval-intro).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) This command returns the SHA1 digest of the script added into the script cache.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/script-load/>

SLOWLOG
=======



```
SLOWLOG GET
```
 Syntax 
```
SLOWLOG GET [count]
```
  Available since: 2.2.12 Time complexity: O(N) where N is the number of entries returned ACL categories:  `@admin`, `@slow`, `@dangerous`,   The `SLOWLOG GET` command returns entries from the slow log in chronological order.

 The Redis Slow Log is a system to log queries that exceeded a specified execution time. The execution time does not include I/O operations like talking with the client, sending the reply and so forth, but just the time needed to actually execute the command (this is the only stage of command execution where the thread is blocked and can not serve other requests in the meantime).

 A new entry is added to the slow log whenever a command exceeds the execution time threshold defined by the `slowlog-log-slower-than` configuration directive. The maximum number of entries in the slow log is governed by the `slowlog-max-len` configuration directive.

 By default the command returns latest ten entries in the log. The optional `count` argument limits the number of returned entries, so the command returns at most up to `count` entries, the special number -1 means return all entries.

 Each entry from the slow log is comprised of the following six values:

 1. A unique progressive identifier for every slow log entry.
2. The unix timestamp at which the logged command was processed.
3. The amount of time needed for its execution, in microseconds.
4. The array composing the arguments of the command.
5. Client IP address and port.
6. Client name if set via the [`CLIENT SETNAME`](../client-setname) command.

 The entry's unique ID can be used in order to avoid processing slow log entries multiple times (for instance you may have a script sending you an email alert for every new slow log entry). The ID is never reset in the course of the Redis server execution, only a server restart will reset it.

 @reply

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of slow log entries.

 History
-------

 * Starting with Redis version 4.0.0: Added client IP address, port and name to the reply.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/slowlog-get/>

SDIFF
=====



```
SDIFF
```
 Syntax 
```
SDIFF key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of elements in all given sets. ACL categories:  `@read`, `@set`, `@slow`,   Returns the members of the set resulting from the difference between the first set and all the successive sets.

 For example:

 
```
key1 = {a,b,c,d}
key2 = {c}
key3 = {a,c,e}
SDIFF key1 key2 key3 = {b,d}

```

Keys that do not exist are considered to be empty sets.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list with members of the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SDIFF key1 key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sdiff/>

SLAVEOF
=======



```
SLAVEOF (deprecated)
```
  As of Redis version 5.0.0, this command is regarded as deprecated.

 It can be replaced by [`REPLICAOF`](../replicaof) when migrating or writing new code.

  Syntax 
```
SLAVEOF host port
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   **A note about the word slave used in this man page and command name**: starting with Redis version 5, if not for backward compatibility, the Redis project no longer uses the word slave. Please use the new command [`REPLICAOF`](../replicaof). The command `SLAVEOF` will continue to work for backward compatibility.

 The `SLAVEOF` command can change the replication settings of a replica on the fly. If a Redis server is already acting as replica, the command `SLAVEOF` NO ONE will turn off the replication, turning the Redis server into a MASTER. In the proper form `SLAVEOF` hostname port will make the server a replica of another server listening at the specified hostname and port.

 If a server is already a replica of some master, `SLAVEOF` hostname port will stop the replication against the old server and start the synchronization against the new one, discarding the old dataset.

 The form `SLAVEOF` NO ONE will stop replication, turning the server into a MASTER, but will not discard the replication. So, if the old master stops working, it is possible to turn the replica into a master and set the application to use this new master in read/write. Later when the other Redis server is fixed, it can be reconfigured to work as a replica.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/slaveof/>

SLOWLOG
=======



```
SLOWLOG LEN
```
 Syntax 
```
SLOWLOG LEN
```
  Available since: 2.2.12 Time complexity: O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command returns the current number of entries in the slow log.

 A new entry is added to the slow log whenever a command exceeds the execution time threshold defined by the `slowlog-log-slower-than` configuration directive. The maximum number of entries in the slow log is governed by the `slowlog-max-len` configuration directive. Once the slog log reaches its maximal size, the oldest entry is removed whenever a new entry is created. The slow log can be cleared with the [`SLOWLOG RESET`](../slowlog-reset) command.

 @reply

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers)

 The number of entries in the slow log.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/slowlog-len/>

SMEMBERS
========



```
SMEMBERS
```
 Syntax 
```
SMEMBERS key
```
  Available since: 1.0.0 Time complexity: O(N) where N is the set cardinality. ACL categories:  `@read`, `@set`, `@slow`,   Returns all the members of the set value stored at `key`.

 This has the same effect as running [`SINTER`](../sinter) with one argument `key`.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): all elements of the set.

 Examples
--------

 
```

SADD myset "Hello"
SADD myset "World"
SMEMBERS myset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/smembers/>

SLOWLOG
=======



```
SLOWLOG RESET
```
 Syntax 
```
SLOWLOG RESET
```
  Available since: 2.2.12 Time complexity: O(N) where N is the number of entries in the slowlog ACL categories:  `@admin`, `@slow`, `@dangerous`,   This command resets the slow log, clearing all entries in it.

 Once deleted the information is lost forever.

 @reply

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK`



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/slowlog-reset/>

SPOP
====



```
SPOP
```
 Syntax 
```
SPOP key [count]
```
  Available since: 1.0.0 Time complexity: Without the count argument O(1), otherwise O(N) where N is the value of the passed count. ACL categories:  `@write`, `@set`, `@fast`,   Removes and returns one or more random members from the set value store at `key`.

 This operation is similar to [`SRANDMEMBER`](../srandmember), that returns one or more random elements from a set but does not remove it.

 By default, the command pops a single member from the set. When provided with the optional `count` argument, the reply will consist of up to `count` members, depending on the set's cardinality.

 Return
------

 When called without the `count` argument:

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the removed member, or `nil` when `key` does not exist.

 When called with the `count` argument:

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): the removed members, or an empty array when `key` does not exist.

 Examples
--------

 
```

SADD myset "one"
SADD myset "two"
SADD myset "three"
SPOP myset
SMEMBERS myset
SADD myset "four"
SADD myset "five"
SPOP myset 3
SMEMBERS myset

```
 Distribution of returned elements
---------------------------------

 Note that this command is not suitable when you need a guaranteed uniform distribution of the returned elements. For more information about the algorithms used for `SPOP`, look up both the Knuth sampling and Floyd sampling algorithms.

 History
-------

 * Starting with Redis version 3.2.0: Added the `count` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/spop/>

SHUTDOWN
========



```
SHUTDOWN
```
 Syntax 
```
SHUTDOWN [NOSAVE | SAVE] [NOW] [FORCE] [ABORT]
```
  Available since: 1.0.0 Time complexity: O(N) when saving, where N is the total number of keys in all databases when saving data, otherwise O(1) ACL categories:  `@admin`, `@slow`, `@dangerous`,   The command behavior is the following:

 * If there are any replicas lagging behind in replication:
	+ Pause clients attempting to write by performing a [`CLIENT PAUSE`](../client-pause) with the `WRITE` option.
	+ Wait up to the configured `shutdown-timeout` (default 10 seconds) for replicas to catch up the replication offset.
* Stop all the clients.
* Perform a blocking SAVE if at least one **save point** is configured.
* Flush the Append Only File if AOF is enabled.
* Quit the server.

 If persistence is enabled this commands makes sure that Redis is switched off without any data loss.

 Note: A Redis instance that is configured for not persisting on disk (no AOF configured, nor "save" directive) will not dump the RDB file on `SHUTDOWN`, as usually you don't want Redis instances used only for caching to block on when shutting down.

 Also note: If Redis receives one of the signals `SIGTERM` and `SIGINT`, the same shutdown sequence is performed. See also [Signal Handling](https://redis.io/topics/signals).

 Modifiers
---------

 It is possible to specify optional modifiers to alter the behavior of the command. Specifically:

 * **SAVE** will force a DB saving operation even if no save points are configured.
* **NOSAVE** will prevent a DB saving operation even if one or more save points are configured.
* **NOW** skips waiting for lagging replicas, i.e. it bypasses the first step in the shutdown sequence.
* **FORCE** ignores any errors that would normally prevent the server from exiting. For details, see the following section.
* **ABORT** cancels an ongoing shutdown and cannot be combined with other flags.

 Conditions where a SHUTDOWN fails
---------------------------------

 When a save point is configured or the **SAVE** modifier is specified, the shutdown may fail if the RDB file can't be saved. Then, the server continues to run in order to ensure no data loss. This may be bypassed using the **FORCE** modifier, causing the server to exit anyway.

 When the Append Only File is enabled the shutdown may fail because the system is in a state that does not allow to safely immediately persist on disk.

 Normally if there is an AOF child process performing an AOF rewrite, Redis will simply kill it and exit. However, there are situations where it is unsafe to do so and, unless the **FORCE** modifier is specified, the **SHUTDOWN** command will be refused with an error instead. This happens in the following situations:

 * The user just turned on AOF, and the server triggered the first AOF rewrite in order to create the initial AOF file. In this context, stopping will result in losing the dataset at all: once restarted, the server will potentially have AOF enabled without having any AOF file at all.
* A replica with AOF enabled, reconnected with its master, performed a full resynchronization, and restarted the AOF file, triggering the initial AOF creation process. In this case not completing the AOF rewrite is dangerous because the latest dataset received from the master would be lost. The new master can actually be even a different instance (if the **REPLICAOF** or **SLAVEOF** command was used in order to reconfigure the replica), so it is important to finish the AOF rewrite and start with the correct data set representing the data set in memory when the server was terminated.

 There are situations when we want just to terminate a Redis instance ASAP, regardless of what its content is. In such a case, the command **SHUTDOWN NOW NOSAVE FORCE** can be used. In versions before 7.0, where the **NOW** and **FORCE** flags are not available, the right combination of commands is to send a **CONFIG appendonly no** followed by a **SHUTDOWN NOSAVE**. The first command will turn off the AOF if needed, and will terminate the AOF rewriting child if there is one active. The second command will not have any problem to execute since the AOF is no longer enabled.

 Minimize the risk of data loss
------------------------------

 Since Redis 7.0, the server waits for lagging replicas up to a configurable `shutdown-timeout`, by default 10 seconds, before shutting down. This provides a best effort minimizing the risk of data loss in a situation where no save points are configured and AOF is disabled. Before version 7.0, shutting down a heavily loaded master node in a diskless setup was more likely to result in data loss. To minimize the risk of data loss in such setups, it's advised to trigger a manual [`FAILOVER`](../failover) (or [`CLUSTER FAILOVER`](../cluster-failover)) to demote the master to a replica and promote one of the replicas to be the new master, before shutting down a master node.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if `ABORT` was specified and shutdown was aborted. On successful shutdown, nothing is returned since the server quits and the connection is closed. On failure, an error is returned.

 Behavior change history
-----------------------

 * `>= 7.0.0`: Introduced waiting for lagging replicas before exiting.

 History
-------

 * Starting with Redis version 7.0.0: Added the `NOW`, `FORCE` and `ABORT` modifiers.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/shutdown/>

SORT
====



```
SORT
```
 Syntax 
```
SORT key [BY pattern] [LIMIT offset count] [GET pattern [GET pattern
  ...]] [ASC | DESC] [ALPHA] [STORE destination]
```
  Available since: 1.0.0 Time complexity: O(N+M\*log(M)) where N is the number of elements in the list or set to sort, and M the number of returned elements. When the elements are not sorted, complexity is O(N). ACL categories:  `@write`, `@set`, `@sortedset`, `@list`, `@slow`, `@dangerous`,   Returns or stores the elements contained in the [list](https://redis.io/topics/data-types#lists), [set](https://redis.io/topics/data-types#set) or [sorted set](https://redis.io/topics/data-types#sorted-sets) at `key`.

 There is also the [`SORT_RO`](../sort_ro) read-only variant of this command.

 By default, sorting is numeric and elements are compared by their value interpreted as double precision floating point number. This is `SORT` in its simplest form:

 
```
SORT mylist

```

Assuming `mylist` is a list of numbers, this command will return the same list with the elements sorted from small to large. In order to sort the numbers from large to small, use the `DESC` modifier:

 
```
SORT mylist DESC

```

When `mylist` contains string values and you want to sort them lexicographically, use the `ALPHA` modifier:

 
```
SORT mylist ALPHA

```

Redis is UTF-8 aware, assuming you correctly set the `LC_COLLATE` environment variable.

 The number of returned elements can be limited using the `LIMIT` modifier. This modifier takes the `offset` argument, specifying the number of elements to skip and the `count` argument, specifying the number of elements to return from starting at `offset`. The following example will return 10 elements of the sorted version of `mylist`, starting at element 0 (`offset` is zero-based):

 
```
SORT mylist LIMIT 0 10

```

Almost all modifiers can be used together. The following example will return the first 5 elements, lexicographically sorted in descending order:

 
```
SORT mylist LIMIT 0 5 ALPHA DESC

```

Sorting by external keys
------------------------

 Sometimes you want to sort elements using external keys as weights to compare instead of comparing the actual elements in the list, set or sorted set. Let's say the list `mylist` contains the elements `1`, `2` and `3` representing unique IDs of objects stored in `object_1`, `object_2` and `object_3`. When these objects have associated weights stored in `weight_1`, `weight_2` and `weight_3`, `SORT` can be instructed to use these weights to sort `mylist` with the following statement:

 
```
SORT mylist BY weight_*

```

The `BY` option takes a pattern (equal to `weight_*` in this example) that is used to generate the keys that are used for sorting. These key names are obtained substituting the first occurrence of `*` with the actual value of the element in the list (`1`, `2` and `3` in this example).

 Skip sorting the elements
-------------------------

 The `BY` option can also take a non-existent key, which causes `SORT` to skip the sorting operation. This is useful if you want to retrieve external keys (see the `GET` option below) without the overhead of sorting.

 
```
SORT mylist BY nosort

```

Retrieving external keys
------------------------

 Our previous example returns just the sorted IDs. In some cases, it is more useful to get the actual objects instead of their IDs (`object_1`, `object_2` and `object_3`). Retrieving external keys based on the elements in a list, set or sorted set can be done with the following command:

 
```
SORT mylist BY weight_* GET object_*

```

The `GET` option can be used multiple times in order to get more keys for every element of the original list, set or sorted set.

 It is also possible to `GET` the element itself using the special pattern `#`:

 
```
SORT mylist BY weight_* GET object_* GET #

```

Restrictions for using external keys
------------------------------------

 When enabling `Redis cluster-mode` there is no way to guarantee the existence of the external keys on the node which the command is processed on. In this case, any use of [`GET`](../get) or `BY` which reference external key pattern will cause the command to fail with an error.

 Starting from Redis 7.0, any use of [`GET`](../get) or `BY` which reference external key pattern will only be allowed in case the current user running the command has full key read permissions. Full key read permissions can be set for the user by, for example, specifying `'%R~*'` or `'~*` with the relevant command access rules. You can check the [`ACL SETUSER`](../acl-setuser) command manual for more information on setting ACL access rules. If full key read permissions aren't set, the command will fail with an error.

 Storing the result of a SORT operation
--------------------------------------

 By default, `SORT` returns the sorted elements to the client. With the `STORE` option, the result will be stored as a list at the specified key instead of being returned to the client.

 
```
SORT mylist BY weight_* STORE resultkey

```

An interesting pattern using `SORT ... STORE` consists in associating an [`EXPIRE`](../expire) timeout to the resulting key so that in applications where the result of a `SORT` operation can be cached for some time. Other clients will use the cached list instead of calling `SORT` for every request. When the key will timeout, an updated version of the cache can be created by calling `SORT ... STORE` again.

 Note that for correctly implementing this pattern it is important to avoid multiple clients rebuilding the cache at the same time. Some kind of locking is needed here (for instance using [`SETNX`](../setnx)).

 Using hashes in `BY` and `GET`
------------------------------

 It is possible to use `BY` and `GET` options against hash fields with the following syntax:

 
```
SORT mylist BY weight_*->fieldname GET object_*->fieldname

```

The string `->` is used to separate the key name from the hash field name. The key is substituted as documented above, and the hash stored at the resulting key is accessed to retrieve the specified hash field.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): without passing the `store` option the command returns a list of sorted elements. [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): when the `store` option is specified the command returns the number of sorted elements in the destination list.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sort/>

SRANDMEMBER
===========



```
SRANDMEMBER
```
 Syntax 
```
SRANDMEMBER key [count]
```
  Available since: 1.0.0 Time complexity: Without the count argument O(1), otherwise O(N) where N is the absolute value of the passed count. ACL categories:  `@read`, `@set`, `@slow`,   When called with just the `key` argument, return a random element from the set value stored at `key`.

 If the provided `count` argument is positive, return an array of **distinct elements**. The array's length is either `count` or the set's cardinality ([`SCARD`](../scard)), whichever is lower.

 If called with a negative `count`, the behavior changes and the command is allowed to return the **same element multiple times**. In this case, the number of returned elements is the absolute value of the specified `count`.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): without the additional `count` argument, the command returns a Bulk Reply with the randomly selected element, or `nil` when `key` does not exist.

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): when the additional `count` argument is passed, the command returns an array of elements, or an empty array when `key` does not exist.

 Examples
--------

 
```

SADD myset one two three
SRANDMEMBER myset
SRANDMEMBER myset 2
SRANDMEMBER myset -5

```
 Specification of the behavior when count is passed
--------------------------------------------------

 When the `count` argument is a positive value this command behaves as follows:

 * No repeated elements are returned.
* If `count` is bigger than the set's cardinality, the command will only return the whole set without additional elements.
* The order of elements in the reply is not truly random, so it is up to the client to shuffle them if needed.

 When the `count` is a negative value, the behavior changes as follows:

 * Repeating elements are possible.
* Exactly `count` elements, or an empty array if the set is empty (non-existing key), are always returned.
* The order of elements in the reply is truly random.

 Distribution of returned elements
---------------------------------

 Note: this section is relevant only for Redis 5 or below, as Redis 6 implements a fairer algorithm.

 The distribution of the returned elements is far from perfect when the number of elements in the set is small, this is due to the fact that we used an approximated random element function that does not really guarantees good distribution.

 The algorithm used, that is implemented inside dict.c, samples the hash table buckets to find a non-empty one. Once a non empty bucket is found, since we use chaining in our hash table implementation, the number of elements inside the bucket is checked and a random element is selected.

 This means that if you have two non-empty buckets in the entire hash table, and one has three elements while one has just one, the element that is alone in its bucket will be returned with much higher probability.

 History
-------

 * Starting with Redis version 2.6.0: Added the optional `count` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/srandmember/>

SREM
====



```
SREM
```
 Syntax 
```
SREM key member [member ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the number of members to be removed. ACL categories:  `@write`, `@set`, `@fast`,   Remove the specified members from the set stored at `key`. Specified members that are not a member of this set are ignored. If `key` does not exist, it is treated as an empty set and this command returns `0`.

 An error is returned when the value stored at `key` is not a set.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of members that were removed from the set, not including non existing members.

 Examples
--------

 
```

SADD myset "one"
SADD myset "two"
SADD myset "three"
SREM myset "one"
SREM myset "four"
SMEMBERS myset

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple `member` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/srem/>

SMISMEMBER
==========



```
SMISMEMBER
```
 Syntax 
```
SMISMEMBER key member [member ...]
```
  Available since: 6.2.0 Time complexity: O(N) where N is the number of elements being checked for membership ACL categories:  `@read`, `@set`, `@fast`,   Returns whether each `member` is a member of the set stored at `key`.

 For every `member`, `1` is returned if the value is a member of the set, or `0` if the element is not a member of the set or if `key` does not exist.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list representing the membership of the given elements, in the same order as they are requested.

 Examples
--------

 
```

SADD myset "one"
SADD myset "one"
SMISMEMBER myset "one" "notamember"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/smismember/>

SPUBLISH
========



```
SPUBLISH
```
 Syntax 
```
SPUBLISH shardchannel message
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of clients subscribed to the receiving shard channel. ACL categories:  `@pubsub`, `@fast`,   Posts a message to the given shard channel.

 In Redis Cluster, shard channels are assigned to slots by the same algorithm used to assign keys to slots. A shard message must be sent to a node that own the slot the shard channel is hashed to. The cluster makes sure that published shard messages are forwarded to all the node in the shard, so clients can subscribe to a shard channel by connecting to any one of the nodes in the shard.

 For more information about sharded pubsub, see [Sharded Pubsub](https://redis.io/topics/pubsub#sharded-pubsub).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of clients that received the message. Note that in a Redis Cluster, only clients that are connected to the same node as the publishing client are included in the count.

 Examples
--------

 For example the following command publish to channel `orders` with a subscriber already waiting for message(s).

 
```
> spublish orders hello
(integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/spublish/>

SMOVE
=====



```
SMOVE
```
 Syntax 
```
SMOVE source destination member
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@write`, `@set`, `@fast`,   Move `member` from the set at `source` to the set at `destination`. This operation is atomic. In every given moment the element will appear to be a member of `source` **or** `destination` for other clients.

 If the source set does not exist or does not contain the specified element, no operation is performed and `0` is returned. Otherwise, the element is removed from the source set and added to the destination set. When the specified element already exists in the destination set, it is only removed from the source set.

 An error is returned if `source` or `destination` does not hold a set value.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * `1` if the element is moved.
* `0` if the element is not a member of `source` and no operation was performed.

 Examples
--------

 
```

SADD myset "one"
SADD myset "two"
SADD myotherset "three"
SMOVE myset myotherset "two"
SMEMBERS myset
SMEMBERS myotherset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/smove/>

SORT\_RO
========



```
SORT_RO
```
 Syntax 
```
SORT_RO key [BY pattern] [LIMIT offset count] [GET pattern [GET
  pattern ...]] [ASC | DESC] [ALPHA]
```
  Available since: 7.0.0 Time complexity: O(N+M\*log(M)) where N is the number of elements in the list or set to sort, and M the number of returned elements. When the elements are not sorted, complexity is O(N). ACL categories:  `@read`, `@set`, `@sortedset`, `@list`, `@slow`, `@dangerous`,   Read-only variant of the [`SORT`](../sort) command. It is exactly like the original [`SORT`](../sort) but refuses the `STORE` option and can safely be used in read-only replicas.

 Since the original [`SORT`](../sort) has a `STORE` option it is technically flagged as a writing command in the Redis command table. For this reason read-only replicas in a Redis Cluster will redirect it to the master instance even if the connection is in read-only mode (see the [`READONLY`](../readonly) command of Redis Cluster).

 The `SORT_RO` variant was introduced in order to allow [`SORT`](../sort) behavior in read-only replicas without breaking compatibility on command flags.

 See original [`SORT`](../sort) for more details.

 Examples
--------

 
```
SORT_RO mylist BY weight_*->fieldname GET object_*->fieldname

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of sorted elements.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sort_ro/>

SSCAN
=====



```
SSCAN
```
 Syntax 
```
SSCAN key cursor [MATCH pattern] [COUNT count]
```
  Available since: 2.8.0 Time complexity: O(1) for every call. O(N) for a complete iteration, including enough command calls for the cursor to return back to 0. N is the number of elements inside the collection. ACL categories:  `@read`, `@set`, `@slow`,   See [`SCAN`](../scan) for `SSCAN` documentation.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sscan/>

SSUBSCRIBE
==========



```
SSUBSCRIBE
```
 Syntax 
```
SSUBSCRIBE shardchannel [shardchannel ...]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of shard channels to subscribe to. ACL categories:  `@pubsub`, `@slow`,   Subscribes the client to the specified shard channels.

 In a Redis cluster, shard channels are assigned to slots by the same algorithm used to assign keys to slots. Client(s) can subscribe to a node covering a slot (primary/replica) to receive the messages published. All the specified shard channels needs to belong to a single slot to subscribe in a given `SSUBSCRIBE` call, A client can subscribe to channels across different slots over separate `SSUBSCRIBE` call.

 For more information about sharded Pub/Sub, see [Sharded Pub/Sub](https://redis.io/topics/pubsub#sharded-pubsub).

 Return
------

 When successful, this command doesn't return anything. Instead, for each shard channel, one message with the first element being the string "ssubscribe" is pushed as a confirmation that the command succeeded. Note that this command can also return a -MOVED redirect.

 Examples
--------

 
```
> ssubscribe orders
Reading messages... (press Ctrl-C to quit)
1) "ssubscribe"
2) "orders"
3) (integer) 1
1) "smessage"
2) "orders"
3) "hello"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ssubscribe/>

SWAPDB
======



```
SWAPDB
```
 Syntax 
```
SWAPDB index1 index2
```
  Available since: 4.0.0 Time complexity: O(N) where N is the count of clients watching or blocking on keys from both databases. ACL categories:  `@keyspace`, `@write`, `@fast`, `@dangerous`,   This command swaps two Redis databases, so that immediately all the clients connected to a given database will see the data of the other database, and the other way around. Example:

 
```
SWAPDB 0 1

```
 This will swap database 0 with database 1. All the clients connected with database 0 will immediately see the new data, exactly like all the clients connected with database 1 will see the data that was formerly of database 0.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` if `SWAPDB` was executed correctly.

 Examples
--------

 
```
SWAPDB 0 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/swapdb/>

SUNIONSTORE
===========



```
SUNIONSTORE
```
 Syntax 
```
SUNIONSTORE destination key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of elements in all given sets. ACL categories:  `@write`, `@set`, `@slow`,   This command is equal to [`SUNION`](../sunion), but instead of returning the resulting set, it is stored in `destination`.

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SUNIONSTORE key key1 key2
SMEMBERS key

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sunionstore/>

TDIGEST.ADD
===========



```
TDIGEST.ADD
```
 Syntax 
```
TDIGEST.ADD key value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(N) , where N is the number of samples to add  Adds one or more observations to a t-digest sketch.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `value` is value of an observation (floating-point).  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> TDIGEST.ADD t 1 2 3
OK
```
 
```
redis> TDIGEST.ADD t string
(error) ERR T-Digest: error parsing val parameter
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.add/>

STRLEN
======



```
STRLEN
```
 Syntax 
```
STRLEN key
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@read`, `@string`, `@fast`,   Returns the length of the string value stored at `key`. An error is returned when `key` holds a non-string value.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the length of the string at `key`, or `0` when `key` does not exist.

 Examples
--------

 
```

SET mykey "Hello world"
STRLEN mykey
STRLEN nonexisting

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/strlen/>

SUBSTR
======



```
SUBSTR (deprecated)
```
  As of Redis version 2.0.0, this command is regarded as deprecated.

 It can be replaced by [`GETRANGE`](../getrange) when migrating or writing new code.

  Syntax 
```
SUBSTR key start end
```
  Available since: 1.0.0 Time complexity: O(N) where N is the length of the returned string. The complexity is ultimately determined by the returned length, but because creating a substring from an existing string is very cheap, it can be considered O(1) for small strings. ACL categories:  `@read`, `@string`, `@slow`,   Returns the substring of the string value stored at `key`, determined by the offsets `start` and `end` (both are inclusive). Negative offsets can be used in order to provide an offset starting from the end of the string. So -1 means the last character, -2 the penultimate and so forth.

 The function handles out of range requests by limiting the resulting range to the actual length of the string.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)

 Examples
--------

 
```

SET mykey "This is a string"
GETRANGE mykey 0 3
GETRANGE mykey -3 -1
GETRANGE mykey 0 -1
GETRANGE mykey 10 100

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/substr/>

TDIGEST.BYRANK
==============



```
TDIGEST.BYRANK
```
 Syntax 
```
TDIGEST.BYRANK key rank [rank ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input rank, an estimation of the value (floating-point) with that rank.

 Multiple estimations can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `rank` Rank, for which the value should be retrieved.

 0 is the rank of the value of the smallest observation.

 *n*-1 is the rank of the value of the largest observation; *n* denotes the number of observations added to the sketch.

  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - an array of floating-points populated with value\_1, value\_2, ..., value\_R:

 * Return an accurate result when `rank` is 0 (the value of the smallest observation)
* Return an accurate result when `rank` is *n*-1 (the value of the largest observation), where *n* denotes the number of observations added to the sketch.
* Return 'inf' when `rank` is equal to *n* or larger than *n*

 All values are 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 1000
OK
redis> TDIGEST.ADD t 1 2 2 3 3 3 4 4 4 4 5 5 5 5 5
OK
redis> TDIGEST.BYRANK t 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
 1) "1"
 2) "2"
 3) "2"
 4) "3"
 5) "3"
 6) "3"
 7) "4"
 8) "4"
 9) "4"
10) "4"
11) "5"
12) "5"
13) "5"
14) "5"
15) "5"
16) "inf"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.byrank/>

SUBSCRIBE
=========



```
SUBSCRIBE
```
 Syntax 
```
SUBSCRIBE channel [channel ...]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of channels to subscribe to. ACL categories:  `@pubsub`, `@slow`,   Subscribes the client to the specified channels.

 Once the client enters the subscribed state it is not supposed to issue any other commands, except for additional `SUBSCRIBE`, [`SSUBSCRIBE`](../ssubscribe), [`PSUBSCRIBE`](../psubscribe), [`UNSUBSCRIBE`](../unsubscribe), [`SUNSUBSCRIBE`](../sunsubscribe), [`PUNSUBSCRIBE`](../punsubscribe), [`PING`](../ping), [`RESET`](../reset) and [`QUIT`](../quit) commands. However, if RESP3 is used (see [`HELLO`](../hello)) it is possible for a client to issue any commands while in subscribed state.

 For more information, see [Pub/sub](https://redis.io/docs/manual/pubsub/).

 Return
------

 When successful, this command doesn't return anything. Instead, for each channel, one message with the first element being the string "subscribe" is pushed as a confirmation that the command succeeded.

 Behavior change history
-----------------------

 * `>= 6.2.0`: [`RESET`](../reset) can be called to exit subscribed state.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/subscribe/>

SUNSUBSCRIBE
============



```
SUNSUBSCRIBE
```
 Syntax 
```
SUNSUBSCRIBE [shardchannel [shardchannel ...]]
```
  Available since: 7.0.0 Time complexity: O(N) where N is the number of clients already subscribed to a shard channel. ACL categories:  `@pubsub`, `@slow`,   Unsubscribes the client from the given shard channels, or from all of them if none is given.

 When no shard channels are specified, the client is unsubscribed from all the previously subscribed shard channels. In this case a message for every unsubscribed shard channel will be sent to the client.

 Note: The global channels and shard channels needs to be unsubscribed from separately.

 For more information about sharded Pub/Sub, see [Sharded Pub/Sub](https://redis.io/topics/pubsub#sharded-pubsub).

 Return
------

 When successful, this command doesn't return anything. Instead, for each shard channel, one message with the first element being the string "sunsubscribe" is pushed as a confirmation that the command succeeded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sunsubscribe/>

TDIGEST.CREATE
==============



```
TDIGEST.CREATE
```
 Syntax 
```
TDIGEST.CREATE key [COMPRESSION compression]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Allocates memory and initializes a new t-digest sketch.

 Required arguments
------------------

 `key` is key name for this new t-digest sketch.  Optional arguments
------------------

 `COMPRESSION compression` is a controllable tradeoff between accuracy and memory consumption. 100 is a common value for normal uses. 1000 is more accurate. If no value is passed by default the compression will be 100. For more information on scaling of accuracy versus the compression parameter see [*The t-digest: Efficient estimates of distributions*](https://www.sciencedirect.com/science/article/pii/S2665963820300403).

  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 100
OK
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.create/>

SYNC
====



```
SYNC
```
 Syntax 
```
SYNC
```
  Available since: 1.0.0 Time complexity: ACL categories:  `@admin`, `@slow`, `@dangerous`,   Initiates a replication stream from the master.

 The `SYNC` command is called by Redis replicas for initiating a replication stream from the master. It has been replaced in newer versions of Redis by [`PSYNC`](../psync).

 For more information about replication in Redis please check the [replication page](https://redis.io/topics/replication).

 Return
------

 **Non standard return value**, a bulk transfer of the data followed by [`PING`](../ping) and write requests from the master.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sync/>

TDIGEST.BYREVRANK
=================



```
TDIGEST.BYREVRANK
```
 Syntax 
```
TDIGEST.BYREVRANK key reverse_rank [reverse_rank ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input reverse rank, an estimation of the value (floating-point) with that reverse rank.

 Multiple estimations can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `revrank` Reverse rank, for which the value should be retrieved.

 0 is the reverse rank of the value of the largest observation.

 *n*-1 is the reverse rank of the value of the smallest observation; *n* denotes the number of observations added to the sketch.

  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - an array of floating-points populated with value\_1, value\_2, ..., value\_R:

 * Return an accurate result when `revrank` is 0 (the value of the largest observation)
* Return an accurate result when `revrank` is *n*-1 (the value of the smallest observation), where *n* denotes the number of observations added to the sketch.
* Return '-inf' when `revrank` is equal to *n* or larger than *n*

 All values are 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 1000
OK
redis> TDIGEST.ADD t 1 2 2 3 3 3 4 4 4 4 5 5 5 5 5
OK
redis> TDIGEST.BYREVRANK t 0 1 2 3 4 5 6 7 8 9 10 11 12 13 14 15
 1) "5"
 2) "5"
 3) "5"
 4) "5"
 5) "5"
 6) "4"
 7) "4"
 8) "4"
 9) "4"
10) "3"
11) "3"
12) "3"
13) "2"
14) "2"
15) "1"
16) "-inf"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.byrevrank/>

TDIGEST.INFO
============



```
TDIGEST.INFO
```
 Syntax 
```
TDIGEST.INFO key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns information and statistics about a t-digest sketch.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.

  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information about the sketch:

 

| Name | Description |
| --- | --- |
| `Compression` | The compression (controllable trade-off between accuracy and memory consumption) of the sketch |
| `Capacity` | Size of the buffer used for storing the centroids and for the incoming unmerged observations |
| `Merged nodes` | Number of merged observations |
| `Unmerged nodes` | Number of buffered nodes (uncompressed observations) |
| `Merged weight` | Weight of values of the merged nodes |
| `Unmerged weight` | Weight of values of the unmerged nodes (uncompressed observations) |
| `Observations` | Number of observations added to the sketch |
| `Total compressions` | Number of times this sketch compressed data together |
| `Memory usage` | Number of bytes allocated for the sketch |

 Examples
--------

 
```
redis> TDIGEST.CREATE t
OK
redis> TDIGEST.ADD t 1 2 3 4 5
OK
redis> TDIGEST.INFO t
 1) Compression
 2) (integer) 100
 3) Capacity
 4) (integer) 610
 5) Merged nodes
 6) (integer) 0
 7) Unmerged nodes
 8) (integer) 5
 9) Merged weight
10) (integer) 0
11) Unmerged weight
12) (integer) 5
13) Observations
14) (integer) 5
15) Total compressions
16) (integer) 0
17) Memory usage
18) (integer) 9768
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.info/>

TDIGEST.MERGE
=============



```
TDIGEST.MERGE
```
 Syntax 
```
TDIGEST.MERGE destination-key numkeys source-key [source-key ...]
  [COMPRESSION compression] [OVERRIDE]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(N\*K), where N is the number of centroids and K being the number of input sketches  Merges multiple t-digest sketches into a single sketch.

 Required arguments
------------------

 `destination-key` is key name for a t-digest sketch to merge observation values to.

 If `destination-key` does not exist - a new sketch is created.

 If `destination-key` is an existing sketch, its values are merged with the values of the source keys. To override the destination key contents use `OVERRIDE`.

  `numkeys` Number of sketches to merge observation values from (1 or more).  `source-key` each is a key name for a t-digest sketch to merge observation values from.  Optional arguments
------------------

 `COMPRESSION compression` is a controllable tradeoff between accuracy and memory consumption. 100 is a common value for normal uses. 1000 is more accurate. If no value is passed by default the compression will be 100. For more information on scaling of accuracy versus the compression parameter see [*The t-digest: Efficient estimates of distributions*](https://www.sciencedirect.com/science/article/pii/S2665963820300403).

 When `COMPRESSION` is not specified:

 * If `destination-key` does not exist or if `OVERRIDE` is specified, the compression is set to the maximal value among all source sketches.
* If `destination-key` already exists and `OVERRIDE` is not specified, its compression is not changed.

  `OVERRIDE` When specified, if `destination-key` already exists, it is overwritten.  Return value
------------

 OK on success, error otherwise.

 Examples
--------

 
```
redis> TDIGEST.CREATE s1
OK
redis> TDIGEST.CREATE s2
OK
redis> TDIGEST.ADD s1 10.0 20.0
OK
redis> TDIGEST.ADD s2 30.0 40.0
OK
redis> TDIGEST.MERGE sM 2 s1 s2
OK
redis> TDIGEST.BYRANK sM 0 1 2 3 4
1) "10"
2) "20"
3) "30"
4) "40"
5) "inf"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.merge/>

TDIGEST.CDF
===========



```
TDIGEST.CDF
```
 Syntax 
```
TDIGEST.CDF key value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input value, an estimation of the fraction (floating-point) of (observations smaller than the given value + half the observations equal to the given value).

 Multiple fractions can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `value` is value for which the CDF (Cumulative Distribution Function) should be retrieved.  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - the command returns an array of floating-points populated with fraction\_1, fraction\_2, ..., fraction\_N.

 All values are 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 1000
OK
redis> TDIGEST.ADD t 1 2 2 3 3 3 4 4 4 4 5 5 5 5 5
OK
redis> TDIGEST.CDF t 0 1 2 3 4 5 6
1) "0"
2) "0.033333333333333333"
3) "0.13333333333333333"
4) "0.29999999999999999"
5) "0.53333333333333333"
6) "0.83333333333333337"
7) "1"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.cdf/>

TDIGEST.MAX
===========



```
TDIGEST.MAX
```
 Syntax 
```
TDIGEST.MAX key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns the maximum observation value from a t-digest sketch.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) of maximum observation value from a sketch. The result is always accurate. 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t
OK
redis> TDIGEST.MAX t
"nan"
redis> TDIGEST.ADD t 3 4 1 2 5
OK
redis>TDIGEST.MAX t
"5"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.max/>

TIME
====



```
TIME
```
 Syntax 
```
TIME
```
  Available since: 2.6.0 Time complexity: O(1) ACL categories:  `@fast`,   The `TIME` command returns the current server time as a two items lists: a Unix timestamp and the amount of microseconds already elapsed in the current second. Basically the interface is very similar to the one of the `gettimeofday` system call.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 A multi bulk reply containing two elements:

 * unix time in seconds.
* microseconds.

 Examples
--------

 
```

TIME
TIME

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/time/>

TDIGEST.QUANTILE
================



```
TDIGEST.QUANTILE
```
 Syntax 
```
TDIGEST.QUANTILE key quantile [quantile ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input fraction, an estimation of the value (floating point) that is smaller than the given fraction of observations.

 Multiple quantiles can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `quantile` is the input fraction (between 0 and 1 inclusively)  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - an array of estimates (floating-point) populated with value\_1, value\_2, ..., value\_N.

 * Return an accurate result when `quantile` is 0 (the value of the smallest observation)
* Return an accurate result when `quantile` is 1 (the value of the largest observation)

 All values are 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 1000
OK
redis> TDIGEST.ADD t 1 2 2 3 3 3 4 4 4 4 5 5 5 5 5
OK
redis> TDIGEST.QUANTILE t 0 0.1 0.2 0.3 0.4 0.5 0.6 0.7 0.8 0.9 1
 1) "1"
 2) "2"
 3) "3"
 4) "3"
 5) "4"
 6) "4"
 7) "4"
 8) "5"
 9) "5"
10) "5"
11) "5"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.quantile/>

TDIGEST.MIN
===========



```
TDIGEST.MIN
```
 Syntax 
```
TDIGEST.MIN key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns the minimum observation value from a t-digest sketch.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) of minimum observation value from a sketch. The result is always accurate. 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t
OK
redis> TDIGEST.MIN t
"nan"
redis> TDIGEST.ADD t 3 4 1 2 5
OK
redis> TDIGEST.MIN t
"1"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.min/>

SUNION
======



```
SUNION
```
 Syntax 
```
SUNION key [key ...]
```
  Available since: 1.0.0 Time complexity: O(N) where N is the total number of elements in all given sets. ACL categories:  `@read`, `@set`, `@slow`,   Returns the members of the set resulting from the union of all the given sets.

 For example:

 
```
key1 = {a,b,c,d}
key2 = {c}
key3 = {a,c,e}
SUNION key1 key2 key3 = {a,b,c,d,e}

```

Keys that do not exist are considered to be empty sets.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list with members of the resulting set.

 Examples
--------

 
```

SADD key1 "a"
SADD key1 "b"
SADD key1 "c"
SADD key2 "c"
SADD key2 "d"
SADD key2 "e"
SUNION key1 key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/sunion/>

TDIGEST.RESET
=============



```
TDIGEST.RESET
```
 Syntax 
```
TDIGEST.RESET key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Resets a t-digest sketch: empty the sketch and re-initializes it.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> TDIGEST.RESET t
OK
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.reset/>

TDIGEST.TRIMMED\_MEAN
=====================



```
TDIGEST.TRIMMED_MEAN
```
 Syntax 
```
TDIGEST.TRIMMED_MEAN key low_cut_quantile high_cut_quantile
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(N) where N is the number of centroids  Returns an estimation of the mean value from the sketch, excluding observation values outside the low and high cutoff quantiles.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `low_cut_quantile` Foating-point value in the range [0..1], should be lower than `high_cut_quantile`

 When equal to 0: No low cut.

 When higher than 0: Exclude observation values lower than this quantile.

  `high_cut_quantile` Floating-point value in the range [0..1], should be higher than `low_cut_quantile`

 When lower than 1: Exclude observation values higher than or equal to this quantile.

 When equal to 1: No high cut.

  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) estimation of the mean value. 'nan' if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE t COMPRESSION 1000
OK
redis> TDIGEST.ADD t 1 2 3 4 5 6 7 8 9 10
OK
redis> TDIGEST.TRIMMED\_MEAN t 0.1 0.6
"4"
redis> TDIGEST.TRIMMED\_MEAN t 0.3 0.9
"6.5"
redis> TDIGEST.TRIMMED\_MEAN t 0 1
"5.5"
```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.trimmed_mean/>

TDIGEST.RANK
============



```
TDIGEST.RANK
```
 Syntax 
```
TDIGEST.RANK key value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input value (floating-point), the estimated rank of the value (the number of observations in the sketch that are smaller than the value + half the number of observations that are equal to the value).

 Multiple ranks can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `value` is input value for which the rank should be estimated. Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - an array of integers populated with rank\_1, rank\_2, ..., rank\_V:

 * -1 - when `value` is smaller than the value of the smallest observation.
* The number of observations - when `value` is larger than the value of the largest observation.
* Otherwise: an estimation of the number of (observations smaller than `value` + half the observations equal to `value`).

 0 is the rank of the value of the smallest observation.

 *n*-1 is the rank of the value of the largest observation; *n* denotes the number of observations added to the sketch.

 All values are -2 if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE s COMPRESSION 1000
OK
redis> TDIGEST.ADD s 10 20 30 40 50 60
OK
redis> TDIGEST.RANK s 0 10 20 30 40 50 60 70
1) (integer) -1
2) (integer) 0
3) (integer) 1
4) (integer) 2
5) (integer) 3
6) (integer) 4
7) (integer) 5
8) (integer) 6
redis> TDIGEST.REVRANK s 0 10 20 30 40 50 60 70
1) (integer) 6
2) (integer) 5
3) (integer) 4
4) (integer) 3
5) (integer) 2
6) (integer) 1
7) (integer) 0
8) (integer) -1 
```
 
```
redis> TDIGEST.CREATE s COMPRESSION 1000
OK
redis> TDIGEST.ADD s 10 10 10 10 20 20
OK
redis> TDIGEST.RANK s 10 20
1) (integer) 2
2) (integer) 5
redis> TDIGEST.REVRANK s 10 20
1) (integer) 4
2) (integer) 1
```
 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.rank/>

TOPK.COUNT
==========



```
TOPK.COUNT (deprecated)
```
  As of Redis version 2.4, this command is regarded as deprecated.

  Syntax 
```
TOPK.COUNT key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n) where n is the number of items  Returns count for an item. Multiple items can be requested at once. Please note this number will never be higher than the real count and likely to be lower.

 This command has been deprecated. The count value is not a representative of the number of appearances of an item.

 ### Parameters

 * **key**: Name of sketch where item is counted.
* **item**: Item/s to be counted.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - count for responding item.

 Examples
--------

 
```
redis> TOPK.COUNT topk foo 42 nonexist
1) (integer) 3
2) (integer) 1
3) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.count/>

TOPK.ADD
========



```
TOPK.ADD
```
 Syntax 
```
TOPK.ADD key items [items ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n \* k) where n is the number of items and k is the depth  Adds an item to the data structure. Multiple items can be added at once. If an item enters the Top-K list, the item which is expelled is returned. This allows dynamic heavy-hitter detection of items being entered or expelled from Top-K list.

 ### Parameters

 * **key**: Name of sketch where item is added.
* **item**: Item/s to be added.

 ### Return

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - if an element was dropped from the TopK list, [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) otherwise..

 #### Example

 
```
redis> TOPK.ADD topk foo bar 42
1) (nil)
2) baz
3) (nil)

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.add/>

TOPK.QUERY
==========



```
TOPK.QUERY
```
 Syntax 
```
TOPK.QUERY key item [item ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n) where n is the number of items  Checks whether an item is one of Top-K items. Multiple items can be checked at once.

 ### Parameters

 * **key**: Name of sketch where item is queried.
* **item**: Item/s to be queried.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - "1" if item is in Top-K, otherwise "0".

 Examples
--------

 
```
redis> TOPK.QUERY topk 42 nonexist
1) (integer) 1
2) (integer) 0

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.query/>

TDIGEST.REVRANK
===============



```
TDIGEST.REVRANK
```
 Syntax 
```
TDIGEST.REVRANK key value [value ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.4.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns, for each input value (floating-point), the estimated reverse rank of the value (the number of observations in the sketch that are larger than the value + half the number of observations that are equal to the value).

 Multiple reverse ranks can be retrieved in a signle call.

 Required arguments
------------------

 `key` is key name for an existing t-digest sketch.  `value` is input value for which the reverse rank should be estimated. Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - an array of integers populated with revrank\_1, revrank\_2, ..., revrank\_V:

 * -1 - when `value` is larger than the value of the largest observation.
* The number of observations - when `value` is smaller than the value of the smallest observation.
* Otherwise: an estimation of the number of (observations larger than `value` + half the observations equal to `value`).

 0 is the reverse rank of the value of the largest observation.

 *n*-1 is the reverse rank of the value of the smallest observation; *n* denotes the number of observations added to the sketch.

 All values are -2 if the sketch is empty.

 Examples
--------

 
```
redis> TDIGEST.CREATE s COMPRESSION 1000
OK
redis> TDIGEST.ADD s 10 20 30 40 50 60
OK
redis> TDIGEST.RANK s 0 10 20 30 40 50 60 70
1) (integer) -1
2) (integer) 0
3) (integer) 1
4) (integer) 2
5) (integer) 3
6) (integer) 4
7) (integer) 5
8) (integer) 6
redis> TDIGEST.REVRANK s 0 10 20 30 40 50 60 70
1) (integer) 6
2) (integer) 5
3) (integer) 4
4) (integer) 3
5) (integer) 2
6) (integer) 1
7) (integer) 0
8) (integer) -1
```
 
```
redis> TDIGEST.CREATE s COMPRESSION 1000
OK
redis> TDIGEST.ADD s 10 10 10 10 20 20
OK
redis> TDIGEST.RANK s 10 20
1) (integer) 2
2) (integer) 5
redis> TDIGEST.REVRANK s 10 20
1) (integer) 4
2) (integer) 1
```
 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/tdigest.revrank/>

TOPK.LIST
=========



```
TOPK.LIST
```
 Syntax 
```
TOPK.LIST key [WITHCOUNT]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(k) where k is the value of top-k  Return full list of items in Top K list.

 ### Parameters

 * **key**: Name of sketch where item is counted.
* **WITHCOUNT**: Count of each element is returned.

 Return
------

 k (or less) items in Top K list.

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - the names of items in the TopK list. If `WITHCOUNT` is requested, [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) and [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) pairs of the names of items in the TopK list and their count.

 Examples
--------

 
```
TOPK.LIST topk
1) foo
2) 42
3) bar

```


```
TOPK.LIST topk WITHCOUNT
1) foo
2) (integer) 12
3) 42
4) (integer) 7
5) bar
6) (integer) 2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.list/>

TOPK.RESERVE
============



```
TOPK.RESERVE
```
 Syntax 
```
TOPK.RESERVE key topk [width depth decay]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Initializes a TopK with specified parameters.

 ### Parameters

 * **key**: Key under which the sketch is to be found.
* **topk**: Number of top occurring items to keep.

 Optional parameters

 * **width**: Number of counters kept in each array. (Default 8)
* **depth**: Number of arrays. (Default 7)
* **decay**: The probability of reducing a counter in an occupied bucket. It is raised to power of it's counter (decay ^ bucket[i].counter). Therefore, as the counter gets higher, the chance of a reduction is being reduced. (Default 0.9)

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 
```
redis> TOPK.RESERVE topk 50 2000 7 0.925
OK

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.reserve/>

TOPK.INFO
=========



```
TOPK.INFO
```
 Syntax 
```
TOPK.INFO key
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(1)  Returns number of required items (k), width, depth and decay values.

 ### Parameters

 * **key**: Name of sketch.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information of the filter.

 Examples
--------

 
```
TOPK.INFO topk
1) k
2) (integer) 50
3) width
4) (integer) 2000
5) depth
6) (integer) 7
7) decay
8) "0.92500000000000004"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.info/>

TS.ALTER
========



```
TS.ALTER
```
 Syntax 
```
TS.ALTER key 
  [RETENTION retentionPeriod] 
  [CHUNK_SIZE size] 
  [DUPLICATE_POLICY policy] 
  [LABELS [{label value}...]]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(N) where N is the number of labels requested to update  Update the retention, chunk size, duplicate policy, and labels of an existing time series

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  **Note:** This command alters only the specified element. For example, if you specify only `RETENTION` and `LABELS`, the chunk size and the duplicate policy are not altered. 

 Optional arguments
------------------

 `RETENTION retentionPeriod` is maximum retention period, compared to the maximum existing timestamp, in milliseconds. See `RETENTION` in [`TS.CREATE`](../ts.create).

  `CHUNK_SIZE size` is the initial allocation size, in bytes, for the data part of each new chunk. Actual chunks may consume more memory. See `CHUNK_SIZE` in [`TS.CREATE`](../ts.create). Changing this value does not affect existing chunks.

  `DUPLICATE_POLICY policy` is policy for handling multiple samples with identical timestamps. See `DUPLICATE_POLICY` in [`TS.CREATE`](../ts.create).

  `LABELS [{label value}...]` is set of label-value pairs that represent metadata labels of the key and serve as a secondary index.

 If `LABELS` is specified, the given label list is applied. Labels that are not present in the given list are removed implicitly. Specifying `LABELS` with no label-value pairs removes all existing labels. See `LABELS` in [`TS.CREATE`](../ts.create).

  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 **Alter a temperature time series** Create a temperature time series.

 
```
127.0.0.1:6379> TS.CREATE temperature:2:32 RETENTION 60000 DUPLICATE\_POLICY MAX LABELS sensor\_id 2 area\_id 32
OK
```
 Alter the labels in the time series.

 
```
127.0.0.1:6379> TS.ALTER temperature:2:32 LABELS sensor\_id 2 area\_id 32 sub\_area\_id 15
OK
```
  See also
--------

 [`TS.CREATE`](../ts.create)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.alter/>

TOUCH
=====



```
TOUCH
```
 Syntax 
```
TOUCH key [key ...]
```
  Available since: 3.2.1 Time complexity: O(N) where N is the number of keys that will be touched. ACL categories:  `@keyspace`, `@read`, `@fast`,   Alters the last access time of a key(s). A key is ignored if it does not exist.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of keys that were touched.

 Examples
--------

 
```

SET key1 "Hello"
SET key2 "World"
TOUCH key1 key2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/touch/>

TS.MADD
=======



```
TS.MADD
```
 Syntax 
```
TS.MADD {key timestamp value}...

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(N\*M) when N is the amount of series updated and M is the amount of compaction rules or O(N) with no compaction  Append new samples to one or more time series

 [Examples](#examples)

 Required arguments
------------------

  `key` is the key name for the time series.

   `timestamp` is (integer) UNIX sample timestamp in milliseconds or `*` to set the timestamp according to the server clock.

   `value` is numeric data value of the sample (double). The double number should follow [RFC 7159](https://tools.ietf.org/html/rfc7159) (a JSON standard). The parser rejects overly large values that would not fit in binary64. It does not accept NaN or infinite values.

  **Notes:**

 * If `timestamp` is older than the retention period compared to the maximum existing timestamp, the sample is discarded and an error is returned.
* Explicitly adding samples to a compacted time series (using [`TS.ADD`](../ts.add), `TS.MADD`, [`TS.INCRBY`](../ts.incrby), or [`TS.DECRBY`](../ts.decrby)) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.

 Return value
------------

 Either

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) representing the timestamp of each added sample or an [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., on `DUPLICATE_POLICY` violation)
* [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., on wrong number of arguments)

 Complexity
----------

 If a compaction rule exits on a time series, TS.MADD performance might be reduced. The complexity of TS.MADD is always `O(N*M)`, where `N` is the amount of series updated and `M` is the amount of compaction rules or `O(N)` with no compaction.

 Examples
--------

  **Add stock prices at different timestamps** Create two stocks and add their prices at three different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.CREATE stock:B LABELS type stock name B
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120 stock:B 1000 120 stock:B 1010 110 stock:B 1020 100
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1000
5) (integer) 1010
6) (integer) 1020
```
  See also
--------

 [`TS.MRANGE`](../ts.mrange) | [`TS.RANGE`](../ts.range) | [`TS.MREVRANGE`](../ts.mrevrange) | [`TS.REVRANGE`](../ts.revrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.madd/>

TOPK.INCRBY
===========



```
TOPK.INCRBY
```
 Syntax 
```
TOPK.INCRBY key item increment [item increment ...]
```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [Bloom 2.0.0](https://redis.io/docs/stack/bloom)  Time complexity: O(n \* k \* incr) where n is the number of items, k is the depth and incr is the increment  Increase the score of an item in the data structure by increment. Multiple items' score can be increased at once. If an item enters the Top-K list, the item which is expelled is returned.

 ### Parameters

 * **key**: Name of sketch where item is added.
* **item**: Item/s to be added.
* **increment**: increment to current item score. Increment must be greater or equal to 1. Increment is limited to 100,000 to avoid server freeze.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - if an element was dropped from the TopK list, [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) otherwise..

 @example

 
```
redis> TOPK.INCRBY topk foo 3 bar 2 42 30
1) (nil)
2) (nil)
3) foo

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/topk.incrby/>

TS.ADD
======



```
TS.ADD
```
 Syntax 
```
TS.ADD key timestamp value 
  [RETENTION retentionPeriod] 
  [ENCODING [COMPRESSED|UNCOMPRESSED]] 
  [CHUNK_SIZE size] 
  [ON_DUPLICATE policy] 
  [LABELS {label value}...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(M) when M is the amount of compaction rules or O(1) with no compaction  Append a sample to a time series

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  `timestamp` is (integer) UNIX sample timestamp in milliseconds or `*` to set the timestamp according to the server clock.

  `value` is (double) numeric data value of the sample. The double number should follow [RFC 7159](https://tools.ietf.org/html/rfc7159) (JSON standard). In particular, the parser rejects overly large values that do not fit in binary64. It does not accept NaN or infinite values.

  **Notes:**

 * When specified key does not exist, a new time series is created.

 if a [COMPACTION\_POLICY](https://redis.io/docs/stack/timeseries/configuration/#compaction_policy) configuration parameter is defined, compacted time series would be created as well.
* If `timestamp` is older than the retention period compared to the maximum existing timestamp, the sample is discarded and an error is returned.
* When adding a sample to a time series for which compaction rules are defined:


	+ If all the original samples for an affected aggregated time bucket are available, the compacted value is recalculated based on the reported sample and the original samples.
	+ If only a part of the original samples for an affected aggregated time bucket is available due to trimming caused in accordance with the time series RETENTION policy, the compacted value is recalculated based on the reported sample and the available original samples.
	+ If the original samples for an affected aggregated time bucket are not available due to trimming caused in accordance with the time series RETENTION policy, the compacted value bucket is not updated.
* Explicitly adding samples to a compacted time series (using `TS.ADD`, [`TS.MADD`](../ts.madd), [`TS.INCRBY`](../ts.incrby), or [`TS.DECRBY`](../ts.decrby)) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.

 Optional arguments
------------------

 The following arguments are optional because they can be set by [`TS.CREATE`](../ts.create).

 `RETENTION retentionPeriod` is maximum retention period, compared to the maximum existing timestamp, in milliseconds.

 Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `RETENTION` in [`TS.CREATE`](../ts.create).

  `ENCODING enc` specifies the series sample's encoding format.

 Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `ENCODING` in [`TS.CREATE`](../ts.create).

  `CHUNK_SIZE size` is memory size, in bytes, allocated for each data chunk. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `CHUNK_SIZE` in [`TS.CREATE`](../ts.create).

  `ON_DUPLICATE policy` is overwrite key and database configuration for [DUPLICATE\_POLICY](https://redis.io/docs/stack/timeseries/configuration/#duplicate_policy), the policy for handling samples with identical timestamps. It is used with one of the following values:

 * `BLOCK`: ignore any newly reported value and reply with an error
* `FIRST`: ignore any newly reported value
* `LAST`: override with the newly reported value
* `MIN`: only override if the value is lower than the existing value
* `MAX`: only override if the value is higher than the existing value
* `SUM`: If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

  `LABELS {label value}...` is set of label-value pairs that represent metadata labels of the time series.

 Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `LABELS` in [`TS.CREATE`](../ts.create).

  **Notes:**

 * You can use this command to add data to a nonexisting time series in a single command. This is why `RETENTION`, `ENCODING`, `CHUNK_SIZE`, `ON_DUPLICATE`, and `LABELS` are optional arguments.
* Setting `RETENTION` and `LABELS` introduces additional time complexity.

 Return value
------------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - the timestamp of the upserted sample, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors).

 Complexity
----------

 If a compaction rule exits on a time series, the performance of `TS.ADD` can be reduced. The complexity of `TS.ADD` is always `O(M)`, where `M` is the number of compaction rules or `O(1)` with no compaction.

 Examples
--------

 **Append a sample to a temperature time series** Create a temperature time series, set its retention to 1 year, and append a sample.

 
```
127.0.0.1:6379> TS.ADD temperature:3:11 1548149183000 27 RETENTION 31536000000
(integer) 1548149183000
```
 **Note:** If a time series with such a name already exists, the sample is added, but the retention does not change.

 Add a sample to the time series, setting the sample's timestamp according to the server clock.

 
```
127.0.0.1:6379> TS.ADD temperature:3:11 \* 30
(integer) 1662042954573
```
  See also
--------

 [`TS.CREATE`](../ts.create)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.add/>

TS.CREATERULE
=============



```
TS.CREATERULE
```
 Syntax 
```
TS.CREATERULE sourceKey destKey 
  AGGREGATION aggregator bucketDuration 
  [alignTimestamp]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(1)  Create a compaction rule

 [Examples](#examples)

 Required arguments
------------------

 `sourceKey` is key name for the source time series.

  `destKey` is key name for destination (compacted) time series. It must be created before `TS.CREATERULE` is called.

  `AGGREGATION aggregator bucketDuration` aggregates results into time buckets.

 * `aggregator` takes one of the following aggregation types:



| `aggregator` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all values |
| `sum` | Sum of all values |
| `min` | Minimum value |
| `max` | Maximum value |
| `range` | Difference between the highest and the lowest value |
| `count` | Number of values |
| `first` | Value with lowest timestamp in the bucket |
| `last` | Value with highest timestamp in the bucket |
| `std.p` | Population standard deviation of the values |
| `std.s` | Sample standard deviation of the values |
| `var.p` | Population variance of the values |
| `var.s` | Sample variance of the values |
| `twa` | Time-weighted average over the bucket's timeframe (since RedisTimeSeries v1.8) |
* `bucketDuration` is duration of each bucket, in milliseconds.

 **Notes**

 * Only new samples that are added into the source series after the creation of the rule will be aggregated.
* Calling `TS.CREATERULE` with a nonempty `destKey` may result in inconsistencies between the raw and the compacted data.
* Explicitly adding samples to a compacted time series (using [`TS.ADD`](../ts.add), [`TS.MADD`](../ts.madd), [`TS.INCRBY`](../ts.incrby), or [`TS.DECRBY`](../ts.decrby)) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.
* If no samples are added to the source time series during a bucket period. no *compacted sample* is added to the destination time series.
* The timestamp of a compacted sample added to the destination time series is set to the start timestamp the appropriate compaction bucket. For example, for a 10-minute compaction bucket with no alignment, the compacted samples timestamps are `x:00`, `x:10`, `x:20`, and so on.
* Deleting `destKey` will cause the compaction rule to be deleted as well.
* On a clustered environment, hash tags should be used to force `sourceKey` and `destKey` to be stored in the same hash slot.

 Optional arguments
------------------

 `alignTimestamp` (since RedisTimeSeries v1.8) ensures that there is a bucket that starts exactly at `alignTimestamp` and aligns all other buckets accordingly. It is expressed in milliseconds. The default value is 0 aligned with the epoch. For example, if `bucketDuration` is 24 hours (`24 * 3600 * 1000`), setting `alignTimestamp` to 6 hours after the epoch (`6 * 3600 * 1000`) ensures that each bucket’s timeframe is `[06:00 .. 06:00)`.

  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

  **Create a compaction rule** Create a time series to store the temperatures measured in Tel Aviv.

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
```
 Next, create a compacted time series named *dailyAvgTemp* containing one compacted sample per 24 hours: the time-weighted average of all measurements taken from midnight to next midnight.

 
```
127.0.0.1:6379> TS.CREATE dailyAvgTemp:TLV LABELS type temp location TLV
127.0.0.1:6379> TS.CREATERULE temp:TLV dailyAvgTemp:TLV AGGREGATION twa 86400000 
```
 Now, also create a compacted time series named *dailyDiffTemp*. This time series will contain one compacted sample per 24 hours: the difference between the minimum and the maximum temperature measured between 06:00 and 06:00 next day. Here, 86400000 is the number of milliseconds in 24 hours, 21600000 is the number of milliseconds in 6 hours.

 
```
127.0.0.1:6379> TS.CREATE dailyDiffTemp:TLV LABELS type temp location TLV
127.0.0.1:6379> TS.CREATERULE temp:TLV dailyDiffTemp:TLV AGGREGATION range 86400000 21600000
```
  See also
--------

 [`TS.DELETERULE`](../ts.deleterule)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)

 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.createrule/>

TS.CREATE
=========



```
TS.CREATE
```
 Syntax 
```
TS.CREATE key 
  [RETENTION retentionPeriod] 
  [ENCODING [UNCOMPRESSED|COMPRESSED]] 
  [CHUNK_SIZE size] 
  [DUPLICATE_POLICY policy] 
  [LABELS {label value}...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(1)  Create a new time series

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  **Notes:**

 * If a key already exists, you get a Redis error reply, `TSDB: key already exists`. You can check for the existence of a key with the [`EXISTS`](../exists) command.
* Other commands that also create a new time series when called with a key that does not exist are [`TS.ADD`](../ts.add), [`TS.INCRBY`](../ts.incrby), and [`TS.DECRBY`](../ts.decrby).

 Optional arguments
------------------

 `RETENTION retentionPeriod` is maximum age for samples compared to the highest reported timestamp, in milliseconds. Samples are expired based solely on the difference between their timestamp and the timestamps passed to subsequent [`TS.ADD`](../ts.add), [`TS.MADD`](../ts.madd), [`TS.INCRBY`](../ts.incrby), and [`TS.DECRBY`](../ts.decrby) calls with this key.

 When set to 0, samples never expire. When not specified, the option is set to the global [RETENTION\_POLICY](https://redis.io/docs/stack/timeseries/configuration/#retention_policy) configuration of the database, which by default is 0.

  `ENCODING enc` specifies the series samples encoding format as one of the following values:

 * `COMPRESSED`, applies compression to the series samples.
* `UNCOMPRESSED`, keeps the raw samples in memory. Adding this flag keeps data in an uncompressed form.

 `COMPRESSED` is almost always the right choice. Compression not only saves memory but usually improves performance due to a lower number of memory accesses. It can result in about 90% memory reduction. The exception are highly irregular timestamps or values, which occur rarely.

 When not specified, the option is set to `COMPRESSED`.

  `CHUNK_SIZE size` is initial allocation size, in bytes, for the data part of each new chunk. Actual chunks may consume more memory. Changing chunkSize (using [`TS.ALTER`](../ts.alter)) does not affect existing chunks.

 Must be a multiple of 8 in the range [48 .. 1048576]. When not specified, it is set to the global [CHUNK\_SIZE\_BYTES](https://redis.io/docs/stack/timeseries/configuration/#chunk_size_bytes) configuration of the database, which by default is 4096 (a single memory page).

 Note: Before v1.6.10 no minimum was enforced. Between v1.6.10 and v1.6.17 and in v1.8.0 the minimum value was 128. Since v1.8.1 the minimum value is 48.

 The data in each key is stored in chunks. Each chunk contains header and data for a given timeframe. An index contains all chunks. Iterations occur inside each chunk. Depending on your use case, consider these tradeoffs for having smaller or larger sizes of chunks:

 * Insert performance: Smaller chunks result in slower inserts (more chunks need to be created).
* Query performance: Queries for a small subset when the chunks are very large are slower, as we need to iterate over the chunk to find the data.
* Larger chunks may take more memory when you have a very large number of keys and very few samples per key, or less memory when you have many samples per key.

 If you are unsure about your use case, select the default.

  `DUPLICATE_POLICY policy` is policy for handling insertion ([`TS.ADD`](../ts.add) and [`TS.MADD`](../ts.madd)) of multiple samples with identical timestamps, with one of the following values:

 * `BLOCK`: ignore any newly reported value and reply with an error
* `FIRST`: ignore any newly reported value
* `LAST`: override with the newly reported value
* `MIN`: only override if the value is lower than the existing value
* `MAX`: only override if the value is higher than the existing value
* `SUM`: If a previous sample exists, add the new sample to it so that the updated value is equal to (previous + new). If no previous sample exists, set the updated value equal to the new value.

 When not specified: set to the global [DUPLICATE\_POLICY](https://redis.io/docs/stack/timeseries/configuration/#duplicate_policy) configuration of the database (which, by default, is `BLOCK`).

  `LABELS {label value}...` is set of label-value pairs that represent metadata labels of the key and serve as a secondary index.

 The [`TS.MGET`](../ts.mget), [`TS.MRANGE`](../ts.mrange), and [`TS.MREVRANGE`](../ts.mrevrange) commands operate on multiple time series based on their labels. The [`TS.QUERYINDEX`](../ts.queryindex) command returns all time series keys matching a given filter based on their labels.

  Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 Examples
--------

 **Create a temperature time series** 
```
127.0.0.1:6379> TS.CREATE temperature:2:32 RETENTION 60000 DUPLICATE\_POLICY MAX LABELS sensor\_id 2 area\_id 32
OK
```
  See also
--------

 [`TS.ADD`](../ts.add) | [`TS.INCRBY`](../ts.incrby) | [`TS.DECRBY`](../ts.decrby) | [`TS.MGET`](../ts.mget) | [`TS.MRANGE`](../ts.mrange) | [`TS.MREVRANGE`](../ts.mrevrange) | [`TS.QUERYINDEX`](../ts.queryindex)

 Related topics
--------------

 * [RedisTimeSeries](https://redis.io/docs/stack/timeseries)
* [RedisTimeSeries Version 1.2 Is Here!](https://redis.com/blog/redistimeseries-version-1-2-is-here/)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.create/>

TS.INFO
=======



```
TS.INFO
```
 Syntax 
```
TS.INFO key 
  [DEBUG]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(1)  Return information and statistics for a time series.

 [Examples](#examples)

 Required arguments
------------------

  `key` is key name of the time series.  Optional arguments
------------------

  `[DEBUG]` is an optional flag to get a more detailed information about the chunks.

  Return value
------------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information about the time series (name-value pairs):

 

| Name[Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) | Description |
| --- | --- |
| `totalSamples` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) Total number of samples in this time series |
| `memoryUsage` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) Total number of bytes allocated for this time series, which is the sum of  - The memory used for storing the series' configuration parameters (retention period, duplication policy, etc.)- The memory used for storing the series' compaction rules- The memory used for storing the series' labels (key-value pairs)- The memory used for storing the chunks (chunk header + compressed/uncompressed data) |
| `firstTimestamp` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) First timestamp present in this time series |
| `lastTimestamp` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) Last timestamp present in this time series |
| `retentionTime` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) The retention period, in milliseconds, for this time series |
| `chunkCount` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) Number of chunks used for this time series |
| `chunkSize` | [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) The initial allocation size, in bytes, for the data part of each new chunk.Actual chunks may consume more memory. Changing the chunk size (using [`TS.ALTER`](../ts.alter)) does not affect existing chunks. |
| `chunkType` | [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) The chunks type: `compressed` or `uncompressed` |
| `duplicatePolicy` | [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) or [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) The [duplicate policy](https://redis.io/docs/stack/timeseries/configuration/#duplicate_policy) of this time series |
| `labels` | [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) or [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) Metadata labels of this time series Each element is a 2-elements [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)) representing (label, value) |
| `sourceKey` | [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) or [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)Key name for source time series in case the current series is a target of a [compaction rule](../ts.createrule/index) |
| `rules` | [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) [Compaction rules](../ts.createrule/index) defined in this time series Each rule is an [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with 4 elements:- [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): The compaction key- [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The bucket duration- [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): The aggregator- [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The alignment (since RedisTimeSeries v1.8) |

 When [`DEBUG`](../debug) is specified, the response also contains:

 

| Name[Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) | Description |
| --- | --- |
| `keySelfName` | [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) Name of the key |
| `Chunks` | [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) with information about the chunksEach element is an [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of information about a single chunk in a name([Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings))-value pairs:- `startTimestamp` - [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - First timestamp present in the chunk- `endTimestamp` - [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - Last timestamp present in the chunk- `samples` - [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - Total number of samples in the chunk- `size` - [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - the chunk's internal data size (without overheads) in bytes- `bytesPerSample` - [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) (double) - Ratio of `size` and `samples` |

 Examples
--------

  **Find information about a temperature/humidity time series by location and sensor type** Create a set of sensors to measure temperature and humidity in your study and kitchen.

 
```
127.0.0.1:6379> TS.CREATE telemetry:study:temperature LABELS room study type temperature
OK
127.0.0.1:6379> TS.CREATE telemetry:study:humidity LABELS room study type humidity
OK
127.0.0.1:6379> TS.CREATE telemetry:kitchen:temperature LABELS room kitchen type temperature
OK
127.0.0.1:6379> TS.CREATE telemetry:kitchen:humidity LABELS room kitchen type humidity
OK
```
 Find information about the time series for temperature in the kitchen.

 
```
127.0.0.1:6379> TS.INFO telemetry:kitchen:temperature
 1) totalSamples
 2) (integer) 0
 3) memoryUsage
 4) (integer) 4246
 5) firstTimestamp
 6) (integer) 0
 7) lastTimestamp
 8) (integer) 0
 9) retentionTime
10) (integer) 0
11) chunkCount
12) (integer) 1
13) chunkSize
14) (integer) 4096
15) chunkType
16) compressed
17) duplicatePolicy
18) (nil)
19) labels
20) 1) 1) "room"
 2) "kitchen"
 2) 1) "type"
 2) "temperature"
21) sourceKey
22) (nil)
23) rules
24) (empty array)
```
 Query the time series using DEBUG to get more information about the chunks.

 
```
127.0.0.1:6379> TS.INFO telemetry:kitchen:temperature DEBUG
 1) totalSamples
 2) (integer) 0
 3) memoryUsage
 4) (integer) 4246
 5) firstTimestamp
 6) (integer) 0
 7) lastTimestamp
 8) (integer) 0
 9) retentionTime
10) (integer) 0
11) chunkCount
12) (integer) 1
13) chunkSize
14) (integer) 4096
15) chunkType
16) compressed
17) duplicatePolicy
18) (nil)
19) labels
20) 1) 1) "room"
 2) "kitchen"
 2) 1) "type"
 2) "temperature"
21) sourceKey
22) (nil)
23) rules
24) (empty array)
25) keySelfName
26) "telemetry:kitchen:temperature"
27) Chunks
28) 1) 1) startTimestamp
 2) (integer) 0
 3) endTimestamp
 4) (integer) 0
 5) samples
 6) (integer) 0
 7) size
 8) (integer) 4096
 9) bytesPerSample
 10) "inf"
```
  See also
--------

 [`TS.RANGE`](../ts.range) | [`TS.QUERYINDEX`](../ts.queryindex) | [`TS.GET`](../ts.get)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.info/>

TS.MGET
=======



```
TS.MGET
```
 Syntax 
```
TS.MGET [LATEST] [WITHLABELS | SELECTED_LABELS label...] FILTER filterExpr...

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n) where n is the number of time-series that match the filters  Get the sample with the highest timestamp from each time series matching a specific filter

 [Examples](#examples)

 Required arguments
------------------

  `FILTER filterExpr...` filters time series based on their labels and label values. Each filter expression has one of the following syntaxes:

 * `label=value`, where `label` equals `value`
* `label!=value`, where `label` does not equal `value`
* `label=`, where `key` does not have label `label`
* `label!=`, where `key` has label `label`
* `label=(value1,value2,...)`, where `key` with label `label` equals one of the values in the list
* `label!=(value1,value2,...)` where key with label `label` does not equal any of the values in the list

 **NOTES:**

 * At least one `label=value` filter is required.
* Filters are conjunctive. For example, the FILTER `type=temperature room=study` means the a time series is a temperature time series of a study room.
* Don't use whitespaces in the filter expression.

  Optional arguments
------------------

  `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.MGET also reports the compacted value of the latest possibly partial bucket, given that this bucket's start time falls within `[fromTimestamp, toTimestamp]`. Without `LATEST`, TS.MGET does not report the latest possibly partial bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest possibly partial bucket is also required. In such a case, use `LATEST`.

   `WITHLABELS` includes in the reply all label-value pairs representing metadata labels of the time series. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

   `SELECTED_LABELS label...` (since RedisTimeSeries v1.6) returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

  **Note:** The [`MGET`](../mget) command cannot be part of transaction when running on a Redis cluster.

 Return value
------------

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): for each time series matching the specified filters, the following is reported:
	+ bulk-string-reply: The time series key name
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): label-value pairs ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings))
		- By default, an empty array is reported
		- If `WITHLABELS` is specified, all labels associated with this time series are reported
		- If `SELECTED_LABELS label...` is specified, the selected labels are reported (null value when no such label defined)
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single timestamp-value pair ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) (double))

 Examples
--------

  **Select labels to retrieve** Create time series for temperature in Tel Aviv and Jerusalem, then add different temperature samples.

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
127.0.0.1:6379> TS.CREATE temp:JLM LABELS type temp location JLM
OK
127.0.0.1:6379> TS.MADD temp:TLV 1000 30 temp:TLV 1010 35 temp:TLV 1020 9999 temp:TLV 1030 40
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1030
127.0.0.1:6379> TS.MADD temp:JLM 1005 30 temp:JLM 1015 35 temp:JLM 1025 9999 temp:JLM 1035 40
1) (integer) 1005
2) (integer) 1015
3) (integer) 1025
4) (integer) 1035
```
 Get all the labels associated with the last sample.

 
```
127.0.0.1:6379> TS.MGET WITHLABELS FILTER type=temp
1) 1) "temp:JLM"
 2) 1) 1) "type"
 2) "temp"
 2) 1) "location"
 2) "JLM"
 3) 1) (integer) 1035
 2) 40
2) 1) "temp:TLV"
 2) 1) 1) "type"
 2) "temp"
 2) 1) "location"
 2) "TLV"
 3) 1) (integer) 1030
 2) 40
```
 To get only the `location` label for each last sample, use `SELECTED_LABELS`.

 
```
127.0.0.1:6379> TS.MGET SELECTED\_LABELS location FILTER type=temp
1) 1) "temp:JLM"
 2) 1) 1) "location"
 2) "JLM"
 3) 1) (integer) 1035
 2) 40
2) 1) "temp:TLV"
 2) 1) 1) "location"
 2) "TLV"
 3) 1) (integer) 1030
 2) 40
```
  See also
--------

 [`TS.MRANGE`](../ts.mrange) | [`TS.RANGE`](../ts.range) | [`TS.MREVRANGE`](../ts.mrevrange) | [`TS.REVRANGE`](../ts.revrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.mget/>

TS.DELETERULE
=============



```
TS.DELETERULE
```
 Syntax 
```
TS.DELETERULE sourceKey destKey

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(1)  Delete a compaction rule

 Required arguments
------------------

 `sourceKey` is key name for the source time series.

  `destKey` is key name for destination (compacted) time series.

  **Note:** This command does not delete the compacted series.

 Return value
------------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) - `OK` if executed correctly, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) otherwise.

 See also
--------

 [`TS.CREATERULE`](../ts.createrule)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.deleterule/>

TS.DEL
======



```
TS.DEL
```
 Syntax 
```
TS.DEL key fromTimestamp toTimestamp

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.6.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(N) where N is the number of data points that will be removed  Delete all samples between two timestamps for a given time series

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  `fromTimestamp` is start timestamp for the range deletion.

  `toTimestamp` is end timestamp for the range deletion.

 The given timestamp interval is closed (inclusive), meaning that samples whose timestamp eqauls the `fromTimestamp` or `toTimestamp` are also deleted.

 **Notes:**

 * If fromTimestamp is older than the retention period compared to the maximum existing timestamp, the deletion is discarded and an error is returned.
* When deleting a sample from a time series for which compaction rules are defined:
	+ If all the original samples for an affected compaction bucket are available, the compacted value is recalculated based on the remaining original samples, or removed if all original samples within the compaction bucket were deleted.
	+ If some or all the original samples for an affected compaction bucket were expired, the deletion is discarded and an error is returned.
* Explicitly deleting samples from a compacted time series may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples. That being said, it is safe to explicitly delete samples from a compacted time series beyond the retention period of the original time series.

 Return value
------------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of samples that were deleted, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors).

 Examples
--------

 **Delete range of data points** Create time series for temperature in Tel Aviv and Jerusalem, then add different temperature samples.

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
127.0.0.1:6379> TS.CREATE temp:JLM LABELS type temp location JLM
OK
127.0.0.1:6379> TS.MADD temp:TLV 1000 30 temp:TLV 1010 35 temp:TLV 1020 9999 temp:TLV 1030 40
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1030
127.0.0.1:6379> TS.MADD temp:JLM 1005 30 temp:JLM 1015 35 temp:JLM 1025 9999 temp:JLM 1035 40
1) (integer) 1005
2) (integer) 1015
3) (integer) 1025
4) (integer) 1035
```
 Delete the range of data points for temperature in Tel Aviv.

 
```
127.0.0.1:6379> TS.DEL temp:TLV 1000 1030
(integer) 4
```
  See also
--------

 [`TS.ADD`](../ts.add)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)

 

 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.del/>

TS.DECRBY
=========



```
TS.DECRBY
```
 Syntax 
```
TS.DECRBY key value 
  [TIMESTAMP timestamp] 
  [RETENTION retentionPeriod] 
  [UNCOMPRESSED] 
  [CHUNK_SIZE size] 
  [LABELS {label value}...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(M) when M is the amount of compaction rules or O(1) with no compaction  Decrease the value of the sample with the maximum existing timestamp, or create a new sample with a value equal to the value of the sample with the maximum existing timestamp with a given decrement

 Required arguments
------------------

 `key` is key name for the time series.

  `value` is numeric data value of the sample (double)

  **Notes**

 * When specified key does not exist, a new time series is created.
* You can use this command as a counter or gauge that automatically gets history as a time series.
* Explicitly adding samples to a compacted time series (using [`TS.ADD`](../ts.add), [`TS.MADD`](../ts.madd), [`TS.INCRBY`](../ts.incrby), or `TS.DECRBY`) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.

 Optional arguments
------------------

 `TIMESTAMP timestamp` is (integer) UNIX sample timestamp in milliseconds or `*` to set the timestamp according to the server clock.

 `timestamp` must be equal to or higher than the maximum existing timestamp. When equal, the value of the sample with the maximum existing timestamp is decreased. If it is higher, a new sample with a timestamp set to `timestamp` is created, and its value is set to the value of the sample with the maximum existing timestamp minus `value`.

 If the time series is empty, the value is set to `value`.

 When not specified, the timestamp is set according to the server clock.

  `RETENTION retentionPeriod` is maximum retention period, compared to the maximum existing timestamp, in milliseconds. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `RETENTION` in [`TS.CREATE`](../ts.create).

  `UNCOMPRESSED` changes data storage from compressed (default) to uncompressed. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `ENCODING` in [`TS.CREATE`](../ts.create).

  `CHUNK_SIZE size` is memory size, in bytes, allocated for each data chunk. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `CHUNK_SIZE` in [`TS.CREATE`](../ts.create).

  `LABELS [{label value}...]` is set of label-value pairs that represent metadata labels of the key and serve as a secondary index. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `LABELS` in [`TS.CREATE`](../ts.create).

  **Notes**

 * You can use this command to add data to a nonexisting time series in a single command. This is why `RETENTION`, `UNCOMPRESSED`, `CHUNK_SIZE`, and `LABELS` are optional arguments.
* When specified and the key doesn't exist, a new time series is created. Setting the `RETENTION` and `LABELS` introduces additional time complexity.

 Return value
------------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - the timestamp of the upserted sample, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors).

 See also
--------

 [`TS.INCRBY`](../ts.incrby) | [`TS.CREATE`](../ts.create)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.decrby/>

TS.INCRBY
=========



```
TS.INCRBY
```
 Syntax 
```
TS.INCRBY key value 
  [TIMESTAMP timestamp] 
  [RETENTION retentionPeriod] 
  [UNCOMPRESSED] 
  [CHUNK_SIZE size] 
  [LABELS {label value}...]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(M) when M is the amount of compaction rules or O(1) with no compaction  Increase the value of the sample with the maximum existing timestamp, or create a new sample with a value equal to the value of the sample with the maximum existing timestamp with a given increment

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  `value` is numeric data value of the sample (double)

  **Notes**

 * When specified key does not exist, a new time series is created.
* You can use this command as a counter or gauge that automatically gets history as a time series.
* Explicitly adding samples to a compacted time series (using [`TS.ADD`](../ts.add), [`TS.MADD`](../ts.madd), `TS.INCRBY`, or [`TS.DECRBY`](../ts.decrby)) may result in inconsistencies between the raw and the compacted data. The compaction process may override such samples.

 Optional arguments
------------------

 `TIMESTAMP timestamp` is (integer) UNIX sample timestamp in milliseconds or `*` to set the timestamp according to the server clock.

 `timestamp` must be equal to or higher than the maximum existing timestamp. When equal, the value of the sample with the maximum existing timestamp is increased. If it is higher, a new sample with a timestamp set to `timestamp` is created, and its value is set to the value of the sample with the maximum existing timestamp plus `value`.

 If the time series is empty, the value is set to `value`.

 When not specified, the timestamp is set according to the server clock.

  `RETENTION retentionPeriod` is maximum retention period, compared to the maximum existing timestamp, in milliseconds. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `RETENTION` in [`TS.CREATE`](../ts.create).

  `UNCOMPRESSED` changes data storage from compressed (default) to uncompressed. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `ENCODING` in [`TS.CREATE`](../ts.create).

  `CHUNK_SIZE size` is memory size, in bytes, allocated for each data chunk. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `CHUNK_SIZE` in [`TS.CREATE`](../ts.create).

  `LABELS [{label value}...]` is set of label-value pairs that represent metadata labels of the key and serve as a secondary index. Use it only if you are creating a new time series. It is ignored if you are adding samples to an existing time series. See `LABELS` in [`TS.CREATE`](../ts.create).

  **Notes**

 * You can use this command to add data to a nonexisting time series in a single command. This is why `RETENTION`, `UNCOMPRESSED`, `CHUNK_SIZE`, and `LABELS` are optional arguments.
* When specified and the key doesn't exist, a new time series is created. Setting the `RETENTION` and `LABELS` introduces additional time complexity.

 Return value
------------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers) - the timestamp of the upserted sample, or [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors).

 Examples
--------

 **Store sum of data from several sources** Suppose you are getting number of orders or total income per minute from several points of sale, and you want to store only the combined value. Call TS.INCRBY for each point-of-sale report.

 
```
127.0.0.1:6379> TS.INCRBY a 232 TIMESTAMP 1657811829000 // point-of-sale #1
(integer) 1657811829000
127.0.0.1:6379> TS.INCRBY a 157 TIMESTAMP 1657811829000 // point-of-sale #2
(integer) 1657811829000
127.0.0.1:6379> TS.INCRBY a 432 TIMESTAMP 1657811829000 // point-of-sale #3
(integer) 1657811829000
```
 Note that the timestamps must arrive in non-decreasing order.

 
```
127.0.0.1:6379> ts.incrby a 100 TIMESTAMP 50
(error) TSDB: timestamp must be equal to or higher than the maximum existing timestamp
```
 You can achieve similar results without such protection using `TS.ADD key timestamp value ON_DUPLICATE sum`.

  **Count sensor captures** Supose a sensor ticks whenever a car is passed on a road, and you want to count occurrences. Whenever you get a tick from the sensor you can simply call:

 
```
127.0.0.1:6379> TS.INCRBY a 1
(integer) 1658431553109
```
 The timestamp is filled automatically.

  See also
--------

 [`TS.DECRBY`](../ts.decrby) | [`TS.CREATE`](../ts.create)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.incrby/>

TYPE
====



```
TYPE
```
 Syntax 
```
TYPE key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   Returns the string representation of the type of the value stored at `key`. The different types that can be returned are: `string`, `list`, `set`, `zset`, `hash` and `stream`.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): type of `key`, or `none` when `key` does not exist.

 Examples
--------

 
```

SET key1 "value"
LPUSH key2 "value"
SADD key3 "value"
TYPE key1
TYPE key2
TYPE key3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/type/>

TS.QUERYINDEX
=============



```
TS.QUERYINDEX
```
 Syntax 
```
TS.QUERYINDEX filterExpr...

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n) where n is the number of time-series that match the filters  Get all time series keys matching a filter list

 [Examples](#examples)

 Required arguments
------------------

  `filterExpr...` filters time series based on their labels and label values. Each filter expression has one of the following syntaxes: * `label=value`, where `label` equals `value`
* `label!=value`, where `label` does not equal `value`
* `label=`, where `key` does not have label `label`
* `label!=`, where `key` has label `label`
* `label=(value1,value2,...)`, where `key` with label `label` equals one of the values in the list
* `label!=(value1,value2,...)`, where key with label `label` does not equal any of the values in the list

 **Notes:**

 * At least one `label=value` filter is required.
* Filters are conjunctive. For example, the FILTER `type=temperature room=study` means the a time series is a temperature time series of a study room.
* Don't use whitespaces in the filter expression.

  **Note:** The `QUERYINDEX` command cannot be part of transaction when running on a Redis cluster.

 Return value
------------

 Either

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) where each element is a [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): a time series key. The array is empty if no time series matches the filter.
* [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., on invalid filter expression)

 Examples
--------

  **Find keys by location and sensor type** Create a set of sensors to measure temperature and humidity in your study and kitchen.

 
```
127.0.0.1:6379> TS.CREATE telemetry:study:temperature LABELS room study type temperature
OK
127.0.0.1:6379> TS.CREATE telemetry:study:humidity LABELS room study type humidity
OK
127.0.0.1:6379> TS.CREATE telemetry:kitchen:temperature LABELS room kitchen type temperature
OK
127.0.0.1:6379> TS.CREATE telemetry:kitchen:humidity LABELS room kitchen type humidity
OK
```
 Retrieve keys of all time series representing sensors located in the kitchen.

 
```
127.0.0.1:6379> TS.QUERYINDEX room=kitchen
1) "telemetry:kitchen:humidity"
2) "telemetry:kitchen:temperature"
```
 To retrieve the keys of all time series representing sensors that measure temperature, use this query:

 
```
127.0.0.1:6379> TS.QUERYINDEX type=temperature
1) "telemetry:kitchen:temperature"
2) "telemetry:study:temperature"
```
  See also
--------

 [`TS.CREATE`](../ts.create) | [`TS.MRANGE`](../ts.mrange) | [`TS.MREVRANGE`](../ts.mrevrange) | [`TS.MGET`](../ts.mget)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.queryindex/>

TS.MREVRANGE
============



```
TS.MREVRANGE
```
 Syntax 
```
TS.MREVRANGE fromTimestamp toTimestamp
  [LATEST]
  [FILTER_BY_TS TS...]
  [FILTER_BY_VALUE min max]
  [WITHLABELS | SELECTED_LABELS label...]
  [COUNT count]
  [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]
  FILTER filterExpr...
  [GROUPBY label REDUCE reducer]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.4.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n/m+k) where n = Number of data points, m = Chunk size (data points per chunk), k = Number of data points that are in the requested ranges  Query a range across multiple time series by filters in reverse direction

 [Examples](#examples)

 Required arguments
------------------

  `fromTimestamp` is start timestamp for the range query (integer UNIX timestamp in milliseconds) or `-` to denote the timestamp of the earliest sample amongs all time series that passes `FILTER filterExpr...`.

   `toTimestamp` is end timestamp for the range query (integer UNIX timestamp in milliseconds) or `+` to denote the timestamp of the latest sample amongs all time series that passes `FILTER filterExpr...`.

   `FILTER filterExpr...` filters time series based on their labels and label values. Each filter expression has one of the following syntaxes:

 * `label=value`, where `label` equals `value`
* `label!=value`, where `label` does not equal `value`
* `label=`, where `key` does not have label `label`
* `label!=`, where `key` has label `label`
* `label=(value1,value2,...)`, where `key` with label `label` equals one of the values in the list
* `label!=(value1,value2,...)`, where key with label `label` does not equal any of the values in the list

 **Notes:**

 * At least one `label=value` filter is required.
* Filters are conjunctive. For example, the FILTER `type=temperature room=study` means the a time series is a temperature time series of a study room.
* Don't use whitespaces in the filter expression.

  Optional arguments
------------------

  `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.MREVRANGE also reports the compacted value of the latest possibly partial bucket, given that this bucket's start time falls within `[fromTimestamp, toTimestamp]`. Without `LATEST`, TS.MREVRANGE does not report the latest possibly partial bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest possibly partial bucket is also required. In such a case, use `LATEST`.

   `FILTER_BY_TS ts...` (since RedisTimeSeries v1.6) filters samples by a list of specific timestamps. A sample passes the filter if its exact timestamp is specified and falls within `[fromTimestamp, toTimestamp]`.

   `FILTER_BY_VALUE min max` (since RedisTimeSeries v1.6) filters samples by minimum and maximum values.

   `WITHLABELS` includes in the reply all label-value pairs representing metadata labels of the time series. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

   `SELECTED_LABELS label...` (since RedisTimeSeries v1.6) returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

   `COUNT count` limits the number of returned samples.

   `ALIGN align` (since RedisTimeSeries v1.6) is a time bucket alignment control for `AGGREGATION`. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

 Values include:

 * `start` or `-`: The reference timestamp will be the query start interval time (`fromTimestamp`) which can't be `-`
* `end` or `+`: The reference timestamp will be the query end interval time (`toTimestamp`) which can't be `+`
* A specific timestamp: align the reference timestamp to a specific time

 **Note:** When not provided, alignment is set to `0`.

   `AGGREGATION aggregator bucketDuration` per time series, aggregates samples into time buckets, where:

 * `aggregator` takes one of the following aggregation types:



| `aggregator` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all values |
| `sum` | Sum of all values |
| `min` | Minimum value |
| `max` | Maximum value |
| `range` | Difference between maximum value and minimum value |
| `count` | Number of values |
| `first` | Value with lowest timestamp in the bucket |
| `last` | Value with highest timestamp in the bucket |
| `std.p` | Population standard deviation of the values |
| `std.s` | Sample standard deviation of the values |
| `var.p` | Population variance of the values |
| `var.s` | Sample variance of the values |
| `twa` | Time-weighted average over the bucket's timeframe (since RedisTimeSeries v1.8) |
* `bucketDuration` is duration of each bucket, in milliseconds.

 Without `ALIGN`, bucket start times are multiples of `bucketDuration`.

 With `ALIGN align`, bucket start times are multiples of `bucketDuration` with remainder `align % bucketDuration`.

 The first bucket start time is less than or equal to `fromTimestamp`.

   `[BUCKETTIMESTAMP bt]` (since RedisTimeSeries v1.8) controls how bucket timestamps are reported.

 

| `bt` | Timestamp reported for each bucket |
| --- | --- |
| `-` or `low` | the bucket's start time (default) |
| `+` or `high` | the bucket's end time |
| `~` or `mid` | the bucket's mid time (rounded down if not an integer) |

   `[EMPTY]` (since RedisTimeSeries v1.8) is a flag, which, when specified, reports aggregations also for empty buckets.

 

| `aggregator` | Value reported for each empty bucket |
| --- | --- |
| `sum`, `count` | `0` |
| `last` | The value of the last sample before the bucket's start. `NaN` when no such sample. |
| `twa` | Average value over the bucket's timeframe based on linear interpolation of the last sample before the bucket's start and the first sample after the bucket's end. `NaN` when no such samples. |
| `min`, `max`, `range`, `avg`, `first`, `std.p`, `std.s` | `NaN` |

 Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is reported for buckets that end before the earliest sample or begin after the latest sample in the time series.

   `GROUPBY label REDUCE reducer` (since RedisTimeSeries v1.6) splits time series into groups, each group contains time series that share the same value for the provided label name, then aggregates results in each group.

 When combined with `AGGREGATION` the `GROUPBY`/`REDUCE` is applied post aggregation stage.

 * `label` is label name. A group is created for all time series that share the same value for this label.
* `reducer` is an aggregation type used to aggregate the results in each group.



| `reducer` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all non-NaN values (since RedisTimeSeries v1.8) |
| `sum` | Sum of all non-NaN values |
| `min` | Minimum non-NaN value |
| `max` | Maximum non-NaN value |
| `range` | Difference between maximum non-NaN value and minimum non-NaN value (since RedisTimeSeries v1.8) |
| `count` | Number of non-NaN values (since RedisTimeSeries v1.8) |
| `std.p` | Population standard deviation of all non-NaN values (since RedisTimeSeries v1.8) |
| `std.s` | Sample standard deviation of all non-NaN values (since RedisTimeSeries v1.8) |
| `var.p` | Population variance of all non-NaN values (since RedisTimeSeries v1.8) |
| `var.s` | Sample variance of all non-NaN values (since RedisTimeSeries v1.8) |

 **Notes:**

 * The produced time series is named `<label>=<value>`
* The produced time series contains two labels with these label array structures:
	+ `__reducer__`, the reducer used (e.g., `"count"`)
	+ `__source__`, the list of time series keys used to compute the grouped series (e.g., `"key1,key2,key3"`)

  **Note:** An `MREVRANGE` command cannot be part of a transaction when running on a Redis cluster.

 Return value
------------

 If `GROUPBY label REDUCE reducer` is not specified:

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): for each time series matching the specified filters, the following is reported:
	+ bulk-string-reply: The time series key name
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): label-value pairs ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings))
		- By default, an empty list is reported
		- If `WITHLABELS` is specified, all labels associated with this time series are reported
		- If `SELECTED_LABELS label...` is specified, the selected labels are reported
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): timestamp-value pairs ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) (double)): all samples/aggregations matching the range

 If `GROUPBY label REDUCE reducer` is specified:

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): for each group of time series matching the specified filters, the following is reported:
	+ bulk-string-reply with the format `label=value` where `label` is the `GROUPBY` label argument
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the `GROUPBY` label argument and value
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the string `__reducer__` and the reducer argument
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the string `__source__` and the time series key names separated by `,`
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): timestamp-value pairs ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) (double)): all samples/aggregations matching the range

 Examples
--------

  **Retrieve maximum stock price per timestamp** Create two stocks and add their prices at three different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.CREATE stock:B LABELS type stock name B
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:B 1000 120 stock:B 1010 110 stock:B 1020 100
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
```
 You can now retrieve the maximum stock price per timestamp.

 
```
127.0.0.1:6379> TS.MREVRANGE - + WITHLABELS FILTER type=stock GROUPBY type REDUCE max
1) 1) "type=stock"
 2) 1) 1) "type"
 2) "stock"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "stock:A,stock:B"
 3) 1) 1) (integer) 1020
 2) 120
 2) 1) (integer) 1010
 2) 110
 3) 1) (integer) 1000
 2) 120
```
 The `FILTER type=stock` clause returns a single time series representing stock prices. The `GROUPBY type REDUCE max` clause splits the time series into groups with identical type values, and then, for each timestamp, aggregates all series that share the same type value using the max aggregator.

   **Calculate average stock price and retrieve maximum average** Create two stocks and add their prices at nine different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.CREATE stock:B LABELS type stock name B
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:B 1000 120 stock:B 1010 110 stock:B 1020 100
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:A 2000 200 stock:A 2010 210 stock:A 2020 220
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:B 2000 220 stock:B 2010 210 stock:B 2020 200
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:A 3000 300 stock:A 3010 310 stock:A 3020 320
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
127.0.0.1:6379> TS.MADD stock:B 3000 320 stock:B 3010 310 stock:B 3020 300
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
```
 Now, for each stock, calculate the average stock price per a 1000-millisecond timeframe, and then retrieve the stock with the maximum average for that timeframe in reverse direction.

 
```
127.0.0.1:6379> TS.MREVRANGE - + WITHLABELS AGGREGATION avg 1000 FILTER type=stock GROUPBY type REDUCE max
1) 1) "type=stock"
 2) 1) 1) "type"
 2) "stock"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "stock:A,stock:B"
 3) 1) 1) (integer) 3000
 2) 310
 2) 1) (integer) 2000
 2) 210
 3) 1) (integer) 1000
 2) 110
```
   **Group query results** Query all time series with the metric label equal to `cpu`, then group the time series by the value of their `metric_name` label value and for each group return the maximum value and the time series keys (*source*) with that value.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user
(integer) 1548149180000
127.0.0.1:6379> TS.MREVRANGE - + WITHLABELS FILTER metric=cpu GROUPBY metric\_name REDUCE max
1) 1) "metric\_name=system"
 2) 1) 1) "metric\_name"
 2) "system"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "ts1"
 3) 1) 1) (integer) 1548149185000
 2) 45
 2) 1) (integer) 1548149180000
 2) 90
2) 1) "metric\_name=user"
 2) 1) 1) "metric\_name"
 2) "user"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "ts2"
 3) 1) 1) (integer) 1548149180000
 2) 99
```
   **Filter query by value** Query all time series with the metric label equal to `cpu`, then filter values larger or equal to 90.0 and smaller or equal to 100.0.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user
(integer) 1548149180000
127.0.0.1:6379> TS.MREVRANGE - + FILTER\_BY\_VALUE 90 100 WITHLABELS FILTER metric=cpu
1) 1) "ts1"
 2) 1) 1) "metric"
 2) "cpu"
 2) 1) "metric\_name"
 2) "system"
 3) 1) 1) (integer) 1548149180000
 2) 90
2) 1) "ts2"
 2) 1) 1) "metric"
 2) "cpu"
 2) 1) "metric\_name"
 2) "user"
 3) 1) 1) (integer) 1548149180000
 2) 99
```
   **Query using a label** Query all time series with the metric label equal to `cpu`, but only return the team label.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system team NY
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user team SF
(integer) 1548149180000
127.0.0.1:6379> TS.MREVRANGE - + SELECTED\_LABELS team FILTER metric=cpu
1) 1) "ts1"
 2) 1) 1) "team"
 2) (nil)
 3) 1) 1) (integer) 1548149185000
 2) 45
 2) 1) (integer) 1548149180000
 2) 90
2) 1) "ts2"
 2) 1) 1) "team"
 2) (nil)
 3) 1) 1) (integer) 1548149180000
 2) 99
```
  See also
--------

 [`TS.MRANGE`](../ts.mrange) | [`TS.RANGE`](../ts.range) | [`TS.REVRANGE`](../ts.revrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.mrevrange/>

TS.MRANGE
=========



```
TS.MRANGE
```
 Syntax 
```
TS.MRANGE fromTimestamp toTimestamp
  [LATEST]
  [FILTER_BY_TS ts...]
  [FILTER_BY_VALUE min max]
  [WITHLABELS | SELECTED_LABELS label...]
  [COUNT count]
  [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]
  FILTER filterExpr...
  [GROUPBY label REDUCE reducer]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n/m+k) where n = Number of data points, m = Chunk size (data points per chunk), k = Number of data points that are in the requested ranges  Query a range across multiple time series by filters in forward direction

 [Examples](#examples)

 Required arguments
------------------

  `fromTimestamp` is start timestamp for the range query (integer UNIX timestamp in milliseconds) or `-` to denote the timestamp of the earliest sample amongs all time series that passes `FILTER filterExpr...`.

   `toTimestamp` is end timestamp for the range query (integer UNIX timestamp in milliseconds) or `+` to denote the timestamp of the latest sample amongs all time series that passes `FILTER filterExpr...`.

   `FILTER filterExpr...` filters time series based on their labels and label values. Each filter expression has one of the following syntaxes:

 * `label=value`, where `label` equals `value`
* `label!=value`, where `label` does not equal `value`
* `label=`, where `key` does not have label `label`
* `label!=`, where `key` has label `label`
* `label=(value1,value2,...)`, where `key` with label `label` equals one of the values in the list
* `label!=(value1,value2,...)`, where key with label `label` does not equal any of the values in the list

 **Notes:**

 * At least one `label=value` filter is required.
* Filters are conjunctive. For example, the FILTER `type=temperature room=study` means the a time series is a temperature time series of a study room.
* Don't use whitespaces in the filter expression.

  Optional arguments
------------------

  `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.MRANGE also reports the compacted value of the latest possibly partial bucket, given that this bucket's start time falls within `[fromTimestamp, toTimestamp]`. Without `LATEST`, TS.MRANGE does not report the latest possibly partial bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest possibly partial bucket is also required. In such a case, use `LATEST`.

   `FILTER_BY_TS ts...` (since RedisTimeSeries v1.6) filters samples by a list of specific timestamps. A sample passes the filter if its exact timestamp is specified and falls within `[fromTimestamp, toTimestamp]`.

   `FILTER_BY_VALUE min max` (since RedisTimeSeries v1.6) filters samples by minimum and maximum values.

   `WITHLABELS` includes in the reply all label-value pairs representing metadata labels of the time series. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

   `SELECTED_LABELS label...` (since RedisTimeSeries v1.6) returns a subset of the label-value pairs that represent metadata labels of the time series. Use when a large number of labels exists per series, but only the values of some of the labels are required. If `WITHLABELS` or `SELECTED_LABELS` are not specified, by default, an empty list is reported as label-value pairs.

   `COUNT count` limits the number of returned samples.

   `ALIGN align` (since RedisTimeSeries v1.6) is a time bucket alignment control for `AGGREGATION`. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

 Values include:

 * `start` or `-`: The reference timestamp will be the query start interval time (`fromTimestamp`) which can't be `-`
* `end` or `+`: The reference timestamp will be the query end interval time (`toTimestamp`) which can't be `+`
* A specific timestamp: align the reference timestamp to a specific time

 **Note:** When not provided, alignment is set to `0`.

   `AGGREGATION aggregator bucketDuration` per time series, aggregates samples into time buckets, where:

 * `aggregator` takes one of the following aggregation types:



| `aggregator` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all values |
| `sum` | Sum of all values |
| `min` | Minimum value |
| `max` | Maximum value |
| `range` | Difference between maximum value and minimum value |
| `count` | Number of values |
| `first` | Value with lowest timestamp in the bucket |
| `last` | Value with highest timestamp in the bucket |
| `std.p` | Population standard deviation of the values |
| `std.s` | Sample standard deviation of the values |
| `var.p` | Population variance of the values |
| `var.s` | Sample variance of the values |
| `twa` | Time-weighted average over the bucket's timeframe (since RedisTimeSeries v1.8) |
* `bucketDuration` is duration of each bucket, in milliseconds.

 Without `ALIGN`, bucket start times are multiples of `bucketDuration`.

 With `ALIGN align`, bucket start times are multiples of `bucketDuration` with remainder `align % bucketDuration`.

 The first bucket start time is less than or equal to `fromTimestamp`.

   `[BUCKETTIMESTAMP bt]` (since RedisTimeSeries v1.8) controls how bucket timestamps are reported.

 

| `bt` | Timestamp reported for each bucket |
| --- | --- |
| `-` or `low` | the bucket's start time (default) |
| `+` or `high` | the bucket's end time |
| `~` or `mid` | the bucket's mid time (rounded down if not an integer) |

   `[EMPTY]` (since RedisTimeSeries v1.8) is a flag, which, when specified, reports aggregations also for empty buckets.

 

| `aggregator` | Value reported for each empty bucket |
| --- | --- |
| `sum`, `count` | `0` |
| `last` | The value of the last sample before the bucket's start. `NaN` when no such sample. |
| `twa` | Average value over the bucket's timeframe based on linear interpolation of the last sample before the bucket's start and the first sample after the bucket's end. `NaN` when no such samples. |
| `min`, `max`, `range`, `avg`, `first`, `std.p`, `std.s` | `NaN` |

 Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is reported for buckets that end before the earliest sample or begin after the latest sample in the time series.

   `GROUPBY label REDUCE reducer` (since RedisTimeSeries v1.6) splits time series into groups, each group contains time series that share the same value for the provided label name, then aggregates results in each group.

 When combined with `AGGREGATION` the `GROUPBY`/`REDUCE` is applied post aggregation stage.

 * `label` is label name. A group is created for all time series that share the same value for this label.
* `reducer` is an aggregation type used to aggregate the results in each group.



| `reducer` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all non-NaN values (since RedisTimeSeries v1.8) |
| `sum` | Sum of all non-NaN values |
| `min` | Minimum non-NaN value |
| `max` | Maximum non-NaN value |
| `range` | Difference between maximum non-NaN value and minimum non-NaN value (since RedisTimeSeries v1.8) |
| `count` | Number of non-NaN values (since RedisTimeSeries v1.8) |
| `std.p` | Population standard deviation of all non-NaN values (since RedisTimeSeries v1.8) |
| `std.s` | Sample standard deviation of all non-NaN values (since RedisTimeSeries v1.8) |
| `var.p` | Population variance of all non-NaN values (since RedisTimeSeries v1.8) |
| `var.s` | Sample variance of all non-NaN values (since RedisTimeSeries v1.8) |

 **Notes:**

 * The produced time series is named `<label>=<value>`
* The produced time series contains two labels with these label array structures:
	+ `__reducer__`, the reducer used (e.g., `"count"`)
	+ `__source__`, the list of time series keys used to compute the grouped series (e.g., `"key1,key2,key3"`)

  **Note:** An `MRANGE` command cannot be part of a transaction when running on a Redis cluster.

 Return value
------------

 If `GROUPBY label REDUCE reducer` is not specified:

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): for each time series matching the specified filters, the following is reported:
	+ bulk-string-reply: The time series key name
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): label-value pairs ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings))
		- By default, an empty array is reported
		- If `WITHLABELS` is specified, all labels associated with this time series are reported
		- If `SELECTED_LABELS label...` is specified, the selected labels are reported (null value when no such label defined)
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): timestamp-value pairs ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) (double)): all samples/aggregations matching the range

 If `GROUPBY label REDUCE reducer` is specified:

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): for each group of time series matching the specified filters, the following is reported:
	+ bulk-string-reply with the format `label=value` where `label` is the `GROUPBY` label argument
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): label-value pairs ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)):
		- By default, an empty array is reported
		- If `WITHLABELS` is specified, the `GROUPBY` label argument and value are reported
		- If `SELECTED_LABELS label...` is specified, the selected labels are reported (null value when no such label defined or label does not have the same value for all grouped time series)
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): either a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the `GROUPBY` label argument and value, or empty array if
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the string `__reducer__` and the reducer argument
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a single pair ([Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings)): the string `__source__` and the time series key names separated by `,`
	+ [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): timestamp-value pairs ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings) (double)): all samples/aggregations matching the range

 Examples
--------

  **Retrieve maximum stock price per timestamp** Create two stocks and add their prices at three different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.CREATE stock:B LABELS type stock name B
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:B 1000 120 stock:B 1010 110 stock:B 1020 100
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
```
 You can now retrieve the maximum stock price per timestamp.

 
```
127.0.0.1:6379> TS.MRANGE - + WITHLABELS FILTER type=stock GROUPBY type REDUCE max
1) 1) "type=stock"
 2) 1) 1) "type"
 2) "stock"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "stock:A,stock:B"
 3) 1) 1) (integer) 1000
 2) 120
 2) 1) (integer) 1010
 2) 110
 3) 1) (integer) 1020
 2) 120
```
 The `FILTER type=stock` clause returns a single time series representing stock prices. The `GROUPBY type REDUCE max` clause splits the time series into groups with identical type values, and then, for each timestamp, aggregates all series that share the same type value using the max aggregator.

   **Calculate average stock price and retrieve maximum average** Create two stocks and add their prices at nine different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.CREATE stock:B LABELS type stock name B
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:B 1000 120 stock:B 1010 110 stock:B 1020 100
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:A 2000 200 stock:A 2010 210 stock:A 2020 220
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:B 2000 220 stock:B 2010 210 stock:B 2020 200
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:A 3000 300 stock:A 3010 310 stock:A 3020 320
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
127.0.0.1:6379> TS.MADD stock:B 3000 320 stock:B 3010 310 stock:B 3020 300
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
```
 Now, for each stock, calculate the average stock price per a 1000-millisecond timeframe, and then retrieve the stock with the maximum average for that timeframe.

 
```
127.0.0.1:6379> TS.MRANGE - + WITHLABELS AGGREGATION avg 1000 FILTER type=stock GROUPBY type REDUCE max
1) 1) "type=stock"
 2) 1) 1) "type"
 2) "stock"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "stock:A,stock:B"
 3) 1) 1) (integer) 1000
 2) 110
 2) 1) (integer) 2000
 2) 210
 3) 1) (integer) 3000
 2) 310
```
   **Group query results** Query all time series with the metric label equal to `cpu`, then group the time series by the value of their `metric_name` label value and for each group return the maximum value and the time series keys (*source*) with that value.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user
(integer) 1548149180000
127.0.0.1:6379> TS.MRANGE - + WITHLABELS FILTER metric=cpu GROUPBY metric\_name REDUCE max
1) 1) "metric\_name=system"
 2) 1) 1) "metric\_name"
 2) "system"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "ts1"
 3) 1) 1) (integer) 1548149180000
 2) 90
 2) 1) (integer) 1548149185000
 2) 45
2) 1) "metric\_name=user"
 2) 1) 1) "metric\_name"
 2) "user"
 2) 1) "\_\_reducer\_\_"
 2) "max"
 3) 1) "\_\_source\_\_"
 2) "ts2"
 3) 1) 1) (integer) 1548149180000
 2) 99
```
   **Filter query by value** Query all time series with the metric label equal to `cpu`, then filter values larger or equal to 90.0 and smaller or equal to 100.0.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user
(integer) 1548149180000
127.0.0.1:6379> TS.MRANGE - + FILTER\_BY\_VALUE 90 100 WITHLABELS FILTER metric=cpu
1) 1) "ts1"
 2) 1) 1) "metric"
 2) "cpu"
 2) 1) "metric\_name"
 2) "system"
 3) 1) 1) (integer) 1548149180000
 2) 90
2) 1) "ts2"
 2) 1) 1) "metric"
 2) "cpu"
 2) 1) "metric\_name"
 2) "user"
 3) 1) 1) (integer) 1548149180000
 2) 99
```
   **Query using a label** Query all time series with the metric label equal to `cpu`, but only return the team label.

 
```
127.0.0.1:6379> TS.ADD ts1 1548149180000 90 labels metric cpu metric\_name system team NY
(integer) 1548149180000
127.0.0.1:6379> TS.ADD ts1 1548149185000 45
(integer) 1548149185000
127.0.0.1:6379> TS.ADD ts2 1548149180000 99 labels metric cpu metric\_name user team SF
(integer) 1548149180000
127.0.0.1:6379> TS.MRANGE - + SELECTED\_LABELS team FILTER metric=cpu
1) 1) "ts1"
 2) 1) 1) "team"
 2) "NY"
 3) 1) 1) (integer) 1548149180000
 2) 90
 2) 1) (integer) 1548149185000
 2) 45
2) 1) "ts2"
 2) 1) 1) "team"
 2) "SF"
 3) 1) 1) (integer) 1548149180000
 2) 99
```
  See also
--------

 [`TS.RANGE`](../ts.range) | [`TS.MREVRANGE`](../ts.mrevrange) | [`TS.REVRANGE`](../ts.revrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.mrange/>

TS.RANGE
========



```
TS.RANGE
```
 Syntax 
```
TS.RANGE key fromTimestamp toTimestamp
  [LATEST]
  [FILTER_BY_TS ts...]
  [FILTER_BY_VALUE min max]
  [COUNT count] 
  [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n/m+k) where n = Number of data points, m = Chunk size (data points per chunk), k = Number of data points that are in the requested range  Query a range in forward direction

 [Examples](#examples)

 Required arguments
------------------

  `key` is the key name for the time series.

   `fromTimestamp` is start timestamp for the range query (integer UNIX timestamp in milliseconds) or `-` to denote the timestamp of the earliest sample in the time series.

   `toTimestamp` is end timestamp for the range query (integer UNIX timestamp in milliseconds) or `+` to denote the timestamp of the latest sample in the time series.

 **Note:** When the time series is a compaction, the last compacted value may aggregate raw values with timestamp beyond `toTimestamp`. That is because `toTimestamp` only limits the timestamp of the compacted value, which is the start time of the raw bucket that was compacted.

  Optional arguments
------------------

  `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.RANGE also reports the compacted value of the latest, possibly partial, bucket, given that this bucket's start time falls within `[fromTimestamp, toTimestamp]`. Without `LATEST`, TS.RANGE does not report the latest, possibly partial, bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest, possibly partial, bucket is also required. In such a case, use `LATEST`.

   `FILTER_BY_TS ts...` (since RedisTimeSeries v1.6) filters samples by a list of specific timestamps. A sample passes the filter if its exact timestamp is specified and falls within `[fromTimestamp, toTimestamp]`.

   `FILTER_BY_VALUE min max` (since RedisTimeSeries v1.6) filters samples by minimum and maximum values.

   `COUNT count` limits the number of returned samples.

   `ALIGN align` (since RedisTimeSeries v1.6) is a time bucket alignment control for `AGGREGATION`. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined.

 `align` values include:

 * `start` or `-`: The reference timestamp will be the query start interval time (`fromTimestamp`) which can't be `-`
* `end` or `+`: The reference timestamp will be the query end interval time (`toTimestamp`) which can't be `+`
* A specific timestamp: align the reference timestamp to a specific time

 **Note:** When not provided, alignment is set to `0`.

   `AGGREGATION aggregator bucketDuration` aggregates samples into time buckets, where:

 * `aggregator` takes one of the following aggregation types:



| `aggregator` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all values |
| `sum` | Sum of all values |
| `min` | Minimum value |
| `max` | Maximum value |
| `range` | Difference between the maximum and the minimum value |
| `count` | Number of values |
| `first` | Value with lowest timestamp in the bucket |
| `last` | Value with highest timestamp in the bucket |
| `std.p` | Population standard deviation of the values |
| `std.s` | Sample standard deviation of the values |
| `var.p` | Population variance of the values |
| `var.s` | Sample variance of the values |
| `twa` | Time-weighted average over the bucket's timeframe (since RedisTimeSeries v1.8) |
* `bucketDuration` is duration of each bucket, in milliseconds.

 Without `ALIGN`, bucket start times are multiples of `bucketDuration`.

 With `ALIGN align`, bucket start times are multiples of `bucketDuration` with remainder `align % bucketDuration`.

 The first bucket start time is less than or equal to `fromTimestamp`.

   `[BUCKETTIMESTAMP bt]` (since RedisTimeSeries v1.8) controls how bucket timestamps are reported.

 

| `bt` | Timestamp reported for each bucket |
| --- | --- |
| `-` or `low` | the bucket's start time (default) |
| `+` or `high` | the bucket's end time |
| `~` or `mid` | the bucket's mid time (rounded down if not an integer) |

   `[EMPTY]` (since RedisTimeSeries v1.8) is a flag, which, when specified, reports aggregations also for empty buckets.

 

| `aggregator` | Value reported for each empty bucket |
| --- | --- |
| `sum`, `count` | `0` |
| `last` | The value of the last sample before the bucket's start. `NaN` when no such sample. |
| `twa` | Average value over the bucket's timeframe based on linear interpolation of the last sample before the bucket's start and the first sample after the bucket's end. `NaN` when no such samples. |
| `min`, `max`, `range`, `avg`, `first`, `std.p`, `std.s` | `NaN` |

 Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is reported for buckets that end before the earliest sample or begin after the latest sample in the time series.

  Return value
------------

 Either

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)) pairs representing (timestamp, value(double))
* [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., on invalid filter value)

 Complexity
----------

 TS.RANGE complexity can be improved in the future by using binary search to find the start of the range, which makes this `O(Log(n/m)+k*m)`. But, because `m` is small, you can disregard it and look at the operation as `O(Log(n)+k)`.

 Examples
--------

 **Filter results by timestamp or sample value** Consider a metric where acceptable values are between -100 and 100, and the value 9999 is used as an indication of bad measurement.

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
127.0.0.1:6379> TS.MADD temp:TLV 1000 30 temp:TLV 1010 35 temp:TLV 1020 9999 temp:TLV 1030 40
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1030
```
 Now, retrieve all values except out-of-range values.

 
```
TS.RANGE temp:TLV - + FILTER\_BY\_VALUE -100 100
1) 1) (integer) 1000
 2) 30
2) 1) (integer) 1010
 2) 35
3) 1) (integer) 1030
 2) 40
```
 Now, retrieve the average value, while ignoring out-of-range values.

 
```
TS.RANGE temp:TLV - + FILTER\_BY\_VALUE -100 100 AGGREGATION avg 1000
1) 1) (integer) 1000
 2) 35
```
  **Align aggregation buckets** To demonstrate alignment, let’s create a stock and add prices at nine different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:A 2000 200 stock:A 2010 210 stock:A 2020 220
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:A 3000 300 stock:A 3010 310 stock:A 3020 320
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
```
 Next, aggregate without using `ALIGN`, defaulting to alignment 0.

 
```
127.0.0.1:6379> TS.RANGE stock:A - + AGGREGATION min 20
1) 1) (integer) 1000
 2) 100
2) 1) (integer) 1020
 2) 120
3) 1) (integer) 1040
 2) 210
4) 1) (integer) 1060
 2) 300
5) 1) (integer) 1080
 2) 320
```
 And now set `ALIGN` to 10 to have a bucket start at time 10, and align all the buckets with a 20 milliseconds duration.

 
```
127.0.0.1:6379> TS.RANGE stock:A - + ALIGN 10 AGGREGATION min 20
1) 1) (integer) 990
 2) 100
2) 1) (integer) 1010
 2) 110
3) 1) (integer) 1990
 2) 200
4) 1) (integer) 2010
 2) 210
5) 1) (integer) 2990
 2) 300
6) 1) (integer) 3010
 2) 310
```
 When the start timestamp for the range query is explicitly stated (not `-`), you can set `ALIGN` to that time by setting align to `-` or to `start`.

 
```
127.0.0.1:6379> TS.RANGE stock:A 5 + ALIGN - AGGREGATION min 20
1) 1) (integer) 985
 2) 100
2) 1) (integer) 1005
 2) 110
3) 1) (integer) 1985
 2) 200
4) 1) (integer) 2005
 2) 210
5) 1) (integer) 2985
 2) 300
6) 1) (integer) 3005
 2) 310
```
 Similarly, when the end timestamp for the range query is explicitly stated, you can set `ALIGN` to that time by setting align to `+` or to `end`.

  See also
--------

 [`TS.MRANGE`](../ts.mrange) | [`TS.REVRANGE`](../ts.revrange) | [`TS.MREVRANGE`](../ts.mrevrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.range/>

UNSUBSCRIBE
===========



```
UNSUBSCRIBE
```
 Syntax 
```
UNSUBSCRIBE [channel [channel ...]]
```
  Available since: 2.0.0 Time complexity: O(N) where N is the number of clients already subscribed to a channel. ACL categories:  `@pubsub`, `@slow`,   Unsubscribes the client from the given channels, or from all of them if none is given.

 When no channels are specified, the client is unsubscribed from all the previously subscribed channels. In this case, a message for every unsubscribed channel will be sent to the client.

 Return
------

 When successful, this command doesn't return anything. Instead, for each channel, one message with the first element being the string "unsubscribe" is pushed as a confirmation that the command succeeded.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/unsubscribe/>

WAIT
====



```
WAIT
```
 Syntax 
```
WAIT numreplicas timeout
```
  Available since: 3.0.0 Time complexity: O(1) ACL categories:  `@slow`, `@connection`,   This command blocks the current client until all the previous write commands are successfully transferred and acknowledged by at least the specified number of replicas. If the timeout, specified in milliseconds, is reached, the command returns even if the specified number of replicas were not yet reached.

 The command **will always return** the number of replicas that acknowledged the write commands sent by the current client before the `WAIT` command, both in the case where the specified number of replicas are reached, or when the timeout is reached.

 A few remarks:

 1. When `WAIT` returns, all the previous write commands sent in the context of the current connection are guaranteed to be received by the number of replicas returned by `WAIT`.
2. If the command is sent as part of a [`MULTI`](../multi) transaction (since Redis 7.0, any context that does not allow blocking, such as inside scripts), the command does not block but instead just return ASAP the number of replicas that acknowledged the previous write commands.
3. A timeout of 0 means to block forever.
4. Since `WAIT` returns the number of replicas reached both in case of failure and success, the client should check that the returned value is equal or greater to the replication level it demanded.

 Consistency and WAIT
--------------------

 Note that `WAIT` does not make Redis a strongly consistent store: while synchronous replication is part of a replicated state machine, it is not the only thing needed. However in the context of Sentinel or Redis Cluster failover, `WAIT` improves the real world data safety.

 Specifically if a given write is transferred to one or more replicas, it is more likely (but not guaranteed) that if the master fails, we'll be able to promote, during a failover, a replica that received the write: both Sentinel and Redis Cluster will do a best-effort attempt to promote the best replica among the set of available replicas.

 However this is just a best-effort attempt so it is possible to still lose a write synchronously replicated to multiple replicas.

 Implementation details
----------------------

 Since the introduction of partial resynchronization with replicas (PSYNC feature) Redis replicas asynchronously ping their master with the offset they already processed in the replication stream. This is used in multiple ways:

 1. Detect timed out replicas.
2. Perform a partial resynchronization after a disconnection.
3. Implement `WAIT`.

 In the specific case of the implementation of `WAIT`, Redis remembers, for each client, the replication offset of the produced replication stream when a given write command was executed in the context of a given client. When `WAIT` is called Redis checks if the specified number of replicas already acknowledged this offset or a greater one.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The command returns the number of replicas reached by all the writes performed in the context of the current connection.

 Examples
--------

 
```
> SET foo bar
OK
> WAIT 1 0
(integer) 1
> WAIT 2 1000
(integer) 1

```

In the following example the first call to `WAIT` does not use a timeout and asks for the write to reach 1 replica. It returns with success. In the second attempt instead we put a timeout, and ask for the replication of the write to two replicas. Since there is a single replica available, after one second `WAIT` unblocks and returns 1, the number of replicas reached.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/wait/>

TS.REVRANGE
===========



```
TS.REVRANGE
```
 Syntax 
```
TS.REVRANGE key fromTimestamp toTimestamp
  [LATEST]
  [FILTER_BY_TS TS...]
  [FILTER_BY_VALUE min max]
  [COUNT count]
  [[ALIGN align] AGGREGATION aggregator bucketDuration [BUCKETTIMESTAMP bt] [EMPTY]]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.4.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(n/m+k) where n = Number of data points, m = Chunk size (data points per chunk), k = Number of data points that are in the requested range  Query a range in reverse direction

 [Examples](#examples)

 Required arguments
------------------

  `key` is the key name for the time series.

   `fromTimestamp` is start timestamp for the range query (integer UNIX timestamp in milliseconds) or `-` to denote the timestamp of the earliest sample in the time series.

   `toTimestamp` is end timestamp for the range query (integer UNIX timestamp in milliseconds) or `+` to denote the timestamp of the latest sample in the time series.

 **Note:** When the time series is a compaction, the last compacted value may aggregate raw values with timestamp beyond `toTimestamp`. That is because `toTimestamp` limits only the timestamp of the compacted value, which is the start time of the raw bucket that was compacted.

  Optional arguments
------------------

  `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.REVRANGE also reports the compacted value of the latest, possibly partial, bucket, given that this bucket's start time falls within `[fromTimestamp, toTimestamp]`. Without `LATEST`, TS.REVRANGE does not report the latest, possibly partial, bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest, possibly partial, bucket is also required. In such a case, use `LATEST`.

   `FILTER_BY_TS ts...` (since RedisTimeSeries v1.6) filters samples by a list of specific timestamps. A sample passes the filter if its exact timestamp is specified and falls within `[fromTimestamp, toTimestamp]`.

   `FILTER_BY_VALUE min max` (since RedisTimeSeries v1.6) filters samples by minimum and maximum values.

   `COUNT count` limits the number of returned samples.   `ALIGN align` (since RedisTimeSeries v1.6) is a time bucket alignment control for `AGGREGATION`. It controls the time bucket timestamps by changing the reference timestamp on which a bucket is defined. Values include:

 * `start` or `-`: The reference timestamp will be the query start interval time (`fromTimestamp`) which can't be `-`
* `end` or `+`: The reference timestamp will be the query end interval time (`toTimestamp`) which can't be `+`
* A specific timestamp: align the reference timestamp to a specific time

 **NOTE:** When not provided, alignment is set to `0`.

   `AGGREGATION aggregator bucketDuration` aggregates samples into time buckets, where: * `aggregator` takes one of the following aggregation types:



| `aggregator` | Description |
| --- | --- |
| `avg` | Arithmetic mean of all values |
| `sum` | Sum of all values |
| `min` | Minimum value |
| `max` | Maximum value |
| `range` | Difference between the maximum and the minimum value |
| `count` | Number of values |
| `first` | Value with lowest timestamp in the bucket |
| `last` | Value with highest timestamp in the bucket |
| `std.p` | Population standard deviation of the values |
| `std.s` | Sample standard deviation of the values |
| `var.p` | Population variance of the values |
| `var.s` | Sample variance of the values |
| `twa` | Time-weighted average over the bucket's timeframe (since RedisTimeSeries v1.8) |
* `bucketDuration` is duration of each bucket, in milliseconds.

 Without `ALIGN`, bucket start times are multiples of `bucketDuration`.

 With `ALIGN align`, bucket start times are multiples of `bucketDuration` with remainder `align % bucketDuration`.

 The first bucket start time is less than or equal to `fromTimestamp`.

   `[BUCKETTIMESTAMP bt]` (since RedisTimeSeries v1.8) controls how bucket timestamps are reported.

 

| `bt` | Timestamp reported for each bucket |
| --- | --- |
| `-` or `low` | the bucket's start time (default) |
| `+` or `high` | the bucket's end time |
| `~` or `mid` | the bucket's mid time (rounded down if not an integer) |

   `[EMPTY]` (since RedisTimeSeries v1.8) is a flag, which, when specified, reports aggregations also for empty buckets. 

| `aggregator` | Value reported for each empty bucket |
| --- | --- |
| `sum`, `count` | `0` |
| `last` | The value of the last sample before the bucket's start. `NaN` when no such sample. |
| `twa` | Average value over the bucket's timeframe based on linear interpolation of the last sample before the bucket's start and the first sample after the bucket's end. `NaN` when no such samples. |
| `min`, `max`, `range`, `avg`, `first`, `std.p`, `std.s` | `NaN` |

 Regardless of the values of `fromTimestamp` and `toTimestamp`, no data is reported for buckets that end before the earliest sample or begin after the latest sample in the time series.

  Return value
------------

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)) pairs representing (timestamp, value(double))
* [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., on invalid filter value)

 Complexity
----------

 TS.REVRANGE complexity can be improved in the future by using binary search to find the start of the range, which makes this `O(Log(n/m)+k*m)`. But, because `m` is small, you can disregard it and look at the operation as `O(Log(n)+k)`.

 Examples
--------

  **Filter results by timestamp or sample value** Consider a metric where acceptable values are between -100 and 100, and the value 9999 is used as an indication of bad measurement.

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
127.0.0.1:6379> TS.MADD temp:TLV 1000 30 temp:TLV 1010 35 temp:TLV 1020 9999 temp:TLV 1030 40
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
4) (integer) 1030
```
 Now, retrieve all values except out-of-range values.

 
```
TS.REVRANGE temp:TLV - + FILTER\_BY\_VALUE -100 100
1) 1) (integer) 1030
 2) 40
2) 1) (integer) 1010
 2) 35
3) 1) (integer) 1000
 2) 30
```
 Now, retrieve the average value, while ignoring out-of-range values.

 
```
TS.REVRANGE temp:TLV - + FILTER\_BY\_VALUE -100 100 AGGREGATION avg 1000
1) 1) (integer) 1000
 2) 35
```
   **Align aggregation buckets** To demonstrate alignment, let’s create a stock and add prices at three different timestamps.

 
```
127.0.0.1:6379> TS.CREATE stock:A LABELS type stock name A
OK
127.0.0.1:6379> TS.MADD stock:A 1000 100 stock:A 1010 110 stock:A 1020 120
1) (integer) 1000
2) (integer) 1010
3) (integer) 1020
127.0.0.1:6379> TS.MADD stock:A 2000 200 stock:A 2010 210 stock:A 2020 220
1) (integer) 2000
2) (integer) 2010
3) (integer) 2020
127.0.0.1:6379> TS.MADD stock:A 3000 300 stock:A 3010 310 stock:A 3020 320
1) (integer) 3000
2) (integer) 3010
3) (integer) 3020
```
 Next, aggregate without using `ALIGN`, defaulting to alignment 0.

 
```
127.0.0.1:6379> TS.REVRANGE stock:A - + AGGREGATION min 20
1) 1) (integer) 3020
 2) 320
2) 1) (integer) 3000
 2) 300
3) 1) (integer) 2020
 2) 220
4) 1) (integer) 2000
 2) 200
5) 1) (integer) 1020
 2) 120
6) 1) (integer) 1000
 2) 100
```
 And now set `ALIGN` to 10 to have a bucket start at time 10, and align all the buckets with a 20 milliseconds duration.

 
```
127.0.0.1:6379> TS.REVRANGE stock:A - + ALIGN 10 AGGREGATION min 20
1) 1) (integer) 3010
 2) 310
2) 1) (integer) 2990
 2) 300
3) 1) (integer) 2010
 2) 210
4) 1) (integer) 1990
 2) 200
5) 1) (integer) 1010
 2) 110
6) 1) (integer) 990
 2) 100
```
 When the start timestamp for the range query is explicitly stated (not `-`), you can set ALIGN to that time by setting align to `-` or to `start`.

 
```
127.0.0.1:6379> TS.REVRANGE stock:A 5 + ALIGN - AGGREGATION min 20
1) 1) (integer) 3005
 2) 310
2) 1) (integer) 2985
 2) 300
3) 1) (integer) 2005
 2) 210
4) 1) (integer) 1985
 2) 200
5) 1) (integer) 1005
 2) 110
6) 1) (integer) 985
 2) 100
```
 Similarly, when the end timestamp for the range query is explicitly stated, you can set ALIGN to that time by setting align to `+` or to `end`.

  See also
--------

 [`TS.RANGE`](../ts.range) | [`TS.MRANGE`](../ts.mrange) | [`TS.MREVRANGE`](../ts.mrevrange)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.revrange/>

TS.GET
======



```
TS.GET
```
 Syntax 
```
TS.GET key 
  [LATEST]

```
  Available in:  [Redis Stack](https://redis.io/docs/stack) / [TimeSeries 1.0.0](https://redis.io/docs/stack/timeseries)  Time complexity: O(1)  Get the sample with the highest timestamp from a given time series

 [Examples](#examples)

 Required arguments
------------------

 `key` is key name for the time series.

  Optional arguments
------------------

 `LATEST` (since RedisTimeSeries v1.8) is used when a time series is a compaction. With `LATEST`, TS.GET reports the compacted value of the latest, possibly partial, bucket. Without `LATEST`, TS.GET does not report the latest, possibly partial, bucket. When a time series is not a compaction, `LATEST` is ignored.

 The data in the latest bucket of a compaction is possibly partial. A bucket is *closed* and compacted only upon arrival of a new sample that *opens* a new *latest* bucket. There are cases, however, when the compacted value of the latest, possibly partial, bucket is also required. In such a case, use `LATEST`.

  Return value
------------

 One of:

 * [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) of a single ([Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings)) pair representing (timestamp, value(double)) of the sample with the highest timetamp
* An empty [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays) - when the time series is empty
* [Error reply](https://redis.io/docs/reference/protocol-spec#resp-errors) (e.g., when the key does not exist or when the number of arguments is wrong)

 Examples
--------

  **Get latest measured temperature for a city** Create a time series to store the temperatures measured in Tel Aviv and add four measurements for Sun Jan 01 2023

 
```
127.0.0.1:6379> TS.CREATE temp:TLV LABELS type temp location TLV
OK
127.0.0.1:6379> TS.MADD temp:TLV 1672534800 12 temp:TLV 1672556400 16 temp:TLV 1672578000 21 temp:TLV 1672599600 14
```
 Next, get the latest measured temperature (the temperature with the highest timestamp)

 
```
127.0.0.1:6379> TS.GET temp:TLV
1) (integer) 1672599600
2) 14
```
   **Get latest maximal daily temperature for a city** Create a time series to store the temperatures measured in Jerusalem

 
```
127.0.0.1:6379> TS.CREATE temp:JLM LABELS type temp location JLM
OK
```
 Next, create a compacted time series named *dailyAvgTemp:JLM* containing one compacted sample per 24 hours: the maximum of all measurements taken from midnight to next midnight.

 
```
127.0.0.1:6379> TS.CREATE dailyMaxTemp:JLM LABELS type temp location JLM
OK
127.0.0.1:6379> TS.CREATERULE temp:JLM dailyMaxTemp:JLM AGGREGATION max 86400000
OK
```
 Add four measurements for Sun Jan 01 2023 and three measurements for Mon Jan 02 2023

 
```
127.0.0.1:6379> TS.MADD temp:JLM 1672534800000 12 temp:JLM 1672556400000 16 temp:JLM 1672578000000 21 temp:JLM 1672599600000 14
1) (integer) 1672534800000
2) (integer) 1672556400000
3) (integer) 1672578000000
4) (integer) 1672599600000
127.0.0.1:6379> TS.MADD temp:JLM 1672621200000 11 temp:JLM 1672642800000 21 temp:JLM 1672664400000 26
1) (integer) 1672621200000
2) (integer) 1672642800000
3) (integer) 1672664400000
```
 Next, get the latest maximum daily temperature; do not report the latest, possibly partial, bucket

 
```
127.0.0.1:6379> TS.GET dailyMaxTemp:JLM
1) (integer) 1672531200000
2) 21
```
 Get the latest maximum daily temperature (the temperature with the highest timestamp); report the latest, possibly partial, bucket

 
```
127.0.0.1:6379> TS.GET dailyMaxTemp:JLM LATEST
1) (integer) 1672617600000
2) 26
```
  See also
--------

 [`TS.MGET`](../ts.mget)

 Related topics
--------------

 [RedisTimeSeries](https://redis.io/docs/stack/timeseries)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ts.get/>

UNWATCH
=======



```
UNWATCH
```
 Syntax 
```
UNWATCH
```
  Available since: 2.2.0 Time complexity: O(1) ACL categories:  `@fast`, `@transaction`,   Flushes all the previously watched keys for a [transaction](https://redis.io/topics/transactions).

 If you call [`EXEC`](../exec) or [`DISCARD`](../discard), there's no need to manually call `UNWATCH`.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/unwatch/>

WATCH
=====



```
WATCH
```
 Syntax 
```
WATCH key [key ...]
```
  Available since: 2.2.0 Time complexity: O(1) for every key. ACL categories:  `@fast`, `@transaction`,   Marks the given keys to be watched for conditional execution of a [transaction](https://redis.io/topics/transactions).

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): always `OK`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/watch/>

XAUTOCLAIM
==========



```
XAUTOCLAIM
```
 Syntax 
```
XAUTOCLAIM key group consumer min-idle-time start [COUNT count]
  [JUSTID]
```
  Available since: 6.2.0 Time complexity: O(1) if COUNT is small. ACL categories:  `@write`, `@stream`, `@fast`,   This command transfers ownership of pending stream entries that match the specified criteria. Conceptually, `XAUTOCLAIM` is equivalent to calling [`XPENDING`](../xpending) and then [`XCLAIM`](../xclaim), but provides a more straightforward way to deal with message delivery failures via [`SCAN`](../scan)-like semantics.

 Like [`XCLAIM`](../xclaim), the command operates on the stream entries at `<key>` and in the context of the provided `<group>`. It transfers ownership to `<consumer>` of messages pending for more than `<min-idle-time>` milliseconds and having an equal or greater ID than `<start>`.

 The optional `<count>` argument, which defaults to 100, is the upper limit of the number of entries that the command attempts to claim. Internally, the command begins scanning the consumer group's Pending Entries List (PEL) from `<start>` and filters out entries having an idle time less than or equal to `<min-idle-time>`. The maximum number of pending entries that the command scans is the product of multiplying `<count>`'s value by 10 (hard-coded). It is possible, therefore, that the number of entries claimed will be less than the specified value.

 The optional `JUSTID` argument changes the reply to return just an array of IDs of messages successfully claimed, without returning the actual message. Using this option means the retry counter is not incremented.

 The command returns the claimed entries as an array. It also returns a stream ID intended for cursor-like use as the `<start>` argument for its subsequent call. When there are no remaining PEL entries, the command returns the special `0-0` ID to signal completion. However, note that you may want to continue calling `XAUTOCLAIM` even after the scan is complete with the `0-0` as `<start>` ID, because enough time passed, so older pending entries may now be eligible for claiming.

 Note that only messages that are idle longer than `<min-idle-time>` are claimed, and claiming a message resets its idle time. This ensures that only a single consumer can successfully claim a given pending message at a specific instant of time and trivially reduces the probability of processing the same message multiple times.

 While iterating the PEL, if `XAUTOCLAIM` stumbles upon a message which doesn't exist in the stream anymore (either trimmed or deleted by [`XDEL`](../xdel)) it does not claim it, and deletes it from the PEL in which it was found. This feature was introduced in Redis 7.0. These message IDs are returned to the caller as a part of `XAUTOCLAIM`s reply.

 Lastly, claiming a message with `XAUTOCLAIM` also increments the attempted deliveries count for that message, unless the `JUSTID` option has been specified (which only delivers the message ID, not the message itself). Messages that cannot be processed for some reason - for example, because consumers systematically crash when processing them - will exhibit high attempted delivery counts that can be detected by monitoring.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 An array with three elements:

 1. A stream ID to be used as the `<start>` argument for the next call to `XAUTOCLAIM`.
2. An array containing all the successfully claimed messages in the same format as [`XRANGE`](../xrange).
3. An array containing message IDs that no longer exist in the stream, and were deleted from the PEL in which they were found.

 Examples
--------

 
```
> XAUTOCLAIM mystream mygroup Alice 3600000 0-0 COUNT 25
1) "0-0"
2) 1) 1) "1609338752495-0"
      2) 1) "field"
         2) "value"
3) (empty array)

```

In the above example, we attempt to claim up to 25 entries that are pending and idle (not having been acknowledged or claimed) for at least an hour, starting at the stream's beginning. The consumer "Alice" from the "mygroup" group acquires ownership of these messages. Note that the stream ID returned in the example is `0-0`, indicating that the entire stream was scanned. We can also see that `XAUTOCLAIM` did not stumble upon any deleted messages (the third reply element is an empty array).

 History
-------

 * Starting with Redis version 7.0.0: Added an element to the reply array, containing deleted entries the command cleared from the PEL



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xautoclaim/>

TTL
===



```
TTL
```
 Syntax 
```
TTL key
```
  Available since: 1.0.0 Time complexity: O(1) ACL categories:  `@keyspace`, `@read`, `@fast`,   Returns the remaining time to live of a key that has a timeout. This introspection capability allows a Redis client to check how many seconds a given key will continue to be part of the dataset.

 In Redis 2.6 or older the command returns `-1` if the key does not exist or if the key exist but has no associated expire.

 Starting with Redis 2.8 the return value in case of error changed:

 * The command returns `-2` if the key does not exist.
* The command returns `-1` if the key exists but has no associated expire.

 See also the [`PTTL`](../pttl) command that returns the same information with milliseconds resolution (Only available in Redis 2.6 or greater).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): TTL in seconds, or a negative value in order to signal an error (see the description above).

 Examples
--------

 
```

SET mykey "Hello"
EXPIRE mykey 10
TTL mykey

```
 History
-------

 * Starting with Redis version 2.8.0: Added the -2 reply.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/ttl/>

XACK
====



```
XACK
```
 Syntax 
```
XACK key group id [id ...]
```
  Available since: 5.0.0 Time complexity: O(1) for each message ID processed. ACL categories:  `@write`, `@stream`, `@fast`,   The `XACK` command removes one or multiple messages from the *Pending Entries List* (PEL) of a stream consumer group. A message is pending, and as such stored inside the PEL, when it was delivered to some consumer, normally as a side effect of calling [`XREADGROUP`](../xreadgroup), or when a consumer took ownership of a message calling [`XCLAIM`](../xclaim). The pending message was delivered to some consumer but the server is yet not sure it was processed at least once. So new calls to [`XREADGROUP`](../xreadgroup) to grab the messages history for a consumer (for instance using an ID of 0), will return such message. Similarly the pending message will be listed by the [`XPENDING`](../xpending) command, that inspects the PEL.

 Once a consumer *successfully* processes a message, it should call `XACK` so that such message does not get processed again, and as a side effect, the PEL entry about this message is also purged, releasing memory from the Redis server.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 The command returns the number of messages successfully acknowledged. Certain message IDs may no longer be part of the PEL (for example because they have already been acknowledged), and XACK will not count them as successfully acknowledged.

 Examples
--------

 
```
redis> XACK mystream mygroup 1526569495631-0
(integer) 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xack/>

XADD
====



```
XADD
```
 Syntax 
```
XADD key [NOMKSTREAM] [<MAXLEN | MINID> [= | ~] threshold
  [LIMIT count]] <* | id> field value [field value ...]
```
  Available since: 5.0.0 Time complexity: O(1) when adding a new entry, O(N) when trimming where N being the number of entries evicted. ACL categories:  `@write`, `@stream`, `@fast`,   Appends the specified stream entry to the stream at the specified key. If the key does not exist, as a side effect of running this command the key is created with a stream value. The creation of stream's key can be disabled with the `NOMKSTREAM` option.

 An entry is composed of a list of field-value pairs. The field-value pairs are stored in the same order they are given by the user. Commands that read the stream, such as [`XRANGE`](../xrange) or [`XREAD`](../xread), are guaranteed to return the fields and values exactly in the same order they were added by `XADD`.

 `XADD` is the *only Redis command* that can add data to a stream, but there are other commands, such as [`XDEL`](../xdel) and [`XTRIM`](../xtrim), that are able to remove data from a stream.

 Specifying a Stream ID as an argument
-------------------------------------

 A stream entry ID identifies a given entry inside a stream.

 The `XADD` command will auto-generate a unique ID for you if the ID argument specified is the `*` character (asterisk ASCII character). However, while useful only in very rare cases, it is possible to specify a well-formed ID, so that the new entry will be added exactly with the specified ID.

 IDs are specified by two numbers separated by a `-` character:

 
```
1526919030474-55

```
 Both quantities are 64-bit numbers. When an ID is auto-generated, the first part is the Unix time in milliseconds of the Redis instance generating the ID. The second part is just a sequence number and is used in order to distinguish IDs generated in the same millisecond.

 You can also specify an incomplete ID, that consists only of the milliseconds part, which is interpreted as a zero value for sequence part. To have only the sequence part automatically generated, specify the milliseconds part followed by the `-` separator and the `*` character:

 
```
> XADD mystream 1526919030474-55 message "Hello,"
"1526919030474-55"
> XADD mystream 1526919030474-* message " World!"
"1526919030474-56"

```

IDs are guaranteed to be always incremental: If you compare the ID of the entry just inserted it will be greater than any other past ID, so entries are totally ordered inside a stream. In order to guarantee this property, if the current top ID in the stream has a time greater than the current local time of the instance, the top entry time will be used instead, and the sequence part of the ID incremented. This may happen when, for instance, the local clock jumps backward, or if after a failover the new master has a different absolute time.

 When a user specified an explicit ID to `XADD`, the minimum valid ID is `0-1`, and the user *must* specify an ID which is greater than any other ID currently inside the stream, otherwise the command will fail and return an error. Usually resorting to specific IDs is useful only if you have another system generating unique IDs (for instance an SQL table) and you really want the Redis stream IDs to match the one of this other system.

 Capped streams
--------------

 `XADD` incorporates the same semantics as the [`XTRIM`](../xtrim) command - refer to its documentation page for more information. This allows adding new entries and keeping the stream's size in check with a single call to `XADD`, effectively capping the stream with an arbitrary threshold. Although exact trimming is possible and is the default, due to the internal representation of steams it is more efficient to add an entry and trim stream with `XADD` using **almost exact** trimming (the `~` argument).

 For example, calling `XADD` in the following form:

 
```
XADD mystream MAXLEN ~ 1000 * ... entry fields here ...

```
 Will add a new entry but will also evict old entries so that the stream will contain only 1000 entries, or at most a few tens more.

 Additional information about streams
------------------------------------

 For further information about Redis streams please check our [introduction to Redis Streams document](https://redis.io/topics/streams-intro).

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings), specifically:

 The command returns the ID of the added entry. The ID is the one auto-generated if `*` is passed as ID argument, otherwise the command just returns the same ID specified by the user during insertion.

 The command returns a [Null reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings) when used with the `NOMKSTREAM` option and the key doesn't exist.

 Examples
--------

 
```

XADD mystream * name Sara surname OConnor
XADD mystream * field1 value1 field2 value2 field3 value3
XLEN mystream
XRANGE mystream - +

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `NOMKSTREAM` option, `MINID` trimming strategy and the `LIMIT` option.
* Starting with Redis version 7.0.0: Added support for the `<ms>-*` explicit ID form.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xadd/>

UNLINK
======



```
UNLINK
```
 Syntax 
```
UNLINK key [key ...]
```
  Available since: 4.0.0 Time complexity: O(1) for each key removed regardless of its size. Then the command does O(N) work in a different thread in order to reclaim memory, where N is the number of allocations the deleted objects where composed of. ACL categories:  `@keyspace`, `@write`, `@fast`,   This command is very similar to [`DEL`](../del): it removes the specified keys. Just like [`DEL`](../del) a key is ignored if it does not exist. However the command performs the actual memory reclaiming in a different thread, so it is not blocking, while [`DEL`](../del) is. This is where the command name comes from: the command just **unlinks** the keys from the keyspace. The actual removal will happen later asynchronously.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of keys that were unlinked.

 Examples
--------

 
```

SET key1 "Hello"
SET key2 "World"
UNLINK key1 key2 key3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/unlink/>

XCLAIM
======



```
XCLAIM
```
 Syntax 
```
XCLAIM key group consumer min-idle-time id [id ...] [IDLE ms]
  [TIME unix-time-milliseconds] [RETRYCOUNT count] [FORCE] [JUSTID]
  [LASTID lastid]
```
  Available since: 5.0.0 Time complexity: O(log N) with N being the number of messages in the PEL of the consumer group. ACL categories:  `@write`, `@stream`, `@fast`,   In the context of a stream consumer group, this command changes the ownership of a pending message, so that the new owner is the consumer specified as the command argument. Normally this is what happens:

 1. There is a stream with an associated consumer group.
2. Some consumer A reads a message via [`XREADGROUP`](../xreadgroup) from a stream, in the context of that consumer group.
3. As a side effect a pending message entry is created in the Pending Entries List (PEL) of the consumer group: it means the message was delivered to a given consumer, but it was not yet acknowledged via [`XACK`](../xack).
4. Then suddenly that consumer fails forever.
5. Other consumers may inspect the list of pending messages, that are stale for quite some time, using the [`XPENDING`](../xpending) command. In order to continue processing such messages, they use `XCLAIM` to acquire the ownership of the message and continue. Consumers can also use the [`XAUTOCLAIM`](../xautoclaim) command to automatically scan and claim stale pending messages.

 This dynamic is clearly explained in the [Stream intro documentation](https://redis.io/topics/streams-intro).

 Note that the message is claimed only if its idle time is greater than the minimum idle time we specify when calling `XCLAIM`. Because as a side effect `XCLAIM` will also reset the idle time (since this is a new attempt at processing the message), two consumers trying to claim a message at the same time will never both succeed: only one will successfully claim the message. This avoids that we process a given message multiple times in a trivial way (yet multiple processing is possible and unavoidable in the general case).

 Moreover, as a side effect, `XCLAIM` will increment the count of attempted deliveries of the message unless the `JUSTID` option has been specified (which only delivers the message ID, not the message itself). In this way messages that cannot be processed for some reason, for instance because the consumers crash attempting to process them, will start to have a larger counter and can be detected inside the system.

 `XCLAIM` will not claim a message in the following cases:

 1. The message doesn't exist in the group PEL (i.e. it was never read by any consumer)
2. The message exists in the group PEL but not in the stream itself (i.e. the message was read but never acknowledged, and then was deleted from the stream, either by trimming or by [`XDEL`](../xdel))

 In both cases the reply will not contain a corresponding entry to that message (i.e. the length of the reply array may be smaller than the number of IDs provided to `XCLAIM`). In the latter case, the message will also be deleted from the PEL in which it was found. This feature was introduced in Redis 7.0.

 Command options
---------------

 The command has multiple options, however most are mainly for internal use in order to transfer the effects of `XCLAIM` or other commands to the AOF file and to propagate the same effects to the replicas, and are unlikely to be useful to normal users:

 1. `IDLE <ms>`: Set the idle time (last time it was delivered) of the message. If IDLE is not specified, an IDLE of 0 is assumed, that is, the time count is reset because the message has now a new owner trying to process it.
2. `TIME <ms-unix-time>`: This is the same as IDLE but instead of a relative amount of milliseconds, it sets the idle time to a specific Unix time (in milliseconds). This is useful in order to rewrite the AOF file generating `XCLAIM` commands.
3. `RETRYCOUNT <count>`: Set the retry counter to the specified value. This counter is incremented every time a message is delivered again. Normally `XCLAIM` does not alter this counter, which is just served to clients when the XPENDING command is called: this way clients can detect anomalies, like messages that are never processed for some reason after a big number of delivery attempts.
4. `FORCE`: Creates the pending message entry in the PEL even if certain specified IDs are not already in the PEL assigned to a different client. However the message must be exist in the stream, otherwise the IDs of non existing messages are ignored.
5. `JUSTID`: Return just an array of IDs of messages successfully claimed, without returning the actual message. Using this option means the retry counter is not incremented.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns all the messages successfully claimed, in the same format as [`XRANGE`](../xrange). However if the `JUSTID` option was specified, only the message IDs are reported, without including the actual message.

 Examples
--------

 
```
> XCLAIM mystream mygroup Alice 3600000 1526569498055-0
1) 1) 1526569498055-0
   2) 1) "message"
      2) "orange"

```

In the above example we claim the message with ID `1526569498055-0`, only if the message is idle for at least one hour without the original consumer or some other consumer making progresses (acknowledging or claiming it), and assigns the ownership to the consumer `Alice`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xclaim/>

XDEL
====



```
XDEL
```
 Syntax 
```
XDEL key id [id ...]
```
  Available since: 5.0.0 Time complexity: O(1) for each single item to delete in the stream, regardless of the stream size. ACL categories:  `@write`, `@stream`, `@fast`,   Removes the specified entries from a stream, and returns the number of entries deleted. This number may be less than the number of IDs passed to the command in the case where some of the specified IDs do not exist in the stream.

 Normally you may think at a Redis stream as an append-only data structure, however Redis streams are represented in memory, so we are also able to delete entries. This may be useful, for instance, in order to comply with certain privacy policies.

 Understanding the low level details of entries deletion
-------------------------------------------------------

 Redis streams are represented in a way that makes them memory efficient: a radix tree is used in order to index macro-nodes that pack linearly tens of stream entries. Normally what happens when you delete an entry from a stream is that the entry is not *really* evicted, it just gets marked as deleted.

 Eventually if all the entries in a macro-node are marked as deleted, the whole node is destroyed and the memory reclaimed. This means that if you delete a large amount of entries from a stream, for instance more than 50% of the entries appended to the stream, the memory usage per entry may increment, since what happens is that the stream will become fragmented. However the stream performance will remain the same.

 In future versions of Redis it is possible that we'll trigger a node garbage collection in case a given macro-node reaches a given amount of deleted entries. Currently with the usage we anticipate for this data structure, it is not a good idea to add such complexity.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of entries actually deleted.

 Examples
--------

 
```
> XADD mystream * a 1
1538561698944-0
> XADD mystream * b 2
1538561700640-0
> XADD mystream * c 3
1538561701744-0
> XDEL mystream 1538561700640-0
(integer) 1
127.0.0.1:6379> XRANGE mystream - +
1) 1) 1538561698944-0
   2) 1) "a"
      2) "1"
2) 1) 1538561701744-0
   2) 1) "c"
      2) "3"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xdel/>

XGROUP
======



```
XGROUP CREATECONSUMER
```
 Syntax 
```
XGROUP CREATECONSUMER key group consumer
```
  Available since: 6.2.0 Time complexity: O(1) ACL categories:  `@write`, `@stream`, `@slow`,   Create a consumer named `<consumername>` in the consumer group `<groupname>` of the stream that's stored at `<key>`.

 Consumers are also created automatically whenever an operation, such as [`XREADGROUP`](../xreadgroup), references a consumer that doesn't exist. This is valid for [`XREADGROUP`](../xreadgroup) only when there is data in the stream.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of created consumers (0 or 1)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xgroup-createconsumer/>

XGROUP
======



```
XGROUP CREATE
```
 Syntax 
```
XGROUP CREATE key group <id | $> [MKSTREAM]
  [ENTRIESREAD entries-read]
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@write`, `@stream`, `@slow`,   Create a new consumer group uniquely identified by `<groupname>` for the stream stored at `<key>`

 Every group has a unique name in a given stream. When a consumer group with the same name already exists, the command returns a `-BUSYGROUP` error.

 The command's `<id>` argument specifies the last delivered entry in the stream from the new group's perspective. The special ID `$` is the ID of the last entry in the stream, but you can substitute it with any valid ID.

 For example, if you want the group's consumers to fetch the entire stream from the beginning, use zero as the starting ID for the consumer group:

 
```
XGROUP CREATE mystream mygroup 0

```
 By default, the `XGROUP CREATE` command expects that the target stream exists, and returns an error when it doesn't. If a stream does not exist, you can create it automatically with length of 0 by using the optional `MKSTREAM` subcommand as the last argument after the `<id>`:

 
```
XGROUP CREATE mystream mygroup $ MKSTREAM

```
 To enable consumer group lag tracking, specify the optional `entries_read` named argument with an arbitrary ID. An arbitrary ID is any ID that isn't the ID of the stream's first entry, last entry, or zero ("0-0") ID. Use it to find out how many entries are between the arbitrary ID (excluding it) and the stream's last entry. Set the `entries_read` the stream's `entries_added` subtracted by the number of entries.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success.

 History
-------

 * Starting with Redis version 7.0.0: Added the `entries_read` named argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xgroup-create/>

XGROUP
======



```
XGROUP DELCONSUMER
```
 Syntax 
```
XGROUP DELCONSUMER key group consumer
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@write`, `@stream`, `@slow`,   The `XGROUP DELCONSUMER` command deletes a consumer from the consumer group.

 Sometimes it may be useful to remove old consumers since they are no longer used.

 Note, however, that any pending messages that the consumer had will become unclaimable after it was deleted. It is strongly recommended, therefore, that any pending messages are claimed or acknowledged prior to deleting the consumer from the group.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of pending messages that the consumer had before it was deleted



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xgroup-delconsumer/>

XGROUP
======



```
XGROUP DESTROY
```
 Syntax 
```
XGROUP DESTROY key group
```
  Available since: 5.0.0 Time complexity: O(N) where N is the number of entries in the group's pending entries list (PEL). ACL categories:  `@write`, `@stream`, `@slow`,   The `XGROUP DESTROY` command completely destroys a consumer group.

 The consumer group will be destroyed even if there are active consumers, and pending messages, so make sure to call this command only when really needed.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of destroyed consumer groups (0 or 1)



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xgroup-destroy/>

XREVRANGE
=========



```
XREVRANGE
```
 Syntax 
```
XREVRANGE key end start [COUNT count]
```
  Available since: 5.0.0 Time complexity: O(N) with N being the number of elements returned. If N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1). ACL categories:  `@read`, `@stream`, `@slow`,   This command is exactly like [`XRANGE`](../xrange), but with the notable difference of returning the entries in reverse order, and also taking the start-end range in reverse order: in `XREVRANGE` you need to state the *end* ID and later the *start* ID, and the command will produce all the element between (or exactly like) the two IDs, starting from the *end* side.

 So for instance, to get all the elements from the higher ID to the lower ID one could use:

 
```
XREVRANGE somestream + -

```
 Similarly to get just the last element added into the stream it is enough to send:

 
```
XREVRANGE somestream + - COUNT 1

```
 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns the entries with IDs matching the specified range, from the higher ID to the lower ID matching. The returned entries are complete, that means that the ID and all the fields they are composed are returned. Moreover the entries are returned with their fields and values in the exact same order as [`XADD`](../xadd) added them.

 Examples
--------

 
```

XADD writers * name Virginia surname Woolf
XADD writers * name Jane surname Austen
XADD writers * name Toni surname Morrison
XADD writers * name Agatha surname Christie
XADD writers * name Ngozi surname Adichie
XLEN writers
XREVRANGE writers + - COUNT 1

```
 History
-------

 * Starting with Redis version 6.2.0: Added exclusive ranges.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xrevrange/>

XINFO
=====



```
XINFO CONSUMERS
```
 Syntax 
```
XINFO CONSUMERS key group
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@read`, `@stream`, `@slow`,   This command returns the list of consumers that belong to the `<groupname>` consumer group of the stream stored at `<key>`.

 The following information is provided for each consumer in the group:

 * **name**: the consumer's name
* **pending**: the number of entries in the PEL: pending messages for the consumer, which are messages that were delivered but are yet to be acknowledged
* **idle**: the number of milliseconds that have passed since the consumer's last attempted interaction (Examples: [`XREADGROUP`](../xreadgroup), [`XCLAIM`](../xclaim), [`XAUTOCLAIM`](../xautoclaim))
* **inactive**: the number of milliseconds that have passed since the consumer's last successful interaction (Examples: [`XREADGROUP`](../xreadgroup) that actually read some entries into the PEL, [`XCLAIM`](../xclaim)/[`XAUTOCLAIM`](../xautoclaim) that actually claimed some entries)

 @reply

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of consumers.

 Examples
--------

 
```
> XINFO CONSUMERS mystream mygroup
1) 1) name
   2) "Alice"
   3) pending
   4) (integer) 1
   5) idle
   6) (integer) 9104628
   7) inactive
   8) (integer) 18104698
2) 1) name
   2) "Bob"
   3) pending
   4) (integer) 1
   5) idle
   6) (integer) 83841983
   7) inactive
   8) (integer) 993841998

```
 History
-------

 * Starting with Redis version 7.2.0: Added the `inactive` field.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xinfo-consumers/>

ZDIFF
=====



```
ZDIFF
```
 Syntax 
```
ZDIFF numkeys key [key ...] [WITHSCORES]
```
  Available since: 6.2.0 Time complexity: O(L + (N-K)log(N)) worst case where L is the total number of elements in all the sets, N is the size of the first set, and K is the size of the result set. ACL categories:  `@read`, `@sortedset`, `@slow`,   This command is similar to [`ZDIFFSTORE`](../zdiffstore), but instead of storing the resulting sorted set, it is returned to the client.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): the result of the difference (optionally with their scores, in case the `WITHSCORES` option is given).

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset1 3 "three"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZDIFF 2 zset1 zset2
ZDIFF 2 zset1 zset2 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zdiff/>

ZINCRBY
=======



```
ZINCRBY
```
 Syntax 
```
ZINCRBY key increment member
```
  Available since: 1.2.0 Time complexity: O(log(N)) where N is the number of elements in the sorted set. ACL categories:  `@write`, `@sortedset`, `@fast`,   Increments the score of `member` in the sorted set stored at `key` by `increment`. If `member` does not exist in the sorted set, it is added with `increment` as its score (as if its previous score was `0.0`). If `key` does not exist, a new sorted set with the specified `member` as its sole member is created.

 An error is returned when `key` exists but does not hold a sorted set.

 The `score` value should be the string representation of a numeric value, and accepts double precision floating point numbers. It is possible to provide a negative value to decrement the score.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the new score of `member` (a double precision floating point number), represented as string.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZINCRBY myzset 2 "one"
ZRANGE myzset 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zincrby/>

XREAD
=====



```
XREAD
```
 Syntax 
```
XREAD [COUNT count] [BLOCK milliseconds] STREAMS key [key ...] id
  [id ...]
```
  Available since: 5.0.0 Time complexity: ACL categories:  `@read`, `@stream`, `@slow`, `@blocking`,   Read data from one or multiple streams, only returning entries with an ID greater than the last received ID reported by the caller. This command has an option to block if items are not available, in a similar fashion to [`BRPOP`](../brpop) or [`BZPOPMIN`](../bzpopmin) and others.

 Please note that before reading this page, if you are new to streams, we recommend to read [our introduction to Redis Streams](https://redis.io/topics/streams-intro).

 Non-blocking usage
------------------

 If the **BLOCK** option is not used, the command is synchronous, and can be considered somewhat related to [`XRANGE`](../xrange): it will return a range of items inside streams, however it has two fundamental differences compared to [`XRANGE`](../xrange) even if we just consider the synchronous usage:

 * This command can be called with multiple streams if we want to read at the same time from a number of keys. This is a key feature of `XREAD` because especially when blocking with **BLOCK**, to be able to listen with a single connection to multiple keys is a vital feature.
* While [`XRANGE`](../xrange) returns items in a range of IDs, `XREAD` is more suited in order to consume the stream starting from the first entry which is greater than any other entry we saw so far. So what we pass to `XREAD` is, for each stream, the ID of the last element that we received from that stream.

 For example, if I have two streams `mystream` and `writers`, and I want to read data from both the streams starting from the first element they contain, I could call `XREAD` like in the following example.

 Note: we use the **COUNT** option in the example, so that for each stream the call will return at maximum two elements per stream.

 
```
> XREAD COUNT 2 STREAMS mystream writers 0-0 0-0
1) 1) "mystream"
   2) 1) 1) 1526984818136-0
         2) 1) "duration"
            2) "1532"
            3) "event-id"
            4) "5"
            5) "user-id"
            6) "7782813"
      2) 1) 1526999352406-0
         2) 1) "duration"
            2) "812"
            3) "event-id"
            4) "9"
            5) "user-id"
            6) "388234"
2) 1) "writers"
   2) 1) 1) 1526985676425-0
         2) 1) "name"
            2) "Virginia"
            3) "surname"
            4) "Woolf"
      2) 1) 1526985685298-0
         2) 1) "name"
            2) "Jane"
            3) "surname"
            4) "Austen"

```

The **STREAMS** option is mandatory and MUST be the final option because such option gets a variable length of argument in the following format:

 
```
STREAMS key_1 key_2 key_3 ... key_N ID_1 ID_2 ID_3 ... ID_N

```
 So we start with a list of keys, and later continue with all the associated IDs, representing *the last ID we received for that stream*, so that the call will serve us only greater IDs from the same stream.

 For instance in the above example, the last items that we received for the stream `mystream` has ID `1526999352406-0`, while for the stream `writers` has the ID `1526985685298-0`.

 To continue iterating the two streams I'll call:

 
```
> XREAD COUNT 2 STREAMS mystream writers 1526999352406-0 1526985685298-0
1) 1) "mystream"
   2) 1) 1) 1526999626221-0
         2) 1) "duration"
            2) "911"
            3) "event-id"
            4) "7"
            5) "user-id"
            6) "9488232"
2) 1) "writers"
   2) 1) 1) 1526985691746-0
         2) 1) "name"
            2) "Toni"
            3) "surname"
            4) "Morrison"
      2) 1) 1526985712947-0
         2) 1) "name"
            2) "Agatha"
            3) "surname"
            4) "Christie"

```

And so forth. Eventually, the call will not return any item, but just an empty array, then we know that there is nothing more to fetch from our stream (and we would have to retry the operation, hence this command also supports a blocking mode).

 Incomplete IDs
--------------

 To use incomplete IDs is valid, like it is valid for [`XRANGE`](../xrange). However here the sequence part of the ID, if missing, is always interpreted as zero, so the command:

 
```
> XREAD COUNT 2 STREAMS mystream writers 0 0

```

is exactly equivalent to

 
```
> XREAD COUNT 2 STREAMS mystream writers 0-0 0-0

```

Blocking for data
-----------------

 In its synchronous form, the command can get new data as long as there are more items available. However, at some point, we'll have to wait for producers of data to use [`XADD`](../xadd) to push new entries inside the streams we are consuming. In order to avoid polling at a fixed or adaptive interval the command is able to block if it could not return any data, according to the specified streams and IDs, and automatically unblock once one of the requested keys accept data.

 It is important to understand that this command *fans out* to all the clients that are waiting for the same range of IDs, so every consumer will get a copy of the data, unlike to what happens when blocking list pop operations are used.

 In order to block, the **BLOCK** option is used, together with the number of milliseconds we want to block before timing out. Normally Redis blocking commands take timeouts in seconds, however this command takes a millisecond timeout, even if normally the server will have a timeout resolution near to 0.1 seconds. This time it is possible to block for a shorter time in certain use cases, and if the server internals will improve over time, it is possible that the resolution of timeouts will improve.

 When the **BLOCK** command is passed, but there is data to return at least in one of the streams passed, the command is executed synchronously *exactly like if the BLOCK option would be missing*.

 This is an example of blocking invocation, where the command later returns a null reply because the timeout has elapsed without new data arriving:

 
```
> XREAD BLOCK 1000 STREAMS mystream 1526999626221-0
(nil)

```

The special `$` ID.
-------------------

 When blocking sometimes we want to receive just entries that are added to the stream via [`XADD`](../xadd) starting from the moment we block. In such a case we are not interested in the history of already added entries. For this use case, we would have to check the stream top element ID, and use such ID in the `XREAD` command line. This is not clean and requires to call other commands, so instead it is possible to use the special `$` ID to signal the stream that we want only the new things.

 It is **very important** to understand that you should use the `$` ID only for the first call to `XREAD`. Later the ID should be the one of the last reported item in the stream, otherwise you could miss all the entries that are added in between.

 This is how a typical `XREAD` call looks like in the first iteration of a consumer willing to consume only new entries:

 
```
> XREAD BLOCK 5000 COUNT 100 STREAMS mystream $

```

Once we get some replies, the next call will be something like:

 
```
> XREAD BLOCK 5000 COUNT 100 STREAMS mystream 1526999644174-3

```

And so forth.

 How multiple clients blocked on a single stream are served
----------------------------------------------------------

 Blocking list operations on lists or sorted sets have a *pop* behavior. Basically, the element is removed from the list or sorted set in order to be returned to the client. In this scenario you want the items to be consumed in a fair way, depending on the moment clients blocked on a given key arrived. Normally Redis uses the FIFO semantics in this use cases.

 However note that with streams this is not a problem: stream entries are not removed from the stream when clients are served, so every client waiting will be served as soon as an [`XADD`](../xadd) command provides data to the stream.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns an array of results: each element of the returned array is an array composed of a two element containing the key name and the entries reported for that key. The entries reported are full stream entries, having IDs and the list of all the fields and values. Field and values are guaranteed to be reported in the same order they were added by [`XADD`](../xadd).

 When **BLOCK** is used, on timeout a null reply is returned.

 Reading the [Redis Streams introduction](https://redis.io/topics/streams-intro) is highly suggested in order to understand more about the streams overall behavior and semantics.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xread/>

XGROUP
======



```
XGROUP SETID
```
 Syntax 
```
XGROUP SETID key group <id | $> [ENTRIESREAD entries-read]
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@write`, `@stream`, `@slow`,   Set the **last delivered ID** for a consumer group.

 Normally, a consumer group's last delivered ID is set when the group is created with [`XGROUP CREATE`](../xgroup-create). The `XGROUP SETID` command allows modifying the group's last delivered ID, without having to delete and recreate the group. For instance if you want the consumers in a consumer group to re-process all the messages in a stream, you may want to set its next ID to 0:

 
```
XGROUP SETID mystream mygroup 0

```
 The optional `entries_read` argument can be specified to enable consumer group lag tracking for an arbitrary ID. An arbitrary ID is any ID that isn't the ID of the stream's first entry, its last entry or the zero ("0-0") ID. This can be useful you know exactly how many entries are between the arbitrary ID (excluding it) and the stream's last entry. In such cases, the `entries_read` can be set to the stream's `entries_added` subtracted with the number of entries.

 Return
------

 [Simple string reply](https://redis.io/docs/reference/protocol-spec#resp-simple-strings): `OK` on success.

 History
-------

 * Starting with Redis version 7.0.0: Added the optional `entries_read` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xgroup-setid/>

XINFO
=====



```
XINFO GROUPS
```
 Syntax 
```
XINFO GROUPS key
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@read`, `@stream`, `@slow`,   This command returns the list of all consumers groups of the stream stored at `<key>`.

 By default, only the following information is provided for each of the groups:

 * **name**: the consumer group's name
* **consumers**: the number of consumers in the group
* **pending**: the length of the group's pending entries list (PEL), which are messages that were delivered but are yet to be acknowledged
* **last-delivered-id**: the ID of the last entry delivered the group's consumers
* **entries-read**: the logical "read counter" of the last entry delivered to group's consumers
* **lag**: the number of entries in the stream that are still waiting to be delivered to the group's consumers, or a NULL when that number can't be determined.

 ### Consumer group lag

 The lag of a given consumer group is the number of entries in the range between the group's `entries_read` and the stream's `entries_added`. Put differently, it is the number of entries that are yet to be delivered to the group's consumers.

 The values and trends of this metric are helpful in making scaling decisions about the consumer group. You can address high lag values by adding more consumers to the group, whereas low values may indicate that you can remove consumers from the group to scale it down.

 Redis reports the lag of a consumer group by keeping two counters: the number of all entries added to the stream and the number of logical reads made by the consumer group. The lag is the difference between these two.

 The stream's counter (the `entries_added` field of the [`XINFO STREAM`](../xinfo-stream) command) is incremented by one with every [`XADD`](../xadd) and counts all of the entries added to the stream during its lifetime.

 The consumer group's counter, `entries_read`, is the logical counter of entries that the group had read. It is important to note that this counter is only a heuristic rather than an accurate counter, and therefore the use of the term "logical". The counter attempts to reflect the number of entries that the group **should have read** to get to its current `last-delivered-id`. The `entries_read` counter is accurate only in a perfect world, where a consumer group starts at the stream's first entry and processes all of its entries (i.e., no entries deleted before processing).

 There are two special cases in which this mechanism is unable to report the lag:

 1. A consumer group is created or set with an arbitrary last delivered ID (the [`XGROUP CREATE`](../xgroup-create) and [`XGROUP SETID`](../xgroup-setid) commands, respectively). An arbitrary ID is any ID that isn't the ID of the stream's first entry, its last entry or the zero ("0-0") ID.
2. One or more entries between the group's `last-delivered-id` and the stream's `last-generated-id` were deleted (with [`XDEL`](../xdel) or a trimming operation).

 In both cases, the group's read counter is considered invalid, and the returned value is set to NULL to signal that the lag isn't currently available.

 However, the lag is only temporarily unavailable. It is restored automatically during regular operation as consumers keep processing messages. Once the consumer group delivers the last message in the stream to its members, it will be set with the correct logical read counter, and tracking its lag can be resumed.

 @reply

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of consumer groups.

 Examples
--------

 
```
> XINFO GROUPS mystream
1)  1) "name"
    2) "mygroup"
    3) "consumers"
    4) (integer) 2
    5) "pending"
    6) (integer) 2
    7) "last-delivered-id"
    8) "1638126030001-0"
    9) "entries-read"
   10) (integer) 2
   11) "lag"
   12) (integer) 0
2)  1) "name"
    2) "some-other-group"
    3) "consumers"
    4) (integer) 1
    5) "pending"
    6) (integer) 0
    7) "last-delivered-id"
    8) "1638126028070-0"
    9) "entries-read"
   10) (integer) 1
   11) "lag"
   12) (integer) 1

```
 History
-------

 * Starting with Redis version 7.0.0: Added the `entries-read` and `lag` fields



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xinfo-groups/>

XREADGROUP
==========



```
XREADGROUP
```
 Syntax 
```
XREADGROUP GROUP group consumer [COUNT count] [BLOCK milliseconds]
  [NOACK] STREAMS key [key ...] id [id ...]
```
  Available since: 5.0.0 Time complexity: For each stream mentioned: O(M) with M being the number of elements returned. If M is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1). On the other side when XREADGROUP blocks, XADD will pay the O(N) time in order to serve the N clients blocked on the stream getting new data. ACL categories:  `@write`, `@stream`, `@slow`, `@blocking`,   The `XREADGROUP` command is a special version of the [`XREAD`](../xread) command with support for consumer groups. Probably you will have to understand the [`XREAD`](../xread) command before reading this page will makes sense.

 Moreover, if you are new to streams, we recommend to read our [introduction to Redis Streams](https://redis.io/topics/streams-intro). Make sure to understand the concept of consumer group in the introduction so that following how this command works will be simpler.

 Consumer groups in 30 seconds
-----------------------------

 The difference between this command and the vanilla [`XREAD`](../xread) is that this one supports consumer groups.

 Without consumer groups, just using [`XREAD`](../xread), all the clients are served with all the entries arriving in a stream. Instead using consumer groups with `XREADGROUP`, it is possible to create groups of clients that consume different parts of the messages arriving in a given stream. If, for instance, the stream gets the new entries A, B, and C and there are two consumers reading via a consumer group, one client will get, for instance, the messages A and C, and the other the message B, and so forth.

 Within a consumer group, a given consumer (that is, just a client consuming messages from the stream), has to identify with a unique *consumer name*. Which is just a string.

 One of the guarantees of consumer groups is that a given consumer can only see the history of messages that were delivered to it, so a message has just a single owner. However there is a special feature called *message claiming* that allows other consumers to claim messages in case there is a non recoverable failure of some consumer. In order to implement such semantics, consumer groups require explicit acknowledgment of the messages successfully processed by the consumer, via the [`XACK`](../xack) command. This is needed because the stream will track, for each consumer group, who is processing what message.

 This is how to understand if you want to use a consumer group or not:

 1. If you have a stream and multiple clients, and you want all the clients to get all the messages, you do not need a consumer group.
2. If you have a stream and multiple clients, and you want the stream to be *partitioned* or *sharded* across your clients, so that each client will get a sub set of the messages arriving in a stream, you need a consumer group.

 Differences between XREAD and XREADGROUP
----------------------------------------

 From the point of view of the syntax, the commands are almost the same, however `XREADGROUP` *requires* a special and mandatory option:

 
```
GROUP <group-name> <consumer-name>

```
 The group name is just the name of a consumer group associated to the stream. The group is created using the [`XGROUP`](../xgroup) command. The consumer name is the string that is used by the client to identify itself inside the group. The consumer is auto created inside the consumer group the first time it is saw. Different clients should select a different consumer name.

 When you read with `XREADGROUP`, the server will *remember* that a given message was delivered to you: the message will be stored inside the consumer group in what is called a Pending Entries List (PEL), that is a list of message IDs delivered but not yet acknowledged.

 The client will have to acknowledge the message processing using [`XACK`](../xack) in order for the pending entry to be removed from the PEL. The PEL can be inspected using the [`XPENDING`](../xpending) command.

 The `NOACK` subcommand can be used to avoid adding the message to the PEL in cases where reliability is not a requirement and the occasional message loss is acceptable. This is equivalent to acknowledging the message when it is read.

 The ID to specify in the **STREAMS** option when using `XREADGROUP` can be one of the following two:

 * The special `>` ID, which means that the consumer want to receive only messages that were *never delivered to any other consumer*. It just means, give me new messages.
* Any other ID, that is, 0 or any other valid ID or incomplete ID (just the millisecond time part), will have the effect of returning entries that are pending for the consumer sending the command with IDs greater than the one provided. So basically if the ID is not `>`, then the command will just let the client access its pending entries: messages delivered to it, but not yet acknowledged. Note that in this case, both `BLOCK` and `NOACK` are ignored.

 Like [`XREAD`](../xread) the `XREADGROUP` command can be used in a blocking way. There are no differences in this regard.

 What happens when a message is delivered to a consumer?
-------------------------------------------------------

 Two things:

 1. If the message was never delivered to anyone, that is, if we are talking about a new message, then a PEL (Pending Entries List) is created.
2. If instead the message was already delivered to this consumer, and it is just re-fetching the same message again, then the *last delivery counter* is updated to the current time, and the *number of deliveries* is incremented by one. You can access those message properties using the [`XPENDING`](../xpending) command.

 Usage example
-------------

 Normally you use the command like that in order to get new messages and process them. In pseudo-code:

 
```
WHILE true
    entries = XREADGROUP GROUP $GroupName $ConsumerName BLOCK 2000 COUNT 10 STREAMS mystream >
    if entries == nil
        puts "Timeout... try again"
        CONTINUE
    end

    FOREACH entries AS stream_entries
        FOREACH stream_entries as message
            process_message(message.id,message.fields)

            # ACK the message as processed
            XACK mystream $GroupName message.id
        END
    END
END

```

In this way the example consumer code will fetch only new messages, process them, and acknowledge them via [`XACK`](../xack). However the example code above is not complete, because it does not handle recovering after a crash. What will happen if we crash in the middle of processing messages, is that our messages will remain in the pending entries list, so we can access our history by giving `XREADGROUP` initially an ID of 0, and performing the same loop. Once providing an ID of 0 the reply is an empty set of messages, we know that we processed and acknowledged all the pending messages: we can start to use `>` as ID, in order to get the new messages and rejoin the consumers that are processing new things.

 To see how the command actually replies, please check the [`XREAD`](../xread) command page.

 What happens when a pending message is deleted?
-----------------------------------------------

 Entries may be deleted from the stream due to trimming or explicit calls to [`XDEL`](../xdel) at any time. By design, Redis doesn't prevent the deletion of entries that are present in the stream's PELs. When this happens, the PELs retain the deleted entries' IDs, but the actual entry payload is no longer available. Therefore, when reading such PEL entries, Redis will return a null value in place of their respective data.

 Example:

 
```
> XADD mystream 1 myfield mydata
"1-0"
> XGROUP CREATE mystream mygroup 0
OK
> XREADGROUP GROUP mygroup myconsumer STREAMS mystream >
1) 1) "mystream"
   2) 1) 1) "1-0"
         2) 1) "myfield"
            2) "mydata"
> XDEL mystream 1-0
(integer) 1
> XREADGROUP GROUP mygroup myconsumer STREAMS mystream 0
1) 1) "mystream"
   2) 1) 1) "1-0"
         2) (nil)

```

Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns an array of results: each element of the returned array is an array composed of a two element containing the key name and the entries reported for that key. The entries reported are full stream entries, having IDs and the list of all the fields and values. Field and values are guaranteed to be reported in the same order they were added by [`XADD`](../xadd).

 When **BLOCK** is used, on timeout a null reply is returned.

 Reading the [Redis Streams introduction](https://redis.io/topics/streams-intro) is highly suggested in order to understand more about the streams overall behavior and semantics.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xreadgroup/>

XPENDING
========



```
XPENDING
```
 Syntax 
```
XPENDING key group [[IDLE min-idle-time] start end count [consumer]]
```
  Available since: 5.0.0 Time complexity: O(N) with N being the number of elements returned, so asking for a small fixed number of entries per call is O(1). O(M), where M is the total number of entries scanned when used with the IDLE filter. When the command returns just the summary and the list of consumers is small, it runs in O(1) time; otherwise, an additional O(N) time for iterating every consumer. ACL categories:  `@read`, `@stream`, `@slow`,   Fetching data from a stream via a consumer group, and not acknowledging such data, has the effect of creating *pending entries*. This is well explained in the [`XREADGROUP`](../xreadgroup) command, and even better in our [introduction to Redis Streams](https://redis.io/topics/streams-intro). The [`XACK`](../xack) command will immediately remove the pending entry from the Pending Entries List (PEL) since once a message is successfully processed, there is no longer need for the consumer group to track it and to remember the current owner of the message.

 The `XPENDING` command is the interface to inspect the list of pending messages, and is as thus a very important command in order to observe and understand what is happening with a streams consumer groups: what clients are active, what messages are pending to be consumed, or to see if there are idle messages. Moreover this command, together with [`XCLAIM`](../xclaim) is used in order to implement recovering of consumers that are failing for a long time, and as a result certain messages are not processed: a different consumer can claim the message and continue. This is better explained in the [streams intro](https://redis.io/topics/streams-intro) and in the [`XCLAIM`](../xclaim) command page, and is not covered here.

 Summary form of XPENDING
------------------------

 When `XPENDING` is called with just a key name and a consumer group name, it just outputs a summary about the pending messages in a given consumer group. In the following example, we create a consumer group and immediately create a pending message by reading from the group with [`XREADGROUP`](../xreadgroup).

 
```
> XGROUP CREATE mystream group55 0-0
OK

> XREADGROUP GROUP group55 consumer-123 COUNT 1 STREAMS mystream >
1) 1) "mystream"
   2) 1) 1) 1526984818136-0
         2) 1) "duration"
            2) "1532"
            3) "event-id"
            4) "5"
            5) "user-id"
            6) "7782813"

```

We expect the pending entries list for the consumer group `group55` to have a message right now: consumer named `consumer-123` fetched the message without acknowledging its processing. The simple `XPENDING` form will give us this information:

 
```
> XPENDING mystream group55
1) (integer) 1
2) 1526984818136-0
3) 1526984818136-0
4) 1) 1) "consumer-123"
      2) "1"

```

In this form, the command outputs the total number of pending messages for this consumer group, which is one, followed by the smallest and greatest ID among the pending messages, and then list every consumer in the consumer group with at least one pending message, and the number of pending messages it has.

 Extended form of XPENDING
-------------------------

 The summary provides a good overview, but sometimes we are interested in the details. In order to see all the pending messages with more associated information we need to also pass a range of IDs, in a similar way we do it with [`XRANGE`](../xrange), and a non optional *count* argument, to limit the number of messages returned per call:

 
```
> XPENDING mystream group55 - + 10
1) 1) 1526984818136-0
   2) "consumer-123"
   3) (integer) 196415
   4) (integer) 1

```

In the extended form we no longer see the summary information, instead there is detailed information for each message in the pending entries list. For each message four attributes are returned:

 1. The ID of the message.
2. The name of the consumer that fetched the message and has still to acknowledge it. We call it the current *owner* of the message.
3. The number of milliseconds that elapsed since the last time this message was delivered to this consumer.
4. The number of times this message was delivered.

 The deliveries counter, that is the fourth element in the array, is incremented when some other consumer *claims* the message with [`XCLAIM`](../xclaim), or when the message is delivered again via [`XREADGROUP`](../xreadgroup), when accessing the history of a consumer in a consumer group (see the [`XREADGROUP`](../xreadgroup) page for more info).

 It is possible to pass an additional argument to the command, in order to see the messages having a specific owner:

 
```
> XPENDING mystream group55 - + 10 consumer-123

```

But in the above case the output would be the same, since we have pending messages only for a single consumer. However what is important to keep in mind is that this operation, filtering by a specific consumer, is not inefficient even when there are many pending messages from many consumers: we have a pending entries list data structure both globally, and for every consumer, so we can very efficiently show just messages pending for a single consumer.

 Idle time filter
----------------

 It is also possible to filter pending stream entries by their idle-time, given in milliseconds (useful for [`XCLAIM`](../xclaim)ing entries that have not been processed for some time):

 
```
> XPENDING mystream group55 IDLE 9000 - + 10
> XPENDING mystream group55 IDLE 9000 - + 10 consumer-123

```

The first case will return the first 10 (or less) PEL entries of the entire group that are idle for over 9 seconds, whereas in the second case only those of `consumer-123`.

 Exclusive ranges and iterating the PEL
--------------------------------------

 The `XPENDING` command allows iterating over the pending entries just like [`XRANGE`](../xrange) and [`XREVRANGE`](../xrevrange) allow for the stream's entries. You can do this by prefixing the ID of the last-read pending entry with the `(` character that denotes an open (exclusive) range, and proving it to the subsequent call to the command.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns data in different format depending on the way it is called, as previously explained in this page. However the reply is always an array of items.

 History
-------

 * Starting with Redis version 6.2.0: Added the `IDLE` option and exclusive range intervals.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xpending/>

ZINTERCARD
==========



```
ZINTERCARD
```
 Syntax 
```
ZINTERCARD numkeys key [key ...] [LIMIT limit]
```
  Available since: 7.0.0 Time complexity: O(N\*K) worst case with N being the smallest input sorted set, K being the number of input sorted sets. ACL categories:  `@read`, `@sortedset`, `@slow`,   This command is similar to [`ZINTER`](../zinter), but instead of returning the result set, it returns just the cardinality of the result.

 Keys that do not exist are considered to be empty sets. With one of the keys being an empty set, the resulting set is also empty (since set intersection with an empty set always results in an empty set).

 By default, the command calculates the cardinality of the intersection of all given sets. When provided with the optional `LIMIT` argument (which defaults to 0 and means unlimited), if the intersection cardinality reaches limit partway through the computation, the algorithm will exit and yield limit as the cardinality. Such implementation ensures a significant speedup for queries where the limit is lower than the actual intersection cardinality.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting intersection.

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZADD zset2 3 "three"
ZINTER 2 zset1 zset2
ZINTERCARD 2 zset1 zset2
ZINTERCARD 2 zset1 zset2 LIMIT 1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zintercard/>

XLEN
====



```
XLEN
```
 Syntax 
```
XLEN key
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@read`, `@stream`, `@fast`,   Returns the number of entries inside a stream. If the specified key does not exist the command returns zero, as if the stream was empty. However note that unlike other Redis types, zero-length streams are possible, so you should call [`TYPE`](../type) or [`EXISTS`](../exists) in order to check if a key exists or not.

 Streams are not auto-deleted once they have no entries inside (for instance after an [`XDEL`](../xdel) call), because the stream may have consumer groups associated with it.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of entries of the stream at `key`.

 Examples
--------

 
```

XADD mystream * item 1
XADD mystream * item 2
XADD mystream * item 3
XLEN mystream

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xlen/>

ZCARD
=====



```
ZCARD
```
 Syntax 
```
ZCARD key
```
  Available since: 1.2.0 Time complexity: O(1) ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the sorted set cardinality (number of elements) of the sorted set stored at `key`.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the cardinality (number of elements) of the sorted set, or `0` if `key` does not exist.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZCARD myzset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zcard/>

XSETID
======



```
XSETID
```
 Syntax 
```
XSETID key last-id [ENTRIESADDED entries-added]
  [MAXDELETEDID max-deleted-id]
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@write`, `@stream`, `@fast`,   The `XSETID` command is an internal command. It is used by a Redis master to replicate the last delivered ID of streams.

 History
-------

 * Starting with Redis version 7.0.0: Added the `entries_added` and `max_deleted_entry_id` arguments.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xsetid/>

ZCOUNT
======



```
ZCOUNT
```
 Syntax 
```
ZCOUNT key min max
```
  Available since: 2.0.0 Time complexity: O(log(N)) with N being the number of elements in the sorted set. ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the number of elements in the sorted set at `key` with a score between `min` and `max`.

 The `min` and `max` arguments have the same semantic as described for [`ZRANGEBYSCORE`](../zrangebyscore).

 Note: the command has a complexity of just O(log(N)) because it uses elements ranks (see [`ZRANK`](../zrank)) to get an idea of the range. Because of this there is no need to do a work proportional to the size of the range.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the specified score range.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZCOUNT myzset -inf +inf
ZCOUNT myzset (1 3

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zcount/>

XINFO
=====



```
XINFO STREAM
```
 Syntax 
```
XINFO STREAM key [FULL [COUNT count]]
```
  Available since: 5.0.0 Time complexity: O(1) ACL categories:  `@read`, `@stream`, `@slow`,   This command returns information about the stream stored at `<key>`.

 The informative details provided by this command are:

 * **length**: the number of entries in the stream (see [`XLEN`](../xlen))
* **radix-tree-keys**: the number of keys in the underlying radix data structure
* **radix-tree-nodes**: the number of nodes in the underlying radix data structure
* **groups**: the number of consumer groups defined for the stream
* **last-generated-id**: the ID of the least-recently entry that was added to the stream
* **max-deleted-entry-id**: the maximal entry ID that was deleted from the stream
* **entries-added**: the count of all entries added to the stream during its lifetime
* **first-entry**: the ID and field-value tuples of the first entry in the stream
* **last-entry**: the ID and field-value tuples of the last entry in the stream

 The optional `FULL` modifier provides a more verbose reply. When provided, the `FULL` reply includes an **entries** array that consists of the stream entries (ID and field-value tuples) in ascending order. Furthermore, **groups** is also an array, and for each of the consumer groups it consists of the information reported by [`XINFO GROUPS`](../xinfo-groups) and [`XINFO CONSUMERS`](../xinfo-consumers).

 The `COUNT` option can be used to limit the number of stream and PEL entries that are returned (The first `<count>` entries are returned). The default `COUNT` is 10 and a `COUNT` of 0 means that all entries will be returned (execution time may be long if the stream has a lot of entries).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): a list of informational bits

 Examples
--------

 Default reply:

 
```
> XINFO STREAM mystream
 1) "length"
 2) (integer) 2
 3) "radix-tree-keys"
 4) (integer) 1
 5) "radix-tree-nodes"
 6) (integer) 2
 7) "last-generated-id"
 8) "1638125141232-0"
 9) "max-deleted-entry-id"
10) "0-0"
11) "entries-added"
12) (integer) 2
13) "groups"
14) (integer) 1
15) "first-entry"
16) 1) "1638125133432-0"
    2) 1) "message"
       2) "apple"
17) "last-entry"
18) 1) "1638125141232-0"
    2) 1) "message"
       2) "banana"

```

Full reply:

 
```
> XADD mystream * foo bar
"1638125133432-0"
> XADD mystream * foo bar2
"1638125141232-0"
> XGROUP CREATE mystream mygroup 0-0
OK
> XREADGROUP GROUP mygroup Alice COUNT 1 STREAMS mystream >
1) 1) "mystream"
   2) 1) 1) "1638125133432-0"
         2) 1) "foo"
            2) "bar"
> XINFO STREAM mystream FULL
 1) "length"
 2) (integer) 2
 3) "radix-tree-keys"
 4) (integer) 1
 5) "radix-tree-nodes"
 6) (integer) 2
 7) "last-generated-id"
 8) "1638125141232-0"
 9) "max-deleted-entry-id"
10) "0-0"
11) "entries-added"
12) (integer) 2
13) "entries"
14) 1) 1) "1638125133432-0"
       2) 1) "foo"
          2) "bar"
    2) 1) "1638125141232-0"
       2) 1) "foo"
          2) "bar2"
15) "groups"
16) 1)  1) "name"
        2) "mygroup"
        3) "last-delivered-id"
        4) "1638125133432-0"
        5) "entries-read"
        6) (integer) 1
        7) "lag"
        8) (integer) 1
        9) "pel-count"
       10) (integer) 1
       11) "pending"
       12) 1) 1) "1638125133432-0"
              2) "Alice"
              3) (integer) 1638125153423
              4) (integer) 1
       13) "consumers"
       14) 1) 1) "name"
              2) "Alice"
              3) "seen-time"
              4) (integer) 1638125133422
              5) "active-time"
              6) (integer) 1638125133432
              7) "pel-count"
              8) (integer) 1
              9) "pending"
              10) 1) 1) "1638125133432-0"
                     2) (integer) 1638125133432
                     3) (integer) 1

```
 History
-------

 * Starting with Redis version 6.0.0: Added the `FULL` modifier.
* Starting with Redis version 7.0.0: Added the `max-deleted-entry-id`, `entries-added`, `recorded-first-entry-id`, `entries-read` and `lag` fields
* Starting with Redis version 7.2.0: Added the `active-time` field, and changed the meaning of `seen-time`.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xinfo-stream/>

XTRIM
=====



```
XTRIM
```
 Syntax 
```
XTRIM key <MAXLEN | MINID> [= | ~] threshold [LIMIT count]
```
  Available since: 5.0.0 Time complexity: O(N), with N being the number of evicted entries. Constant times are very small however, since entries are organized in macro nodes containing multiple entries that can be released with a single deallocation. ACL categories:  `@write`, `@stream`, `@slow`,   `XTRIM` trims the stream by evicting older entries (entries with lower IDs) if needed.

 Trimming the stream can be done using one of these strategies:

 * `MAXLEN`: Evicts entries as long as the stream's length exceeds the specified `threshold`, where `threshold` is a positive integer.
* `MINID`: Evicts entries with IDs lower than `threshold`, where `threshold` is a stream ID.

 For example, this will trim the stream to exactly the latest 1000 items:

 
```
XTRIM mystream MAXLEN 1000

```

Whereas in this example, all entries that have an ID lower than 649085820-0 will be evicted:

 
```
XTRIM mystream MINID 649085820

```

By default, or when provided with the optional `=` argument, the command performs exact trimming.

 Depending on the strategy, exact trimming means:

 * `MAXLEN`: the trimmed stream's length will be exactly the minimum between its original length and the specified `threshold`.
* `MINID`: the oldest ID in the stream will be exactly the maximum between its original oldest ID and the specified `threshold`.

 Nearly exact trimming
---------------------

 Because exact trimming may require additional effort from the Redis server, the optional `~` argument can be provided to make it more efficient.

 For example:

 
```
XTRIM mystream MAXLEN ~ 1000

```

The `~` argument between the `MAXLEN` strategy and the `threshold` means that the user is requesting to trim the stream so its length is **at least** the `threshold`, but possibly slightly more. In this case, Redis will stop trimming early when performance can be gained (for example, when a whole macro node in the data structure can't be removed). This makes trimming much more efficient, and it is usually what you want, although after trimming, the stream may have few tens of additional entries over the `threshold`.

 Another way to control the amount of work done by the command when using the `~`, is the `LIMIT` clause. When used, it specifies the maximal `count` of entries that will be evicted. When `LIMIT` and `count` aren't specified, the default value of 100 \* the number of entries in a macro node will be implicitly used as the `count`. Specifying the value 0 as `count` disables the limiting mechanism entirely.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): The number of entries deleted from the stream.

 Examples
--------

 
```

XADD mystream * field1 A field2 B field3 C field4 D
XTRIM mystream MAXLEN 2
XRANGE mystream - +

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `MINID` trimming strategy and the `LIMIT` option.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xtrim/>

ZINTER
======



```
ZINTER
```
 Syntax 
```
ZINTER numkeys key [key ...] [WEIGHTS weight [weight ...]]
  [AGGREGATE <SUM | MIN | MAX>] [WITHSCORES]
```
  Available since: 6.2.0 Time complexity: O(N\*K)+O(M\*log(M)) worst case with N being the smallest input sorted set, K being the number of input sorted sets and M being the number of elements in the resulting sorted set. ACL categories:  `@read`, `@sortedset`, `@slow`,   This command is similar to [`ZINTERSTORE`](../zinterstore), but instead of storing the resulting sorted set, it is returned to the client.

 For a description of the `WEIGHTS` and `AGGREGATE` options, see [`ZUNIONSTORE`](../zunionstore).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): the result of intersection (optionally with their scores, in case the `WITHSCORES` option is given).

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZADD zset2 3 "three"
ZINTER 2 zset1 zset2
ZINTER 2 zset1 zset2 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zinter/>

ZADD
====



```
ZADD
```
 Syntax 
```
ZADD key [NX | XX] [GT | LT] [CH] [INCR] score member [score member
  ...]
```
  Available since: 1.2.0 Time complexity: O(log(N)) for each item added, where N is the number of elements in the sorted set. ACL categories:  `@write`, `@sortedset`, `@fast`,   Adds all the specified members with the specified scores to the sorted set stored at `key`. It is possible to specify multiple score / member pairs. If a specified member is already a member of the sorted set, the score is updated and the element reinserted at the right position to ensure the correct ordering.

 If `key` does not exist, a new sorted set with the specified members as sole members is created, like if the sorted set was empty. If the key exists but does not hold a sorted set, an error is returned.

 The score values should be the string representation of a double precision floating point number. `+inf` and `-inf` values are valid values as well.

 ZADD options
------------

 ZADD supports a list of options, specified after the name of the key and before the first score argument. Options are:

 * **XX**: Only update elements that already exist. Don't add new elements.
* **NX**: Only add new elements. Don't update already existing elements.
* **LT**: Only update existing elements if the new score is **less than** the current score. This flag doesn't prevent adding new elements.
* **GT**: Only update existing elements if the new score is **greater than** the current score. This flag doesn't prevent adding new elements.
* **CH**: Modify the return value from the number of new elements added, to the total number of elements changed (CH is an abbreviation of *changed*). Changed elements are **new elements added** and elements already existing for which **the score was updated**. So elements specified in the command line having the same score as they had in the past are not counted. Note: normally the return value of `ZADD` only counts the number of new elements added.
* **INCR**: When this option is specified `ZADD` acts like [`ZINCRBY`](../zincrby). Only one score-element pair can be specified in this mode.

 Note: The **GT**, **LT** and **NX** options are mutually exclusive.

 Range of integer scores that can be expressed precisely
-------------------------------------------------------

 Redis sorted sets use a *double 64-bit floating point number* to represent the score. In all the architectures we support, this is represented as an **IEEE 754 floating point number**, that is able to represent precisely integer numbers between `-(2^53)` and `+(2^53)` included. In more practical terms, all the integers between -9007199254740992 and 9007199254740992 are perfectly representable. Larger integers, or fractions, are internally represented in exponential form, so it is possible that you get only an approximation of the decimal number, or of the very big integer, that you set as score.

 Sorted sets 101
---------------

 Sorted sets are sorted by their score in an ascending way. The same element only exists a single time, no repeated elements are permitted. The score can be modified both by `ZADD` that will update the element score, and as a side effect, its position on the sorted set, and by [`ZINCRBY`](../zincrby) that can be used in order to update the score relatively to its previous value.

 The current score of an element can be retrieved using the [`ZSCORE`](../zscore) command, that can also be used to verify if an element already exists or not.

 For an introduction to sorted sets, see the data types page on [sorted sets](https://redis.io/topics/data-types#sorted-sets).

 Elements with the same score
----------------------------

 While the same element can't be repeated in a sorted set since every element is unique, it is possible to add multiple different elements *having the same score*. When multiple elements have the same score, they are *ordered lexicographically* (they are still ordered by score as a first key, however, locally, all the elements with the same score are relatively ordered lexicographically).

 The lexicographic ordering used is binary, it compares strings as array of bytes.

 If the user inserts all the elements in a sorted set with the same score (for example 0), all the elements of the sorted set are sorted lexicographically, and range queries on elements are possible using the command [`ZRANGEBYLEX`](../zrangebylex) (Note: it is also possible to query sorted sets by range of scores using [`ZRANGEBYSCORE`](../zrangebyscore)).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * When used without optional arguments, the number of elements added to the sorted set (excluding score updates).
* If the `CH` option is specified, the number of elements that were changed (added or updated).

 If the [`INCR`](../incr) option is specified, the return value will be [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings):

 * The new score of `member` (a double precision floating point number) represented as string, or `nil` if the operation was aborted (when called with either the `XX` or the `NX` option).

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 1 "uno"
ZADD myzset 2 "two" 3 "three"
ZRANGE myzset 0 -1 WITHSCORES

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple elements.
* Starting with Redis version 3.0.2: Added the `XX`, `NX`, `CH` and `INCR` options.
* Starting with Redis version 6.2.0: Added the `GT` and `LT` options.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zadd/>

ZDIFFSTORE
==========



```
ZDIFFSTORE
```
 Syntax 
```
ZDIFFSTORE destination numkeys key [key ...]
```
  Available since: 6.2.0 Time complexity: O(L + (N-K)log(N)) worst case where L is the total number of elements in all the sets, N is the size of the first set, and K is the size of the result set. ACL categories:  `@write`, `@sortedset`, `@slow`,   Computes the difference between the first and all successive input sorted sets and stores the result in `destination`. The total number of input keys is specified by `numkeys`.

 Keys that do not exist are considered to be empty sets.

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting sorted set at `destination`.

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset1 3 "three"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZDIFFSTORE out 2 zset1 zset2
ZRANGE out 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zdiffstore/>

ZRANGE
======



```
ZRANGE
```
 Syntax 
```
ZRANGE key start stop [BYSCORE | BYLEX] [REV] [LIMIT offset count]
  [WITHSCORES]
```
  Available since: 1.2.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements returned. ACL categories:  `@read`, `@sortedset`, `@slow`,   Returns the specified range of elements in the sorted set stored at `<key>`.

 `ZRANGE` can perform different types of range queries: by index (rank), by the score, or by lexicographical order.

 Starting with Redis 6.2.0, this command can replace the following commands: [`ZREVRANGE`](../zrevrange), [`ZRANGEBYSCORE`](../zrangebyscore), [`ZREVRANGEBYSCORE`](../zrevrangebyscore), [`ZRANGEBYLEX`](../zrangebylex) and [`ZREVRANGEBYLEX`](../zrevrangebylex).

 Common behavior and options
---------------------------

 The order of elements is from the lowest to the highest score. Elements with the same score are ordered lexicographically.

 The optional `REV` argument reverses the ordering, so elements are ordered from highest to lowest score, and score ties are resolved by reverse lexicographical ordering.

 The optional `LIMIT` argument can be used to obtain a sub-range from the matching elements (similar to *SELECT LIMIT offset, count* in SQL). A negative `<count>` returns all elements from the `<offset>`. Keep in mind that if `<offset>` is large, the sorted set needs to be traversed for `<offset>` elements before getting to the elements to return, which can add up to O(N) time complexity.

 The optional `WITHSCORES` argument supplements the command's reply with the scores of elements returned. The returned list contains `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).

 Index ranges
------------

 By default, the command performs an index range query. The `<start>` and `<stop>` arguments represent zero-based indexes, where `0` is the first element, `1` is the next element, and so on. These arguments specify an **inclusive range**, so for example, `ZRANGE myzset 0 1` will return both the first and the second element of the sorted set.

 The indexes 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.

 Out of range indexes do not produce an error.

 If `<start>` is greater than either the end index of the sorted set or `<stop>`, an empty list is returned.

 If `<stop>` is greater than the end index of the sorted set, Redis will use the last element of the sorted set.

 Score ranges
------------

 When the `BYSCORE` option is provided, the command behaves like [`ZRANGEBYSCORE`](../zrangebyscore) and returns the range of elements from the sorted set having scores equal or between `<start>` and `<stop>`.

 `<start>` and `<stop>` can be `-inf` and `+inf`, denoting the negative and positive infinities, respectively. This means that you are not required to know the highest or lowest score in the sorted set to get all elements from or up to a certain score.

 By default, the score intervals specified by `<start>` and `<stop>` are closed (inclusive). It is possible to specify an open interval (exclusive) by prefixing the score with the character `(`.

 For example:

 
```
ZRANGE zset (1 5 BYSCORE

```

Will return all elements with `1 < score <= 5` while:

 
```
ZRANGE zset (5 (10 BYSCORE

```

Will return all the elements with `5 < score < 10` (5 and 10 excluded).

 Reverse ranges
--------------

 Using the `REV` option reverses the sorted set, with index 0 as the element with the highest score.

 By default, `<start>` must be less than or equal to `<stop>` to return anything. However, if the `BYSCORE`, or `BYLEX` options are selected, the `<start>` is the highest score to consider, and `<stop>` is the lowest score to consider, therefore `<start>` must be greater than or equal to `<stop>` in order to return anything.

 For example:

 
```
ZRANGE zset 5 10 REV

```

Will return the elements between index 5 and 10 in the reversed index.

 
```
ZRANGE zset 10 5 REV BYSCORE

```

Will return all elements with scores less than 10 and greater than 5.

 Lexicographical ranges
----------------------

 When the `BYLEX` option is used, the command behaves like [`ZRANGEBYLEX`](../zrangebylex) and returns the range of elements from the sorted set between the `<start>` and `<stop>` lexicographical closed range intervals.

 Note that lexicographical ordering relies on all elements having the same score. The reply is unspecified when the elements have different scores.

 Valid `<start>` and `<stop>` must start with `(` or `[`, in order to specify whether the range interval is exclusive or inclusive, respectively.

 The special values of `+` or `-` for `<start>` and `<stop>` mean positive and negative infinite strings, respectively, so for instance the command `ZRANGE myzset - + BYLEX` is guaranteed to return all the elements in the sorted set, providing that all the elements have the same score.

 The `REV` options reverses the order of the `<start>` and `<stop>` elements, where `<start>` must be lexicographically greater than `<stop>` to produce a non-empty result.

 ### Lexicographical comparison of strings

 Strings are compared as a binary array of bytes. Because of how the ASCII character set is specified, this means that usually this also have the effect of comparing normal ASCII characters in an obvious dictionary way. However, this is not true if non-plain ASCII strings are used (for example, utf8 strings).

 However, the user can apply a transformation to the encoded string so that the first part of the element inserted in the sorted set will compare as the user requires for the specific application. For example, if I want to add strings that will be compared in a case-insensitive way, but I still want to retrieve the real case when querying, I can add strings in the following way:

 
```
ZADD autocomplete 0 foo:Foo 0 bar:BAR 0 zap:zap

```
 Because of the first *normalized* part in every element (before the colon character), we are forcing a given comparison. However, after the range is queried using `ZRANGE ... BYLEX`, the application can display to the user the second part of the string, after the colon.

 The binary nature of the comparison allows to use sorted sets as a general purpose index, for example, the first part of the element can be a 64-bit big-endian number. Since big-endian numbers have the most significant bytes in the initial positions, the binary comparison will match the numerical comparison of the numbers. This can be used in order to implement range queries on 64-bit values. As in the example below, after the first 8 bytes, we can store the value of the element we are indexing.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified range (optionally with their scores, in case the `WITHSCORES` option is given).

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZRANGE myzset 0 -1
ZRANGE myzset 2 3
ZRANGE myzset -2 -1

```
 The following example using `WITHSCORES` shows how the command returns always an array, but this time, populated with *element\_1*, *score\_1*, *element\_2*, *score\_2*, ..., *element\_N*, *score\_N*.

 
```

ZRANGE myzset 0 1 WITHSCORES

```
 This example shows how to query the sorted set by score, excluding the value `1` and up to infinity, returning only the second element of the result:

 
```

ZRANGE myzset (1 +inf BYSCORE LIMIT 1 1

```
 History
-------

 * Starting with Redis version 6.2.0: Added the `REV`, `BYSCORE`, `BYLEX` and `LIMIT` options.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrange/>

ZPOPMIN
=======



```
ZPOPMIN
```
 Syntax 
```
ZPOPMIN key [count]
```
  Available since: 5.0.0 Time complexity: O(log(N)\*M) with N being the number of elements in the sorted set, and M being the number of elements popped. ACL categories:  `@write`, `@sortedset`, `@fast`,   Removes and returns up to `count` members with the lowest scores in the sorted set stored at `key`.

 When left unspecified, the default value for `count` is 1. Specifying a `count` value that is higher than the sorted set's cardinality will not produce an error. When returning multiple elements, the one with the lowest score will be the first, followed by the elements with greater scores.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of popped elements and scores.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZPOPMIN myzset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zpopmin/>

ZINTERSTORE
===========



```
ZINTERSTORE
```
 Syntax 
```
ZINTERSTORE destination numkeys key [key ...] [WEIGHTS weight
  [weight ...]] [AGGREGATE <SUM | MIN | MAX>]
```
  Available since: 2.0.0 Time complexity: O(N\*K)+O(M\*log(M)) worst case with N being the smallest input sorted set, K being the number of input sorted sets and M being the number of elements in the resulting sorted set. ACL categories:  `@write`, `@sortedset`, `@slow`,   Computes the intersection of `numkeys` sorted sets given by the specified keys, and stores the result in `destination`. It is mandatory to provide the number of input keys (`numkeys`) before passing the input keys and the other (optional) arguments.

 By default, the resulting score of an element is the sum of its scores in the sorted sets where it exists. Because intersection requires an element to be a member of every given sorted set, this results in the score of every element in the resulting sorted set to be equal to the number of input sorted sets.

 For a description of the `WEIGHTS` and `AGGREGATE` options, see [`ZUNIONSTORE`](../zunionstore).

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting sorted set at `destination`.

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZADD zset2 3 "three"
ZINTERSTORE out 2 zset1 zset2 WEIGHTS 2 3
ZRANGE out 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zinterstore/>

ZREMRANGEBYLEX
==============



```
ZREMRANGEBYLEX
```
 Syntax 
```
ZREMRANGEBYLEX key min max
```
  Available since: 2.8.9 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements removed by the operation. ACL categories:  `@write`, `@sortedset`, `@slow`,   When all the elements in a sorted set are inserted with the same score, in order to force lexicographical ordering, this command removes all elements in the sorted set stored at `key` between the lexicographical range specified by `min` and `max`.

 The meaning of `min` and `max` are the same of the [`ZRANGEBYLEX`](../zrangebylex) command. Similarly, this command actually removes the same elements that [`ZRANGEBYLEX`](../zrangebylex) would return if called with the same `min` and `max` arguments.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements removed.

 Examples
--------

 
```

ZADD myzset 0 aaaa 0 b 0 c 0 d 0 e
ZADD myzset 0 foo 0 zap 0 zip 0 ALPHA 0 alpha
ZRANGE myzset 0 -1
ZREMRANGEBYLEX myzset [alpha [omega
ZRANGE myzset 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zremrangebylex/>

XRANGE
======



```
XRANGE
```
 Syntax 
```
XRANGE key start end [COUNT count]
```
  Available since: 5.0.0 Time complexity: O(N) with N being the number of elements being returned. If N is constant (e.g. always asking for the first 10 elements with COUNT), you can consider it O(1). ACL categories:  `@read`, `@stream`, `@slow`,   The command returns the stream entries matching a given range of IDs. The range is specified by a minimum and maximum ID. All the entries having an ID between the two specified or exactly one of the two IDs specified (closed interval) are returned.

 The `XRANGE` command has a number of applications:

 * Returning items in a specific time range. This is possible because Stream IDs are [related to time](https://redis.io/topics/streams-intro).
* Iterating a stream incrementally, returning just a few items at every iteration. However it is semantically much more robust than the [`SCAN`](../scan) family of functions.
* Fetching a single entry from a stream, providing the ID of the entry to fetch two times: as start and end of the query interval.

 The command also has a reciprocal command returning items in the reverse order, called [`XREVRANGE`](../xrevrange), which is otherwise identical.

 
`-` and `+` special IDs
------------------------

 The `-` and `+` special IDs mean respectively the minimum ID possible and the maximum ID possible inside a stream, so the following command will just return every entry in the stream:

 
```
> XRANGE somestream - +
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"
2) 1) 1526985069902-0
   2) 1) "duration"
      2) "415"
      3) "event-id"
      4) "2"
      5) "user-id"
      6) "772213"
... other entries here ...

```

The `-` and `+` special IDs mean, respectively, the minimal and maximal range IDs, however they are nicer to type.

 Incomplete IDs
--------------

 Stream IDs are composed of two parts, a Unix millisecond time stamp and a sequence number for entries inserted in the same millisecond. It is possible to use `XRANGE` specifying just the first part of the ID, the millisecond time, like in the following example:

 
```
> XRANGE somestream 1526985054069 1526985055069

```

In this case, `XRANGE` will auto-complete the start interval with `-0` and end interval with `-18446744073709551615`, in order to return all the entries that were generated between a given millisecond and the end of the other specified millisecond. This also means that repeating the same millisecond two times, we get all the entries within such millisecond, because the sequence number range will be from zero to the maximum.

 Used in this way `XRANGE` works as a range query command to obtain entries in a specified time. This is very handy in order to access the history of past events in a stream.

 Exclusive ranges
----------------

 The range is close (inclusive) by default, meaning that the reply can include entries with IDs matching the query's start and end intervals. It is possible to specify an open interval (exclusive) by prefixing the ID with the character `(`. This is useful for iterating the stream, as explained below.

 Returning a maximum number of entries
-------------------------------------

 Using the **COUNT** option it is possible to reduce the number of entries reported. This is a very important feature even if it may look marginal, because it allows, for instance, to model operations such as *give me the entry greater or equal to the following*:

 
```
> XRANGE somestream 1526985054069-0 + COUNT 1
1) 1) 1526985054069-0
   2) 1) "duration"
      2) "72"
      3) "event-id"
      4) "9"
      5) "user-id"
      6) "839248"

```

In the above case the entry `1526985054069-0` exists, otherwise the server would have sent us the next one. Using `COUNT` is also the base in order to use `XRANGE` as an iterator.

 Iterating a stream
------------------

 In order to iterate a stream, we can proceed as follows. Let's assume that we want two elements per iteration. We start fetching the first two elements, which is trivial:

 
```
> XRANGE writers - + COUNT 2
1) 1) 1526985676425-0
   2) 1) "name"
      2) "Virginia"
      3) "surname"
      4) "Woolf"
2) 1) 1526985685298-0
   2) 1) "name"
      2) "Jane"
      3) "surname"
      4) "Austen"

```

Then instead of starting the iteration again from `-`, as the start of the range we use the entry ID of the *last* entry returned by the previous `XRANGE` call as an exclusive interval.

 The ID of the last entry is `1526985685298-0`, so we just prefix it with a '(', and continue our iteration:

 
```
> XRANGE writers (1526985685298-0 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
      3) "surname"
      4) "Morrison"
2) 1) 1526985712947-0
   2) 1) "name"
      2) "Agatha"
      3) "surname"
      4) "Christie"

```

And so forth. Eventually this will allow to visit all the entries in the stream. Obviously, we can start the iteration from any ID, or even from a specific time, by providing a given incomplete start ID. Moreover, we can limit the iteration to a given ID or time, by providing an end ID or incomplete ID instead of `+`.

 The command [`XREAD`](../xread) is also able to iterate the stream. The command [`XREVRANGE`](../xrevrange) can iterate the stream reverse, from higher IDs (or times) to lower IDs (or times).

 ### Iterating with earlier versions of Redis

 While exclusive range intervals are only available from Redis 6.2, it is still possible to use a similar stream iteration pattern with earlier versions. You start fetching from the stream the same way as described above to obtain the first entries.

 For the subsequent calls, you'll need to programmatically advance the last entry's ID returned. Most Redis client should abstract this detail, but the implementation can also be in the application if needed. In the example above, this means incrementing the sequence of `1526985685298-0` by one, from 0 to 1. The second call would, therefore, be:

 
```
> XRANGE writers 1526985685298-1 + COUNT 2
1) 1) 1526985691746-0
   2) 1) "name"
      2) "Toni"
...

```

Also, note that once the sequence part of the last ID equals 18446744073709551615, you'll need to increment the timestamp and reset the sequence part to 0. For example, incrementing the ID `1526985685298-18446744073709551615` should result in `1526985685299-0`.

 A symmetrical pattern applies to iterating the stream with [`XREVRANGE`](../xrevrange). The only difference is that the client needs to decrement the ID for the subsequent calls. When decrementing an ID with a sequence part of 0, the timestamp needs to be decremented by 1 and the sequence set to 18446744073709551615.

 Fetching single items
---------------------

 If you look for an `XGET` command you'll be disappointed because `XRANGE` is effectively the way to go in order to fetch a single entry from a stream. All you have to do is to specify the ID two times in the arguments of XRANGE:

 
```
> XRANGE mystream 1526984818136-0 1526984818136-0
1) 1) 1526984818136-0
   2) 1) "duration"
      2) "1532"
      3) "event-id"
      4) "5"
      5) "user-id"
      6) "7782813"

```

Additional information about streams
------------------------------------

 For further information about Redis streams please check our [introduction to Redis Streams document](https://redis.io/topics/streams-intro).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays), specifically:

 The command returns the entries with IDs matching the specified range. The returned entries are complete, that means that the ID and all the fields they are composed are returned. Moreover, the entries are returned with their fields and values in the exact same order as [`XADD`](../xadd) added them.

 Examples
--------

 
```

XADD writers * name Virginia surname Woolf
XADD writers * name Jane surname Austen
XADD writers * name Toni surname Morrison
XADD writers * name Agatha surname Christie
XADD writers * name Ngozi surname Adichie
XLEN writers
XRANGE writers - + COUNT 2

```
 History
-------

 * Starting with Redis version 6.2.0: Added exclusive ranges.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/xrange/>

ZLEXCOUNT
=========



```
ZLEXCOUNT
```
 Syntax 
```
ZLEXCOUNT key min max
```
  Available since: 2.8.9 Time complexity: O(log(N)) with N being the number of elements in the sorted set. ACL categories:  `@read`, `@sortedset`, `@fast`,   When all the elements in a sorted set are inserted with the same score, in order to force lexicographical ordering, this command returns the number of elements in the sorted set at `key` with a value between `min` and `max`.

 The `min` and `max` arguments have the same meaning as described for [`ZRANGEBYLEX`](../zrangebylex).

 Note: the command has a complexity of just O(log(N)) because it uses elements ranks (see [`ZRANK`](../zrank)) to get an idea of the range. Because of this there is no need to do a work proportional to the size of the range.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the specified score range.

 Examples
--------

 
```

ZADD myzset 0 a 0 b 0 c 0 d 0 e
ZADD myzset 0 f 0 g
ZLEXCOUNT myzset - +
ZLEXCOUNT myzset [b [f

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zlexcount/>

ZMSCORE
=======



```
ZMSCORE
```
 Syntax 
```
ZMSCORE key member [member ...]
```
  Available since: 6.2.0 Time complexity: O(N) where N is the number of members being requested. ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the scores associated with the specified `members` in the sorted set stored at `key`.

 For every `member` that does not exist in the sorted set, a `nil` value is returned.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of scores or `nil` associated with the specified `member` values (a double precision floating point number), represented as strings.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZMSCORE myzset "one" "two" "nofield"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zmscore/>

ZMPOP
=====



```
ZMPOP
```
 Syntax 
```
ZMPOP numkeys key [key ...] <MIN | MAX> [COUNT count]
```
  Available since: 7.0.0 Time complexity: O(K) + O(M\*log(N)) where K is the number of provided keys, N being the number of elements in the sorted set, and M being the number of elements popped. ACL categories:  `@write`, `@sortedset`, `@slow`,   Pops one or more elements, that are member-score pairs, from the first non-empty sorted set in the provided list of key names.

 `ZMPOP` and [`BZMPOP`](../bzmpop) are similar to the following, more limited, commands:

 * [`ZPOPMIN`](../zpopmin) or [`ZPOPMAX`](../zpopmax) which take only one key, and can return multiple elements.
* [`BZPOPMIN`](../bzpopmin) or [`BZPOPMAX`](../bzpopmax) which take multiple keys, but return only one element from just one key.

 See [`BZMPOP`](../bzmpop) for the blocking variant of this command.

 When the `MIN` modifier is used, the elements popped are those with the lowest scores from the first non-empty sorted set. The `MAX` modifier causes elements with the highest scores to be popped. The optional `COUNT` can be used to specify the number of elements to pop, and is set to 1 by default.

 The number of popped elements is the minimum from the sorted set's cardinality and `COUNT`'s value.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): specifically:

 * A `nil` when no element could be popped.
* A two-element array with the first element being the name of the key from which elements were popped, and the second element is an array of the popped elements. Every entry in the elements array is also an array that contains the member and its score.

 Examples
--------

 
```

ZMPOP 1 notsuchkey MIN
ZADD myzset 1 "one" 2 "two" 3 "three"
ZMPOP 1 myzset MIN
ZRANGE myzset 0 -1 WITHSCORES
ZMPOP 1 myzset MAX COUNT 10
ZADD myzset2 4 "four" 5 "five" 6 "six"
ZMPOP 2 myzset myzset2 MIN COUNT 10
ZRANGE myzset 0 -1 WITHSCORES
ZMPOP 2 myzset myzset2 MAX COUNT 10
ZRANGE myzset2 0 -1 WITHSCORES
EXISTS myzset myzset2

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zmpop/>

ZRANGEBYLEX
===========



```
ZRANGEBYLEX (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`ZRANGE`](../zrange) with the `BYLEX` argument when migrating or writing new code.

  Syntax 
```
ZRANGEBYLEX key min max [LIMIT offset count]
```
  Available since: 2.8.9 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements being returned. If M is constant (e.g. always asking for the first 10 elements with LIMIT), you can consider it O(log(N)). ACL categories:  `@read`, `@sortedset`, `@slow`,   When all the elements in a sorted set are inserted with the same score, in order to force lexicographical ordering, this command returns all the elements in the sorted set at `key` with a value between `min` and `max`.

 If the elements in the sorted set have different scores, the returned elements are unspecified.

 The elements are considered to be ordered from lower to higher strings as compared byte-by-byte using the `memcmp()` C function. Longer strings are considered greater than shorter strings if the common part is identical.

 The optional `LIMIT` argument can be used to only get a range of the matching elements (similar to *SELECT LIMIT offset, count* in SQL). A negative `count` returns all elements from the `offset`. Keep in mind that if `offset` is large, the sorted set needs to be traversed for `offset` elements before getting to the elements to return, which can add up to O(N) time complexity.

 How to specify intervals
------------------------

 Valid *start* and *stop* must start with `(` or `[`, in order to specify if the range item is respectively exclusive or inclusive. The special values of `+` or `-` for *start* and *stop* have the special meaning or positively infinite and negatively infinite strings, so for instance the command **ZRANGEBYLEX myzset - +** is guaranteed to return all the elements in the sorted set, if all the elements have the same score.

 Details on strings comparison
-----------------------------

 Strings are compared as binary array of bytes. Because of how the ASCII character set is specified, this means that usually this also have the effect of comparing normal ASCII characters in an obvious dictionary way. However this is not true if non plain ASCII strings are used (for example utf8 strings).

 However the user can apply a transformation to the encoded string so that the first part of the element inserted in the sorted set will compare as the user requires for the specific application. For example if I want to add strings that will be compared in a case-insensitive way, but I still want to retrieve the real case when querying, I can add strings in the following way:

 
```
ZADD autocomplete 0 foo:Foo 0 bar:BAR 0 zap:zap

```
 Because of the first *normalized* part in every element (before the colon character), we are forcing a given comparison, however after the range is queries using `ZRANGEBYLEX` the application can display to the user the second part of the string, after the colon.

 The binary nature of the comparison allows to use sorted sets as a general purpose index, for example the first part of the element can be a 64 bit big endian number: since big endian numbers have the most significant bytes in the initial positions, the binary comparison will match the numerical comparison of the numbers. This can be used in order to implement range queries on 64 bit values. As in the example below, after the first 8 bytes we can store the value of the element we are actually indexing.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified score range.

 Examples
--------

 
```

ZADD myzset 0 a 0 b 0 c 0 d 0 e 0 f 0 g
ZRANGEBYLEX myzset - [c
ZRANGEBYLEX myzset - (c
ZRANGEBYLEX myzset [aaa (g

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrangebylex/>

ZREM
====



```
ZREM
```
 Syntax 
```
ZREM key member [member ...]
```
  Available since: 1.2.0 Time complexity: O(M\*log(N)) with N being the number of elements in the sorted set and M the number of elements to be removed. ACL categories:  `@write`, `@sortedset`, `@fast`,   Removes the specified members from the sorted set stored at `key`. Non existing members are ignored.

 An error is returned when `key` exists and does not hold a sorted set.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers), specifically:

 * The number of members removed from the sorted set, not including non existing members.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREM myzset "two"
ZRANGE myzset 0 -1 WITHSCORES

```
 History
-------

 * Starting with Redis version 2.4.0: Accepts multiple elements.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrem/>

ZREMRANGEBYRANK
===============



```
ZREMRANGEBYRANK
```
 Syntax 
```
ZREMRANGEBYRANK key start stop
```
  Available since: 2.0.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements removed by the operation. ACL categories:  `@write`, `@sortedset`, `@slow`,   Removes all elements in the sorted set stored at `key` with rank between `start` and `stop`. Both `start` and `stop` are `0` -based indexes with `0` being the element with the lowest score. These indexes can be negative numbers, where they indicate offsets starting at the element with the highest score. For example: `-1` is the element with the highest score, `-2` the element with the second highest score and so forth.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements removed.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREMRANGEBYRANK myzset 0 1
ZRANGE myzset 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zremrangebyrank/>

ZPOPMAX
=======



```
ZPOPMAX
```
 Syntax 
```
ZPOPMAX key [count]
```
  Available since: 5.0.0 Time complexity: O(log(N)\*M) with N being the number of elements in the sorted set, and M being the number of elements popped. ACL categories:  `@write`, `@sortedset`, `@fast`,   Removes and returns up to `count` members with the highest scores in the sorted set stored at `key`.

 When left unspecified, the default value for `count` is 1. Specifying a `count` value that is higher than the sorted set's cardinality will not produce an error. When returning multiple elements, the one with the highest score will be the first, followed by the elements with lower scores.

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of popped elements and scores.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZPOPMAX myzset

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zpopmax/>

ZRANGEBYSCORE
=============



```
ZRANGEBYSCORE (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`ZRANGE`](../zrange) with the `BYSCORE` argument when migrating or writing new code.

  Syntax 
```
ZRANGEBYSCORE key min max [WITHSCORES] [LIMIT offset count]
```
  Available since: 1.0.5 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements being returned. If M is constant (e.g. always asking for the first 10 elements with LIMIT), you can consider it O(log(N)). ACL categories:  `@read`, `@sortedset`, `@slow`,   Returns all the elements in the sorted set at `key` with a score between `min` and `max` (including elements with score equal to `min` or `max`). The elements are considered to be ordered from low to high scores.

 The elements having the same score are returned in lexicographical order (this follows from a property of the sorted set implementation in Redis and does not involve further computation).

 The optional `LIMIT` argument can be used to only get a range of the matching elements (similar to *SELECT LIMIT offset, count* in SQL). A negative `count` returns all elements from the `offset`. Keep in mind that if `offset` is large, the sorted set needs to be traversed for `offset` elements before getting to the elements to return, which can add up to O(N) time complexity.

 The optional `WITHSCORES` argument makes the command return both the element and its score, instead of the element alone. This option is available since Redis 2.0.

 Exclusive intervals and infinity
--------------------------------

 `min` and `max` can be `-inf` and `+inf`, so that you are not required to know the highest or lowest score in the sorted set to get all elements from or up to a certain score.

 By default, the interval specified by `min` and `max` is closed (inclusive). It is possible to specify an open interval (exclusive) by prefixing the score with the character `(`. For example:

 
```
ZRANGEBYSCORE zset (1 5

```

Will return all elements with `1 < score <= 5` while:

 
```
ZRANGEBYSCORE zset (5 (10

```

Will return all the elements with `5 < score < 10` (5 and 10 excluded).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified score range (optionally with their scores).

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZRANGEBYSCORE myzset -inf +inf
ZRANGEBYSCORE myzset 1 2
ZRANGEBYSCORE myzset (1 2
ZRANGEBYSCORE myzset (1 (2

```
 Pattern: weighted random selection of an element
------------------------------------------------

 Normally `ZRANGEBYSCORE` is simply used in order to get range of items where the score is the indexed integer key, however it is possible to do less obvious things with the command.

 For example a common problem when implementing Markov chains and other algorithms is to select an element at random from a set, but different elements may have different weights that change how likely it is they are picked.

 This is how we use this command in order to mount such an algorithm:

 Imagine you have elements A, B and C with weights 1, 2 and 3. You compute the sum of the weights, which is 1+2+3 = 6

 At this point you add all the elements into a sorted set using this algorithm:

 
```
SUM = ELEMENTS.TOTAL_WEIGHT // 6 in this case.
SCORE = 0
FOREACH ELE in ELEMENTS
    SCORE += ELE.weight / SUM
    ZADD KEY SCORE ELE
END

```

This means that you set:

 
```
A to score 0.16
B to score .5
C to score 1

```

Since this involves approximations, in order to avoid C is set to, like, 0.998 instead of 1, we just modify the above algorithm to make sure the last score is 1 (left as an exercise for the reader...).

 At this point, each time you want to get a weighted random element, just compute a random number between 0 and 1 (which is like calling `rand()` in most languages), so you can just do:

 
```
RANDOM_ELE = ZRANGEBYSCORE key RAND() +inf LIMIT 0 1

```
 History
-------

 * Starting with Redis version 2.0.0: Added the `WITHSCORES` modifier.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrangebyscore/>

ZRANK
=====



```
ZRANK
```
 Syntax 
```
ZRANK key member [WITHSCORE]
```
  Available since: 2.0.0 Time complexity: O(log(N)) ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the rank of `member` in the sorted set stored at `key`, with the scores ordered from low to high. The rank (or index) is 0-based, which means that the member with the lowest score has rank `0`.

 The optional `WITHSCORE` argument supplements the command's reply with the score of the element returned.

 Use [`ZREVRANK`](../zrevrank) to get the rank of an element with the scores ordered from high to low.

 Return
------

 * If `member` exists in the sorted set:
	+ using `WITHSCORE`, [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): an array containing the rank and score of `member`.
	+ without using `WITHSCORE`, [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the rank of `member`.
* If `member` does not exist in the sorted set or `key` does not exist:
	+ using `WITHSCORE`, [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): `nil`.
	+ without using `WITHSCORE`, [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): `nil`.

 Note that in RESP3 null and nullarray are the same, but in RESP2 they are not.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZRANK myzset "three"
ZRANK myzset "four"
ZRANK myzset "three" WITHSCORE
ZRANK myzset "four" WITHSCORE

```
 History
-------

 * Starting with Redis version 7.2.0: Added the optional `WITHSCORE` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrank/>

ZREVRANGE
=========



```
ZREVRANGE (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`ZRANGE`](../zrange) with the `REV` argument when migrating or writing new code.

  Syntax 
```
ZREVRANGE key start stop [WITHSCORES]
```
  Available since: 1.2.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements returned. ACL categories:  `@read`, `@sortedset`, `@slow`,   Returns the specified range of elements in the sorted set stored at `key`. The elements are considered to be ordered from the highest to the lowest score. Descending lexicographical order is used for elements with equal score.

 Apart from the reversed ordering, `ZREVRANGE` is similar to [`ZRANGE`](../zrange).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified range (optionally with their scores).

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREVRANGE myzset 0 -1
ZREVRANGE myzset 2 3
ZREVRANGE myzset -2 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrevrange/>

ZRANDMEMBER
===========



```
ZRANDMEMBER
```
 Syntax 
```
ZRANDMEMBER key [count [WITHSCORES]]
```
  Available since: 6.2.0 Time complexity: O(N) where N is the number of members returned ACL categories:  `@read`, `@sortedset`, `@slow`,   When called with just the `key` argument, return a random element from the sorted set value stored at `key`.

 If the provided `count` argument is positive, return an array of **distinct elements**. The array's length is either `count` or the sorted set's cardinality ([`ZCARD`](../zcard)), whichever is lower.

 If called with a negative `count`, the behavior changes and the command is allowed to return the **same element multiple times**. In this case, the number of returned elements is the absolute value of the specified `count`.

 The optional `WITHSCORES` modifier changes the reply so it includes the respective scores of the randomly selected elements from the sorted set.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): without the additional `count` argument, the command returns a Bulk Reply with the randomly selected element, or `nil` when `key` does not exist.

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): when the additional `count` argument is passed, the command returns an array of elements, or an empty array when `key` does not exist. If the `WITHSCORES` modifier is used, the reply is a list elements and their scores from the sorted set.

 Examples
--------

 
```

ZADD dadi 1 uno 2 due 3 tre 4 quattro 5 cinque 6 sei
ZRANDMEMBER dadi
ZRANDMEMBER dadi
ZRANDMEMBER dadi -5 WITHSCORES

```
 Specification of the behavior when count is passed
--------------------------------------------------

 When the `count` argument is a positive value this command behaves as follows:

 * No repeated elements are returned.
* If `count` is bigger than the cardinality of the sorted set, the command will only return the whole sorted set without additional elements.
* The order of elements in the reply is not truly random, so it is up to the client to shuffle them if needed.

 When the `count` is a negative value, the behavior changes as follows:

 * Repeating elements are possible.
* Exactly `count` elements, or an empty array if the sorted set is empty (non-existing key), are always returned.
* The order of elements in the reply is truly random.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrandmember/>

ZREMRANGEBYSCORE
================



```
ZREMRANGEBYSCORE
```
 Syntax 
```
ZREMRANGEBYSCORE key min max
```
  Available since: 1.2.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements removed by the operation. ACL categories:  `@write`, `@sortedset`, `@slow`,   Removes all elements in the sorted set stored at `key` with a score between `min` and `max` (inclusive).

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements removed.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREMRANGEBYSCORE myzset -inf (2
ZRANGE myzset 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zremrangebyscore/>

ZREVRANGEBYSCORE
================



```
ZREVRANGEBYSCORE (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`ZRANGE`](../zrange) with the `REV` and `BYSCORE` arguments when migrating or writing new code.

  Syntax 
```
ZREVRANGEBYSCORE key max min [WITHSCORES] [LIMIT offset count]
```
  Available since: 2.2.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements being returned. If M is constant (e.g. always asking for the first 10 elements with LIMIT), you can consider it O(log(N)). ACL categories:  `@read`, `@sortedset`, `@slow`,   Returns all the elements in the sorted set at `key` with a score between `max` and `min` (including elements with score equal to `max` or `min`). In contrary to the default ordering of sorted sets, for this command the elements are considered to be ordered from high to low scores.

 The elements having the same score are returned in reverse lexicographical order.

 Apart from the reversed ordering, `ZREVRANGEBYSCORE` is similar to [`ZRANGEBYSCORE`](../zrangebyscore).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified score range (optionally with their scores).

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREVRANGEBYSCORE myzset +inf -inf
ZREVRANGEBYSCORE myzset 2 1
ZREVRANGEBYSCORE myzset 2 (1
ZREVRANGEBYSCORE myzset (2 (1

```
 History
-------

 * Starting with Redis version 2.1.6: `min` and `max` can be exclusive.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrevrangebyscore/>

ZREVRANGEBYLEX
==============



```
ZREVRANGEBYLEX (deprecated)
```
  As of Redis version 6.2.0, this command is regarded as deprecated.

 It can be replaced by [`ZRANGE`](../zrange) with the `REV` and `BYLEX` arguments when migrating or writing new code.

  Syntax 
```
ZREVRANGEBYLEX key max min [LIMIT offset count]
```
  Available since: 2.8.9 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements being returned. If M is constant (e.g. always asking for the first 10 elements with LIMIT), you can consider it O(log(N)). ACL categories:  `@read`, `@sortedset`, `@slow`,   When all the elements in a sorted set are inserted with the same score, in order to force lexicographical ordering, this command returns all the elements in the sorted set at `key` with a value between `max` and `min`.

 Apart from the reversed ordering, `ZREVRANGEBYLEX` is similar to [`ZRANGEBYLEX`](../zrangebylex).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): list of elements in the specified score range.

 Examples
--------

 
```

ZADD myzset 0 a 0 b 0 c 0 d 0 e 0 f 0 g
ZREVRANGEBYLEX myzset [c -
ZREVRANGEBYLEX myzset (c -
ZREVRANGEBYLEX myzset (g [aaa

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrevrangebylex/>

ZSCAN
=====



```
ZSCAN
```
 Syntax 
```
ZSCAN key cursor [MATCH pattern] [COUNT count]
```
  Available since: 2.8.0 Time complexity: O(1) for every call. O(N) for a complete iteration, including enough command calls for the cursor to return back to 0. N is the number of elements inside the collection. ACL categories:  `@read`, `@sortedset`, `@slow`,   See [`SCAN`](../scan) for `ZSCAN` documentation.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zscan/>

ZRANGESTORE
===========



```
ZRANGESTORE
```
 Syntax 
```
ZRANGESTORE dst src min max [BYSCORE | BYLEX] [REV] [LIMIT offset
  count]
```
  Available since: 6.2.0 Time complexity: O(log(N)+M) with N being the number of elements in the sorted set and M the number of elements stored into the destination key. ACL categories:  `@write`, `@sortedset`, `@slow`,   This command is like [`ZRANGE`](../zrange), but stores the result in the `<dst>` destination key.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting sorted set.

 Examples
--------

 
```

ZADD srczset 1 "one" 2 "two" 3 "three" 4 "four"
ZRANGESTORE dstzset srczset 2 -1
ZRANGE dstzset 0 -1

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrangestore/>

ZREVRANK
========



```
ZREVRANK
```
 Syntax 
```
ZREVRANK key member [WITHSCORE]
```
  Available since: 2.0.0 Time complexity: O(log(N)) ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the rank of `member` in the sorted set stored at `key`, with the scores ordered from high to low. The rank (or index) is 0-based, which means that the member with the highest score has rank `0`.

 The optional `WITHSCORE` argument supplements the command's reply with the score of the element returned.

 Use [`ZRANK`](../zrank) to get the rank of an element with the scores ordered from low to high.

 Return
------

 * If `member` exists in the sorted set:
	+ using `WITHSCORE`, [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): an array containing the rank and score of `member`.
	+ without using `WITHSCORE`, [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the rank of `member`.
* If `member` does not exist in the sorted set or `key` does not exist:
	+ using `WITHSCORE`, [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): `nil`.
	+ without using `WITHSCORE`, [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): `nil`.

 Note that in RESP3 null and nullarray are the same, but in RESP2 they are not.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZADD myzset 2 "two"
ZADD myzset 3 "three"
ZREVRANK myzset "one"
ZREVRANK myzset "four"
ZREVRANK myzset "three" WITHSCORE
ZREVRANK myzset "four" WITHSCORE

```
 History
-------

 * Starting with Redis version 7.2.0: Added the optional `WITHSCORE` argument.



 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zrevrank/>

ZUNIONSTORE
===========



```
ZUNIONSTORE
```
 Syntax 
```
ZUNIONSTORE destination numkeys key [key ...] [WEIGHTS weight
  [weight ...]] [AGGREGATE <SUM | MIN | MAX>]
```
  Available since: 2.0.0 Time complexity: O(N)+O(M log(M)) with N being the sum of the sizes of the input sorted sets, and M being the number of elements in the resulting sorted set. ACL categories:  `@write`, `@sortedset`, `@slow`,   Computes the union of `numkeys` sorted sets given by the specified keys, and stores the result in `destination`. It is mandatory to provide the number of input keys (`numkeys`) before passing the input keys and the other (optional) arguments.

 By default, the resulting score of an element is the sum of its scores in the sorted sets where it exists.

 Using the `WEIGHTS` option, it is possible to specify a multiplication factor for each input sorted set. This means that the score of every element in every input sorted set is multiplied by this factor before being passed to the aggregation function. When `WEIGHTS` is not given, the multiplication factors default to `1`.

 With the `AGGREGATE` option, it is possible to specify how the results of the union are aggregated. This option defaults to `SUM`, where the score of an element is summed across the inputs where it exists. When this option is set to either `MIN` or `MAX`, the resulting set will contain the minimum or maximum score of an element across the inputs where it exists.

 If `destination` already exists, it is overwritten.

 Return
------

 [Integer reply](https://redis.io/docs/reference/protocol-spec#resp-integers): the number of elements in the resulting sorted set at `destination`.

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZADD zset2 3 "three"
ZUNIONSTORE out 2 zset1 zset2 WEIGHTS 2 3
ZRANGE out 0 -1 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zunionstore/>

ZSCORE
======



```
ZSCORE
```
 Syntax 
```
ZSCORE key member
```
  Available since: 1.2.0 Time complexity: O(1) ACL categories:  `@read`, `@sortedset`, `@fast`,   Returns the score of `member` in the sorted set at `key`.

 If `member` does not exist in the sorted set, or `key` does not exist, `nil` is returned.

 Return
------

 [Bulk string reply](https://redis.io/docs/reference/protocol-spec#resp-bulk-strings): the score of `member` (a double precision floating point number), represented as string.

 Examples
--------

 
```

ZADD myzset 1 "one"
ZSCORE myzset "one"

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zscore/>

ZUNION
======



```
ZUNION
```
 Syntax 
```
ZUNION numkeys key [key ...] [WEIGHTS weight [weight ...]]
  [AGGREGATE <SUM | MIN | MAX>] [WITHSCORES]
```
  Available since: 6.2.0 Time complexity: O(N)+O(M\*log(M)) with N being the sum of the sizes of the input sorted sets, and M being the number of elements in the resulting sorted set. ACL categories:  `@read`, `@sortedset`, `@slow`,   This command is similar to [`ZUNIONSTORE`](../zunionstore), but instead of storing the resulting sorted set, it is returned to the client.

 For a description of the `WEIGHTS` and `AGGREGATE` options, see [`ZUNIONSTORE`](../zunionstore).

 Return
------

 [Array reply](https://redis.io/docs/reference/protocol-spec#resp-arrays): the result of union (optionally with their scores, in case the `WITHSCORES` option is given).

 Examples
--------

 
```

ZADD zset1 1 "one"
ZADD zset1 2 "two"
ZADD zset2 1 "one"
ZADD zset2 2 "two"
ZADD zset2 3 "three"
ZUNION 2 zset1 zset2
ZUNION 2 zset1 zset2 WITHSCORES

```


 © 2006–2022 Salvatore Sanfilippo  
Licensed under the Creative Commons Attribution-ShareAlike License 4.0.  

<https://redis.io/commands/zunion/>

redis