Data Forms

Scalar

Constructor

All basic data types of Java API implement the Scalar interface. For example, a scalar can be declared using the constructor of BasicInt:

Scalar scalar = new BasicInt(123);

Usage

You can use the getNumber method or the getString method to get the value of a basic data type.

For example, for BasicInt:

BasicInt basicInt = new BasicInt(36);
String basicIntString = basicInt.getString();
Number basicIntNumber = basicInt.getNumber();

Note: The getNumber method can only return numeric types. For non-numeric types such as BasicString, it will throw an exception. For example:

Scalar scalar = new BasicString("123123");
System.out.println(scalar.getNumber());

This will throw an exception:

java.lang.Exception: Incompatible data type

Data types currently supported by the getNumber method in the Java API include: BasicBoolean, BasicByte, BasicComplex, BasicDecimal32, BasicDecimal64, BasicDecimal128, BasicDouble, BasicDuration, BasicFloat, BasicInt, BasicInt128, BasicLong, BasicPoint, BasicShort, BasicString, Void.

Vector

The Java API support vectors of various data types. Note that this vector is not the Java built-in Vector. It is located in the com.xxdb.data package. The following description takes BasicIntVector for example.

Constructor

The constructor for BasicIntVector is as follows:

// Define by capacity
public BasicIntVector(int size)

// Define by list and the vector has initial values
public BasicIntVector(List<Integer> list)

Usage

You can add values to the end of a vector using the add method.

BasicIntVector v = new BasicIntVector(6);
v.add(1);
v.add(2);
v.add(3);
for (int i = 0; i < v.rows(); i++) {
   System.out.print(v.get(i) + " ");
}

Expected output:

0 0 0 0 0 0 1 2 3 0
// Note: Adding starts from the 7th position, not the beginning

You can modify the values of the vector using the setInt method:
```
BasicIntVector v = new BasicIntVector(6);
v.setInt(0, 2147483647);
v.setInt(1, -2147483647);
v.setInt(2, 99);
v.setInt(3, 0);
v.setInt(4, -12);
```
The setInt method is defined as follows:
```
public void setInt(int index, int value)
```
Parameters
- index: The index of the element to be modified, starting from 0.
- value: The value to modify the element to.

You can get the value at a specific index using the get method:

// Declare a Vector of size 5
BasicIntVector v = new BasicIntVector(6);
v.setInt(0, 2147483647);
v.setInt(1, -2147483647);
v.setInt(2, 99);
v.setInt(3, 0);
v.setInt(4, -12);
// Get the number of rows in the vector. Note that this value is 6, not 5, because the Vector size is 6, and the unset parts are filled with 0 or null.
for (int i = 0; i < v.rows(); i++) {
    System.out.println(v.get(i));
}

In DolphinDB, a query returns a vector if it starts with exec and the result has only one column. For example, the following query returns a vector:

DBConnection conn = new DBConnection();
conn.connect(HOST, PORT, USER, PASSWORD);
String script = "exec x from loadTable(\"dfs://ramd\", `pt1)";
Vector vector = (Vector) conn.run(script);

The attempt to receive the result with a Table object will throw an exception:

Table table = (Table) conn.run(script);
// java.lang.ClassCastException: com.xxdb.data.BasicDoubleVector cannot be cast to com.xxdb.data.Table

Matrix

Constructor

A matrix is an interface implemented by various basic data types in matrix form. For example, the constructor for BasicIntMatrix is as follows:

public BasicIntMatrix(int rows, int columns, List<int[]> list)

Parameters

rows: The number of rows in the matrix.
columns: The number of columns in the matrix.
list (optional): The initial values for each position in the matrix.

To declare a 2x2 BasicIntMatrix:

int[] row1 = {1, 2};
int[] row2 = {3, 4};
BasicIntMatrix matrix = new BasicIntMatrix(2, 2, Arrays.asList(row1, row2));

Usage

You can use the get method to get a value at a specific position (defined by row and column) in the matrix. The return value is a scalar:
```
public Scalar get(int row, int column)
```
You can use the set<data_type> method (where <data_type> represents the data type, for example, if the data type is Int, the method is setInt) to set the value at a specific position in the matrix. For example, to set the value at row 1, column 2 to 3:
```
matrix.setInt(1, 2, 3);
```

Set

Java API provides a Set interface BasicSet for storing a series of elements of the same type.

Constructor

Elements of a set are called keys. The constructor for BasicSet is as follows:

