Table

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

Creating a Table

Constructor

The constructor of BasicTable is as follows:

public BasicTable()
public BasicTable(final List<String> colNames, final List<Vector> cols)
public BasicTable(final List<String> colNames, final Collection<?> cols)
public BasicTable(final List<String> colNames, final Object[] cols)
public BasicTable(final List<String> colNames, final List<?> cols, final DATA_TYPE[] colTypes)
public BasicTable(final List<String> colNames, final List<?> cols, final DATA_TYPE[] colTypes, final int[] colExtraParams)
public BasicTable(final List<String> colNames, final Object[] cols, final DATA_TYPE[] colTypes)
public BasicTable(final List<String> colNames, final Object[] cols, final DATA_TYPE[] colTypes, final int[] colExtraParams)

Parameters

colNames: Column names of the table.
cols: Data for each column.
colTypes(optional): is an array of DATA_TYPE specifying the data type for each column.
colExtraParams(optional): is an array of integers specifying extra parameters for certain data types, e.g., the scale for DECIMAL columns.

Notes

BasicTable() creates an empty table; columns can be added individually using the addColumn method.

When colTypes is not specified, the constructor automatically maps Java types to DolphinDB data types as follows:


Java Type	DolphinDB Type
Boolean	BOOL
Byte	CHAR
Short	SHORT
Integer	INT
Long	LONG
Float	FLOAT
Double	DOUBLE
String	STRING
YearMonth	MONTH
LocalDate	DATE
LocalTime	NANOTIME
LocalDateTime	NANOTIMESTAMP
Date	TIMESTAMP
Calendar	TIMESTAMP
byte[]	BLOB

For data types requiring precise control, such as DECIMAL, SYMBOL, UUID, IPADDR, INT128, POINT, COMPLEX, it is recommended to first create the corresponding Vector and then create a BasicTable or use addColumn(String colName, Vector col).
In BasicTable(final List<String> colNames, final Collection<?> cols), cols must be a List, and each column can be a Java List or array.
In BasicTable(final List<String> colNames, final Object[] cols), each column must be a Java object array, such as Integer[] or String[]; primitive arrays like int[] or double[] are not supported directly.
When specifying colTypes, the constructor supports either Java native data or DolphinDB Vectors. Java native data and Vectors cannot be mixed.
If a Vector is provided, colTypes and colExtraParams can be null; if specified, the constructor will validate the Vector type and extra parameters.

Examples

// Create an empty table and add columns using addColumn
BasicTable table1 = new BasicTable();
table1.addColumn("id", Arrays.asList(1, 2, 3));
table1.addColumn("name", Arrays.asList("a", "b", "c"));

// Create a table using Vectors
List<String> colNames2 = Arrays.asList("id", "name");
List<Vector> cols2 = Arrays.asList(
    new BasicIntVector(new int[]{1, 2, 3}),
    new BasicStringVector(new String[]{"a", "b", "c"})
);
BasicTable table2 = new BasicTable(colNames2, cols2);

// Create a table using Java Lists (automatic type mapping)
List<String> colNames3 = Arrays.asList("id", "name");
List<Object> cols3 = Arrays.asList(
    Arrays.asList(1, 2, 3),
    Arrays.asList("a", "b", "c")
);
BasicTable table3 = new BasicTable(colNames3, cols3);

// Create a table using Java arrays (automatic type mapping)
List<String> colNames4 = Arrays.asList("id", "name");
Object[] cols4 = new Object[]{
    new Integer[]{1, 2, 3},
    new String[]{"a", "b", "c"}
};
BasicTable table4 = new BasicTable(colNames4, cols4);

// Create a table using Java Lists with specified data types
List<String> colNames5 = Arrays.asList("id", "name");
List<Object> cols5 = Arrays.asList(
    Arrays.asList(1, 2, 3),
    Arrays.asList("a", "b", "c")
);
DATA_TYPE[] colTypes5 = new DATA_TYPE[]{
    DATA_TYPE.DT_INT,
    DATA_TYPE.DT_STRING
};
BasicTable table5 = new BasicTable(colNames5, cols5, colTypes5);

