This development brings a host of advantages and opportunities for both the neomodel community and Neo4j users alike. In this post, we’ll cover what value this brings to the library and implies for its future.

A Community-Focused Library

Neo4j Labs is a means for exploring new technologies with Neo4j with open-source projects. It focuses on projects that see interest and adoption and manages expectations and a minimum level of quality. Many important product developments had their origins in Neo4j Labs like graph data science, the GraphQL library, the Kafka and Spark integrations, and APOC core.

Neo4j Labs - Neo4j Labs

Like the other Neo4j Labs projects, neomodel remains an open-source, and completely community-driven library.

Joining the Neo4j Labs program implies the following:

• Clear expectations: Labs projects are experimental and not officially product-supported, although some of them (like NeoDash, neosemantics, and neomodel) have available Neo4j Services packages for development and support.
• Quality standards: To be part of Labs, you need to adhere to certain minimal quality standards, which ensures enhanced code quality (unit and integration testing), security checks, automated tooling (CI/CD), etc…
• Releases and responsiveness: Labs projects must have regular releases, e.g., to support newer Neo4j versions and respond timely to issues and user questions. Neo4j involvement: At least one maintainer must be Neo4j employee.
• Collaboration and evolution: It provides the library with closer interactions with the Neo4j product and field teams. For example, it can benefit from learnings gained in the official OGMs for Java/Spring and GraphQL. Learnings from Labs projects will be integrated into future product development.
• Real-world usage and interest: In the case of neomodel, this also happened because neomodel is being used in production by Neo4j Services customers with special requirements — see author disclaimer at the end of this article for an example.

You can find all the Neo4j Labs projects and the Neomodel pages on the website.

neomodel - Python OGM for Neo4j - Neo4j Labs

Now Fully Supporting All Current Versions of Python and Neo4j

Since neomodel got back into active maintenance mode in early 2023, the main focus has been to improve tooling (above all integration tests) to ensure robustness, confidence, and version support. The maintainence team is now pleased to announce that neomodel fully supports all supported versions of Python and Neo4j — both Community and Enterprise — as seen in the Integration tests matrix in GitHub Actions.

• Latest neomodel release
• Latest Django-neomodel release

Future Evolutions

Stay updated on neomodel’s future evolutions, and please join the discussions on its GitHub repository :

• The Issues log is being monitored again — to the extent that time allows, and we are trying to summarize and clean up the old issues.
• The Discussions page is open to anyone and will contain announcements.

What Is Neomodel and How Does It Work?

We intend to release new, updated content around the library. But until we can work this out, please see the following content written for previous versions of the library — the sample projects mentioned in these articles have been kept up to date :

• Simple example
• Neo4j for Django developers
• Talk at upcoming DjangoCon
• Documentation

For more insights and discussions, join the neomodel community on GitHub and stay tuned to the latest developments.

Looking forward to your feedback, Marius

Disclaimer: About the Author and their Role — and how neomodel benefits from field experience.

The author of this article is a member of Neo4j’s Professional Services team, dedicated to assisting customers in successfully deploying Neo4j projects into production environments. A good example of an impactful, production-type project using neomodel is OpenStudyBuilder, driven by Novo Nordisk. OpenStudyBuilder showcases the practical application of neomodel within real-world projects and also provides specific requirements, which in turn become new features for the community thanks to Neo4j’s Services team merging it back into the library. It is also a great example of an Enterprise organization leveraging and donating back to open source, but that would deserve a whole article.

Neomodel: Python OGM for Neo4j Extends Version Support and Moves to Neo4j Labs was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Background

Sprint cycles are an extremely common way for development teams to plan and execute the development of projects. This agile method can be used by a variety of different development teams. Working in sprint cycles allows teams to get fast feedback, improve their product’s quality, reduce risk, and it makes it easier to stay on schedule.

The Problem

Project Managers must work carefully to make sure the sprint cycles can flow as best as possible with minimal stagnation. To do so, Project Managers set aside time for sprint planning where they can create a road map of what tasks need to be done in what order so that the project can progress and be completed. This can be especially difficult to accomplish since some tasks can be more important or more complicated than others or rely on the completion of other tasks before they may be worked on.

The Solution

The Orai application is a recommendation engine built around project management data. It combines the querying power of the Neo4j graph database with the flexibility of the Django web framework using the django-neomodel plugin.

