0
# Data Storage and Retrieval
1

2
MMKV provides high-performance key-value storage supporting Java primitives, strings, byte arrays, Parcelable objects, and string sets. All data is immediately persisted to disk using memory-mapped files, with optional key expiration support.
3

4
## Capabilities
5

6
### Boolean Values
7

8
Store and retrieve boolean values with optional default values and expiration.
9

10
```java { .api }
11
/**
12
 * Store a boolean value
13
 * @param key The key to store the value under
14
 * @param value The boolean value to store
15
 * @return true if successful, false otherwise
16
 */
17
boolean encode(String key, boolean value);
18

19
/**
20
 * Store a boolean value with expiration
21
 * @param key The key to store the value under
22
 * @param value The boolean value to store
23
 * @param expireDurationInSecond Override the default duration, 0 means never expire
24
 * @return true if successful, false otherwise
25
 */
26
boolean encode(String key, boolean value, int expireDurationInSecond);
27

28
/**
29
 * Retrieve a boolean value
30
 * @param key The key to retrieve
31
 * @return The stored boolean value, or false if key doesn't exist
32
 */
33
boolean decodeBool(String key);
34

35
/**
36
 * Retrieve a boolean value with default
37
 * @param key The key to retrieve
38
 * @param defaultValue The default value to return if key doesn't exist
39
 * @return The stored boolean value, or defaultValue if key doesn't exist
40
 */
41
boolean decodeBool(String key, boolean defaultValue);
42
```
43

44
**Usage Examples:**
45

46
```java
47
MMKV kv = MMKV.defaultMMKV();
48

49
// Store boolean values
50
kv.encode("user_logged_in", true);
51
kv.encode("notifications_enabled", false);
52

53
// Store with expiration (expires in 1 hour)
54
kv.encode("temp_flag", true, MMKV.ExpireInHour);
55

56
// Retrieve boolean values
57
boolean isLoggedIn = kv.decodeBool("user_logged_in");
58
boolean notificationsOn = kv.decodeBool("notifications_enabled", false);
59
```
60

61
### Integer Values
62

63
Store and retrieve 32-bit integer values with optional expiration.
64

65
```java { .api }
66
/**
67
 * Store an integer value
68
 * @param key The key to store the value under
69
 * @param value The integer value to store
70
 * @return true if successful, false otherwise
71
 */
72
boolean encode(String key, int value);
73

74
/**
75
 * Store an integer value with expiration
76
 * @param key The key to store the value under
77
 * @param value The integer value to store
78
 * @param expireDurationInSecond Override the default duration, 0 means never expire
79
 * @return true if successful, false otherwise
80
 */
81
boolean encode(String key, int value, int expireDurationInSecond);
82

83
/**
84
 * Retrieve an integer value
85
 * @param key The key to retrieve
86
 * @return The stored integer value, or 0 if key doesn't exist
87
 */
88
int decodeInt(String key);
89

90
/**
91
 * Retrieve an integer value with default
92
 * @param key The key to retrieve
93
 * @param defaultValue The default value to return if key doesn't exist
94
 * @return The stored integer value, or defaultValue if key doesn't exist
95
 */
96
int decodeInt(String key, int defaultValue);
97
```
98

99
**Usage Examples:**
100

101
```java
102
// Store integer values
103
kv.encode("user_id", 12345);
104
kv.encode("login_attempts", 3);
105

106
// Store with expiration (expires in 1 day)
107
kv.encode("daily_score", 1500, MMKV.ExpireInDay);
108

109
// Retrieve integer values
110
int userId = kv.decodeInt("user_id");
111
int attempts = kv.decodeInt("login_attempts", 0);
112
```
113

114
### Long Values
115

116
Store and retrieve 64-bit long values with optional expiration.
117

