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
8

# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --location --request POST \
     'http://<db.host>:9191/show/system/properties' \
     --user <username>:<password> \
     --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
8

# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --location --request POST \
     'https://<db.host>:8082/gpudb-0/show/system/properties' \
     --user <username>:<password> \
     --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
9

# Example call invoking the /show/system/properties endpoint
#   and requesting the database's version number
curl --location --request POST \
     'https://<db.host>:8082/gpudb-0/show/system/properties' \
     --user <username>:<password> \
     --data '{"options": {"properties": "version.gpudb_core_version"}}' \
     --insecure \
     --header 'cache-control: no-cache' \
     --header 'content-type: application/json'

HTTPS Connections with OIDC/OAuth Authentication

C++ 
1
2
3
4
5
6

#include "gpudb/GPUdb.hpp"

gpudb::GPUdb::Options options = gpudb::GPUdb::Options();
options.setOauthToken("<oauthToken>");

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

using kinetica;

Kinetica.Options options = new Kinetica.Options();
options.OauthToken = "<oauthToken>";

Kinetica kinetica = new Kinetica("https://<db.host>:8082/gpudb-0", options );
Java 
1
2
3
4
5
6

import com.gpudb.GPUdb;

GPUdb.Options options = new GPUdb.Options()
    .setOauthToken("<oauthToken>");

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

<script type="text/javascript" src="GPUdb.js"></script>
<script type="text/javascript">
var kinetica = new GPUdb(
    "https://<db.host>:8082/gpudb-0",
    {
        oauth_token: "<oauthToken>"
    }
);
</script>
Node.js 
1
2
3
4
5
6
7
8

// 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"],
    {
        oauth_token: "<oauthToken>"
    }
);
Python 
1
2
3
4
5
6
7
8
9

import gpudb

options = gpudb.GPUdb.Options()
options.oauth_token = "<oauthToken>"

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 --location --request POST \
     'https://<db.host>:8082/gpudb-0/show/system/properties' \
     --oauth2-bearer "<token>" \
     --data '{"options": {"properties": "version.gpudb_core_version"}}' \
     --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.