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.

abort()

End the current query and return an abort error with a user-defined abort value.

Signature

abort(return: Any) => Never

Description

abort() lets you intentionally return an abort error in an FQL query or UDF. You can pass a user-defined return value to abort(). For example, in a UDF:

function checkout(orderId, status, payment) {
  ...
  // Abort the query if its calls `checkout()` with a
  // `status` other than `processing`.
  if (status != "processing") {
    // `Abort()` accepts a user-defined return value.
    // The value can be of any FQL type.
    abort("Cannot call checkout with status other than processing.")
  }
}

Calling abort() ends the current query, including all expressions in query, and returns an abort error. Changes made before the abort() call are discarded.

Abort errors

Abort errors use the abort error code and include the user-defined return value in the Query HTTP API endpoint's error.abort response body property:

{
  "error": {
      "code": "abort",
      "message": "Query aborted.",
      "abort": "\"Cannot call checkout with status other than processing.\""
  },
  ...
}

The return value is encoded to JSON using the data format specified in the X-Format header.

Fauna’s client drivers include classes for abort errors:

Parameters

Parameter Type Required Description

return

Any

Yes

User-defined value returned in the error.abort property of abort error responses.

The return value is encoded to JSON using the data format specified in the Query HTTP API request's X-Format header.

Return value

Type Description

Never

abort() never returns a value. Queries that call abort() always return an abort error, not query results.

Examples

This simple example shows how to abort a query.

Create a document in the collection and abort the query:

Customer.create({
  name: "John Doe",
  email: "jdoe@example.com",
  address: {
    street: "87856 Mendota Court",
    city: "Washington",
    state: "DC",
    postalCode: "20220",
    country: "US"
  }
})
abort("Discard")
abort: Query aborted.

error: Query aborted.
at *query*:12:6
   |
12 | abort("Discard")
   |      ^^^^^^^^^^^
   |

 

Run Customer.all() to verify that a customer with the last name of Jones wasn’t added.

The following example creates an anonymous function, which aborts when called without a valid email argument:

let createCustomer = (email) => {
  if (email.length <= 0) {
    abort({
      code: "invalid_email",
      message: "user email must be non-empty"
    })
  }
  Customer.create({
    name: "Jane Doe",
    email: email,
    address: {
      street: "87856 Mendota Court",
      city: "Washington",
      state: "DC",
      postalCode: "20220",
      country: "US"
    }
  })
}

createCustomer("fake@example.com")
createCustomer("")
abort: Query aborted.

error: Query aborted.
at *query*:3:10
  |
3 |       abort({
  |  __________^
4 | |       code: "invalid_email",
5 | |       message: "user email must be non-empty"
6 | |     })
  | |______^
  |
at *query*:22:15
   |
22 | createCustomer("")
   |               ^^^^
   |

The first call to createCustomer() succeeds. The second call fails because a valid email argument isn’t included, which triggers the abort() action.

The response message is the notification response.

Notice that the query runs all the statements included in the query.

Is this article helpful? 

Tell Fauna how the article can be improved:
 Visit Fauna's forums or email docs@fauna.com

Thank you for your feedback!