118
```java { .api }
119
/**
120
 * Store a long value
121
 * @param key The key to store the value under
122
 * @param value The long value to store
123
 * @return true if successful, false otherwise
124
 */
125
boolean encode(String key, long value);
126

127
/**
128
 * Store a long value with expiration
129
 * @param key The key to store the value under
130
 * @param value The long value to store
131
 * @param expireDurationInSecond Override the default duration, 0 means never expire
132
 * @return true if successful, false otherwise
133
 */
134
boolean encode(String key, long value, int expireDurationInSecond);
135

136
/**
137
 * Retrieve a long value
138
 * @param key The key to retrieve
139
 * @return The stored long value, or 0 if key doesn't exist
140
 */
141
long decodeLong(String key);
142

143
/**
144
 * Retrieve a long value with default
145
 * @param key The key to retrieve
146
 * @param defaultValue The default value to return if key doesn't exist
147
 * @return The stored long value, or defaultValue if key doesn't exist
148
 */
149
long decodeLong(String key, long defaultValue);
150
```
151

152
**Usage Examples:**
153

154
```java
155
// Store long values
156
kv.encode("timestamp", System.currentTimeMillis());
157
kv.encode("file_size", 1024L * 1024L * 100L); // 100MB
158

159
// Store with expiration (expires in 1 minute)
160
kv.encode("session_start", System.currentTimeMillis(), MMKV.ExpireInMinute);
161

162
// Retrieve long values
163
long timestamp = kv.decodeLong("timestamp");
164
long fileSize = kv.decodeLong("file_size", 0L);
165
```
166

167
### Float Values
168

169
Store and retrieve 32-bit float values with optional expiration.
170

171
```java { .api }
172
/**
173
 * Store a float value
174
 * @param key The key to store the value under
175
 * @param value The float value to store
176
 * @return true if successful, false otherwise
177
 */
178
boolean encode(String key, float value);
179

180
/**
181
 * Store a float value with expiration
182
 * @param key The key to store the value under
183
 * @param value The float value to store
184
 * @param expireDurationInSecond Override the default duration, 0 means never expire
185
 * @return true if successful, false otherwise
186
 */
187
boolean encode(String key, float value, int expireDurationInSecond);
188

189
/**
190
 * Retrieve a float value
191
 * @param key The key to retrieve
192
 * @return The stored float value, or 0.0f if key doesn't exist
193
 */
194
float decodeFloat(String key);
195

196
/**
197
 * Retrieve a float value with default
198
 * @param key The key to retrieve
199
 * @param defaultValue The default value to return if key doesn't exist
200
 * @return The stored float value, or defaultValue if key doesn't exist
201
 */
202
float decodeFloat(String key, float defaultValue);
203
```
204

205
**Usage Examples:**
206

207
```java
208
// Store float values
209
kv.encode("user_rating", 4.5f);
210
kv.encode("completion_percentage", 0.75f);
211

212
// Retrieve float values
213
float rating = kv.decodeFloat("user_rating");
214
float completion = kv.decodeFloat("completion_percentage", 0.0f);
215
```
216

217
### Double Values
218

219
Store and retrieve 64-bit double values with optional expiration.
220

221
```java { .api }
222
/**
223
 * Store a double value
224
 * @param key The key to store the value under
225
 * @param value The double value to store
226
 * @return true if successful, false otherwise
227
 */
228
boolean encode(String key, double value);
229

230
/**
231
 * Store a double value with expiration
232
 * @param key The key to store the value under
233
 * @param value The double value to store
234
 * @param expireDurationInSecond Override the default duration, 0 means never expire
235
 * @return true if successful, false otherwise
236
 */
237
boolean encode(String key, double value, int expireDurationInSecond);
238

239
/**
240
 * Retrieve a double value
241
 * @param key The key to retrieve
242
 * @return The stored double value, or 0.0 if key doesn't exist
243
 */
244
double decodeDouble(String key);
245

246
/**
247
 * Retrieve a double value with default
248
 * @param key The key to retrieve
249
 * @param defaultValue The default value to return if key doesn't exist
250
 * @return The stored double value, or defaultValue if key doesn't exist
251
 */
252
double decodeDouble(String key, double defaultValue);
253
```
254

255
**Usage Examples:**
256

