DOCUMENT and DOCUMENTS

Fetch a record by its identifier, or several at once, without writing a read.

Syntax

Write the function's name and a GID, or a list of GIDs.

DOCUMENT(key)
DOCUMENTS(keys)

Parameters and arguments

Arguments are written in brackets, separated by commas. An argument in square brackets is optional.

  • DOCUMENT

    key

    Required: Yes
  • DOCUMENTS

    keys

    Required: Yes

Examples

A record fetched by the GID another record stored, in one call.

Return type and behaviour

Each function returns one value. The table shows its type, what it does and one way to write it; the examples use the functions in realistic statements.

FunctionReturnsBehaviourForm
DOCUMENTrecordThe record the GID namesDOCUMENT("gid://acme/order/6a1f")
DOCUMENTSlist of recordsThe records the GIDs nameDOCUMENTS(["gid://acme/order/6a1f", "gid://acme/order/9c2e"])
Errors and exceptions
ErrorWhat happenedHow to recover
HTQL-5001The function was given the wrong number of arguments. The message names the function and the countsGive it the arguments listed under Parameters
HTQL-1004 Unsupported functionThe name is not a function this engine runsCheck the name and its spelling against this entry
HTQL-2001 Invalid document keyThe key is not a GID, such as DOCUMENT("entries")Write gid://namespace/resource/id or resource/id
Limitations
  • The key must be a GID. A table name such as "entries" is refused.
  • The resource part of the GID decides which table is read: its plural names the table (order reads orders) and the resource followed by _id names the identifier column (order_id).
  • Coming: the content tenant of the guide's own site cannot run these two. DOCUMENT("entries/aosIndexPage") answers column "entries_id" does not exist and DOCUMENT("gid://x/order/1") answers relation "orders" does not exist, so no output is shown for these examples: they need records of your own.
Permissions and security

DOCUMENT and DOCUMENTS read records, so they need read access to the table that the GID's resource names.

Best practices
  • Use DOCUMENTS to fetch several linked records in one call.
  • Use LOOKUP when you need to choose by a condition rather than by identifier.