Introduction to the TIMESTAMP_NTZ data type in MaxCompute - MaxCompute

TIMESTAMP_NTZ, MaxCompute V2.0 veri türü sürümünde saat dilimi bağımsız bir zaman damgası türüdür. Yazdığınız kesin "duvar saati" (wall-clock) değerini depolar ve oturum saat diliminden bağımsız olarak her zaman bu değeri değiştirilmeden döndürür. Bu özellik, herhangi bir saat dilimi dönüşümü gerektirmeden zaman karşılaştırmalarını ve aritmetik işlemlerini öngörülebilir hale getirir.

Çalışma biçimi

TIMESTAMP ve TIMESTAMP_NTZ veriyi farklı şekilde depolar:

	TIMESTAMP	TIMESTAMP_NTZ
Dahili depolama	Epoçtan (1970-01-01 00:00:00 UTC) UTC ofseti	Duvar saati zamanı, saat dilimi referansı yok
Görüntüleme davranışı	Geçerli oturum saat dilimine göre ayarlanır	Değeri her zaman yazıldığı gibi döndürür
Saat dilimi dönüşümü	Okuma sırasında gereklidir	Yoktur
SQL standardı	Hive 2 uyumlu	SQL:2003 / Hive 3 uyumlu

Örneğin, UTC+8'de 1970-01-01 00:00:00 olarak yazılan bir TIMESTAMP değeri, oturum UTC'ye geçtiğinde 1969-12-31 16:00:00 olarak görüntülenir. TIMESTAMP_NTZ olarak depolanan aynı girdi ise, oturum saat diliminden bağımsız olarak her zaman 1970-01-01 00:00:00 şeklinde görüntülenir.

Aşağıdaki örnek bu farkı göstermektedir. MaxCompute V2.0 veri türü sürümünü etkinleştirin ve saat dilimini UTC+8 olarak ayarlayın (MaxCompute projeleri için varsayılan değer):

-- Enable the MaxCompute V2.0 data type edition
SET odps.sql.type.system.odps2=true;
-- Confirm the current time zone (default: Asia/Shanghai, which is UTC+8)
setproject;
-- If your project time zone is not UTC+8, set it explicitly
SET odps.sql.timezone=Asia/Shanghai;

Her iki türü de içeren bir tablo oluşturun ve aynı zaman damgası değerini ekleyin:

-- Create a table with both types for comparison
CREATE TABLE ts_test02(a timestamp, b timestamp_ntz);
INSERT INTO TABLE ts_test02 VALUES(timestamp '1970-01-01 00:00:00', timestamp_ntz '1970-01-01 00:00:00');

-- Query results in UTC+8
SELECT * FROM ts_test02;

Çıktı:

+---------------------+---------------------+
| a                   | b                   |
+---------------------+---------------------+
| 1970-01-01 00:00:00 | 1970-01-01 00:00:00 |
+---------------------+---------------------+

Oturum saat dilimini UTC olarak değiştirin ve sorguyu yeniden çalıştırın:

SET odps.sql.timezone=UTC;
SELECT * FROM ts_test02;

Çıktı — a alanı (TIMESTAMP) 8 saat kayar; b alanı (TIMESTAMP_NTZ) değişmez:

+---------------------+---------------------+
| a                   | b                   |
+---------------------+---------------------+
| 1969-12-31 16:00:00 | 1970-01-01 00:00:00 |
+---------------------+---------------------+

Ön koşullar

Başlamadan önce şunlara sahip olduğunuzdan emin olun:

MaxCompute V2.0 veri türü sürümü etkinleştirilmiş olmalıdır (SET odps.sql.type.system.odps2=true)
(UDF örnekleri için) SQL ifadeleri komut dosyası modunda gönderilmelidir — bkz. SQL in script mode

Sınırlamalar

Hologres: TIMESTAMP_NTZ verilerini okuyamaz veya yazamaz.
Platform for AI (PAI): AlgoTask ve PS işleri TIMESTAMP_NTZ verilerini okuyamaz veya yazamaz.
MaxCompute istemcisi (odpscmd): Sürüm 0,46 veya üzeri gereklidir.

Tabloda TIMESTAMP_NTZ kullanımı

MaxCompute V2.0 veri türü sürümünü etkinleştirdikten sonra, CREATE TABLE ifadesinde sütun türü olarak timestamp_ntz kullanın:

SET odps.sql.type.system.odps2=true;
CREATE TABLE ts_test01(ts timestamp_ntz) lifecycle 1;
INSERT INTO TABLE ts_test01 VALUES(timestamp_ntz '1970-01-01 00:00:00');
SELECT * FROM ts_test01;

Çıktı:

+---------------------+
| ts                  |
+---------------------+
| 1970-01-01 00:00:00 |
+---------------------+

TIMESTAMP_NTZ değerleri oluşturma

Değişmezler (Literals)

Bir tarih-saat dizesinin önüne TIMESTAMP_NTZ anahtar sözcüğünü ekleyin:

-- Returns 2017-11-11 00:00:00.123456789
SELECT TIMESTAMP_NTZ '2017-11-11 00:00:00.123456789';

CAST ile tür dönüşümü

Diğer türleri TIMESTAMP_NTZ'ye dönüştürmek için CAST function kullanın. Tüm örnekler MaxCompute V2.0 veri türü sürümünü gerektirir.

Zaman türlerinden TIMESTAMP_NTZ'ye

SET odps.sql.type.system.odps2=true;
SELECT
  cast(date '1970-01-01' AS timestamp_ntz) AS date_cast_result,
  cast(datetime '1970-01-01 00:00:00' AS timestamp_ntz) AS datetime_cast_result,
  cast(timestamp '1970-01-01 00:00:00' AS timestamp_ntz) AS timestamp_cast_result;

Çıktı:

+---------------------+---------------------+-----------------------+
| date_cast_result    | datetime_cast_result | timestamp_cast_result |
+---------------------+---------------------+-----------------------+
| 1970-01-01 00:00:00 | 1970-01-01 00:00:00 | 1970-01-01 00:00:00   |
+---------------------+---------------------+-----------------------+

Sayısal türlerden TIMESTAMP_NTZ'ye

SET odps.sql.type.system.odps2=true;
SELECT
  cast(1L AS timestamp_ntz) AS bigint_cast_result,
  cast(1BD AS timestamp_ntz) AS decimal_cast_result,
  cast(1.5f AS timestamp_ntz) AS float_cast_result,
  cast(1.5 AS timestamp_ntz) AS double_cast_result;

Çıktı:

+---------------------+---------------------+-----------------------+---------------------+
| bigint_cast_result  | decimal_cast_result | float_cast_result     | double_cast_result  |
+---------------------+---------------------+-----------------------+---------------------+
| 1970-01-01 00:00:01 | 1970-01-01 00:00:01 | 1970-01-01 00:00:01.5 | 1970-01-01 00:00:01.5 |
+---------------------+---------------------+-----------------------+---------------------+

Dize türlerinden TIMESTAMP_NTZ'ye

SET odps.sql.type.system.odps2=true;
SELECT
  cast(s AS timestamp_ntz) AS string_cast_result,
  cast(cast(s AS char(50)) AS timestamp_ntz) AS char_cast_result,
  cast(cast(s AS varchar(100)) AS timestamp_ntz) AS varchar_cast_result
FROM VALUES('1970-01-01 00:00:01.2345') AS t(s);

Çıktı:

+--------------------------+--------------------------+------------------------------+
| string_cast_result       | char_cast_result         | varchar_cast_result          |
+--------------------------+--------------------------+------------------------------+
| 1970-01-01 00:00:01.2345 | 1970-01-01 00:00:01.2345 | 1970-01-01 00:00:01.2345     |
+--------------------------+--------------------------+------------------------------+

İşlev dönüş değerleri

FROM_UTC_TIMESTAMP, TO_UTC_TIMESTAMP ve CURRENT_TIMESTAMP işlevleri varsayılan olarak TIMESTAMP döndürür. Bunun yerine TIMESTAMP_NTZ döndürmelerini sağlamak için odps.sql.timestamp.function.ntz=true parametresini ayarlayın:

SET odps.sql.type.system.odps2=true;
SET odps.sql.timestamp.function.ntz=true;

SELECT
  current_timestamp() AS current_result,
  from_utc_timestamp(0L, 'UTC') AS from_result,
  to_utc_timestamp(0L, 'UTC') AS to_result;

Çıktı (current_result değeri, çalıştırma sırasındaki gerçek sistem saatini yansıtır):

+-------------------------+---------------------+---------------------+
| current_result          | from_result         | to_result           |
+-------------------------+---------------------+---------------------+
| 2023-07-01 21:22:39.066 | 1970-01-01 00:00:00 | 1970-01-01 00:00:00 |
+-------------------------+---------------------+---------------------+

Dönüş türlerini doğrulamak için sorguda EXPLAIN komutunu çalıştırın:

EXPLAIN SELECT current_timestamp() AS current_result, from_utc_timestamp(0L, 'UTC') AS from_result, to_utc_timestamp(0L, 'UTC') AS to_result;

Yürütme planı, üç çıkış alanının da timestamp_ntz olduğunu gösterir:

 FS: output: Screen
     schema:
       current_result (timestamp_ntz)
       from_result (timestamp_ntz)
       to_result (timestamp_ntz)

Desteklenen işlemler

İlişkisel operatörler

TIMESTAMP_NTZ tüm standart ilişkisel operatörleri destekler. Daha fazla bilgi için bkz. Operators.

SET odps.sql.type.system.odps2=true;

-- Equals (=), Not Equals (!=), and Eqns (<=>)
SELECT
  a = b AS eq_result,
  a != b AS neq_result,
  a <=> b AS eqns_result
FROM VALUES(timestamp_ntz '1970-01-01 00:00:00', timestamp_ntz '1970-01-01 00:00:00') AS t(a, b);
-- Output: true | false | true

