> ## Documentation Index
> Fetch the complete documentation index at: https://docs.elementum.io/llms.txt
> Use this file to discover all available pages before exploring further.

# Date and Time Handling

> This guide explains how Elementum handles date and time values throughout the platform, particularly when integrating with external data sources.

<Warning>
  **Critical**: Elementum's platform **assumes all dates are in UTC (Coordinated Universal Time)**. Incorrect timezone handling can cause display inconsistencies across your platform.
</Warning>

## UTC Standard

Elementum's platform uses UTC as the foundation of our date/time handling strategy:

<CardGroup cols={3}>
  <Card title="Database Storage" icon="database">
    All timestamps stored in Elementum's databases are in UTC
  </Card>

  <Card title="API Communications" icon="code">
    All API communications use UTC for consistency
  </Card>

  <Card title="UI Display" icon="eye">
    UI displays convert UTC to the user's local timezone for presentation
  </Card>
</CardGroup>

## External Data Integration

When importing data from external sources like Snowflake:

### Requirements for Date/Time Fields

<Steps>
  <Step title="Use UTC Format">
    **All date/time values should be in UTC format**
  </Step>

  <Step title="Avoid Mixed Formats">
    Data imported with mixed timezone formats will cause display inconsistencies
  </Step>

  <Step title="Proper Conversion">
    Local timezone dates without proper UTC conversion will display incorrectly
  </Step>
</Steps>

### Common Issues

<Accordion title="Mixed Timezone Problems">
  The most frequent issue occurs when:

  * ❌ Some date fields contain UTC timestamps
  * ❌ Other date fields contain local timezone timestamps
  * ❌ All are treated as UTC by the platform
  * ❌ UI displays show incorrect times for users in different timezones

  **Example**: For a user in EDT (UTC-4):

  ```bash theme={null}
  # Correct behavior
  True UTC timestamp: 14:00 → Displays as: 10:00 ✓

  # Incorrect behavior  
  Local EDT timestamp: 14:00 → Displays as: 10:00 ✗
  # Should display as: 14:00
  ```
</Accordion>

## Best Practices

<CardGroup cols={1}>
  <Card title="1. Store All Timestamps in UTC" icon="clock">
    <div className="space-y-2">
      * Convert any local timestamps to UTC before importing
      * Include timezone offset information if available
    </div>
  </Card>

  <Card title="2. Standardize Date Formats" icon="calendar">
    <div className="space-y-2">
      * Use ISO 8601 format when possible (`YYYY-MM-DDTHH:MM:SSZ`)
      * Ensure consistency across all data sources
    </div>
  </Card>

  <Card title="3. Snowflake Configuration" icon="snowflake">
    <div className="space-y-2">
      * Configure all date columns to use UTC timezone
      * Convert any local timestamps during ETL processes
      * Don't mix UTC and local timezone values in the same dataset
    </div>
  </Card>
</CardGroup>

## Troubleshooting

<Tip>
  If dates appear incorrect in the Elementum UI, follow these steps:
</Tip>

<Steps>
  <Step title="Verify Original Data">
    Check the original timestamps in your data source (e.g., Snowflake)
  </Step>

  <Step title="Check Consistency">
    Verify that timestamps are consistently in UTC format
  </Step>

  <Step title="Convert Data">
    Convert any non-UTC timestamps to UTC in the data source
  </Step>

  <Step title="Re-import">
    Re-import the data after standardization
  </Step>
</Steps>