标量

Java API 标量接口为 Scalar，继承自 Entity 接口。

创建标量，就是将 Java 原生类型转换为 DolphinDB 中类型。一个标量就是一个单独的数据。

本节将介绍标量的创建、读取和更新方式及使用示例。

VOID

// VOID 类型不支持通过构造方法直接创建，一般由脚本运行返回
DBConnection conn = new DBConnection();
conn.connect("192.168.0.69", 8802, "admin", "123456");
Void voidValue = (Void) conn.run("NULL");
// 读取数据
voidValue.getString(); // ""
// 判空/设置为空
voidValue.isNull();    // true
// 获取数据类型/数据形式
voidValue.getDataType(); // DT_VOID;
voidValue.getDataCategory(); // NOTHING;

LOGICAL

BOOL

// 创建 boolean 类型标量
BasicBoolean basicBoolean = new BasicBoolean(true);

// 读取数据
basicBoolean.getString();    // "true"
basicBoolean.getBoolean();   // true

// 判空/设置为空
basicBoolean.isNull();       // false
basicBoolean.setNull();      // BasicBoolean 空值底层用 Byte.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicBoolean.getDataType();     // DT_BOOL
basicBoolean.getDataCategory(); // LOGICAL

INTEGRAL

CHAR

// 创建 char 类型标量
BasicByte basicByte = new BasicByte((byte) 'a');
// 读取数据
basicByte.getString(); // 'a'
basicByte.getByte();    // 97
// 判空/设置为空
basicByte.isNull();    // false
basicByte.setNull();     // BasicByte 空值底层用 Byte.MIN_VALUE 来表示
// 获取数据类型/数据形式
basicByte.getDataType(); // DT_BYTE;
basicByte.getDataCategory(); // INTEGRAL;

SHORT

// 创建 short 类型标量
BasicShort basicShort = new BasicShort((short) 21);
// 读取数据
basicShort.getString(); // 21
basicShort.getShort();    // 21
// 判空/设置为空
basicShort.isNull();    // false
basicShort.setNull();     // BasicShort 空值底层用 Short.MIN_VALUE 来表示
// 获取数据类型/数据形式
basicShort.getDataType(); // DT_SHORT;
basicShort.getDataCategory(); // INTEGRAL;

INT

// 创建 int 类型标量
BasicInt basicInt = new BasicInt(21);
// 读取数据
basicInt.getString(); // "21"
basicInt.getInt();    // 21
// 判空/设置为空
basicInt.isNull();    // false
basicInt.setNull();     // BasicInt 空值底层用 Integer.MIN_VALUE 来表示
// 获取数据类型/数据形式
basicInt.getDataType(); // DT_INT;
basicInt.getDataCategory(); // INTEGRAL;

LONG

// 创建 long 类型标量
BasicLong basicLong = new BasicLong(21L);
// 读取数据
basicLong.getString(); // "21"
basicLong.getLong();    // 21
// 判空/设置为空
basicLong.isNull();    // false
basicLong.setNull();     // BasicLong 空值底层用 Long.MIN_VALUE 来表示
// 获取数据类型/数据形式
basicLong.getDataType(); // DT_LONG;
basicLong.getDataCategory(); // INTEGRAL;

TEMPORAL

DATE

// 1）使用 LocalDate 创建 DATE 类型标量
BasicDate basicDate = new BasicDate(LocalDate.of(2023, 12, 25));
// 2）使用 Calendar 创建 date 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25);
BasicDate basicDate = new BasicDate(calendar);

// 读取数据
basicDate.getString();    // "2023.12.25"
basicDate.getDate();      // LocalDate对象: 2023-12-25

// 判空/设置为空
basicDate.isNull();       // false
basicDate.setNull();      // BasicDate 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicDate.getDataType();     // DT_DATE
basicDate.getDataCategory(); // TEMPORAL

MONTH

// 1）使用 Month 创建 MONTH 类型标量
BasicMonth basicMonth = new BasicMonth(2023, Month.DECEMBER);
// 2）使用 YearMonth 创建 MONTH 类型标量
BasicMonth basicMonth = new BasicMonth(YearMonth.of(2023, 12));
// 3）使用 Calendar 创建 MONTH 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 1);
BasicMonth basicMonth = new BasicMonth(calendar);

// 读取数据
basicMonth.getString();    // "2023.12M"
basicMonth.getMonth();     // YearMonth对象: 2023-12

// 判空/设置为空
basicMonth.isNull();       // false
basicMonth.setNull();      // BasicMonth 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicMonth.getDataType();     // DT_MONTH
basicMonth.getDataCategory(); // TEMPORAL

TIME

