Note

This documentation is for a prior release of Kinetica. For the latest documentation, click here.

C++ Developer Guide

Step-by-step instructions on writing C++ applications with Kinetica

The following guide provides step-by-step instructions to get started writing C++ applications using Kinetica. This guide demonstrates only a small set of the available API. A detailed description of the complete interface is available under C++ API Reference.

API Download

The source code for the C++ API is available for download from the GitHub repository kineticadb/kinetica-api-cpp. Follow the instructions in the included README file to build the API library.

Connecting to the Database

To connect to the database, instantiate an object of the GPUdb class, providing the connection URL of the database server:

1
gpudb::GPUdb h_db("http://localhost:9191;CombinePrepareAndExecute=1;RowsPerFetch=20000");

Loading Data

Before any data can be loaded into the system, a Type needs to be defined in the system. The type definition is a JSON string describing the fields (i.e. columns) of the type along with a name for the type. Each field consists of a name and a data type:

1
2
3
4
5
6
7
8
9
const std::string COL_1 = "col1";
const std::string COL_2 = "col2";
const std::string COL_GROUP_ID = "group_id";

std::vector<gpudb::Type::Column> columns;
columns.push_back(gpudb::Type::Column(COL_1, avro::AVRO_DOUBLE));
columns.push_back(gpudb::Type::Column(COL_2, avro::AVRO_STRING));
columns.push_back(gpudb::Type::Column(COL_GROUP_ID,avro::AVRO_STRING));
gpudb::Type myType("my_type_1", columns);
1
std::string type_id_1 = myType.create(h_db);

The returned object from the Type.create() call contains a unique type identifier allocated by the system. This identifier can then be used in the request to create a new table as follows:

1
gpudb::CreateTableResponse response = h_db.createTable(my_table, type_id_1, options);

Once the table is created, data can be inserted as follows:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
std::map<std::string, std::string> options;
std::vector<gpudb::GenericRecord> record_list;
for (int i = start ; i < end ; i++)
{
    gpudb::GenericRecord datum(myTypeSchema);
    datum.setAsDouble(COL_1,i + col1_const);
    datum.setAsString(COL_2,ostr.str());
    record_list.push_back(datum);
}
options["return_record_ids"] = "true";  // optionally request record_ids
gpudb::InsertRecordsResponse response = h_db.insertRecords(my_table, record_list, options);

Retrieving Data

Once the table is populated with data, the data can be retrieved from the system by a call to getRecords() as shown below:

1
2
3
4
5
6
gpudb::GetRecordsResponse<gpudb::GenericRecord> response = h_db.getRecords<gpudb::GenericRecord>(myType, my_table, 0, 100, options);
for(unsigned int i = 0 ; i < response.data.size() ; ++i)
{
    const gpudb::GenericRecord& record = response.data[i];
    double d = record.getAsDouble(COL_1);
}

For large tables, the data can be easily be retrieved in smaller blocks by using the offset and limit parameters. The returned response also contains the schema (or data type) of the results.

Running Queries

To filter a subset of the records, use the filter() method with an expression as follows:

1
2
3
std::string my_view("my_view_1");
my_filterExpr="col1 <= 9 and group_id=\"Group 1\"";
gpudb::FilterResponse filter_resp = h_db.filter(my_table, my_view, my_filterExpr, options);

To filter all the records matching a known list of values:

1
2
3
4
5
6
std::string my_view2("my_view_2");
std::map<std::string, std::vector<std::string> > my_filterList;
my_filterList["col1"].push_back("1.1");
my_filterList["col1"].push_back("2.1");
my_filterList["col1"].push_back("5.1");
gpudb::FilterByListResponse filterByList_resp = h_db.filterByList(my_view, my_view2, my_filterList, options);

To retrieve a list of all the unique values for a column or a set of columns or expression:

1
2
3
4
5
6
7
gpudb::AggregateUniqueResponse aggrUniq_resp = h_db.aggregateUnique(my_table, COL_GROUP_ID, 0, 100, options);
std::cout << "Unique values in group_id column " << aggrUniq_resp.data.size() << std::endl;
std::cout << "Schema " << aggrUniq_resp.responseSchemaStr << std::endl;
for (size_t i = 0 ; i < aggrUniq_resp.data.size(); ++i )
{
    std::cout << '"' << record.value<std::string>(0) << "\", ";
}

Kinetica supports various group-by queries. To group by one or more columns and return the count of the unique values, use the aggregateGroupBy() method as shown below. The next query shows how to get the count of records, as well as the sum and average of the values of column col1, within each group:

