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.