// 1）使用 LocalTime 创建 TIME 类型标量
BasicTime basicTime = new BasicTime(LocalTime.of(14, 30, 45, 123000000));
// 2）使用 Calendar 创建 TIME 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.HOUR_OF_DAY, 14);
calendar.set(Calendar.MINUTE, 30);
calendar.set(Calendar.SECOND, 45);
calendar.set(Calendar.MILLISECOND, 123);
BasicTime basicTime = new BasicTime(calendar);

// 读取数据
basicTime.getString();    // "14:30:45.123"
basicTime.getTime();      // LocalTime对象: 14:30:45.123

// 判空/设置为空
basicTime.isNull();       // false
basicTime.setNull();      // BasicTime 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicTime.getDataType();     // DT_TIME
basicTime.getDataCategory(); // TEMPORAL

MINUTE

// 1）使用 LocalTime 创建 MINUTE 类型标量
BasicMinute basicMinute = new BasicMinute(LocalTime.of(14, 30));
// 2）使用 Calendar 创建 MINUTE 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.HOUR_OF_DAY, 14);
calendar.set(Calendar.MINUTE, 30);
BasicMinute basicMinute = new BasicMinute(calendar);

// 读取数据
basicMinute.getString();    // "14:30m"
basicMinute.getMinute();    // LocalTime对象: 14:30

// 判空/设置为空
basicMinute.isNull();       // false
basicMinute.setNull();      // BasicMinute 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicMinute.getDataType();     // DT_MINUTE
basicMinute.getDataCategory(); // TEMPORAL

SECOND

// 1）使用 LocalTime 创建 SECOND 类型标量
BasicSecond basicSecond = new BasicSecond(LocalTime.of(14, 30, 45));
// 2）使用 Calendar 创建 SECOND 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.HOUR_OF_DAY, 14);
calendar.set(Calendar.MINUTE, 30);
calendar.set(Calendar.SECOND, 45);
BasicSecond basicSecond = new BasicSecond(calendar);

// 读取数据
basicSecond.getString();    // "14:30:45"
basicSecond.getSecond();    // LocalTime对象: 14:30:45

// 判空/设置为空
basicSecond.isNull();       // false
basicSecond.setNull();      // BasicSecond 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicSecond.getDataType();     // DT_SECOND
basicSecond.getDataCategory(); // TEMPORAL

DATETIME

// 1）使用 LocalDateTime 创建 DATETIME 类型标量
BasicDateTime basicDateTime = new BasicDateTime(LocalDateTime.of(2023, 12, 25, 14, 30, 45));
// 2）使用 Calendar 创建 DATETIME 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 30, 45);
BasicDateTime basicDateTime = new BasicDateTime(calendar);

// 读取数据
basicDateTime.getString();    // "2023.12.25T14:30:45"
basicDateTime.getDateTime();  // LocalDateTime对象: 2023-12-25T14:30:45

// 判空/设置为空
basicDateTime.isNull();       // false
basicDateTime.setNull();      // BasicDateTime 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicDateTime.getDataType();     // DT_DATETIME
basicDateTime.getDataCategory(); // TEMPORAL

TIMESTAMP

// 1）使用 LocalDateTime 创建 TIMESTAMP 类型标量
BasicTimestamp basicTimestamp = new BasicTimestamp(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123000000));
// 2）使用 Calendar 创建 TIMESTAMP 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 30, 45);
calendar.set(Calendar.MILLISECOND, 123);
BasicTimestamp basicTimestamp = new BasicTimestamp(calendar);

// 读取数据
basicTimestamp.getString();      // "2023.12.25T14:30:45.123"
basicTimestamp.getTimestamp();   // LocalDateTime对象: 2023-12-25T14:30:45.123

// 判空/设置为空
basicTimestamp.isNull();         // false
basicTimestamp.setNull();        // BasicTimestamp 空值底层用 Long.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicTimestamp.getDataType();     // DT_TIMESTAMP
basicTimestamp.getDataCategory(); // TEMPORAL

NANOTIME

// 1）使用 LocalTime 创建 NANOTIME 类型标量
BasicNanoTime basicNanoTime = new BasicNanoTime(LocalTime.of(14, 30, 45, 123456789));
// 2）使用 LocalDateTime 创建 NANOTIME 类型标量
BasicNanoTime basicNanoTimeFromDateTime = new BasicNanoTime(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123456789));

// 读取数据
basicNanoTime.getString();      // "14:30:45.123456789"
basicNanoTime.getNanoTime();    // LocalTime对象: 14:30:45.123456789

// 判空/设置为空
basicNanoTime.isNull();         // false
basicNanoTime.setNull();        // BasicNanoTime 空值底层用 Long.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicNanoTime.getDataType();     // DT_NANOTIME
basicNanoTime.getDataCategory(); // TEMPORAL

NANOTIMESTAMP

