Skip to main content

Query

Adds helpful functions that wrap Instance:QueryDescendants().

Functions​

all​

</>
Query.all(
parent: Instance,
selector: string
) → {Instance}

filter​

</>
Query.filter(
parent: Instance,
selector: string,
filter: (Instance) → boolean
) → {Instance}

Returns the query result, filtered by the filter function. Ideally, most of the filtering should be done with the selector itself. However, if the selector is not enough, this function can be used to further filter the results. 

local buttons = Query.filter(workspace, ".Button", function(instance)
	return instance.Transparency > 0.25
end)

map​

</>
Query.map(
parent: Instance,
selector: string,
map: (Instance) → T
) → {T}

Returns the query result mapped by the map function.

local Button = {}

function Button.new(btn: BasePart)
	...
end

----

local buttons = Query.map(workspace, ".Button", function(instance)
	return Button.new(instance)
end)

first​

</>
Query.first(
parent: Instance,
selector: string
) → Instance?

Returns the first item from the query. Might be nil if the query returns nothing.

This is equivalent to parent:QueryDescendants(selector)[1].

-- Find an instance tagged with 'Tycoon' that has
-- the OwnerId attribute matching the player's UserId:
local tycoon = Query.first(workspace, `.Tycoon[$OwnerId = {player.UserId}]`)

if tycoon then
	...
end

one​

</>
Query.one(
parent: Instance,
selector: string
) → Instance

Asserts that the query returns exactly one instance. The instance is returned. This is useful when attempting to find an exact match of an instance that must exist.

If the result returns zero or more than one result, an error is thrown.

-- Find a SpawnLocation that has the MainSpawn attribute set to true:
local spawnPoint = Query.one(workspace, "SpawnLocation[$MainSpawn = true]")
Show raw api
{
    "functions": [
        {
            "name": "all",
            "desc": "Equivalent to [`parent:QueryDescendants(selector)`](https://create.roblox.com/docs/reference/engine/classes/Instance#QueryDescendants).",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Instance }\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 17,
                "path": "modules/query/init.luau"
            }
        },
        {
            "name": "filter",
            "desc": "Returns the query result, filtered by the `filter` function. Ideally, most of\nthe filtering should be done with the selector itself. However, if the selector\nis not enough, this function can be used to further filter the results.\n\n```lua\nlocal buttons = Query.filter(workspace, \".Button\", function(instance)\n\treturn instance.Transparency > 0.25\nend)\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "filter",
                    "desc": "",
                    "lua_type": "(Instance) -> boolean"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ Instance }\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 34,
                "path": "modules/query/init.luau"
            }
        },
        {
            "name": "map",
            "desc": "Returns the query result mapped by the `map` function.\n\n```lua\nlocal Button = {}\n\nfunction Button.new(btn: BasePart)\n\t...\nend\n\n----\n\nlocal buttons = Query.map(workspace, \".Button\", function(instance)\n\treturn Button.new(instance)\nend)\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "string"
                },
                {
                    "name": "map",
                    "desc": "",
                    "lua_type": "(Instance) -> T"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "{ T }\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 63,
                "path": "modules/query/init.luau"
            }
        },
        {
            "name": "first",
            "desc": "Returns the first item from the query. Might be `nil` if the query returns\nnothing.\n\nThis is equivalent to `parent:QueryDescendants(selector)[1]`.\n\n```lua\n-- Find an instance tagged with 'Tycoon' that has\n-- the OwnerId attribute matching the player's UserId:\nlocal tycoon = Query.first(workspace, `.Tycoon[$OwnerId = {player.UserId}]`)\n\nif tycoon then\n\t...\nend\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance?\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 90,
                "path": "modules/query/init.luau"
            }
        },
        {
            "name": "one",
            "desc": "Asserts that the query returns exactly one instance. The instance is returned.\nThis is useful when attempting to find an exact match of an instance that\nmust exist.\n\nIf the result returns zero or more than one result, an error is thrown.\n\n```lua\n-- Find a SpawnLocation that has the MainSpawn attribute set to true:\nlocal spawnPoint = Query.one(workspace, \"SpawnLocation[$MainSpawn = true]\")\n```",
            "params": [
                {
                    "name": "parent",
                    "desc": "",
                    "lua_type": "Instance"
                },
                {
                    "name": "selector",
                    "desc": "",
                    "lua_type": "string"
                }
            ],
            "returns": [
                {
                    "desc": "",
                    "lua_type": "Instance\n"
                }
            ],
            "function_type": "static",
            "source": {
                "line": 108,
                "path": "modules/query/init.luau"
            }
        }
    ],
    "properties": [],
    "types": [],
    "name": "Query",
    "desc": "Adds helpful functions that wrap\n[`Instance:QueryDescendants()`](https://create.roblox.com/docs/reference/engine/classes/Instance#QueryDescendants).",
    "source": {
        "line": 9,
        "path": "modules/query/init.luau"
    }
}