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
Required: YeskeyDOCUMENTS
Required: Yeskeys
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.
| Function | Returns | Behaviour | Form |
|---|---|---|---|
DOCUMENT | record | The record the GID names | DOCUMENT("gid://acme/order/6a1f") |
DOCUMENTS | list of records | The records the GIDs name | DOCUMENTS(["gid://acme/order/6a1f", "gid://acme/order/9c2e"]) |
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-5001 | The function was given the wrong number of arguments. The message names the function and the counts | Give it the arguments listed under Parameters |
HTQL-1004 Unsupported function | The name is not a function this engine runs | Check the name and its spelling against this entry |
HTQL-2001 Invalid document key | The 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 (
orderreadsorders) and the resource followed by_idnames the identifier column (order_id). - Coming: the content tenant of the guide's own site cannot run these two.
DOCUMENT("entries/aosIndexPage")answerscolumn "entries_id" does not existandDOCUMENT("gid://x/order/1")answersrelation "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.