// 使用 LocalDateTime 创建 NANOTIMESTAMP 类型标量
BasicNanoTimestamp basicNanoTimestamp = new BasicNanoTimestamp(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123456789));

// 读取数据
basicNanoTimestamp.getString();         // "2023.12.25T14:30:45.123456789"
basicNanoTimestamp.getNanoTimestamp();  // LocalDateTime对象: 2023-12-25T14:30:45.123456789

// 判空/设置为空
basicNanoTimestamp.isNull();            // false
basicNanoTimestamp.setNull();           // BasicNanoTimestamp 空值底层用 Long.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicNanoTimestamp.getDataType();       // DT_NANOTIMESTAMP
basicNanoTimestamp.getDataCategory();   // TEMPORAL

DATEHOUR

// 1）使用 LocalDateTime 创建 DATEHOUR 类型标量
BasicDateHour basicDateHour = new BasicDateHour(LocalDateTime.of(2023, 12, 25, 14, 0, 0));

// 2）使用 Calendar 创建 DATEHOUR 类型标量
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 0, 0);
BasicDateHour basicDateHourFromCalendar = new BasicDateHour(calendar);

// 读取数据
basicDateHour.getString();      // "2023.12.25T14"
basicDateHour.getDateHour();    // LocalDateTime对象: 2023-12-25T14:00
basicDateHour.getInt();         // 小时数: 548774

// 判空/设置为空
basicDateHour.isNull();         // false
basicDateHour.setNull();        // BasicDateHour 空值底层用 Integer.MIN_VALUE 来表示

// 获取数据类型/数据形式
basicDateHour.getDataType();     // DT_DATEHOUR
basicDateHour.getDataCategory(); // TEMPORAL

FLOATING

FLOAT

// 创建 float 类型标量
BasicFloat basicFloat = new BasicFloat(3.14159f);

// 读取数据
basicFloat.getString();     // "3.14159"
basicFloat.getFloat();      // 3.14159f

// 判空/设置为空
basicFloat.isNull();        // false
basicFloat.setNull();       // BasicFloat 空值底层用 -Float.MAX_VALUE 来表示

// 获取数据类型/数据形式
basicFloat.getDataType();     // DT_FLOAT
basicFloat.getDataCategory(); // FLOATING

DOUBLE

// 创建 double 类型标量
BasicDouble basicDouble = new BasicDouble(3.141592653589793);

// 读取数据
basicDouble.getString();     // "3.14159265"
basicDouble.getDouble();     // 3.141592653589793

// 判空/设置为空
basicDouble.isNull();        // false
basicDouble.setNull();       // BasicDouble 空值底层用 -Double.MAX_VALUE 来表示

// 获取数据类型/数据形式
basicDouble.getDataType();     // DT_DOUBLE
basicDouble.getDataCategory(); // FLOATING

LITERAL

STRING

// 创建 string 类型标量
BasicString basicString = new BasicString("Hello World");

// 读取数据
basicString.getString();     // "Hello World"

// 判空/设置为空
basicString.isNull();        // false
basicString.setNull();       // BasicString 空值底层用空字符串 "" 来表示

// 获取数据类型/数据形式
basicString.getDataType();     // DT_STRING
basicString.getDataCategory(); // LITERAL

SYMBOL

不支持创建 SYMBOL 类型标量。

BLOB

// 创建 blob 类型标量
BasicString basicBlob = new BasicString("Hello World", true);

// 读取数据
basicBlob.getString();       // "Hello World"
basicBlob.getBytes();        // byte数组: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]

// 判空/设置为空
basicBlob.isNull();          // false
basicBlob.setNull();         // BasicString(BLOB) 空值底层用空字节数组 new byte[0] 来表示

// 获取数据类型/数据形式
basicBlob.getDataType();     // DT_BLOB
basicBlob.getDataCategory(); // LITERAL

BINARY

INT128

// 创建 int128 类型标量
BasicInt128 basicInt128 = new BasicInt128(15645L, 564353L);

// 读取数据
basicInt128.getString(); // "0000000000003d1d0000000000089c81"

// 判空/设置为空
basicInt128.isNull();                   // false
basicInt128.setNull();                  // BasicInt128 空值底层用 Long2 的空值来表示: high、low 分别为0

// 获取数据类型/数据形式
basicInt128.getDataType();              // DT_INT128
basicInt128.getDataCategory();          // BINARY

UUID

// 创建 uuid 类型标量
BasicUuid basicUuid = new BasicUuid(321324L, 32433L);

// 读取数据
basicUuid.getString(); // "00000000-0004-e72c-0000-000000007eb1"

// 判空/设置为空
basicUuid.isNull();                  // false
basicUuid.setNull();                 // BasicUuid 空值底层用 Long2 的空值来表示 (high=0, low=0)

