Bloom features in detail

This chapter provides a closer look at the most commonly used features of Neo4j Bloom.

Bloom provides an easy and flexible way to explore your graph through graph patterns. It uses a vocabulary built from your graph and Perspective elements (categories, labels, relationship types, property keys and property values). Uncategorized labels and relationships or properties hidden in the Perspective are not considered in the vocabulary. To build a graph pattern search in Bloom, you use this vocabulary and either type in a near-natural language phrase or build the pattern step by step.

1.1. Near-natural language and graph patterns

Let’s say you want to find Products that are connected to Orders by any relationship. Using a near-natural language search expression, you can type in the search in several different ways. Here are a few examples with Bloom results for the first two:

  • Product Order

  • Order with Product

  • Order of a Product

  • Product in Order

  • Product having Order

product order
order with product

As shown above, Bloom interprets your search term using the vocabulary and as a result, offers suggestions for graph pattern queries you can run.

This is done by first breaking down the search input into word tokens. These tokens are then refined and combined together to create meaningful token permutations, which may be many in number. Bloom uses its knowledge of the graph schema as well as the data in your graph to filter out invalid permutations. The remaining permutations are presented in a comprehensive list of suggestions, which includes graph pattern and other matches (as described in Search bar).

The picture below shows how to interpret these suggestions before selecting one to run. You can toggle the suggestions with the arrows on your keyboard or just click the appropriate one. Once you have decided, press <RETURN> to execute.

search suggestions annotations

1.2. Step-by-step pattern building with proactive suggestions

Another approach to building graph patterns is to use the proactive suggestions feature of Bloom. This is useful when you need assistance with picking elements of your graph schema (e.g. relationship types from a label or categories that connect together).

Before you type anything in the search input box, Bloom proactively shows a list of your graph schema objects, like categories, label and relationship types. If appropriate for your query, you can start by picking one of the proactive suggestions. But, as explained in Near-natural language and graph patterns, you can always type your own query as well.

proactive blank input

If you pick something from the list (e.g. Order), Bloom assumes that you are interested in a graph pattern with that element. Bloom is able to further refine your suggestion options from there on, including offering additional suggestions on patterns you can create (e.g. categories that connect with Order).

proactive order selected

You can also combine both approaches mentioned above by typing a partial search term, picking a suggestion and continuing to build the search using proactive suggestions. Once you are satisfied with your graph pattern query, press <RETURN> to run it.

1.3. Suggestions based on property values

Category, label and relationship type matches are searched in Bloom’s in-memory metadata of available graph and Perspective elements. For property matches, Bloom queries the database instead to find suggestions. To do so, Bloom relies on property indexes to be set up in the database for any properties that should be searchable in Bloom. For small graphs with low cardinality in data values (e.g. the Movies graph, found in the example data sets), Bloom is able to search for property values without requiring an index.

Depending on the search input, the number of indexes, and the speed of typing in the search box, it is possible that Bloom will run a large number of index lookup queries to find relevant matches. Optimizations are built-in to delay firing queries while waiting for user to complete the input and to cancel un-needed queries if the input is changed.

Bloom will also attempt to hide pattern permutations from the suggestions list, if they are not found in the database. This may not be applicable in all situations. It is possible for database performance issues or network latency between the user’s machine and the Neo4j server to cause delays in showing search suggestions.

1.4. Case sensitivity of input

Neo4j database is case sensitive. By default, property values are matched by Bloom in a case sensitive fashion, if they begin with any of the matching tokens input by the user. If you would like search suggestions to be case insensitive, you can enable Case insensitive search and suggestions under Bloom settings.

By contrast, metadata elements like labels, categories, relationship types or property keys, are matched in a case insensitive fashion. Also, metadata elements are matched if they simply contain one of the search tokens.

Case insensitive matching of property values requires full-text indexes on all properties that will be searched. Without full-text indexes, Bloom will use case sensitive searching even with Case insensitive search and suggestions enabled.

