Adding Metadata to C++ Libraries

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 an 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);

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

// Include the top-level Vertica SDK file
#include "Vertica.h"
// Using the Vertica namespace means we don't have to prefix all
// class references with Vertica:: 
using namespace Vertica;
/* 
* ScalarFunction implementation for a UDSF that adds 
* two numbers together. 
*/

class Add2Ints : public ScalarFunction
{
public:
  /*
   * This function does all of the actual processing for the UDx.
   * In this case, it simply reads two integer values and returns
   * their sum.   
   *   
   * The inputs are retrieved via arg_reader
   * The outputs are returned via arg_writer
   */
    virtual void processBlock(ServerInterface &srvInterface,
                            BlockReader &arg_reader,
                            BlockWriter &res_writer)
    {
    // While we have input to process
    do
      {
        // Read the two integer input parameters by calling the
        // BlockReader.getIntRef class functionconst
        vint a = arg_reader.getIntRef(0);
        const vint b = arg_reader.getIntRef(1);
        // Call BlockWriter.setInt to store the output value, which is the
        //  two input values added together
        res_writer.setInt(a+b);
        // Finish writing the row, and advance to the next output row
        res_writer.next();
        // Continue looping until there are no more input rows
      }
    while (arg_reader.next());
  }
};

/*
* This class provides metadata about the ScalarFunction class, and
* also instantiates a member of that class when needed.
*/
class Add2IntsFactory : public ScalarFunctionFactory
{
    // return an instance of Add2Ints to perform the actual addition.
    virtual ScalarFunction *createScalarFunction(ServerInterface &interface)
    {
        // Calls the vt_createFuncObj to create the new Add2Ints class instance.
        return vt_createFuncObj(interface.allocator, Add2Ints);
    }
  
    // This function returns the description of the input and outputs of the
    // Add2Ints class's processBlock function.  It stores this information in
    // two ColumnTypes objects, one for the input parameters, and one for
    // the return value.
    virtual void getPrototype(ServerInterface &interface,
                            ColumnTypes &argTypes,
                            ColumnTypes &returnType)
    {
        // Takes two ints as inputs, so add ints to the argTypes object
        argTypes.addInt();
        argTypes.addInt();
        // returns a single int, so add a single int to the returnType object.
        // Note that ScalarFunctions *always* return a single value.
        returnType.addInt();
    }
};

// Register the factory with Vertica
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         |