Native C/C++ API

NitrosBase C/C++ API follows the common practices for database drivers.

A typical database interaction is as follows:

Connect to a server
Query a server
Receive response
Disconnect

After successfully connecting, a connection descriptor is returned that uniquely identifies the current session. This descriptor will be used in all later API calls.

When API is used, raw types and numeric values not wrapped into constants and typedefs should be avoided. Constant values and underlying types may be different on different platforms and in different API versions.

nb_connect

NB_HANDLE nb_connect (
    const char * host,
    int sockport,
    const char * user,
    const char * password
);

Attempts to connect to NitrosBase server.

Parameters:

host — NitrosBase server hostname
sockport — NitrosBase server TCP port
user — NitrosBase server user
password — NitrosBase server user password

Returned value:

If successful, connection descriptor is returned
In case of failure — NB_INVALID_HANDLE is returned

Currently, NitrosBase doesn't support authentication. Any values, including NULL, can be passed as user and password.

nb_disconnect

NB_ERROR_T nb_disconnect (
    NB_HANDLE connection
);

Terminates the connection immediately.

Parameters:

connection — server connection descriptor

Returned value:

NB_SUCCESS (if successful)
error code (in case of failure)

nb_setoption

void nb_setoption (
    NB_HANDLE connection,
    NB_CONN_OPTIONS option,
    int value
);

Allows specification of connection parameters.

Function parameters:

connection — connection descriptor
option — connection parameter to configure
value — the new value for the parameter: 0 or 1 (currently, connection to NitrosBase has boolean settings only).

NB_CONN_OPTIONS — enumeration with the following members:

NB_OPT_STREAMED_RESULT — if 1, the server starts to send a response before full query results are obtained.
In this mode, NBAffectedRows() is not available and always returns 0.
NB_OPT_DATETIME_MICROSECONDS — whether datetime values' precision is microseconds (1) or milliseconds (0);
NB_OPT_AVGINTASDOUBLE — if 1 then avg(intfield) function returns double value, if 0 then avg(intfield) function returns int value (like MSSQL).

nb_errno

NB_ERROR_T nb_errno (
    NB_HANDLE connection
);

Returns code for the latest error associated with the connection.

Parameters:

connection — connection descriptor

Returned value:

NB_SUCCESS — success
NB_ERROR_UNKNOWN = (NB_ERROR | 0) — general error
NB_ERROR_NOT_IMPLEMENTED = (NB_ERROR | 1) — not implemented
NB_ERROR_UNEXPECTED = (NB_ERROR | 2) — unexpected result or state when executing function
NB_ERROR_ARGUMENTS = (NB_ERROR | 3) — incorrect arguments
NB_ERROR_TIMEOUT = (NB_ERROR | 4) — function execution timeout
NB_ERROR_NO\_DATA = (NB_ERROR | 5) — no data; result set is empty

nb_err_text

const char * nb_err_text (
    NB_HANDLE connection
);

Returns text of the latest error associated with the connection.

Parameters:

connection — connection descriptor

Returned value: error text.

nb_execute_sql

NB_ERROR_T nb_execute_sql (
    NB_HANDLE connection,
    const char * query,
    size_t length
);

Performs SQL query on the server.

Parameters:

connection — connection descriptor
query — query text
length — query text length

Returned value:

NB_SUCCESS (if successful)
Error code (in case of failure)

Despite its name, the function can perform not only SQL queries, but also SPARQL queries or other queries in supported languages.

The length parameter is used when the query text contains binary data (e.g., the \0 symbol).

nb_fetch_row

NB_ERROR_T nb_fetch_row (
    NB_HANDLE connection
);

Returns the next result from query result set.

Parameters:

connection — connection descriptor

Returned value:

NB_SUCCESS (if successful)
Error code (in case of failure)

nb_field_count

int nb_field_count (
    NB_HANDLE connection
);

Returns number of fields of the latest record received using nb_fetch_row.

Parameters:

connection — connection descriptor

Returned value:

The number of fields (if successful)
-1 (in case of failure)

The number of fields in the result set is not a constant value. In a graph model, it may vary from one record to another.

nb_field_name

NB_ERROR_T nb_field_name (
    NB_HANDLE connection,
    int fieldnum, NBValue * name
);

Returns field name from the latest element of the result set obtained using nb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (numbering starts from 0)
name — pointer to the NBValue structure that contains result set element

The NBValue structure is defined as follows:

struct NBValue {
 NB_DATA_TYPE type;
 union {
     int intv;
     long long int64v;
     double dbl;
     struct {
         char * str;
         int len;
     };
 };
 bool null;
};

