Class GPUdbTableMonitor

class gpudb_table_monitor.GPUdbTableMonitor[source]
class Client(db, table_name, callback_list, options=None)[source]

This class is the main client side API class implementing most of the functionalities. Implementing table monitor functions means that this class creates the server side table monitors in Kinetica and also starts listening for different events on those monitors like inserts, deletes and updates. Once the notifications (inserted records, deletions and updates) are received this class will call the different callback methods passed in the constructor.

The intended use of this class is to derive from this and define the different callback methods and pass the callback methods wrapped in different callback objects of the types defined by the class Callback.Type. The callback objects thus created must be passed as a list to the constructor of this class.

A usage that will suffice for most cases has been given in the examples/table_monitor_example.py file. The user is requested to go through the example to get a thorough understanding of how to use this class.

The readme contains the relevant links to navigate directly to the examples provided.

Parameters

db (gpudb.GPUdb) –

The gpudb.GPUdb object which is created external to this class and passed in to facilitate calling different methods of that API. This has to be pre-initialized and must have a valid value. If this is uninitialized then the constructor will raise a gpudb.GPUdbException.

table_name (str) –

The name of the Kinetica table for which a monitor is to be created. This must have a valid value and cannot be an empty string. In case this parameter does not have a valid value, the constructor will raise a gpudb.GPUdbException.

callback_list (list(Callback)) –

List of Callback objects

options (GPUdbTableMonitor.Options) –

The class to encapsulate the various options that can be passed to a Client object to alter the behavior of the monitor instance. The details are given in the GPUdbTableMonitor.Options section.

start_monitor()[source]

This the API called by the client to start the table monitor

This method has to be called to activate the table monitors which have been created in accordance to the callback objects passed in the constructor, whether this class is instantiated directly or a class derived from (Client) is used.

See also

stop_monitor()

stop_monitor()[source]

This API is called by the client to stop the table monitor. This has to be called to stop the table monitor which has been started by the call start_monitor().

Failure to call this method will produce unpredictable results since the table monitors running in the background will not be stopped and cleaned up properly.

See also

start_monitor()

class Options(_dict=None)[source]

Encapsulates the various options used to create a table monitor. The class is initialized with sensible defaults which can be overridden by the users of the class. The following options are supported:

  • inactivity_timeout

    This option controls the time interval to set the timeout to determine when the program would do idle time processing like checking for the table existence, server HA failover, etc., if needed. It is specified in minutes as a float so that seconds can be accommodated as well. The default value is set to 20 minutes, which is converted internally to seconds.

Example usage:

options = GPUdbTableMonitor.Options(_dict=dict(
    inactivity_timeout=0.1
))

Constructor for GPUdbTableMonitor.Options class

Parameters

_dict (dict) –

Optional dictionary with options already loaded. Value can be None; if it is None suitable sensible defaults will be set internally.

Returns

static default()[source]

Create a default set of options for Client

Returns

property inactivity_timeout

This is the getter for the property inactivity_timeout. This is specified in minutes as a float so that seconds can be accommodated. This indicates a timeout interval after which if no notification is received from the server table monitors, the program will check whether everything is alright, like whether the table is still there and in the process will automatically trigger HA failover if needed.

The default value is set to 20 minutes converted to milliseconds.

Returns

The value of the timeout as set in the –

GPUdbTableMonitor.Options instance.

as_json()[source]

Return the options as a JSON

as_dict()[source]

Return the options as a dict

class Callback(callback_type, event_callback, error_callback=None, event_options=None)[source]

Use this class to indicate which type of table monitor is desired.

When the Client is constructed, a list of objects of this class has to be supplied to the constructor of the class.

If the list of callbacks is empty or the list does not contain at least one of the callbacks of types (Callback.Type) INSERT_DECODED, INSERT_RAW, DELETED, or UPDATED, no table monitor would be created internally and the program would raise a gpudb.GPUdbException and exit. So, a list of objects of this class is mandatory for the table monitor to function.

An example of using this class and passing on to the constructor of Client is as follows:

class GPUdbTableMonitorExample(GPUdbTableMonitor.Client):

    def __init__(self, db, table_name, options=None):

        # Create the list of callbacks objects which are to be passed to the
        # GPUdbTableMonitor.Client class constructor

        # This example shows only two callbacks being created so
        # only an insert type table monitor will be created. For other
        # types callback objects could be created similarly to receive
        # notifications about other events.
        callbacks = [
            GPUdbTableMonitor.Callback(GPUdbTableMonitor.Callback.Type.INSERT_RAW,
                                      self.on_insert_raw,
                                      self.on_error),

            GPUdbTableMonitor.Callback(GPUdbTableMonitor.Callback.Type.INSERT_DECODED,
                                      self.on_insert_decoded,
                                      self.on_error,
                                      GPUdbTableMonitor.Callback.InsertDecodedOptions( GPUdbTableMonitor.Callback.InsertDecodedOptions.DecodeFailureMode.ABORT ))

        ]

        # Invoke the base class constructor and pass in the list of callback
        # objects created earlier.  This invocation is mandatory for the table
        # monitor to be actually functional.
        super(GPUdbTableMonitorExample, self).__init__(
            db, table_name,
            callbacks, options=options)