-- GT (>), GE (>=), LT (<), LE (<=)
SELECT
  a > b AS gt_result,
  a >= b AS ge_result,
  a < b AS lt_result,
  a <= b AS le_result
FROM VALUES(timestamp_ntz '1970-01-01 00:00:00', timestamp_ntz '1970-01-01 00:00:00') AS t(a, b);
-- Output: false | true | false | true

Aritmetik işlemler

Daha fazla bilgi için bkz. Operators.

İki TIMESTAMP_NTZ değerini çıkarma — sonuç INTERVAL_DAY_TIME türündedir:

SET odps.sql.type.system.odps2=true;
SELECT timestamp_ntz '1970-01-01 00:01:30' - timestamp_ntz '1970-01-01 00:00:00';
-- Output: 0 00:01:30.000000000

INTERVAL_YEAR_MONTH ekleme veya çıkarma:

SET odps.sql.type.system.odps2=true;
SELECT a+b AS plus_result, a-b AS minus_result
FROM VALUES(timestamp_ntz '1970-01-01 00:00:00', interval '1' year) AS t(a, b);
-- Output: plus_result=1971-01-01 00:00:00  |  minus_result=1969-01-01 00:00:00

INTERVAL_DAY_TIME ekleme veya çıkarma:

SET odps.sql.type.system.odps2=true;
SELECT a+b AS plus_result, a-b AS minus_result
FROM VALUES(timestamp_ntz '1970-01-01 00:00:00', interval '1' day) AS t(a, b);
-- Output: plus_result=1970-01-02 00:00:00  |  minus_result=1969-12-31 00:00:00

Tarih ve saat işlevleri

Tarih ve saat işlevleri hem TIMESTAMP hem de TIMESTAMP_NTZ'yi girdi olarak kabul eder. Tam işlev referansı için bkz. Date functions.

SET odps.sql.type.system.odps2=true;

-- DATEADD: add 1 day to both types
SELECT dateadd(a, 1, 'dd') AS a_result, dateadd(b, 1, 'dd') AS b_result
FROM VALUES(timestamp '1970-01-01 00:00:00', timestamp_ntz '1970-01-01 00:00:00') t(a, b);
-- Output: a_result=1970-01-02 00:00:00  |  b_result=1970-01-02 00:00:00

-- MONTH: extract the month from both types
SELECT month(a) AS a_result, month(b) AS b_result
FROM VALUES(timestamp '1970-01-01 00:00:00', timestamp_ntz '1970-01-01 00:00:00') t(a, b);
-- Output: a_result=1  |  b_result=1

Toplama işlevleri

MAX ve MIN işlevleri TIMESTAMP_NTZ'yi destekler:

SET odps.sql.type.system.odps2=true;
SELECT max(a) AS max_result, min(a) AS min_result
FROM VALUES
  (timestamp_ntz '1970-01-01 00:00:00'),
  (timestamp_ntz '1970-01-01 01:00:00'),
  (timestamp_ntz '1970-01-01 02:00:00') AS t(a);

Çıktı:

+---------------------+---------------------+
| max_result          | min_result          |
+---------------------+---------------------+
| 1970-01-01 02:00:00 | 1970-01-01 00:00:00 |
+---------------------+---------------------+

Kullanıcı Tanımlı İşlevler (UDF'ler)

Java kullanıcı tanımlı işlevleri (UDF'ler), TIMESTAMP_NTZ girdi ve çıktı parametrelerini eşlemek için java.time.LocalDateTime kullanır.

Aşağıdakileri komut dosyası modlu bir SQL işi olarak gönderin. Daha fazla bilgi için bkz. Code-embedded UDFs ve SQL in script mode.

SET odps.sql.type.system.odps2=true;

-- Define a UDF that sets the millisecond component to 999
CREATE TEMPORARY FUNCTION foo_udf AS 'com.mypackage.Test' USING
#CODE ('lang'='JAVA')
package com.mypackage;
import com.aliyun.odps.udf.UDF;
public class Test extends UDF {
  public java.time.LocalDateTime evaluate(java.time.LocalDateTime ld) {
    if (ld == null) return null;
    java.time.LocalDateTime result = java.time.LocalDateTime.of(
        ld.getYear(), ld.getMonthValue(), ld.getDayOfMonth(),
        ld.getHour(), ld.getMinute(), ld.getSecond(), 999000000);
    return result;
  }
}
#END CODE;

-- Pass a TIMESTAMP_NTZ value to the UDF
SELECT foo_udf(a) FROM VALUES(timestamp_ntz '1970-01-01 00:00:00') AS t(a);

Çıktı:

+-------------------------+
| _c0                     |
+-------------------------+
| 1970-01-01 00:00:00.999 |
+-------------------------+

Sonraki adımlar

Time zones — MaxCompute'te desteklenen saat dilimleri
Date functions — tarih ve saat işlevleri için tam referans
Operators — ilişkisel operatör referansı
Operators — aritmetik operatör referansı
CAST function — tür dönüşümü referansı
Code-embedded UDFs — UDF oluşturma kılavuzu