/create/tablemonitor

URL: http://<db.host>:<db.port>/create/tablemonitor

Creates a monitor that watches for a single table modification event type (insert, update, or delete) on a particular table (identified by input parameter table_name) and forwards event notifications to subscribers via ZMQ. After this call completes, subscribe to the returned output parameter topic_id on the ZMQ table monitor port (default 9002). Each time an operation of the given type on the table completes, a multipart message is published for that topic; the first part contains only the topic ID, and each subsequent part contains one binary-encoded Avro object that corresponds to the event and can be decoded using output parameter type_schema. The monitor will continue to run (regardless of whether or not there are any subscribers) until deactivated with /clear/tablemonitor.

For more information on table monitors, see Table Monitors.

Input Parameter Description

Name

Type

Description

table_name

string

Name of the table to monitor, in [schema_name.]table_name format, using standard name resolution rules.

options

map of string to strings

Optional parameters. The default value is an empty map ( {} ).

Supported Parameters (keys)

Parameter Description

event

Type of modification event on the target table to be monitored by this table monitor. The default value is insert.

Supported Values	Description
insert	Get notifications of new record insertions. The new row images are forwarded to the subscribers.
update	Get notifications of update operations. The modified row count information is forwarded to the subscribers.
delete	Get notifications of delete operations. The deleted row count information is forwarded to the subscribers.

monitor_id

ID to use for this monitor instead of a randomly generated one

datasink_name

Name of an existing data sink to send change data notifications to

destination

Destination for the output data in format 'destination_type://path[:port]'. Supported destination types are 'http', 'https' and 'kafka'.

kafka_topic_name

Name of the Kafka topic to publish to if destination in input parameter options is specified and is a Kafka broker

increasing_column

Column on subscribed table that will increase for new records (e.g., TIMESTAMP).

expression

Filter expression to limit records for notification

refresh_method

Method controlling when the table monitor reports changes to the input parameter table_name. The default value is on_change.

Supported Values	Description
on_change	Report changes as they occur.
periodic	Report changes periodically at rate specified by refresh_period.

refresh_period

When refresh_method is periodic, specifies the period in seconds at which changes are reported.

refresh_start_time

When refresh_method is periodic, specifies the first time at which changes are reported. Value is a datetime string with format 'YYYY-MM-DD HH:MM:SS'.

Output Parameter Description

The GPUdb server embeds the endpoint response inside a standard response structure which contains status information and the actual response to the query. Here is a description of the various fields of the wrapper:

Name

Type

Description

status

String

'OK' or 'ERROR'

message

String

Empty if success or an error message

data_type

String

'create_table_monitor_response' or 'none' in case of an error

data

String

Empty string

data_str

JSON or String

This embedded JSON represents the result of the /create/tablemonitor endpoint:

Name

Type

Description

topic_id

string

The ZMQ topic ID to subscribe to for table events.

table_name

string

Value of input parameter table_name.

type_schema

string

JSON Avro schema of the table, for use in decoding published records.

info

map of string to strings

Additional information. The default value is an empty map ( {} ).

Possible Parameters (keys)	Parameter Description
ttl	For insert_table/delete_table events, the ttl of the table.
insert_topic_id	The topic id for 'insert' event in input parameter options
update_topic_id	The topic id for 'update' event in input parameter options
delete_topic_id	The topic id for 'delete' event in input parameter options
insert_type_schema	The JSON Avro schema of the table in output parameter table_name
update_type_schema	The JSON Avro schema for 'update' events
delete_type_schema	The JSON Avro schema for 'delete' events

Empty string in case of an error.