public BasicSet(DATA_TYPE keyType, int capacity)

Parameters

keyType: An enum declaring the type of the set.
capacity (optional, default 0): An integer specifying the initial capacity of the set. The set will automatically double its capacity when the number of elements reaches 0.75*capacity.

Usage

You can add objects to a set using the add method. For example:

BasicSet basicSet = new BasicSet(Entity.DATA_TYPE.DT_INT,4);
basicSet.add(new BasicInt(1));

You can get all keys from a set using the keys method:

public Vector keys();

This method returns a vector (from com.xxdb.data package). You can get all the elements of the set using this vector:

BasicSet basicSet = new BasicSet(Entity.DATA_TYPE.DT_INT);
basicSet.add(new BasicInt(1));
basicSet.add(new BasicInt(2));
basicSet.add(new BasicInt(3));
basicSet.add(new BasicInt(4));
basicSet.add(new BasicInt(5));
Vector vector = basicSet.keys();
System.out.println(vector.getString());

You can check if a key exists in the set using the contains method, which returns a boolean value. For example:

BasicSet basicSet = new BasicSet(Entity.DATA_TYPE.DT_INT,4);
basicSet.add(new BasicInt(1));
basicSet.add(new BasicInt(2));
basicSet.add(new BasicInt(3));
basicSet.add(new BasicInt(4));
basicSet.add(new BasicInt(5));
System.out.println(basicSet.contains(new BasicInt(4)));

Dictionary

Constructor

The constructor of BasicDictionary is as follows:

public BasicDictionary(DATA_TYPE keyType, DATA_TYPE valueType, int capacity)

Parameters

keyType: An enum declaring the data type of the keys.
valueType: An enum declaring the data type of the values.
capacity (optional, default 0): An integer specifying the initial capacity of the dictionary. The dictionary will automatically double its capacity when the number of key-value pairs exceeds capacity.

Usage

You can add a key-value pair to the BasicDictionary using the put method.

BasicDictionary basicDictionary = new BasicDictionary(Entity.DATA_TYPE.DT_STRING, Entity.DATA_TYPE.DT_INT);
// key type: BasicString, value type: BasicInt
basicDictionary.put(new BasicString("1"),new BasicInt(2));

You can retrieve the value to a key using the get method.

BasicDictionary basicDictionary = new BasicDictionary(Entity.DATA_TYPE.DT_STRING, Entity.DATA_TYPE.DT_INT);
basicDictionary.put(new BasicString("1"),new BasicInt(2));
System.out.println(basicDictionary.get(new BasicString("1")));
// output: 2

You can query all keys using the keys method.

Note: Unlike BasicSet, the keys method of BasicDictionary returns a set with a generic type of Entity. For example:

BasicDictionary basicDictionary = new BasicDictionary(Entity.DATA_TYPE.DT_STRING, Entity.DATA_TYPE.DT_INT);
basicDictionary.put(new BasicString("1"),new BasicInt(1));
basicDictionary.put(new BasicString("2"),new BasicInt(2));
basicDictionary.put(new BasicString("3"),new BasicInt(3));
Set<Entity> entities = basicDictionary.keys();
for (Entity e : entities) {
    System.out.print(e.getString() + " ");
}
// output: 1 2 3

You can directly get the key-value mappings in BasicDictionary using the getString method:

BasicDictionary basicDictionary = new BasicDictionary(Entity.DATA_TYPE.DT_STRING, Entity.DATA_TYPE.DT_INT);
basicDictionary.put(new BasicString("1"),new BasicInt(4));
basicDictionary.put(new BasicString("2"),new BasicInt(5));
basicDictionary.put(new BasicString("3"),new BasicInt(6));
System.out.println(basicDictionary.getString());
// output: {1,2,3}->{4,5,6}

Table

The Java API defines the data form Table to facilitate queries and operations on data.

Constructor

The constructor of BasicTable is as follows:

public BasicTable(final List<String> colNames, final List<Vector> cols)

Parameters

colNames: Column names of the table.
cols: Data for each column.

Usage

You can directly obtain a table by executing a query.

DBConnection dbConnection = new DBConnection();
DBConnection dbConnection = new DBConnection();
dbConnection.connect(HOST,PORT,USER,PASSWORD);
BasicTable basicTable = (BasicTable) dbConnection.run("select * from loadTable(\"dfs://ramd\",`pt3)");

