QuerySubscription

LiveView. QuerySubscription

new QuerySubscription(id, connection, query, settings)

Object that represents a query that has been or is currently being executed at the server. This constructor is internal to LiveView and should not be invoked directly. QuerySubscriptions will be created and returned as the result of calling subscribe.
Parameters:
Name Type Description
id Number The unique identifier for this subscription. This value will be set by the API.
connection LiveView.Connection The connection on which the query is subscribed.
query LiveView.Query The query string that was issued to the server.
settings Object The settings that were used when subscribing to the query. This includes the callbacks and context provided for subscription events.

Members

(static, readonly) Status :Object

Properties:
Name Type Description
STARTING Object The query is in the process of starting up. Once the query has been acknowledged by the server as started and the necessary listeners have been linked, status will transition to ACTIVE
ACTIVE Object The query has started and is running
UPDATING Object The query is in the process of updating its parameters
CLOSING Object The query is in the process of closing. Once query closure has been acknowledged by the server and any necessary cleanup has been performed, status will transition to CLOSED
CLOSED Object The query is not active.
ERROR Object There was an error that occurred while running the query
Type:
  • Object

connection :LiveView.Connection

The connection on which the query is subscribed.
Type:

id :Number

The unique identifier for this subscription. This value will be set by the API.
Type:
  • Number

isLvQuery :boolean

A flag indicating whether or not the query was issued against a native LiveView Table. Queries against tables that do not use LiveView as their table data provider will have isLvQuery set to false.
Type:
  • boolean

keyFields :Array.<String>

The query's key fields as an array of field names.
Type:
  • Array.<String>

query :LiveView.Query

The query object that represents the query that was issued to the server.
Type:

settings :Object

The settings for the subscription (i.e. those that were passed when invoking subscribe)
Type:
  • Object

status :LiveView.QuerySubscription.Status

The status object that represents the query that was issued to the server.
Type:

Methods

applyParameters(parameters, settingsopt) → {Promise.<Object>}

Applies the provided parameters to the query that is maintained by this QuerySubscription. The process terminates the currently executing query and reinitializes it with the given parameters. This QuerySubscription's fields will not change in the process (i.e. the query id, callbacks, etc.). Only the contained Query's parameters will be modified. The same callbacks that were used for the initial query will still be used for the re-parameterized query.
Example
//First connect to LiveView
 var lvConnection, subscribedQuery;
 LiveView.connect({url: '/lv/client'}).then(
     function(connection){
         //once connected, keep the reference to the connection and run queries
         lvConnection = connection;
         runQueries();
     }
 );

 function runQueries(){
     lvConnection.subscribe(
         new LiveView.Query('SELECT sku, lastSoldPrice FROM ItemsSales WHERE sku = @itemName', {'@itemName':'\'Teddy Bear\''}),
         {
             onSnapshotStart: function(event){
                 console.log('Snapshot started for query ' + event.subscription.id);
                 console.log('The query schema is:');
                 console.log(event.schema);
             },
             onInsert: function(event){
                 console.log('Query ' + event.subscription.id + ' got new data.');
                 console.log('The new tuple is:');
                 console.log(event.tuple);
             },
             onUpdate: function(event){
                 console.log('Query ' + event.subscription.id + ' updated data for tuple ' + event.tuple.id);
                 console.log('The updated tuple data is:');
                 console.log(event.tuple.fieldMap);
             },
             onDelete: function(event){
                 console.log('Query ' + event.subscription.id + ' deleted tuple ' + event.tuple.id);
             },
             onSnapshotEnd: function(event){
                 console.log('Snapshot ended for query ' + event.subscription.id);
             },
             onError: function(error){
                 console.log('There was an error while running query ' + event.subscription.id);
                 console.log('ERROR:');
                 console.log(error);
             }
         }
     )
     .then(
         function(result){
             subscribedQuery = result.subscription;
             //In normal applications, triggering of query update is likely to come from a user who clicked a
             //button, selected something from a drop-down, etc.
             //Here, we wait 2 seconds and then apply new parameters to the query
             setTimeout(function(){updateQuery('\'Cell Phone\'')}, 2000);
         },
         function(error){
             console.log('Something went wrong: ' + error.message);
         }
     );
 }

 function updateQuery(itemName){
     if(!subscribedQuery){ return; } //query isn't ready
     console.log('================ Applying Parameters ===============');
     subscribedQuery.applyParameters({'@itemName':itemName});
 }
Parameters:
Name Type Attributes Description
parameters Object Map of parameter token to parameter value to be applied to the query. Users are essentially free to define the token used to identify a parameter as they wish. The query string is generated using regular expression substitution, so avoidance of regular expression special characters is recommended as it will likely cause unexpected behavior. The '@' character as a parameter prefix works well (e.g. {'@priceMin':100, '@lastUpdated':1415230518223}).
settings Object <optional>
 Object specifying additional settings for the applyParameters function
Properties
Name Type Attributes Description
context Object <optional>
 Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function <optional>
 Callback function to invoke upon successful application of parameters to the query. The callback will be passed an object with field: subscription. The subscription field is this query subscription (i.e. the one whose parameters were applied).
onError function <optional>
 Callback function to invoke upon failure to apply parameters to the query. The callback function will be passed an Error object containing details about what went wrong.
Returns:
-- Promise representing the result of the applyParameters function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is this query subscription (i.e. the one whose parameters were applied). If the applying parameters fails, the promise will be rejected and the rejection handler will be passed an Error object containing details about what went wrong.
Type
Promise.<Object>

close(settingsopt) → {Promise.<Object>}

Closes the query maintained by this QuerySubscription.
Parameters:
Name Type Attributes Description
settings Object <optional>
 Object specifying additional, optional settings for the close function
Properties
Name Type Attributes Description
context Object <optional>
 Object to use as the context for all callback functions. Use this if you need the callbacks to execute within a specific context or scope other than the global window.
onSuccess function <optional>
 Callback function to invoke upon successful closure of the subscription. The callback will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully closed.
onError function <optional>
 Callback function to invoke upon failure to close the query subscription. The callback function will be passed an Error object containing details about what went wrong.
Returns:
-- Promise representing the result of the close function. On success, the promise resolution handler function will be passed an object with field: subscription. The subscription field is the QuerySubscription that successfully closed. If there is an error, the promise will be rejected and the rejection handler function will be passed an Error object containing details about what went wrong.
Type
Promise.<Object>