Using Query Contexts in Queries
When you use the Graph Data Interface (GDI) for querying data sources, you may connect to sources that require input of sensitive connection and authorization information such as keys, tokens, and user credentials. When configuring a step that runs a GDI query, Cambridge Semantics recommends that you refer to a Query Context whenever possible. Contexts store sensitive information as key-value pairs. Queries reference only the keys from the context and the sensitive values are abstracted from the requests that are sent to the data source and AnzoGraph. This topic provides information on configuring Query Contexts and referring to Context Variables in a query.
Overview of Query Contexts
Query contexts are accessible from the Query Context tab that is available when creating or editing a data layer or step. The image below shows the Query Context tab for a layer.
Context Providers
Connections in Anzo implement the Context Provider interface. For example, file store connections and data source connections provide contexts (in the form of JSON objects) that contain key-value pairs. The contexts contain the source connection details such as URLs, database names, user names, passwords, and tokens. A context is passed to the data source when a request is made against that source. To use one of the Anzo-generated Context Providers that was created for a pre-existing connection, select that provider from the drop-down list. When you select a provider, the variables from that context are displayed under Context Variables, as shown in the image below:
Context Variables
When you select a Context Provider, the variables from the selected context are displayed under Context Variables. You can copy the text and then use any key in the list as a variable in any query that connects to this data source. Typically there are two versions of each variable. Either version can be used in a query. The short versions are generated from the long versions for ease of use and readability in queries. For information about referencing variables in a query, see Referencing Context Variables in a Query below.
Custom Context
Custom Contexts are user-defined key-value pairs that are not associated with a particular Context Provider. To add a key and define its value, click the Add Key button. Then specify the Key Name and Key Value in the Create Context Key dialog box. Click Create to add the key-value pair to the context.
When defining custom keys at the layer level, make sure that the key names are unique. A layer may have different steps that connect to different sources but reference the same custom context. The image below, for example, creates URL, username, and password Context Keys for a MySQL database.
Referencing Context Variables in a Query
The format that you use for referencing a Context Variable in a query depends on the type of AnzoGraph plugin or extension that is being called by the query. Generally, contexts are only used in steps that contain GDI queries. When referencing context keys in GDI queries, use the following format:
{{@context_key_name}}
For example, the following GDI query references three variables from the Context Provider shown above: url, user, and password.
PREFIX s: <http://cambridgesemantics.com/ontologies/DataToolkit#>
PREFIX xsd: <http://www.w3.org/2001/XMLSchema#>
SELECT DISTINCT *
WHERE
{
SERVICE <http://cambridgesemantics.com/services/DataToolkit>
{
?data a s:DbSource ;
s:url "{{@db.718cc8ab3e9fb2b22345ad4dc31e685c.url}}" ;
s:username "{{@db.718cc8ab3e9fb2b22345ad4dc31e685c.user}}" ;
s:password "{{@db.718cc8ab3e9fb2b22345ad4dc31e685c.password}}" ;
s:selector "[dbo].[FILM]" ;
?year ("[YEAR]" xsd:int);
?length (xsd:int) ;
?title (xsd:string) ;
?subject ("[dbo].[FILM].[SUBJECT]" xsd:string) ;
?actor ("[ACTOR]" xsd:string) ;
?actress (xsd:string) ;
?director (xsd:string) ;
?popularity (xsd:int) ;
?awards (xsd:string) ;
?image (xsd:string) .
FILTER(?year >= 1990 && ?year < 2000)
FILTER(?subject = "Drama" || ?subject = "Action")
FILTER(?length <= 90)
}
}