You can get all values of a column using the getColumn method, which is defined as follows:
```
// by column index
public Vector getColumn(int index)

// by column name
public Vector getColumn(String name)
```
The return value is a com.xxdb.data.Vector, which can be used to iterate through all data.

You can manipulate the Vector object returned by getColumn to modify the content of the table. For example:

public void test_set_nullvalue() throws IOException {
  try{
      List<String> colNames =  Arrays.asList("cint","cdouble","clong","cfloat","cshort");
      List<Vector> colData = Arrays.asList(new BasicIntVector(1),new BasicDoubleVector(1),new BasicLongVector(1),new BasicFloatVector(1),new BasicShortVector(1));
      BasicTable bt = new BasicTable(colNames,colData);
      bt.getColumn("cint").set(0,new BasicInt(Integer.MIN_VALUE));
      bt.getColumn("cdouble").set(0,new BasicDouble(-Double.MIN_VALUE));
      bt.getColumn("clong").set(0,new BasicLong(Long.MIN_VALUE));
      bt.getColumn("cfloat").set(0,new BasicFloat(-Float.MAX_VALUE));
      bt.getColumn("cshort").set(0,new BasicShort(Short.MIN_VALUE));
      bt.getColumn("cshort").set(0,new BasicShort(Short.MIN_VALUE));
      bt.getColumn("cshort").set(0,new BasicShort(Short.MIN_VALUE));
      assertTrue(((Scalar)bt.getColumn("clong").get(0)).isNull());
  }catch (Exception e){
      e.printStackTrace();
  }
}

If you want to generate each row in JSON format, you can call the getRowJson method. For example:

DBConnection dbConnection = new DBConnection();
dbConnection.connect(HOST, PORT, USER, PASSWORD);
BasicTable basicTable = (BasicTable) dbConnection.run("select * from loadTable(\"dfs://ramd\", `pt3)");
// Get the number of rows
int rows = basicTable.rows();
// Iterate through each row
for (int i = 0; i < rows; i++) {
    System.out.println(basicTable.getRowJson(i));
}

Tensor

Constructor

Java API implements Tensor data of the following types:

DT_BOOL
DT_CHAR
DT_SHORT
DT_INT
DT_LONG
DT_FLOAT
DT_DOUBLE

BasicTensor can be used to obtain Tensor data created with tensor() on DolphinDB server. The constructor on Java is not implemented yet.

Usage

@Test
public void test_tensor_1() throws IOException {
    DBConnection conn = new DBConnection();
    conn.connect("192.168.0.69", 8802, "admin", "123456");
    // Create with DolphinDB function tensor()
    // Retrieve Tensor data with BasicTensor
    BasicTensor tensor = (BasicTensor) conn.run("tensor(((1..1000$50:20),(1..1000$50:20)))");
    System.out.println(entity.getString());
}

Execution result:

