Data Types

ArcadeDB supports several data types natively. Below is the complete table.

Type SQL type Description Java type Minimum — Maximum Auto-conversion from/to

Boolean

BOOLEAN

Handles only the values True or False

java.lang.Boolean or boolean

0 — 1

String

Integer

INTEGER

32-bit signed Integers

java.lang.Integer or int

-2,147,483,648 — +2,147,483,647

Any Number, String

Short

SHORT

Small 16-bit signed integers

java.lang.Short or short

-32,768 — 32,767

Any Number, String

Long

LONG

Big 64-bit signed integers

java.lang.Long or long

-263 — +263-1

Any Number, String

Float

FLOAT

Decimal numbers

java.lang.Float or float

2-149 — (2-2-23)*2127

Any Number, String

Double

DOUBLE

Decimal numbers with high precision

java.lang.Double or double

2-1074 — (2-2-52)*21023

Any Number, String

Datetime

DATETIME

Any date with the precision up to milliseconds. To know more about it, look at Managing Dates

java.util.Date

Date, Long, String

Local time

LOCAL_TIME

A time of day without an offset, e.g. 10:15:30. (Since v26.10.2.) See Managing Dates

java.time.LocalTime

String

Offset time

OFFSET_TIME

A time of day with a UTC offset, e.g. 09:00:00-05:00. (Since v26.10.2.)

java.time.OffsetTime

String

Zoned datetime

ZONED_DATETIME

A datetime that keeps the zone or offset it was written with, e.g. 2024-01-01T10:00:00+01:00[Europe/Rome]. (Since v26.10.2.)

java.time.ZonedDateTime

String

Duration

DURATION

An openCypher duration with months, days, seconds and nanoseconds, e.g. P1M2DT3S. (Since v26.10.2.)

com.arcadedb.query.opencypher.temporal.CypherDuration

String

String

STRING

Any string as alphanumeric sequence of chars

java.lang.String

Binary

BINARY

Can contain any value as byte array

byte[]

0 — 2,147,483,647

String

Embedded

EMBEDDED

The Record is contained inside the owner. The contained record has no RID

EmbeddedDocument

EmbeddedDocument

Embedded list

LIST

The Records are contained inside the owner. The contained records have no RIDs and are reachable only by navigating the owner record

List<EmbeddedDocument>

0 — 41,000,000 items

String

Embedded map

MAP

The Records are contained inside the owner as values of the entries, while the keys can only be Strings. The contained records have no RIDs and are reachable only by navigating the owner Record

Map<String, EmbeddedDocument>

0 — 41,000,000 items

Collection<? extends EmbeddedDocument<?>>, String

Link

LINK

Link to another Record. It’s a common one-to-one relationship

RID, <? extends Record>

1:-1 — 32767:263-1

String

Byte

BYTE

Single byte. Useful to store small 8-bit signed integers

java.lang.Byte or byte

-128 — +127

Any Number, String

Decimal

DECIMAL

Decimal numbers without rounding

java.math.BigDecimal

Any Number, String

Vector

ARRAY_OF_?

Vector of scalar types: SHORTS, INTEGERS, LONGS, FLOATS, DOUBLES. A full type is for example then ARRAY_OF_FLOATS

