Dictionary API reference for Momento Cache

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

a technical illustration of stacks of books. some dusty, so not. All collected into groups.

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(): String
- fieldBytes(): Bytes
- valueString(): String
- valueBytes(): Bytes
  These return the field and its value from the dictionary.
Cache miss
- fieldString(): String
- fieldBytes(): Bytes
Cache error
- fieldString(): String
- fieldBytes(): 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.

note

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 incrementing
- toString(): 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.

Dictionary API reference for Momento Cache

Dictionary methods​

DictionaryFetch​

DictionaryGetField​

DictionaryGetFields​

DictionaryIncrement​

DictionaryRemoveField​

DictionaryRemoveFields​

DictionarySetField​

DictionarySetFields​

DictionaryLength​

Dictionary methods

DictionaryFetch

DictionaryGetField

DictionaryGetFields

DictionaryIncrement

DictionaryRemoveField

DictionaryRemoveFields

DictionarySetField

DictionarySetFields

DictionaryLength