Context References

contextMask is a mask of contexts whose entities (variables or functions) will be used to build tables on which the query will be executed. This mask can be a plain context name (without any wildcards) or resolve to several contexts.

contextEntityReference may point to a context variable, a group of variables or function. It looks like:

{ contextVariableName | contextVariableGroupName.* | contextFunctionName ( contextFunctionParameters ) }

The pipe marks above denote alternatives -- they're not actually included in the contextEntityReference. Here is the simplest example of a context reference:

this reference points to the value of the userInfo variable from the users.admin context.

The colon (:) mark is used to separate the context mask from the entity. An "entity" is a fancy name for a variable or a function. So, once you specify a mask (i.e, "where" you want to go), you then put a colon and specify the entity (i.e, "what" you want to find out when you get to where you're going). You can even use a wildcard after the colon, to refer to a group of variables (such as user.charlie.devices.sensor:remote.*, which will give you all settings (variables) in the group remote of the sensor Device which belongs to the user charlie).

Every Context Reference may combine context masks and several entity references (even of different types):

This reference points to the value of the userInfo variable, all variables that belong to the variableGroup group and to the output of the status function called without parameters. Values are fetched from all contexts corresponding to the mask users.*, i.e. to the context of all users in the system that are visible with the permission level of the user who executes this query.

When a query is executed, the first thing which happens is that every Context Reference is used to build a single table, on which the query will be performed. Building of this table is a complex process which includes several steps:

1.	The context mask is resolved to the list of contexts that correspond to it, and are accessible to the user executing the query (according to his permissions).

2.	The query processing engine now retrieves and caches the values of the variables that the context reference points to. It also calls all referred functions with the parameters specified in the query text and caches the output of these functions.

Now a list of fields for the resulting table is generated, according to several rules. If the context reference refers to just one variable or function, the resulting table will have exactly the same fields as that variable or function output. If the context reference refers to several variables or functions, the format of the resulting table will include all of the fields that appear in the format of these variables or in the function output. The only exception occurs when a value or a function output contains more than one record. In this case, the resulting table will have just one field for this variable/function. That field will contain a nested table with the value of the variable or the function output.

The table is filled with data. Usually, one record is created for every context that corresponds to the context reference mask. But if just one variable/function is referred and its value/output contains several records, all these records are put in the resulting table (i.e, you won't have a table containing just one record, that record being another nested table. That wouldn't make much sense).

Click here to see where the Context References may appear in Query Language Syntax.

When a context function is called during Context Reference resolution, it usually has to get some input values. These values are specified in a list containing string parameters. The parameters are all in one long string, and are sepearated by commas (",").

See details on how comma-separated parameter list is converted to a Data Table here. The Data Table is built according to the function input format.

Every table build from a Context Reference contains three additional fields: CONTEXT_ID, PARENT_ID and RECORD_INDEX. These fields are implicitly added by query processing engine.

CONTEXT_ID field contains full name of context that originated the particular record.

PARENT_ID field is the full name of context that is parent to context that originated the record.

RECORD_INDEX is the number of record in Data Table from that the particular record was taken.

The special fields may be referred by the WHERE clause. However, these fields are hidden. They are not visible in the query results.

These special fields may be referred in any query. See using joins for an example of how to do that.

Note that names of special fields must be explicitly specified in the SELECT clause when using editable query results. See write-back fields for more information.

Let's assume you have two contexts, path.name and path.name2. The path.* context mask matches both.

integerField	booleanField
123	TRUE

This context also defines the func1 function, which returns the following value:

floatField	integerField
45.6	456
78.9	789

integerField	booleanField
555	FALSE

floatField	integerField
11.1	666
22.2	777
33.3	888

Table built from this simple context reference will be exactly the same as value of var2:

var2$integerField	var2$booleanField
123	TRUE

Note that names of fields in the resulting table include the variables from which each field was taken (var2 above). This helps to refer to these fields using Field References.

This reference will resolve to a table with three fields, one from the value of var1 and two from the value of var2. There's just one line, because both variables come from the same context.

var1$stringField	var2$integerField	var2$booleanField
"test string"	123	TRUE

This reference points to a context mask, so it will result to the table with three fields, like in the previous example, but with two records, one per every context:

var1$stringField	var2$integerField	var2$booleanField
"test string"	123	TRUE
"string in 2nd context"	555	FALSE

This reference points to a single entity (function) with a value containing multiple records, so the resulting table will have the same fields as the function output. The total number of records in the table is five, since two records are provided by the value of func1 in path.name and three records by the value of func1 in path.name2

func1$floatField	func1$integerField
45.6	456
78.9	789
11.1	666
22.2	777
33.3	888

Since several entities (var1 variable and func1 function) are referred here, the multi-line values of func1 will be put in nested tables. Fields in these nested tables can not be referred using Field References.

var1$stringField	func1
"test string"	[Nested table with the value of "func1" in "path.name"]
"string in 2nd context"	[Nested table with the value of "func1" in "path.name2"]