Tuples
Embedded types, like EMBEDDED (document), (embedded) LIST, and (embedded) MAP are non-scalar types.
A vector type can be either LIST OF SHORT|INTEGER|LONG|FLOAT|DOUBLE or ARRAY_OF_SHORTS|INTEGERS|LONGS|FLOATS|DOUBLES.
An ARRAY_OF_FLOATS or ARRAY_OF_DOUBLES value is stored fixed-width: the element count followed by the raw little-endian IEEE-754 elements, 4 bytes per float and 8 per double (since v26.11.1). Before, each element was written as a zigzag varint of its bit pattern, 5 bytes per float and 9 to 10 per double. A record holding a 1536-dimension float embedding shrinks from about 7,695 to about 6,150 bytes, so 9 such records fit a 64 KiB bucket page instead of 7, about 22% less disk and page cache. Existing records need no migration: the old form is still read, and an update rewrites the value in the new form. Once a database holds records in the new form, a build older than 26.11.1 cannot read them (see Upgrade). In an HA cluster the new form is written only once every peer advertises the fixed-width-float-arrays capability, so a rolling upgrade keeps writing the old form until the last node runs 26.11.1 (see High Availability).
A declared ARRAY_OF_SHORTS|INTEGERS|LONGS|FLOATS|DOUBLES property takes a list or an array of numbers, primitive (float[], int[], …​) or boxed (Float[], Object[], …​), and converts it to the declared element type, refusing an item out of its range. Since v26.11.1 any other value is refused with an error naming the property: a scalar (embedding = 0.5), a string ('[0.1, 0.2]'), a map, a list with a null or non-numeric item, or a number the element type cannot hold (Double.MAX_VALUE for an ARRAY_OF_FLOATS, which used to become Infinity). Before, such a value was stored as it came, and depending on whether a vector index on the property already existed, the write failed or the row was silently missing from an index created afterwards. Records written before the upgrade are read back unchanged.
An equality lookup (=, <>, IN) on a FLOAT or DOUBLE property converts the operand to the property’s type, with or without an index. A FLOAT holding 0.1 is therefore found by the double 0.10000000149011612 (what you get by reading the FLOAT back as a double), and a DOUBLE is found by the BigDecimal that rounds to it. Ordering (<, >) is unchanged and reads a FLOAT by its decimal value, so a value can satisfy both = and < against the same operand.
A write to a declared property is refused, with an error naming the property, when the value cannot be held by the type: a boolean, list, map or date for a numeric property, an empty string for a numeric property, a number outside the 64-bit range for a LONG (or a finite number that overflows a FLOAT or DOUBLE), an empty or digit-only string for a DATETIME, a string for a BINARY, a non-link value for a LINK, or an array for a STRING. A STRING holding a lone UTF-16 surrogate (for example "\uD83D", which cannot be encoded as UTF-8) is refused with a validation error instead of being stored as ? (since v26.10.1). Such a value is never stored as NULL, 0 or as a value of another type, with or without an index. A number written to a BOOLEAN is false only when it is 0.
A java.math.BigInteger written to a property with no declared type keeps its exact value: inside the 64-bit range it is stored as an INTEGER or LONG, outside it as a DECIMAL (it reads back as a BigDecimal with the same digits), never as a rounded DOUBLE.
Equality lookups give the same answer with or without an index. Two DECIMAL values are equal when they have the same numeric value, whatever their scale (19.9 equals 19.90). A DATETIME property is matched by a java.time.Instant, ZonedDateTime or OffsetDateTime of the same moment. A BOOLEAN property is matched by true/false as a string or by a number (0 is false, anything else is true); an operand that does not read as a boolean matches nothing.
When serializing floating point types FLOAT and DOUBLE to JSON, NaN, Inf, and -Inf are cast to null, wherever they appear, including inside lists and arrays (before v26.10.1 a non-finite value inside a list was written as 0) (since v26.10.1).

Embedded MAP vs EMBEDDED Document

A MAP type and an EMBEDDED type are both a hierarchy of key-value pairs (think JSON); but the EMBEDDED type needs to know which document type it is an instance of. Hence, to embed a document, a document type needs to be declared beforehand, such that upon embedding validity of constrains (if existing) can be checked.

The embedded type is taken from either of two places:

  • a @type property in the value’s top-level, naming an existing document type, or

  • the property’s own declared embedded type, when the property was created with one (CREATE PROPERTY Person.address EMBEDDED OF Address).

If the property declares an embedded type, a plain map is enough and you do not have to repeat @type:

person.set("address", Map.of("city", "Rome"));

A @type in the value still takes precedence where present, which is how you store a subtype of the declared one. If neither is available, the value is rejected.