Skip to content

Creating a Neo4j data service#

Neo4j is a graph database. It stores data as nodes and relationships, and you query it with openCypher. This tutorial shows you how to create an Ametnes-managed Neo4j service and connect to it from Neo4j Browser, cypher-shell and the Python driver.

Graphs suit connected data: knowledge graphs, recommendations, identity and access, fraud detection and similar workloads.

Ametnes offers the community edition in two release series:

  • service/neo4j:5.26-ce - current release (Neo4j 5.26.0 community) and the recommended choice for new deployments.
  • service/neo4j:4.4-ce - previous LTS release (Neo4j 4.4.48 community) with the APOC and neosemantics (n10s) plugins included.

Both series run a single Neo4j server. Neo4j clustering and read replicas are Enterprise features and are not offered by the Ametnes catalog. The retired service/neo4j:4.2 kind is disabled and cannot be provisioned.

Prerequisites#

  1. A service location (see Service Location).

Networking is automatic by default

Creating a network access resource is optional. If you do not create one, Ametnes manages network access for the location and the service attaches automatically. Create your own only if you want to control exposure (see Network Access Resources).

Connections#

Neo4j publishes two connections:

Connection Default port Purpose
bolt+s 7687 Bolt driver protocol for cypher-shell and drivers
https 443 Neo4j Browser and the HTTP API

The host is the service's DNS name on your zone. Use the host and port values returned in the service's connections array. Connect with the neo4j+s:// or bolt+s:// scheme rather than plain bolt://.

The admin user is neo4j. If you do not set an admin password at create time, Ametnes generates one and stores it in the service's Kubernetes Secret.

Create the Neo4j service#

  1. Navigate to the Services left menu and click New Service.
  2. Enter Name (for example Neo4jService).
  3. Select Kind: Neo4j 5.26 Community Service (service/neo4j:5.26-ce).
  4. Select the Location: your data service location. Leave Network unset to let Ametnes manage it.
  5. Select the Setup Architecture: Starter for evaluation, Small and above for production.
  6. Enter the Admin Password, or leave it empty to have one generated.
  7. Leave Public unset for a private endpoint, or enable it to make the endpoint reachable from the internet.
  8. Click Create Service and wait for the status ready.
service.tf
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
resource "ametnes_service" "neo4j" {
  name     = "Neo4jService"
  project  = data.ametnes_project.project.id
  location = data.ametnes_location.location.id
  kind     = "neo4j:5.26-ce"
  capacity {
    storage = 10
  }
  config = {
    "architecture"   = "Starter"
    "admin.password" = "<admin-password>"
  }
}

output "connections" {
  value = ametnes_service.neo4j.connections
}

The provider adds the service/ prefix. The architecture controls CPU and memory; capacity.storage sets the data volume size.

Record the admin password at create time

The password is stored as a per-resource Secret. If you let Ametnes generate it, capture it when the service is created; the console does not display it later.

Connect#

Open Neo4j Browser at https://<host>/browser/ in a browser, then connect to neo4j+s://<host>:7687 with the user neo4j and your admin password.

Check connectivity from the command line with cypher-shell:

cypher-shell \
  -a "neo4j+s://<host>:7687" \
  -u neo4j \
  -p '<admin-password>' \
  "RETURN 1 AS ok;"

The HTTP API accepts transactional Cypher over HTTPS with basic authentication:

curl --request POST \
  --url "https://<host>/db/neo4j/tx/commit" \
  --user "neo4j:<admin-password>" \
  --header "Content-Type: application/json" \
  --data '{"statements":[{"statement":"RETURN 1 AS ok"}]}'

From Python, install the official driver and verify the connection:

pip install neo4j

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "neo4j+s://<host>:7687",
    auth=("neo4j", "<admin-password>"),
)

driver.verify_connectivity()
print("connected")
driver.close()

Create data and query it#

The following example creates a small graph, reads it back and adds a uniqueness constraint. Use parameters rather than string interpolation so values are sent safely to the server.

from neo4j import GraphDatabase

driver = GraphDatabase.driver(
    "neo4j+s://<host>:7687",
    auth=("neo4j", "<admin-password>"),
)

with driver.session(database="neo4j") as session:
    session.run(
        """
        MERGE (ada:Person {name: $name})
        MERGE (grace:Person {name: $friend})
        MERGE (ada)-[:KNOWS]->(grace)
        """,
        name="Ada",
        friend="Grace",
    )

    result = session.run(
        """
        MATCH (p:Person)-[:KNOWS]->(f:Person)
        RETURN p.name AS person, f.name AS friend
        """
    )
    for record in result:
        print(record["person"], "knows", record["friend"])

    session.run(
        """
        CREATE CONSTRAINT person_name_unique IF NOT EXISTS
        FOR (p:Person) REQUIRE p.name IS UNIQUE
        """
    )

driver.close()

The constraint uses Neo4j 5 syntax. On a 4.4 service, use the 4.x ASSERT form instead.

The equivalent openCypher statements in Neo4j Browser are:

CREATE (ada:Person {name: 'Ada'})-[:KNOWS]->(grace:Person {name: 'Grace'});

MATCH (p:Person)-[:KNOWS]->(f:Person)
RETURN p.name AS person, f.name AS friend;

The default database is neo4j. Open sessions against it explicitly with database="neo4j" (or the equivalent in Neo4j Browser) so the choice is clear.

Architectures#

Every tier is a single node with one data volume. Requests are half of the limits.

Architecture Nodes CPU / memory Storage ACU
Starter 1 1 CPU / 2Gi 10Gi 2
Small 1 3 CPU / 6Gi 60Gi 6
Basic 1 6 CPU / 12Gi 120Gi 12
Medium 1 12 CPU / 24Gi 240Gi 24
Large 1 24 CPU / 48Gi 480Gi 48
XLarge 1 36 CPU / 72Gi 720Gi 72
2XLarge 1 48 CPU / 96Gi 1200Gi 96
3XLarge 1 80 CPU / 320Gi 3000Gi 320
4XLarge 1 160 CPU / 640Gi 4000Gi 640

Community edition is single-node

Neo4j community edition does not support clustering or read replicas. A larger tier adds CPU and memory to the same single server; it does not add nodes or high availability. Plan for maintenance windows and keep exports of important graphs.

Scale#

Use Modify Resource in the console to move to a larger architecture. The topology stays a single node, so a tier change resizes CPU and memory. The data volume keeps its current size unless you change the service's storage value, and Ametnes never shrinks a deployed volume.

The 4.4 and 5.26 releases are separate kinds with no in-place major-version upgrade path. To move between them, provision the target kind and migrate the data with neo4j-admin dump/export and load, or with apoc.export/apoc.load when the plugins are available.

Automated backups are not enabled for Neo4j services in this catalog. Export the database with the neo4j-admin command for your Neo4j version and copy the dump to storage you control.

Validation checklist#

  • Neo4j resource status is ready in Ametnes Platform.
  • cypher-shell connects with neo4j+s:// and returns 1 from RETURN 1.
  • Neo4j Browser opens at https://<host>/browser/ and accepts the login.
  • The Python driver passes verify_connectivity().
  • You can create nodes and relationships and read them back with openCypher.

Next#