257
```java
258
// Store double values for high precision
259
kv.encode("latitude", 37.7749295);
260
kv.encode("longitude", -122.4194155);
261

262
// Retrieve double values
263
double lat = kv.decodeDouble("latitude");
264
double lng = kv.decodeDouble("longitude", 0.0);
265
```
266

267
### String Values
268

269
Store and retrieve string values with optional expiration and null safety.
270

271
```java { .api }
272
/**
273
 * Store a string value
274
 * @param key The key to store the value under
275
 * @param value The string value to store (can be null)
276
 * @return true if successful, false otherwise
277
 */
278
boolean encode(String key, String value);
279

280
/**
281
 * Store a string value with expiration
282
 * @param key The key to store the value under
283
 * @param value The string value to store (can be null)
284
 * @param expireDurationInSecond Override the default duration, 0 means never expire
285
 * @return true if successful, false otherwise
286
 */
287
boolean encode(String key, String value, int expireDurationInSecond);
288

289
/**
290
 * Retrieve a string value
291
 * @param key The key to retrieve
292
 * @return The stored string value, or null if key doesn't exist
293
 */
294
String decodeString(String key);
295

296
/**
297
 * Retrieve a string value with default
298
 * @param key The key to retrieve
299
 * @param defaultValue The default value to return if key doesn't exist (can be null)
300
 * @return The stored string value, or defaultValue if key doesn't exist
301
 */
302
String decodeString(String key, String defaultValue);
303
```
304

305
**Usage Examples:**
306

307
```java
308
// Store string values
309
kv.encode("username", "john_doe");
310
kv.encode("user_email", "john@example.com");
311
kv.encode("optional_field", null); // Store null values
312

313
// Store with expiration (expires in 1 hour)
314
kv.encode("session_token", "abc123xyz", MMKV.ExpireInHour);
315

316
// Retrieve string values
317
String username = kv.decodeString("username");
318
String email = kv.decodeString("user_email", "unknown@example.com");
319
String token = kv.decodeString("session_token"); // May return null if expired
320
```
321

322
### String Sets
323

324
Store and retrieve sets of strings with optional expiration.
325

326
```java { .api }
327
/**
328
 * Store a string set
329
 * @param key The key to store the value under
330
 * @param value The string set to store (can be null)
331
 * @return true if successful, false otherwise
332
 */
333
boolean encode(String key, Set<String> value);
334

335
/**
336
 * Store a string set with expiration
337
 * @param key The key to store the value under
338
 * @param value The string set to store (can be null)
339
 * @param expireDurationInSecond Override the default duration, 0 means never expire
340
 * @return true if successful, false otherwise
341
 */
342
boolean encode(String key, Set<String> value, int expireDurationInSecond);
343

344
/**
345
 * Retrieve a string set
346
 * @param key The key to retrieve
347
 * @return The stored string set, or null if key doesn't exist
348
 */
349
Set<String> decodeStringSet(String key);
350

351
/**
352
 * Retrieve a string set with default
353
 * @param key The key to retrieve
354
 * @param defaultValue The default value to return if key doesn't exist (can be null)
355
 * @return The stored string set, or defaultValue if key doesn't exist
356
 */
357
Set<String> decodeStringSet(String key, Set<String> defaultValue);
358

359
/**
360
 * Retrieve a string set with custom Set implementation
361
 * @param key The key to retrieve
362
 * @param defaultValue The default value to return if key doesn't exist (can be null)
363
 * @param cls The Set class to instantiate for the result
364
 * @return The stored string set, or defaultValue if key doesn't exist
365
 */
366
Set<String> decodeStringSet(String key, Set<String> defaultValue, Class<? extends Set> cls);
367
```
368

369
**Usage Examples:**
370

