Number

Generates numeric values, whole or fractional.

Use it for numeric columns such as a quantity, a price, a score, a running identifier or a measurement. mode sets how the values are distributed:

A counter that increases by a fixed amount on every row is Sequential.
Whole numbers spread evenly across a range, such as ages, is Whole.
Fractional numbers spread evenly across a range, such as prices, is Real.
Numbers from a fixed list, such as status codes, is Lookup.
Numbers concentrated around an average, such as body weights, is Clustered.

For a numeric code such as an account or order number, Identifier has more control over the format.

Sub-field: value

Every JSON block on this page is a single field object, one entry in a table's fields array. See Building a Request for the full request structure.

Properties

Property	Type	Default	Description
`includeNegative`	`boolean?`	`false`	Whether an unset `min` allows negative values. Has no effect when `min` is set. `Whole` and `Real` only. See Default range.
`lookupValues`	`LookupValue[]`	none	The numbers for `Lookup` mode. Required in that mode.
`map`	`object`	required	Maps the `value` sub-field to a destination column. See Building a Request and Column types.
`max`	`number?`	see Default range	Inclusive upper bound. `Whole`, `Real` and `Clustered` only.
`mean`	`number?`	none	The center of the distribution in `Clustered` mode. Required in that mode, and must be within `min` to `max`.
`min`	`number?`	see Default range	Inclusive lower bound. `Whole`, `Real` and `Clustered` only. Must not be greater than `max`.
`mode`	`"Whole"` / `"Real"` / `"Sequential"` / `"Lookup"` / `"Clustered"`	`"Whole"`	How values are generated. See Modes.
`nullPercentageMax`	`number`	`0`	Upper bound (0-100) of the percentage of rows that should be null. See `nullPercentageMin`.
`nullPercentageMin`	`number`	`0`	Lower bound (0-100) of the percentage of rows that should be null. The rate is fixed once for the whole field from this range, not recalculated per row. Set equal to `nullPercentageMax` for an exact rate. Has no effect in `Sequential` mode.
`percentInRange`	`number?`	none	Percentage (0-100) of rows generated from `percentMin` to `percentMax` instead of the full range. `Whole` and `Real` only, and rejected in any other mode. See Random within a narrower window.
`percentMax`	`number?`	none	Upper bound of the window `percentInRange` applies to. Required with `percentInRange`, and must be within `min` to `max`.
`percentMin`	`number?`	none	Lower bound of the window `percentInRange` applies to. Required with `percentInRange`, and must be within `min` to `max`.
`precision`	`integer?`	none	The total number of digits a value can have, before and after the decimal point, as in SQL `DECIMAL(precision, scale)`. Must be at least 1 and not less than `scale`. See Scale and precision.
`scale`	`integer?`	none	The number of digits after the decimal point. `Real` and `Clustered` values are rounded to it. Must be between 0 and 28. See Scale and precision.
`seed`	`integer`	random	Per-field seed, overriding the request's own `seed` for this field only.
`start`	`number?`	`1`	The first row's value. `Sequential` only.
`stdDev`	`number?`	none	The standard deviation of the distribution in `Clustered` mode. Required in that mode, and must be greater than 0.
`step`	`number?`	`1`	The amount added on each row in `Sequential` mode. `0` repeats `start`, and a negative value counts down.
`unique`	`boolean`	`false`	Whether every generated value must differ from the others. See Unique numbers.

Modes

Whole generates whole numbers from min to max, with every number equally likely. percentInRange concentrates a percentage of the rows in a narrower window.
Real generates fractional numbers from min to max, with every value equally likely. percentInRange concentrates a percentage of the rows in a narrower window. With scale or precision set, values are rounded. See Scale and precision.
Sequential increases by a fixed amount. The first row is start, and each row after it is step more. The values are not random, so the same request always produces the same numbers, with or without a seed.
Lookup selects from the numbers in lookupValues, optionally weighted. It never produces a number that is not in the list. See LookupValue.
Clustered generates a normal distribution around mean, with stdDev setting its width. See Clustered distribution.

Properties by mode

A property that applies only to another mode is ignored, except percentInRange, which is rejected outside Whole and Real.

Property	Whole	Real	Sequential	Lookup	Clustered
`min`, `max`	Yes	Yes			Yes
`includeNegative`	Yes	Yes
`percentInRange`, `percentMin`, `percentMax`	Yes	Yes
`start`, `step`			Yes
`lookupValues`				Yes
`mean`, `stdDev`					Yes
`scale`		Yes	Yes	Yes	Yes
`precision`	Yes	Yes	Yes	Yes	Yes
`nullPercentageMin`, `nullPercentageMax`	Yes	Yes		Yes	Yes

Sequential mode never produces nulls. Use another mode for a column with null values.