GitHub - Group13-FAU/Orai

The Orai system monitors all tasks dependent on each other and builds sprints from them with the highest priority tasks getting scheduled first. The length of these sprints is based on each tasks’ complexity, allowing the user to gain more control of how much the development team can handle.

Furthermore, the user can control the number of sprints, the complexity of sprints, the essential tasks, and the number of essential tasks that can be worked on per sprint.

Implementation Details

Orai takes in four user inputs:

• The max complexity value of each sprint
• Minimum number of sprints desired
• (Optional) The maximum length of the dependency tree
• A set of Storys to be prioritized

The Story Model and Relationships are extremely lightweight — the application uses only Story nodes and a REQUIRES relationship between Storys:

from neomodel import (
    StringProperty,
    StructuredNode,
    RelationshipTo,
    IntegerProperty,
    FloatProperty,
    BooleanProperty
)


class Story(StructuredNode):
    # Properties
    nodeID = IntegerProperty(index=True, db_property='id')
    sentimentScore = StringProperty()
    sentiment = StringProperty()
    notes = StringProperty()
    name = StringProperty()
    value = StringProperty()
    acceptance_criteria = StringProperty()
    complexity = IntegerProperty()
    priority = FloatProperty()
    approved = BooleanProperty()

    # Relationships
    requires = RelationshipTo('.story.Story', 'REQUIRES')

The project used a dataset from The SilverLogic’s internal project management system.

MATCH p=(:Story)-[:REQUIRES]->(:Story)
RETURN p
LIMIT 10

In the example output above, if a team wanted to prioritize the implementation of the Invoice Picker story, they would have to first complete the Share text and No Stories Empty State stories, as they are prerequisites.

Given enough team members and a long-enough sprint, it might be possible to work on Share text and No Stories Empty State in parallel, and immediately move to Invoice Picker once both tasks are completed. If the team knows roughly how many complexity points they can complete in one sprint — and have thoughtfully given their best estimates to the stories in the backlog — having a planning tool that can provide example roadmaps that take into account inter-story relationships can be a useful starting point for planning and scheduling.

Example Input Form

Imagine selecting the following parameters:

Max complexity value per sprint: 12

Minimum number of sprints: 3

Priority Story :

• Epic / Actor / Platform Archiving
• Harvest Integration V2 Phase 4 Time Entry Augmentation
• Invoice Time Entry Moving

Example Output

The above is an example of a sprint cycle. The required stories are organized such that the stories it depends on are scheduled before it. For example, Sub Epics requires that Invoice Time Entry Moving be completed first.

Conclusion and Retrospective

Over the course of two semesters, Logic13 was able to successfully design and implement a low-cost solution to the project sponsor’s (The SilverLogic) requested problem.

Our project, Orai, is a user-friendly system that can generate optimal sprint cycles from user inputs and display them along with informative details about the sprints and the tasks.

The team was able to learn new programming and computer skills, such as working with and collaborating through GitHub. The team also learned about software development and how to help customers with their requests by giving them alternatives and explanations.

If we had the opportunity to start over and do it again, we’d make a few improvements. One is that on the suggestion page where the user inputs the information, we would add more information to the list of tasks to make it easier for the user to make a choice. This would make the system easier and more convenient to use for the user. Besides that, the team believes this solution is the most optimal and efficient way to schedule tasks for sprints. We are very proud of the work put into the development of the system.

Team Logic13

Team Logic13 (pictured below) consisted of very talented individuals that came together to develop a great system. Felix Medrano took on the role of project lead and handled project scheduling and synchronization, as well as communicating with the sponsor.

Because of his experience with web development and algorithms he would develop the scheduling algorithm used for Orai as well as develop the front end. Valentina Diaz, also having experience with the algorithms we would need, oversaw the chart development and helped with documentation. Because of his experience in the field, Jacob Christensen oversaw the back end and the development of the foundation for the project, including database and system management.

Further Resources

• Fall 2021 Showcase
• GitHub - neo4j-examples/paradise-papers-django: A simple Django web app for searching the Paradise Papers dataset backed by Neo4j
• Future Sponsors

Orai: Project Planning with Neo4j was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Resonate is a relatively young, (almost all) open source music streaming platform with a catalog featuring mostly but not exclusively ambient and electronic music, as categorized by Tags at the album level.

