opencode-skills-collection 3.1.12 → 3.1.13

package/bundled-skills/redis-cli/references/data-query-commands.md

@@ -0,0 +1,417 @@
+# Data Query Commands
+
+Complete command reference for querying and manipulating data in Redis, organized by data type. Each entry includes syntax, complexity, and key behavioral notes.
+
+## Table of Contents
+
+- [Strings](#strings)
+- [Hashes](#hashes)
+- [Lists](#lists)
+- [Sets](#sets)
+- [Sorted Sets](#sorted-sets)
+- [Streams](#streams)
+- [Bitmaps and Bitfields](#bitmaps-and-bitfields)
+- [HyperLogLog](#hyperloglog)
+- [Geospatial](#geospatial)
+- [Key Operations](#key-operations)
+- [Database Operations](#database-operations)
+- [Transactions](#transactions)
+
+## Strings
+
+Strings are the most basic Redis type, holding up to 512MB. They can store text, numbers (for INCR/DECR), or binary data.
+
+```
+# Read / Write
+GET key                                # Get value                        O(1)
+SET key value [EX sec|PX ms|EXAT ts|PXAT ms|KEEPTTL]  # Set with optional expiry  O(1)
+SET key value [NX|XX]                  # NX=only if not exists, XX=exists O(1)
+SET key value GET                      # Set and return old value         O(1)
+GETSET key newvalue                    # [Deprecated 6.2] Use SET key value GET
+GETDEL key                             # Get then delete                  O(1)
+GETEX key [EX sec|PX ms|PERSIST]       # Get and set/remove expiry        O(1)
+
+# Multi-key
+MGET key [key ...]                     # Get multiple values              O(N)
+MSET key value [key value ...]         # Set multiple values              O(N)
+MSETNX key value [key value ...]       # Set if NONE exist                O(N)
+
+# Numeric operations (value must be integer or float)
+INCR key                               # +1                               O(1)
+INCRBY key increment                   # +N                               O(1)
+INCRBYFLOAT key increment              # +float                           O(1)
+DECR key                               # -1                               O(1)
+DECRBY key decrement                   # -N                               O(1)
+
+# String manipulation
+STRLEN key                             # Length in bytes                  O(1)
+GETRANGE key start end                 # Substring                        O(N)
+SETRANGE key offset value              # Overwrite at position            O(N)
+APPEND key value                       # Append to string                 O(1)
+SUBSTR key start end                   # Alias for GETRANGE               O(N)
+
+# Conditional set (Redis 8.4+)
+SET key value IFEQ expected-value      # Set only if current value matches
+SET key value IFNE expected-value      # Set only if current value differs
+SET key value IFDEQ expected-digest    # Set only if digest matches (hash comparison)
+SET key value IFDNE expected-digest    # Set only if digest differs
+```
+
+**Behavioral notes:**
+- `SET` overwrites any existing value regardless of type and clears any existing TTL
+- `SET NX` is commonly used for distributed locks
+- `INCR`/`DECR` fail if the value is not a valid integer; use `INCRBYFLOAT` for decimals
+- `GETRANGE` is 0-indexed; negative indices count from end (-1 = last character)
+- Empty string uses ~56 bytes of overhead (`MEMORY USAGE`)
+
+## Hashes
+
+Hashes map string fields to string values — ideal for representing objects. Small hashes are stored in a memory-efficient ziplist encoding.
+
+```
+# Read
+HGET key field                         # Get field value                  O(1)
+HMGET key field [field ...]            # Get multiple fields              O(N)
+HGETALL key                            # Get all fields and values        O(N)
+HKEYS key                              # Get all field names              O(N)
+HVALS key                              # Get all values                   O(N)
+HLEN key                               # Number of fields                 O(1)
+HEXISTS key field                      # Check field exists               O(1)
+HRANDFIELD key [count [WITHVALUES]]    # Random field(s)                  O(N)
+
+# Write
+HSET key field value [field value ...] # Set one or more fields           O(N)
+HSETNX key field value                 # Set field only if not exists     O(1)
+HDEL key field [field ...]             # Delete fields                    O(N)
+
+# Numeric
+HINCRBY key field increment            # Increment integer field          O(1)
+HINCRBYFLOAT key field increment       # Increment float field            O(1)
+
+# Iterate
+HSCAN key cursor [MATCH pat] [COUNT n] [NOVALUES]  # Incremental iterate O(1)/call
+
+# Field-level expiry (Redis 7.4+)
+HEXPIRE key seconds [NX|XX|GT|LT] FIELDS numfields field [field ...]  # Set field TTL
+HPEXPIRE key milliseconds [NX|XX|GT|LT] FIELDS numfields field [field ...]  # Set field TTL (ms)
+HTTL key numfields field [field ...]               # Get field TTL
+HPERSIST key [NX|XX|GT|LT] FIELDS numfields field [field ...]  # Remove field TTL
+```
+
+**Behavioral notes:**
+- `HGETALL` returns alternating field-value pairs: `[field1, value1, field2, value2, ...]`
+- `HGETALL` on a non-existent key returns an empty list
+- Field order in `HGETALL` and `HKEYS` is non-deterministic
+- `HSCAN` with `NOVALUES` returns field names only (saves bandwidth)
+- For small hashes, `HGETALL` is efficient; for large ones, prefer `HSCAN`
+- Minimum hash length is 0 (empty hash after HDEL of last field)
+
+## Lists
+
+Lists are ordered sequences of strings, implemented as linked lists for fast head/tail operations. Good for queues, stacks, and timelines.
+
+```
+# Read
+LRANGE key start stop                  # Get range (0 -1 = all)          O(N)
+LLEN key                               # List length                      O(1)
+LINDEX key index                       # Get by index (0-based)           O(N)
+LPOS key value [RANK rank] [COUNT n] [MAXLEN len]  # Find position   O(N)
+LMPOP numkeys key [key ...] LEFT|RIGHT [COUNT count]  # Pop from multiple lists  O(N+M)
+
+# Write (push)
+LPUSH key element [element ...]        # Push to head                     O(N) for N elements
+RPUSH key element [element ...]        # Push to tail                     O(N) for N elements
+LPUSHX key element                     # Push to head if exists           O(1)
+RPUSHX key element                     # Push to tail if exists           O(1)
+LINSERT key BEFORE|AFTER pivot element # Insert relative to pivot        O(N)
+
+# Write (pop)
+LPOP key [count]                       # Pop from head                    O(N) for count
+RPOP key [count]                       # Pop from tail                    O(N) for count
+BLPOP key [key ...] timeout            # Blocking pop from head           O(N)
+BRPOP key [key ...] timeout            # Blocking pop from tail           O(N)
+
+# Move
+LMOVE source destination LEFT|RIGHT LEFT|RIGHT  # Atomic move       O(1)
+BLMOVE src dest L|R L|R timeout       # Blocking move                    O(1)
+RPOPLPUSH source destination           # [Deprecated 6.2] Use LMOVE       O(1)
+
+# Modify
+LSET key index element                 # Set at index                     O(N)
+LREM key count element                 # Remove occurrences               O(N+M)
+LTRIM key start stop                   # Keep only range                  O(N)
+```
+
+**Behavioral notes:**
+- `LRANGE key 0 -1` returns all elements; `LRANGE key 0 9` returns first 10
+- Negative indexes count from end: `-1` is last element
+- `LPUSH` with multiple elements pushes them left-to-right, so final order is reversed
+- `LPOP`/`RPOP` with count (Redis 6.2+) returns an array; without count returns a single element or nil
+- `LTRIM` is often combined with `LPUSH` to maintain a capped list
+- `BLPOP`/`BRPOP` block the client until data is available or timeout expires (0 = wait forever)
+
+## Sets
+
+Sets are unordered collections of unique strings. Good for membership checking, deduplication, and set operations.
+
+```
+# Read
+SMEMBERS key                           # Get all members                  O(N)
+SCARD key                              # Member count                     O(1)
+SISMEMBER key member                   # Check membership                 O(1)
+SMISMEMBER key member [member ...]     # Multi-membership check           O(N)
+SRANDMEMBER key [count]                # Random member(s)                 O(N)
+SSCAN key cursor [MATCH pat] [COUNT n] # Incremental iterate              O(1)/call
+
+# Write
+SADD key member [member ...]           # Add members                      O(N)
+SREM key member [member ...]           # Remove members                   O(N)
+SPOP key [count]                       # Remove and return random         O(N)
+SMOVE source dest member               # Move member between sets         O(1)
+
+# Set operations
+SINTER key [key ...]                   # Intersection                     O(N*M)
+SINTERCARD numkeys key [key ...] [LIMIT limit]  # Intersection cardinality  O(N*M)
+SINTERSTORE dest key [key ...]         # Intersection → new set           O(N*M)
+SUNION key [key ...]                   # Union                            O(N)
+SUNIONSTORE dest key [key ...]         # Union → new set                  O(N)
+SDIFF key [key ...]                    # Difference (first - rest)        O(N)
+SDIFFSTORE dest key [key ...]          # Difference → new set             O(N)
+```
+
+**Behavioral notes:**
+- `SMEMBERS` returns all members; for large sets, use `SSCAN`
+- `SRANDMEMBER` with positive count returns distinct elements (may be fewer than count if count > set size)
+- `SRANDMEMBER` with negative count may return duplicates (always returns exactly count elements)
+- `SPOP` removes the element(s) from the set; `SRANDMEMBER` does not
+- `SDIFF` computes difference starting from the first key — order matters
+
+## Sorted Sets
+
+Sorted sets (zsets) map members to scores. Members are unique and ordered by score, then lexicographically. Good for leaderboards, rankings, and priority queues.
+
+```
+# Read by index
+ZRANGE key start stop [WITHSCORES]               # By rank              O(log(N)+M)
+ZRANGESTORE dest src start stop                   # Store range          O(log(N)+M)
+
+# Read by score
+ZRANGE key min max BYSCORE [WITHSCORES] [LIMIT offset count]  # By score O(log(N)+M)
+ZCOUNT key min max                                # Count in score range O(log(N))
+ZLEXCOUNT key min max                             # Count in lex range   O(log(N))
+
+# Read by lexicographic order (all members must have same score)
+ZRANGE key min max BYLEX [LIMIT offset count]     # By lex              O(log(N)+M)
+
+# Member lookup
+ZSCORE key member                                 # Get score            O(1)
+ZRANK key member                                  # Get rank (ascending) O(log(N))
+ZREVRANK key member                               # Get rank (descending)O(log(N))
+ZMSCORE key member [member ...]                   # Multi-score get      O(N)
+
+# Aggregate info
+ZCARD key                                         # Member count         O(1)
+ZRANDMEMBER key [count [WITHSCORES]]              # Random member(s)     O(N)
+
+# Iterate
+ZSCAN key cursor [MATCH pat] [COUNT n]            # Incremental iterate  O(1)/call
+
+# Pop extremes
+ZPOPMIN key [count]                               # Remove lowest scored O(log(N)*count)
+ZPOPMAX key [count]                               # Remove highest scoredO(log(N)*count)
+BZPOPMIN key [key ...] timeout                    # Blocking pop min     O(log(N))
+BZPOPMAX key [key ...] timeout                    # Blocking pop max     O(log(N))
+ZMPOP numkeys key [key ...] MIN|MAX [COUNT count] # Pop from multiple    O(K)+O(M*log(N))
+
+# Write
+ZADD key [NX|XX] [GT|LT] [CH] score member [score member ...]  # Add/update  O(log(N))
+ZREM key member [member ...]                      # Remove members       O(M*log(N))
+ZINCRBY key increment member                      # Increment score      O(log(N))
+
+# Remove by range
+ZREMRANGEBYRANK key start stop                    # Remove by rank       O(log(N)+M)
+ZREMRANGEBYSCORE key min max                      # Remove by score      O(log(N)+M)
+ZREMRANGEBYLEX key min max                        # Remove by lex        O(log(N)+M)
+
+# Set operations
+ZUNIONSTORE dest numkeys key [key ...] [WEIGHTS w...] [AGGREGATE SUM|MIN|MAX]
+ZINTERSTORE dest numkeys key [key ...] [WEIGHTS w...] [AGGREGATE SUM|MIN|MAX]
+ZUNION numkeys key [key ...] [WITHSCORES]         # Union result
+ZINTER numkeys key [key ...] [WITHSCORES]         # Intersection result
+ZINTERCARD numkeys key [key ...] [LIMIT limit]    # Intersection count
+ZDIFF numkeys key [key ...] [WITHSCORES]          # Difference result
+ZDIFFSTORE dest numkeys key [key ...]             # Difference → new set
+```
+
+**Behavioral notes:**
+- `ZRANGE` replaces `ZRANGEBYSCORE`, `ZRANGEBYLEX`, `ZREVRANGE`, `ZREVRANGEBYSCORE`, `ZREVRANGEBYLEX` (all deprecated since Redis 6.2)
+- Index-based: `0` is lowest score, `-1` is highest; `REV` flag reverses order
+- Score-based: use `-inf` and `+inf` for unbounded ranges; `(` prefix means exclusive: `(1 10` = scores >1 and <=10
+- Lex-based: use `[` for inclusive, `(` for exclusive: `[a (z` = members >= "a" and < "z"
+- `ZADD` options: `NX` (only add new), `XX` (only update existing), `GT` (only if new score > current), `LT` (only if new score < current), `CH` (return number of changed elements)
+- `WITHSCORES` returns alternating member,score pairs
+
+## Streams
+
+Streams are append-only log data structures with consumer groups for message processing.
+
+```
+# Write
+XADD key [NOMKSTREAM] [MAXLEN|MINID [=|~] threshold [LIMIT count]] *|ID field value [field value ...]
+                                        # Add entry                            O(1)
+XADD key [KEEPREF|DELREF|ACKED] ...     # Reference control (Redis 8.2+)
+XADD key [IDMPAUTO pid | IDMP pid iid] ...  # Idempotent add (Redis 8.6+)
+
+# Read
+XRANGE key start end [COUNT count]                 # Read by ID range     O(N)
+XREVRANGE key end start [COUNT count]              # Reverse read         O(N)
+XREAD [COUNT count] [BLOCK ms] STREAMS key [key ...] ID [ID ...]  # Read new entries
+XLEN key                                           # Entry count          O(1)
+
+# Consumer groups
+XGROUP CREATE key groupname ID|$ [MKSTREAM]        # Create group
+XREADGROUP GROUP group consumer [COUNT n] [BLOCK ms] [NOACK] STREAMS key [key ...] ID [ID ...]
+XPENDING key group                                 # Pending messages info
+XACK key group ID [ID ...]                         # Acknowledge message
+XCLAIM key group consumer min-idle-time ID [ID ...] [IDLE ms] [TIME ms] [RETRYCOUNT n] [FORCE] [JUSTID]
+XAUTOCLAIM key group consumer min-idle-time start [COUNT count] [JUSTID]
+
+# Info
+XINFO STREAM key                                   # Stream info
+XINFO GROUPS key                                   # Consumer group info
+XINFO CONSUMERS key group                          # Consumer info
+
+# Management
+XTRIM key MAXLEN|MINID [=|~] threshold [LIMIT count]  # Trim stream
+XDEL key ID [ID ...]                               # Delete entries
+XSETID key last-idle                               # Set last ID
+```
+
+**Behavioral notes:**
+- `XADD` with `*` auto-generates an ID in format `TIMESTAMP-SEQUENCE`
+- `XRANGE key - +` returns all entries; use `COUNT` to limit
+- `XREAD BLOCK 0 STREAMS mystream $` blocks until new entries arrive (`$` = latest ID)
+- Consumer groups enable multiple consumers to process a stream collaboratively
+- Use `XREADGROUP ... STREAMS key >` to read new unassigned messages
+
+## Bitmaps and Bitfields
+
+Bitmaps are strings treated as arrays of bits. Bitfields provide atomic operations on arbitrary-width integers at bit offsets.
+
+```
+# Bitmap operations
+SETBIT key offset value                # Set bit at offset                O(1)
+GETBIT key offset                      # Get bit at offset                O(1)
+BITCOUNT key [start end [BYTE|BIT]]    # Count set bits                   O(N)
+BITPOS key bit [start [end [BYTE|BIT]]]  # Find first set/unset bit       O(N)
+BITOP AND|OR|XOR|NOT dest key [key ...] # Bitwise operations              O(N)
+
+# Bitfield operations
+BITFIELD key [GET type offset] [SET type offset value] [INCRBY type offset increment] [OVERFLOW WRAP|SAT|FAIL]
+```
+
+## HyperLogLog
+
+HyperLogLog provides approximate cardinality counting with ~0.81% standard error using constant memory (~12KB).
+
+```
+PFADD key element [element ...]        # Add elements                     O(1)
+PFCOUNT key [key ...]                  # Estimate unique count            O(1) per key
+PFMERGE destkey sourcekey [sourcekey ...]  # Merge HyperLogLogs            O(N)
+```
+
+## Geospatial
+
+Geospatial commands operate on sorted sets with GEO-specific wrappers.
+
+```
+GEOADD key [NX|XX] longitude latitude member [longitude latitude member ...]  # Add geo entry
+GEOPOS key member [member ...]         # Get coordinates                  O(N)
+GEODIST key member1 member2 [m|km|ft|mi]  # Distance between two members  O(log(N))
+GEOHASH key member [member ...]        # Get geohash strings              O(N)
+GEORADIUS key longitude latitude radius m|km|ft|mi [WITHCOORD] [WITHDIST] [WITHHASH] [COUNT count] [ASC|DESC]  # [Deprecated 6.2]
+GEORADIUSBYMEMBER key member radius m|km|ft|mi [...]  # [Deprecated 6.2]
+GEOSEARCH key [FROMMEMBER member|FROMLONLAT lon lat] [BYRADIUS radius m|km|ft|mi|BYBOX width height m|km|ft|mi] [ASC|DESC] [COUNT count [ANY]] [WITHCOORD] [WITHDIST] [WITHHASH]
+GEOSEARCHSTORE dest key [...]          # Store search results             O(N)
+```
+
+**Note:** `GEORADIUS` and `GEORADIUSBYMEMBER` are deprecated. Use `GEOSEARCH` instead.
+
+## Key Operations
+
+### Debugging
+
+```
+DEBUG OBJECT key                       # Internal debug info (rl:refcount, lru, lru_seconds_idle, etc.)  O(1)
+DEBUG SEGFAULT                        # Crash server (debugging only, never in production)
+```
+
+`DEBUG OBJECT` returns internal metadata such as reference count, LRU idle time, encoding, and serialized length. Useful for diagnosing memory and eviction issues.
+
+```
+EXISTS key [key ...]                   # Check existence (returns count)   O(N) for multi
+TYPE key                               # Data type (string|list|set|zset|hash|stream|none) O(1)
+RENAME key newkey                      # Rename key                       O(1)
+RENAMENX key newkey                    # Rename if target not exists      O(1)
+COPY key newkey [DB db] [REPLACE]      # Copy key                        O(N)
+DEL key [key ...]                      # Delete keys                      O(N)
+UNLINK key [key ...]                   # Async delete (non-blocking)      O(1)
+TOUCH key [key ...]                    # Update last access time          O(N)
+MOVE key db                            # Move key to another database     O(1)
+RANDOMKEY                              # Return a random key              O(1)
+
+# Expiry
+EXPIRE key seconds [NX|XX|GT|LT]      # Set TTL in seconds               O(1)
+PEXPIRE key milliseconds [NX|XX|GT|LT]# Set TTL in ms                    O(1)
+EXPIREAT key timestamp [NX|XX|GT|LT]  # Set expiry at Unix timestamp     O(1)
+PEXPIREAT key ms-timestamp [NX|XX|GT|LT]  # Set expiry at ms-timestamp   O(1)
+TTL key                                # Get TTL in seconds (-1=none, -2=not exists) O(1)
+PTTL key                               # Get TTL in ms                    O(1)
+EXPIRETIME key                         # Expiry as Unix timestamp         O(1)
+PERSIST key                            # Remove expiry                    O(1)
+
+# Object introspection
+DUMP key                               # Serialize value                  O(N)
+RESTORE key ttl serialized-value [REPLACE] [ABSTTL] [IDLETIME sec] [FREQ freq]  # Deserialize
+OBJECT REFCOUNT key                    # Reference count                  O(1)
+OBJECT ENCODING key                    # Internal encoding                O(1)
+OBJECT IDLETIME key                    # Seconds since last access        O(1)
+OBJECT FREQ key                        # Access frequency (LFU)           O(1)
+MEMORY USAGE key [SAMPLES count]       # Memory in bytes                  O(N)
+SORT key [BY pattern] [LIMIT offset count] [GET pattern [GET pattern ...]] [ASC|DESC] [ALPHA] [STORE dest]
+SORT_RO key [BY pattern] [LIMIT offset count] [GET pattern [GET pattern ...]] [ASC|DESC] [ALPHA]  # Read-only sort (Redis 7.0+)
+```
+
+**Expiry options explained:**
+- `NX` — set expiry only if key has no expiry
+- `XX` — set expiry only if key already has an expiry
+- `GT` — set expiry only if new TTL is greater than current
+- `LT` — set expiry only if new TTL is less than current
+
+## Database Operations
+
+```
+DBSIZE                                 # Total keys in database           O(1)
+FLUSHDB [ASYNC|SYNC]                   # Delete all keys in current DB    O(N)
+FLUSHALL [ASYNC|SYNC]                  # Delete all keys in all DBs       O(N)
+SWAPDB index1 index2                   # Swap two databases               O(N)
+SELECT index                           # Switch database                  O(1)
+SCAN cursor [MATCH pattern] [COUNT count] [TYPE type]  # Incremental key iteration O(1)/call
+```
+
+## Transactions
+
+```
+MULTI                                  # Start transaction
+... commands ...
+EXEC                                   # Execute all queued commands
+DISCARD                                # Discard queued commands
+
+WATCH key [key ...]                    # Watch keys for conditional exec
+UNWATCH                                # Unwatch all keys
+```
+
+**Behavioral notes:**
+- Commands between `MULTI` and `EXEC` are queued and executed atomically
+- If `WATCH` detects changes to watched keys, `EXEC` returns nil (transaction aborted)
+- Redis transactions are not rollback-capable — if one command fails, the rest still execute