Command: LIST.POP

Overview

The LIST.POP command return (pops) a single element from the beginning (index 0) of a list stored at a specified key. If the list becomes empty after the pop, the key is removed from the store.

Command Name

LIST.POP

Description

Removes the first element from a list stored at the provided key.

  • If the list contains more than one item, only the first is removed.

  • If it contains exactly one item, the entire key is deleted.

  • If the key doesn’t exist, the command returns an empty result.

  • If the key exists but is not a list, an error is returned.

Use Cases

  • Queue-like processing: Use LIST.POP to process tasks from a list where items are inserted using LIST.PUSH .

  • FIFO data consumption: Retrieve data in a First-In-First-Out manner.

  • Cleaning up data: Automatically delete keys when lists become empty.

  • Lightweight job scheduler: Pop jobs/tasks from a list stored under a worker queue.

Syntax 

  LIST.POP <key>
  • <key> : The key associated with the list from which to remove the first item.

Permissions

No special permissions are required to execute this command. However, the caller must have:

  • Access to the given key.

  • Write privileges on the key’s shard.

Examples

Example 1: Pop from a list with multiple values 
  localhost:9219> LIST.PUSH myKey "First"
Ok

localhost:9219> LIST.PUSH myKey "Second" "Third"
Ok
  
  localhost:9219> LIST.POP myKey
Ok "First"
Example 2: Pop from a list with one value (deletes the key) 
  localhost:9219> LIST.PUSH myKey "OnlyOne"
Ok

localhost:9219> LIST.POP myKey
Ok "OnlyOne"
Example 3: Pop from a nonexistent key 
  localhost:9219> LIST.POP unknownKey
Ok

Note: Output is intentionally minimal. Use LIST.GET <key> afterward to verify changes.

After popping, the remaining list: 
  localhost:9219> LIST.GET myKey
Ok [
  "Second",
  "Third"
]
When key does not exist: 
  Ok
When key contains invalid (non-list) data: 
  InvalidValueError: the existing value for the provided key must be a list
When key is not provided: 
  InvalidKeyError: Key must be provided

Behavior on Error

Scenario Error Message
No key provided INVALID_KEY_ERROR: Key must be provided
Invalid key format (non-conforming) INVALID_KEY_ERROR: <validation error>
Value at key is not of list type INVALID_VALUE_ERROR: the existing value for the provided key must be a list
Malformed JSON stored in list INVALID_CHARACTER_ERROR: <JSON unmarshal error>