Query Templates

Table of Contents

A Query Template is a custom Cypher/Gremlin query presented to the user as a form with dynamic parameters (with suggestions) that the user can set in the UI and run the query without any Cypher/Gremlin knowledge.

Query Templates can be managed on the Queries page or using the Queries Setting. This page describes all options available in the JSON representation of a Query Template that can be managed using the Queries Setting.

Example of a Template Configuration

{
"title":"Example Pattern",
"description":"This pattern looks for all relationships of a particular types starting in nodes with some specific labels. Max number of returned elements is 100.",
"template":{
"textTemplate" : "Get all nodes with labels (all labels are mandatory) $labels related to other nodes through relationships of types $rel_types. Max number of returned elements is 100",
"cypherTemplate" : "MATCH (a$labels)-[r]->(b) WHERE type(r) IN $rel_types RETURN a, r, b LIMIT 100",
"parameters" : [
{
"parameter" : "labels",
"type" : "NODE_LABELS",
"config" : {
"multiple" : true,
"cypherColonFormat" : true
}
},
{
"parameter" : "rel_types",
"type" : "REL_TYPES",
"config" : {
"multiple" : true
}
}
]
}
}

The configuration of the template consists of these parts:

  • title - Query title displayed on the Queries page or in the visualization.

  • description (optional) - Description of the pattern displayed on the Search page. This is a good place to explain to the user what the pattern is for if it's a complicated one.

  • template - actual template configuration

    • textTemplate - The textual representation of the template query with dynamic parameters in the text (e.g. $type_list). Example: "Get all nodes related to nodes of type $type_list with relationship type $rel_type . Max number of returned nodes is 100."

    • cypherTemplate or gremlinTemplate - A Cypher/Gremlin query with dynamic parameters in the text (e.g. $type_list). These dynamic fields will be replaced in runtime with user inputs (like node IDs or some filtering values). Example: "MATCH (a:SomeLabel)-[r:$rel_type]->(b) WHERE a.type IN $type_list RETURN r LIMIT 100" or "g.V().has('type', '$type').bothE('$rel_type').limit(100)"

    • parameters - An array of Parameter Definition Objects (PDOs). PDOs can more precisely define the input restrictions and options for every dynamic parameter of the template query. It's not mandatory to define every dynamic parameter but it gives much more value to the user, like pre-populated lists of values and more.

      • PDO.parameter - Unique name of the dynamic parameter. Example: "type_list"

      • PDO.type - The type of input field used in the UI. Based on this type a specific renderer (e.g. string input, number input, node searcher, ...) will be used in the Query Template . All values (NODE_FULLTEXT_SEARCH, NODE_LABELS, ...) and their configs are in the table below.

      • PDO.config - Configuration of the dynamic parameter. This object is different for every PDO.type value. Please see the chapters below for more information and examples.

PDO - Parameter Definition Objects

Every dynamic parameter has different configuration options. Please read more about the specifics in the next chapters.

NODE_PROPERTY_VALUES

Returns node's prop value or a list of prop values.

Example

Example
{
"parameter" : "param_id",
"type" : "NODE_PROPERTY_VALUES",
"config" : {
"placeholder" : "select a property value",
"multiple" : false,
"labels" : ["some_label", "some_other_label"],
"property" : "property_key"
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

labels

Array of strings

<empty>

List of node labels for which the property values should be returned. All nodes will be used if empty.

property

MANDATORY

String


Property name of the property that should be returned.

defaultValues

String or array of strings

<empty>

Default selected value or array of values.

REL_PROPERTY_VALUES

Returns rel's prop value or a list of prop values.

Example

Example
{
"parameter" : "param_id",
"type" : "REL_PROPERTY_VALUES",
"config" : {
"placeholder" : "select a property value",
"multiple" : false,
"relTypes" : ["some_rel_type"],
"property" : "property_key"
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

relTypes

Array of strings

<empty>

List of rel types for which the property values should be returned.

property

MANDATORY

String


Property name of the property that should be returned. All relationships will be used if empty.

defaultValues

String or array of strings

<empty>

Default selected value or array of values.

NODE_LABELS

Returns node's label or a list of labels.

Example

Example
{
"parameter" : "param_id",
"type" : "NODE_LABELS",
"config" : {
"placeholder" : "select a node label",
"multiple" : false
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

defaultValues

String or array of strings

<empty>

Default selected value or array of values.

cypherColonFormat

Boolean

false

If true then the resulting value is returned in the cypher colon format, e.g. ":LABEL_1:LABEL_2", that can be used in the MATCH part of cypher queries.

REL_TYPES

Returns rel's type or a list of types.

Example

Example
{
"parameter" : "param_id",
"type" : "REL_TYPES",
"config" : {
"placeholder" : "select a relationship type",
"multiple" : false
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

defaultValues

String or array of strings

<empty>

Default selected value or array of values.

cypherColonFormat

Boolean

false

If true then the resulting value is returned in the cypher colon format, e.g. ":REL_TYPE_1|REL_TYPE_2|REL_TYPE_3", which can be used in the MATCH part of cypher queries.

STRING

Simple input for any string values and arrays of strings.

Example

Example
{
"parameter" : "param_id",
"type" : "STRING",
"config" : {
"placeholder" : "select a value",
"multiple" : false,
"values" : ["value_1", "value_2", "value_3"]
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

defaultValues

String or array of strings

<empty>

Default selected value or array of values.

values

Array of string

<empty>

A defined list of values in the suggestion list.

strict

Boolean

false

If true then only values defined in "values" can be entered by the user.

NUMBER

Simple input for any number values and arrays of numbers.

Example

Example
{
"parameter" : "param_id",
"type" : "NUMBER",
"config" : {
"placeholder" : "select a value",
"multiple" : false,
"values" : [1, 2, 3, 4, 5]
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

defaultValues

Number or array of numbers

<empty>

Default selected value or array of values.

values

Array of numbers

<empty>

A defined list of values in the suggestion list.

strict

Boolean

false

If true then only values defined in "values" can be entered by the user.

CYPHER

Select with values loaded with a cypher query.

Example

Example
{
"parameter" : "param_id",
"type" : "CYPHER",
"config" : {
"placeholder" : "select a value",
"multiple" : false,
"query" : "MATCH (n:some_label) RETURN DISTINCT n.property LIMIT 20"
}
}

Configuration

PDO.config


Default

Description

placeholder

String

<empty>

Text shown in an empty input.

multiple

Boolean

false

Boolean value whether the num of selected values can be more than 1.

mandatory

Boolean

true

If false, the input is optional.

prefix

String

<empty>

String, that will be placed before the parameter's value in the final query.

suffix

String

<empty>

String, that will be placed after the parameter's value in the final query.

defaultValues

Value or array of values

<empty>

Default selected value or array of values.

query

MANDATORY

String


Cypher query for loading the values in suggestions.