371
```java
372
// Store string sets
373
Set<String> tags = new HashSet<>();
374
tags.add("java");
375
tags.add("android");
376
tags.add("mobile");
377
kv.encode("user_tags", tags);
378

379
// Store with expiration
380
Set<String> tempCategories = new HashSet<>();
381
tempCategories.add("temp1");
382
tempCategories.add("temp2");
383
kv.encode("temp_categories", tempCategories, MMKV.ExpireInHour);
384

385
// Retrieve string sets
386
Set<String> userTags = kv.decodeStringSet("user_tags");
387
Set<String> emptyTags = kv.decodeStringSet("non_existent", new HashSet<>());
388

389
// Use specific Set implementation
390
LinkedHashSet<String> orderedTags = (LinkedHashSet<String>) kv.decodeStringSet(
391
    "user_tags", 
392
    new LinkedHashSet<>(), 
393
    LinkedHashSet.class
394
);
395
```
396

397
### Byte Arrays
398

399
Store and retrieve raw byte arrays with optional expiration.
400

401
```java { .api }
402
/**
403
 * Store a byte array
404
 * @param key The key to store the value under
405
 * @param value The byte array to store (can be null)
406
 * @return true if successful, false otherwise
407
 */
408
boolean encode(String key, byte[] value);
409

410
/**
411
 * Store a byte array with expiration
412
 * @param key The key to store the value under
413
 * @param value The byte array to store (can be null)
414
 * @param expireDurationInSecond Override the default duration, 0 means never expire
415
 * @return true if successful, false otherwise
416
 */
417
boolean encode(String key, byte[] value, int expireDurationInSecond);
418

419
/**
420
 * Retrieve a byte array
421
 * @param key The key to retrieve
422
 * @return The stored byte array, or null if key doesn't exist
423
 */
424
byte[] decodeBytes(String key);
425

426
/**
427
 * Retrieve a byte array with default
428
 * @param key The key to retrieve
429
 * @param defaultValue The default value to return if key doesn't exist (can be null)
430
 * @return The stored byte array, or defaultValue if key doesn't exist
431
 */
432
byte[] decodeBytes(String key, byte[] defaultValue);
433
```
434

435
**Usage Examples:**
436

437
```java
438
// Store binary data
439
byte[] imageData = loadImageAsBytes();
440
kv.encode("profile_image", imageData);
441

442
// Store with expiration (expires in 1 day)
443
byte[] tempData = generateTempData();
444
kv.encode("temp_binary", tempData, MMKV.ExpireInDay);
445

446
// Retrieve binary data
447
byte[] storedImage = kv.decodeBytes("profile_image");
448
byte[] defaultImage = kv.decodeBytes("profile_image", getDefaultImageBytes());
449
```
450

451
### Parcelable Objects
452

453
Store and retrieve Android Parcelable objects with automatic serialization.
454

455
```java { .api }
456
/**
457
 * Store a Parcelable object
458
 * @param key The key to store the value under
459
 * @param value The Parcelable object to store (can be null)
460
 * @return true if successful, false otherwise
461
 */
462
boolean encode(String key, Parcelable value);
463

464
/**
465
 * Store a Parcelable object with expiration
466
 * @param key The key to store the value under
467
 * @param value The Parcelable object to store (can be null)
468
 * @param expireDurationInSecond Override the default duration, 0 means never expire
469
 * @return true if successful, false otherwise
470
 */
471
boolean encode(String key, Parcelable value, int expireDurationInSecond);
472

473
/**
474
 * Retrieve a Parcelable object
475
 * @param key The key to retrieve
476
 * @param tClass The class of the Parcelable object
477
 * @return The stored Parcelable object, or null if key doesn't exist
478
 */
479
<T extends Parcelable> T decodeParcelable(String key, Class<T> tClass);
480

481
/**
482
 * Retrieve a Parcelable object with default
483
 * @param key The key to retrieve
484
 * @param tClass The class of the Parcelable object
485
 * @param defaultValue The default value to return if key doesn't exist (can be null)
486
 * @return The stored Parcelable object, or defaultValue if key doesn't exist
487
 */
488
<T extends Parcelable> T decodeParcelable(String key, Class<T> tClass, T defaultValue);
489
```
490

491
**Usage Examples:**
492