// 获取数据类型/数据形式
basicUuid.getDataType();             // DT_UUID
basicUuid.getDataCategory();         // BINARY

// 从字符串创建/随机生成
BasicUuid.fromString("550e8400-e29b-41d4-a716-446655440000"); // 从UUID字符串创建
BasicUuid.random();                  // 生成随机UUID

IPADDR

// 创建 IP 地址类型标量
BasicIPAddr basicIPAddr = new BasicIPAddr(0, 3232235953L);
// 从字符串创建
BasicIPAddr.fromString("192.168.1.1");              // 从IPv4字符串创建
BasicIPAddr.fromString("2001:0db8:85a3::8a2e:370:7334"); // 从IPv6字符串创建

// 读取数据
System.out.println(basicIPAddr.getString(); // "192.168.1.177"

// 判空/设置为空
basicIPAddr.isNull();                  // false
basicIPAddr.setNull();                 // BasicIPAddr 空值底层用 Long2 的空值来表示 (high=0, low=0)

// 获取数据类型/数据形式
basicIPAddr.getDataType();             // DT_IPADDR
basicIPAddr.getDataCategory();         // BINARY

POINT

// 创建点类型标量
BasicPoint basicPoint = new BasicPoint(3.14, 2.71);
// 读取数据
basicPoint.getString(); // "(3.14, 2.71)"
basicPoint.getX();               // 3.14 (x坐标)
basicPoint.getY();               // 2.71 (y坐标)

// 判空/设置为空
basicPoint.isNull();             // false
basicPoint.setNull();            // 设置为空值，getString()返回"(,)"

// 获取数据类型/数据形式
basicPoint.getDataType();        // DT_POINT
basicPoint.getDataCategory();    // BINARY

DECIMAL

DECIMAL32

// 创建 Decimal32 类型标量
BasicDecimal32 basicDecimal32 = new BasicDecimal32("123.45", 2);

// 读取数据
basicDecimal32.getString();          // "123.45"
basicDecimal32.getScale();           // 2 (小数位数)

// 判空/设置为空
basicDecimal32.isNull();             // false
basicDecimal32.setNull();            // 设置为空值，getString()返回""

// 获取数据类型/数据形式
basicDecimal32.getDataType();        // DT_DECIMAL32
basicDecimal32.getDataCategory();    // DENARY

DECIMAL64

BasicDecimal64 basicDecimal64 = new BasicDecimal64("123456.789", 3);
// 读取数据
basicDecimal64.getString();          // "123456.789"
basicDecimal64.getScale();           // 3 (小数位数)

// 判空/设置为空
basicDecimal64.isNull();             // false
basicDecimal64.setNull();            // 设置为空值，getString()返回""

// 获取数据类型/数据形式
basicDecimal64.getDataType();        // DT_DECIMAL64
basicDecimal64.getDataCategory();    // DENARY

DECIMAL128

BasicDecimal128 basicDecimal128 = new BasicDecimal128("12345678901234567890.123456", 6);
// 读取数据
basicDecimal128.getString();         // "12345678901234567890.123456"
basicDecimal128.getScale();          // 6 (小数位数)

// 判空/设置为空
basicDecimal128.isNull();            // false
basicDecimal128.setNull();           // 设置为空值，getString()返回""

// 获取数据类型/数据形式
basicDecimal128.getDataType();       // DT_DECIMAL128
basicDecimal128.getDataCategory();   // DENARY

OTHER

COMPLEX

// 创建复数类型标量
BasicComplex basicComplex = new BasicComplex(3.14, -2.71);
// 读取数据
basicComplex.getString();           // "3.14-2.71i"
basicComplex.getReal();             // 3.14 (实部)
basicComplex.getImage();            // -2.71 (虚部)
// 判空/设置为空
basicComplex.isNull();              // false
basicComplex.setNull();             // 设置为空值，getString()返回""
// 获取数据类型/数据形式
basicComplex.getDataType();         // DT_COMPLEX
basicComplex.getDataCategory();     // BINARY

SYSTEM

DURATION

// 使用 Entity.DURATION 创建持续时间类型标量
BasicDuration basicDuration = new BasicDuration(Entity.DURATION.SECOND, 3600);
// 或者使用字符串表示单位
BasicDuration basicDuration = new BasicDuration("s", 3600);

// 读取数据
basicDuration.getString();           // "3600s"
basicDuration.getDuration();         // 3600
basicDuration.getUnit();             // DURATION.SECOND
basicDuration.getExchangeInt();      // 3
basicDuration.getExchangeName();     // "s"

// 判空/设置为空
basicDuration.isNull();              // false
basicDuration.setNull();             // 设置为空值，getString()返回""
// 获取数据类型/数据形式
basicDuration.getDataType();         // DT_DURATION
basicDuration.getDataCategory();     // SYSTEM