# Class: QuerySubscription

## LiveView. QuerySubscription

#### new LiveView.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.

  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

#### idNumber

  The unique identifier for this subscription. This value will be set by the API.

#### connectionLiveView.Connection

  The connection on which the query is subscribed.

#### queryLiveView.Query

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

#### settingsObject

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

#### statusLiveView.QuerySubscription.Status

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

#### keyFieldsArray.<String>

  The query's key fields as an array of field names.

#### isLvQueryboolean

  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.

#### static,readonlyLiveView.QuerySubscription.StatusObject

  ##### Properties:

  Name | Type | Default | Description
  --- | --- | --- | ---
  `STARTING` | Object | {"string":"STARTING","value":0} | 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 | {"string":"ACTIVE","value":1} | The query has started and is running
  `UPDATING` | Object | {"string":"UPDATING","value":2} | The query is in the process of updating its parameters
  `CLOSING` | Object | {"string":"CLOSING","value":3} | 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 | {"string":"CLOSED","value":4} | The query is not active.
  `ERROR` | Object | {"string":"ERROR","value":5} | There was an error that occurred while running the query

### Methods

#### applyParameters(parameters, settings){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.

  Name | Type | 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
  Name | Type | 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.

  Type | Description
  --- | ---
  Promise.<Object> | -- 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.

  ##### 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});
       }

#### close(settings){Promise.<Object>}

  Closes the query maintained by this QuerySubscription.

  Name | Type | Description
  --- | --- | ---
  `settings` | Object | optional Object specifying additional, optional settings for the close function
  Name | Type | 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.

  Type | Description
  --- | ---
  Promise.<Object> | -- 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.