Insert Context Attributes Using a Query (Context Attribute Step)

This topic provides guidance on configuring a Context Attribute Step, which allows you to define and run a SELECT query against the graphmart, Graph Lakehouse, or another data source, a system journal or a semantic service, so that the named variables from the first row of the query result get inserted as context attributes into the graphmart.

Within this step, you can introduce logic for conditional execution of steps and layers, as well as custom incremental logic. Furthermore, for all step types that involve a query, the query templates within steps and views can use context attributes as template replacements before being sent to Graph Studio.

For example, this step could be used for querying for the date and time an FLDS was last updated and putting that timestamp into a context attribute, so that a further step could be enabled or disabled based on whether the FLDS had been updated before or after a certain threshold date.

Add a step as follows:

1. Go to the graphmart for which you want to add a step and then expand its Data Layers list.

2. In the Data Layers list, find the layer that you want to add the step to. Click the menu icon () for that layer and select Add Step/View. For example:

   

   The Add Step/View dialog box is displayed with the New tab selected.

   

3. To create a new Context Attribute Step, select Context Attribute Step and then click OK. If you want to clone an existing step, click the Existing Steps tab, select the step that you want to clone, and then click OK. The Create Validate Data Step dialog opens. Specify a name for the step in the Title field and include an optional description in the Description field. Click Confirm. Graph Studio creates or clones the step and displays the Details tab. Refresh the layer.

   

4. On the Details tab, configure the following options as needed:
   • Title: The required name of the step.
   • Description: An optional short description of the step.
   • Enabled: When creating a new step, the Enabled option is selected by default, indicating that the step is enabled and will run when the layer is loaded or refreshed. If you want to disable the step so that it is not processed, clear the Enabled checkbox.
   • Source: The source data that this step should act upon. Steps can build upon the data generated by steps in other layers or can be self-contained, applying changes that relate only to the data defined in the layer that contains this step. You can select any number of the following options:
     • Self: This option is selected by default and means that the step runs against the data that is in the parent layer.
     • All Previous Layers Within Graphmart: This option means that the step runs against the data in all of the successful layers that precede the layer this step is in. Any failed layers are ignored.
     • Previous Layer Within Graphmart: This option means that the query runs against the data that is in the one layer that precedes the layer this step is in.
     • Layer Name: The Source drop-down list also includes options for layer names. You can choose a specific layer to act upon the data in that layer.
   • Ontology Models: This optional field specifies the ontologies to associate with this step.

     The Ontology Models list displays all of the available models. By default, the field is set to Exclude System Data (). If you want to choose a system model, click the toggle button on the right side of the field to change it to Include System Data (). When system data is included, the drop-down list displays the system models in addition to the user-generated models.

   • Pre-Run Generate Statistics: This option controls whether to initiate Graph Lakehouse's internal statistics gathering queries before running the query to pre-compile. The statistics gathering helps ensure that the Graph Lakehouse query planner generates ideal query execution plans for queries that are run against the graphmart.
   • Pre-Vacuum: This option controls whether to vacuum the source layers before running the step. Select this option to clean up outdated or obsolete data in the source layers, reclaim unused space and improve query performance.
   • Query Source: The source data that the query defined in the Context Attribute Query tab should act upon. Select one of the following options:
     • Default: The current graphmart is the default query source.
     • Query Datasource: An optional datasource used to perform the query. Selecting this option enables the Query Source Datasource field allowing you to select the desired source from a list (other datasources, journals, Lakehouse servers).
     • Semantic Service: Specify a Semantic Service to call, and whose result statements are queried against for the steps operations. Selecting this option and specifying a service enables additional fields:
       • Semantic Service Operation: Select the operation from the list of operations defined for the specified Semantic Service.
       • Request Statements: The request statements that the semantic service will send out. Once you specify the statements, click the Run Service button to perform a dry run to see what the results would be, if necessary.

       • Response Statements: The statements returned from running the semantic service specified above. The query defined in the Context Attribute tab is going to run against these response statements.

         Example:

         

     • Note: If you choose Query Datasource or Semantic Service, make sure a service user is defined, since running this as sysadmin is not allowed.
5. When you have finished configuring the Details tab, click the Context Attribute Query tab. This tab defines the query that this step should run.

   

6. Edit the provided template to compose the SELECT query the step should run. For information about SELECT queries, see SELECT in the W3C SPARQL 1.1 Query Language specification.

   You can click the Dry Run button to perform practice runs to see results without having to refresh the graphmart or layer.

   The variables from this SELECT query then become context attributes that other steps can use. They become available to be injected into future queries or into their execution conditions.

   For example, in the Execution Condition tab of the next step or any further step in the data layer, you can enable it based on a Boolean condition and select any of these context attributes as the Condition variable.

   Context attributes can also be used inside the condition query in the Execution Condition tab of any subsequent step. If you enable the step based on a Boolean condition and select the Query option for Condition type, then you can refer to any available context attribute in the format ${contextAttribute1} when writing the Condition query statement, and that would get replaced at runtime with the actual value of the variable (attribute) at the time this is executed.

   If your query connects to a source that requires input of connection and authorization information, Altair recommends that you do not include the connection and authorization values directly in the query. Instead, replace those values with Context Variables from a Query Context. You can access Context Providers for each data source from the step's Query Context tab. For detailed information about query contexts and referencing variables in a query, see Using Query Contexts.

7. Click Save to save the step configuration.

Once the Details tab is configured and the context attribute query is written, the step can be run. For information about running this step conditionally by setting up an execution condition, see Defining Execution Conditions.