> 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/parse_epoch.md).

# parse\_epoch

Use the `parse_epoch()` function to return a Unix epoch integer value by converting a string representation of a timestamp.

## Syntax

```sql
parse_epoch ("<format_string>", <timestamp field>)
parse_epoch ("<format_string>", <timestamp field>, "<time_zone>")
parse_epoch ("<format_string>", <timestamp field>, "<time_zone>", "<time_unit>")
```

## Parameters

| Name              | Type   | Required | Description                                                                                                                           |
| ----------------- | ------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `format_string`   | string | Yes      | Defines the layout of the input timestamp string (for example, `%Y-%m-%d %H:%M:%S`).                                                  |
| `timestamp_field` | string | Yes      | The string containing the timestamp to be parsed.                                                                                     |
| `time_zone`       | string | No       | An optional time zone specified by hours offset (for example, `+08:00`) or name (for example, `America/Chicago`). The default is UTC. |
| `time_unit`       | string | No       | Specifies the granularity of the returned integer (SECONDS, MILLIS, MICROS). The default is SECONDS.                                  |

## Returns

The `parse_epoch()` function returns a Unix epoch integer value.

## Usage notes

* The order of `time_zone` and `time unit` is important.
* If you're using the `time_zone` argument, you must define it immediately before the `time_unit` argument.
* If you use `time_zone` after `time_unit`, the default time zone (UTC) is used, and the configured value is ignored.
* To display the returned integer as a human-readable timestamp, it is typically passed to the `to_timestamp()` function.

## Examples

### Example 1: Without a time zone or time unit configured (implicit UTC, seconds)

**Goal**: Convert a timestamp string into an epoch integer using the default UTC time zone and SECONDS unit, then display it as a timestamp.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter new_time = to_timestamp(parse_epoch("%Y-%m-%d %H:%M:%S", "2023-10-26 10:00:00")) 
| fields event_id, new_time 
| limit 3 
```

**Explanation**: The input string "2023-10-26 10:00:00" is parsed using the format "%Y-%m-%d %H:%M:%S". Because no time zone is specified, `parse_epoch()` interprets it as a UTC timestamp. `to_timestamp()` then converts the resulting epoch seconds back to a TIMESTAMP object for display.

**Output**:

| EVENT\_ID | NEW\_TIME              |
| --------- | ---------------------- |
| 101       | Oct 26th 2023 10:00:00 |
| 102       | Oct 26th 2023 10:00:00 |
| 103       | Oct 26th 2023 10:00:00 |

### Example 2: With a time zone configured using an hours offset

**Goal**: Convert a timestamp string interpreting it relative to a +03:00 hours offset.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter new_time = to_timestamp(parse_epoch("%Y-%m-%d %H:%M:%S", "2023-10-26 10:00:00", "+03:00")) 
| fields event_id, new_time 
| limit 3 
```

**Explanation**: The input string 10:00:00 is interpreted as being in a +03:00 time zone. When converted to UTC (which epoch time is based on), it becomes 07:00:00 UTC. This UTC time is then returned as the TIMESTAMP object.

**Output**:

| EVENT\_ID | NEW\_TIME              |
| --------- | ---------------------- |
| 101       | Oct 26th 2023 07:00:00 |
| 102       | Oct 26th 2023 07:00:00 |
| 103       | Oct 26th 2023 07:00:00 |

### Example 3: With a time zone name configured

**Goal**: Convert a timestamp string interpreting it relative to the "America/Chicago" time zone.

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter new_time = to_timestamp(parse_epoch("%Y-%m-%d %H:%M:%S", "2023-10-26 10:00:00", "America/Chicago")) 
| fields event_id, new_time 
| limit 3 
```

**Explanation**: The input string 10:00:00 is interpreted as being in the "America/Chicago" time zone (UTC-5 for this date). To convert to UTC, 5 hours are added, resulting in 15:00:00 UTC.

**Output**:

| EVENT\_ID | NEW\_TIME              |
| --------- | ---------------------- |
| 101       | Oct 26th 2023 15:00:00 |
| 102       | Oct 26th 2023 15:00:00 |
| 103       | Oct 26th 2023 15:00:00 |

### Example 4: With both time zone and time unit configured

**Goal**: Convert a timestamp string using a +03:00 hours offset and explicitly return the epoch in MILLIS (milliseconds).

**XQL code**:

```sql
config timeframe = 1d 
| dataset = sample_xql_raw 
| alter new_time = to_timestamp(parse_epoch("%Y-%m-%d %H:%M:%S", "2023-10-26 10:00:00", "+03:00", "MILLIS"), "MILLIS") 
| fields event_id, new_time 
| limit 3 
```

**Explanation**: The input string is interpreted within the +03:00 time zone (converting 10:00:00 to 07:00:00 UTC). `parse_epoch()` generates the epoch value in milliseconds. This integer is then converted to a TIMESTAMP object using `to_timestamp()` with the "MILLIS" unit.

**Output**:

| EVENT\_ID | NEW\_TIME              |
| --------- | ---------------------- |
| 101       | Oct 26th 2023 07:00:00 |
| 102       | Oct 26th 2023 07:00:00 |
| 103       | Oct 26th 2023 07:00:00 |

## Related articles

* **Stages**: [`alter`](/xql-command-reference-guide/readme/stages/alter.md)
* **Functions**: [`to_timestamp`](/xql-command-reference-guide/readme/functions/to_timestamp.md)
* **Datasets**: [`xdr_data`](https://www.google.com/search?q=%5Bhttps://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction%5D\(https://docs-cortex.paloaltonetworks.com/r/Cortex-XQL-Schema-Reference-Guide/Introduction\))


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.