1
2
3
4
5
6
7
8
std::vector<std::string> col_names;
col_names.push_back("group_id");
gpudb::AggregateGroupByResponse aggrGB_resp = h_db.aggregateGroupBy(my_table, col_names, 0, 100, options);

col_names.push_back("count(*)");
col_names.push_back("sum(col1)");
col_names.push_back("avg(col1)");
aggrGB_resp = h_db.aggregateGroupBy(my_table, col_names, 0, 100, options);

Kinetica supports grouping numerical data into a histogram. The input range is divided into equal sized bins and the count of objects in each bin are returned:

1
2
3
4
double range_start = 0.0;
double range_end   = 11;
double interval    = 1;
gpudb::AggregateHistogramResponse aggrHist_resp = h_db.aggregateHistogram(my_table, "col1", range_start, range_end, interval, options);

Complete Sample

Included below is a complete sample program containing all the above queries:

  1
  2
  3
  4
  5
  6
  7
  8
  9
 10
 11
 12
 13
 14
 15
 16
 17
 18
 19
 20
 21
 22
 23
 24
 25
 26
 27
 28
 29
 30
 31
 32
 33
 34
 35
 36
 37
 38
 39
 40
 41
 42
 43
 44
 45
 46
 47
 48
 49
 50
 51
 52
 53
 54
 55
 56
 57
 58
 59
 60
 61
 62
 63
 64
 65
 66
 67
 68
 69
 70
 71
 72
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
#include <iostream>
#include <GPUdb.hpp>


const std::string COL_1 = "col1";
const std::string COL_2 = "col2";
const std::string COL_GROUP_ID = "group_id";
const std::string STR_GROUP_1_CONST = "Group 1";
const std::string STR_GROUP_2_CONST = "Group 2";
const std::string my_table("my_table_1");


// helper functions prototypes
void print_GetRecordsResponse(const gpudb::GetRecordsResponse<gpudb::GenericRecord>&);
void insertRecordsLocal(gpudb::GPUdb& h_db, gpudb::Type myTypeSchema, int start, int end, double col1_const, std::string col2_const, std::string group_id_const, bool display_record_ids = false);


