Light
Dark
System
1.0latest

Expressions

The query builder is exact what it sounds like: a way to declare EdgeQL queries with code. By convention, it’s imported from the directory where it was generated as a single, default import called e.

Copy
import e from "./dbschema/edgeql-js";

The e variable provides everything you need to build any EdgeQL query. All EdgeQL commands, standard library functions, and types are available as properties on e.

Copy
import e from "./dbschema/edgeql-js";

// commands
e.select;
e.insert;
e.update;
e.delete;

// types
e.str;
e.bool;
e.int64;
e.duration;
e.cal.local_date;

// functions
e.str_upper;
e.len;
e.count;
e.math.stddev;

These building blocks are used to define expressions. Everything you create using the query builder is an expression. Expressions have a few things in common.

Below is a number of expressions and the EdgeQL they produce. (The actual EdgeQL the create may look slightly different, but it’s equivalent.) You can extract an EdgeQL representation of any expression calling the .toEdgeQL() method.

Copy
e.str("Hello world!").toEdgeQL();
// "Hello world"

e.set(1, 2, 3).toEdgeQL();
// {1, 2, 3}

e.count(e.Movie).toEdgeQL();
// count(Movie)

e.insert(e.Movie, { title: "Iron Man "}).toEdgeQL();
// insert Movie { title := "Iron Man" }

e.select(e.Movie, () => ({ id: true, title: true })).toEdgeQL();
// select Movie { id, title }

The query builder automatically infers the TypeScript type that best represents the result of a given expression. This inferred type can be extracted with the $infer helper.

Copy
import e, {$infer} from "./dbschema/edgeql-js";

const query = e.select(e.Movie, () => ({ id: true, title: true }));
type result = $infer<typeof query>;
// {id: string; title: string}[]

Expressions can be executed with the .run method.

Copy
import * as edgedb from "edgedb";

const client = edgedb.createClient();
const myQuery = e.select(e.Movie, () => ({
  id: true,
  title: true
}));

const result = await myQuery.run(client)
// => [{ id: "abc...", title: "The Avengers" }, ...]

Note that the .run method accepts an instance of Client() (or Transaction) as it’s first argument. See Creating a Client for details on creating clients. The second argument is for passing $parameters, more on that later.

Copy
.run(client: Client | Transaction, params: Params): Promise<T>

JSON serialization

You can also use the runJSON method to retrieve the query results as a serialized JSON-formatted string. This serialization happens inside the database and is much faster than calling JSON.stringify.

Copy
const myQuery = e.select(e.Movie, () => ({
  id: true,
  title: true
}));
const result = await myQuery.runJSON(client);
// => '[{ "id": "abc...", "title": "The Avengers" }, ...]'
Light
Dark
System