While many users enjoy exploring in random mode, listeners interested in learning more about the seemingly endless subgenres within Resonate would benefit from having a simple recommendation tool to find the most popular tracks for each tag.

In an attempt to provide a solution to this discovery issue, Resotrack (demo, code) uses Neo4j to suggest popular, relevant tracks for each tag in Resonate’s music catalog.

Resonate - the ethical music streaming co-op

Resotrack also happens to be built using Django-Neomodel and deployed on Aura Free and Heroku. This example will present a brief overview of the project and provide simple examples of apoc.periodic.commit and importing JSON Data from a REST API into Neo4j using apoc.load.json.

The Resotrack Data Model

While the creators of the tracks can add their tracks to a variety of types of TrackGroups (lp, eps, et cetera) and add Tags to these TrackGroups, non-artists can add tracks to TrackGroups of type playlist, and have limited (or no) tagging capabilities.

As Resotrack users search and interact with the data, the system calculates a “Top Track” for each tag and presents the “Top Track” for a particular tag to the user.

Using Resotrack

In the example below, the user has searched for techno and is presented with the top track for tags containing the string techno. In the image below, since ambienttechno has techno as a substring, we can see that Daibutsu is the TOP_TRACK for the Tag ambientechno.

In the Django admin, the superuser can view the project’s R(esonate) Users, Tags, Track groups, and Tracks.

Connecting the Django-Neomodel App to Aura Free

If you haven’t already, clone the repo to your local machine:

git clone git@github.com:whatSocks/reso-tag-charts.git

GitHub - whatSocks/reso-tag-charts: Example Movie app for Neo4j and Django

Create or log in to your Aura account

Neo4j Aura - Fully Managed Cloud Solution

Tap Create a database then select Aura Free.

Follow the prompts to create the database and take note of the username (neo4j) and password.

Log in to the neo4j browser and verify the database exists with the “Open” button.

In your terminal, navigate to the project’s root directory and create the database environment variable:

export NEO4J_BOLT_URL=neo4j+s://neo4j:password@host-or-ip:port

Run migrations and create your superuser (for the admin, this is using an SQLite database)

./manage.py migrate
./manage.py createsuperuser

Run the server:

python manage.py runserver

Now you should be able to access http://localhost:8000 and view the empty app.

Load the Data

An empty database is no fun. We can use apoc.load.json (Strava example) and apoc.periodic.commit to load the data from the Resonate API.

Importing JSON Data from a REST API into Neo4j - Developer Guides

You can easily create a Listener account on Resonate and create your own playlists before you start. While not required, accounts are free and are helpful in understanding the lay of the data.

Create Constraints

CREATE CONSTRAINT ON (a:Ruser) ASSERT a.uuid IS UNIQUE;
CREATE CONSTRAINT ON (a:TrackGroup) ASSERT a.uuid IS UNIQUE;
CREATE CONSTRAINT ON (a:Track) ASSERT a.uuid IS UNIQUE;

Add the first page of Playlists (a type of TrackGroup)

WITH 'https://api.resonate.coop/v2/' AS uri
CALL apoc.load.json(uri + ‘trackgroups?type=playlist’) // in this example, grabbing listener-generated playlists
YIELD value
UNWIND value[“data”] as data
MERGE (u:RUser {uuid:toString(data['user']['id'])})
MERGE (t:TrackGroup {uuid:toString(data['id'])})
MERGE (u)-[:OWNS]->(t)
SET t.title = data['title']
SET t.type = data['type']
SET t.slug = data['slug']
SET t.tracks_imported = false

Add more TrackGroups

