Check out v4 of the Fauna CLI

v4 of the Fauna CLI is now GA.

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

Migrating from v3 of the CLI? See the CLI migration guide.

`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 a provided message in the summary of query responses and returns the 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.

Debug messages for UDF calls

When calling a user-defined function (UDF) that uses dbg(), the visibility of debug messages depends on the authentication secret's role:

Role Visibility

Role	Visibility
`admin`, `server`	Messages are returned in the response’s `summary`.
`server-readonly`, User-defined role	Messages are not returned, even if the UDF is annotated with `@role(admin)` or `@role(server)`.

admin, server

Messages are returned in the response’s summary.

server-readonly, User-defined role

Messages are not returned, even if the UDF is annotated with @role(admin) or @role(server).

Parameters

Parameter Type Required Description

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

value

Any

true

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()