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.
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.
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.
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.
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.
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.
.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.
const myQuery = e.select(e.Movie, () => ({
id: true,
title: true
}));
const result = await myQuery.runJSON(client);
// => '[{ "id": "abc...", "title": "The Avengers" }, ...]'