UNIXタイムスタンプの秒とミリ秒を見分ける方法

秒とミリ秒は何が違うか

UNIXタイムスタンプは、基準時刻である1970年1月1日00:00:00 UTCからの経過時間を数値で表します。ただし、データ交換で使われる単位は一つに統一されていません。秒単位なら 1700000000、ミリ秒単位なら 1700000000000 が同じ瞬間を表します。

現在に近い正の値では、秒が10桁前後、ミリ秒が13桁前後になることが多いため、桁数は便利な手掛かりです。しかし、古い日付、遠い将来、負の値、小数を含む秒、先頭ゼロを持つ文字列では桁数が変わります。桁数だけで単位を確定しないでください。

単位を判断する順序

最初に値の出所を確認します。API仕様、データベースの列定義、変数名の timestamp_ms、ライブラリのドキュメントなど、単位を明示する契約が最も強い根拠です。

契約が不明な場合は、次の順で候補を絞ります。

1. 元データの型と単位に関する説明を探します。
2. 値を秒として変換した結果と、ミリ秒として変換した結果を両方確認します。
3. 想定する業務期間と照合します。注文日時ならサービス開始前や数百年後の結果は通常不自然です。
4. 前後のレコードとの間隔を確認します。1秒ごとの記録が 1000 ずつ増えるなら、ミリ秒である可能性があります。
5. それでも決められなければ、推測で保存せずデータ提供元へ確認します。

12桁の値も、それだけで不正とは断定できません。秒としては遠い将来を、ミリ秒としては1970年代から2001年頃までを表し得ます。値が妥当かどうかは、桁数ではなく単位の契約と期待する期間で判断します。

1000倍と1000分の1の誤変換

秒をJavaScriptの Date へ渡す場合は1000倍してミリ秒へ変換します。すでにミリ秒の値をさらに1000倍すると、意図よりはるか未来になるか、扱える範囲を超えて無効な日付になります。反対に、秒の値をミリ秒としてそのまま渡すと1970年1月付近に寄ります。

const seconds = 1700000000;
const milliseconds = 1700000000000;

new Date(seconds * 1000).toISOString();
// expected: "2023-11-14T22:13:20.000Z"

new Date(milliseconds).toISOString();
// expected: "2023-11-14T22:13:20.000Z"

new Date(seconds).toISOString();
// wrong unit: "1970-01-20T16:13:20.000Z"

小数の秒を扱う場合、1700000000.123 * 1000 のようにJavaScriptでミリ秒へ変換できます。App Museumの変換アプリがtimestampとして自動判定する入力は整数なので、小数秒はこのコード例で確認してください。保存先が整数だけを受け付けるなら、丸め方を仕様として決める必要があります。

入力値を確認する手順

1. 値をコピーし、符号、小数点、先頭ゼロがないか確認します。
2. 入力が整数なら、UNIXタイムスタンプ変換アプリの結果を確認します。このアプリは桁数から単位を自動判定するため、表示された単位を事実ではなく候補として扱います。
3. 小数秒またはもう一方の単位で解釈した結果は、上のJavaScript例のように元の値をそのままミリ秒として渡す場合と、1000倍して渡す場合を比較します。
4. UTCの結果が期待する年月日と一致するか確認します。
5. ローカル表示が必要なら、UTCと混同せず別に確認します。
6. 正しい単位をコード、スキーマ、またはAPI仕様へ明記します。

App MuseumのUNIXタイムスタンプ変換アプリは、一般的な値を桁数から秒またはミリ秒として自動判定します。この判定は入力をすばやく確認するための手掛かりであり、12桁を含む境界的な値の単位を保証するものではありません。変換結果を出所の仕様と照合してください。

参考資料

• ECMAScript Language Specification: Time Values and Time Range
• The Open Group Base Specifications: Seconds Since the Epoch