OpenText Analytics Database 26.2.x – C++ SDK

Extending: Setting up the C++ SDK

Mon, 01 Jan 0001 00:00:00 +0000

The OpenText™ Analytics Database C++ Software Development Kit (SDK) is distributed as part of the server installation. It contains the source and header files you need to create your UDx library. For examples that you can compile and run, see Downloading and running UDx example code.

Requirements

At a minimum, install the following on your development machine:

gcc version 8 or higher. OpenText™ Analytics Database has not tested UDx builds with versions higher than 9.
g++ and its associated toolchain, such as ld. Some Linux distributions package g++ separately from gcc.
A copy of the OpenText™ Analytics Database SDK.

Note

The database binaries are compiled using the default version of g++ installed on the supported Linux platforms.

You must compile with a std flag value of c++11 or later.

The following optional software packages can simplify development:

make, or some other build-management tool.
gdb, or some other debugger.
Valgrind, or similar tools that detect memory leaks.

If you want to use any third-party libraries, such as statistical analysis libraries, you need to install them on your development machine. If you do not statically link these libraries into your UDx library, you must install them on every node in the cluster. See Compiling your C++ library for details.

SDK files

The SDK files are located in the sdk subdirectory under the root database server directory (usually, /opt/vertica/sdk). This directory contains a subdirectory, include, which contains the headers and source files needed to compile UDx libraries.

There are two files in the include directory you need when compiling your UDx:

Vertica.h is the main header file for the SDK. Your UDx code needs to include this file in order to find the SDK's definitions.
Vertica.cpp contains support code that needs to be compiled into the UDx library.

Much of the database SDK API is defined in the VerticaUDx.h header file (which is included by the Vertica.h file). If you're curious, you might want to review the contents of this file in addition to reading the API documentation.

Finding the current SDK version

You must develop your UDx using the same SDK version as the database in which you plan to use it. To display the SDK version currently installed on your system, run the following command in vsql:

=> SELECT sdk_version();

Running the examples

You can download the examples from the GitHub repository (see Downloading and running UDx example code). Compiling and running the examples helps you to ensure that your development environment is properly set up.

To compile all of the examples, including the Java examples, issue the following command in the Java-and-C++ directory under the examples directory:

$ make

Note

To compile the examples, you must have a g++ development environment installed. To install a g++ development environment on Red Hat systems, run yum install gcc gcc-c++ make.

Extending: Compiling your C++ library

Mon, 01 Jan 0001 00:00:00 +0000

GNU g++ is the only supported compiler for compiling UDx libraries. Always compile your UDx code on the same version of Linux that you use on your OpenText™ Analytics Database cluster.

When compiling your library, you must always:

Compile with a -std flag value of c++11 or later.
Pass the -shared and -fPIC flags to the linker. The simplest method is to just pass these flags to g++ when you compile and link your library.
Use the -Wno-unused-value flag to suppress warnings when macro arguments are not used. If you do not use this flag, you may get "left-hand operand of comma has no effect" warnings.
Compile sdk/include/Vertica.cpp and link it into your library. This file contains support routines that help your UDx communicate with the database. The easiest way to do this is to include it in the g++ command to compile your library. The database supplies this file as C++ source rather than a library to limit library compatibility issues.
Add the OpenText™ Analytics Database SDK include directory in the include search path using the g++ -I flag.

The SDK examples include a working makefile. See Downloading and running UDx example code.

Example of compiling a UDx

The following command compiles a UDx contained in a single source file named MyUDx.cpp into a shared library named MyUDx.so:

g++ -I /opt/vertica/sdk/include -Wall -shared -Wno-unused-value \
      -fPIC -o MyUDx.so MyUDx.cpp /opt/vertica/sdk/include/Vertica.cpp

Important

The database only supports UDx development on 64-bit architectures.

After you debug your UDx, you are ready to deploy it. Recompile your UDx using the -O3 flag to enable compiler optimization.

You can add additional source files to your library by adding them to the command line. You can also compile them separately and then link them together.

Tip

The examples subdirectory in the Vertica SDK directory contains a make file that you can use as starting point for your own UDx project.

Handling external libraries

You must link your UDx library to any supporting libraries that your UDx code relies on.These libraries might be either ones you developed or others provided by third parties. You have two options for linking:

Statically link the support libraries into your UDx. The benefit of this method is that your UDx library does not rely on external files. Having a single UDx library file simplifies deployment because you just transfer a single file to your database cluster. This method's main drawback is that it increases the size of your UDx library file.
Dynamically link the library to your UDx. You must sometimes use dynamic linking if a third-party library does not allow static linking. In this case, you must copy the libraries to your database cluster in addition to your UDx library file.

Extending: Adding metadata to C++ libraries

Mon, 01 Jan 0001 00:00:00 +0000

You can add metadata, such as author name, the version of the library, a description of your library, and so on to your library. This metadata lets you track the version of your function that is deployed on a Vertica Analytic Database cluster and lets third-party users of your function know who created the function. Your library's metadata appears in the USER_LIBRARIES system table after your library has been loaded into the Vertica Analytic Database catalog.

You declare the metadata for your library by calling the RegisterLibrary() function in one of the source files for your UDx. If there is more than one function call in the source files for your UDx, whichever gets interpreted last as Vertica Analytic Database loads the library is used to determine the library's metadata.

