Queries Setting

Required Permission: Project Settings management (Read more about permissions in User Groups)

Table of Contents


The Queries setting is used to store the project's queries. There are several types of queries that can be defined with this setting (read more about queries in the Queries page):

  • Node Filter query

    • This type of query allows users to search for nodes using a simple condition builder and fulltext search. Any property or node labels (_dbLabels) can be displayed as columns in the result table. The user can define a simple condition to filter nodes and combine it with the fulltext search to find specific nodes. Selected nodes from the result can be visualized (used in a new visualization or added to the last opened visualization).

    • Query definition consists of "title", "description", "columns", and "condition" (optional) - see Explanation of JSON properties below.

  • Cypher/Gremlin query

    • This type of query allows users to enter any Cypher or Gremlin query (based on the user's permissions only read queries can be executed or any query if the user has the All Data permission).

    • Query definition consists of "title", "description", and "cypher"/"gremlin" - see Explanation of JSON properties below.

  • Query template

    • A template is a custom Cypher/Gremlin query presented to the user as a form with dynamic parameters (with suggestions) that the user can use to change and use the query without any Cypher/Gremlin knowledge. The Result Panel for this type of query shows basic statistical information about the returned elements and allows to visualize the result.

Configuration

  1. In the "Application Menu" (top right) choose page "Project Settings"

  2. In the "Project Settings" panel click on the "Queries" row.

  3. Enter JSON configuration and confirm by pressing the "Save" button.

Description of configuration

The configuration is entered in JSON format. Example:

[
{
"title":"Nodes in a table",
"description":"Persons and Companies of some subtype",
"condition":{
"labels":[ "Person", "Company" ],
"properties":[
{
"property":"type",
"values":[ "person", "company" ]
},
{
"property":"subtype",
"values":[ "auditor", "manager", "limited" ]
}
]
},
"columns":[
{
"property":"title"
},
{
"property":"type"
}
]
},
{
"title":"Cypher query",
"description":"Returns the first 100 nodes.",
"cypher":"MATCH (n) RETURN n LIMIT 100"
},
{
"title":"SomeRelType Pattern",
"description":"This pattern looks for all relationships of a particular type starting in nodes of some specific type. Max number of returned relationships is 100.",
"template":{
"textTemplate" : "Get all nodes related to nodes of type $type_list with relationship type $rel_type . Max number of returned nodes is 100",
"cypherTemplate" : "MATCH (a:SomeLabel)-[r:$rel_type]->(b) WHERE a.type IN $type_list RETURN r LIMIT 100",
"parameters" : [
{
"parameter" : "type_list",
"type" : "NODE_PROPERTY_VALUES",
"config" : {
"multiple" : true,
"labels" : ["SomeLabel"],
"property" : "type"
}
},
{
"parameter" : "rel_type",
"type" : "REL_TYPES",
"config" : {
"multiple" : false
}
}
]
}
}
]

Explanation of JSON properties:

Property

Values

Query type support

Description

title

MANDATORY

String

All query types

Title of the query.

description

String

All query types

Description of the query.

cypher

String

Cypher query

Cypher query defining the output of this query object.

gremlin

String

Gremlin query

Gremlin query defining the output of this query object.

template

Object

Query template

Cypher query Template object.

template.textTemplate

String

Query template

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."

template.cypherTemplate

String

Query template

The Cypher representation of the template query with dynamic parameters in the text (e.g. $type_list). Example: "MATCH (a:SomeLabel)-[r:$rel_type]->(b) WHERE a.type IN $type_list RETURN r LIMIT 100"

template.gremlinTemplate

String

Query template

The Gremlin representation of the template query with dynamic parameters in the text (e.g. $type_list). Example: "g.V().has('type', '$type').bothE('$rel_type').limit(100)"

template.parameters

Array of PDOs

Query template

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

String

Query template

Name of the dynamic parameter. Example: "type_list"

PDO.type

String

Query template

Type of the dynamic parameter. Available types are listed in the chapter below ("Cypher Query Template Configuration")

PDO.config

Object

Query template

Configuration of the dynamic parameter. This object is different for every PDO.type value. Please see the chapter below ("Query Template Configuration") for more information and examples.

condition

Object

Node Filter query

Condition for filtering nodes listed in the result table. Always use it together with columns.

condition.properties

null, undefined, Array of SFO objects

Node Filter query

An array of filter criteria. Defined criteria will be used in the search and only elements which match these criteria will be shown in the results. If not defined, set to null, or set to an empty array then no filtering is applied for this query. Each criterion is defined by SFO (Search Filter Object).

Logical "AND" is between each criteria in properties and logical "OR" is between items in values. Final condition based on properties can be for example: "type"="person" AND ("subtype"="auditor" OR "subtype"="manager").

SFO.property

MANDATORY

String

Node Filter query

Name of the DB property to filter on. This property has to be indexed, which means it has to be set in properties of Node Index configuration or Relationship Index configuration. See the fulltext index configuration here - Graph Connections#FulltextSearchConfiguration.

SFO.values

MANDATORY

Array of strings/numbers/booleans

Node Filter query

List of values of the DB property which are matched in the search filter. The exact string/number/boolean value is matched.

condition.labels

Array of strings

Node Filter query

Defines search criteria for node DB labels. Logical "OR" is used - a node passes the filter if it has at least one of the listed labels.

columns

MANDATORY

Array of CDO objects

Node Filter query

An array of column definitions used in the search results table. Each column is defined by CDO (Column Definition Object) which holds primarily the DB property name. Other metadata is used from Data Schema (e.g. title).

CDO.property

MANDATORY

String

Node Filter query

Name of the DB property used in the defined column. Values of this DB property will be listed as cell values in the result table column.


Query Template Configuration

Example of a Cypher Query 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 text that is shown to the user with dynamic parameters (prefixed with "$") that the user can change

    • cypherTemplate - Cypher query with dynamic parameters prefixed with $ (e.g. $param1, $date, ...). These dynamic fields will be replaced in runtime with user inputs (like node IDs or some filtering values)

    • parameters - config for every dynamic param used in the cypherTemplate and textTemplate

      • parameter - identification used in cypherTemplate

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

      • config - configuration for the specific param field (determined by the "type" attribute)

Dynamic Parameter types and their configuration options

Param Type

Notes

Config

NODE_FULLTEXT_SEARCH

Returns node's ID (internal database ID) or a list of ID's. It's using a fulltext index for searching for the nodes. The fulltext search configuration like min length and throttle delay from the Graph Connections is used.

  • "placeholder": text shown in an empty input.

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "resultProperties": list of properties that will be used in the result set to identify nodes.

  • "selectionProperties": list of properties that will be used in the selection set to identify nodes.

  • "exactMatch": boolean value whether the fulltext search should perform an exact match (a faster option) or non-exact match (a slower option but it's returning results matching the search pattern anywhere in the indexed properties).

  • "filter": an object containing "labels" and "properties" that will filter the nodes in the result set. The node in the result set has to have at least one of the listed labels and at least one of the listed values in the properties defined in the filter.

Example
{
"parameter" : "param_id",
"type" : "NODE_FULLTEXT_SEARCH",
"config" : {
"placeholder" : "search for nodes",
"multiple" : true,
"resultProperties" : ["Name", "Address", "Phone"],
"selectionProperties" : ["Name"],
"exactMatch" : true,
"filter" : {
"labels" : ["Person", "Company"],
"properties" : [
{
"property" : "State",
"values" : ["UK", "USA"]
}
]
}
}
}

NODE_PROPERTY_VALUES

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

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "labels": list of node labels for which the property values should be returned.

  • "property": key of the property that should be returned.

  • "defaultValues": default selected 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"
}
}

