Parameters

You can pass strongly-typed parameters into your query with e.params.

  1. const helloQuery = e.params({name: e.str}, (params) =>
  2. e.op('Yer a wizard, ', '++', params.name)
  3. );
  4. /* with name := <str>$name
  5. select name;
  6. */

The first argument is an object defining the parameter names and their corresponding types. The second argument is a closure that returns an expression; use the params argument to construct the rest of your query.

Passing parameter data

To executing a query with parameters, pass the parameter data as the second argument to .run(); this argument is fully typed!

  1. await helloQuery.run(client, { name: "Harry Styles" })
  2. // => "Yer a wizard, Harry Styles"
  3. await helloQuery.run(client, { name: 16 })
  4. // => TypeError: number is not assignable to string

Top-level usage

Note that you must call .run on the result of e.params; in other words, you can only use e.params at the top level of your query, not as an expression inside a larger query.

  1. // ❌ TypeError
  2. const wrappedQuery = e.select(helloQuery);
  3. wrappedQuery.run(client, {name: "Harry Styles"});

Optional parameters

A type can be made optional with the e.optional function.

  1. const query = e.params(
  2. {
  3. title: e.str,
  4. duration: e.optional(e.duration),
  5. },
  6. (params) => {
  7. return e.insert(e.Movie, {
  8. title: params.title,
  9. duration: params.duration,
  10. });
  11. }
  12. );
  13. // works with duration
  14. const result = await query.run(client, {
  15. title: 'The Eternals',
  16. duration: new Duration(0, 2, 3)
  17. });
  18. // or without duration
  19. const result = await query.run(client, {title: 'The Eternals'});

Complex types

In EdgeQL, parameters can only be primitives or arrays of primitives. That’s not true with the query builder! Parameter types can be arbitrarily complex. Under the hood, the query builder serializes the parameters to JSON and deserializes them on the server.

  1. const insertMovie = e.params(
  2. {
  3. title: e.str,
  4. release_year: e.int64,
  5. actors: e.array(
  6. e.tuple({
  7. name: e.str,
  8. })
  9. ),
  10. },
  11. (params) =>
  12. e.insert(e.Movie, {
  13. title: params.title,
  14. })
  15. );
  16. await insertMovie.run(client, {
  17. title: 'Dune',
  18. release_year: 2021,
  19. actors: [{name: 'Timmy'}, {name: 'JMo'}],
  20. });