The __index Metamethod

Now that you know how to attach metatables to tables, it's time to learn about the most important metamethod: __index. This metamethod controls what happens when you try to access a key that doesn't exist in a table.

Normally, when you look up a key that isn't in a table, Lua returns nil. But when a table has a metatable with an __index field, Lua will check that field instead. If __index points to another table, Lua will look for the key there:

local defaults = {
    health = 100,
    speed = 10
}

local player = {name = "Alice"}
local meta = {__index = defaults}

setmetatable(player, meta)

print(player.name)    -- Output: Alice
print(player.health)  -- Output: 100

In this example, player only has a name key. When you access player.health, Lua doesn't find it in player, so it checks the metatable's __index field. Since __index points to the defaults table, Lua looks there and finds health = 100.

This creates a fallback mechanism where one table can provide default values for another. The original table keeps its own values, but any missing keys are automatically looked up in the fallback table.

__index can also be a function. When a key is missing, Lua calls it with the table and the key, and uses whatever it returns:

local scores = {alice = 12}

setmetatable(scores, {
    __index = function(t, key)
        return 0  -- every missing name counts as 0
    end
})

print(scores.alice)  -- Output: 12
print(scores.bob)    -- Output: 0

A table gives fixed fallback values; a function can work out a value for any missing key.