Number literal

CQL supports both whole and real numbers, which include integers and numbers with a fractional part. In most cases, you do not need to worry about selecting the appropriate type, as CQL automatically chooses the most suitable one.

Integers

Integers are whole numbers, either positive or negative, that have no fractional part. To express an integer literal, simply write the number without a decimal point:

42

For those familiar with the technical terminology, the underlying type is a 64-bit signed integer. This means that the highest value allowed is 9223372036854775807, while the lowest is -9223372036854775808. Specifying a value outside this range will result in an error.

Real numbers

Real numbers consist of integers and numbers with a fractional part. These are commonly used to represent continuous values, such as lengths, weights, and other quantities.

CQL supports two types of real numbers: decimals, which have maximum precision, and floats, which are approximate.

Both decimal and float literals support exponential notation. This allows you to represent very large or very small numbers in a more compact way.

Let's take a look at each of these types in more detail.

Decimals

Decimal is the type used to represent fractional numbers in CQL. Because they are precise, they avoid many pitfalls of floating-point arithmetic.

Unlike integers, decimal numbers do not have a maximum or minimum value. However, they do have a maximum precision of 28 digits. Precision refers to the number of significant digits in the number, excluding any leading zeros.

For example, the number 123.456 has 6 significant digits, 0.02001 has 4, and 0.000001 has only 1.

To write a decimal literal, simply write the number with a decimal point, followed by the digits of the fractional part:

3.14

You can also represent a whole number as a decimal by adding a .0 to the end:

42.0

And you can use exponential notation to represent very large numbers:

3.0e2 // 300.0

Or very small numbers:

1.5e-3 // 0.0015

For fractions, you can skip the whole part and start with the decimal:

.5 // This is equivalent to 0.5

Keep in mind that although decimals are suitable for most use cases, they might not be the best choice for representing approximate values such as measurements, scores, or ratings. For these cases, consider using floats instead.

Floats

Floats are commonly used to represent continuous values that do not need to be precise. They are approximate real numbers that trade accuracy for the speed of computational operations.

Use floats when you need to represent approximate values, such as geo-coordinates, ratios, or probabilities.

To specify a float literal, add the f suffix to the number:

3.14f

You can also use exponential notation to represent very large numbers:

3.0e2f // 300.0f

Or very small numbers:

1.5e-3f // 0.0015f

For fractions, you can skip the whole part and start with the decimal:

.5f // This is equivalent to 0.5f

The underlying float type is a 64-bit floating-point number, equivalent to the double type in other languages. It can only accurately represent integers in the range -9007199254740991 to 9007199254740991 and a subset of decimal numbers.

As mentioned earlier, floats are approximate and may not always yield the expected results. If you need to perform precise calculations, consider using decimals instead.

Ordinals

Ordinals are a convenient and more natural alternative to using numerical indices, which are zero-based and sometimes confusing.

In English, you add the suffixes st, nd, rd, and th to indicate position, as in 1st, 2nd, 3rd, and 4th. This is exactly how you use ordinals in CQL.

Can I use ordinals everywhere?

You can use ordinals only where explicitly indicated in the documentation. Attempting to use them in other situations will result in a syntax error.

One of the primary use cases of ordinals in CQL is when accessing items from collections. For example, the following expression returns the first item the user added to their cart:

cart.items[1st]

In some instances, you can also express ordinal numbers using words such as first, second, third, through twelfth to indicate a position. Yet, not all places where you can use ordinals support the word form, so check the relevant documentation for specific cases.

For a practical use case of ordinals, see the Ordinal selector documentation.