int main(int argc, char *argv[])
{
    std::map<std::string, std::string> options;


    gpudb::GPUdb h_db("http://localhost:9191;CombinePrepareAndExecute=1;RowsPerFetch=20000");


    std::vector<gpudb::Type::Column> columns;

    columns.push_back(gpudb::Type::Column(COL_1, gpudb::Type::Column::ColumnType::DOUBLE));
    columns.push_back(gpudb::Type::Column(COL_2, gpudb::Type::Column::ColumnType::STRING));
    columns.push_back(gpudb::Type::Column(COL_GROUP_ID, gpudb::Type::Column::ColumnType::STRING));
    gpudb::Type myType("my_type_1", columns);

    std::string type_id_1 = myType.create(h_db);
    std::cout << "GPUdb generated type id for the new type -  " << type_id_1 << std::endl;

    try
    {
        gpudb::CreateTableResponse response = h_db.createTable(my_table, type_id_1, options);
    }
    catch (const std::exception& ex)
    {
        std::cout << "Caught Exception: " << ex.what() << std::endl;
        return 10;
    }


    try
    {
        // Insert some records into the table
        insertRecordsLocal(h_db, myType, 1, 10, 0.1, "string ", STR_GROUP_1_CONST, true);

        // Call the helper function to Retrieve records from the table
        gpudb::GetRecordsResponse<gpudb::GenericRecord> response = h_db.getRecords<gpudb::GenericRecord>(myType, my_table, 0, 100, options);
        print_GetRecordsResponse(response);

        // Filter the records by an expression into a view
        std::string my_view("my_view_1");
        std::string my_filterExpr("col1=1.1");
        gpudb::FilterResponse filter_resp = h_db.filter(my_table, my_view, my_filterExpr, options);
        std::cout << "Number of records returned by filter expression: " << filter_resp.count << std::endl;

        // Retrieve records from the view
        response = h_db.getRecords<gpudb::GenericRecord>(myType, my_view, 0, 100, options);
        print_GetRecordsResponse(response);

        // Drop the view (same function as dropping a table)
        gpudb::ClearTableResponse clrTbl_Resp = h_db.clearTable(my_view, "", options);

        // Apply a filter condition with two columns
        my_filterExpr = "col1 <= 9 and group_id=\"Group 1\"";
        filter_resp = h_db.filter(my_table, my_view, my_filterExpr, options);
        std::cout << "Number of records returned by second filter expression: " << filter_resp.count << std::endl;

        response = h_db.getRecords<gpudb::GenericRecord>(myType, my_view, 0, 100, options);
        print_GetRecordsResponse(response);

        // Filter by a list of values.  Note also query chaining - query run on another view.
        std::string my_view2("my_view_2");
        std::map<std::string, std::vector<std::string> > my_filterList;
        my_filterList["col1"].push_back("1.1");
        my_filterList["col1"].push_back("2.1");
        my_filterList["col1"].push_back("5.1");
        gpudb::FilterByListResponse filterByList_resp = h_db.filterByList(my_view, my_view2, my_filterList, options);
        std::cout << "Number of records returned by filter by list expression " << filterByList_resp.count << std::endl;

        response = h_db.getRecords<gpudb::GenericRecord>(myType, my_view2, 0, 100, options);
        print_GetRecordsResponse(response);

        // Filter by a range
        std::string my_view3("my_view_3");
        gpudb::FilterByRangeResponse filterByRange_resp = h_db.filterByRange(my_view, my_view3, COL_1, 1, 5, options);
        std::cout << "Number of records returned by filter by range expression " << filterByRange_resp.count << std::endl;

        response = h_db.getRecords<gpudb::GenericRecord>(myType, my_view3, 0, 100, options);
        print_GetRecordsResponse(response);

        // Insert New Records
        insertRecordsLocal(h_db, myType, 1, 8, 10.1, "string ", STR_GROUP_2_CONST);

        // Retrieve unique values for a column
        gpudb::AggregateUniqueResponse aggrUniq_resp = h_db.aggregateUnique(my_table, COL_GROUP_ID, 0, 100, options);
        std::cout << "Unique values in group_id column " << aggrUniq_resp.data.size() << std::endl;
        std::cout << "Schema " << aggrUniq_resp.responseSchemaStr << std::endl;
        for (size_t i = 0; i < aggrUniq_resp.data.size(); ++i)
        {
            const gpudb::DynamicTableRecord& record = aggrUniq_resp.data[i];

            // already know the returned column and its type ; just print it.
            assert(record.getFieldCount() == 1);
            std::cout << '"' << record.value<std::string>(0) << "\", ";
        }

        // "Group by" query
        std::cout << "Calling aggregateGroupBy on a single column. ";
        std::vector<std::string> col_names;
        col_names.push_back(COL_2);
        gpudb::AggregateGroupByResponse aggrGB_resp = h_db.aggregateGroupBy(my_table, col_names, 0, 100, options);
        std::cout << "Number of unique values in col2  " << aggrGB_resp.data.size() << std::endl;
        std::cout << "Schema " << aggrGB_resp.responseSchemaStr << std::endl;

        for (size_t i = 0; i < aggrGB_resp.data.size(); ++i)
        {
            const gpudb::DynamicTableRecord& record = aggrGB_resp.data[i];

            assert(record.getFieldCount() == 2);
            std::cout << '"' << record.value<std::string>(0) << '"';
            std::cout << ':' << record.getAsDouble(1) << std::endl;
        }


        std::cout << "Calling aggregateGroupBy to retrieve stats on a column. ";
        col_names.clear();
        col_names.push_back(COL_GROUP_ID);
        col_names.push_back("count(*)");
        col_names.push_back("sum(col1)");
        col_names.push_back("avg(col1)");
        aggrGB_resp = h_db.aggregateGroupBy(my_table, col_names, 0, 100, options);
        std::cout << "Number of unique values in group_id column " << aggrGB_resp.data.size() << std::endl;

        // std::cout << "Schema " << aggrGB_resp.responseSchemaStr << std::endl;

        // Parse the group by response.
        const gpudb::GenericRecord& rec1 = aggrGB_resp.data[0];

        for (size_t j = 0; j < rec1.getType().getColumnCount(); j++)
        {
            std::cout << rec1.getType().getColumn(j).getName() << '\t';
        }
        std::cout << std::endl;

        // print the values from the response
        for (size_t i = 0; i < aggrGB_resp.data.size(); ++i)
        {
            const gpudb::DynamicTableRecord& record = aggrGB_resp.data[i];
            assert(record.getFieldCount() == col_names.size());

            for (size_t j = 0; j < record.getType().getColumnCount(); j++)
            {
                switch (record.getType().getColumn(j).getType())
                {

                case gpudb::Type::Column::STRING:
                    std::cout << '"' << record.value<std::string>(j) << "\"\t";
                    break;

                case gpudb::Type::Column::DOUBLE:
                    std::cout << record.getAsDouble(j) << '\t';
                    break;

                case gpudb::Type::Column::FLOAT:
                    std::cout << record.getAsFloat(j) << '\t';
                    break;

                case gpudb::Type::Column::INT:
                    std::cout << record.getAsInt(j) << '\t';
                    break;

                case gpudb::Type::Column::LONG:
                    std::cout << record.getAsLong(j) << '\t';
                    break;

                default:
                    std::cout << "!Unhandled Type!" << '\t';
                }
            }
            std::cout << std::endl;
        }

        // expressions in group by
        std::cout << "Calling aggregateGroupBy for an expression. ";
        col_names.clear();
        col_names.push_back(COL_GROUP_ID);
        col_names.push_back("sum(col1*10)");
        aggrGB_resp = h_db.aggregateGroupBy(my_table, col_names, 0, 100, options);
        std::cout << "Unique values in group_id column " << aggrGB_resp.data.size() << std::endl;
         std::cout << "Schema " << aggrGB_resp.responseSchemaStr << std::endl;

        const gpudb::DynamicTableRecord& rec2 = aggrGB_resp.data[0];
        for (size_t j = 0; j < rec2.getType().getColumnCount(); j++)
        {
            std::cout << rec2.getType().getColumn(j).getName() << '\t';
        }
        std::cout << std::endl;

        for (size_t i = 0; i < aggrGB_resp.data.size(); ++i)
        {
            const gpudb::DynamicTableRecord& record = aggrGB_resp.data[i];
            assert(record.getFieldCount() == col_names.size());

            for (size_t j = 0; j < record.getType().getColumnCount(); j++)
            {
                switch (record.getType().getColumn(j).getType())
                {
                case gpudb::Type::Column::STRING:
                    std::cout << '"' << record.value<std::string>(j) << "\"\t";
                    break;

                case gpudb::Type::Column::DOUBLE:
                    std::cout << record.getAsDouble(j) << '\t';
                    break;

                case gpudb::Type::Column::FLOAT:
                    std::cout << record.getAsFloat(j) << '\t';
                    break;

                case gpudb::Type::Column::INT:
                    std::cout << record.getAsInt(j) << '\t';
                    break;

                case gpudb::Type::Column::LONG:
                    std::cout << record.getAsLong(j) << '\t';
                    break;

                default:
                    std::cout << "!Unhandled Type!" << '\t';
                }
            }
            std::cout << std::endl;
        }

        // Insert few more records
        insertRecordsLocal(h_db, myType, 4, 10, 0.6, "string 2", STR_GROUP_1_CONST);

        // Aggregate Histogram
        std::cout << "Calling aggregateHistogram. ";
        double range_start = 0.0;
        double range_end = 11;
        double interval = 1;
        gpudb::AggregateHistogramResponse aggrHist_resp = h_db.aggregateHistogram(my_table, COL_1, range_start, range_end, interval, options);
        std::cout << "Num Histogram bins: " << aggrHist_resp.counts.size()
            << "  Start: " << aggrHist_resp.start
            << "  end: " << aggrHist_resp.end << std::endl;
        std::cout << "Count per bin - ";
        std::copy(aggrHist_resp.counts.begin(), aggrHist_resp.counts.end(), std::ostream_iterator<int>(std::cout, ", "));
        std::cout << std::endl;

    }
    catch (const std::exception& ex)
    {
        std::cout << "Caught Exception: " << ex.what() << std::endl;
        return 1;
    }

return 0;
    }


