Skip to main content

Convert Timestamp

Convert timestamps between different formats and timezones.

Overview​

The Convert Timestamp transformation allows you to parse timestamps in various formats and convert them to different output formats and timezones. This is essential for normalizing timestamp data from different sources or preparing data for systems that expect specific timestamp formats.

Automatic Format Detection: By default, the source timestamp format is automatically detected (source_format: "auto"), so you only need to specify the source field and the desired output format. This works for most common timestamp formats including Unix timestamps, ISO 8601, RFC 3339, and many others. You can also explicitly specify the source format if auto-detection doesn't work for your use case.

Supported Formats​

Standard Formats​

  • Auto (auto) - Automatically detect the format (source format only)
  • RFC 3339 (rfc3339) - 2006-01-02T15:04:05Z07:00
  • RFC 3339 Nano (rfc3339_nano) - 2006-01-02T15:04:05.999999999Z07:00
  • ISO 8601 (iso8601) - 2006-01-02T15:04:05.000Z
  • Unix (unix) - 1769619715 (seconds since epoch)
  • Unix Milli (unix_milli) - 1769619754507 (milliseconds since epoch)
  • Unix Nano (unix_nano) - 1769619754507123456 (nanoseconds since epoch)
  • RFC 1123 (rfc1123) - Mon, 02 Jan 2006 15:04:05 MST
  • RFC 1123 Z (rfc1123z) - Mon, 02 Jan 2006 15:04:05 -0700
  • ANSIC (ansic) - Mon Jan _2 15:04:05 2006
  • Date (date) - 2006-01-02
  • Time (time) - 15:04:05
  • DateTime (datetime) - 2006-01-02 15:04:05
  • Custom (custom) - Specify your own Go time layout string

Configuration​

ArgumentTypeRequiredDefaultDescription
source_keystringYes-The JSONPath to the source timestamp field in your record
source_formatstringYes"auto"The format of the source timestamp. Use "auto" to automatically detect the format (see supported formats above)
source_format_customstringNo-Custom Go time layout string (required only if source_format is "custom")
source_timezonestringNo"UTC"IANA timezone name for the source timestamp (e.g., "America/New_York", "Europe/London"). Defaults to UTC if not embedded in timestamp
target_keystringNo-The JSONPath where the converted timestamp will be stored. If empty, overwrites the source field (in-place conversion)
target_formatstringYes-The desired output format for the timestamp (see supported formats above)
target_format_customstringNo-Custom Go time layout string (required only if target_format is "custom")
target_timezonestringNo"UTC"IANA timezone name for the output timestamp (e.g., "America/New_York", "Europe/London")

Examples​

Example 1: Unix to RFC3339​

Convert a Unix timestamp to RFC3339 format.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "timestamp",
    "target_format": "rfc3339"
  }
}

Given the input record:

{
  "timestamp": 1609459200
}

The output record will be:

{
  "timestamp": "2021-01-01T00:00:00Z"
}

Example 2: RFC3339 to Unix with New Field​

Convert an RFC3339 timestamp to Unix format and store it in a new field.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "created_at",
    "target_key": "created_at_unix",
    "target_format": "unix"
  }
}

Given the input record:

{
  "created_at": "2021-01-01T00:00:00Z",
  "user_id": "12345"
}

The output record will be:

{
  "created_at": "2021-01-01T00:00:00Z",
  "user_id": "12345",
  "created_at_unix": 1609459200
}

Example 3: Timezone Conversion​

Convert a timestamp from UTC to America/New_York timezone.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "event_time",
    "source_timezone": "UTC",
    "target_key": "event_time_ny",
    "target_format": "rfc3339",
    "target_timezone": "America/New_York"
  }
}

Given the input record:

{
  "event_time": "2021-06-15T12:00:00Z"
}

The output record will be:

{
  "event_time": "2021-06-15T12:00:00Z",
  "event_time_ny": "2021-06-15T08:00:00-04:00"
}

Example 4: Unix Milliseconds to ISO8601​

Convert Unix milliseconds to ISO8601 format.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "log_timestamp",
    "target_format": "iso8601"
  }
}

Given the input record:

{
  "log_timestamp": 1609459200000
}

The output record will be:

{
  "log_timestamp": "2021-01-01T00:00:00.000Z"
}

Example 5: Extract Date Only​

Extract just the date portion from a full timestamp.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "timestamp",
    "target_key": "date",
    "target_format": "date"
  }
}

Given the input record:

{
  "timestamp": "2021-06-15T14:30:45Z"
}

The output record will be:

{
  "timestamp": "2021-06-15T14:30:45Z",
  "date": "2021-06-15"
}

Example 6: Custom Source Format​

Use a custom format string for parsing when auto-detection doesn't work.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "custom_time",
    "source_format": "custom",
    "source_format_custom": "02/01/2006 03:04 PM",
    "target_format": "rfc3339"
  }
}

Given the input record:

{
  "custom_time": "15/06/2021 02:30 PM"
}

The output record will be:

{
  "custom_time": "2021-06-15T14:30:00Z"
}

Example 7: Nested Field Path​

Convert a timestamp in a nested object.

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "event.metadata.timestamp",
    "target_key": "event.metadata.timestamp_formatted",
    "target_format": "rfc3339"
  }
}

Given the input record:

{
  "event": {
    "metadata": {
      "timestamp": 1609459200
    }
  }
}

The output record will be:

{
  "event": {
    "metadata": {
      "timestamp": 1609459200,
      "timestamp_formatted": "2021-01-01T00:00:00Z"
    }
  }
}

Common Use Cases​

Normalizing API Timestamps​

When integrating with multiple APIs that return timestamps in different formats:

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "api_timestamp",
    "target_format": "rfc3339"
  }
}

Preparing Data for Database Storage​

Convert timestamps to a format suitable for your database:

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "created_at",
    "target_format": "datetime"
  }
}

Handling Multi-Region Data​

Convert timestamps to local timezones for regional processing:

{
  "operation": "convert_timestamp",
  "arguments": {
    "source_key": "order_time",
    "source_timezone": "UTC",
    "target_key": "order_time_local",
    "target_format": "rfc3339",
    "target_timezone": "America/Los_Angeles"
  }
}

Notes​

  • Auto-detection: When source_format is set to "auto" (the default), the timestamp format is automatically detected from the first record. This works for most common formats including Unix timestamps (seconds, milliseconds, nanoseconds), ISO 8601, RFC 3339, and many others.
  • Unix format detection: Unix timestamps are detected by digit count: ≤11 digits = seconds, 12-14 digits = milliseconds, ≥15 digits = nanoseconds
  • Unix timestamps can be provided as either numeric values or string-encoded numbers
  • When target_key is omitted or empty, the transformation overwrites the source field (in-place conversion)
  • Timezone conversions preserve the actual moment in time while adjusting the representation
  • Use source_format: "custom" with source_format_custom when you need a specific Go time layout that isn't covered by the standard formats (see Go time package documentation)
  • Invalid timestamps or format mismatches will return an error and leave the record unchanged
  • Supported IANA timezone names can be found in the IANA Time Zone Database