Scalar

The Java API scalar interface is Scalar, which extends the Entity interface.

Creating a scalar means converting a native Java type into a DolphinDB type. A scalar represents a single piece of data.

This section introduces how to create, read, and update scalars, along with usage examples.

VOID

// VOID type does not support direct creation through constructor, generally returned by script execution
DBConnection conn = new DBConnection();
conn.connect("192.168.0.69", 8802, "admin", "123456");
Void voidValue = (Void) conn.run("NULL");
// Read data
voidValue.getString(); // ""
// Check null/set null
voidValue.isNull();    // true
// Get data type/data category
voidValue.getDataType(); // DT_VOID;
voidValue.getDataCategory(); // NOTHING;

LOGICAL

BOOL

// Create boolean type scalar
BasicBoolean basicBoolean = new BasicBoolean(true);

// Read data
basicBoolean.getString();    // "true"
basicBoolean.getBoolean();   // true

// Check null/set null
basicBoolean.isNull();       // false
basicBoolean.setNull();      // BasicBoolean null value is represented by Byte.MIN_VALUE internally

// Get data type/data category
basicBoolean.getDataType();     // DT_BOOL
basicBoolean.getDataCategory(); // LOGICAL

INTEGRAL

CHAR

// Create char type scalar
BasicByte basicByte = new BasicByte((byte) 'a');
// Read data
basicByte.getString(); // 'a'
basicByte.getByte();    // 97
// Check null/set null
basicByte.isNull();    // false
basicByte.setNull();     // BasicByte null value is represented by Byte.MIN_VALUE internally
// Get data type/data category
basicByte.getDataType(); // DT_BYTE;
basicByte.getDataCategory(); // INTEGRAL;

SHORT

// Create short type scalar
BasicShort basicShort = new BasicShort((short) 21);
// Read data
basicShort.getString(); // 21
basicShort.getShort();    // 21
// Check null/set null
basicShort.isNull();    // false
basicShort.setNull();     // BasicShort null value is represented by Short.MIN_VALUE internally
// Get data type/data category
basicShort.getDataType(); // DT_SHORT;
basicShort.getDataCategory(); // INTEGRAL;

INT

// Create int type scalar
BasicInt basicInt = new BasicInt(21);
// Read data
basicInt.getString(); // "21"
basicInt.getInt();    // 21
// Check null/set null
basicInt.isNull();    // false
basicInt.setNull();     // BasicInt null value is represented by Integer.MIN_VALUE internally
// Get data type/data category
basicInt.getDataType(); // DT_INT;
basicInt.getDataCategory(); // INTEGRAL;

LONG

// Create long type scalar
BasicLong basicLong = new BasicLong(21L);
// Read data
basicLong.getString(); // "21"
basicLong.getLong();    // 21
// Check null/set null
basicLong.isNull();    // false
basicLong.setNull();     // BasicLong null value is represented by Long.MIN_VALUE internally
// Get data type/data category
basicLong.getDataType(); // DT_LONG;
basicLong.getDataCategory(); // INTEGRAL;

TEMPORAL

DATE

// 1) Create DATE type scalar using LocalDate
BasicDate basicDate = new BasicDate(LocalDate.of(2023, 12, 25));
// 2) Create date type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25);
BasicDate basicDate = new BasicDate(calendar);

// Read data
basicDate.getString();    // "2023.12.25"
basicDate.getDate();      // LocalDate object: 2023-12-25

// Check null/set null
basicDate.isNull();       // false
basicDate.setNull();      // BasicDate null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicDate.getDataType();     // DT_DATE
basicDate.getDataCategory(); // TEMPORAL

MONTH

// 1) Create MONTH type scalar using Month
BasicMonth basicMonth = new BasicMonth(2023, Month.DECEMBER);
// 2) Create MONTH type scalar using YearMonth
BasicMonth basicMonth = new BasicMonth(YearMonth.of(2023, 12));
// 3) Create MONTH type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 1);
BasicMonth basicMonth = new BasicMonth(calendar);

// Read data
basicMonth.getString();    // "2023.12M"
basicMonth.getMonth();     // YearMonth object: 2023-12

// Check null/set null
basicMonth.isNull();       // false
basicMonth.setNull();      // BasicMonth null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicMonth.getDataType();     // DT_MONTH
basicMonth.getDataCategory(); // TEMPORAL

TIME

// 1) Create TIME type scalar using LocalTime
BasicTime basicTime = new BasicTime(LocalTime.of(14, 30, 45, 123000000));
// 2) Create TIME type scalar using Calendar
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);