// Helper functions

// Insert new records to the table

void insertRecordsLocal(gpudb::GPUdb& h_db, gpudb::Type myTypeSchema, int start, int end, double col1_const, std::string col2_const, std::string group_id_const, bool display_record_ids)
{
    std::map<std::string, std::string> options;
    std::vector<gpudb::GenericRecord> record_list;
    for (int i = start; i < end; i++)
    {
        gpudb::GenericRecord datum(myTypeSchema);
        datum.setAsDouble(COL_1,i + col1_const);
        std::ostringstream ostr;
        ostr << col2_const << i;
        datum.setAsString(COL_2,ostr.str());
        datum.setAsString(COL_GROUP_ID,group_id_const);
        record_list.push_back(datum);
    }
    options["return_record_ids"] = "true";  // optionally request record_ids
    gpudb::InsertRecordsResponse response = h_db.insertRecords(my_table, record_list, options);
    options.clear();

    if (display_record_ids)
    {
        std::cout << "Record Ids for " << response.countInserted << " new records - [";
        std::copy(response.recordIds.begin(), response.recordIds.end() - 1, std::ostream_iterator<std::string>(std::cout, "', '"));
        std::cout << "'" << *(response.recordIds.end() - 1) << "']" << std::endl;
    }
    else
    {
        std::cout << response.countInserted << " new records inserted." << std::endl;
    }

}

