array_length

Use the `array_length()` function to return the number of elements in an array.

## Syntax

```sql
array_length (<array>)
```

## Parameters

| Name | Type | Required | Description |
| ------- | ----- | -------- | ------------------------------------- |
| `array` | array | Yes | The array field you want to evaluate. |

## Returns

The `array_length()` function returns an integer representing the count of elements in the specified array.

## Usage notes

* If the input array is empty, the function returns `0`.
* The function provides a direct count of how many items are present within an array field.
* This function is typically used within the `alter` stage to create new fields or modify existing ones by calculating array sizes.
* The function can also be used in `filter` stages to narrow down results based on string length.

## Examples

### Example 1: Calculating the length of a string array

**Goal**: Determine the number of string elements in an array field.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter num_string_tags = array_length(string_tags) 
| fields event_id, string_tags, num_string_tags 
| limit 4
```

**Explanation**: For `event_id` 101, 102, and 103, `string_tags` contains two elements, so `num_string_tags` is 2. For `event_id` 104, `string_tags` contains one element, so `num_string_tags` is 1.

**Output**:

| EVENT\_ID | STRING\_TAGS | NUM\_STRING\_TAGS |
| --------- | --------------------------- | ----------------- |
| 101 | \["security", "login"] | 2 |
| 102 | \["filesystem", "critical"] | 2 |
| 103 | \["network", "cloud"] | 2 |
| 104 | \["monitoring"] | 1 |

### Example 2: Calculating the length of a numeric array

**Goal**: Determine the number of numeric elements in an array field.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter num_numeric_codes = array_length(numeric_codes) 
| fields event_id, numeric_codes, num_numeric_codes 
| limit 6
```

**Explanation**: For `event_id` 101, 102, and 105, `numeric_codes` contains five elements. For `event_id` 103 and 106, `numeric_codes` contains six elements. For `event_id` 104, `numeric_codes` is an empty array, so `num_numeric_codes` is 0.

**Output**:

| EVENT\_ID | NUMERIC\_CODES | NUM\_NUMERIC\_CODES |
| --------- | --------------------------- | ------------------- |
| 101 | \[13, -47, 29, 82, -15] | 5 |
| 102 | \[-21, 56, 13, -88, 42] | 5 |
| 103 | \[90, -33, 7, 51, -62, 18] | 6 |
| 104 | \[] | 0 |
| 105 | \[77, -9, 35, -47, 61] | 5 |
| 106 | \[-12, 24, 68, -59, 37, 80] | 6 |

### Example 3: Calculating the length of an array of JSON objects

**Goal**: Determine the number of JSON objects contained within an array field.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter num_json_objects = array_length(array_of_json_objects) 
| fields event_id, array_of_json_objects, num_json_objects 
| limit 4
```

**Explanation**: For `event_id` 101 and 103, `array_of_json_objects` contains two elements. For `event_id` 102, `array_of_json_objects` contains one element. For `event_id` 104, `array_of_json_objects` is an empty array, so `num_json_objects` is 0.

**Output**:

| EVENT\_ID | ARRAY\_OF\_JSON\_OBJECTS | NUM\_JSON\_OBJECTS |
| --------- | ------------------------------------------------------------------------------------- | ------------------ |
| 101 | \[{"action": "read", "file": "doc1.txt"}, {"action": "write", "file": "report.log"}] | 2 |
| 102 | \[{"event": "file\_open", "path": "/etc/passwd"}] | 1 |
| 103 | \[{"conn\_type": "outbound", "bytes": 1024}, {"conn\_type": "inbound", "bytes": 512}] | 2 |
| 104 | \[] | 0 |

### Example 4: Using array\_length() in a filter to check for non-empty arrays

**Goal**: Filter events to include only those where a specific array field is not empty.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw
| alter tags_count = array_length(string_tags)
| filter tags_count > 0
| fields event_id, string_tags, tags_count 
| limit 5
```

**Explanation**: This query returns all events where the `string_tags` array has at least one element. No events with an empty `string_tags` array are present in this filtered result set.

**Output**:

| EVENT\_ID | STRING\_TAGS | TAGS\_COUNT |
| --------- | --------------------------- | ----------- |
| 101 | \["security", "login"] | 2 |
| 102 | \["filesystem", "critical"] | 2 |
| 103 | \["network", "cloud"] | 2 |
| 104 | \["monitoring"] | 1 |
| 105 | \["data\_ops"] | 1 |

### Example 5: Using array\_length() in a filter to check for a specific array size

**Goal**: Filter events to include only those where an array field contains a precise number of elements.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw
| alter codes_count = array_length(numeric_codes)
| filter codes_count = 5 
| fields event_id, numeric_codes, codes_count 
| limit 5
```

**Explanation**: Only events with exactly five elements in their `numeric_codes` array are returned, such as `event_id` 101, 102, and 105. Events like 103 (length 6) or 104 (length 0) are excluded by the filter.

**Output**:

| EVENT\_ID | NUMERIC\_CODES | CODES\_COUNT |
| --------- | ----------------------- | ------------ |
| 101 | \[13, -47, 29, 82, -15] | 5 |
| 102 | \[-21, 56, 13, -88, 42] | 5 |
| 105 | \[77, -9, 35, -47, 61] | 5 |

## Related articles

* **Stages**: [`alter`](../stages/alter), [`filter`](../stages/filter), [`fields`](../stages/fields)
* **Functions**: [`array_all`](array_all), [`array_any`](array_any)