API Concepts

Connecting via API

The following shows the means of connecting to Kinetica via the various APIs available.

HTTP Connections

C++
1
2
3
4
5
6
7
#include "gpudb/GPUdb.hpp"

gpudb::GPUdb::Options options = gpudb::GPUdb::Options();
options.setUsername("<username>");
options.setPassword("<password>");

gpudb::GPUdb kinetica("http://<db.host>:9191", options);
C#
1
2
3
4
5
6
7
using kinetica;

Kinetica.Options options = new Kinetica.Options();
options.Username = "<username>";
options.Password = "<password>";

Kinetica kinetica = new Kinetica("http://<db.host>:9191", options );
Java
1
2
3
4
5
6
7
import com.gpudb.GPUdb;

GPUdb.Options options = new GPUdb.Options()
    .setUsername("<username>")
    .setPassword("<password>");

GPUdb kinetica = new GPUdb("http://<db.host>:9191", options);
JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<script type="text/javascript" src="GPUdb.js"></script>
<script type="text/javascript">
var kinetica = new GPUdb(
    "http://<db.host>:9191",
    {
        username: "<username>",
        password: "<password>"
    }
);
</script>
Node.js
1
2
3
4
5
6
7
8
9
// To install Kinetica, first run this from the CLI: npm i @kinetica/gpudb
var GPUdb = require("@kinetica/gpudb");
var kinetica = new GPUdb(
    ["http://<db.host>:9191"],
    {
        username: "<username>",
        password: "<password>"
    }
);
Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import gpudb

options = gpudb.GPUdb.Options()
options.username = "<username>"
options.password = "<password>"

kinetica = gpudb.GPUdb(
    host=["http://<db.host>:9191"],
    options = options
)
REST
1
2
3
4
5
6
7
# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --user <username>:<password> --location --request POST \
    'http://<db.host>:9191/show/system/properties' \
    --data '{"options": {"properties": "version.gpudb_core_version"}}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json'

HTTPS Connections with Certificate Validation

C++
1
2
3
4
5
6
7
#include "gpudb/GPUdb.hpp"

gpudb::GPUdb::Options options = gpudb::GPUdb::Options();
options.setUsername("<username>");
options.setPassword("<password>");

gpudb::GPUdb kinetica("https://<db.host>:8082/gpudb-0", options);
C#
1
2
3
4
5
6
7
using kinetica;

Kinetica.Options options = new Kinetica.Options();
options.Username = "<username>";
options.Password = "<password>";

Kinetica kinetica = new Kinetica("https://<db.host>:8082/gpudb-0", options );
Java
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
import com.gpudb.GPUdb;

GPUdb.Options options = new GPUdb.Options()
    .setUsername("<username>")
    .setPassword("<password>");

// By default, the Java system CA trust store will be used;
//   to specify a different trust store, use these options:
options.setTrustStoreFilePath("</path/to/truststore.jks>");
options.setTrustStorePassword("<trustStorePassword>");

GPUdb kinetica = new GPUdb("https://<db.host>:8082/gpudb-0", options);
JavaScript
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
<script type="text/javascript" src="GPUdb.js"></script>
<script type="text/javascript">
var kinetica = new GPUdb(
    "https://<db.host>:8082/gpudb-0",
    {
        username: "<username>",
        password: "<password>"
    }
);
</script>
Node.js
1
2
3
4
5
6
7
8
9
// To install Kinetica, first run this from the CLI: npm i @kinetica/gpudb
var GPUdb = require("@kinetica/gpudb");
var kinetica = new GPUdb(
    ["https://<db.host>:8082/gpudb-0"],
    {
        username: "<username>",
        password: "<password>"
    }
);
Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
import gpudb

options = gpudb.GPUdb.Options()
options.username = "<username>"
options.password = "<password>"

kinetica = gpudb.GPUdb(
    host=["https://<db.host>:8082/gpudb-0"],
    options = options
)
REST
1
2
3
4
5
6
7
# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --user <username>:<password> --location --request POST \
    'https://<db.host>:8082/gpudb-0/show/system/properties' \
    --data '{"options": {"properties": "version.gpudb_core_version"}}' \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json'

HTTPS Connections without Certificate Validation

Note

Using these setups, no certificate validation of any kind will be performed; not recommended for production deployments.

To bypass certificate checks in JDBC, see Secure Connections. To bypass certificate checks in KiSQL, see Parameterized Options.

Java
1
2
3
4
5
6
7
8
import com.gpudb.GPUdb;

GPUdb.Options options = new GPUdb.Options()
    .setBypassSslCertCheck(true)
    .setUsername("<username>")
    .setPassword("<password>");

GPUdb kinetica = new GPUdb("https://<db.host>:8082/gpudb-0", options);
Python
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
import gpudb

options = gpudb.GPUdb.Options()
options.username = "<username>"
options.password = "<password>"
options.skip_ssl_cert_verification = True

kinetica = gpudb.GPUdb(
    host=["https://<db.host>:8082/gpudb-0"],
    options = options
)
REST
1
2
3
4
5
6
7
8
# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --user <username>:<password> --location --request POST \
    'https://<db.host>:8082/gpudb-0/show/system/properties' \
    --data '{"options": {"properties": "version.gpudb_core_version"}}' \
    --insecure \
    --header 'cache-control: no-cache' \
    --header 'content-type: application/json'


Compatibility Matrix

The following chart shows the version compatibilities between the various APIs and a target database server. While only the major & minor version numbers (6.2, 7.0, 7.1, 7.2) must match to achieve interoperability, the complete feature set for a given database version can only be utilized via the corresponding API version, depicted below.

DatabaseC++C#JavaJavascriptNode.jsPython
6.26.2.*6.2.*6.2.*6.2.*6.2.*6.2.*
7.0.X7.0.X7.0.X7.0.X7.0.X7.0.X7.0.X
7.1.X7.1.X7.1.X7.1.X7.1.X7.1.X7.1.X
7.2.X7.2.X7.2.X7.2.X7.2.X7.2.X7.2.X


Dynamic Schemas

When working with APIs, it is helpful to have an understanding of how data is returned by the database. For a detailed breakdown in Java & Python, see Dynamic Schemas.