Set API reference for Momento Cache

A set is a collection of elements, but each element can appear only once and order is not guaranteed.

info

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

Example: if your set contains [1, 2, 3] and you add 2, the set remains [1, 2, 3].

See Sets for more information on their usage.

Set methods

SetAddElement

Adds an element to a set. If the set item does not already exist, this method will create one.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item to be altered.
element	String | Bytes	Element to be added by this operation.
ttl	CollectionTTL object	TTL for the set item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client.

Method response object

• Success
• Error

See response objects for specific information.

JavaScript

const result = await cacheClient.setAddElement(cacheName, 'test-set', 'test-element');
switch (result.type) {
  case CacheSetAddElementResponse.Success:
    console.log("Element added successfully to set 'test-set'");
    break;
  case CacheSetAddElementResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheSetAddElement on set 'test-set' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

SetAddElements

Adds multiple elements to a set item. If the set item does not already exist, this method will create one.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item to be altered.
elements	String[] | Bytes[]	Elements to be added by this operation.
ttl	CollectionTTL object	TTL for the set item in cache. This TTL takes precedence over the TTL used when initializing a cache connection client.

Method response object

• Success
• Error

See response objects for specific information.

JavaScript

const result = await cacheClient.setAddElements(cacheName, 'test-set', ['test-element1', 'test-element2']);
switch (result.type) {
  case CacheSetAddElementsResponse.Success:
    console.log("Elements added successfully to set 'test-set'");
    break;
  case CacheSetAddElementsResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheSetAddElements on set 'test-set' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

Rust

  cache_client
      .set_add_elements(cache_name, "set_name", vec!["value1", "value2"])
      .await?;
  println!("Elements added to set");

info

Full example code and imports can be found here

SetFetch

Gets a set item from a cache.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	The name of the set item to be retrieved.

Method response object

The response object for SetFetch returns three possible options, a cache hit, miss, or an error.

• Hit
  • valueSetBytes(): Bytes[]
  • valueSetString(): String[]
  • toString(): String
• Miss
• Error

See response objects for specific information.

JavaScript

await cacheClient.setAddElements(cacheName, 'test-set', ['test-element1', 'test-element2']);
const result = await cacheClient.setFetch(cacheName, 'test-set');

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

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

info

Full example code and imports can be found here

Rust

  let _fetched_elements: Vec<String> = cache_client
      .set_fetch(cache_name, "set_name")
      .await?
      .try_into()
      .expect("Expected a set!");

info

Full example code and imports can be found here

SetSample

Gets a random sampling of elements from a set item in a cache.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	The name of the set item to sample.
limit	Number	The maximum number of elements to be retrieved.

Method response object

The response object for SetSample returns three possible options, a cache hit, miss, or an error.

• Hit
  • valueSetBytes(): Bytes[]
  • valueSetString(): String[]
  • toString(): String
• Miss
• Error

See response objects for specific information.

JavaScript

await cacheClient.setAddElements(cacheName, 'test-set', ['test-element1', 'test-element2', 'test-element3']);
const result = await cacheClient.setSample(cacheName, 'test-set', 2);

// simplified style; assume the value was found
console.log(`Sampled 2 elements from set: ${result.value()!}`);

// pattern-matching style; safer for production code
switch (result.type) {
  case CacheSetSampleResponse.Hit:
    console.log('Sample of 2 elements from set: ');
    result.valueSet().forEach((value, key) => {
      console.log(`${key} : ${value}`);
    });
    break;
  case CacheSetSampleResponse.Miss:
    console.log(`Set 'test-set' was not found in cache '${cacheName}'`);
    break;
  case CacheSetSampleResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheSetSample on set 'test-set' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

C#

var setAddResult = await cacheClient.SetAddElementsAsync("test-cache", "test-set", new string[] { "foo", "bar", "baz" });
if (setAddResult is CacheSetAddElementsResponse.Success)
{
    Console.WriteLine("Added elements to 'test-set' successfully");
}
else if (setAddResult is CacheSetAddElementsResponse.Error error)
{
    throw new Exception($"An error occurred while attempting to delete key 'test-key' from cache 'test-cache': {error.ErrorCode}: {error}");
}

var setSampleResult = await cacheClient.SetSampleAsync("test-cache", "test-set", 2);
if (setSampleResult is CacheSetSampleResponse.Hit setSampleHit)
{
    Console.WriteLine($"Sampled random elements from 'test-set': {String.Join(", ", setSampleHit.ValueSetString)}");
}
else if (setSampleResult is CacheSetSampleResponse.Error error)
{
    throw new Exception($"An error occurred while attempting to sample from 'test-set' from cache 'test-cache': {error.ErrorCode}: {error}");
}

info

Full example code and imports can be found here

SetRemoveElement

Removes a single element from an existing set item. If the set is emptied as a result, the item is deleted.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item to be altered.
element	String | Bytes	Element to be removed by this operation.

Method response object

• Success
• Error

See response objects for specific information.

JavaScript

await cacheClient.setAddElement(cacheName, 'test-set', 'test-element');
const result = await cacheClient.setRemoveElement(cacheName, 'test-set', 'test-element');
switch (result.type) {
  case CacheSetRemoveElementResponse.Success:
    console.log("Element 'test-element' removed successfully from set 'test-set'");
    break;
  case CacheSetRemoveElementResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheSetRemoveElement on set 'test-set' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

SetRemoveElements

Removes multiple elements from an existing set item. If the set is emptied as a result, the item is deleted.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item to be altered.
element	String[] | Bytes[]	Elements to be removed by this operation.

Method response object

• Success
• Error

See response objects for specific information.

JavaScript

await cacheClient.setAddElements(cacheName, 'test-set', ['test-element1', 'test-element2']);
const result = await cacheClient.setRemoveElements(cacheName, 'test-set', ['test-element1', 'test-element2']);
switch (result.type) {
  case CacheSetRemoveElementsResponse.Success:
    console.log("Elements 'test-element1' and 'test-element2' removed successfully from set 'test-set'");
    break;
  case CacheSetRemoveElementsResponse.Error:
    throw new Error(
      `An error occurred while attempting to call cacheSetRemoveElements on set 'test-set' in cache '${cacheName}': ${result.errorCode()}: ${result.toString()}`
    );
}

info

Full example code and imports can be found here

Rust

  cache_client
      .set_remove_elements(cache_name, "set_name", vec!["element1", "element2"])
      .await?;
  println!("Elements removed from set");

info

Full example code and imports can be found here

SetContainsElement

Checks if a provided element is in the given set.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item.
element	String | Bytes	Name of the element to check existence of.

Method response object

The response object for SetContainsElement returns three possible options, a cache hit, miss, or an error.

• Hit
  • containsElement(): bool
• Miss
• Error

See response objects for specific information.

SetContainsElements

Checks if provided elements are in the given set.

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item.
elements	String[] | Bytes[]	Array of element names to check existence of.

Method response object

The response object for SetContainsElements returns three possible options, a cache hit, miss, or an error.

• Hit
  • containsElements(): bool[]
• Miss
• Error

See response objects for specific information.

SetLength

Get the length of an existing set item

Name	Type	Description
cacheName	String	Name of the cache.
setName	String	Name of the set item to be checked.

Method response object

• Hit
  • length(): Number
• Miss
• Error

See response objects for specific information.