Each mode checks its own settings before any row is generated, so a missing mean or an empty lookupValues list is rejected immediately.

Default range

When min or max is not set in Whole or Real mode, the field uses a default:

An unset min is 0. With includeNegative set to true, it is the lowest value of the column type instead.
An unset max is the highest value of the column type.

For a whole-number column (Byte, Short, Integer or Long), the column type is the destination column's own type. For any other column, it is Long in Whole mode and the full range of a decimal number in Real mode.

In Clustered mode, an unset min or max does not limit the values, and includeNegative has no effect. A value can be any distance from mean, so a field with a positive mean can produce negative values.

A min, max, start or lookup value that a whole-number column cannot store is rejected.

Column types

value can be mapped to a number, Boolean or text column.

A whole-number column (Byte, Short, Integer or Long) receives whole numbers. A Real or Clustered value is rounded to the nearest whole number. A Sequential field that counts past what the column can store is rejected at the first row that does not fit.
A Decimal column needs a precision and a scale. They come from precision and scale when precision is set. Otherwise they are calculated from min and max in Whole mode, from min, max and scale in Real and Clustered modes, and from the values themselves in Lookup mode. A field that does not set enough to calculate them is rejected. A Sequential field mapped to a Decimal column must set precision.
A Double or Float column receives the value as it is generated.
A Boolean column receives false for zero and true for any other value.
A text column such as VarChar receives the number as text.

Scale and precision

scale and precision describe a SQL DECIMAL(precision, scale) column. scale is the number of digits after the decimal point, and precision is the total number of digits.

In Real and Clustered modes, setting either one rounds every value to scale decimal places. With precision set and scale not set, scale is 0, so the values are whole numbers. With neither set, values are not rounded.

precision sets an upper limit on the digits of every value:

A min, max or start with more digits before the decimal point than precision minus scale allows is rejected before any data is generated. So is an unset min or max whose default value is too large.
A lookup value with more digits than precision and scale allow is rejected before any data is generated. Lookup values are never rounded, so a value with more decimal places than scale is rejected too.
A generated value with more digits than precision allows is rejected when it is generated. This applies to a Clustered field with no min or max, and to a Sequential field that counts past the limit.

LookupValue

Lookup mode selects from a list of numbers. Each entry is an object with a value and an optional weight:

Property	Type	Default	Description
`value`	`number`	required	The number.
`weight`	`number`	`1`	The entry's weight relative to the other entries in the list. Must be greater than 0.

Weights are relative, not percentages, so they do not need to total any particular number. 3 and 1 give the same distribution as 30 and 10: the first entry is selected three times as often as the second. With no weights set, every entry is equally likely.

The list must contain at least one entry.

Weights that total 100 can be read as percentages. The number of items in a basket, mostly one:

{
  "type": "Number",
  "mode": "Lookup",
  "lookupValues": [
    { "value": 1, "weight": 60 },
    { "value": 2, "weight": 25 },
    { "value": 3, "weight": 10 },
    { "value": 10, "weight": 5 }
  ],
  "seed": 13,
  "map": { "value": { "column": "items_in_basket", "dataType": "Integer" } }
}

Sample output:

items_in_basket
1
2
3
1
1
3
2
10
1
1

Each row is selected separately, so the proportions are approximate.

The same kind of list with no weights:

{
  "type": "Number",
  "mode": "Lookup",
  "lookupValues": [
    { "value": 10 },
    { "value": 20 },
    { "value": 50 }
  ],
  "seed": 8,
  "map": { "value": { "column": "denomination", "dataType": "Integer" } }
}

Sample output:

denomination
50
10
20
10
50
20

Lookup values are written exactly as listed. scale and precision do not round them, and min and max do not limit them. The two decimal places in this example are from the values themselves, with no scale set:

{
  "type": "Number",
  "mode": "Lookup",
  "lookupValues": [
    { "value": 9.99 },
    { "value": 19.99, "weight": 3 },
    { "value": 49.99 }
  ],
  "seed": 2,
  "map": { "value": { "column": "price", "dataType": "Decimal" } }
}

Sample output:

price
19.99
19.99
9.99
49.99
9.99
19.99
49.99
19.99

Clustered distribution

How mean, stdDev, min and max affect the output. The curve is the number of rows with each value. Most values are near mean, and fewer are further away, at a rate set by stdDev. A value beyond min or max is set to that boundary, shown by the solid bar at each one.

mean sets the center and stdDev sets the width, both in the field's own units. About 68% of values are within one stdDev of mean, about 95% within two, and about 99.7% within three. A larger stdDev spreads the values further from mean, and a smaller one keeps them closer to it.

min and max are optional. Without them, a value can be any distance from mean within the range the field supports. With them, a value outside the range is set to the nearer of min or max. It is not generated again. The solid bars in the diagram are these values.

