divide

Use the `divide()` function to perform arithmetic division, calculating the quotient of two numbers.

## Syntax

```sql
divide (<string> | <integer> | <float>, <string> | <integer> | <float>)
```

## Parameters

| Name | Type | Required | Description |
| ------------- | ---------------------- | -------- | -------------------------------------------- |
| `numerator` | integer, float, string | Yes | The number to be divided (the dividend). |
| `denominator` | integer, float, string | Yes | The number by which to divide (the divisor). |

## Returns

The `divide()` function returns the numerical quotient of the two input parameters.

## Usage notes

* The function accepts numeric literals (integers, floating-point numbers) or field values that represent numbers.
* The function supports input values provided as a string data type (for example, an integer stored as a string).
* The function can handle negative numbers.
* This function is typically used within the `alter` stage to create or modify fields.

## Examples

### Example 1: Dividing an integer field by an integer literal

**Goal**: Calculate a new field by dividing an existing integer field (`event_id`) by a fixed integer value.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter divided_event_id = divide(event_id, 2)
| fields event_id, divided_event_id 
| limit 3 

```

**Explanation**: This query calculates a new field, `divided_event_id`, by dividing each `event_id` (an integer) by 2.

**Output**:

| event\_id | divided\_event\_id |
| --------- | ------------------ |
| 101 | 50.5 |
| 102 | 51.0 |
| 103 | 51.5 |

### Example 2: Dividing a floating-point field by an integer literal

**Goal**: Calculate a new field by dividing a floating-point field (`duration_seconds`) by an integer literal.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter divided_duration = divide(duration_seconds, 5)
| fields event_id, duration_seconds, divided_duration 
| limit 3 

```

**Explanation**: This query divides `duration_seconds` (which contains decimal values) by 5, producing a new floating-point value in `divided_duration`.

**Output**:

| event\_id | duration\_seconds | divided\_duration |
| --------- | ----------------- | ----------------- |
| 101 | 1.5 | 0.3 |
| 102 | 0.8 | 0.16 |
| 103 | 10.2 | 2.04 |

### Example 3: Dividing a floating-point field by a floating-point literal

**Goal**: Divide a floating-point number field by a decimal literal.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter precise_division = divide(duration_seconds, 0.25)
| fields event_id, duration_seconds, precise_division 
| limit 3 

```

**Explanation**: This query divides `duration_seconds` by 0.25, resulting in `precise_division` which will also be a floating-point number.

**Output**:

| event\_id | duration\_seconds | precise\_division |
| --------- | ----------------- | ----------------- |
| 101 | 1.5 | 6.0 |
| 102 | 0.8 | 3.2 |
| 103 | 10.2 | 40.8 |

### Example 4: Dividing a numeric literal by a negative literal

**Goal**: Perform division using a negative literal value.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter negative_literal_division = divide(100, -4)
| fields event_id, negative_literal_division 
| limit 3 

```

**Explanation**: This query divides the positive literal 100 by the negative literal -4, producing a constant -25.0 for the `negative_literal_division` field across all records.

**Output**:

| event\_id | negative\_literal\_division |
| --------- | --------------------------- |
| 101 | -25.0 |
| 102 | -25.0 |
| 103 | -25.0 |

### Example 5: Dividing a string-converted-to-number field

**Goal**: Divide a numeric value that was extracted as a string from a JSON field and converted to a number.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| filter simple_json_data != null 
| alter json_code_string = simple_json_data -> code 
| alter json_code_number = to_number(json_code_string) 
| alter divided_json_code = divide(json_code_number, 100) 
| fields event_id, simple_json_data, json_code_number, divided_json_code 
| limit 3 

```

**Explanation**: The query extracts the `code` "200" as a string, converts it to a number, and then divides it by 100, resulting in `divided_json_code` of 2.0. Records where the field is null will result in NULL.

**Output**:

| event\_id | simple\_json\_data | json\_code\_number | divided\_json\_code |
| --------- | ------------------------------------------------- | ------------------ | ------------------- |
| 101 | {"status": "ok", "code": 200} | 200 | 2.0 |
| 102 | {"status": "fail", "error": "access\_denied"} | NULL | NULL |
| 103 | {"connection\_id": "CONN-001", "protocol": "TCP"} | NULL | NULL |

## Related articles

* **Stages**: [`alter`](../stages/alter), [`config`](../stages/config), [`limit`](../stages/limit)
* **Functions**: [`add`](add), [`multiply`](multiply), [`subtract`](subtract), [`to_number`](to_number)