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 2

Parameters and arguments

  • NAME

    A report from the catalogue, in any case

    Required: Yes
  • OUTBOUND, INBOUND or ANY

    The direction to follow from the root. The keyword is optional and the default is OUTBOUND

    Required: No
  • root

    One 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: Yes
  • FILTER

    Quoted GIDs, or conditions such as column = value, that narrow the report to one point of a connection. Separate several with commas

    Required: No
  • SHOW

    The columns to return, separated by commas. A dotted path walks connections: line.variant.product.vendor goes from the order's lines to their variants, products and vendors. A name may start with @ to read an edge's metadata field

    Required: No
  • WINDOW

    A named period for the report

    Required: No
  • SORT

    Columns to order by, each with an optional ASC or DESC

    Required: No
  • LIMIT

    The most rows to return

    Required: No
  • DEPTH

    How 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
ErrorWhat happenedHow to recover
HTQL-3008The name is not a report in the catalogue. The answer reads Unknown report 'NO_SUCH_REPORT'Check the report's name
HTQL-3009The report is in the catalogue and has no engine behind itUse RELATIONSHIP_DISCOVERY, or LEARN
HTQL-2001The 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-1003The statement is not written in HTQL's grammarCheck 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.