// Create a table using Java Lists with DECIMAL scale
List<String> colNames6 = Arrays.asList("id", "price");
List<Object> cols6 = Arrays.asList(
    Arrays.asList(1, 2, 3),
    Arrays.asList("12.34", "56.78", "90.12")
);
DATA_TYPE[] colTypes6 = new DATA_TYPE[]{
    DATA_TYPE.DT_INT,
    DATA_TYPE.DT_DECIMAL64
};
int[] colExtraParams6 = new int[]{-1, 2};
BasicTable table6 = new BasicTable(colNames6, cols6, colTypes6, colExtraParams6);

// Create a table using Java arrays with specified data types
List<String> colNames7 = Arrays.asList("id", "name");
Object[] cols7 = new Object[]{
    new Integer[]{1, 2, 3},
    new String[]{"a", "b", "c"}
};
DATA_TYPE[] colTypes7 = new DATA_TYPE[]{
    DATA_TYPE.DT_INT,
    DATA_TYPE.DT_STRING
};
BasicTable table7 = new BasicTable(colNames7, cols7, colTypes7);

// Create a table using Java arrays with DECIMAL scale
List<String> colNames8 = Arrays.asList("id", "price");
Object[] cols8 = new Object[]{
    new Integer[]{1, 2, 3},
    new String[]{"12.34", "56.78", "90.12"}
};
DATA_TYPE[] colTypes8 = new DATA_TYPE[]{
    DATA_TYPE.DT_INT,
    DATA_TYPE.DT_DECIMAL64
};
int[] colExtraParams8 = new int[]{-1, 2};
BasicTable table8 = new BasicTable(colNames8, cols8, colTypes8, colExtraParams8);

Retrieving Table Data via Query

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)");

Usage

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));
}

You can add columns using addColumn method, which is defined as follows:

public void addColumn(String colName, Vector col)
public void addColumn(String colName, List<?> values)
public void addColumn(String colName, Object[] values)

Parameters

colName is a string representing the name of the column.
col is a DolphinDB Vector representing the column data.
values is a Java List or array representing the column data.

Notes

addColumn(String colName, List<?> values) and addColumn(String colName, Object[] values) automatically map Java types to DolphinDB data types. The mapping rules are as follows:


Java Type	DolphinDB Type
Boolean	BOOL
Byte	CHAR
Short	SHORT
Integer	INT
Long	LONG
Float	FLOAT
Double	DOUBLE
String	STRING
YearMonth	MONTH
LocalDate	DATE
LocalTime	NANOTIME
LocalDateTime	NANOTIMESTAMP
Date	TIMESTAMP
Calendar	TIMESTAMP
byte[]	BLOB

addColumn(String colName, Object[] values) supports Java object arrays such as Integer[] or String[], but primitive arrays like int[] or double[] are not supported.
When adding the first column, its length defines the number of rows in the table. Subsequent columns must have the same length as existing columns.
To explicitly specify the DolphinDB data type, it is recommended to first construct a Vector and then call addColumn(String colName, Vector col).

Examples

// Add a column using a Vector
BasicTable table1 = new BasicTable();
table1.addColumn("id", new BasicIntVector(new int[]{1, 2, 3}));

// Add columns using Java Lists (automatic type mapping)
BasicTable table2 = new BasicTable();
table2.addColumn("id", Arrays.asList(1, 2, 3));
table2.addColumn("name", Arrays.asList("a", "b", "c"));

// Add columns using Java arrays (automatic type mapping)
BasicTable table3 = new BasicTable();
table3.addColumn("id", new Integer[]{1, 2, 3});
table3.addColumn("name", new String[]{"a", "b", "c"});