WITH 'https://api.resonate.coop/v2/' AS uri
CALL apoc.load.json(uri + ‘trackgroups’) // in this example, grabbing listener-generated playlists
YIELD value
UNWIND value[“data”] as data
MERGE (u:RUser {uuid:toString(data['user']['id'])})
MERGE (t:TrackGroup {uuid:toString(data['id'])})
MERGE (u)-[:OWNS]->(t)
SET t.title = data['title']
SET t.type = data['type”]
SET t.slug = data['slug]
SET t.tracks_imported = false

Add Tracks

CALL apoc.periodic.commit(
"MATCH (tg:TrackGroup)
WHERE NOT tg.tracks_imported
SET tg.tracks_imported = true
WITH tg limit $limit
WITH 'https://api.resonate.coop/v2/' AS uri, tg.uuid as tg_id
CALL apoc.load.json(uri + 'trackgroups/' + tg_id )
YIELD value
UNWIND value['data']['items'] as items
MERGE (u:RUser {uuid:toString(items['track']['creator_id'])})
MERGE (track:Track {uuid:toString(items['track']['id'])})
MERGE (t)-[:HAS_TRACK]->(track)
MERGE (track)<-[:CREATED]-(u)
SET track.title = items['track']['title']
SET track.tags_imported = false
RETURN count(*)",

{limit:10});

Add Tags

CALL apoc.periodic.commit(
"
MATCH (u:RUser)-[:CREATED]->(track:Track)
WHERE not u.uuid in ['7212','4315',’4414'] // bad data
AND NOT track.tags_imported
SET track.tags_imported = true
WITH u as artist, u.uuid as user_id, count(DISTINCT track) as tracks,'https://api.resonate.coop/v2/' as uri
ORDER BY tracks desc
LIMIT $limit
CALL apoc.load.json(uri + 'artists/' + user_id + '/releases') // grabbing all
YIELD value
UNWIND value['data'] as data
UNWIND data['tags'] as tags
MERGE (t:TrackGroup {uuid:toString(data['id'])})
MERGE (user:RUser {uuid:toString(user_id)})-[:OWNS]->(t)
MERGE (tag:Tag {name:toLower(tags)})
MERGE (tag)<-[:HAS_TAG]-(t)
SET tag.uuid=apoc.create.uuid()
SET t.title = data['title']
SET t.type = data['type']
RETURN count(*)
",
{limit:10});

Now you should be able to explore the data locally, with your data safe and sound in Aura.

About the Authors

Cristina and Alisson work at The SilverLogic, a software development company based in Boca Raton.

Learn More

• apoc.periodic.commit - APOC Documentation
• Importing JSON Data from a REST API into Neo4j - Developer Guides
• Load JSON - APOC Documentation
• Resonate - the ethical music streaming co-op
• GitHub - whatSocks/reso-tag-charts: Example Movie app for Neo4j and Django
• Neo4j Aura - Neo4j Aura
• Getting Started with Neomodel

Resotrack: Exploring the Resonate API with Django-Neomodel on Aura was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

A Paradise Papers Example

If you’re a Django developer, you may have already found the popular py2neo toolkit and may have some experience using Neomodel and/or the Neo4j python driver directly. But how well do these tools play with Django?

Thankfully for Django developers, the Neo4j ecosystem provides a quick way to spin up an example app — the Paradise Papers Search App — based on the Paradise Papers dataset, conveniently available on Neo4j Sandbox.

This post will be a quick walkthrough of how to register a model on the Paradise Papers Search app. For more details, check out our previous post on the topic here:

Neo4j for Django Developers

Local Setup — Sandbox Database

First step, set up your local environment:

clone the repo:

git clone git@github.com:neo4j-examples/paradise-papers-django.git

In a virtual environment, install the requirements:

pip install -r requirements.txt

Next you’ll need to point your app to a sandbox instance of the database.

In Neo4j Sandbox, create an account and select Paradise Papers by ICIJ.

Back in the Sandbox UI, tap “Connection details” to find the database’s Bolt URL, username, and password.

In your local environment, set the DATABASE_URL variable using the credentials found in the Sandbox admin:

export DATABASE_URL=bolt://<Username>:<Password>@<IP Address>:7687

In paradise_papers_search/fetch_api/admin, add the models you would like to explore using the admin:

from django.contrib import admin as dj_admin
from django_neomodel import admin as neo_admin

from .models import Entity

class EntityAdmin(dj_admin.ModelAdmin):
    list_display = (“name”,)

neo_admin.register(Entity, EntityAdmin)

Add the admin URL to urls.py (if you haven’t done so already):

from django.conf.urls import url, include
from django.views.generic import TemplateView
from django.contrib import admin

urlpatterns = [
    url(r'^$', TemplateView.as_view(template_name='index.html'), name='index'),
    url(r'^fetch/', include('fetch_api.urls')),
    url(r"^admin/", admin.site.urls)
]

Because Django’s admin authentication still goes through Django models, you will you need to set up a (relational) user database in your settings file and run the migrations.

Example settings snippet:

DATABASES = {
    'default': {
        'NAME': 'papers.db',
        'ENGINE': 'django.db.backends.sqlite3',
        'USER': '',
        'PASSWORD': '',
        'PORT': '',
    },
}

Running the migrations:

./manage.py migrate

After that, create the admin superuser:

./manage.py createsuperuser

Run the app!

python manage.py runserver — settings=paradise_papers_search.settings.dev

Start searching at http://127.0.0.1:8000/

Log in to the admin at http://127.0.0.1:8000/admin

That’s it!

Next Steps

After testing out the ICIJ Panama Papers database, you may want to try using some of the data native to your Django application. Test out converting your relational dataset using the Neo4j ETL Tool:

Neo4j ETL Tool - Interactive Relational Database Data Import - Neo4j Labs

Resources

• neo4j-contrib/neomodel
• neo4j-contrib/django-neomodel
• neo4j/neo4j-python-driver

Looking for more details on how Neo4j was used in the Panama Papers investigation? Check out more coverage here:

• An In-Depth Graph Analysis of the Paradise Papers
• How the ICIJ Used Neo4j to Unravel the Panama Papers
• Analyzing the Panama Papers with Neo4j: Data Models, Queries & More
• The Panama Papers: Why It Couldn’t Have Happened Ten Years Ago

Register Your Neo4j-Based Models to the Django Admin was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

A Neomodel community member asked about how to run Django Neomodel (a Neomodel plugin for Django) within a Docker container. So let’s show how to do it.

Haven’t tried out Django-Neomodel yet? Start here.

Neo4j for Django Developers

Local Setup — Example

Prerequisites:

• An updated version of Docker
• Django Neomodel

The Django-Neomodel repository comes with a Docker example. If you’re just getting started with Docker, this may be a good place to start.

From the root of the Django-Neomodel repo, go to the tests directory:

cd tests/

Run the Docker Command (make sure your Docker service is running and up to date).

docker-compose up

Verify the Django admin is running: http://localhost:8000/admin/

Verify Neo4j Browser is running: http://localhost:7474/browser/

You’ll be then able to log in with the test credentials admin / 1234.

Under the Hood

Dockerfile

The Dockerfile collects the commands Docker will be using to create your environment.

FROM python:3
WORKDIR /usr/src/app
COPY ./tests/requirements.txt ./
RUN pip install — no-cache-dir -r requirements.txt
COPY .. .
RUN chmod +x ./tests/docker-entrypoint.sh
CMD [“./tests/docker-entrypoint.sh” ]

docker-compose.yml

docker-compose.yml is where you’ll configure the ports you’ll be using to communicate with your Neo4j database.

docker-compose.yml :

version: ‘3’
services:
    backend:
        build:
            context: ../
            dockerfile: ./tests/Dockerfile
        command: ‘/bin/bash -c “chmod +x /usr/src/app/tests/docker-entrypoint.sh && /usr/src/app/tests/docker-entrypoint.sh”’
        volumes:
          - ..:/usr/src/app
        ports:
          - “8000:8000”
        expose:
          - 8000
        depends_on:
          - neo4j_db
        links:
          - neo4j_db
        environment:
          - NEO4J_BOLT_URL=bolt://neo4j:foobar@neo4j_db:7687
          - DJANGO_SETTINGS_MODULE=settings

neo4j_db:
        image: neo4j:4.2-enterprise
        ports:
          - “7474:7474”
          - “7687:7687”
        expose:
          - 7474
          - 7687
        volumes:
          - db:/data/dbms
        environment:
          - NEO4J_AUTH=neo4j/foobar
          - NEO4J_ACCEPT_LICENSE_AGREEMENT=yes
          - dbms.connector.bolt.listen_address=:7687
          - dbms.connector.bolt.advertised_address=:7687

volumes:
    db:

docker-entrypoint.sh

docker-entrypoint.sh is where you’ll configure the python/Django portion of your app. You’ll add your DJANGO_SUPERUSER_USERAME and other Django-related environment variables here.

docker-entrypoint.sh :

#!/bin/bash -xe
cd tests
python -c <<EOF |
from django.db import IntegrityError
try:
    python manage.py install_labels
except IntegrityError:
    print(“Already installed”)
EOF

python manage.py migrate # Apply database migrations
if [ “$DJANGO_SUPERUSER_USERNAME” ]
then
    python manage.py createsuperuser \
        — noinput \
        — username $DJANGO_SUPERUSER_USERNAME \
        — email $DJANGO_SUPERUSER_EMAIL
fi

$@
python manage.py runserver 0.0.0.0:8000

Resources

• Docker: Accelerated Container Application Development
• Django
• neo4j-contrib/neomodel
• neo4j-contrib/django-neomodel
• GitHub - neo4j-examples/paradise-papers-django: A simple Django web app for searching the Paradise Papers dataset backed by Neo4j
• Docker-compose: db connection from web container to neo4j container using bolt
• Neo4j for Django Developers

About the Authors

Cristina and Alisson work at The SilverLogic, a software development company based in Boca Raton.

Alisson is a software engineer at The SilverLogic. Passionate about plants, he is the driving force behind Que Planta, a GraphQL-based social network for plants.

Running Django-Neomodel Within a Docker Container was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.

Making the leap from a relational database to a graph database for an existing project is not easy. Questions arise:

What happens to the existing data? If the data is migrated, will the whole system have to be rewritten? What if we like our existing stack but still want the benefits of a graph database? Should we try a microservice? Will there be overhead? Will the overhead be worth it?

Thankfully for Django developers, the Neo4j ecosystem provides a quick and painless way to spin up a test implementation

The Paradise Papers Search App, based on the Paradise Papers dataset, is conveniently available on Neo4j Sandbox. By following along with the steps of this post, you will be able to spin up a small Django application to explore the Paradise Papers dataset either locally or on Heroku.

GitHub - neo4j-examples/paradise-papers-django: A simple Django web app for searching the Paradise Papers dataset backed by Neo4j

About the Paradise Papers Search App

Background

The ICIJ published a fraction of the Paradise Papers data as part of their Power Players visualization at the same time as the reported stories. Some time later, Neo4j added a version of the Paradise Papers dataset, with 163,414 nodes and 364,456 relationships, to the sandboxes available on Neo4j Sandbox.

Paradise Papers Archives - ICIJ

Data Model

The model includes:

• A company, trust or fund created in a low-tax, offshore jurisdiction by an agent ( Entity )
• People or companies who play a role in an offshore entity (Officer)
• Addresses (Address)
• Law firms or middlemen (Intermediary) that asks an offshore service provider to create an offshore firm for a client

Each of these carries different properties, including name, address, country, status, start and end date, validity information, and more.

Relationships between the elements capture the roles people or other companies play in the offshore entities (often shell companies), we see many OFFICER_OF relationships for directors, shareholders, beneficiaries, etc.

Other relationships capture similar addresses or the responsibility of creating a shell company by a law firm (INTERMEDIARY_OF).

For a detailed description of the data model, check out An In-Depth Graph Analysis of the Paradise Papers.

Paradise Papers: an in-depth graph analysis

Django-Neomodel

The Paradise Papers app uses Django-Neomodel, a Django module allows you to use the Neo4j database with Django using neomodel.

Who uses Django, and why? Many python developers (or their employers) prefer to use an ORM such as Django as it allows them to focus on the business logic, the “money query,” or other more complex features of their product while the object mapper handles the relationship between the database, the Python models, and other aspects of web development.
Django’s introspection-generated admin portal is another benefit, avoiding the boilerplate code for administrator pages.

What about neomodel? Similar to Django, neomodel, an object mapper, allows Python developers to focus on solving problems for their users by thinking in terms of domain objects and less in terms of writing Cypher statements.

Neomodel documentation - neomodel 3.3.2 documentation

Neomodel uses the concepts of StructuredNode and StructuredRel to formalize the relationship between domain objects, Python classes and Neo4j nodes and relationships. (Read more about extending StructuredNodes)

But would anyone use neomodel with an existing ORM? If an ORM-based product would like to leverage Neo4j as well, the Django-neomodel plugin would allow them to add Neo4j-based functionality to their existing application.

The Example App: Paradise Papers Search

The Paradise Papers search app allows users to search and filter for Entities, Officers, Intermediaries, and Addresses, providing results in a list. It is not intended to be a fully-fledged app (although it can be considered such), but is rather an example of how a Python developer could integrate Neo4j into a Django application.

Upon clicking a list item, the user can see some details about the item, in addition to Entities, Officers, Intermediaries, or Addresses that might be connected to the item.

The “StructuredNodes”

Entity

In the entity.py file, you will find a class Entity corresponding to Entity nodes in the Neo4j database.

A bit below the Entity definition, take a look at the example serializers. In this example, serializing the Officers, Intermediaries, Addresses, Entities, and Others that have relationships with a particular Entity:

Address

Similarly, you can find the Address StructuredNode in address.py

Intermediaries, Officers, and “Other”

Intermediaries, Officers, and “Other” StructuredNodes can be found in the models directory of the repo.

Read more in the paradise-papers-django tutorial

Local App: Sandbox Database

First step, set up your local environment.

Clone the repo:

GitHub - neo4j-examples/paradise-papers-django: A simple Django web app for searching the Paradise Papers dataset backed by Neo4j

git clone git@github.com:neo4j-examples/paradise-papers-django.git

In a virtual environment, install the requirements:

pip install -r requirements.txt

Next, you’ll need to point your app to a sandbox instance of the Neo4j database. In Neo4j Sandbox, create an account and select Paradise Papers by ICIJ.

Check out the graph in the browser by clicking the “Open” button. You will find a informative Graph Guide detailing the dataset:

Back in the Sandbox UI, tap Connection details to find the database’s bolt URL, Username, and Password.

Since the Paradise Papers Search App uses Django Neomodel, which is built on the official Python driver, it is a good idea to double-check the suggested implementation under Connect via drivers > Python.

In your local environment, set the DATABASE_URL environment variable using the credentials found in the Sandbox admin:

export DATABASE_URL=bolt://<username>:<password>@<ip>:7687

Run the app!

python manage.py runserver \
— settings=paradise_papers_search.settings.dev

Start searching at http://127.0.0.1:8000/

Local Setup, Local Data

Sandbox comes with an expiration date, so if you want to do some additional experimentation, you will have to get the data and import it to your local database. We have made the sandbox datasets, browser guides and code examples available as GitHub repositories, that you can import into your Neo4j installation.

neo4j-graph-examples/icij-paradise-papers

Fortunately, Neo4j Desktop now supports that out of the box. If you have not yet done so, please download and install Neo4j Desktop.

Import the repository into desktop, via the New -> Import sample project. And pick the icij-paradise-papers from the list. That should prompt you for the database import and create a database and project for you.

Back in your app, update the database environment variables to reflect this new database.

export DATABASE_URL=bolt://neo4j:<password>@localhost:7687

Deploy to Heroku

An app deployed locally is okay, but what about deployment?

Create a new Heroku app, (for example, paradise-papers)

Go to the app’s settings and add the following config vars:

ALLOWED_HOST : paradise-papers.herokuapp.com
(change to your app name)

DATABASE_URL: the credentials from your sandbox database

Over in your local terminal inside the repository, add the Heroku app as a remote, then push to Heroku:

git remote add heroku https://git.heroku.com/paradise-papers.git

git push heroku master

View your app at the URL you specified in the configuration.

Use a Neo4j Aura Database

Now that you’ve seen the app in action locally and on a remote server, if you want someone else to be able to visit the app without your computer running, you may want to use a database on Neo4j Aura.

After creating an Aura account, you can import by following the wizard on the Aura console. You can drag and drop your dump-file onto the browser to seed your database.

Next Steps

After testing out the ICIJ Panama Papers database, you may want to test out using some of the data native to your Django application. Test out converting your relational data set using the Neo4j ETL Tool.

Looking for more details on how Neo4j was used in the Panama Papers investigation? Check out our full coverage here:

• An In-Depth Graph Analysis of the Paradise Papers
• How the ICIJ Used Neo4j to Unravel the Panama Papers
• Analyzing the Panama Papers with Neo4j: Data Models, Queries & More
• The Panama Papers: Why It Couldn’t Have Happened Ten Years Ago

Resources

• neo4j-contrib/neomodel
• neo4j-contrib/django-neomodel
• neo4j/neo4j-python-driver
• Getting Started with Neomodel

About the Authors

Cristina and Alisson work at The SilverLogic, a software development company based in Boca Raton.

Alisson is a software engineer at The SilverLogic. Passionate about plants, he is the driving force behind Que Planta, a GraphQL-based social network for plants.

Neo4j for Django Developers was originally published in Neo4j Developer Blog on Medium, where people are continuing the conversation by highlighting and responding to this story.