REL_PROPERTY_VALUES

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

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "relTypes": list of rel types for which the property values should be returned.

  • "property": key of the property that should be returned.

  • "defaultValues": default selected values

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

NODE_LABELS

Returns node's label or a list of labels.

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "defaultValues": default selected values

  • "cypherColonFormat": true/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

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

REL_TYPES

Returns rel's type or a list of types.

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "defaultValues": default selected values

  • "cypherColonFormat": true/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.

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

STRING

Simple input for any string values and arrays of strings.

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "defaultValues": default selected values

  • "values": defined list of values in the suggestion list

  • "strict": true/false

    • if true then only values defined in "values" can be entered by the user

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

NUMBER

Simple input for any number values and arrays of numbers.

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "defaultValues": default selected values

  • "values": defined list of values in the suggestion list

  • "strict": true/false

    • if true then only values defined in "values" can be entered by the user

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

CYPHER

Select with values loaded with a cypher query.

  • "placeholder": text shown in an empty input

  • "multiple": boolean value whether the num of selected values can be more than 1.

  • "mandatory": if false, the input is optional (default is true).

  • "prefix": string, that will be placed before the parameter's value in the final query.

  • "suffix": string, that will be placed after the parameter's value in the final query.

  • "query": cypher query for loading the values in suggestions.

  • "defaultValues": default selected values

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