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. It can be a list of Vectors, a list of Java native types, or an array of Java native types. In BasicTable(final List<String> colNames, final Collection<?> cols), cols must be a List, and each column can be a Java List or array.

colTypes: Data type of each column.

colExtraParams: Extra parameters for certain data types, e.g., the scale for DECIMAL columns.

Notes

  • When a list of Vectors is provided, the column type is determined by the corresponding Vector.

  • When colTypes is not specified, Java native types are automatically mapped to DolphinDB data types. See "Automatic Type Mapping Rules".

  • When colTypes is specified, columns are constructed with the specified DolphinDB data types.

  • For DECIMAL, colExtraParams can be used to specify scale.

  • When passing column data through arrays, primitive arrays such as int[] and float[] are not supported. Use wrapper type arrays such as Integer[] and Float[].

Automatic Type Mapping Rules

When colTypes is not specified, Java native types are automatically mapped to DolphinDB data types as follows. This rule also applies when passing a Java List or array through addColumn.

Java Type DolphinDB Data 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, and COMPLEX, it is recommended to first construct the corresponding Vector and then pass it to the constructor.

Examples
// Create an empty table and add columns using addColumn
BasicTable table1 = new BasicTable();
table1.addColumn("id", new BasicIntVector(new int[]{1, 2, 3}));

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

// Create a table using Java Lists with automatic type mapping
List<String> colNames3 = Arrays.asList("id", "name");
List<?> 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 with 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", "value");
List<?> cols5 = Arrays.asList(Arrays.asList(1, 2, 3), Arrays.asList(1.1, 2.2, 3.3));
DATA_TYPE[] colTypes5 = new DATA_TYPE[]{DATA_TYPE.DT_INT, DATA_TYPE.DT_DOUBLE};
BasicTable table5 = new BasicTable(colNames5, cols5, colTypes5);

// Create a table using Java Lists with DECIMAL scale
List<String> colNames6 = Arrays.asList("price");
List<?> cols6 = Arrays.asList(Arrays.asList("1.23", "4.56", "7.89"));
DATA_TYPE[] colTypes6 = new DATA_TYPE[]{DATA_TYPE.DT_DECIMAL32};
int[] colExtraParams6 = new int[]{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", "value");
Object[] cols7 = new Object[]{new Integer[]{1, 2, 3}, new Double[]{1.1, 2.2, 3.3}};
DATA_TYPE[] colTypes7 = new DATA_TYPE[]{DATA_TYPE.DT_INT, DATA_TYPE.DT_DOUBLE};
BasicTable table7 = new BasicTable(colNames7, cols7, colTypes7);

// Create a table using Java arrays with DECIMAL scale
List<String> colNames8 = Arrays.asList("price");
Object[] cols8 = new Object[]{new String[]{"1.23", "4.56", "7.89"}};
DATA_TYPE[] colTypes8 = new DATA_TYPE[]{DATA_TYPE.DT_DECIMAL32};
int[] colExtraParams8 = new int[]{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

  1. 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.

  2. 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();
  }
}

  3. 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));
}
  4. You can add columns using the 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: Column name.

    col: Column data of type Vector.

    values: Column data, which can be a Java List or array.

    Notes

    • When a Vector is provided, the column type is determined by that Vector.

    • When a Java List or array is provided, Java native types are automatically mapped to DolphinDB data types. See "Automatic Type Mapping Rules".

    • When passing column data through arrays, primitive arrays such as int[] and float[] are not supported. Use wrapper type arrays such as Integer[] and Float[].

    • The length of the new column must be consistent with existing columns. Empty tables are not subject to this restriction.

    • For data types that require explicit typing or are not yet supported by automatic mapping, it is recommended to first construct the corresponding Vector and then call addColumn.

    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 with 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 with automatic type mapping
BasicTable table3 = new BasicTable();
table3.addColumn("id", new Integer[]{1, 2, 3});
table3.addColumn("name", new String[]{"a", "b", "c"});