// Read data
basicTime.getString();    // "14:30:45.123"
basicTime.getTime();      // LocalTime object: 14:30:45.123

// Check null/set null
basicTime.isNull();       // false
basicTime.setNull();      // BasicTime null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicTime.getDataType();     // DT_TIME
basicTime.getDataCategory(); // TEMPORAL

MINUTE

// 1) Create MINUTE type scalar using LocalTime
BasicMinute basicMinute = new BasicMinute(LocalTime.of(14, 30));
// 2) Create MINUTE type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(Calendar.HOUR_OF_DAY, 14);
calendar.set(Calendar.MINUTE, 30);
BasicMinute basicMinute = new BasicMinute(calendar);

// Read data
basicMinute.getString();    // "14:30m"
basicMinute.getMinute();    // LocalTime object: 14:30

// Check null/set null
basicMinute.isNull();       // false
basicMinute.setNull();      // BasicMinute null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicMinute.getDataType();     // DT_MINUTE
basicMinute.getDataCategory(); // TEMPORAL

SECOND

// 1) Create SECOND type scalar using LocalTime
BasicSecond basicSecond = new BasicSecond(LocalTime.of(14, 30, 45));
// 2) Create SECOND type scalar using Calendar
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);

// Read data
basicSecond.getString();    // "14:30:45"
basicSecond.getSecond();    // LocalTime object: 14:30:45

// Check null/set null
basicSecond.isNull();       // false
basicSecond.setNull();      // BasicSecond null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicSecond.getDataType();     // DT_SECOND
basicSecond.getDataCategory(); // TEMPORAL

DATETIME

// 1) Create DATETIME type scalar using LocalDateTime
BasicDateTime basicDateTime = new BasicDateTime(LocalDateTime.of(2023, 12, 25, 14, 30, 45));
// 2) Create DATETIME type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 30, 45);
BasicDateTime basicDateTime = new BasicDateTime(calendar);

// Read data
basicDateTime.getString();    // "2023.12.25T14:30:45"
basicDateTime.getDateTime();  // LocalDateTime object: 2023-12-25T14:30:45

// Check null/set null
basicDateTime.isNull();       // false
basicDateTime.setNull();      // BasicDateTime null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicDateTime.getDataType();     // DT_DATETIME
basicDateTime.getDataCategory(); // TEMPORAL

TIMESTAMP

// 1) Create TIMESTAMP type scalar using LocalDateTime
BasicTimestamp basicTimestamp = new BasicTimestamp(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123000000));
// 2) Create TIMESTAMP type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 30, 45);
calendar.set(Calendar.MILLISECOND, 123);
BasicTimestamp basicTimestamp = new BasicTimestamp(calendar);

// Read data
basicTimestamp.getString();      // "2023.12.25T14:30:45.123"
basicTimestamp.getTimestamp();   // LocalDateTime object: 2023-12-25T14:30:45.123

// Check null/set null
basicTimestamp.isNull();         // false
basicTimestamp.setNull();        // BasicTimestamp null value is represented by Long.MIN_VALUE internally

// Get data type/data category
basicTimestamp.getDataType();     // DT_TIMESTAMP
basicTimestamp.getDataCategory(); // TEMPORAL

NANOTIME

// 1) Create NANOTIME type scalar using LocalTime
BasicNanoTime basicNanoTime = new BasicNanoTime(LocalTime.of(14, 30, 45, 123456789));
// 2) Create NANOTIME type scalar using LocalDateTime
BasicNanoTime basicNanoTimeFromDateTime = new BasicNanoTime(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123456789));

// Read data
basicNanoTime.getString();      // "14:30:45.123456789"
basicNanoTime.getNanoTime();    // LocalTime object: 14:30:45.123456789

// Check null/set null
basicNanoTime.isNull();         // false
basicNanoTime.setNull();        // BasicNanoTime null value is represented by Long.MIN_VALUE internally

// Get data type/data category
basicNanoTime.getDataType();     // DT_NANOTIME
basicNanoTime.getDataCategory(); // TEMPORAL

NANOTIMESTAMP

// Create NANOTIMESTAMP type scalar using LocalDateTime
BasicNanoTimestamp basicNanoTimestamp = new BasicNanoTimestamp(LocalDateTime.of(2023, 12, 25, 14, 30, 45, 123456789));

// Read data
basicNanoTimestamp.getString();         // "2023.12.25T14:30:45.123456789"
basicNanoTimestamp.getNanoTimestamp();  // LocalDateTime object: 2023-12-25T14:30:45.123456789

