TIBCO LogLogic Unity Query Input Adapter

Introduction

The TIBCO StreamBase® Adapter for TIBCO® LogLogic Unity allows a StreamBase application to query a LogLogic Unity server.

The adapter connects to a LogLogic Unity server when a command is sent to the query adapter. The adapter can be set up to poll for query results until complete or allow you to use event flow to query for specific result sets if required. Cached and Forward Only queries are supported. Forward Only queries are faster to return results but do not allow for sub result sets or fetching results out of order.

You configure the adapter through several properties set in its Properties view in StreamBase Studio. Properties include parameters used to connect to the LogLogic Unity REST API.

The adapter was designed to handle one type of result set schema. If you require multiple different queries with different result set schemas, you must use multiple query adapters. The query adapter does allow multiple different queries with the same end schema but different predicates. Also, this adapter supports creation of multiple result sets based on an original query.

General Tab

Name: Use this field to specify or change the component's name, which must be unique in the application. The name must contain only alphabetic characters, numbers, and underscores, and no hyphens or other special characters. The first character must be alphabetic or an underscore.

Adapter: A read-only field that shows the formal name of the adapter.

Start with application: If this field is set to Yes or to a module parameter that evaluates to true, an instance of this adapter starts as part of the containing StreamBase Server. If this field is set to No or to a module parameter that evaluates to false, the adapter is loaded with the server, but does not start until you send an sbadmin resume command, or until you start the component with StreamBase Manager. With this option set to No or false, the adapter does not start even if the application as a whole is suspended and later resumed. The recommended setting is selected by default.

Enable Error Output Port: Select this check box to add an Error Port to this component. In the EventFlow canvas, the Error Port shows as a red output port, always the last port for the component. See Using Error Ports and Error Streams to learn about Error Ports.

Description: Optionally enter text to briefly describe the component's purpose and function. In the EventFlow canvas, you can see the description by pressing Ctrl while the component's tooltip is displayed.

Adapter Properties Tab

Property Description
URL The URL endpoint to the Unity server. For example: http://localhost:9681
Poll Interval (ms) The number of milliseconds to wait between polling for new records of each query. This option is used when the control tuple requests pollUntilComplete.
Enable Pass Through Fields When enabled, fields of the incoming control tuple to be copied to the outgoing data tuple.
Enable Status Port When enabled, the status port outputs related information to the input tuple commands and operations of the adapter. For example, if the query command is entered a status message is output with the action Query Started and its action will be the query ID.
Log Level Controls the level of verbosity the adapter uses to send notifications to the console. This setting can be higher than the containing application's log level. If set lower, the system log level will be used. Available values, in increasing order of verbosity, are: OFF, ERROR, WARN, INFO, DEBUG, TRACE, and ALL (Default: INFO).

Connection Tab

Property Description
Connect Timeout Sets a specified timeout value, in milliseconds, to be used when opening. A timeout of zero is interpreted as an infinite timeout.
Read Timeout Sets a specified timeout value, in milliseconds, to be used when reading. A timeout of zero is interpreted as an infinite timeout.
Use Proxy Use a proxy server to access the URL.
Proxy Host Proxy server host name or IP address.
Proxy Port Proxy server port number.
Ignore Certificate Errors When enabled any errors produced by invalid SSL certificates are ignored and the website is processed as normal. Warning! This can lead to man-in-the-middle attacks.
Authentication The type of authentication used when making a request to the service.
Username The user name to send when authentication requires it.
Password The password to send when authentication requires it.

Edit Schema Tab

Generate Schema from Query

The Generate schema from query quick link uses the current adapter settings and prompts for an EQL or SQL query which will be sent to the current adapters URL and will convert the queries column descriptors into a StreamBase schema.

Query Result Schema

The Edit Schema tab is used to create the output schema of the queries that will be requested from this adapter. All queries input into this adapter MUST contains the same number of fields and the same field types as this schema or results will be invalid. If you require more than one result set type you must use two different Query adapters to perform this task.

Control Port

Description

Use the control port to send action commands to the adapter.