2. 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 designer.

2.1. Static Search phrase

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.

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

2.2. Parameters in Search phrases

parameterized search phrase

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.

2.2.1. Parameter data types

Starting in version 1.2, the data type for every parameter must be specified. At this time, Bloom supports string, integer, float and boolean data types. 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 or datetime Cypher functions along with a string parameter. For example:

    MATCH (n:Employee) where n.startDate = date($inDate)
    return n

    where $inDate would be a string input like 2019-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 have float inputs like 37.55 and -122.31.

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

parameter chaining

2.3. Search phrases caveats

  • It is recommended that Search phrases either return a path or a set of nodes.

    Returning only relationships may cause unexpected behaviour 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.

Bloom allows users to always run a full-text search query against the database for their search input. This is useful when suggestions provided by Bloom do not satisfy the user’s need. Full-text search using the input is the last suggestion provided to the user in the suggestions list.

full text search

Starting with Neo4j 3.5, Bloom can take advantage of native full text indexes in the database. For both Neo4j 3.5 as well as older versions, Bloom also looks through other property indexes for a full text match. Additionally, for small graphs with low cardinality in data values (e.g. the Movies graph), Bloom is able to search in property values without requiring an explicit index. The full text string entered by the user is searched as one unit for these cases.

Full-text searching can be a time-consuming operation. Depending on the database, the state of indexes, and the search input requested, you may have a noticeable lag in response time because the queries may take a long time to return. That’s why full-text search is kept as the last option in the suggestions list, to avoid unintentional use.
When there is a delay in getting the search suggestions to return, the full-text search is the only option available to the user in the suggestions list. It is recommended not to use the full-text search suggestion inadvertently. The user may have to wait for a long time before results are returned and the full-text search can put a slightly larger workload on the database server.

4. Export data from Bloom

Bloom allows you to share your insights. Once you have found an interesting scene, you can extract your results as two CSV files, one representing the nodes and the other the relationships present in the current scene. This way, you may also use your results in applications other than Bloom.

In this example, you want a list of all German customers that order products from the Seafood category to pass on to a hypothetical marketing department for a promotion. Using the Germans ordering Seafood Search phrase from above, the scene displays the customers you are looking for. The context menu allows you to export your current scene as CSV. You can share the relevant file, or both, with marketing. If you need to edit the scene after using the Search phrase, for example remove a customer that should be exempt from the coming promotion, do so and export once you are satisfied. Only the nodes and relationships shown in the current scene will be exported.

export as csv

There are many cases where it may be useful to start Bloom with an initial context, allowing your Bloom journey to begin with that context in mind. This context may be supplied by an application, website, email or another medium you are using. To allow for an initial context, a link can be constructed with a pattern or search query that contains the identifiers needed so you immediately can begin exploration from that starting point.

Neo4j Bloom deep links are URLs that contain parameters that specifies the context for exploration. Links can be constructed for both the server hosted and Desktop hosted Bloom application. While the link parameters for both cases are the same, the URLs are specific to whether you are trying to access server hosted Bloom or Desktop hosted Bloom. Bloom accepts a search context and a perspective context as parameters in the link. Search context passed in gets populated into the search input and therefore can be any of the search input types that Bloom recognizes. Perspective context is used to choose the intended perspective for the particular exploration.

To illustrate this, picture that you are given a list of employees in a particular function:

bloom deeplink list

Based on this, you may wish to explore the graph of one specific employee in Bloom:

bloom deeplink

5.1. Server hosted Bloom

When you want to link to Bloom in a web browser, you will need to construct the link for server hosted Bloom. As described in [Installing server plugin], there is a slight difference in configuration depending on whether you are using Neo4j 3.x or 4.x. The link format is as follows:

For Neo4j 3.x:
http://<server_hosting_Bloom>[:<http-port>]/browser/bloom/[?search=search_input&perspective=perspective_name]
https://<server_hosting_Bloom>[:<https-port>]/browser/bloom/[?search=search_input&perspective=perspective_name]

