Context References

A Context Reference looks like this:

contextMask { :contextEntityReference [: ...] }

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:

users.admin:childInfo

this reference points to the value of the childInfo 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):

users.*:childInfo:variableGroup.*:status()

This reference points to the value of the childInfo 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:

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 separated 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.

When tables are being created to match a Context Reference, the system may also create indexes for certain fields. Those indexes may dramatically speed up processing of a query. Indexes are automatically created for all key fields, i.e. fields that have Key flag set in table format.

If some of your queries, such as a query that relies to JOINs, takes considerable time to complete or creates high performance overhead, try to modify structure of source values so that necessary fields will become Key fields. In this case indexes will be automatically created for them and query performance will increase many times.

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.

A table alias that was defined to reference results of a query can be used as a context variable in a context reference in another query. The context reference in such case looks like this:

queryContextPath.queryContextName:tableAlies

For example, let's say you created a query context named sineHistory. Say, the purpose of this context is to retrieve the variable history of the sine variable of a virtual device called virtual located in users.admin.devices (note that history storage time must be set for the corresponding variable in order to allow the storage of its history). The query text is the following:

SELECT * FROM utilities:variableHistory("users.admin.devices.virtual", "sine") AS data1

You can use the created data1 alias to reference the results of the sineHistory query in a different query. Let's suppose that you created another query context named sineHistoryLast20. With the following query, sineHistoryLast20 will return the last twenty history records:

SELECT * FROM users.admin.queries.sineHistory:data1 AS data2 LIMIT 20

In this way, the sineHistory query context is used as an external "subquery" for the sineHistoryLast20 context.

Note that as opposed to table aliases, you cannot reference the execute function of a query context in another query context. The output format of the execute function is dynamic (meaning that it does not contain any predefined fields) so the result of a query that references only this function will be an empty table (see point 3 of the Building Source Tables from Context References section above).

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

path.name has two variables:

var1:

var2:

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

path.name2 has the same variable names, but with different values:

var1:

var2:

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

Example 1

Context Reference: path.name:var2

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

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.

Example 2

Context Reference: path.name:var1:var2

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.

Example 3

Context Reference: path.*:var1:var2

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:

Example 4

Context Reference: path.*:func1

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

Example 5

Context Reference: path.*:var1:func1

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.

Was this page helpful?

Tell us more

Send

Thank you!