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.
1. 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.
2. PDO - Parameter Definition Objects
Every dynamic parameter has different configuration options. Please read more about the specifics in the next chapters.
2.1. NODE_FULLTEXT_SEARCH
Returns node's ID (internal database ID) or a list of IDs. It's using a fulltext index for searching for the nodes. The fulltext search configuration like min length and throttle delay from the Search Settings is used.
Example
{
"parameter"
:
"param_id"
,
"type"
:
"NODE_FULLTEXT_SEARCH"
,
"config"
: {
"placeholder"
:
"search for nodes"
,
"multiple"
:
true
,
"useArrayBrackets"
:
true
,
"resultProperties"
: [
"Name"
,
"Address"
,
"Phone"
],
"selectionProperties"
: [
"Name"
],
"exactMatch"
:
true
,
"filter"
: {
"labels"
: [
"Person"
,
"Company"
],
"properties"
: [
{
"property"
:
"State"
,
"values"
: [
"UK"
,
"USA"
]
}
]
}
}
}
Configuration
PDO.config | Type | 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. |
useArrayBrackets | Boolean | true | If true, the replaced value is in brackets, e.g. [ "value1", "value2" ]. If false, the replaced value is without brackets, just values separated with a comma, e.g. "value1", "value2". |
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. |
resultProperties mandatory | Array of strings | List of properties that will be used in the result set to identify nodes. | |
selectionProperties | Array of strings | List of properties that will be used in the selection set to identify nodes. The "resultProperties" value is used if empty. | |
exactMatch | Boolean | false | Boolean value whether the fulltext search should perform an exact match (a faster option) or a non-exact match (a slower option but its returning results matching the search pattern anywhere in the indexed properties). |
filter | Object | <empty> | An object containing "labels" and "properties" that will filter the nodes in the result set. The node in the result set must have at least one of the listed labels and at least one of the listed values in the properties defined in the filter. |
2.2. NODE_PROPERTY_VALUES
Returns node's prop value or a list of prop values.
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 | Type | 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. |
2.3. REL_PROPERTY_VALUES
Returns rel's prop value or a list of prop values.
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 | Type | 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. |
2.4. NODE_LABELS
Returns node's label or a list of labels.
Example
{
"parameter"
:
"param_id"
,
"type"
:
"NODE_LABELS"
,
"config"
: {
"placeholder"
:
"select a node label"
,
"multiple"
:
false
}
}
Configuration
PDO.config | Type | 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. |
2.5. REL_TYPES
Returns rel's type or a list of types.
Example
{
"parameter"
:
"param_id"
,
"type"
:
"REL_TYPES"
,
"config"
: {
"placeholder"
:
"select a relationship type"
,
"multiple"
:
false
}
}
Configuration
PDO.config | Type | 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. |
2.6. STRING
Simple input for any string values and arrays of strings.
Example
{
"parameter"
:
"param_id"
,
"type"
:
"STRING"
,
"config"
: {
"placeholder"
:
"select a value"
,
"multiple"
:
false
,
"values"
: [
"value_1"
,
"value_2"
,
"value_3"
]
}
}
Configuration
PDO.config | Type | 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. |
2.7. NUMBER
Simple input for any number values and arrays of numbers.
Example
{
"parameter"
:
"param_id"
,
"type"
:
"NUMBER"
,
"config"
: {
"placeholder"
:
"select a value"
,
"multiple"
:
false
,
"values"
: [
1
,
2
,
3
,
4
,
5
]
}
}
Configuration
PDO.config | Type | 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. |
2.8. CYPHER
Select with values loaded with a cypher query.
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 | Type | 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. |