Reference

Client

): Client

Creates a new :jsClient instance.

param options

This is an optional parameter. When it is not specified the client will connect to the current EdgeDB Project instance.

If this parameter is a string it can represent either a DSN or an instance name:

when the string does not start with edgedb:// it is a name of an instance <ref_reference_connection_instance_name>;

otherwise it specifies a single string in the connection URI format: edgedb://user:password@host:port/database?option=value.

See the Connection Parameters <ref_reference_connection> docs for full details.

Alternatively the parameter can be a ConnectOptions config; see the documentation of valid options below.

param string options.dsn

Specifies the DSN of the instance.

param string options.credentialsFile

Path to a file containing credentials.

param string options.host

Database host address as either an IP address or a domain name.

param number options.port

Port number to connect to at the server host.

param string options.user

The name of the database role used for authentication.

param string options.database

The name of the database to connect to.

param string options.password

Password to be used for authentication, if the server requires one.

param string options.tlsCAFile

Path to a file containing the root certificate of the server.

param boolean options.tlsSecurity

Determines whether certificate and hostname verification is enabled. Valid values are 'strict' (certificate will be fully validated), 'no_host_verification' (certificate will be validated, but hostname may not match), 'insecure' (certificate not validated, self-signed certificates will be trusted), or 'default' (acts as strict by default, or no_host_verification if tlsCAFile is set).

The above connection options can also be specified by their corresponding environment variable. If none of dsn, credentialsFile, host or port are explicitly specified, the client will connect to your linked project instance, if it exists. For full details, see the Connection Parameters <ref_reference_connection> docs.

param number options.timeout

Connection timeout in milliseconds.

param number options.waitUntilAvailable

If first connection fails, the number of milliseconds to keep retrying to connect (Defaults to 30 seconds). Useful if your development instance and app are started together, to allow the server time to be ready.

param number options.concurrency

The maximum number of connection the Client will create in it's connection pool. If not specified the concurrency will be controlled by the server. This is recommended as it allows the server to better manage the number of client connections based on it's own available resources.

returns

Returns an instance of :jsClient.

Example:
// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const client = edgedb.createClient();

  const data = await client.querySingle("select 1 + 1");

  // The result is a number 2.
  assert(typeof data === "number");
  assert(data === 2);
}

main();

Type conversion

The client automatically converts EdgeDB types to the corresponding JavaScript types and vice versa.

The table below shows the correspondence between EdgeDB and JavaScript types.

EdgeDB Type	JavaScript Type
`multi` set	`Array`
`array<anytype>`	`Array`
`anytuple`	`Array`
`anyenum`	`string`
`Object`	`object`
`bool`	`boolean`
`bytes`	`Uint8Array`
`str`	`string`
`float32`, `float64`, `int16`, `int32`, `int64`	`number`
`bigint`	`BigInt`
`decimal`	n/a
`json`	`unknown`
`uuid`	`string`
`datetime`	`Date`
`cal::local_date`	:js`LocalDate`
`cal::local_time`	:js`LocalTime`
`cal::local_datetime`	:js`LocalDateTime`
`duration`	:js`Duration`
`cal::relative_duration`	:js`RelativeDuration`
`cal::date_duration`	:js`DateDuration`
`range<anytype>`	:js`Range`
`cfg::memory`	:js`ConfigMemory`

Note

Inexact single-precision float values may have a different representation when decoded into a JavaScript number. This is inherent to the implementation of limited-precision floating point types. If you need the decimal representation to match, cast the expression to float64 in your query.

Note

Due to precision limitations the decimal type cannot be decoded to a JavaScript number. Use an explicit cast to float64 if the precision degradation is acceptable or a cast to str for an exact decimal representation.

Arrays

EdgeDB array maps onto the JavaScript Array.

// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const client = edgedb.createClient("edgedb://edgedb@localhost/");

  const data = await client.querySingle("select [1, 2, 3]");

  // The result is an Array.
  assert(data instanceof Array);
  assert(typeof data[0] === "number");
  assert(data.length === 3);
  assert(data[2] === 3);
}

main();

Objects

Object represents an object instance returned from a query. The value of an object property or a link can be accessed through a corresponding object key:

// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const client = edgedb.createClient("edgedb://edgedb@localhost/");

  const data = await client.querySingle(`
    select schema::Property {
        name,
        annotations: {name, @value}
    }
    filter .name = 'listen_port'
        and .source.name = 'cfg::Config'
    limit 1
  `);

  // The property 'name' is accessible.
  assert(typeof data.name === "string");
  // The link 'annotaions' is accessible and is a Set.
  assert(typeof data.annotations === "object");
  assert(data.annotations instanceof edgedb.Set);
  // The Set of 'annotations' is array-like.
  assert(data.annotations.length > 0);
  assert(data.annotations[0].name === "cfg::system");
  assert(data.annotations[0]["@value"] === "true");
}

main();

Tuples

A regular EdgeDB tuple becomes an Array in JavaScript.

// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const client = edgedb.createClient("edgedb://edgedb@localhost/");

  const data = await client.querySingle(`
    select (1, 'a', [3])
  `);

  // The resulting tuple is an Array.
  assert(data instanceof Array);
  assert(data.length === 3);
  assert(typeof data[0] === "number");
  assert(typeof data[1] === "string");
  assert(data[2] instanceof Array);
}

main();

Named Tuples

A named EdgeDB tuple becomes an Array-like object in JavaScript, where the elements are accessible either by their names or indexes.

// Use the Node.js assert library to test results.
const assert = require("assert");
const edgedb = require("edgedb");

async function main() {
  const client = edgedb.createClient("edgedb://edgedb@localhost/");

  const data = await client.querySingle(`
    select (a := 1, b := 'a', c := [3])
  `);

  // The resulting tuple is an Array.
  assert(data instanceof Array);
  assert(data.length === 3);
  assert(typeof data[0] === "number");
  assert(typeof data[1] === "string");
  assert(data[2] instanceof Array);
  // Elements can be accessed by their names.
  assert(typeof data.a === "number");
  assert(typeof data["b"] === "string");
  assert(data.c instanceof Array);
}

main();

Local Date

A JavaScript representation of an EdgeDB local_date value. Implements a subset of the TC39 Temporal Proposal PlainDate type.

Assumes the calendar is always ISO 8601.

Local Time

A JavaScript representation of an EdgeDB local_time value. Implements a subset of the TC39 Temporal Proposal PlainTime type.

Note

The EdgeDB local_time type only has microsecond precision, any nanoseconds specified in the LocalTime will be ignored when encoding to an EdgeDB local_time.

Local Date and Time

A JavaScript representation of an EdgeDB local_datetime value. Implements a subset of the TC39 Temporal Proposal PlainDateTime type.

Inherits all properties from the :js~LocalDate and :js~LocalTime types.

Duration

A JavaScript representation of an EdgeDB duration value. This class attempts to conform to the TC39 Temporal Proposal Duration type as closely as possible.

No arguments may be infinite and all must have the same sign. Any non-integer arguments will be rounded towards zero.

Note

The Temporal Duration type can contain both absolute duration components, such as hours, minutes, seconds, etc. and relative duration components, such as years, months, weeks, and days, where their absolute duration changes depending on the exact date they are relative to (eg. different months have a different number of days).

The EdgeDB duration type only supports absolute durations, so any Duration with non-zero years, months, weeks, or days will throw an error when trying to encode them.

Note

The EdgeDB duration type only has microsecond precision, any nanoseconds specified in the Duration will be ignored when encoding to an EdgeDB duration.

Note

Temporal Duration objects can be unbalanced, (ie. have a greater value in any property than it would naturally have, eg. have a seconds property greater than 59), but EdgeDB duration objects are always balanced.

Therefore in a round-trip of a Duration object to EdgeDB and back, the returned object, while being an equivalent duration, may not have exactly the same property values as the sent object.

RelativeDuration

A JavaScript representation of an EdgeDB :eqlcal::relative_duration value. This type represents a non-definite span of time such as "2 years 3 days". This cannot be represented as a :eqlduration because a year has no absolute duration; for instance, leap years are longer than non-leap years.

This class attempts to conform to the TC39 Temporal Proposal Duration type as closely as possible.

Internally, a cal::relative_duration value is represented as an integer number of months, days, and seconds. During encoding, other units will be normalized to these three. Sub-second units like microseconds will be ignored.

DateDuration

)

A JavaScript representation of an EdgeDB :eqlcal::date_duration value. This type represents a non-definite span of time consisting of an integer number of months and days.

This type is primarily intended to simplify logic involving :eqlcal::local_date values.
db> select <cal::date_duration>'5 days';
{<cal::date_duration>'P5D'}
db> select <cal::local_date>'2022-06-25' + <cal::date_duration>'5 days';
{<cal::local_date>'2022-06-30'}
db> select <cal::local_date>'2022-06-30' - <cal::local_date>'2022-06-25';
{<cal::date_duration>'P5D'}
Internally, a cal::relative_duration value is represented as an integer number of months and days. During encoding, other units will be normalized to these two.

Memory

Range

)

A JavaScript representation of an EdgeDB std::range value. This is a generic TypeScript class with the following type signature.
class Range<
    T extends number | Date | LocalDate | LocalDateTime | Duration
>{
    // ...
}
}

Returns a JSON-encodable representation of the range.

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

reference.rst

reference.rst

Reference

Client

Type conversion

Arrays

Objects

Tuples

Named Tuples

Local Date

Local Time

Local Date and Time

Duration

RelativeDuration

DateDuration

Memory

Range

Files

reference.rst

Latest commit

History

reference.rst

File metadata and controls

Reference

Client

Type conversion

Arrays

Objects

Tuples

Named Tuples

Local Date

Local Time

Local Date and Time

Duration

RelativeDuration

DateDuration

Memory

Range