When the range is narrow relative to stdDev, many rows have a value of exactly min or max. In the diagram, the range is one and a half standard deviations either side of mean. To reduce the number of rows on the boundaries, widen the range or reduce stdDev.

For a Number field, mean and stdDev are in the same units as the value. With a mean of 3 and a stdDev of 1.5, about 95% of rows are from 0 to 6.

Order quantities around 3, with a min of 1 so that no quantity is zero or negative. min is less than one and a half standard deviations below mean, so many rows have a value of exactly 1:

{
  "type": "Number",
  "mode": "Clustered",
  "mean": 3,
  "stdDev": 1.5,
  "min": 1,
  "seed": 1,
  "map": { "value": { "column": "quantity", "dataType": "Integer" } }
}

Sample output:

quantity
4
1
4
3
2
3
3
1

A temperature around 5°C with no min or max. Any value more than 5 below mean is negative. That is 0.625 standard deviations, so about a quarter of the rows are negative:

{
  "type": "Number",
  "mode": "Clustered",
  "mean": 5,
  "stdDev": 8,
  "scale": 1,
  "precision": 4,
  "seed": 1,
  "map": { "value": { "column": "temperature_c", "dataType": "Decimal" } }
}

Sample output:

temperature_c
8.9
-3.9
9.8
2.4
2.1
6.9
4.5
-5

A Decimal value is written without trailing zeros, so -5.0 is written as -5.

Random within a narrower window

percentInRange generates a percentage of the rows of a Whole or Real field from a narrower window, and the rest from the full range. percentMin and percentMax set the window, which must be within min to max.

For each row, the field first selects either the window, with a probability of percentInRange, or the full range from min to max. It then generates a value from the selected range, with every value equally likely.

The rows generated from the full range can also be in the window, so the proportion of rows in the window is higher than percentInRange. The difference depends on the size of the window relative to the full range.

In Whole mode, only the whole numbers in a range are generated. A percentMin of 1.4 and a percentMax of 3.6 produce 2 and 3. A range or window that contains no whole number, such as 1.4 to 1.6, is rejected. In Real mode with scale or precision set, the same applies to the values at that number of decimal places.

Order quantities where most are from one to three, with some larger bulk orders:

{
  "type": "Number",
  "mode": "Whole",
  "min": 1,
  "max": 50,
  "percentInRange": 80,
  "percentMin": 1,
  "percentMax": 3,
  "seed": 10,
  "map": { "value": { "column": "quantity", "dataType": "Integer" } }
}

Sample output:

quantity
45
2
2
2
1
3
1
1
2
39
3
3

Ten of the twelve rows are in the window. Each row is selected separately, so a small sample does not match percentInRange exactly.

A price, mostly under $100 is the same technique in Real mode.

Unique numbers

With unique set, every row has a different value. A request for more rows than the field can produce is rejected before any data is generated, stating how many are available:

Mode	Distinct values available
`Whole`	The number of whole numbers from `min` to `max`.
`Real`	With `scale` or `precision` set, the number of values at that number of decimal places from `min` to `max`. On a whole-number column, the number of whole numbers from `min` to `max`. Otherwise there is no fixed limit.
`Clustered`	The same as `Real`, also counting `min` and `max` themselves.
`Sequential`	One per row, or only one when `step` is `0`.
`Lookup`	The number of different values in `lookupValues`.

In Clustered mode, values far from mean are rare. A unique request close to the limit can run out of distinct values during generation, even when the limit is not exceeded.

What is rejected

Each of the following is rejected before any rows are generated:

Request	Message
`min` greater than `max`	`min (50) must not be greater than max (10).`
A range with no whole number in `Whole` mode	`The range from min (1.4) to max (1.6) contains no whole number. Widen the range.`
`mean` outside `min` to `max`	`mean (500) must be between min (0) and max (10).`
`stdDev` missing, zero or negative	`Field in Clustered mode requires a positive stdDev.`
`percentInRange` in `Sequential`, `Lookup` or `Clustered`	`percentInRange has no effect on mode 'Sequential'. It only applies to Whole and Real.`
Only one of `percentMin` and `percentMax` set	`percentInRange requires both percentMin and percentMax to be set.`
`percentMin` below `min`	`percentMin (-5) must not be less than min (0).`
`scale` below 0	`scale must be between 0 and 28, but was -1.`
`precision` less than `scale`	`precision (2) must not be less than scale (4).`
`max` with more digits than `precision` allows	`max (1000) has 4 digits before the decimal point, but precision 5 with scale 2 allows 3. Raise precision, or set max to a value that fits.`
A value a whole-number column cannot store	`min (99999) does not fit column 'rating' (Short), which holds -32768 to 32767.`
A `Decimal` column with no way to size it	`Column 'price' is a decimal, so it needs a precision and a scale, and this field does not give enough to work them out. Set precision, or set scale together with min and max.`

