EdgeQL queries can reference parameters with $ notation. The value of these
parameters are supplied externally.
select <str>$var;
select <int64>$a + <int64>$b;
select BlogPost filter .id = <uuid>$blog_id;Note that we provided an explicit type cast before the parameter. This is required, as it enables EdgeDB to enforce the provided types at runtime.
When you include a parameter reference in an EdgeDB REPL, you’ll be prompted interactively to provide a value or values.
db>
select 'I ❤️ ' ++ <str>$var ++ '!';Parameter <str>$var: EdgeDB
{'I ❤️ EdgeDB!'}await client.query(
"select 'I ❤️ ' ++ <str>$var ++ '!';",
var="lamp")
await client.query(
"select <datetime>$date;",
date=datetime.today())await client.query("select 'I ❤️ ' ++ <str>$name ++ '!';", {
name: "rock and roll"
});
await client.query("select <datetime>$date;", {
date: new Date()
});var result string
err = db.QuerySingle(ctx,
`select 'I ❤️ ' ++ <str>$var ++ '!';"`,
&result, "Golang")
var date time.Time
err = db.QuerySingle(ctx,
`select <datetime>$date;`,
&date, time.Now())Refer to the Datatypes page of your preferred client library to learn more about mapping between EdgeDB types and language-native types.
Prior to EdgeDB 3.0, parameters can be only scalars or arrays of scalars. In EdgeDB 3.0, parameters can also be tuples. This may seem limiting at first, but in actuality this doesn’t impose any practical limitation on what can be parameterized. To pass complex structures as parameters, use EdgeDB’s built-in JSON functionality.
db> ... ... ... ...
with data := <json>$data
insert Movie {
title := <str>data['title'],
release_year := <int64>data['release_year'],
};Parameter <json>$data: {"title": "The Marvels", "release_year": 2023}
{default::Movie {id: 8d286cfe-3c0a-11ec-aa68-3f3076ebd97f}}Arrays can be “unpacked” into sets and assigned to multi links or
properties.
with friends := (
select User filter .id in array_unpack(<array<uuid>>$friend_ids)
)
insert User {
name := <str>$name,
friends := friends,
};By default, query parameters are required; the query will fail if the
parameter value is an empty set. You can use an optional modifier inside
the type cast if the parameter is optional.
db>
select <optional str>$name;Parameter <str>$name (Ctrl+D for empty set `{}`):
{}When using a client library, pass the idiomatic null pointer for your language:
null, None, nil, etc.
The <required foo> type cast is also valid (though redundant) syntax.
select <required str>$name;Any data manipulation language (DML) statement can be
parameterized: select, insert, update, and delete.
Schema definition language (SDL) and configure statements cannot be parameterized. Data definition language (DDL) has limited support for parameters, but it’s not a recommended pattern. Some of the limitations might be lifted in the future versions.