493
```java
494
// Custom Parcelable class
495
public class UserProfile implements Parcelable {
496
    public String name;
497
    public int age;
498
    public String email;
499
    
500
    // Parcelable implementation...
501
}
502

503
// Store Parcelable objects
504
UserProfile profile = new UserProfile("John", 25, "john@example.com");
505
kv.encode("user_profile", profile);
506

507
// Store with expiration
508
UserProfile tempProfile = createTempProfile();
509
kv.encode("temp_profile", tempProfile, MMKV.ExpireInHour);
510

511
// Retrieve Parcelable objects
512
UserProfile storedProfile = kv.decodeParcelable("user_profile", UserProfile.class);
513
UserProfile defaultProfile = kv.decodeParcelable(
514
    "user_profile", 
515
    UserProfile.class, 
516
    new UserProfile("Unknown", 0, "")
517
);
518
```
519

520
### Key Management
521

522
Check for key existence and get information about stored values.
523

524
```java { .api }
525
/**
526
 * Check whether or not MMKV contains the key
527
 * @param key The key to check
528
 * @return true if the key exists, false otherwise
529
 */
530
boolean containsKey(String key);
531

532
/**
533
 * Get all keys
534
 * @return Array of all keys, or null if empty
535
 */
536
String[] allKeys();
537

538
/**
539
 * Get all non-expired keys. Note that this call has costs.
540
 * @return Array of non-expired keys, or null if empty
541
 */
542
String[] allNonExpireKeys();
543

544
/**
545
 * Get the total count of all keys
546
 * @return The total count of keys
547
 */
548
long count();
549

550
/**
551
 * Get the total count of all non-expired keys. Note that this call has costs.
552
 * @return The total count of non-expired keys
553
 */
554
long countNonExpiredKeys();
555
```
556

557
**Usage Examples:**
558

559
```java
560
// Check if key exists before retrieving
561
if (kv.containsKey("user_profile")) {
562
    UserProfile profile = kv.decodeParcelable("user_profile", UserProfile.class);
563
    // Use profile...
564
}
565

566
// Get all keys for debugging or migration
567
String[] allKeys = kv.allKeys();
568
for (String key : allKeys) {
569
    Log.d("MMKV", "Key: " + key);
570
}
571

572
// Get count of stored items
573
long totalItems = kv.count();
574
long activeItems = kv.countNonExpiredKeys();
575
Log.d("MMKV", "Total: " + totalItems + ", Active: " + activeItems);
576
```
577

578
### Value Size Information
579

580
Get information about the storage size of values.
581

582
```java { .api }
583
/**
584
 * Get the actual size consumption of the key's value.
585
 * Note: might be a little bigger than value's length.
586
 * @param key The key of the value
587
 * @return The storage size in bytes
588
 */
589
int getValueSize(String key);
590

591
/**
592
 * Get the actual size of the key's value. String's length or byte[]'s length, etc.
593
 * @param key The key of the value
594
 * @return The actual value size
595
 */
596
int getValueActualSize(String key);
597
```
598

599
**Usage Examples:**
600

601
```java
602
// Check storage overhead
603
int storageSize = kv.getValueSize("large_data");
604
int actualSize = kv.getValueActualSize("large_data");
605
Log.d("MMKV", "Storage: " + storageSize + ", Actual: " + actualSize);
606
```
607

608
### Value Removal
609

610
Remove individual keys or multiple keys at once.
611

612
```java { .api }
613
/**
614
 * Remove a single key-value pair
615
 * @param key The key to remove
616
 */
617
void removeValueForKey(String key);
618

619
/**
620
 * Batch remove multiple keys from the MMKV instance
621
 * @param arrKeys The keys to be removed
622
 */
623
void removeValuesForKeys(String[] arrKeys);
624
```
625

626
**Usage Examples:**
627

628
```java
629
// Remove single key
630
kv.removeValueForKey("temp_data");
631

632
// Remove multiple keys
633
String[] keysToRemove = {"temp1", "temp2", "temp3"};
634
kv.removeValuesForKeys(keysToRemove);
635
```