Data types
When producing results, the client automatically decodes Gel types to the corresponding JavaScript types. When you pass scalar values to the client as arguments, the client automatically encodes them to the corresponding Gel types.
The table below shows the correspondence between Gel and JavaScript data types.
|
Gel Type |
JavaScript Type |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
n/a |
|
|
|
|
|
|
|
|
|
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
| |
|
|
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.
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
Gel array maps onto the JavaScript Array.
await client.querySingle<number[]>("select [1, 2, 3];");
// number[]: [1, 2, 3]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:
await client.query<{
title: string;
characters: {
name: string;
"@character_name": string;
}[];
}>(`
select Movie {
title,
characters: {
name,
@character_name
}
};
`);Tuples
A regular Gel
tuple becomes an Array in JavaScript. A Gel
namedtuple becomes an object with properties corresponding to the tuple elements.
await client.queryRequiredSingle<[number, string]>(`select (1, "hello");`);
// [number, string]: [1, 'hello']
await client.queryRequiredSingle<{
foo: number;
bar: string;
}>(`select (foo := 1, bar := "hello");`);
// { foo: number; bar: string }: { foo: 1; bar: 'hello' }Local Date
A JavaScript representation of a Gel
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 a Gel local_time value. Implements a subset of the TC39 Temporal Proposal
PlainTime type.
The Gel local_time type only has microsecond precision, any nanoseconds specified in the LocalTime will be ignored when encoding to a Gel local_time.
Local Date and Time
A JavaScript representation of a Gel
local_datetime value. Implements a subset of the TC39 Temporal Proposal
PlainDateTime type.
Inherits all properties from the LocalDate() and LocalTime() types.
Duration
A JavaScript representation of a Gel 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.
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 Gel 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.
The Gel duration type only has microsecond precision, any nanoseconds specified in the Duration will be ignored when encoding to a Gel duration.
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 Gel duration objects are always balanced.
Therefore in a round-trip of a Duration object to Gel and back, the returned object, while being an equivalent duration, may not have exactly the same property values as the sent object.
Get the string representation of the duration in ISO 8601 duration format.
Relative Duration
A JavaScript representation of a Gel cal::relative_duration value. This type represents a non-definite span of time such as "2 years 3 days". This cannot be represented as a duration 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.
Get the string representation of the duration in ISO 8601 duration format.
Date Duration
A JavaScript representation of a Gel cal::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 cal::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.
Get the string representation of the duration in ISO 8601 duration format.
Memory
The memory value in bytes (B).
The Gel cfg::memory represents a number of bytes stored as an int64. Since JS the number type is a float64, values above ~8191TiB will lose precision when represented as a JS number. To keep full precision use the bytesBigInt property.
Range
A JavaScript representation of a Gel std::range value. This is a generic TypeScript class with the following type signature.
class Range<
T extends number | Date | LocalDate | LocalDateTime | Duration
>{
// ...
}