Dictionary API reference for Momento Cache
This page details the Momento API methods for the dictionary collection data type.

Dictionary methods
DictionaryFetch
Gets a dictionary item from a cache.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | The name of the dictionary item to be retrieved. |
Method response object
The response object for DictionaryFetch returns three possible options, a cache hit, miss, or an error.
- Cache hit
valueDictionaryBytesBytes()
: Map<Bytes, Bytes>valueDictionaryStringString()
: Map<String, String>valueDictionaryStringBytes()
: Map<String, Bytes>valueDictionaryBytesString()
: Map<Bytes, String>toString()
: String - displays the field/value pairs, truncated.
- Cache miss
- Cache error
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetField('test-cache', 'test-dictionary', 'test-field', 'test-value');
const result = await cacheClient.dictionaryFetch('test-cache', 'test-dictionary');
if (result instanceof CacheDictionaryFetch.Hit) {
console.log('Dictionary fetched successfully- ');
result.valueMapStringString().forEach((value, key) => {
console.log(`${key} : ${value}`);
});
} else if (result instanceof CacheDictionaryFetch.Miss) {
console.log("Dictionary 'test-dictionary' was not found in cache 'test-cache'");
} else if (result instanceof CacheDictionaryFetch.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryFetch on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryGetField
Get one field from a dictionary item in the cache.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be retrieved. |
field | String/Bytes | Name of the field in the dictionary item to be retrieved. |
Method response object
Cache hit
fieldString()
: StringfieldBytes()
: BytesvalueString()
: StringvalueBytes()
: BytesThese return the field and its value from the dictionary.
Cache miss
fieldString()
: StringfieldBytes()
: Bytes
Cache error
fieldString()
: StringfieldBytes()
: Bytes
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetField('test-cache', 'test-dictionary', 'test-field', 'test-value');
const result = await cacheClient.dictionaryGetField('test-cache', 'test-dictionary', 'test-field');
if (result instanceof CacheDictionaryGetField.Hit) {
console.log(
`Field ${result.fieldString()} fetched successfully from cache 'test-cache' with value: ${result.valueString()}`
);
} else if (result instanceof CacheDictionaryGetField.Miss) {
console.log("Dictionary 'test-dictionary' was not found in cache 'test-cache'");
} else if (result instanceof CacheDictionaryGetField.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryGetField on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryGetFields
Get one or more fields from a dictionary in the cache.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be retrieved. |
fields | String[]/Bytes[] | Name of the field in the dictionary item to be retrieved. |
Method response object
- Cache hit
- valueDictionaryBytesBytes(): Map<Bytes, Bytes>
- valueDictionaryStringString(): Map<String, String>
- valueDictionaryStringBytes(): Map<String, Bytes>
- valueDictionaryBytesString(): Map<Bytes, String>
- toString(): String - displays truncated valueDictionaryStringString()
- Cache miss
- Error
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetFields(
'test-cache',
'test-dictionary',
new Map<string, string>([
['key1', 'value1'],
['key2', 'value2'],
])
);
const result = await cacheClient.dictionaryGetFields('test-cache', 'test-dictionary', ['key1', 'key2']);
if (result instanceof CacheDictionaryGetFields.Hit) {
console.log('Values fetched successfully- ');
result.valueMapStringString().forEach((value, key) => {
console.log(`${key} : ${value}`);
});
} else if (result instanceof CacheDictionaryGetFields.Miss) {
console.log("Dictionary 'test-dictionary' was not found in cache 'test-cache'");
} else if (result instanceof CacheDictionaryGetFields.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryGetFields on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryIncrement
Adds to the value of a field, if and only if the existing value is a UTF-8 string representing a base 10 integer. If the field is missing from the dictionary, this method sets the field's value to the amount to increment by.
The resulting incremented value must be between -9223372036854775808 and 9223372036854775807, ie. a signed 64-bit integer. If not, there will be an error response.
Examples:
- When the field does not exist,
dictionaryIncrement(cache, dict, field, 10)
will set the field's value to 10. - When the field = 5,
dictionaryIncrement(cache, dict, field, 10)
will set the field's value to 15. - When the field = ‘five’, it will respond with a FailedPreconditionException error.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be retrieved. |
field | String/Bytes | Name of the field in the dictionary item to be retrieved. |
amount | Integer | The quantity to add to the value. May be positive, negative, or zero. Defaults to 1. |
ttl | CollectionTTL object | This will come back as a TTL construct. |
Method response object
- Success
value()
: integer - the new value after incrementingtoString()
: String - displays the value()
- Error
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetField('test-cache', 'test-dictionary', 'test-field', '10');
const result = await cacheClient.dictionaryIncrement('test-cache', 'test-dictionary', 'test-field', 1);
if (result instanceof CacheDictionaryIncrement.Success) {
console.log(`Field value incremented by 1. Result - ${result.valueNumber()}`);
} else if (result instanceof CacheDictionaryIncrement.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryIncrement on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryRemoveField
Removes a field from a dictionary item.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be retrieved. |
field | String/Bytes | Name of the field in the dictionary item to be retrieved. |
Method response object
- Success
- Error
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetField('test-cache', 'test-dictionary', 'test-field', '10');
const result = await cacheClient.dictionaryRemoveField('test-cache', 'test-dictionary', 'test-field');
if (result instanceof CacheDictionaryRemoveField.Success) {
console.log("Field removed successfully from dictionary 'test-dictionary'");
} else if (result instanceof CacheDictionaryRemoveField.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryRemoveField on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryRemoveFields
Removes multiple fields from a dictionary item.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be retrieved. |
fields | String[]/Bytes[] | Name of the field in the dictionary item to be retrieved. |
Method response object
- Success
- Error
See response objects for specific information.
- JavaScript
await cacheClient.dictionarySetFields(
'test-cache',
'test-dictionary',
new Map<string, string>([
['key1', 'value1'],
['key2', 'value2'],
])
);
const result = await cacheClient.dictionaryRemoveFields('test-cache', 'test-dictionary', ['key1', 'key2']);
if (result instanceof CacheDictionaryRemoveFields.Success) {
console.log("Fields removed successfully from dictionary 'test-dictionary'");
} else if (result instanceof CacheDictionaryRemoveFields.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionaryRemoveFields on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionarySetField
Sets a field:value pair in an existing dictionary item. If the dictionary item does not exist, it is created with the new field:value pair.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be set. |
field | String/Bytes | Name of the field in the dictionary item to be set. |
value | String/Bytes | Value for the field to be set. |
ttl | CollectionTTL object | TTL for the dictionary item in cache. This TTL takes precedence over the TTL used when initializing a cache client. |
Method response object
- Success
- Error
See response objects for specific information.
- JavaScript
const result = await cacheClient.dictionarySetField('test-cache', 'test-dictionary', 'test-field', 'test-value');
if (result instanceof CacheDictionarySetField.Success) {
console.log("Field set successfully into cache 'test-cache'");
} else if (result instanceof CacheDictionarySetField.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionarySetField on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionarySetFields
Sets several field:value pairs in a dictionary item. If the dictionary item does not exist, it is created with the new fields.
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be set. |
fields | String[]/Bytes[] | Field:value pair to be added to the dictionary item by the set operation. |
ttl | CollectionTTL object | TTL for the dictionary item in cache. This TTL takes precedence over the TTL used when initializing a cache client. |
Method response object
- Success
- Error
See response objects for specific information.
- JavaScript
const result = await cacheClient.dictionarySetFields(
'test-cache',
'test-dictionary',
new Map<string, string>([
['key1', 'value1'],
['key2', 'value2'],
])
);
if (result instanceof CacheDictionarySetFields.Success) {
console.log("Fields set successfully into cache 'test-cache'");
} else if (result instanceof CacheDictionarySetFields.Error) {
throw new Error(
`An error occurred while attempting to call cacheDictionarySetFields on dictionary 'test-dictionary' in cache 'test-cache': ${result.errorCode()}: ${result.toString()}`
);
}
DictionaryLength
Get the length of an existing dictionary item
Name | Type | Description |
---|---|---|
cacheName | String | Name of the cache. |
dictionaryName | String | Name of the dictionary item to be checked. |
Method response object
- Hit
length()
: Number
- Miss
- Error
See response objects for specific information.