Big Number type

Overview #

This type is designed to store large numbers and can accommodate up to 34 significant digits.

The big number type utilizes bignumber.js within the JavaScript API. For performing operations using this data type, you can refer to bignumber.js’s documentation.

To set the value, you can use a string, number, or a big number object. The BigNumber class is accessible through sys.utils.numbers.

For instance:

// retrieve the big number instance
var bigNumber = record.field('raiting').val();
// perform some operation. Check documentation http://mikemcl.github.io/bignumber.js
bigNumber = bigNumber.plus(3); // objects are immutable
// set value before save it
record.field('raiting').val(bigNumber);

// or
var bigNumber = new sys.utils.numbers.BigNumber(1011, 2);
bigNumber = bigNumber.plus(5);
record.field('raiting').val(bigNumber);

Available features #

Type rules #

Minimum value #

The minimum value (inclusive).

Maximum value #

The maximum value (inclusive).

Limit decimals #

This feature enables the limitation of the number of decimals. This limitation will be applied at the data level, meaning numbers will be stored in the database with the specified number of decimals, and any additional decimals will be discarded. If you wish to retain the additional decimals for display purposes while limiting their storage, you should configure these settings within the display options.

When you opt to limit the number of decimals, the following choices will be presented:

• Number of Decimals: This indicates the number of decimals to be stored. It can range from 0 to 4.

• Extra Decimals Action: This specifies the action to take when there are more decimals than the limit permits. The available options include:

  • Round: Rounding will be used to limit the decimals.
  • Truncate: Truncation will be applied to the trailing decimals.
  • Throw Error: An error will be triggered if an attempt is made to set more decimals than the allowable limit.

Display options #

• Show Thousands Separator: If this flag is enabled, the thousands separator will be displayed in read-only mode. Please note that this flag does not impact edit mode.

• Limit Number of Decimals: This feature permits the restriction of the displayed decimals. It operates at the UI level and does not affect validation rules or the storage of numbers in the database. Consequently, these options only apply to read-only mode.

When you choose to limit the number of decimals, the following choices will be available:

• Number of Decimals: This denotes the count of decimals to be shown. It can range from 0 to 4.

• Extra Decimals Action: This specifies the action to be taken when there are more decimals than the set limit. The available options include:

  • Round: Rounding will be employed to limit the decimals.
  • Truncate: Truncation will be applied to the trailing decimals.

REST API #

Read format #

The format is an string with big number:

"amount": "8.997738199773819977381"

Write format #

To set the value, provide a string with the big number:

"amount": "8.997738199773819977381"

JavaScript API #

Read format #

The val() method within the wrapper will return an instance of a big number:

// this will print something like "energy: 0.123465789"
log('energy: '+record.field('energy').val());

var value = record.field('energy').val();
log('energy: '+ value.toFormat(2)); // toFormat is a BigNumber function and limit to two decimals

Write format #

To set the value, provide a number, string, or big number:

var number = new sys.utils.numbers.BigNumber('zz.9', 36);   // Number base 36 -> "1295.25"
var n1 = new sys.utils.numbers.BigNumber(1011, 2);          // Number base 2  -> "11"
number = number.plus(n1);
log(number);  // print -> 1306.25
record.field('energy').val(number); // set before seved it

Wrapper method:
toHex() #

The toHex() method returns string of hexadecimal representation of the value or empty ('') if null.

Returns #

string - Hex value of number.

Samples #

// prints the hex value of a big number field
var record = sys.data.findOne('contacts', {email: 'william.brown@acme.com'});
sys.logs.debug('contact token hex: '+record.field('token').toHex());

Wrapper method:
format(options) #

Returns a string representing the formatted number value or an unformatted string.

Parameters #

Returns #

string - String of formatted value of number.

Samples #

// prints the formated value of a big number field
var inv = sys.data.findById('invoices', '579f5929e4b043b8ce4519b6');
sys.logs.debug('total: ' + inv.field('total').format({
  'thousandsSeparator': true, 
  'limitNumberOfDecimals': true, 
  'numberOfDecimals': 2
  })
);

Export/Import #

Export format #

The export format is a big number:

"bigNumberField1","bigNumberField2"
"0.872","27810.0028"

Import format #

The import format is a string with a big number:

"bigNumberField1","bigNumberField2"
"0.872","27810.0028"

Queries #

For more information, please refer to the Query Language Documentation.

Available operators #

Query formats #

You should provide the number. For instance:

// finds companies with rating grater or equals than 3.0 
var records_sample = sys.data.find('companies', {'rating': 'greaterOrEquals(3.0)'});
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds companies with rating grater or equals than 3.0 
var query_sample = sys.data.createQuery('companies')
    .field('rating').greaterOrEquals('3.0')
var records_sample = sys.data.find(query_sample);
log('total: '+records_sample.count());
while (records_sample.hasNext()) {
    log(records_sample.next().label());
}

// finds companies with rating grater or equals than 3.0 
GET /data/contacts?rating=greaterOrEquals(3.0)

Aggregate queries #

Please refer to the Aggregate Queries Documentation for more detailed information.

Available operators #

UI queries #

Please refer to the UI Queries Documentation for more detailed information.

Matching of values #

Available operators #