Cache

The cache manager provides simple key-value storage at a high-speed data storage layer (Redis) speeding up the data set and get operations.

The values stored can be a single JSON object, an array of objects or primitive values (e.g., numbers, text, boolean). Values can be stored with an optional time-to-live (TTL) to automatically expire entries.

List keys in cache

The listKeys method retrieves a list of keys from your app's cache storage. You can use a pattern to narrow down the results or choose to retrieve all keys. This method is helpful for managing and inspecting cache data.

Javascript

const cacheName = "default"
// Retrieve 10 cache keys and their values mathing the pattern
const data1 = await agnost.cache(cacheName).listKeys("*", 10);

// Retrieve 5 cache keys and their values mathing the pattern from cache read-replica
const data2 = await agnost.cache(cacheName).listKeys("h*llo", 5, true);

Example response

The listKeys method returns a Promise that resolves to an object with the following structure:

[
  {
    "key": "key1",
    "value": "value2"
  },
  {
    "key": "key2",
    "value": "value2"
  },
  ...
]

Parameters

Here are the parameters for the listKeys method:

#	Name	Data Type	Required	Description
1	pattern	string	Yes	The pattern string used to filter cache keys.
2	count	number	Yes	The maximum number of keys and their values to return.
3	useReadReplica	boolean	No	Specifies whether to use the read replica of the cache. If no read replica cache exists, it uses the read-write database.

info

See below examples how to specify filtering pattern:

• h?llo matches hello, hallo and hxllo
• h*llo matches hllo and heeeello
• h[ae]llo matches hello and hallo, but not hillo
• h^ello matches hallo, hbllo, ... but not hello
• h[a-b]llo matches hallo and hbllo

Set items in cache

You can set items in the cache using the setKeyValue method and overwrite any existing value already set. If TTL (time to live) is specified, it automatically sets the stored entry to expire in specified milliseconds. Any previous TTL associated with the key is discarded on a successful set operation.

Javascript

const cacheName = "default";
const key = "lastUserOrder";

// Store key value in cache
await agnost.cache(cacheName).setKeyValue(key, {
  productId: "prd000234",
  quantity: 12,
  customerId: "61fbf6ceeeed063ab062ac05",
  createdAt: "2022-02-09T10:55:34.562+00:00",
});

Parameters

Here, you can find parameters for the setKeyValue method.

#	Name	Data type	Required	Description
1	key	string	Yes	The key you want to set, must be a string.
2	value	any	Yes	The value you want to set in redis key-value pair.
3	ttl	number	No	The number of time to live in milliseconds.

Get item from cache

You can retrieve items from cache by using the getKeyValue method.

Javascript

const cacheName = "default";
const key = "lastUserOrder";

// Query items from cache with using the `key`
const result = await agnost.cache(cacheName).getKeyValue(key);

Example response

{
  "productId": "prd000234",
  "quantity": 12,
  "customerId": "61fbf6ceeeed063ab062ac05",
  "createdAt": "2022-02-09T10:55:34.562+00:00"
}

Parameters

Here, you can find parameters for the getKeyValue method.

#	Name	Data type	Required	Description
1	key	string	Yes	The key you want to get, must be a string.
2	useReadReplica	boolean	No	If set to true, the query will be executed on a read replica. If no read replica cache exists uses the read-write cache.

Delete items from cache

You can delete items from cache using the deleteKey method. It removes the specified key from the cache.

Javascript

const cacheName = "default";
const key = "lastUserOrder";

// Delete items from cache by key
await agnost.cache(cacheName).deleteKey(key);

Parameters

Here, you can find parameters for the deleteKey method.

#	Name	Data type	Required	Description
1	keys	string or array of strings	Yes	The key(s) you want to delete.

Set cache expiry time

You can set cache expiry time using the expireKey method. It sets a timeout on key. After the timeout has expired, the key will automatically be deleted.

Javascript

const cacheName = "default";
const key = "lastUserOrder";

// Set cache expiry time 60 seconds
await agnost.cache(cacheName).expireKey(key, 60 * 1000);

Parameters

Here you can find parameters for the expireKey method.

#	Name	Data type	Required	Description
1	key	string	Yes	The key to set its expiry duration.
2	ttl	number	No	The number of time to live in milliseconds.

Increment value

You can increment value using the incrementKeyValue method. It increments the value of the number stored at the key by the increment amount and returns the value of key after the increment.

Javascript

const cacheName = "default";
const key = "counter";

// Increment 'counter' value by 1
const result = await agnost.cache(cacheName).incrementKeyValue(key, 1)

info

• If the key does not exist, it is set to 0 before performing the operation.
• If ttl is specified, sets the stored entry to automatically expire in specified milliseconds.
• Any previous time to live associated with the key is discarded on successful increment operation.

Parameters

Here, you can find parameters for the incrementKeyValue method.

#	Name	Data type	Required	Description
1	key	string	Yes	The key you want to increment must be a string.
2	increment	number	Yes	The amount to increment the value by.
3	ttl	number	No	The number of time to live in milliseconds.

Decrement value

You can decrement value using the decrementKeyValue method. It decrements the value of the number stored at the key by the decrement amount.

Javascript

const cacheName = "default";
const key = "counter";

// Decrement 'counter' value by 1
const result = await agnost.cache(cacheName).decrementKeyValue(key, 1);

info

• If the key does not exist, it is set to 0 before performing the operation.
• If ttl is specified, sets the stored entry to automatically expire in specified milliseconds.
• Any previous time to live associated with the key is discarded on successful decrement operation.

Parameters

Here, you can find parameters for the decrementKeyValue method.

#	Name	Data type	Required	Description
1	key	string	Yes	The key you want to decrement must be a string.
2	decrement	number	No	The amount to decrement the value by.
3	ttl	number	No	The number of time to live in milliseconds.

Accessing Redis Client

For more detailed operations and to fully utilize the capabilities of Redis Client, you can call getClient method to retrieve the actual Redis client to the read-write cache. Please see Redis client documentation for more details.

Javascript

const cacheName = "default";
const redisClient = await agnost.cache(cacheName).getClient();