Examples

Each example below is a single field object, one entry in a table's fields array within a full request, not a complete request on its own. See Building a Request for how it fits into a full DatasetRequest.

A sequential ID

{
  "type": "Number",
  "mode": "Sequential",
  "start": 1,
  "map": { "value": { "column": "id", "dataType": "Integer" } }
}

Sample output:

id
1
2
3
4
5
6

A price, mostly under $100

Two decimal places, with 90% of rows generated from 0 to 100 and the rest from 0 to 1000.

{
  "type": "Number",
  "mode": "Real",
  "min": 0,
  "max": 1000,
  "scale": 2,
  "percentInRange": 90,
  "percentMin": 0,
  "percentMax": 100,
  "map": { "value": { "column": "price", "dataType": "Decimal" } }
}

Sample output:

price
671.56
36.04
44.8
64.34
85.89
38.42
53.6
77.79

A weighted status code

{
  "type": "Number",
  "mode": "Lookup",
  "lookupValues": [
    { "value": 200, "weight": 90 },
    { "value": 404, "weight": 7 },
    { "value": 500, "weight": 3 }
  ],
  "seed": 15,
  "map": { "value": { "column": "status_code", "dataType": "Integer" } }
}

Sample output:

status_code
200
200
200
200
500
200
200
404
200
200

An age from 18 to 90

{
  "type": "Number",
  "mode": "Whole",
  "min": 18,
  "max": 90,
  "map": { "value": { "column": "age", "dataType": "Integer" } }
}

Sample output:

age
33
78
40
49
89
68

Weights clustered around a mean

Most values are near mean, and min and max limit the extremes.

{
  "type": "Number",
  "mode": "Clustered",
  "mean": 70,
  "stdDev": 12,
  "min": 40,
  "max": 120,
  "scale": 1,
  "map": { "value": { "column": "weight_kg", "dataType": "Double" } }
}

Sample output:

weight_kg
62.3
88.1
68
78.1
58.4
75.8

A sequence in steps of ten

{
  "type": "Number",
  "mode": "Sequential",
  "start": 10000,
  "step": 10,
  "map": { "value": { "column": "invoice_number", "dataType": "Long" } }
}

Sample output:

invoice_number
10000
10010
10020
10030
10040
10050

A descending sequence

A negative step counts down from start.

{
  "type": "Number",
  "mode": "Sequential",
  "start": 100,
  "step": -1,
  "map": { "value": { "column": "remaining", "dataType": "Integer" } }
}

Sample output:

remaining
100
99
98
97
96
95

A range that includes negative values

A min below zero allows negative values, so includeNegative is not needed.

{
  "type": "Number",
  "mode": "Real",
  "min": -500,
  "max": 2500,
  "scale": 2,
  "map": { "value": { "column": "balance", "dataType": "Decimal" } }
}

Sample output:

balance
2094.32
1323.2
-152.9
-294.12
2381.43
1205.24

A Decimal value is written without trailing zeros, so 1323.20 is written as 1323.2.

A value for a DECIMAL(5,2) column

precision and scale match the destination column. Every value has at most five digits, two of them after the decimal point.

{
  "type": "Number",
  "mode": "Real",
  "min": 0,
  "max": 999.99,
  "precision": 5,
  "scale": 2,
  "map": { "value": { "column": "unit_price", "dataType": "Decimal" } }
}

Sample output:

unit_price
418.65
38.46
467.07
339.13
516.97
713.79

A max of 1000 has four digits before the decimal point, one more than this precision and scale allow, and is rejected before any data is generated.

Unique employee numbers

{
  "type": "Number",
  "mode": "Whole",
  "min": 1000,
  "max": 9999,
  "unique": true,
  "map": { "value": { "column": "employee_number", "dataType": "Integer" } }
}

Sample output:

employee_number
3425
3254
3146
7956
9637
7507

The range contains 9,000 whole numbers, so a table of more than 9,000 rows is rejected before any data is generated.

Null rows

{
  "type": "Number",
  "mode": "Whole",
  "min": 1,
  "max": 5,
  "nullPercentageMin": 25,
  "nullPercentageMax": 25,
  "seed": 31,
  "map": { "value": { "column": "rating", "dataType": "Short" } }
}

Sample output:

rating
2

2
4

5
5
3

Table of Contents

Number

Properties

Modes

Properties by mode

Default range

Column types

Scale and precision

LookupValue

Clustered distribution

Random within a narrower window

Unique numbers

What is rejected

Examples

A sequential ID

A price, mostly under $100

A weighted status code

An age from 18 to 90

Weights clustered around a mean

A sequence in steps of ten

A descending sequence

A range that includes negative values

A value for a DECIMAL(5,2) column

Unique employee numbers

Null rows