Search phrases for advanced queries
As mentioned in Search phrase, a Search phrase allows you to save a pre-defined graph query. Search phrases are defined in the Perspective drawer and automatically saved when created. Your saved Search phrases can be accessed from the Perspective drawer as well.
Static Search phrase
In this example using the Northwind graph, a static Search phrase has been saved with a Cypher query that spans multiple nodes and relationships.
The first box titled Search phrase
specifies the phrase that the user will type in partially or fully.
The description appears underneath all the Search phrase matches displayed to the user.
Explore will match any part of the Search phrase field in a case-insensitive fashion.
For example, typing in germ
or ORDER
or SeaFoo
will all show a match for Germans ordering Seafood
.
Dynamic Search phrases
Parameters can be used in Search phrases to make them dynamic.
In this example using the Northwind graph, there are 2 parameters (indicated with $
sign in front) added to the Search phrase.
These allow for further user input to determine which query should be run.
There are three options available for suggestions to these parameters:
-
No suggestions - If selected, the suggestions list will not show when using the Search phrase.
-
Label-key - Allows picking label:key pair for the suggestions list.
-
Cypher query - Custom written Cypher query for the suggestions list.
Parameter data types
The data type for every parameter must be specified.
Explore supports string
, integer
, float
and boolean
data types.
Additionally, Explore also supports the temporal types Date
, Time
, DateTime
, LocalDate
, and LocalDateTime
.
Temporal types with time zones, i.e. Time
and DateTime
, can also be used for rule-based styling or filters.
You can search for them and get search suggestions and also edit them in the Inspector (provided that you have write access to the graph).
User input for a parameter gets converted to the data type specified for it.
If you want to setup parameters for other data types supported in Cypher, you can use a combination of string
, integer
, float
and boolean
inputs to build other data types for Cypher.
Please see Cypher manual → Values and types for more information on data types.
A couple of scenarios are described below, but there are a number of others that you may come across.
-
Temporal (date or time) type: When you have temporal properties, you can use
Date
,Time
,DateTime
,LocalDate
, orLocalDateTime
Cypher functions along with a string parameter. For example:MATCH (n:Employee) where n.startDate = date($inDate) return n
where
$inDate
would be astring
input like2019-05-23
. -
Spatial type: For spatial properties, you can use point or distance Cypher functions along with float parameters in a Search phrase. For example:
MATCH (n:Store) where n.location = point({latitude:$lat, longitude:$long}) return n
where
$lat
and$long
would havefloat
inputs like37.55
and-122.31
.
Chaining of parameters
The user-input for one parameter can be used to filter the list of suggestions provided for a subsequent parameter.
This is referred to as parameter chaining.
For example, consider the Search phrase used above with multiple parameters, Customers from $country ordering $category
.
In this case, perhaps you want to restrict the list of category suggestions based on the country the user picked, parameter chaining will help you achieve this.
To use it, the list of category suggestions will need to be constructed using a Cypher query that uses the $country
parameter to filter categories.
See image below for an example of what this could look like.
Search phrases caveats
-
Explore will limit the number of records processed for the visualization to 10000 unless a smaller limit has been set in the query. This is to prevent the app from hanging or crashing for queries that return too many records.
-
It is recommended that Search phrases either return a path or a set of nodes.
Returning only relationships may cause unexpected behavior in addition to no graph visualization changes.
For example, the following query:
MATCH ()-[r:CONNECTED_TO]->() RETURN r
Should be refactored to:
MATCH p = ()-[r:CONNECTED_TO]->() RETURN p
-
Furthermore, be aware that it is possible to modify data with a Search phrase as any valid Cypher query can be used. It is not recommended to use Search phrase for this goal as an end-user might not be aware of the consequences of running a Search phrase that includes WRITE transactions.