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()}`
    );
}

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()}`
    );
}

Rust

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

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()}`
    );
}

Rust

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

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()}`
    );
}

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}");
}

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()}`
    );
}

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()}`
    );
}

Rust

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

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.