Neo4j Bloom helps people connect and interact with their graph data.
Exploring the meaning of data with an appropriate visualization is extremely important for us, and for the users who want to explore the relationships and properties stored in their database.
Bloom lets us easily expand and follow the different paths in our graph, which is great for exploration and analysis, but we can enhance the capabilities of Bloom even further by leveraging the power of Neo4j Cypher.
Cypher is a great query language that allows us to query our data and perform write operations, like updating properties or adding new relationships. Bloom already supports Cypher queries in Search Phrases — using the search box the user can add a specific command, the Cypher code to execute along with any parameters — and recall it easily from the UI.
The new Bloom 2.2 expands this capability by adding a new tool in our toolbox: “Scene Actions.”
What’s a Scene Action?
A Scene Action lets us execute a Cypher query contextually on a specific user selection of nodes and relationships in the scene.
Once the Scene Action is configured, the user will be able to select nodes or relationships and run the custom Cypher query on those nodes/relationships.
Adding a Scene Action is straightforward!
Open the Perspective Designer panel on the left side, select “Saved Cypher” and then “Scene actions.”
The Action name will be shown when we open the right click context menu.
Cypher query contains the code to execute. To reference the user’s selection, use the implicit parameters $nodes and $relationships, and Bloom will take care to pass the values of the parameters as Lists of ids.
- The expression id(n) in $nodes will let us reference the nodes based on the user selection.
- Same with id(r) in $relationships, but for relationships.
Action availability allows us to define whether we should show the Scene Action in the context menu or not, based on the types of nodes and relationships in the user’s selection. By default, all nodes and relationships are included so the scene action will appear in the context menu regardless of what the user selected before right-clicking.
Let’s Dive In!
The following examples are created using the commonly available dataset “Northwind.” We suggest starting from your own database, and you can use Aura DB Free to set up your own instance.
Add the data following this tutorial about setting it up or simply start Neo4j Browser and execute the command :play northwind-graph, then follow the easy step-by-step tutorial. You will get all the data you need!
Here’s a brief explanation of the data model we’ll use (as pictured):
- ( Customer )-[ PURCHASED ]->( Order )
- ( Order)-[ ORDERS ]->( Product )
- ( Product )-[ PART_OF ]->( Category )
- “Order” contains the basic information of each order
- The relationship “ORDERS” contains the order item details (quantity and price of a product in the Order)
We will use different examples to show some applications of Scene Actions.
Scene Action 1: Get the Products Purchased by a Customer
Starting from a set of Customers we want to retrieve all the Products that the Customers have purchased over time.
If we want to get this information using existing Bloom features, we would need to use the “Expand” action twice — once to see a customer’s Orders and again to see an Order’s Products.
We can create a Scene Action and limit the availability to user selections that include the “Customer” node label.
MATCH p = (c:Customer)--(:Order)--(:Product)
WHERE id(c) in $nodes
RETURN p
This example highlights the following advantages:
- We can do any read operation using the selected nodes/relationships as input values.
- We can transform repetitive operations into a Scene Action.
- We can simplify an analyst’s exploration using a command name that is meaningful in the context of the data model.
Scene Action 2: Get the Latest Order
We can also expand and select paths based on property values — in this case, we want to retrieve the most recent order.
This Scene Action can be applied to selections having either Customer or Product node labels, and we can get the most recent Order purchased by a Customer, or the most recent Order containing a specific Product.
Here’s the Cypher we can use to create a Scene Action for Customer/Product.
MATCH (c)
WHERE id(c) in $nodes
CALL {
WITH c
MATCH (c)--(m:Order)
RETURN max(m.orderDate) as maxOrderDate
}
WITH c, maxOrderDate
MATCH p = (c)--(o:Order)
WHERE o.orderDate = maxOrderDate
RETURN p
In this example, we see some additional advantages:
- We can explore paths based on properties, aggregate functions, subqueries, and procedures (including calls to APOC and Graph Data Science).
- We can reuse the Scene Action for several Categories and hide it for others.
Scene Action 3: Get Orders That Contain More Than One of the Products Selected
Given a set of Products selected, we want to retrieve all orders that contain more than one product in the selection.
In this case, the query will search for some shared data within the selection.
This Scene Action is only for Product category:
MATCH p = (w:Product)—-(:Order)--(q:Product)
WHERE id(w) in $nodes and id(q) in $nodes
RETURN p
Here we see more advantages:
- We can retrieve data based on shared property values or shared relationships within the selection.
- We can reuse the selection ($node) inside the same query more than once.
Scene Action 4: Get Cheap and Expensive Products
This query is very similar to the previous one, but in this case, we use a UNION of two disjoint queries. As before, we can apply the selection more than once and retrieve the information we need.
This Scene action is for Category nodes:
MATCH (c:Category)-[r]-(p:Product)
WHERE id(c) in $nodes and p.unitPrice < 10
RETURN *
UNION ALL
MATCH (c:Category)-[r]-(p:Product)
WHERE id(c) in $nodes and p.unitPrice > 50
RETURN *
Advanced Scene Actions
The following examples will update/create data in the database. The user is required to have write privileges in the database and the setting “Allow write transaction” enabled in the “Experimental Features” section in Bloom. The “Experimental Features” can be enabled in the Settings panel.
Scene Action 5: Increase Ordered Quantity by 10
Until now we have just retrieved data from the underlying graph. Sometimes we want to change the data and trigger a more complex series of operations.
In this example, we want to enable the user to increase the quantity of a specific Order item, and the following steps are needed to perform this business operation:
- Select the Order item, which is stored in the relationship ORDERS between the Order and the Product.
- Increase the “quantity” value by 10.
- Select the Product node and increase the value of “unitsOnOrder” by 10.
- In the Product node, decrease the “unitsInStock” by 10.
- If there are not enough “unitsInStock” of the product we should not perform the operation.
The following Scene Action can be applied to relationships of type ORDERS:
MATCH ()-[r:ORDERS]-(p:Product)
WHERE id(r) in $relationships and p.unitsInStock > 10
WITH r, p
SET r.quantity = r.quantity + 10
SET p.unitsOnOrder = p.unitsOnOrder + 10
SET p.unitsInStock = p.unitsInStock — 10
RETURN *
Bloom will continue to respect Neo4j’s permissions for users attempting to write to the database, so the user would need to have appropriate authorizations on their database role.
The following advantages can be seen in this example:
- We can update relationships properties (write operation) by changing the underlying data and update the visualization in Bloom. (We can change nodes properties as well.)
- We can also apply Scene Action to relationships and we can limit the scope of applicability of the Scene Action to a single relationship type.
- Because we can easily perform several operations involving updates in nodes and relationships, a Scene Action can implement business logic procedures, making them easy to execute.
Using Scene Action and Style Rules
Try to add a style rule for Products based on “unitsOnOrder” — you’ll see an immediate change when applying this Scene Action in the scene!
Scene Action 6: Create a New Order From a Selection
Until now we have retrieved data and updated properties, but we can do much more, like adding new data or facilitating data insertion.
Given a selection of products and customers we want to be able to create new orders with the following requirements:
- Every selected customer will have a new Order connected with all the selected Products.
- Prefill some values in the new Order, like “customerID,” “orderDate,” and “orderID.”
- Connect the new Order with the Products with an ORDERS relationship.
- Prefill some values in the relationship, like the “orderID” from the order and the “unitPrice” from the Product. Other properties can have a default value.
The following Scene Action will help us automate this logic, in the exact order of the requirements above.
MATCH (c:Customer)
WHERE id(c) in $nodes
WITH c
CREATE (c)-[r1:PURCHASED]->(o:Order)
SET o.customerID = c.customerID
SET o.orderDate = toString(localdatetime())
SET o.orderID = toString(id(o))
WITH c, o, r1
MATCH (p:Product)
WHERE id(p) in $nodes
CREATE (o)-[r:ORDERS]->(p)
SET r.discount = '0'
SET r.orderID = o.orderID
SET r.productID = p.productID
SET r.quantity = 1
SET r.unitPrice = p.unitPrice
RETURN *
Select the Products and Customers first:
The Scene Action will create new nodes and relationships:
With this final example, we see even more advantages of Bloom’s Scene Actions:
- We can easily create new nodes and relationships in one step.
- The selection of the Customers and Products is done visually.
- Customize the insertion of new data based on specific business logic.
- Add multiple nodes and relationships.
- Set new property values from the current graph data and define some default values for other properties.
- The action is very easy to use — the user just needs to select the products and the customers. After that, the user can change the properties directly in Bloom.
- If we select more customers, we will create different orders.
- The insertion is done in the same transaction, keeping this operation secure from a consistency point of view.
That’s All ?
The applications of Scene Actions are limited only by the power of Neo4j Cypher.
Even with this small dataset we demonstrated that we can show subsets of the graph, alter data in the database, and create entirely new data.
We can automate repetitive tasks and implement complex operations in a safe and controlled manner, which empowers users to efficiently manipulate the graph data and perform business operations.
So what would you use this feature for?
Give us feedback or suggestions here. If you need more technical information about Bloom, see the documentation, or for more use cases take a look at our website.
Bloom Scene Actions — different way to interact with your graph was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.
