Memory store hash map

Explains how to implement the hash map data structure for memory stores.

Hash maps, similar to sorted maps, let you store in-memory data as key-value pairs. Unlike sorted maps, they maintain no ordering guarantees. This data structure is useful for cases that require simple data caching and rapid access, such as shared inventories, physical auction houses, and more. Hash maps automatically handle partitioning your data and are very useful if you have more than 1,000 keys. For smaller key spaces, we recommend sorted maps.

Limits#

Hash maps have a key size limit of 128 characters and a value size limit of 32 KB.

Otherwise, hash maps use the same API request and memory quota limits as the other memory store data structures.

Get a hash map#

To get a hash map, call MemoryStoreService:GetHashMap() with a name for the hash map. The name is global within the game, so you can access the same hash map on any script using this name.

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

After you get a hash map, call any of the following functions to read or write data in it:

Function	Action
`MemoryStoreHashMap:SetAsync()`	Add a new key or overwrite the value if the key already exists.
`MemoryStoreHashMap:GetAsync()`	Read a particular key.
`MemoryStoreHashMap:ListItemsAsync()`	List items in a hash map.
`MemoryStoreHashMap:UpdateAsync()`	Update the value of a key after retrieving it from a hash map.
`MemoryStoreHashMap:RemoveAsync()`	Remove a key from the hash map.

For in-depth documentation about each function, see MemoryStoreHashMap.

All functions accessing data structures in memory stores are asynchronous network calls that might occasionally fail. You should wrap these calls in LuaGlobals.pcall() to catch and handle errors, as shown in the code samples.

Add or overwrite data#

To add a new key or overwrite the value of a key in the hash map, call MemoryStoreHashMap:SetAsync() with the key name, its value, and an expiration time in seconds. The memory automatically cleans up once the key expires. The maximum expiration time is 3,888,000 seconds (45 days).

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

Get data#

You can either get a value associated with a specific key or get multiple key-value pairs in the hash map.

Get data with one key#

To get a value associated with one key from the hash map, call MemoryStoreHashMap:GetAsync() with the key name.

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local item
local getSuccess, getError = pcall(function()
	item = hashMap:GetAsync("User_1234")
end)
if getSuccess then
	print(item)
else
	warn(getError)
end

Get data with multiple key-value pairs#

To get all the key-value pairs from the hash map as a single operation, call MemoryStoreHashMap:ListItemsAsync() with the desired page size. This function lists all existing keys in a paginated manner. For example, the following code sample retrieves up to 32 items from the hash map.

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Get list of items, 32 items at a time
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Get the current page
		local entries = pages:GetCurrentPage()
		-- Iterate through all key-value pairs on page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
		end
		-- Check if last page has been reached
		if pages.IsFinished then
			break
		else
			print("----------")
			-- Advance to next page
			pages:AdvanceToNextPageAsync()
		end
	end
end

Update data#

To retrieve the value of a key from a hash map and update it, call MemoryStoreHashMap:UpdateAsync() with the key name, a callback function to update the key, and an expiration time in seconds.

For most games, multiple servers can update the same key concurrently and change the value. As UpdateAsync() always modifies the latest value before updating, you should use it to read the latest value as the input for your callback function.

For example, the following code sample updates the resource count of a resource in a shared inventory. UpdateAsync() ensures that all player contributions will make their way into this shared inventory, even if these contributions are made simultaneously. In this function, it also enforces a max resource count of 500.

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("ResourceInventory")

local function contributeResources(itemResource, addedCount)
	local success, newResourceCount = pcall(function()
		return hashMap:UpdateAsync(itemResource, function(resource)
			resource = resource or {count = 0}
			resource.count = resource.count + addedCount

			-- ensure we don't exceed the maximum resource count
			if resource.count > 500 then
				resource.count = 500
			end
			return resource
		end, 1200)
	end)
	if success then
		print(newResourceCount)
	end
end

The latency for UpdateAsync() is similar to GetAsync() and SetAsync() unless there is contention.

When contention occurs, the system automatically retries the operation until one of these three happens: the operation succeeds, the callback function returns nil, or the maximum number of retries is reached. If the system reaches the maximum number of retries, it returns a conflict.

Remove data#

You can use MemoryStoreHashMap:RemoveAsync() for both removing one key from the hash map and deleting all data in a memory store hash map.

Remove a key#

To remove a key from the hash map, call MemoryStoreHashMap:RemoveAsync() with a key name.

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

local setSuccess, _ = pcall(function()
	return hashMap:SetAsync("User_1234", 1000, 30)
end)
if setSuccess then
	print("Set succeeded.")
end

local removeSuccess, removeError = pcall(function()
	hashMap:RemoveAsync("User_1234")
end)
if not removeSuccess then
	warn(removeError)
end

Delete all data#

To delete all data in a hash map, list all your items with MemoryStoreHashMap:ListItemsAsync(), then remove them with MemoryStoreHashMap:RemoveAsync().

Luau

local MemoryStoreService = game:GetService("MemoryStoreService")

local hashMap = MemoryStoreService:GetHashMap("HashMap1")

-- Get list of items, 32 items at a time
local success, pages = pcall(function()
	return hashMap:ListItemsAsync(32)
end)
if success then
	while true do
		-- Get the current page
		local entries = pages:GetCurrentPage()
		local removeSuccess = true
		local removeError = nil
		-- Iterate through all key-value pairs on page
		for _, entry in ipairs(entries) do
			print(entry.key .. " : " .. tostring(entry.value))
			removeSuccess, removeError = pcall(function()
				hashMap:RemoveAsync(entry.key)
			end)

			if not removeSuccess then
				warn(removeError)
			end
		end
		-- Check if last page has been reached
		if pages.IsFinished then
			print("Finished deleting all data.")
			break
		else
			print("----------")
			-- Advance to next page
			pages:AdvanceToNextPageAsync()
		end
	end
end