Returned value:

If successful, the function returns NB_SUCCESS and fills the NBValue structure referenced by the name pointer.
In case of failure, the function returns error code.

nb_field_type

NB_DATA_TYPE nb_field_type ( NB_HANDLE connection, int fieldnum );

Returns the scalar value type of field in the latest record obtained using nb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (numbering starts from 0)

Returned value is one of the following:

enum NB_DATA_TYPE {
 NB_DATA_NONE,
 NB_DATA_STRING,
 NB_DATA_INT,
 NB_DATA_INT64,
 NB_DATA_DOUBLE,
 NB_DATA_DATETIME,
 NB_DATA_BOOL,
};

In case of error, the NB_DATA_NONE value is returned.

nb_field_value

NB_ERROR_T nb_field_value (
    NB_HANDLE connection,
    int fieldnum,
    NBValue * v );

Returns value of field in the latest record obtained using nb_fetch_row.

Parameters:

connection — connection descriptor
fieldnum — field number (starting from 0)
v — pointer to the NBValue structure that contains result set element (see the nb_field_name function description)

Returned value:

If successful, returns NB_SUCCESS and fills the NBValue structure referenced by the v pointer.
In case of failure, returns the error code.

nb_get_tableslist

NB_ERROR_T nb_get_tableslist (
    NB_HANDLE connection,
);

Returns the table list (see also INFORMATION_SCHEMA.TABLES pseudo table description)

Parameters:

connection — connection descriptor.

Returned value:

NB_SUCCESS (if successful)
Error code (in case of failure)

After calling this function, one has to call nb_fetch_row, etc., as if a regular query was executed via nb_execute_sql. A result contains two fields:

name — table name;
type — table type (2 — regular table; 3 — link table, see CREATE TABLE AS EDGE).

nb_get_tablesсhema

NB_ERROR_T nb_get_tableschema (
    NB_HANDLE connection,
    const char * table,
    size_t length
);

Returns the table column list (see also INFORMATION_SCHEMA.COLUMNS pseudo table description)

Parameters:

connection — connection descriptor
table — table name
length — table name length

Returned value:

NB_SUCCESS (if successful)
Error code (in case of failure)

After calling this function, one has to call nb_fetch_row, etc., as if a regular query was executed via nb_execute_sql. A result contains five fields:

name — field name;
type — field type:
1 — string,
2 — int,
3 — bigint,
4 — double,
5 — datetime,
6 — bool,
7 — date,
8 — if field is a primary key or a foreign key (and is a string thereafter);
subtype — specifies the previous field:
0 — regular field,
1 — primary key,
2 — foreign key;
linktable — referenced table name for foreign key;
nullable — always TRUE in the current version.

nb_get_indexsсhema

NB_ERROR_T nb_get_indexschema( NB_HANDLE connection );

Returns JSON, containing information about all the indexes in the database

Parameters:

connection — server connection descriptor;

After calling this function, you should call nb_fetch_row, etc. as if a regular query were executed using nb_execute_sql.

The result contains one record with one field containing JSON.

JSON example

[
  {

    "name" : "p_age",
    "table" : "person",
    "fields" : [ "age" ]
  },
  {

    "name" : "p_city",
    "table" : "person",
    "fields" : [ "city" ]
  },
  {

    "name" : "c_model",
    "table" : "car",
    "fields" : [ "model" ]
  }
]

Creating client application

In Microsoft Visual Studio, included directories and library directories have to be configured:

the nitrosbase/include directory has to be added to the included directories list (Project Properties / VC++ Directories > Include Directories)
the nitrosbase/lib and nitrosbase/bin directories have to be added to the library directories list (Project Properties > VC++ Directories > Library Directories)

There are two options to link the client library:

use preprocessor: #pragma comment(lib, "nbclient.lib")
add nbclient.lib to the list of additional libraries (in Visual Studio: Project properties > Linker > Input Additional Dependencies)

← Graph-SQL .NET API →

# Native C/C++ API

# nb_connect

# nb_disconnect

# nb_setoption

# nb_errno

# nb_err_text

# nb_execute_sql

# nb_fetch_row

# nb_field_count

# nb_field_name

# nb_field_type

# nb_field_value

# nb_get_tableslist

# nb_get_tablesсhema

# nb_get_indexsсhema

# Creating client application

Native C/C++ API

nb_connect

nb_disconnect

nb_setoption

nb_errno

nb_err_text

nb_execute_sql

nb_fetch_row

nb_field_count

nb_field_name

nb_field_type

nb_field_value

nb_get_tableslist

nb_get_tablesсhema

nb_get_indexsсhema

Creating client application