tensor<int[2][50][20]>([[[1,51,101,151,201,251,301,351,401,451,501...],[2,52,102,152,202,252,302,352,402,452,502...],[3,53,103,153,203,253,303,353,403,453,503...],[4,54,104,154,204,254,304,354,404,454,504...],[5,55,105,155,205,255,305,355,405,455,505...],[6,56,106,156,206,256,306,356,406,456,506...],[7,57,107,157,207,257,307,357,407,457,507...],[8,58,108,158,208,258,308,358,408,458,508...],[9,59,109,159,209,259,309,359,409,459,509...],[10,60,110,160,210,260,310,360,410,460,510...],[11,61,111,161,211,261,311,361,411,461,511...],[12,62,112,162,212,262,312,362,412,462,512...],[13,63,113,163,213,263,313,363,413,463,513...],[14,64,114,164,214,264,314,364,414,464,514...],[15,65,115,165,215,265,315,365,415,465,515...],[16,66,116,166,216,266,316,366,416,466,516...],[17,67,117,167,217,267,317,367,417,467,517...],[18,68,118,168,218,268,318,368,418,468,518...],[19,69,119,169,219,269,319,369,419,469,519...],[20,70,120,170,220,270,320,370,420,470,520...],[21,71,121,171,221,271,321,371,421,471,521...],[22,72,122,172,222,272,322,372,422,472,522...],[23,73,123,173,223,273,323,373,423,473,523...],[24,74,124,174,224,274,324,374,424,474,524...],[25,75,125,175,225,275,325,375,425,475,525...],[26,76,126,176,226,276,326,376,426,476,526...],[27,77,127,177,227,277,327,377,427,477,527...],[28,78,128,178,228,278,328,378,428,478,528...],[29,79,129,179,229,279,329,379,429,479,529...],[30,80,130,180,230,280,330,380,430,480,530...],[31,81,131,181,231,281,331,381,431,481,531...],[32,82,132,182,232,282,332,382,432,482,532...],[33,83,133,183,233,283,333,383,433,483,533...],[34,84,134,184,234,284,334,384,434,484,534...],[35,85,135,185,235,285,335,385,435,485,535...],[36,86,136,186,236,286,336,386,436,486,536...],[37,87,137,187,237,287,337,387,437,487,537...],[38,88,138,188,238,288,338,388,438,488,538...],[39,89,139,189,239,289,339,389,439,489,539...],[40,90,140,190,240,290,340,390,440,490,540...],[41,91,141,191,241,291,341,391,441,491,541...],[42,92,142,192,242,292,342,392,442,492,542...],[43,93,143,193,243,293,343,393,443,493,543...],[44,94,144,194,244,294,344,394,444,494,544...],[45,95,145,195,245,295,345,395,445,495,545...],[46,96,146,196,246,296,346,396,446,496,546...],[47,97,147,197,247,297,347,397,447,497,547...],[48,98,148,198,248,298,348,398,448,498,548...],[49,99,149,199,249,299,349,399,449,499,549...],[50,100,150,200,250,300,350,400,450,500,550...]],[[1,51,101,151,201,251,301,351,401,451,501...],[2,52,102,152,202,252,302,352,402,452,502...],[3,53,103,153,203,253,303,353,403,453,503...],[4,54,104,154,204,254,304,354,404,454,504...],[5,55,105,155,205,255,305,355,405,455,505...],[6,56,106,156,206,256,306,356,406,456,506...],[7,57,107,157,207,257,307,357,407,457,507...],[8,58,108,158,208,258,308,358,408,458,508...],[9,59,109,159,209,259,309,359,409,459,509...],[10,60,110,160,210,260,310,360,410,460,510...],[11,61,111,161,211,261,311,361,411,461,511...],[12,62,112,162,212,262,312,362,412,462,512...],[13,63,113,163,213,263,313,363,413,463,513...],[14,64,114,164,214,264,314,364,414,464,514...],[15,65,115,165,215,265,315,365,415,465,515...],[16,66,116,166,216,266,316,366,416,466,516...],[17,67,117,167,217,267,317,367,417,467,517...],[18,68,118,168,218,268,318,368,418,468,518...],[19,69,119,169,219,269,319,369,419,469,519...],[20,70,120,170,220,270,320,370,420,470,520...],[21,71,121,171,221,271,321,371,421,471,521...],[22,72,122,172,222,272,322,372,422,472,522...],[23,73,123,173,223,273,323,373,423,473,523...],[24,74,124,174,224,274,324,374,424,474,524...],[25,75,125,175,225,275,325,375,425,475,525...],[26,76,126,176,226,276,326,376,426,476,526...],[27,77,127,177,227,277,327,377,427,477,527...],[28,78,128,178,228,278,328,378,428,478,528...],[29,79,129,179,229,279,329,379,429,479,529...],[30,80,130,180,230,280,330,380,430,480,530...],[31,81,131,181,231,281,331,381,431,481,531...],[32,82,132,182,232,282,332,382,432,482,532...],[33,83,133,183,233,283,333,383,433,483,533...],[34,84,134,184,234,284,334,384,434,484,534...],[35,85,135,185,235,285,335,385,435,485,535...],[36,86,136,186,236,286,336,386,436,486,536...],[37,87,137,187,237,287,337,387,437,487,537...],[38,88,138,188,238,288,338,388,438,488,538...],[39,89,139,189,239,289,339,389,439,489,539...],[40,90,140,190,240,290,340,390,440,490,540...],[41,91,141,191,241,291,341,391,441,491,541...],[42,92,142,192,242,292,342,392,442,492,542...],[43,93,143,193,243,293,343,393,443,493,543...],[44,94,144,194,244,294,344,394,444,494,544...],[45,95,145,195,245,295,345,395,445,495,545...],[46,96,146,196,246,296,346,396,446,496,546...],[47,97,147,197,247,297,347,397,447,497,547...],[48,98,148,198,248,298,348,398,448,498,548...],[49,99,149,199,249,299,349,399,449,499,549...],[50,100,150,200,250,300,350,400,450,500,550...]]])