Unix timestamp: seconds, ms, µs or ns
4 types, told apart by digit count: 10, 13, 16 and 19.
The types
| Type | Unit | Digits | Pattern | DuckDB transform | Sample |
|---|---|---|---|---|---|
| Unix Timestamp (seconds) | Seconds | 10 | ^\d{10}$ | to_timestamp({col}::BIGINT) | 1705312200 |
| Unix Timestamp (milliseconds) | Milliseconds | 13 | ^\d{13}$ | to_timestamp({col}::BIGINT / 1000) | 1705312200000 |
| Unix Timestamp (microseconds) | Microseconds | 16 | ^\d{16}$ | to_timestamp({col}::BIGINT / 1000000) | 1705312200000000 |
| Unix Epoch Nanoseconds | Nanoseconds | 19 | ^\d{19}$ | make_timestamp_ns({col}::BIGINT) | 1705325400000000000 |
Read in each unit
Each type's first registry sample, decoded in every unit. The bold reading is the type's own.
| Sample | Seconds | Milliseconds | Microseconds | Nanoseconds |
|---|---|---|---|---|
Unix Timestamp (seconds) 1705312200 | 2024-01-15 09:50:00 UTC (this type's unit) | 1970-01-20 17:41:52.2 UTC | 1970-01-01 00:28:25.3122 UTC | 1970-01-01 00:00:01.7053122 UTC |
Unix Timestamp (milliseconds) 1705312200000 | after 9999 | 2024-01-15 09:50:00 UTC (this type's unit) | 1970-01-20 17:41:52.2 UTC | 1970-01-01 00:28:25.3122 UTC |
Unix Timestamp (microseconds) 1705312200000000 | after 9999 | after 9999 | 2024-01-15 09:50:00 UTC (this type's unit) | 1970-01-20 17:41:52.2 UTC |
Unix Epoch Nanoseconds 1705325400000000000 | after 9999 | after 9999 | after 9999 | 2024-01-15 13:30:00 UTC (this type's unit) |
How finetype tells them apart
From finetype 0.6.66's source.
finetype's datetime format reader reads a 10-digit integer as Unix seconds, a 13-digit integer as milliseconds, a 16-digit integer as microseconds and a 19-digit integer as nanoseconds.[1] The reader picks a format only when at least 95% of the column's sampled non-null values match it.[2][3] For these four formats the reader checks the digit count alone, not the date a value would decode to.[1][4]
finetype's source describes a bare 10-digit integer as possibly an epoch, an identifier or a phone number, so it applies an epoch reading only when its model has already given the column a datetime type.[5][6] finetype applies that reading only when at least 90% of the column's non-empty sampled values pass the chosen type's own validation rule.[7][8]
Column names such as epoch, unix timestamp, epoch time and posix time point finetype to seconds, and epoch ms, unix ms and epoch milliseconds point it to milliseconds.[9] A column name that no earlier header rule claims and that contains epoch or unix points to milliseconds when it also contains ms or milli, and to seconds when it does not.[10] finetype declines a seconds or milliseconds hint from a column name when there are at least three non-empty values and 10% or fewer of them pass that type's validation rule.[11][12]
Where the digit count and the column name disagree, decode a few values and check the dates against something you already know about the data. (Meridian's view)
What finetype's evaluation shows
The evaluation report in finetype's repository at release 0.6.66 measured release 0.6.60 on 2026-09-23.[13] The report says its tables are generated by a separate tool that has drifted from the SQL harness it claims to mirror, and that a figure taken from it for publication must be its SQL headline.[14] Until finetype publishes a measurement for each type, this page gives no figure for how often it mistakes one unit for another. (Meridian's view)
Who writes each unit
Seconds
Python's time.time() returns the time in seconds since the epoch as a floating-point number.[15] RFC 7519 defines the JSON Web Token NumericDate as a JSON numeric value representing the number of seconds from 1970-01-01T00:00:00Z UTC, ignoring leap seconds.[16] Stripe's API reference describes the created attribute of a Charge as measured in seconds since the Unix epoch.[17]
Milliseconds
JavaScript's Date.now() returns the number of milliseconds elapsed since the epoch.[18] Elasticsearch stores dates internally as a long number representing milliseconds since the epoch.[19] Binance's spot REST API documentation states that all time and timestamp related fields in its JSON responses are in milliseconds by default.[20]
Microseconds
The Zipkin API specification describes a span's timestamp as epoch microseconds of the start of the span.[21] BigQuery's UNIX_MICROS function returns the number of microseconds since 1970-01-01 00:00:00 UTC.[22]
Nanoseconds
Go's time package documents UnixNano as returning a time as the number of nanoseconds elapsed since January 1, 1970 UTC.[23] OpenTelemetry's Metrics Data Model records the time a value was sampled in a field called time_unix_nano.[24] pandas converts integer epoch times with to_datetime, and its default unit is nanoseconds.[25]
Sources
- [1]finetype 0.6.66, datetime_format.rsFineType
- [2]finetype 0.6.66, datetime_format.rsFineType
- [3]finetype 0.6.66, datetime_format.rsFineType
- [4]finetype 0.6.66, datetime_format.rsFineType
- [5]finetype 0.6.66, datetime_format.rsFineType
- [6]finetype 0.6.66, column/mod.rsFineType
- [7]finetype 0.6.66, column/mod.rsFineType
- [8]finetype 0.6.66, column/mod.rsFineType
- [9]finetype 0.6.66, header_sharpen.rsFineType
- [10]finetype 0.6.66, header_sharpen.rsFineType
- [11]finetype 0.6.66, column/mod.rsFineType
- [12]finetype 0.6.66, column/mod.rsFineType
- [13]finetype evaluation report (release 0.6.60)FineType
- [14]finetype evaluation report (release 0.6.60)FineType
- [15]time — Time access and conversionsdocumentation
- [16]RFC 7519: JSON Web Token (JWT)standard
- [17]The Charge objectorganisation
- [18]Date.now() - JavaScript | MDNdocumentation
- [19]Date field typedocumentation
- [20]General REST API Information | Binance Developer Docsorganisation
- [21]zipkin-api/zipkin2-api.yaml at master · openzipkin/zipkin-api · GitHubdocumentation
- [22]Timestamp functions | BigQuery | Google Cloud Documentationdocumentation
- [23]time package - time - Go Packagesdocumentation
- [24]Metrics Data Modeldocumentation
- [25]Time series / date functionalitydocumentation