Upstash Documentation

Array commands

Commands for storing values in a sparse, index-addressed array.
2 min read

An array stores string values under unsigned integer indexes, from 0 up to 18446744073709551614. It is sparse: an index either holds a value or is empty, and writing to a distant index does not allocate the slots in between. Nothing shifts when a value is deleted, so an index keeps its meaning for the lifetime of the key. That makes an array the right shape for data that already has a natural numeric key, such as a sequence number or a bucketed timestamp, where a list would force a scan and a hash would store the index as a string.

Two numbers describe an array and they are not the same. ARCOUNT is how many slots hold a value; ARLEN is the highest occupied index plus one. They agree only when the array is densely filled from 0.

Each array also keeps an append cursor, holding the index the last append wrote to. ARINSERT appends after it, ARRING appends after it and wraps within a fixed number of slots, ARNEXT reads where the next append will land, and ARSEEK moves it. The cursor tracks appends only: positional writes with ARSET and deletions never move it, so a freed index is never silently reused.