(UPDATED MAY 2026). So, you want to build a python app or Jupyter notebook to utilize Neo4j, but aren't too keen on coding a lot of string manipulation to programmatic create ad-hoc Cypher queries? You're in the right place: the GraphAccess library (formerly called NeoAccess) can do take care of all that, sparing you from lengthy, error-prone development that requires substantial graph-database and software-development expertise!
"GraphAccess" is the bottom layer of the technology stack provided by the BrainAnnex open-source project. All layers are very modular, and the GraphAccess library may also be used by itself, entirely separately from the rest of the technology stack. (A diagram of the full stack is shown later in this article.)
GraphAccess interacts with the Neo4j Python driver, which is provided by the Neo4j company, to access the database from Python; the API to access that driver is very powerful, but complex - and does not provide higher-level services.
The Handover from Graph Database Specialists to Data Scientists & General Python Programmers
One could do a lot directly with the Cypher query language... And there are times when working directly with Cypher is necessary or convenient - just like when one may want to work interactively with SQL in a relational database.
But what if you need to do something programmatically?
Or what if you don't want to deal with writing Cypher queries, or if someone working on the project may not be an expert in Cypher?
Well, that's where the GraphAccess library comes in to save the day!
In some ways, the GraphAccess library can be thought of as a handover from data engineering that requires expertise in Cypher, passing the baton to data scientists and software engineers who may have only limited understanding of what graph databases are, and limited or no knowledge of Cypher.
The goal of GraphAccess is to make it easy and convenient for a Python programmer or Data Scientist to manage a lot of the typical database operations - without having to deal with Cypher.
If you're accessing Neo4j programmatically, and you wanted to create functions to provide typical database operations (such as create a new node, or link 2 existing nodes), you'd be faced with a lot of tedious - and very error prone - string manipulations to create the Cypher queries in your Python scripts. Not to mention having to deal with pesky special cases (such as, can one have blank spaces in a node label? What if I later need to have more than 1 label per node?)
Those aggravations are something best avoided - and left to the GraphAccess library, which has grappled with these issues for a long time! And it has been unit-tested at great length...
Example: Create a New Node
By using the GraphAccess library, all you have to do is: create a connection database, and then run the method "create_node" and pass arguments to it.
That's all! (Compare to the Cypher query-language equivalent, below...)
And if you want to have a second "label" for the node, just change the label string into a list - and you don't have to worry about it! Similarly, if you have blank spaces in any of the labels, you can just simply do it and not worry about it.
The GraphAccess library will worry about the Cypher syntax needed to deal with multiple labels, or needed to deal with blank spaces and labels.
No Deep Graph-Database Expertise Needed for Many Typical Operations
Some of the beauty of using a library like GraphAccess is that all you need is a relatively modest knowledge of the essentials of graph databases; something that you can really explain very quickly, with a diagram in the style of the familiar "friends-of-friends" (as done, for example, in Part 1 of this series of articles.)
As long as someone knows the basics... knows about nodes representing records with fields in it... and knows that nodes can be connected by relationships (aka links) that have a name and can also have attributes... and, finally, that each node can have one or more labels (which are reminiscent of table names in relation databases)...
Well, that's the fundamental knowledge - and just about all that one needs to know - to do quite a bit using the GraphAccess library!
Conversely, people who are experts in Cypher, can easily submit any arbitrary query to GraphAccess - and get the results (including errors and status of the operations) in a variety of convenient Python data structures.
Block Diagram of GraphAccess
Repeated from the top of this article, here's a block diagram of what the the GraphAccess library consists of:
Shown at the center, there's a Foundational Layer, and a set of Cypher utilities.
The foundational layer takes care of operations like connecting to the database, running generic Cypher queries, and receiving complex data structures (and status/error info) from the database.
The Cypher utilities take care of a lot of the very specific syntactic operations to create correct Cypher queries.
Armed with this foundation layer, one can easily run any Cypher query.
But in practice, most of the time, all that one needs to do are a small set of very typical operations. For example: create notes, delete notes, modify fields, add/delete relationships, restructure relationships, follow links. As well as operations involving labels, indexes and constraints.
GraphAccess allows the execution of those typical scenarios with simple, streamlined function calls.
It also provides a group operations about imports and exports. For example, dealing with files or Pandas. Oftentimes, the import/export operations are done at a higher layer, such as the schema layer (see next section), not at the GraphAccess layer. So this is something of a separate group - and might end up getting split off in the future.
Who uses GraphAccess, and how does one use it?
A key user of the GraphAccess library is the GraphSchema library, the layer above it in the technology stack of the BrainAnnex open-source project:
And the layers above the GraphSchema library could in principle also use GraphAccess directly - although it's probably not a good idea; that's why I'm using dashed arrows there.
But anyone can use the GraphAccess library directly, if they so wish: you can use it with a Python script, or you can use it with a Jupyter notebook. The remainder of the technology stack shown above is NOT required; if it doesn't suit your needs, you can simply opt to use the GraphAccess library directly.
In situations where you don't really care about the schema, maybe because you're doing exploratory analysis or a demo, that's a use case of using the GraphAccess library directly, and by itself. (In fact, it is independently released, and all you need to do to use it, is to install that one library from the standard python library repository.)
But in most situations, it may be better to go through the GraphSchema layer (the 2nd layer from the bottom, in the above diagram.)
Brief History and Current Status
Back in 2020 I created, and released to open source, a library called Neo4jLiaison, now obsolete, which was a forerunner of what has become the GraphAccess library.
In the following year, 2021, I was working at pharmaceutical giant GSK. At that time, I combined my library with another library that someone else in the company had created.
Our two libraries conveniently happened to be fairly complimentary. So, we merged them, and then expanded the combined library quite substantially - and added a lot of unit testing.
After a good part of a year of development, GSK pharmaceuticals very graciously released it as open source at the end of 2021, under the name of the NeoInterface library - after requiring a VERY EXTENSIVE amount of unit testing.
At that point I forked the open-source library, renamed it NeoAccess - and expanded it a fair bit throughout 2022 and 2023, using it as the new foundation of the overhauled BrainAnnex open-source project (which dates back to 2015, and was originally built on top of a relational database), as well as at 2 other use cases at jobs I held during that time.
In 2023, the GraphAccess library (back then still called "NeoAccess") started being distributed independently from the rest of the BrainAnnex technology stack.
In 2025, in anticipation of future support of other graph databases besides Neo4j, "NeoAccess" was renamed "GraphAccess", and it was again incorporated into - and released alongside - the main "BrainAnnex" library.
As of May 2026, GraphAccess supports version 4 and version 5 of the Neo4j database - and is expected to also support other databases at a future date. (We had an earlier port to AWS Neptune, but that isn't currently being maintained.) The GraphAccess library largely insulates the higher layers from the specifics of the actual graph database being used.
How to Use GraphAccess
IMPORTANT:you do NOT need to install the full BrainAnnex app if you only need the GraphAccess library!
To use the GraphAccess library: pip install it, as part of the BrainAnnex library, from the standard PyPI distribution , either for version 4 of Neo4j or for version 5.
For example, place brainannex-neo4jv4 or brainannex-neo4jv5 in your "requirements.txt" file (or use your IDE to install the latest version of either one.) Then, in your code, include:
frombrainanneximport GraphAccess
At that point, you can issue commands such as:
host="you_host_info"# EXAMPLES: bolt://1.2.3.4 OR neo4j://localhost
db =GraphAccess(host=host, credentials=("neo4j", your_password_info))
neo_car = db.create_node("Car", {'color': 'white', 'make': 'Toyota'})
neo_person = db.create_node("Person", {'name': 'Julian'})
number_links_added = db.add_links(neo_car, neo_person, rel_name="OWNED_BY")
Of course, you will also need an installed Neo4j database - or simply register for the free "sandbox" short-term hosted solution described in a previous article.
Tutorials
They are in the form of annotated and illustrated Jupyterlab notebooks, which come as part of the Brain Annex repository:
The above link are just VIEWS of notebooks. If you want to actually run them from your machine, follow the instructions in the previous section.
Further Directions
List of functions in the GraphAccess library
The GraphAccess library repository
Versions & changelog (combined with the whole BrainAnnex technology stack)
Comments
Post a Comment