Dictionary API reference for Momento Cache

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

info

Momento collection types use a CollectionTTL to specify their TTL behavior. This is an optional argument for all "write" operations.

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
Rust

await cacheClient.dictionarySetField(cacheName, 'test-dictionary', 'test-field', 'test-value');
const result = await cacheClient.dictionaryFetch(cacheName, 'test-dictionary');

// simplified style; assume the value was found
console.log(`Dictionary fetched: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheDictionaryFetchResponse.Hit:
    console.log('Dictionary fetched successfully- ');
    result.valueMap().forEach((value, key) => {
      console.log(`${key} : ${value}`);
    });
    break;
  case CacheDictionaryFetchResponse.Miss:
    console.log(`Dictionary 'test-dictionary' was not found in cache '${cacheName}'`);
    break;
  case CacheDictionaryFetchResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryFetch on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  let response = cache_client
      .dictionary_fetch(cache_name, "dictionary_name")
      .await?;

  match response {
      DictionaryFetchResponse::Hit { value } => {
          let dictionary: HashMap<String, String> =
              value.try_into().expect("I stored a dictionary!");
          println!("Fetched dictionary: {:?}", dictionary);
      }
      DictionaryFetchResponse::Miss => println!("Cache miss"),
  }

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
Rust

await cacheClient.dictionarySetField(cacheName, 'test-dictionary', 'test-field', 'test-value');
const result = await cacheClient.dictionaryGetField(cacheName, 'test-dictionary', 'test-field');

// simplified style; assume the value was found
console.log(`Field 'test-field' fetched from dictionary: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheDictionaryGetFieldResponse.Hit:
    console.log(
      `Field ${result.fieldString()} fetched successfully from cache '${cacheName}' with value: ${result.value()}`
    );
    break;
  case CacheDictionaryGetFieldResponse.Miss:
    console.log(`Dictionary 'test-dictionary' was not found in cache '${cacheName}'`);
    break;
  case CacheDictionaryGetFieldResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryGetField on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  let response = cache_client
      .dictionary_get_field(cache_name, "dictionary_name", "field")
      .await?;

  match response {
      DictionaryGetFieldResponse::Hit { value } => {
          let value: String = value.try_into().expect("I stored a string!");
          println!("Fetched value: {}", value);
      }
      DictionaryGetFieldResponse::Miss => println!("Cache miss"),
  }

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
Rust

await cacheClient.dictionarySetFields(
  cacheName,
  'test-dictionary',
  new Map<string, string>([
    ['key1', 'value1'],
    ['key2', 'value2'],
  ])
);
const result = await cacheClient.dictionaryGetFields(cacheName, 'test-dictionary', ['key1', 'key2']);

// simplified style; assume the value was found
console.log(`Got fields from dictionary: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheDictionaryGetFieldsResponse.Hit:
    console.log('Values fetched successfully- ');
    result.valueMap().forEach((value, key) => {
      console.log(`${key} : ${value}`);
    });
    break;
  case CacheDictionaryGetFieldsResponse.Miss:
    console.log(`Dictionary 'test-dictionary' was not found in cache '${cacheName}'`);
    break;
  case CacheDictionaryGetFieldsResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryGetFields on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  let response = cache_client
      .dictionary_get_fields(cache_name, "dictionary_name", vec!["field1", "field2"])
      .await?;

  match response {
      DictionaryGetFieldsResponse::Hit { .. } => {
          let dictionary: HashMap<String, String> = response
              .try_into()
              .expect("I stored a dictionary of strings!");
          println!("Fetched dictionary: {:?}", dictionary);
      }
      DictionaryGetFieldsResponse::Miss => println!("Cache miss"),
  }

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
Rust

await cacheClient.dictionarySetField(cacheName, 'test-dictionary', 'test-field', '10');
const result = await cacheClient.dictionaryIncrement(cacheName, 'test-dictionary', 'test-field', 1);
switch (result.type) {
  case CacheDictionaryIncrementResponse.Success:
    console.log(`Field value incremented by 1. Result - ${result.valueNumber()}`);
    break;
  case CacheDictionaryIncrementResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryIncrement on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  let response = cache_client
      .dictionary_increment(cache_name, "dictionary_name", "field", 1)
      .await?;
  println!("Incremented field in dictionary to {}", response.value);

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
Rust

await cacheClient.dictionarySetField(cacheName, 'test-dictionary', 'test-field', '10');
const result = await cacheClient.dictionaryRemoveField(cacheName, 'test-dictionary', 'test-field');
switch (result.type) {
  case CacheDictionaryRemoveFieldResponse.Success:
    console.log("Field removed successfully from dictionary 'test-dictionary'");
    break;
  case CacheDictionaryRemoveFieldResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryRemoveField on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  cache_client
      .dictionary_remove_field(cache_name, "dictionary_name", "field")
      .await?;
  println!("Field removed from dictionary");

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
Rust

await cacheClient.dictionarySetFields(
  cacheName,
  'test-dictionary',
  new Map<string, string>([
    ['key1', 'value1'],
    ['key2', 'value2'],
  ])
);
const result = await cacheClient.dictionaryRemoveFields(cacheName, 'test-dictionary', ['key1', 'key2']);
switch (result.type) {
  case CacheDictionaryRemoveFieldsResponse.Success:
    console.log("Fields removed successfully from dictionary 'test-dictionary'");
    break;
  case CacheDictionaryRemoveFieldsResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionaryRemoveFields on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  cache_client
      .dictionary_remove_fields(cache_name, "dictionary_name", vec!["field1", "field2"])
      .await?;
  println!("Fields removed from dictionary");

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
Rust

const result = await cacheClient.dictionarySetField(cacheName, 'test-dictionary', 'test-field', 'test-value');
switch (result.type) {
  case CacheDictionarySetFieldResponse.Success:
    console.log(`Field set successfully into cache '${cacheName}'`);
    break;
  case CacheDictionarySetFieldResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionarySetField on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  cache_client
      .dictionary_set_field(cache_name.to_string(), "dictionary_name", "field", "value")
      .await?;
  println!("Set field in dictionary");

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
Rust

const result = await cacheClient.dictionarySetFields(
  cacheName,
  'test-dictionary',
  new Map<string, string>([
    ['key1', 'value1'],
    ['key2', 'value2'],
  ])
);
switch (result.type) {
  case CacheDictionarySetFieldsResponse.Success:
    console.log(`Fields set successfully into cache '${cacheName}'`);
    break;
  case CacheDictionarySetFieldsResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheDictionarySetFields on dictionary 'test-dictionary' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

  cache_client
      .dictionary_set_fields(
          cache_name.to_string(),
          "dictionary_name",
          vec![("field1", "value1"), ("field2", "value2")],
      )
      .await?;
  println!("Set fields in dictionary");

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.

Rust

  let _length: u32 = cache_client
      .dictionary_length(cache_name, "dictionary_name")
      .await?
      .try_into()
      .expect("Expected a dictionary length!");

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