// Check null/set null
basicNanoTimestamp.isNull();            // false
basicNanoTimestamp.setNull();           // BasicNanoTimestamp null value is represented by Long.MIN_VALUE internally

// Get data type/data category
basicNanoTimestamp.getDataType();       // DT_NANOTIMESTAMP
basicNanoTimestamp.getDataCategory();   // TEMPORAL

DATEHOUR

// 1) Create DATEHOUR type scalar using LocalDateTime
BasicDateHour basicDateHour = new BasicDateHour(LocalDateTime.of(2023, 12, 25, 14, 0, 0));

// 2) Create DATEHOUR type scalar using Calendar
Calendar calendar = Calendar.getInstance();
calendar.set(2023, Calendar.DECEMBER, 25, 14, 0, 0);
BasicDateHour basicDateHourFromCalendar = new BasicDateHour(calendar);

// Read data
basicDateHour.getString();      // "2023.12.25T14"
basicDateHour.getDateHour();    // LocalDateTime object: 2023-12-25T14:00
basicDateHour.getInt();         // Hour count: 548774

// Check null/set null
basicDateHour.isNull();         // false
basicDateHour.setNull();        // BasicDateHour null value is represented by Integer.MIN_VALUE internally

// Get data type/data category
basicDateHour.getDataType();     // DT_DATEHOUR
basicDateHour.getDataCategory(); // TEMPORAL

FLOATING

FLOAT

// Create float type scalar
BasicFloat basicFloat = new BasicFloat(3.14159f);

// Read data
basicFloat.getString();     // "3.14159"
basicFloat.getFloat();      // 3.14159f

// Check null/set null
basicFloat.isNull();        // false
basicFloat.setNull();       // BasicFloat null value is represented by -Float.MAX_VALUE internally

// Get data type/data category
basicFloat.getDataType();     // DT_FLOAT
basicFloat.getDataCategory(); // FLOATING

DOUBLE

// Create double type scalar
BasicDouble basicDouble = new BasicDouble(3.141592653589793);

// Read data
basicDouble.getString();     // "3.14159265"
basicDouble.getDouble();     // 3.141592653589793

// Check null/set null
basicDouble.isNull();        // false
basicDouble.setNull();       // BasicDouble null value is represented by -Double.MAX_VALUE internally

// Get data type/data category
basicDouble.getDataType();     // DT_DOUBLE
basicDouble.getDataCategory(); // FLOATING

LITERAL

STRING

// Create string type scalar
BasicString basicString = new BasicString("Hello World");

// Read data
basicString.getString();     // "Hello World"

// Check null/set null
basicString.isNull();        // false
basicString.setNull();       // BasicString null value is represented by empty string "" internally

// Get data type/data category
basicString.getDataType();     // DT_STRING
basicString.getDataCategory(); // LITERAL

SYMBOL

Does not support creating SYMBOL type scalar.

BLOB

// Create blob type scalar
BasicString basicBlob = new BasicString("Hello World", true);

// Read data
basicBlob.getString();       // "Hello World"
basicBlob.getBytes();        // byte array: [72, 101, 108, 108, 111, 32, 87, 111, 114, 108, 100]

// Check null/set null
basicBlob.isNull();          // false
basicBlob.setNull();         // BasicString(BLOB) null value is represented by empty byte array new byte[0] internally

// Get data type/data category
basicBlob.getDataType();     // DT_BLOB
basicBlob.getDataCategory(); // LITERAL

BINARY

INT128

// Create int128 type scalar
BasicInt128 basicInt128 = new BasicInt128(15645L, 564353L);

// Read data
basicInt128.getString(); // "0000000000003d1d0000000000089c81"

// Check null/set null
basicInt128.isNull();                   // false
basicInt128.setNull();                  // BasicInt128 null value is represented by Long2's null value: high, low are both 0

// Get data type/data category
basicInt128.getDataType();              // DT_INT128
basicInt128.getDataCategory();          // BINARY

UUID

// Create uuid type scalar
BasicUuid basicUuid = new BasicUuid(321324L, 32433L);

// Read data
basicUuid.getString(); // "00000000-0004-e72c-0000-000000007eb1"

// Check null/set null
basicUuid.isNull();                  // false
basicUuid.setNull();                 // BasicUuid null value is represented by Long2's null value (high=0, low=0)

// Get data type/data category
basicUuid.getDataType();             // DT_UUID
basicUuid.getDataCategory();         // BINARY

