Indexing Resources

Link, unlink, or retrieve resources from a specific path by indexing resources in your Elements game or application.

Indexing allows you to not only link and unlink resources at a path, but it also allows you to retrieve resources. In fact, we can even use wildcards to retrieve a list of resources. Take creation path we used in the above example:

local creation_path = 
    string.format("games/%s/%s/%s", player1_id, player2_id, game_id)

we can use index.list to get all games between player 1 and player 2 like so:

local index = require "namazu.index"
...
local path = 
    string.format("games/%s/%s/%s", player1_id, player2_id, "*")

-- Array of { path, resource_id } for each game
local ids_of_games_between_players = index.list(path)

or even all of the games for player 1 if we change the path to: local path = string.format("games/%s/*", player1_id)

At this point, now that you have their ids, you can do whatever you like with the resources. The most common use case would be to invoke a method on them, for example:

-- Get all the games for the listed ids
local list_of_games = {}

for path, id in pairs(ids_of_games_between_players) do
    local game_info, response_code = resource.invoke(id, "get_info")

    if(response_code == responsecode.OK) then
        list_of_games[#list_of_games + 1] = game_info
    end
end

return response.formulate(200, list_of_games)

Index Functions

Require "namazu.index" from any Lua script.

-- Lists all ResourceIds matching a path
-- This executes a path query which may accept a wildcard path returning zero or more listings for resources.  The
-- return value is a table containing a mapping of path strings to resource_id strings.  Care must be taken when passing
-- a path to this function.  The remote will return all paths that match the supplied path.  Therefore, a large query
-- may consume considerable resources.  It is recommended that path schemes be crafted to return relatively small data
-- sets.
--
-- This function yields until the response is available and must be invoked from within a system-managed coroutine.
--
-- @param path the path, may be wildcard, to list
-- @return a sequence containing a table containing paths mapped to resource_ids (or an empty table)
-- @return a response code
function index.list(path)

--- Links a ResourceId to a Path
-- Associates a resource id to a path, essentially creating an alias at the new path.  There may exist many paths
-- referencing a single resource_id but not the converse.  This is useful for generating collections or associations
-- among Resources in the cluster.
--
-- This function yields until the response is available and must be invoked from within a system-managed coroutine.
--
-- @param resource_id the resource id to link to the new path
-- @param path the destination path to link
-- @return the response code indicating if the link was successful or not
function index.link(resource_id, path)

--- Links a Path to a Path
-- Associates a source path to a destination path, essentially creating an alias at the new path.  There may exist many
-- This is useful for generating collections or associations among Resources in the cluster.
--
-- This function yields until the response is available and must be invoked from within a system-managed coroutine.
--
-- @param source the source path
-- @param destination the destination path
-- @return the response code indicating if the link was successful or not
function index.link_path(source, destination)

--- Unlinks a path to its associated ResourceId
-- Removes a previous association at a specific path.  When all paths pointing to a resource are removed, then the
-- cluster will remove and destroy the resource.  In this scenario, this will have the same effect as destroying the
-- the resource using its id.
--
-- This function yields until the response is available and must be invoked from within a system-managed coroutine.
--
-- @param path the path to unlink
-- @return the affected resource id
-- @return a boolean indicating if it was destroyed
-- @return the actual network response code
function index.unlink(path)