Literals​

The query builder provides a set of “helper functions” that convert JavaScript literals into expressions that can be used in queries. For the most part, these helper functions correspond to the name of the type.

Primitives​

Primitive literal expressions are created using constructor functions that correspond to EdgeDB datatypes. Each expression below is accompanied by the EdgeQL it produces.

1. e.str("asdf")            // "asdf"
2. e.int64(123)             // 1234
3. e.float64(123.456)       // 123.456
4. e.bool(true)             // true
5. e.bigint(12345n)         // 12345n
6. e.decimal("1234.1234n")  // 1234.1234n
7. e.uuid("599236a4...")    // <uuid>"599236a4..."

9. e.bytes(Buffer.from('binary data'));
10. // b'binary data'

Strings​

String expressions have some special functionality: they support indexing and slicing, as in EdgeQL.

1. const myString = e.str("hello world");

3. myString[5];         //  "hello world"[5]
4. myString['2:5'];     //  "hello world"[0:5]
5. myString[':5'];     //  "hello world"[:5]
6. myString['2:'];     //  "hello world"[:5]

There are also equivalent .index and .slice methods that can accept integer expressions as arguments.

1. const myString = e.str("hello world");
2. const start = e.int64(2);
3. const end = e.int64(5);

5. myString.index(start);          //  "hello world"[2]
6. myString.slice(start, end);     //  "hello world"[2:5]
7. myString.slice(null, end);      //  "hello world"[:5]
8. myString.slice(start, null);    //  "hello world"[2:]

Enums​

All enum types are represented as functions.

1. e.Colors('green');
2. // Colors.green;

4. e.sys.VersionStage('beta');
5. // sys::VersionStage.beta

Dates and times​

To create an instance of datetime, pass a JavaScript Date object into e.datetime:

1. e.datetime(new Date('1999-01-01')))
2. // <datetime>'1999-01-01T00:00:00.000Z'

EdgeDB’s other temporal datatypes don’t have equivalents in the JavaScript type system: duration, cal::local_date, cal::local_time, and cal::local_datetime.

To resolve this, each of these datatypes can be represented with an instance of a corresponding class, as defined in edgedb module. The driver uses these classes to represent these values in query results; they are documented on the Driver page.

The code below demonstrates how to declare each kind of temporal literal, along with the equivalent EdgeQL.

1. import * as edgedb from "edgedb";

3. const myDuration = new edgedb.Duration(0, 0, 0, 0, 1, 2, 3);
4. e.duration(myDuration);

6. const myLocalDate = new edgedb.LocalDate(1776, 07, 04);
7. e.cal.local_date(myLocalDate);

9. const myLocalTime = new edgedb.LocalTime(13, 15, 0);
10. e.cal.local_time(myLocalTime);

12. const myLocalDateTime = new edgedb.LocalDateTime(1776, 07, 04, 13, 15, 0);
13. e.cal.local_datetime(myLocalDateTime);

You can also declare these literals by casting an appropriately formatted str expression, as in EdgeQL. Casting is documented in more detail later in the docs.

1. e.cast(e.duration, e.str('5 minutes'));
2. // <std::duration>'5 minutes'

4. e.cast(e.cal.local_datetime, e.str('1999-03-31T15:17:00'));
5. // <cal::local_datetime>'1999-03-31T15:17:00'

7. e.cast(e.cal.local_date, e.str('1999-03-31'));
8. // <cal::local_date>'1999-03-31'

10. e.cast(e.cal.local_time, e.str('15:17:00'));
11. // <cal::local_time>'15:17:00'

JSON​

JSON literals are created with the e.json function. You can pass in any data structure of EdgeDB-encodable data.

What does “EdgeDB-encodable” mean? It means any JavaScript data structure with an equivalent in EdgeDB: strings, number, booleans, arrays, objects, bigint``s, ``Buffer``s, ``Date``s, and instances of EdgeDB's built-in classes: ``Duration, LocalDate LocalTime, and LocalDateTime.

1. e.json({ name: "Billie" })
2. // to_json('{"name": "Billie"}')

4. const data = e.json({
5. name: "Billie",
6. numbers: [1,2,3],
7. nested: { foo: "bar"},
8. duration: new edgedb.Duration(1, 3, 3)
9. })

JSON expressions support indexing, as in EdgeQL. The returned expression also has a json type.

1. const myJSON = e.json({ numbers: [0,1,2] });
2. // to_json('{"numbers":[0,1,2]}')

4. myJSON.numbers[0];
5. // to_json('{"numbers":[0,1,2]}')['numbers'][0]

Arrays​

Declare array expressions by passing an array of expressions into e.array.

1. e.array([e.str("a"), e.str("b"), e.str("b")]);
2. // ["a", "b", "c"]

EdgeQL semantics are enforced by TypeScript, so arrays can’t contain elements with incompatible types.

1. e.array([e.int64(5), e.str("foo")]);
2. // TypeError!

For convenence, the e.array can also accept arrays of plain JavaScript data as well.

1. e.array(['a', 'b', 'c']);
2. // ['a', 'b', 'c']

4. // you can intermixing expressions and plain data
5. e.array([1, 2, e.int64(3)]);
6. // [1, 2, 3]

Array expressions also support indexing and slicing operations.

1. const myArray = e.array(['a', 'b', 'c', 'd', 'e']);
2. // ['a', 'b', 'c', 'd', 'e']

4. myArray[1];
5. // ['a', 'b', 'c', 'd', 'e'][1]

7. myArray['1:3'];
8. // ['a', 'b', 'c', 'd', 'e'][1:3]

There are also equivalent .index and .slice methods that can accept other expressions as arguments.

1. const start = e.int64(1);
2. const end = e.int64(3);

4. myArray.index(start);
5. // ['a', 'b', 'c', 'd', 'e'][1]

7. myArray.slice(start, end);
8. // ['a', 'b', 'c', 'd', 'e'][1:3]

Tuples​

Declare tuples with e.tuple. Pass in an array to declare a “regular” (unnamed) tuple; pass in an object to declare a named tuple.

1. e.tuple([e.str("Peter Parker"), e.int64(18)]);
2. // ("Peter Parker", 18)

4. e.tuple({
5. name: e.str("Peter Parker"),
6. age: e.int64(18)
7. });
8. // (name := "Peter Parker", age := 18)

Tuple expressions support indexing.

1. // Unnamed tuples
2. const spidey = e.tuple([
3. e.str("Peter Parker"),
4. e.int64(18)
5. ]);
6. spidey[0];                 // => ("Peter Parker", 18)[0]
7. spidey.index(0);           // => ("Peter Parker", 18)[0]
8. spidey.index(e.int64(0));  // => ("Peter Parker", 18)[0]

10. // Named tuples
11. const spidey = e.tuple({
12. name: e.str("Peter Parker"),
13. age: e.int64(18)
14. });
15. spidey.name;
16. // (name := "Peter Parker", age := 18).name

Set literals​

Declare sets with e.set.

1. e.set(e.str("asdf"), e.str("qwer"));
2. // {'asdf', 'qwer'}

As in EdgeQL, sets can’t contain elements with incompatible types. These semantics are enforced by TypeScript.

1. e.set(e.int64(1234), e.str(1234));
2. // TypeError

Empty sets​

To declare an empty set, cast an empty set to the desired type. As in EdgeQL, empty sets are not allowed without a cast.

1. e.cast(e.int64, e.set());
2. // <std::int64>{}