Control Port Schema

  • command, string, the command to send to the adapter.

    The values are:

    • query — Use this command to start a query. The field query is required when performing this command. The fields metadata, queryStyle, and pollUntilComplete are optional; all other fields are ignored. See below for definitions of the required fields. The status port will output a Query Started event with the ID of the query. Once a query is started you can query for results using the getresults or getforwardresults command depending on your query style. If the optional parameter pollUntilComplete is set to true the adapter internally polls for results no matter the style and output the proper results until the query is complete. NOTE: If a tail query is input and pollUntilComplete is set to true the query will never complete and you must manually send a deletequery command to remove it. If the metadata field has a value it is added to the query when started.

    • createresultset — Use this command to create a sub result set based on an already running query. The query and queryId fields are required; all other fields are ignored. See below for definitions of the required fields. The status port will output a Create Result Set action with the new result set ID which can be used to request the results with the getresults or getforwardresults command depending on your query style.

    • deleteresultset — Use this command to delete a sub result set created with the createresultset command. The queryId and resultSetId fields are required for this command; all other fields are ignored. See below for definitions of the required fields.

    • getresults — Use this command to request results from a previous query command with a queryStyle of CACHED. The field queryId is required, the fields resultSetId, from, and size are optional; all other fields are ignored. See below for definitions of the required fields. If resultSetId is missing the default of 0 is used.

    • getforwardresults — Use this command to request results from a previous query command with a queryStyle of FORWARD_ONLY. The field queryId is required; the fields resultSetId, minEvents, maxEvents, and timeout are optional. All other fields are ignored. See below for definitions of the required fields. If resultSetId is missing the default of 0 is used.

    • deletequery — Use this command to delete a query created using the query command. The field queryId is required; all other fields are ignored. See below for definitions of the required fields.

    • queries — Use this command to get a list of all running queries on the server. No input fields are used for this command and are ignored.

    • getmetadata — Use this command to get the meta data for a running query. The field queryId is required; all other fields are ignored. See below for definitions of the required fields.

    • addmetadata — Use this command to set the metadata for a running query. The fields queryId and metadata are required; all other fields are ignored. See below for definitions of the required fields. The metadata input must be a valid JSON payload.

  • query, string. The EQL or SQL query to send to the server. Used for the commands query and createresultset.

  • queryStyle, string. This field determines the query type to perform when using the query command and if this field is null it defaults to CACHED. The available options are CACHED and FORWARD_ONLY.

  • queryId, string. This is the ID of the query produced by the query command. The status port outputs an event with the action Query Started and its object is the queryId.

  • resultSetId, string. This field is used in the getresults and the deleteresultset commands. If using the getresults command and if this field is null, it defaults to 0. For the deleteresultset this field does not default and is required.

  • from, integer. This field is used with the getresults command to get the results from a specific starting point. If this value is null or empty it is ignored.

  • size, integer. This field is used with the getresults command to get a specific number of results at a time. If this value is null or empty it is ignored and the server default is used.

  • minEvents, integer. This field is used with the getforwardresults. The server waits for this many events to be available before returning (unless timed out).

  • maxEvents, integer. This field is used with the getforwardresults. The server will not return more than this many events even if they are available.

  • timeout, integer. This field is used with the getforwardresults. It is the maximum time to wait to get the minimum number events requested. If this much time passes, the server returns the events available (which might be none).

  • pollUntilComplete, boolean. This field is used with the query command to determine whether the query should continuously call the server for results and output result tuples until the query is marked as complete. For CACHED queries this means when the from + count equals the totalCount. For FORWARD_ONLY queries this means the finished field is true. For tail queries, the system polls until the query is manually deleted from the server.

  • metadata, string. A JSON string to be appended to the query.

Query Result Output Port

The first adapter port is the query output port. It outputs results for queries.

  • id, string. The query ID.

  • resultSetId, string. The result set ID.

  • from, string. The number of the first row returned in the result set. Only set with CACHED queries.

  • count, string. The number of rows in the response. Only set with CACHED queries.

  • totalCount, string. The total number of rows in the result set. The total can be -1 for queries that are not finished. Only set with CACHED queries.

  • queryTime, string, The time (in milliseconds) that it took to process the query. It is -1 for queries that are not finished. Only set with CACHED queries.

  • eventsProcessed, string. The number of events processed until now when the query is executed. Only set with CACHED queries.

  • eventsTotalCount, string. The total number of events that need to be processed for this query. Only set with CACHED queries.

  • results, string. The list of results which has the format given in the edit schema property tab.

  • finished, string. Specifies whether a query is complete. Only set for FORWARD_ONLY queries.

  • passThroughFields, tuple. When enabled, the initial tuple that started the query.

Query List Output Port

The second adapter port is the query list output port. It outputs results for query lists.

  • queryList, list. The list of queries currently running on the server.

  • passThroughFields, tuple. When enabled, the initial tuple that started the query list operation.

Metadata Output Port

The third adapter port is the metadata output port. It outputs the metadata field for a query when using the getmetadata command.

  • queryId, string. The query ID.

  • metadata, string. The meta data associated with the query.

  • passThroughFields, tuple. When enabled, the initial tuple that started the query list operation.

Status Port

Description

For change notification, use the status port to send status information tuples downstream.

Status Port Schema

  • type, string. The type of status information emitted on this port. Status types are:

    • Error — Indicates this message is related to an error that occurred.

    • Warn — Indicates this message is related to a warning that the user should be aware of.

    • Info — Indicates this message is related to extra status information.

  • action, string.

    • Command — A message about the last command that was sent to the adapter.

    • Query — A message about a query operation.

    • Query Start — The query has started; this message object field contains the new query's ID.

    • Get Results — A message about a get result command.

    • Get Forward Results — A message about a get forward result command.

    • Create Result Set — A new result set has been created. This message object field contains the new result set ID.

    • Delete Result Set — A result set was deleted.

    • Delete Query — A query was deleted.

    • Queries — A message about the queries command.

    • Metadata — A message about getting metadata.

    • Add Metadata — A message about adding metadata to a query.

  • object, string. This value may be null. If not null, it contains a value relevant to the status message.

  • message, string. This is a formatted human-readable message that explains the status message.

  • time, timestamp. The time the status message occurred.

  • inputTuple, tuple. If passThroughFields is enabled this will contain the original input tuple which is associated with this message.