// Print the records from the table
void print_GetRecordsResponse(const gpudb::GetRecordsResponse<gpudb::GenericRecord>& response)
{
    // std::cout << "response schema - " << response.typeSchema << std::endl;
    for (unsigned int i = 0; i < response.data.size(); ++i)
    {
        const gpudb::GenericRecord& record = response.data[i];
        std::cout << "\"" << COL_1 << "\":" << record.getAsDouble(COL_1)
            << ", \"" << COL_2 << "\":\"" << record.getAsString(COL_2) << std::flush
            << "\", \"" << COL_GROUP_ID << "\":\"" << record.getAsString(COL_GROUP_ID) << "\"\n";
    }

}

Output from above sample program

| GPUdb generated type id for the new type -  460479593343997452
| Record Ids for 9 new records - [0010000010e00000_0000000000000000', '0010000010e00000_0000000000000001', '0010000010e00000_0000000000000002', '0010000010e00000_0000000000000003', '0010000010e00000_0000000000000004', '0010000010e00000_0000000000000005', '0010000010e00000_0000000000000006', '0010000010e00000_0000000000000007', ''0010000010e00000_0000000000000008']
| "col1":1.1, "col2":"string 1", "group_id":"Group 1"
| "col1":2.1, "col2":"string 2", "group_id":"Group 1"
| "col1":3.1, "col2":"string 3", "group_id":"Group 1"
| "col1":4.1, "col2":"string 4", "group_id":"Group 1"
| "col1":5.1, "col2":"string 5", "group_id":"Group 1"
| "col1":6.1, "col2":"string 6", "group_id":"Group 1"
| "col1":7.1, "col2":"string 7", "group_id":"Group 1"
| "col1":8.1, "col2":"string 8", "group_id":"Group 1"
| "col1":9.1, "col2":"string 9", "group_id":"Group 1"
| Number of records returned by filter expression: 1
| "col1":1.1, "col2":"string 1", "group_id":"Group 1"
| Number of records returned by second filter expression: 8
| "col1":1.1, "col2":"string 1", "group_id":"Group 1"
| "col1":2.1, "col2":"string 2", "group_id":"Group 1"
| "col1":3.1, "col2":"string 3", "group_id":"Group 1"
| "col1":4.1, "col2":"string 4", "group_id":"Group 1"
| "col1":5.1, "col2":"string 5", "group_id":"Group 1"
| "col1":6.1, "col2":"string 6", "group_id":"Group 1"
| "col1":7.1, "col2":"string 7", "group_id":"Group 1"
| "col1":8.1, "col2":"string 8", "group_id":"Group 1"
| Number of records returned by filter by list expression 3
| "col1":1.1, "col2":"string 1", "group_id":"Group 1"
| "col1":2.1, "col2":"string 2", "group_id":"Group 1"
| "col1":5.1, "col2":"string 5", "group_id":"Group 1"
| Number of records returned by filter by range expression 4
| "col1":1.1, "col2":"string 1", "group_id":"Group 1"
| "col1":2.1, "col2":"string 2", "group_id":"Group 1"
| "col1":3.1, "col2":"string 3", "group_id":"Group 1"
| "col1":4.1, "col2":"string 4", "group_id":"Group 1"
| 7 new records inserted.
| Unique values in group_id column 2
| "Group 1", "Group 2", Calling aggregateGroupBy on a single column. Number of unique values in col2  9
| "string 1":2
| "string 2":2
| "string 3":2
| "string 4":2
| "string 5":2
| "string 6":2
| "string 7":2
| "string 8":1
| "string 9":1
| Calling aggregateGroupBy to retrieve stats on a column. Number of unique values in group_id column 2
| group_id      count(*)        sum(col1)       avg(col1)
| "Group 1"     9       45.9    0
| "Group 2"     7       98.7    0
| Calling aggregateGroupBy for an expression. Unique values in group_id column 2
| group_id      sum(col1*10)
| "Group 1"     459
| "Group 2"     987
| 6 new records inserted.
| Calling aggregateHistogram. Num Histogram bins: 11  Start: 0  end: 11
| Count per bin - 0, 1, 1, 1, 2, 2, 2, 2, 2, 2, 0,