The RegisterLibrary() function takes eight string parameters:

RegisterLibrary(author,
                library_build_tag,
                library_version,
                library_sdk_version,
                source_url,
                description,
                licenses_required,
                signature);

author contains whatever name you want associated with the creation of the library (your own name or your company's name for example).
library_build_tag is a string you want to use to represent the specific build of the library (for example, the SVN revision number or a timestamp of when the library was compiled). This is useful for tracking instances of your library as you are developing them.
library_version is the version of your library. You can use whatever numbering or naming scheme you want.
library_sdk_version is the version of the Vertica Analytic Database SDK Library for which you've compiled the library.

Note
This field isn't used to determine whether a library is compatible with a version of the Vertica Analytic Database server. The version of the Vertica Analytic Database SDK you use to compile your library is embedded in the library when you compile it. It is this information that Vertica Analytic Database server uses to determine if your library is compatible with it.
source_url is a URL where users of your function can find more information about it. This can be your company's website, the GitHub page hosting your library's source code, or whatever site you like.
description is a concise description of your library.
licenses_required is a placeholder for licensing information. You must pass an empty string for this value.
signature is a placeholder for a signature that will authenticate your library. You must pass an empty string for this value.

For example, the following code demonstrates adding metadata to the Add2Ints example (see C++ example: Add2Ints).

// Register the factory with OpenText&trade; Analytics Database
RegisterFactory(Add2IntsFactory);

// Register the library's metadata.
RegisterLibrary("Whizzo Analytics Ltd.",
                "1234",
                "2.0",
                "7.0.0",
                "http://www.example.com/add2ints",
                "Add 2 Integer Library",
                "",
                "");

Loading the library and querying the USER_LIBRARIES system table shows the metadata supplied in the call to RegisterLibrary():

=> CREATE LIBRARY add2intslib AS '/home/dbadmin/add2ints.so';
CREATE LIBRARY
=> \x
Expanded display is on.
=> SELECT * FROM USER_LIBRARIES WHERE lib_name = 'add2intslib';
-[ RECORD 1 ]-----+----------------------------------------
schema_name       | public
lib_name          | add2intslib
lib_oid           | 45035996273869808
author            | Whizzo Analytics Ltd.
owner_id          | 45035996273704962
lib_file_name     | public_add2intslib_45035996273869808.so
md5_sum           | 732c9e145d447c8ac6e7304313d3b8a0
sdk_version       | v7.0.0-20131105
revision          | 125200
lib_build_tag     | 1234
lib_version       | 2.0
lib_sdk_version   | 7.0.0
source_url        | http://www.example.com/add2ints
description       | Add 2 Integer Library
licenses_required |
signature         |

Extending: C++ SDK data types

Mon, 01 Jan 0001 00:00:00 +0000

The OpenText™ Analytics Database SDK has typedefs and classes for representing the database data types within your UDx code. Using these typedefs ensures data type compatibility between the data your UDx processes and generates and the database. The following table describes some of the typedefs available. Consult the C++ SDK Documentation for a complete list, as well as lists of helper functions to convert and manipulate these data types.

For information about SDK support for complex data types, see Complex Types as Arguments and Return Values.

Type Definition	Description
Interval	An OpenText™ Analytics Database interval
IntervalYM	An OpenText™ Analytics Database year-to-month interval.
Timestamp	An OpenText™ Analytics Database timestamp
vint	A standard OpenText™ Analytics Database 64-bit integer
vbool	A Boolean value in OpenText™ Analytics Database
vbool_null	A null value for a Boolean data types
vfloat	An OpenText™ Analytics Database floating point value
VString	String data types (such as varchar and char) Note: Do not use a VString object to hold an intermediate result. Use a std::string or char[] instead.
VNumeric	Fixed-point data types from OpenText™ Analytics Database
VUuid	An OpenText™ Analytics Database universally unique identifier

Notes

When making some SDK API calls (such as VerticaType::getNumericLength()) on objects, make sure they have the correct data type. To minimize overhead and improve performance, most of the APIs do not check the data types of the objects on which they are called. Calling a function on an incorrect data type can result in an error.
You cannot create instances of VString or VNumeric yourself. You can manipulate the values of existing objects of these classes that the database passes to your UDx, and extract values from them. However, only the database can instantiate these classes.

Extending: Resource use for C++ UDxs

Mon, 01 Jan 0001 00:00:00 +0000

Your UDxs consume at least a small amount of memory by instantiating classes and creating local variables. This basic memory usage by UDxs is small enough that you do not need to be concerned about it.

If your UDx needs to allocate more than one or two megabytes of memory for data structures, or requires access to additional resources such as files, you must inform OpenText™ Analytics Database about its resource use. The database can then ensure that the resources your UDx requires are available before running a query that uses it. Even moderate memory use (10MB per invocation of a UDx, for example) can become an issue if there are many simultaneous queries that call it.

Note

If your UDx allocates its own memory, you must make absolutely sure it properly frees it. Failing to free even a single byte of allocated memory can have significant consequences at scale. Instead of having your code allocate its own memory, you should use the C++ vt_alloc macro, which uses the database's own memory manager to allocate and track memory. This memory is guaranteed to be properly disposed of when your UDx completes execution. See Allocating resources for UDxs for more information.