Numbers
In SurrealDB, numbers can be one of three types. 64-bit integers, 64-bit floating point numbers, or arbitrary-length decimal numbers with infinite precision.
Integer numbers
If a numeric value is specified without any decimal point suffix and is within the range -9223372036854775808
to 9223372036854775807
then the value will be parsed, stored, and treated as a 64-bit integer.
CREATE event SET year = 2022;
Decimal numbers
If a number value is specified with a decimal point suffix, or is outside of the maximum range specified above, then the number will automatically be parsed, stored, and treated as an infinite length decimal value. This ensures that there is no loss of precision when performing mathematical calculations within SurrealDB.
CREATE event SET temperature = 41.5;
Floating point numbers
To use floating point numbers when specifying numeric values, you can cast the value to a 64-bit floating point number.
SELECT * FROM <float> 13.5719384719384719385639856394139476937756394756;
Using a specific numeric type
To use a specific type when specifying numeric values, you can cast the value to a specific numeric type.
CREATE event SET
year = <int> 2022,
temperature = <float> 41.5,
horizon = <decimal> 13.5719384719384719385639856394139476937756394756
;
Numeric precision
The benefits of floating point numeric values are speed and storage size, but there is a limit to the numeric precision.
SELECT * FROM <float> 13.5719384719384719385639856394139476937756394756;
13.571938471938473
In addition, when using floating point numbers specifically, mathematical operations can result in a loss of precision (as is normal with other databases).
SELECT * FROM <float> 0.3 + <float> 0.3 + <float> 0.3 + <float> 0.1;
1.0000000000000002
However, as numbers are treated as decimal values by default, then no precision is lost when performing mathematical calculations inside the database.
SELECT * FROM 0.3 + 0.3 + 0.3 + 0.1;
1.0
Numeric calculations
Different numeric types can be compared and used together in calculations.
SELECT * FROM <float> 13.5719384719384719385639856394139476937756394756;
13.571938471938473
In addition, when using floating point numbers specifically, mathematical operations can result in a loss of precision (as is normal with other databases).
SELECT * FROM <float> 0.3 + <float> 0.3 + <float> 0.3 + <float> 0.1;
1.0000000000000002
However, as numbers are treated as decimal values by default, then no precision is lost when performing mathematical calculations inside the database.
SELECT * FROM 0.3 + 0.3 + 0.3 + 0.1;
1.0
Mathematical constants
A set of floating point numeric constants are available in SurrealDB. Constant names are case insensitive, and can be specified with either lowercase or capital letters, or a mixture of both.
CREATE circle SET radius = circumference / ( 2 * MATH::PI );
Constant | Value |
---|---|
MATH::E |
2.718281828459045 |
MATH::FRAC_1_PI |
0.3183098861837907 |
MATH::FRAC_1_SQRT_2 |
0.7071067811865476 |
MATH::FRAC_2_PI |
0.6366197723675814 |
MATH::FRAC_2_SQRT_PI |
1.1283791670955126 |
MATH::FRAC_PI_2 |
1.5707963267948966 |
MATH::FRAC_PI_3 |
1.0471975511965979 |
MATH::FRAC_PI_4 |
0.7853981633974483 |
MATH::FRAC_PI_6 |
0.5235987755982989 |
MATH::FRAC_PI_8 |
0.39269908169872414 |
MATH::LN_10 |
2.302585092994046 |
MATH::LN_2 |
0.6931471805599453 |
MATH::LOG10_2 |
0.3010299956639812 |
MATH::LOG10_E |
0.4342944819032518 |
MATH::LOG2_10 |
3.321928094887362 |
MATH::LOG2_E |
1.4426950408889634 |
MATH::PI |
3.141592653589793 |
MATH::SQRT_2 |
1.4142135623730951 |
MATH::TAU |
6.283185307179586 |
Next steps
You've now seen how to use numeric values in SurrealDB. For more advanced functionality, take a look at the operators and math functions, which enable advanced calculations on numeric values and sets of numeric values.