0
# Batch Operations
1

2
High-performance batch operations for working with multiple keys simultaneously, with optimizations for storage adapters that support native batch operations.
3

4
## Capabilities
5

6
### Get Many
7

8
Retrieves multiple values simultaneously with better performance than individual get operations.
9

10
```typescript { .api }
11
/**
12
 * Get multiple values by keys array
13
 * @param keys - Array of keys to retrieve
14
 * @param options - Options including raw data access
15
 * @returns Promise resolving to array of values in same order as keys
16
 */
17
async getMany<Value = GenericValue>(keys: string[], options?: {raw?: false}): Promise<Array<StoredDataNoRaw<Value>>>;
18
async getMany<Value = GenericValue>(keys: string[], options?: {raw?: true}): Promise<Array<StoredDataRaw<Value>>>;
19
```
20

21
**Usage Examples:**
22

23
```typescript
24
const keyv = new Keyv();
25

26
// Setup test data
27
await keyv.set('user:1', { name: 'Alice', age: 30 });
28
await keyv.set('user:2', { name: 'Bob', age: 25 });
29
await keyv.set('user:3', { name: 'Charlie', age: 35 });
30

31
// Get multiple users
32
const users = await keyv.getMany(['user:1', 'user:2', 'user:4']); 
33
// [{ name: 'Alice', age: 30 }, { name: 'Bob', age: 25 }, undefined]
34

35
// Get raw data for multiple keys
36
const rawUsers = await keyv.getMany(['user:1', 'user:2'], { raw: true }); 
37
// [{ value: { name: 'Alice', age: 30 }, expires: undefined }, ...]
38

39
// Type safety with generics
40
interface User { name: string; age: number; }
41
const typedUsers = await keyv.getMany<User>(['user:1', 'user:2']);
42
// Array<User | undefined>
43

44
// Empty array handling
45
const empty = await keyv.getMany([]); // []
46
```
47

48
### Set Many
49

50
Sets multiple key-value pairs simultaneously with optional individual TTL values.
51

52
```typescript { .api }
53
/**
54
 * Set multiple key-value pairs
55
 * @param entries - Array of entries to set
56
 * @returns Promise resolving to array of success booleans
57
 */
58
async setMany<Value = GenericValue>(entries: KeyvEntry[]): Promise<boolean[]>;
59

60
interface KeyvEntry {
61
  /** Key to set */
62
  key: string;
63
  /** Value to set */
64
  value: any;
65
  /** Time to live in milliseconds (optional) */
66
  ttl?: number;
67
}
68
```
69

70
**Usage Examples:**
71

72
```typescript
73
const keyv = new Keyv();
74

75
// Set multiple entries
76
const results = await keyv.setMany([
77
  { key: 'user:1', value: { name: 'Alice', age: 30 } },
78
  { key: 'user:2', value: { name: 'Bob', age: 25 } },
79
  { key: 'user:3', value: { name: 'Charlie', age: 35 } }
80
]);
81
// [true, true, true]
82

83
// Set with individual TTL values
84
await keyv.setMany([
85
  { key: 'session:1', value: 'abc123', ttl: 60000 }, // 1 minute
86
  { key: 'session:2', value: 'def456', ttl: 120000 }, // 2 minutes
87
  { key: 'permanent', value: 'data' } // no TTL, permanent
88
]);
89

90
// Mixed data types
91
await keyv.setMany([
92
  { key: 'string', value: 'hello' },
93
  { key: 'number', value: 42 },
94
  { key: 'object', value: { x: 1, y: 2 } },
95
  { key: 'array', value: [1, 2, 3] },
96
  { key: 'buffer', value: Buffer.from('data') }
97
]);
98

99
// Empty array handling
100
const emptyResults = await keyv.setMany([]); // []
101
```
102

103
### Delete Many
104

105
Deletes multiple keys simultaneously.
106

107
```typescript { .api }
108
/**
109
 * Delete multiple keys
110
 * @param keys - Array of keys to delete
111
 * @returns Promise resolving to true if operation succeeded
112
 */
113
async deleteMany(keys: string[]): Promise<boolean>;
114
```
115

116
**Usage Examples:**
117

118
```typescript
119
const keyv = new Keyv();
120

121
// Setup test data
122
await keyv.set('temp:1', 'data1');
123
await keyv.set('temp:2', 'data2');
124
await keyv.set('temp:3', 'data3');
125

126
// Delete multiple keys
127
const success = await keyv.deleteMany(['temp:1', 'temp:2', 'nonexistent']);
128
// true (returns true if operation completed, regardless of individual key existence)
129

130
// Verify deletion
131
const remaining = await keyv.getMany(['temp:1', 'temp:2', 'temp:3']);
132
// [undefined, undefined, 'data3']
133

134
// Delete all remaining
135
await keyv.deleteMany(['temp:3']); // true
136

137
// Empty array handling
138
const emptyResult = await keyv.deleteMany([]); // true
139
```
140

141
### Has Many
142

143
Checks existence of multiple keys simultaneously.
144

145
```typescript { .api }
146
/**
147
 * Check if multiple keys exist and are not expired
148
 * @param keys - Array of keys to check
149
 * @returns Promise resolving to array of existence booleans
150
 */
151
async hasMany(keys: string[]): Promise<boolean[]>;
152
```
153

154
**Usage Examples:**
155

156
```typescript
157
const keyv = new Keyv();
158

159
// Setup test data
160
await keyv.set('existing:1', 'value1');
161
await keyv.set('existing:2', 'value2');
162
await keyv.set('expiring', 'value', 1000); // expires in 1 second
163

164
// Check multiple keys
165
const exists = await keyv.hasMany(['existing:1', 'existing:2', 'nonexistent']);
166
// [true, true, false]
167

168
// Check with expired keys (after waiting > 1 second)
169
// const existsLater = await keyv.hasMany(['existing:1', 'expiring']);
170
// [true, false] - expired key returns false
171

172
// Empty array handling
173
const emptyExists = await keyv.hasMany([]); // []
174

175
// Type consistency
176
interface User { name: string; }
177
const keyvTyped = new Keyv<User>();
178
await keyvTyped.set('user:1', { name: 'Alice' });
179
const typedExists = await keyvTyped.hasMany(['user:1', 'user:2']);
180
// [true, false]
181
```
182

183
## Performance Notes
184

185
Batch operations provide significant performance benefits:
186

187
- **Native Batch Support**: When storage adapter supports native batch operations (like Redis MGET/MSET), these are used automatically
188
- **Fallback Behavior**: For adapters without native batch support, operations are executed in parallel using Promise.all
189
- **Network Efficiency**: Reduces network round trips for remote storage adapters
190
- **Memory Efficiency**: Processes results in streaming fashion where possible
191

192
**Example with Redis adapter:**
193

194
```typescript
195
import Keyv from "keyv";
196
import KeyvRedis from "@keyv/redis";
197

198
const keyv = new Keyv(new KeyvRedis('redis://localhost:6379'));
199

200
// This uses Redis MGET internally for optimal performance
201
const values = await keyv.getMany(['key1', 'key2', 'key3']);
202

203
// This uses Redis MSET internally
204
await keyv.setMany([
205
  { key: 'key1', value: 'value1' },
206
  { key: 'key2', value: 'value2' },
207
  { key: 'key3', value: 'value3' }
208
]);
209
```