REPORT
Ask for a connected business document by name.
Syntax
Name the report, then add the parts you need, in any order.
REPORT ON NAME
OUTBOUND "gid://namespace/resource/id"
FILTER "gid://namespace/resource/id"
SHOW column, line.variant.product.vendor
WINDOW name
SORT column DESC
LIMIT 10
DEPTH 2Parameters and arguments
NAMEA report from the catalogue, in any case
Required: YesOUTBOUND, INBOUND or ANYThe direction to follow from the root. The keyword is optional and the default is
Required: NoOUTBOUNDrootOne or more quoted GIDs to start from, separated by commas. RELATIONSHIP_DISCOVERY reads the first, and it must be a record in your tenant
Required: YesFILTERQuoted GIDs, or conditions such as
Required: Nocolumn = value, that narrow the report to one point of a connection. Separate several with commasSHOWThe columns to return, separated by commas. A dotted path walks connections:
Required: Noline.variant.product.vendorgoes from the order's lines to their variants, products and vendors. A name may start with@to read an edge's metadata fieldWINDOWA named period for the report
Required: NoSORTColumns to order by, each with an optional
Required: NoASCorDESCLIMITThe most rows to return
Required: NoDEPTHHow many connections to follow
Required: No
Examples
RELATIONSHIP_DISCOVERY from one order, following its lines to their products' vendors and its location's name.
Return type and behaviour
RELATIONSHIP_DISCOVERY returns one nested document rooted at the record, holding the connections you named in SHOW. A connection with many records is a list.
The names a report accepts form a closed catalogue. A name outside it is refused with HTQL-3008.
Errors and exceptions
| Error | What happened | How to recover |
|---|---|---|
HTQL-3008 | The name is not a report in the catalogue. The answer reads Unknown report 'NO_SUCH_REPORT' | Check the report's name |
HTQL-3009 | The report is in the catalogue and has no engine behind it | Use RELATIONSHIP_DISCOVERY, or LEARN |
HTQL-2001 | The statement has no root (requires a root vertex), or its root is not a record in your tenant (is not a registered entity) | Start from a record that exists |
HTQL-1003 | The statement is not written in HTQL's grammar | Check the parts against the syntax |
Placement and context
REPORT is a statement of its own. Its parts can be written in any order.
Limitations
- RELATIONSHIP_DISCOVERY needs a SHOW of connection paths, such as
SHOW refund.amount, line.variant.product.vendor. - Not supported: any other report name in the catalogue. It answers
HTQL-3009. Build the answer you need with LEARN, or with a LOOKUP and JOIN. - The report reads your tenant's own commerce records, so the root GID is a record of that kind.
Permissions and security
REPORT reads the tenant's own records.
Best practices
- Start from one root record, and add FILTER to narrow further.
- Choose the columns you need with SHOW, so the document stays small.