API Docs - v1.1.0¶
Env¶
getEnvironmentProperty (Function)¶
This function returns the Java environment property that corresponds with the key provided
Syntax
<STRING> env:getEnvironmentProperty(<STRING> key, <STRING> default.value)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| key | This specifies the key of the property to be read. | STRING | No | No | |
| default.value | This specifies the default value to be returned if the property value is not available. | null | STRING | Yes | No |
Examples EXAMPLE 1
define stream keyStream (key string); from keyStream env:getEnvironmentProperty(key) as FunctionOutput insert into outputStream;
This query returns the Java environment property that corresponds with the key from the 'keyStream' as 'FunctionOutput' to the outputStream.
getOriginIPFromXForwarded (Function)¶
This function returns the public origin IP from the given X-Forwarded header.
Syntax
<STRING> env:getOriginIPFromXForwarded(<STRING> xforwardedheader)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| xforwardedheader | The 'X-Forwarded-For' header of the request. | STRING | No | No |
Examples EXAMPLE 1
define stream InputStream (xForwardedHeader string); from InputStream select env:getOriginIPFromXForwarded(xForwardedHeader) as originIP insert into OutputStream;
This query returns the public origin IP from the given X-Forwarded header as 'originIP', and inserts it to the 'OutputStream' stream.
getSystemProperty (Function)¶
This function returns the system property referred to via the system property key.
Syntax
<STRING> env:getSystemProperty(<STRING> key, <STRING> default.value)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| key | This specifies the key of the property to be read. | STRING | No | No | |
| default.value | This specifies the default value to be returned if the property value is not available. | null | STRING | Yes | No |
Examples EXAMPLE 1
define stream KeyStream (key string); from KeyStream env:getSystemProperty(key) as FunctionOutput insert into OutputStream;
This query returns the system property that corresponds with the key from the 'KeyStream' stream as the 'FunctionOutput' to the 'OutputStream' stream.
getUserAgentProperty (Function)¶
This function returns the value that corresponds with a specified property name of a specified user agent
Syntax
<STRING> env:getUserAgentProperty(<STRING> user.agent, <STRING> property.name)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| user.agent | This specifies the user agent from which the property needs to be extracted. | STRING | No | No | |
| property.name | This specifies the property name that needs to be extracted. Supported property names are 'browser', 'os', and 'device'. | STRING | No | No |
System Parameters
| Name | Description | Default Value | Possible Parameters |
|---|---|---|---|
| regexFilePath | The location of the yaml file that contains the regex to process the user agent. | Default regexes included in the ua_parser library | N/A |
Examples EXAMPLE 1
define stream UserAgentStream (userAgent string); from UserAgentStream select env:getUserAgentProperty(userAgent, "browser") as functionOutput insert into OutputStream;
This query returns the browser name of the 'userAgent' from the 'UserAgentStream' stream as 'functionOutput', and inserts it into the 'OutputStream'stream.
getYAMLProperty (Function)¶
This function returns the YAML property requested or the default values specified if such avariable is not specified in the 'deployment.yaml'.
Syntax
<INT|LONG|DOUBLE|FLOAT|STRING|BOOL> env:getYAMLProperty(<STRING> key, <STRING> data.type, <INT|LONG|DOUBLE|FLOAT|STRING|BOOL> default.value)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| key | This specifies key of the property to be read. | STRING | No | No | |
| data.type | A string constant parameter expressing the data type of the propertyusing one of the following string values: int, long, float, double, string, bool. |
string | STRING | No | No |
| default.value | This specifies the default value to be returned if the property value is not available. | null | INT LONG DOUBLE FLOAT STRING BOOL |
Yes | No |
Examples EXAMPLE 1
define stream KeyStream (key string); from KeyStream env:getYAMLProperty(key) as FunctionOutput insert into outputStream;
This query returns the corresponding YAML property for the corresponding key from the 'KeyStream' stream as 'FunctionOutput', and inserts it into the to the 'OutputStream' stream.
resourceIdentifier (Stream Processor)¶
The resource identifier stream processor is an extension to register a resource name with a reference in a static map and serve a static resources count for a specific resource name.
Syntax
env:resourceIdentifier(<STRING> resource.group.id)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| resource.group.id | The name of the resource group. | STRING | No | No |
Examples EXAMPLE 1
@info(name='product_color_code_rule')
from SweetProductDefectsDetector#env:resourceIdentifier("rule-group-1")
select productId, ifThenElse(colorCode == '#FF0000', true, false) as isValid
insert into DefectDetectionResult;
@info(name='product_dimensions_rule')
from SweetProductDefectsDetector#env:resourceIdentifier("rule-group-1")
select productId, ifThenElse(height == 5 && width ==10, true, false) as isValid
insert into DefectDetectionResult;
@info(name='defect_analyzer')
from DefectDetectionResult#window.env:resourceBatch("rule-group-1", productId, 60000)
select productId, and(not isValid) as isDefected
insert into SweetProductDefectAlert;
'product_color_code_rule' and 'product_dimensions_rule' are two rule-based queries that process the same events from the 'SweetProductDefectsDetector' stream. They both insert their process results as the output into the 'DefectDetectionResult' output stream.
Multiple queries like this can be added in the Siddhi Application and the number of output events inserted into the 'DefectDetectionResult' stream depends on the number of available queries. If you need to further aggregate results for a particular correlation ID ('productId' in this scenario) from the 'DefectDetectionResult' stream, follow-up queries need to wait for events with same value for the 'productId' attribute from all the available queries. For this, follow-up queries need to identify the number of events that can be expected from these rule-based queries with a specific value for 'productID'. To address this requirement, a resource identifier named 'rule-group-1' is assigned to both the rule queries. The 'defect_analyzer' query includes the 'env:resourceBatch' window to derive the count for the registered resource named 'rule-group-1' count from the output of both the queries within a specific time period. All of these factors determine the event waiting condition for events from the 'DefectDetectionResult' stream.
resourceBatch (Window)¶
This extension is a resource batch (tumbling) window that holds a number of events based on the resource count inferred from the 'env:resourceIdentifier' extension, and with a specific attribute as the grouping key. The window is updated each time a batch of events arrive with a matching value for the grouping key, and where the number of events is equal to the resource count.
Syntax
env:resourceBatch(<STRING> resource.group.id, <INT|LONG|FLOAT|BOOL|DOUBLE> correlation.id, <INT|LONG|TIME> time.in.milliseconds)
QUERY PARAMETERS
| Name | Description | Default Value | Possible Data Types | Optional | Dynamic |
|---|---|---|---|---|---|
| resource.group.id | The name of the resource group. | STRING | No | No | |
| correlation.id | The attribute that should be used for event correlation. | INT LONG FLOAT BOOL DOUBLE |
No | No | |
| time.in.milliseconds | The time period to wait for the arrival of a new event before generating the output for events belonging to a specific batch and flushing them. | 300000 | INT LONG TIME |
Yes | No |
Examples EXAMPLE 1
define stream SweetProductDefectsDetector(productId string, colorCode string, height long, width long);
define stream SweetProductDefectAlert(productId string, isDefected bool);
@info(name='product_color_code_rule')
from SweetProductDefectsDetector#env:resourceIdentifier("rule-group-1")
select productId, ifThenElse(colorCode == '#FF0000', true, false) as isValid
insert into DefectDetectionResult;
@info(name='product_dimensions_rule')
from SweetProductDefectsDetector#env:resourceIdentifier("rule-group-1")
select productId, ifThenElse(height == 5 && width ==10, true, false) as isValid
insert into DefectDetectionResult;
@info(name='defect_analyzer')
from DefectDetectionResult#window.env:resourceBatch("rule-group-1", productId, 60000)
select productId, and(not isValid) as isDefected
insert into SweetProductDefectAlert;
This example demonstrates the usage of the 'env:resourceBatch' widow extension with the 'env:resourceIdentifier' stream processor and the 'and' attribute aggregator extension.
Data relating to the sweet production is received into the 'SweetProductDefectsDetector' input stream. This data is consumed by two rule queries named 'product_color_code_rule' and 'product_dimensions_rule'.
The follow-up query named 'defect_analyzer' needs to wait for the output results of both the rule queries mentioned above, and generate an output based on aggregated results.
To ensure that each event from the 'SweetProductDefectsDetector' input stream is processed by both the rule queries, they are grouped together. This is done by assigning a resource identifier named 'rule-group-1' to each rule query.
The 'defect_analyzer' follow-up query waits until an equal number of output events with the same value for the 'productID' attribute are generated by both the rule queries for the 'rule-group-1' resource identifier. Then it selects the events where the product ID is matching and the value for the 'isValid' attribute is not 'true'.
When deriving this output, a 'resourceBatch' time window of 2000 milliseconds is considered. This checks whether events that match the criteria outlined above occurs within a time period of 2000 milliseconds in a tumbling manner. If the criteria is not met within 2000 events, the events within that time window are considered expired and flushed from the window. If the criteria is met within the time window of 2000 milliseconds, the output is inserted into the "SweetProductDefectAlert' output stream as boolean values where 'isDefected' attribute is set to 'true'. The sample output can be as given below.
Input 1: [SweetProductDefectsDetector]
{
"event":{
"productId":"Cake",
"colorCode":"FF0000",
"height": 5,
"width": 10
}
}
Output 1:[SweetProductDefectAlert]
{
"event":{
"productId":"Cake",
"isDefected":"false"
}
}
Input 2: [SweetProductDefectsDetector]
{
"event":{
"productId":"Cake",
"colorCode":"FF0000",
"height": 10,
"width": 20
}
}
Output 2:[SweetProductDefectAlert]
{
"event":{
"productId":"Cake",
"isDefected":"true"
}
}