Skip to main content

​
Overview

Returns the specified elements of the list stored at key. The offsets start and end are zero-based indexes. These offsets can also be negative numbers indicating offsets from the end of the list.

​
Method Signature

lrange<TResult = string>(key: string, start: number, end: number): Promise<TResult[]>

​
Parameters

​
key
string
required
The key of the list.
​
start
number
required
The starting index (zero-based). Negative values indicate offsets from the end of the list (e.g., -1 is the last element, -2 is the second-to-last).
​
end
number
required
The ending index (zero-based, inclusive). Negative values indicate offsets from the end of the list. Use -1 to get all elements from start to the end of the list.

​
Return Value

​
elements
TResult[]
An array of elements in the specified range. Returns an empty array if the list does not exist or the range is out of bounds.

​
Examples

​
Basic Usage

import { Redis } from '@upstash/redis';

const redis = new Redis({
  url: process.env.UPSTASH_REDIS_REST_URL,
  token: process.env.UPSTASH_REDIS_REST_TOKEN,
});

// Set up a list
await redis.rpush('mylist', 'one', 'two', 'three', 'four', 'five');

// Get elements from index 1 to 3
const range = await redis.lrange('mylist', 1, 3);
console.log(range); // ['two', 'three', 'four']

// Get all elements
const all = await redis.lrange('mylist', 0, -1);
console.log(all); // ['one', 'two', 'three', 'four', 'five']

​
Using Negative Indexes

await redis.rpush('items', 'A', 'B', 'C', 'D', 'E');

// Get the last 3 elements
const lastThree = await redis.lrange('items', -3, -1);
console.log(lastThree); // ['C', 'D', 'E']

// Get all except the first element
const withoutFirst = await redis.lrange('items', 1, -1);
console.log(withoutFirst); // ['B', 'C', 'D', 'E']

// Get all except the last element
const withoutLast = await redis.lrange('items', 0, -2);
console.log(withoutLast); // ['A', 'B', 'C', 'D']

​
Working with Objects

interface Product {
  id: string;
  name: string;
  price: number;
}

// Add products
await redis.rpush<Product>('products', 
  { id: '1', name: 'Laptop', price: 999 },
  { id: '2', name: 'Mouse', price: 25 },
  { id: '3', name: 'Keyboard', price: 75 }
);

// Get first two products
const products = await redis.lrange<Product>('products', 0, 1);
console.log(products[0].name); // 'Laptop'
console.log(products[1].name); // 'Mouse'

​
Pagination

const pageSize = 10;
const pageNumber = 2; // 0-based

const start = pageNumber * pageSize;
const end = start + pageSize - 1;

const page = await redis.lrange('items', start, end);
console.log(`Page ${pageNumber + 1}:`, page);

​
Getting Recent Items

// Get the 5 most recent items (assuming newer items are pushed with RPUSH)
const recentCount = 5;
const recentItems = await redis.lrange('recent:activity', -recentCount, -1);
console.log('Recent items:', recentItems);

​
Viewing Queue Contents

// View the next 10 items in a queue without removing them
const nextJobs = await redis.lrange('queue:jobs', 0, 9);
console.log('Next jobs to process:', nextJobs);

// Check if queue has items
const hasItems = nextJobs.length > 0;

​
See Also

  • LLEN - Get the length of a list
  • LINDEX - Get an element by index
  • LPUSH - Insert elements at the head of a list
  • RPUSH - Insert elements at the tail of a list