> For the complete documentation index, see [llms.txt](https://cortex-docs.paloaltonetworks.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/sign.md).

# sign

Use the `sign()` function to determine the sign of a numeric value. The function returns -1, 0, or 1 depending on whether the input is negative, zero, or positive.

## Syntax

```sql
sign(<number>)
```

## Parameters

| Name     | Type           | Required | Description                                       |
| -------- | -------------- | -------- | ------------------------------------------------- |
| `number` | integer, float | Yes      | The numeric value whose sign is to be determined. |

## Returns

**Type**: integer

**Description**: The `sign()` function returns `-1` if the input is negative, `0` if the input is zero, and `1` if the input is positive. If the input is `null`, the function returns `null`.

## 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 `sign()` function accepts any real number.
* **Null Handling**: If the input expression is `null`, the function returns `null`.
* **Return Values**: The function always returns one of three values: `-1`, `0`, or `1`.
* **NaN Handling**: If the input is `NaN`, the behavior depends on the implementation and may return `null` or `NaN`.
* **Common Use Cases**: This function is typically used within the `alter` stage for direction detection, trend analysis, conditional logic based on value polarity, and data classification.

## Examples

### Example 1: Determine sign of literal values

**Goal**: Determine the sign of specific numeric literals.

**XQL code**:

```sql
dataset = xdr_data
| limit 1
| alter sign_pos = sign(42), sign_neg = sign(-17), sign_zero = sign(0)
| fields sign_pos, sign_neg, sign_zero
```

**Explanation**: `sign(42)` returns `1` (positive), `sign(-17)` returns `-1` (negative), and `sign(0)` returns `0` (zero).

**Output**:

| SIGN\_POS | SIGN\_NEG | SIGN\_ZERO |
| --------- | --------- | ---------- |
| 1         | -1        | 0          |

### Example 2: Classify field values by sign

**Goal**: Classify values in a dataset field as positive, negative, or zero.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter value_sign = sign(numeric_value)
| alter classification = if(value_sign = 1, "positive", value_sign = -1, "negative", "zero")
| fields event_id, numeric_value, value_sign, classification
| limit 4
```

**Explanation**: This query determines the sign of each `numeric_value` and maps it to a human-readable classification label using `if()`.

**Output**:

| EVENT\_ID | NUMERIC\_VALUE | VALUE\_SIGN | CLASSIFICATION |
| --------- | -------------- | ----------- | -------------- |
| 101       | 5.0            | 1           | positive       |
| 102       | -200.0         | -1          | negative       |
| 103       | 0.0            | 0           | zero           |
| 104       | 50.0           | 1           | positive       |

### Example 3: Use sign for directional comparison

**Goal**: Determine the direction of change between two fields.

**XQL code**:

```sql
config timeframe = 1d
| dataset = sample_xql_raw
| alter change = subtract(numeric_value, duration_seconds)
| alter direction = sign(change)
| alter trend = if(direction = 1, "increasing", direction = -1, "decreasing", "unchanged")
| fields event_id, numeric_value, duration_seconds, change, trend
| limit 3
```

**Explanation**: This query calculates the difference between `numeric_value` and `duration_seconds`, then uses `sign()` to determine the direction of the change. The result is mapped to a trend label.

**Output**:

| EVENT\_ID | NUMERIC\_VALUE | DURATION\_SECONDS | CHANGE | TREND      |
| --------- | -------------- | ----------------- | ------ | ---------- |
| 101       | 5.0            | 1.5               | 3.5    | increasing |
| 102       | 0.8            | 200.0             | -199.2 | decreasing |
| 103       | 10.2           | 10.2              | 0.0    | unchanged  |

## Related articles

* **Stages**: [`alter`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/alter.md), [`fields`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/fields.md), [`limit`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/stages/limit.md)
* **Functions**: [`if`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/if.md), [`subtract`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/subtract.md), [`safe_negate`](https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/safe_negate.md)


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

```
GET https://cortex-docs.paloaltonetworks.com/xql-command-reference-guide/readme/functions/sign.md?ask=<question>&goal=<user_goal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.