// Create from string/generate randomly
BasicUuid.fromString("550e8400-e29b-41d4-a716-446655440000"); // Create from UUID string
BasicUuid.random();                  // Generate random UUID

IPADDR

// Create IP address type scalar
BasicIPAddr basicIPAddr = new BasicIPAddr(0, 3232235953L);
// Create from string
BasicIPAddr.fromString("192.168.1.1");              // Create from IPv4 string
BasicIPAddr.fromString("2001:0db8:85a3::8a2e:370:7334"); // Create from IPv6 string

// Read data
System.out.println(basicIPAddr.getString(); // "192.168.1.177"

// Check null/set null
basicIPAddr.isNull();                  // false
basicIPAddr.setNull();                 // BasicIPAddr null value is represented by Long2's null value (high=0, low=0)

// Get data type/data category
basicIPAddr.getDataType();             // DT_IPADDR
basicIPAddr.getDataCategory();         // BINARY

POINT

// Create point type scalar
BasicPoint basicPoint = new BasicPoint(3.14, 2.71);
// Read data
basicPoint.getString(); // "(3.14, 2.71)"
basicPoint.getX();               // 3.14 (x coordinate)
basicPoint.getY();               // 2.71 (y coordinate)

// Check null/set null
basicPoint.isNull();             // false
basicPoint.setNull();            // Set to null value, getString() returns "(,)"

// Get data type/data category
basicPoint.getDataType();        // DT_POINT
basicPoint.getDataCategory();    // BINARY

DECIMAL

DECIMAL32

// Create Decimal32 type scalar
BasicDecimal32 basicDecimal32 = new BasicDecimal32("123.45", 2);

// Read data
basicDecimal32.getString();          // "123.45"
basicDecimal32.getScale();           // 2 (decimal places)

// Check null/set null
basicDecimal32.isNull();             // false
basicDecimal32.setNull();            // Set to null value, getString() returns ""

// Get data type/data category
basicDecimal32.getDataType();        // DT_DECIMAL32
basicDecimal32.getDataCategory();    // DENARY

DECIMAL64

BasicDecimal64 basicDecimal64 = new BasicDecimal64("123456.789", 3);
// Read data
basicDecimal64.getString();          // "123456.789"
basicDecimal64.getScale();           // 3 (decimal places)

// Check null/set null
basicDecimal64.isNull();             // false
basicDecimal64.setNull();            // Set to null value, getString() returns ""

// Get data type/data category
basicDecimal64.getDataType();        // DT_DECIMAL64
basicDecimal64.getDataCategory();    // DENARY

DECIMAL128

BasicDecimal128 basicDecimal128 = new BasicDecimal128("12345678901234567890.123456", 6);
// Read data
basicDecimal128.getString();         // "12345678901234567890.123456"
basicDecimal128.getScale();          // 6 (decimal places)

// Check null/set null
basicDecimal128.isNull();            // false
basicDecimal128.setNull();           // Set to null value, getString() returns ""

// Get data type/data category
basicDecimal128.getDataType();       // DT_DECIMAL128
basicDecimal128.getDataCategory();   // DENARY

OTHER

COMPLEX

// Create complex number type scalar
BasicComplex basicComplex = new BasicComplex(3.14, -2.71);
// Read data
basicComplex.getString();           // "3.14-2.71i"
basicComplex.getReal();             // 3.14 (real part)
basicComplex.getImage();            // -2.71 (imaginary part)
// Check null/set null
basicComplex.isNull();              // false
basicComplex.setNull();             // Set to null value, getString() returns ""
// Get data type/data category
basicComplex.getDataType();         // DT_COMPLEX
basicComplex.getDataCategory();     // BINARY

SYSTEM

DURATION

// Create duration type scalar using Entity.DURATION
BasicDuration basicDuration = new BasicDuration(Entity.DURATION.SECOND, 3600);
// Or use string representation for unit
BasicDuration basicDuration = new BasicDuration("s", 3600);

// Read data
basicDuration.getString();           // "3600s"
basicDuration.getDuration();         // 3600
basicDuration.getUnit();             // DURATION.SECOND
basicDuration.getExchangeInt();      // 3
basicDuration.getExchangeName();     // "s"

// Check null/set null
basicDuration.isNull();              // false
basicDuration.setNull();             // Set to null value, getString() returns ""
// Get data type/data category
basicDuration.getDataType();         // DT_DURATION
basicDuration.getDataCategory();     // SYSTEM