Query end points

Owned by jrenbb
Last updated: Sept 28, 2020 by Long Tran
3 min read

Query end points the listeners within A-Stack which is ready to take any TQL Query requests (CRUD Queries) and send the response back to the user.

Query endpoints are generated when TQL Facet type is instantiated using NewFacetInstance as part of package definition. The format of the published endpoint is below:


Format of Published Endpoint


There are two end points created with standard project deployment (defined in package definition)

        http://<hostname>:<portnumber>/fid-<Project facet Id>

                This end point takes all TQL Queries as request-response

        ws://<hostname>:<portnumber>/fid-<Project facet Id>WS

                 This end point takes all subscription queries and publishes messages asynchronously against the subscriptions.

In addition to northbound end points for applications, there are additional end points, which come out of the box from the engine to communicate with southbound devices.

Supported Protocol Handler

Protocol nameProtocol Prefix
HTTP/Shttp://
Peripheralperif://
Phidgetphid://
UCAMucam://
Bluetooth / BLEblth://
Websocketws://


Example of Published Query Endpoint

Facet Type NameSffTqlFacet
Language SupportThing Interaction Language (TIL) - TQL CRUD Queries requested via <Query> tag.
Transports

HttpServerExtensionArgs

WsServerExtensionArgs

Usage

 Facet Types are used using <NewFacetInstance> when creating a Package (Deployment) definition for your models.

SffTqlFacet Example
# Typical TQL Facet Definition
NewFacetInstance(fid: "samplequeries", Name: "TQL", Type: "SffTqlFacet"):
    OnActivate:
        # Associate other facet types; Either Private or Public Instances
        NewFacetInstance(name: "tqlwfws", type: "SffWdlFacet") # Private Instance of wdl facet
        NetworkFacet: "?cluster"  # Public Instance of Network Facet
        TopicFacet: "?TQLGenericTopic"  # Public Instance of Topic Facet
        ImportFacet: 
            [:RuntimeParams.MacroFacetID:]  # Private Instance of Msg facet
        Process: 
            # Define TQL Storage Scheme
            Storage(Name: "[:RuntimeParams.TQLCacheName:]", Type: "SqlSff", Comment: "[:RuntimeParams.TQLCacheName:] Database SFF Unstructured SQL database")
            # Specify the Model Definition file (TDL). Normally consists of Model definitions
            Namespace: 
                Include: cloud.dbm.xml
    OnOpen(ModifyPipeline: "WsServerExtensionArgs")
    OnRequest:    
        #HandOff the request to Facet
        DoRequest: 
            Process Return: "CMD_NOP"):
                Message: 
                    Value: 
                        Include: $Request.Message.Value
        DoResponse:  # Process the response from Facet or send it straight through
            Process: 
                Message(type: "[:RuntimeParams.TQLOutputFormat:]"):
                    Value: 
                        Include: $Response.Message.Value
Endpoint Generated

ws://<HostName>:<PortNumber>/fid-samplequeries

Where PortNumber is the port on which A-Stack is started and <HostName> is the engine machine IP address


TQLStudio 

 When models are built using Model Editor and deploy to A-Stack in the cloud or the project imported into local A-Stack, the Query endpoints are automatically generated because of the fixed package definition. The endpoints are unique for each project. This could be one way to protect your endpoints for unauthorized access.