Constructor for this class.

Parameters

callback_type (Callback.Type) –

This indicates the type of the table monitor this callback will be used for. It must be of the type Callback.Type enum.

event_callback (method reference) –

This is to be called for any event related to an operation on a table like insert, update, delete etc. As soon as such an event is observed this method will be called.

This method can have only one parameter. For each table monitor event (callback_type), the parameter would be different. The method name has got no significance as long as the signature is as given below:

def method_name(param):
    # param - Could be a (dict|bytes|int|str)
    # depending on the :attr:`callback_type`
    # Processing Code follows ....

The method thus defined does not return anything.

The following table describes the parameter types which correspond to each of the callback_type:

NO

callback_type

Parameter Type

1

INSERT_DECODED

dict

2

INSERT_RAW

bytes

3

DELETED

int

4

UPDATED

int

5

TABLE_ALTERED

str

6

TABLE_DROPPED

str
error_callback (method reference) –

Optional parameter.

This will be called in case of any operational error that typically could manifest in the form of some exception (gpudb.GPUdbException).

The name of the method does not matter. It must have only one argument of type str. The argument to this method will contain information related to the error that occurred; often details about any exception that was raised.

The signature of this method has to be:

def method_name(param):
    # param - str
    # code here ...
event_options (Callback.Options) –

Optional parameter.

Options applicable to a specific callback type, e.g., insert, delete, update etc. Right now, the only option applicable is for the callback handling insertion of records where the record information is decoded and sent to the callback by the table monitor.

property event_callback

Getter for the __event_callback field Used to call the method pointed to once an event is received

property error_callback

Getter for the __error_callback field Used to call the method pointed to in case of an error related to the callback_type of this class.

class Options[source]

This class embodies the options for any given callback type. The Callback constructor expects an instance of this class. However, instead of using this class directly, the user is supposed to use an instance of one of its derived classes. Each derived class is specialized with options that pertain to a certain type of callback.

Note that, currently, there is only one derived class as other callback types do not have special options at the moment.

See also

Callback.InsertDecodedOptions

class InsertDecodedOptions(decode_failure_mode=None)[source]

Options used to control the behavior if an error occurs while receiving notifications about inserted records after decoding.

Constructor for this class.

Parameters

decode_failure_mode (Callback.InsertDecodedOptions.DecodeFailureMode) –

This is either SKIP or ABORT as described in the class documentation.

property decode_failure_mode

Getter method

Return the __decode_failure_mode value.

class DecodeFailureMode(value, names=None, module=None, type=None, start=1)[source]

This enum is used to identify the two possible modes to handle any error that can occur while decoding the payload received from the server table monitors. In both the cases (SKIP and ABORT) it will try to recover once by default.

ABORT = <DecodeFailureMode.ABORT: 1>

If a decoding error occurs and ABORT is specified, then the program aborts (quits with an exception)

Type:

int

SKIP = <DecodeFailureMode.SKIP: 2>

if SKIP is specified, then the program will skip to the next record and try to decode that. In SKIP mode, the record that has been skipped due to a problem in decoding will appear in the error log.

Type:

int

class Type(value, names=None, module=None, type=None, start=1)[source]

Indicates that the callback is for insert/update/delete event for the target table. The API will create a[n] insert/update/delete table monitor, and per event, will invoke the appropriate event callback method. [Optional based on context: “Upon receiving records that have been recently inserted into the target table, the table monitor will/will not decode the records and pass the binary/decoded records to the event callback method.”]

INSERT_DECODED = <Type.INSERT_DECODED: 1>

This mode indicates an interest in receiving records after decoding according to the table schema. This is used to create an insert monitor internally. The user will get the notification through the callback method pointed to by the event_callback property of Callback. The inserted records will be returned as a dict as an argument to the `event_callback.

See also

Client

Type:

int

INSERT_RAW = <Type.INSERT_RAW: 2>

This mode indicates an interest in receiving records before decoding that is as raw bytes. This is used to create an insert monitor internally. The user will get the notification through the callback method pointed to by the event_callback property of Callback. The inserted records will be returned as bytes as an argument to the event_callback.

See also

Client

Type:

int

DELETED = <Type.DELETED: 3>

This mode indicates an interest in receiving notification about the count of deleted records. This is used to create a delete monitor internally. The user will get the notification through the callback method pointed to by the event_callback property of Callback.

See also

Client

Type:

int

UPDATED = <Type.UPDATED: 4>

This mode indicates an interest in receiving notification about the count of updated records. This is used to create an update monitor internally. The user will get the notification through the callback method pointed to by the event_callback property of Callback.

See also

Client

Type:

int

TABLE_ALTERED = <Type.TABLE_ALTERED: 5>

This mode indicates an interest in receiving notification about the possible table alterations while one or more table monitors (insert, update, delete) are monitoring a table. If this is supplied then the user will be notified using the callback pointed to by the event_callback property of Callback.

See also

Client

Type:

int

TABLE_DROPPED = <Type.TABLE_DROPPED: 6>

This mode indicates an interest in receiving notification about the possible table deletions while one or more table monitors (insert, update, delete) are monitoring a table. If this is supplied then the user will be notified using the callback pointed to by the event_callback property of Callback.

See also

Client

Type:

int