Query Microservice
You can use Query Microservice to offload the ThingWorx server by allowing query execution to occur in a separate process on the same or on a different physical machine. Query Microservice is recommended in the following cases:
Your system uses queries that load and retrieve a very large amount of data in-memory that results in slowness or system crash.
Your system experiences slowness and unresponsiveness due to large volume of queries executed as part of processing.
* 
While Query Microservice reduces system processing on the ThingWorx server, there is still a possibility that query execution can bring down service due to a large amount of data processing.
Features
Query Microservice supports PostgreSQL, MSSQL, and InfluxDB data providers on ThingWorx 8.4.0 and later.
Query Microservice only supports value streams.
Query Microservice can execute on the same machine as ThingWorx or on a different machine.
Database cursor support: Can be enabled through <queryservice.serialisation PageSize> option. When enabled, the query results from the database are returned in chunks of this size instead at one time. This puts less load on server memory and there is less chance of the service going down. The default is 0 which means no cursor.
Location
Query Microservice is available on the PTC Support Portal.
Installation and Configuration
To use Query Microservice, security credentials must be set up to provide communication between ThingWorx and Query Microservice. This requires using the ThingWorx Security Management Tool. Query Microservice must be installed using the scripts provided in the distribution package. The following steps should be followed to install and configure Query Microservice:
* 
This process assumes ThingWorx is installed. If necessary, see Installing ThingWorx.
1. Obtain Query Microservice from the PTC Support Portal.
2. Run the Query Microservice Installer (.qms-1.0-windows-installer.exe for Windows or qms-1.0-linux-x64-installer.run for Linux). The installer Setup screen displays. Click Next.
* 
If using Linux, the installer contains a .run file that requires executable permissions. To set these, run the following:
chmod +x qms-installer-file-name.run
* 
If you run the installer as ./qms-installer-file-name.run, it will run in graphical mode. To run in text mode run the following:
./qms-installer-file-name.run --mode text
3. In the Installation Directory field, specify the installation location. Click Next.
4. Add the location of the ThingWorx server and the application key to connect with. Click Next.
5. Click Finish.
6. Create a Query Microservice configuration file with the following parameters and provide a name for the file. In this example the file is named qms-security.props. Update the values for password-file-path and path.
* 
These locations can be any directory, but must match the values in your Query Microservice application.properties file. The keystore.jks file should be located under the path directory and the keystore-password file should be located under the password-file-pathdirectory. If they don't exist, they are created.
* 
Permission requirements:
Directories must exist and must be writable by the user running the Security Management Tool.
The user running Query Microservices must have read access.
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128
keystore {
password-file-path = "/QmsPasswordDir"
password-file-name = "qms-keystore-password"
path = "/QmsKeysotreDir"
name = "qmskeystore.jks"
}
}
}
7. Obtain the Security Management Command Line Tool from the PTC Support Site.
* 
For more information on the tool see Security Management Tool.
8. Run the command line for the Security Tool with a ThingWorx configuration file to generate the key.
* 
In this example, the key name is qmsAesEncryptionKey.
./security-common-cli qms-security.props generate-key qmsAesEncryptionKey
9. Get the generated qmsAesEncryptionKey key by running security-common-cli to get the generated encryption key, copy, and save it. It will be inserted into the ThingWorx keystore in the following steps:
./security-common-cli qms-security.props get qmsAesEncryptionKey

Loading config from file qms-security.props
7qT1lf6adY+UvV8hq/xxxx==
10. Create a configuration file for the Security Management Tool and provide a name for the file (in this example it is named twx-security.props). Update the values for password-file-path and path.
* 
The keystore.jks file should be located under the path directory and the keystore-password file should be located under the password-file-pathdirectory.
* 
Permission requirements:
These directories must exist and must be writable by the user with whom you are running the Security Management Tool.
{
security {
secret-provider = "com.thingworx.security.provider.keystore.KeyStoreProvider"
default-encryption-key-length = 128

keystore {
password-file-path = "/ThingworxPlatform"
password-file-name = "keystore-password"
path = "/ThingworxStorage"
name = "keystore.jks"
}
}
}
11. Insert the qmsAesEncryptionKey into the ThingWorx keystore:
./security-common-cli twx-security.props set qmsAesEncryptionKey OBTAINED_KEY_ABOVE
12. Verify that the configuration in the Query Microservice application.properties file matches the configuration in the Security Tool configuration file.
13. Add the newly generated application key to application.properties or add it to the Query Microservice keystore using the command line tool. See Configuration Parameters below for more information. For example:
./security-common-cli qms-security.props set qmsThingworxAppKey <Application key>
14. Run Query Microservice located in the query-micro-service-1.0.0 directory by executing the following:
* 
Verify it has executable permissions.
Linux:

./bin/query-micro-service.sh
Windows:
bin\query-micro-service
15. If necessary, verify that Query Microservice has been installed successfully.
* 
The service creates a new Thing in Composer named remoteQueryService. As long as the remoteQueryService Thing exists in the platform and is in Active state, queries are not executed on the ThingWorx server. To execute queries on the ThingWorx server, you must manually delete the remoteQueryService Thing.
* 
To verify that the remoteQueryService Thing is active, you can view the icon next to the entity name in Composer. The service is connected in the image below:
In the image below, the red icon denotes that it is not connected.
Configuration Parameters
Query Microservice contains an application.properties file that is located under the config directory after you extract the provided TAR or ZIP file. If you are not using the default values, the configuration parameters for Query Microservice are listed below and must be configured before running the service:
Parameter
Description
Default Value
queryserviceMinthread
Minimum number of threads that the client (Query Microservice) uses to process incoming messages. If all of the threads are busy handling messages, then additional incoming messages are queued, up to the number specified by the queryservice.queuesize. Once the queue is full, additional threads are added up to the value defined for queryservice.maxthread.
4
queryserviceMaxthread
Maximum number of threads that the client (Query Microservice) uses to process incoming message.
10
queryserviceQueuesize
QueueSize is the number of incoming messages that the queue can hold before more threads are added to the thread pool. If the max number of threads are already active, then new incoming messages are rejected.
1000
queryserviceSerialisationPageSize
Database cursor fetch size. Default is paging disabled. Recommended size is 5000.
0
thingworxUri
The ThingWorx server host URI and port.
ws://localhost:8080/Thingworx/WS
qmsThingworxAppKey
The application key used to connect to the ThingWorx server. It must be created in ThingWorx before running the microservice.
Security Parameters
Parameter
Description
default-encryption-key-length
The default length used for encryption keys.
password-file-path
The absolute path to the Query Microservice keystore password file.
password-file-name
The keystore password file name.
path
The absolute path to the Query Microservice keystore file.
name
The keystore file name.