In the example above, the link would be constructed as follows:

http://1.1.1.1:7474/browser/bloom/?search=employee%203115112&perspective=HRM%20Perspective
For Neo4j 4.x:
http://<server_hosting_Bloom>[:<http-port>]/bloom/[?search=search_input&perspective=perspective_name]
https://<server_hosting_Bloom>[:<https-port>]/bloom/[?search=search_input&perspective=perspective_name]

In the example above, the link would be constructed as follows:

http://1.1.1.1:7474/bloom/?search=employee%203115112&perspective=HRM%20Perspective

As indicated by enclosing with [], both search_input and perspective_name are optional and should be URL encoded if they contain spaces or other special characters.

5.2. Desktop hosted Bloom

When you want to link to Bloom and open it in Neo4j Desktop, you will need to construct the link for Desktop hosted Bloom. The link format is as follows:

neo4j://graphapps/neo4j-bloom/[?search=search_input&perspective=perspective_name]

In the example above, the link would be constructed as follows:

neo4j://graphapps/neo4j-bloom/?search=employee%203115112&perspective=HRM%20Perspective

Just like in the case of server hosted Bloom, as indicated by []; both search_input and perspective_name are optional and should be URL encoded if they contain spaces or other special characters.

A deep link to Desktop hosted Bloom will require an active connection to the specific Neo4j graph for which the link is applicable, and will use the user credentials stored in Desktop for the graph in question.

6. Default actions and shortcuts

A summary of the actions and associated keyboard shortcuts are below.

Table 1. Neo4j Bloom Actions and their Keyboard Shortcuts
Action Description Shortcut

icon magnifying glass

Inspect

Opens the detail view of a selected node, showing all its properties and labels

Mac: kbd:[⌘+I]

Windows: kbd:[Ctrl+I]

icon pencil

Edit node

Allows editing of all the properties of the selected node at once

Mac: kbd:[⌘+⌥+E]

Windows: kbd:[Ctrl+Alt+E]

icon invert

Invert Selection

Inverts the current selection

Mac: kbd:[⌘+⌥+A]

Windows: kbd:[Ctrl+Alt+A]

icon fit selection

Fit to selection

Zooms in and centers the selection on the canvas

Mac: kbd:[⌘+F]

Windows: kbd:[Ctrl+F]

icon expand reveal

Expand

Expands all the neighbours of the selected nodes)

Mac: kbd:[⌘+E]

Windows: kbd:[Ctrl+E]

icon expand reveal

Reveal

List/Detail view specific action. Reveals all the selected nodes or relationships on the canvas

icon path

Path

Shows the shortest path between two selected nodes

icon dismiss

Dismiss

Hides all selected nodes and relationships

Mac: kbd:[⌘+H]

Windows: kbd:[Ctrl+H]

icon dismiss

Dismiss other nodes

Hides everything that is not selected

Mac: kbd:[⌘+⇧+H]

Windows: kbd:[Ctrl+⇧+H]

icon add

Create relationship

Allows the creation of relationship between two selected nodes. The direction is set in the sequence in which the two nodes are clicked

icon add

Create node

Allows the creation of a node in a specified category. The newly created node will inherit all the labels that category has

icon duplicate

Duplicate

Duplicates a selected node with all the properties it has. The newly duplicated node is always selected and has no relationships to other nodes

Mac: kbd:[⌘+D]

Windows: kbd:[Ctrl+D]

icon clear

Clear Scene

Clears the whole scene and collapses the list view

icon undo

Undo

icon redo

Redo

icon jumpto

Jump to node/ relationship

Zooms in and centers the desired node or relationship on the canvas

Select All

Selects all properties and relationships on the canvas

Mac: kbd:[⌘+A]

Windows: kbd:[Ctrl+A]

Zoom In

Mac: kbd:[⌘ + +]

Zoom Out

Mac: kbd:[⌘ + -]