Skip to main content

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.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringThe name of the dictionary item to be retreived.
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.

DictionaryGetField

Get one field from a dictionary item in the cache.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be retreived.
fieldString/bytesName of the field in the dictionary item to be retreived.
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.

DictionaryGetFields

Get one or more fields from a dictionary in the cache.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be retreived.
fieldsString[]/bytes[]Name of the field in the dictionary item to be retreived.
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.

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.
NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be retreived.
fieldStringbytes
amountIntegerThe quantity to add to the value. May be positive, negative, or zero. Defaults to 1.
ttlCollectionTTL objectThis 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.

DictionaryRemoveField

Removes a field from a dictionary item.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be retreived.
fieldStringbytes
Method response object
  • Success
  • Error

See response objects for specific information.

DictionaryRemoveFields

Removes multiple fields from a dictionary item.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be retreived.
fieldsString[]/bytes[]Name of the field in the dictionary item to be retreived.
Method response object
  • Success
  • Error

See response objects for specific information.

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.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be set.
fieldString/bytesName of the field in the dictionary item to be set.
valueString/bytesValue for the field to be set.
ttlCollectionTTL objectTTL 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.

DictionarySetFields

Sets several field:value pairs in a dictionary item. If the dictionary item does not exist, it is created with the new fields.

NameTypeDescription
cacheNameStringName of the cache.
dictionaryNameStringName of the dictionary item to be set.
fieldsString[]/bytes[]Field:value pair to be added to the dictionary item by the set operation.
ttlCollectionTTL objectTTL 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.