Table

Table is a database object that holds a list of vectors in a given order. This section describes how to create, access, and modify tables, along with examples.

Creating Tables

The DolphinDB C++ API provides two methods (createTable defined in the header <Util.h>) for creating tables:

(1) The following is the syntax to declare a table with names and data types specified for each column:

static Table* createTable(const vector<string>& colNames, const vector<DATA_TYPE>& colTypes, INDEX size, INDEX capacity, const vector<int>& extraParams = {});

Arguments

  • colNames: The names for each column.
  • colTypes: The data types for each column.
  • size: The initial size (in terms of the number of rows) of the table.
  • capacity: The amount of memory (in terms of the number of rows) allocated to the table.
  • extraParam: It determines the scale for values in a matrix of DECIMAL type.

Examples

vector<string> colNames{"col1", "col2", "col3"};
vector<DATA_TYPE> colTypes{DT_INT, DT_BOOL, DT_STRING};
TableSP tbl = Util::createTable(colNames, colTypes, 0, 100);

(2) The following is the syntax to declare a table with names and vectors specified for each column:

static Table* createTable(const vector<string>& colNames, const vector<ConstantSP>& cols);

Arguments

  • colNames: The names for each column.
  • colTypes: A list of vectors, where each vector defines the values for a single column. Note that all vectors must be of the same length.

Examples

vector<string> colNames{"col1", "col2", "col3"};
vector<ConstantSP> cols;
cols.emplace_back(Util::createVector(DT_INT, 0));
cols.emplace_back(Util::createVector(DT_BOOL, 0));
cols.emplace_back(Util::createVector(DT_STRING, 0));
TableSP tbl = Util::createTable(colNames, cols);

Accessing Tables

The DolphinDB C++ API provides two methods to retrieve data from a table:

(1) By column

Use function getColumn to obtain a vector (i.e., a column) from the table. For further retrieving entries from a column, see Accessing Vectors. The function declarations are as follows:

ConstantSP getColumn(const string& name) const;           //get the column with the name 'name'
ConstantSP getColumn(INDEX index) const;                  //get the index (starts at 0) column

Examples

VectorSP col1 = tbl->getColumn(0);        // get the first column (with index 0)
VectorSP col2 = tbl->getColumn("col2");   // get the column with name 'col2'

(2) By row

There are two ways to retrieve data from a table by row.

a. Use the get function to get the index (starts at 0) row of the table. It returns a dictionary with column names as keys and entry values as values. The function declaration is as follows:

ConstantSP get(INDEX index) const;

Examples

DictionarySP row = tbl->get(0);
std::cout << row->getMember("col1")->getInt() << std::endl;
std::cout << row->getMember("col3")->getString() << std::endl;

b. Use class ResultSet defined in the header <Util.h>.

ResultSet resultSet(tbl);
while (!resultSet.isAfterLast()) {
        int colIndex = 0;
        std::cout << resultSet.getInt(colIndex++) << " ";
        std::cout << int(resultSet.getBool(colIndex++)) << " ";
        std::cout << resultSet.getString(colIndex++) << std::endl;
        resultSet.next();
}

Appending Data to a Table

The DolphinDB C++ API provides two methods for appending data to a vector:

(1) Use the append function to add rows to the end of a table. The function declaration is as follows:

bool append(vector<ConstantSP>& values, INDEX& insertedRows, string& errMsg);

Arguments

  • values: In-parameter. The values to be appended. It can be a list of equal-length vectors with data types matching each column, or a table with identical schema to the original table.
  • insertedRows: Out-parameter. The number of rows that have been successfully inserted.
  • errMsg: Out-parameter. The error message for the failed insert operation.

Return Values

A boolean value indicating whether data is appended successfully.

Examples

INDEX insertedRows;
std::string errorMsg;
VectorSP col0 = Util::createVector(DT_INT, 0);
VectorSP col1 = Util::createVector(DT_BOOL, 0);
VectorSP col2 = Util::createVector(DT_STRING, 0);
col0->append(Util::createInt(1));
col1->append(Util::createBool(true));
col2->append(Util::createString("123"));
vector<ConstantSP> values{col0, col1, col2};
tbl->append(values, insertedRows, errorMsg)                   //values is a list of vectors, where each vector corresponds to 'col0', 'col1', 'col2'
    
TableSP tbl2 = tbl->getValue();
values= {tbl2};
tbl->append(tempCols, insertedRows, errorMsg);                //values is a table

(2) Use the getColumn function to obtain vectors (i.e., a columns) from the table, append data to each vector, and then call the BasicTable::updateSize() function to update the number of rows.

Example

VectorSP col0 = tbl->getColumn(0);
VectorSP col1 = tbl->getColumn(1);
VectorSP col2 = tbl->getColumn(2);

col0->append(Util::createInt(1));
col1->append(Util::createBool(true));
col2->append(Util::createString("123"));
dynamic_cast<BasicTable*>(tbl.get())->updateSize();