Neo4J is a commonly used graph database. Rather than rows and columns as is mostly commonly seen as a data format, Neo4J stores nodes and edges in a graph structure. Individual records are nodes, with any number of properties attached. Additionally, any node in your model can have any kind of connection to any other node--and that connection itself can have properties.

Storing data that represents networks and connections can be an incredibly useful way to interact with it. Exaptive applications can fully take advantage of this powerful graph database engine and makes its capability a first class citizen of your xap.

Connecting to your Neo4J database

Like almost anything you can think of, there is an Exaptive component that serves as a gateway with your Neo4J database. It allows you to make connections, run queries, and use the response data from those queries throughout your xap. And not only can you read the data in your database, you can set it up to write data back based on interactions from users.

Once you have the Neo4J component in your studio, you can pull it into any xap.

There are two inputs the component needs. The first is a set of configuration options.

Most of these are self-explanatory. You will need to provide authentication information like your username and password, as well as connection properties like the DNS address of the server hosting the database and the port to connect to (7474 by default). The other three options require slightly more explanation. (There is additional documentation and examples available on the component page).

  • return_type: Neo4J queries can return two types of responses: a graph (nodes and edges) or tabular data (rows and columns). Depending on how you would like the component to encode the returned data, set this value to either graph or tabular.
  • agg_edgesIt is common for graphs to have multiple edges that connect any two nodes. If you set this value to true, it will aggregate those multiple edges into a single edge.
  • agg_field: since edges can have multiple properties, choose which edges properties should be used to determine the uniqueness of an edge when aggregating like edges.

Running a query

Once you have your configuration options set up, it's time to run a Cypher query. The cypher_query in event takes a string query to submit to the database.

This string query can easily be dynamically driven. Consider using the String Template component to combine inputs from elsewhere in your application to control the parameters of your Cypher queries. See the companion article on Hadoop/Spark where this method is employed in the same manner to dynamically generate SQL query strings.

What kind of data will you get back?

If you specified that you wanted tabular data back, then you will receive a list of entities. Each entity is analogous to a row, and each property of the entity is a column and corresponding cell value.


    {'col1': 'val1', 'col2': 'val2'},
    {'col1': 'val1', 'col2': 'val2'},


If you specify that you want graph data back, then you will receive a single entity with two top level values: nodes and edges. Nodes will be a list of entities, each of which is a single node with all of its properties. There is one property, _id, on each node that is guaranteed to be unique across all nodes in the set. Edges is also a list, with each edge represented as an entity of properties of that edge connecting two nodes. Included in edge properties are a source (_src)and destination (_dst) property, that link that edge to which nodes it connects.


            '_id': 'hashed id from Neo4J system',
            '_label': 'node label from Neo4J',
            'other': 'all other attached properties from database'
    'edges': [
            '_src': 'source node of edge, references a node._id',
            '_dst': 'destination node of edge, references a node._id',
            '_type': 'edge type from Neo4J',
            '_weight': 2,  //exists only in graph mode, when agg_edges is True
            'other': 'all other attached edge properties'


What else can you do with the data?

Once you have your data output from the component, there are many things you can do with it:

  • Visualize it with a Network Diagram, see your graph on the screen, interact with it, and map the visual properties any way you like.
  • Find and visualize a path through your network. See how to get from one node to another and visualize where this path is in the larger network.
  • Layout the graph according to many different properties; everything from how many edges are connected to a node, to how influential the node is in the entire network.
  • Aggregate the graph by common properties of multiple nodes. The original structure of the network does not have to be the only one you can use.