Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now in beta.

The new version introduces enhancements to the developer experience, including an improved authentication workflow. To get started, check out the CLI v4 quick start.

`dbg()`

Output a debug message in the query summary and return the message in the query results.

Signature

dbg()(value: A) => A

Description

The dbg() (debug) method outputs message in the summary of query responses and returns message in the query result. In the summary, debug messages are annotated as info.

`dbg()` and `log()`

dbg() is similar to log() except that dbg() returns its message in the actual query result.

You can use dbg() inline within method calls for debugging.

Debug message template

The debug message template is:

info: <message>
at *<source>*:<line>:<column>
       |
<line> | dbg(<message>)
       |    ^^^^^^^^^^^
       |

where:

Field Description

<source>

Message source.
One of:

Source Description

query

The dbg() call occurred in the main query body.

udf:<function>

The dbg() call occurred in the user-defined function named <function>

<line>

Line number where dbg() is used.

<column>

Character offset in <line> where dbg() is used.

<message>

String-serialized message.

Parameters

Parameter Type Required Description

Parameter	Type	Required	Description
`value`	Any	Yes	Value to output to the query summary and query results.

value

Any

Yes

Value to output to the query summary and query results.

Return value

Type	Description
Any	Returns `value`.

Examples

Basic example

The following FQL query uses dbg() within a collection.create() call:

let x = "key limes"

Product.create(
  // `dbg()` outputs its message. In this case,
  // it outputs a struct containing the `name`
  // and `stock` properties.
  dbg({
    name: "#{x}",
    stock: 1 + 2 + 3,
  })
)

The query as a Query endpoint request:

 curl -X POST \
  'https://db.fauna.com/query/1' \
  -H 'Authorization: Bearer <FAUNA_SECRET>' \
  -H 'Content-Type: application/json' \
  -H 'X-Format: tagged' \
  -d '{
    "query": "let x = \"key limes\"\n\nProduct.create(\n  dbg({\n    name: \"#{x}\",\n    stock: 1 + 2 + 3,\n  })\n)"
  }'

The message is included in the query results in data. The summary includes the query lines that called dbg():

{
  "data": {
    "@doc": {
      "id": "413921254218661965",
      "coll": {
        "@mod": "Product"
      },
      "ts": {
        "@time": "2099-11-07T18:41:59.173Z"
      },
      "name": "key limes",
      "stock": {
        "@int": "6"
      }
    }
  },
  "static_type": "Product",
  "summary": "info: { name: \"key limes\", stock: 6 }\nat *query*:4:6\n  |\n4 |     dbg({\n  |  ______^\n5 | |     name: \"#{x}\",\n6 | |     stock: 1 + 2 + 3,\n7 | |   })\n  | |____^\n  |",
  ...
}

When unescaped, the response’s summary renders as:

info: { name: "key limes", stock: 6 }
at *query*:4:6
  |
4 |     dbg({
  |  ______^
5 | |     name: "#{x}",
6 | |     stock: 1 + 2 + 3,
7 | |   })
  | |____^
  |

Output a field value

Product.create({
  name: "debug1",
  stock: dbg(1 + 2 + 3),
})

info: 6
at *query*:3:13
  |
3 |   stock: dbg(1 + 2 + 3),
  |             ^^^^^^^^^^^
  |

{
  id: "394873023799230528",
  coll: Product,
  ts: Time("2099-04-11T12:38:31.050Z"),
  name: "debug1",
  stock: 6
}

Output an object

Product.create(
  dbg({
    name: "debug2",
    stock: 1 + 2 + 3,
  })
)

info: { name: "debug2", stock: 6 }
at *query*:2:6
  |
2 |     dbg({
  |  ______^
3 | |     name: "debug2",
4 | |     stock: 1 + 2 + 3,
5 | |   })
  | |____^
  |

{
  id: "394873104675897408",
  coll: Product,
  ts: Time("2099-04-11T12:39:48.180Z"),
  name: "debug2",
  stock: 6
}

Output a document

dbg(
  Product.create({
    name: "debug3",
    stock: 1 + 2 + 3,
  })
)

info: { id: ID("394873211262599234"), coll: Product, ts: TransactionTime(), name: "debug3", stock: 6 }
at *query*:1:4
  |
1 |   dbg(
  |  ____^
2 | |   Product.create({
3 | |     name: "debug3",
4 | |     stock: 1 + 2 + 3,
5 | |   })
6 | | )
  | |_^
  |

{
  id: "394873211262599234",
  coll: Product,
  ts: Time("2099-04-11T12:41:29.835Z"),
  name: "debug3",
  stock: 6
}

dbg()