log10

Use the `log10()` function to calculate the base-10 (common) logarithm of a numeric value.

## Syntax

```sql
log10(<number>)
```

## Parameters

| Name | Type | Required | Description |
| -------- | -------------- | -------- | ------------------------------------------------------------------------------------------------- |
| `number` | integer, float | Yes | The numeric value for which to calculate the base-10 logarithm. The value must be greater than 0. |

## Returns

**Type**: float

**Description**: The `log10()` function returns the base-10 logarithm of the input value. If the input is `null`, zero, or negative, the function returns `null` or `NaN`.

## Usage notes

* **Input type**: XQL doesn't support NaN or infinite values as input and these value types also can not be returned.
* **Valid Input Range**: The input `number` must be strictly greater than 0. The base-10 logarithm is undefined for zero and negative numbers.
* **Zero Input**: `log10(0)` returns negative infinity or `null`.
* **Negative Input**: `log10(x)` for `x < 0` returns `NaN` or `null`.
* **Null Handling**: If the input expression is `null`, the function returns `null`.
* **Key Values**: `log10(1)` returns `0.0`, `log10(10)` returns `1.0`, `log10(100)` returns `2.0`, `log10(1000)` returns `3.0`.
* **Relationship**: `log10(x)` is equivalent to `log(x, 10)`.
* **Common Use Cases**: This function is typically used within the `alter` stage for decibel calculations, order-of-magnitude analysis, pH calculations, and logarithmic scaling of data.

## Examples

### Example 1: Calculate base-10 logarithm of literal values

**Goal**: Calculate the base-10 logarithm for specific numeric literals to verify known mathematical results.

**XQL code**:

```sql
dataset = xdr_data
| limit 1
| alter result1 = log10(1), result2 = log10(100), result3 = log10(1000)
| fields result1, result2, result3
```

**Explanation**: `log10(1)` returns `0.0`, `log10(100)` returns `2.0` (since 10^2 = 100), and `log10(1000)` returns `3.0` (since 10^3 = 1000).

**Output**:

| RESULT1 | RESULT2 | RESULT3 |
| ------- | ------- | ------- |
| 0.0 | 2.0 | 3.0 |

### Example 2: Calculate base-10 logarithm from a field value

**Goal**: Calculate the base-10 logarithm of values stored in a dataset field to determine their order of magnitude.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| filter numeric_value > 0
| alter log10_result = log10(numeric_value)
| alter order_of_magnitude = floor(log10_result)
| fields event_id, numeric_value, log10_result, order_of_magnitude
| limit 3
```

**Explanation**: This query computes the base-10 logarithm for each positive value in `numeric_value`, then uses `floor()` to determine the order of magnitude. For example, a value of 500 has `log10` ≈ 2.699, so its order of magnitude is 2 (hundreds).

**Output**:

| EVENT\_ID | NUMERIC\_VALUE | LOG10\_RESULT | ORDER\_OF\_MAGNITUDE |
| --------- | -------------- | ------------- | -------------------- |
| 101 | 5.0 | 0.69897 | 0 |
| 102 | 500.0 | 2.69897 | 2 |
| 103 | 10000.0 | 4.0 | 4 |

### Example 3: Use log10 for decibel calculation

**Goal**: Calculate a decibel-like ratio using the base-10 logarithm.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| filter numeric_value > 0 and duration_seconds > 0
| alter ratio = divide(numeric_value, duration_seconds)
| alter decibel_ratio = multiply(10, log10(ratio))
| fields event_id, numeric_value, duration_seconds, ratio, decibel_ratio
| limit 3
```

**Explanation**: This query calculates a decibel-like ratio using the formula `10 * log10(ratio)`, which is a common pattern in signal processing and audio engineering.

**Output**:

| EVENT\_ID | NUMERIC\_VALUE | DURATION\_SECONDS | RATIO | DECIBEL\_RATIO |
| --------- | -------------- | ----------------- | ----- | -------------- |
| 101 | 100.0 | 1.0 | 100.0 | 20.0 |
| 102 | 50.0 | 5.0 | 10.0 | 10.0 |
| 103 | 1000.0 | 10.0 | 100.0 | 20.0 |

## Related articles

* **Stages**: [`alter`](../stages/alter), [`filter`](../stages/filter), [`fields`](../stages/fields), [`limit`](../stages/limit)
* **Functions**: [`ln()`](ln), [`log()`](log), [`exp()`](exp), [`floor()`](floor)
* **Datasets**: [`xdr_data`](https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction)