Overview

Flavius supports Bolt protocol . User can use Neo4j Python/Java SDK to access flavius database with minor changes.

Supported Version

Flavius currently only supports Bolt v5.6 and above.

Namespace and Graph

Flavius differs from Neo4j’s database concept, replacing it with namespace and graph. Before query operations, you need to specify the target namespace and graph. If the required namespace and graph don’t exist in the system, users need to create them first before use.

Setting timezone and timeout

User can set timezone and timeout when connecting database via the URI. For example, setting timezone UTC and query timeout 300 second with the following URI.


neo4j://localhost:7687?timezone=UTC&timeout=300

Supported Timezone representations:

IANA Timezone Database format (e.g., “Asia/Shanghai”)
UTC offset format (e.g., “+08:00”)
‘UTC’

Setting working namespace and graph in session variables

For python driver, user can use session.run to run queries. When you need to specify which namespace and graph the statements in the run method should execute in, you can specify this through metadata={}.

For example


session.run("CREATE NAMESPACE ns")
# setting working namespace
session.run("CREATE GRAPH g", metadata={"namespace": "ns"})
session.run(
    "CREATE VERTEX album (name VARCHAR NOT NULL, genre VARCHAR, release DATE) PRIMARY KEY name",
    # setting working namespace and working graph
    metadata={"namespace": "ns", "graph": "g"}
)

Python SDK

Setup Neo4j Python Driver pip install neo4j or uv install neo4j

By default, the latest version of the driver is installed, which was v5.28 as of August 7, 2025. Flavius currently only supports Bolt protocol v5.6 and above. Driver versions v5.21 and above all satisfy the requirement of Bolt version > 5.6.

Example usage


from neo4j import GraphDatabase
import time
import json
 
def main():
    # please replace the URI
    URI = "neo4j://localhost:7687"
    AUTH = ("username", "password")
 
    with GraphDatabase.driver(URI, auth=AUTH) as driver:
        with driver.session() as session:
            session.run("CREATE NAMESPACE ns")
            session.run("CREATE GRAPH music", metadata={"namespace": "ns"})
            session.run(
                "CREATE VERTEX album (name VARCHAR NOT NULL, genre VARCHAR) PRIMARY KEY name",
                metadata={"graph": "music", "namespace": "ns"}
            )
            session.run(
                "CREATE VERTEX people (name VARCHAR NOT NULL, job VARCHAR) PRIMARY KEY name",
                metadata={"graph": "music", "namespace": "ns"}
            )
            session.run(
                "CREATE DIRECTED EDGE produce (FROM people to album, role VARCHAR)",
                metadata={"graph": "music", "namespace": "ns"}
            )
            session.run(
                '''INSERT INTO album VALUES
                ("Close to the Edge", "Art Rock"),
                ("Igor", "Hip Hop"),
                ("To Pimp a Butterfly", "Hip Hop"),
                ("OK Computer", "Alternative Rock"),
                ("In Rainbow", "Art Rock"),
                ("Wise You Were Here", "Progressvie Rock"),
                ("good kid, m.A.A.d city", "Consicious Hip Hop"),
                ("In the Court of the Crimson King", "Progressive Rock"),
                ("Madvillainy", "Abstract Hip Hop"),
                ("Revolver", "Pop Rock"),
                ("The Black Saint and the Sinner Lady", "Avant-Garde Jazz"),
                ("Paranoid", "Heavy Metal"),
                ("Vespertine", "Art Pop"),
                ("A Love Supreme", "Spiritual Jazz")
                ''',
                metadata={"graph": "music", "namespace": "ns"}
            )
            session.run(
                '''INSERT INTO people VALUES
                ("Bill Bruford", "musician"),
                ("Robert Fripp", "musician"),
                ("Kendrick Lamar", "rapper"),
                ("Thom Yorke", "musician"),
                ("Roger Waters", "composer"),
                ("Ringo Starr", "musician"),
                ("John Lennon", "socialist"),
                ("David Bowie", "singer"),
                ("Charlie Mingus", "band leader"),
                ("bjork", "songwriter"),
                ("Jhon Coltrane", "saint"),
                ("Miles Davis", "jazz pioneer"),
                ("Kanye West", "social influener")
                ''',
                metadata={"graph": "music", "namespace": "ns"}
            )
            session.run(
                '''INSERT INTO produce VALUES
                ("Robert Fripp", "In the Court of the Crimson King", "guitar, composer"),
                ("Bill Bruford", "Close to the Edge", "drums, percussion"),
                ("Kendrick Lamar", "good kid, m.A.A.d city", "rap, art direction"),
                ("Thom Yorke", "OK Computer", "vocals, guitar, pinano, programming, songwriter"),
                ("Thom Yorke", "In Rainbow", "vocals"),
                ("Roger Waters", "Wise You Were Here", "bass guitar, vocals, writer, lyrics"),
                ("Ringo Starr", "Revolver", "drums, cowbell"),
                ("John Lennon", "Revolver", "lead vocals, bass guitar, songwriter"),
                ("bjork", "Vespertine", "writer, producer, vocals"),
                ("Jhon Coltrane", "A Love Supreme", "tenor saxophone, liner notes, composer")
                ''',
                metadata={"graph": "music", "namespace": "ns"}
            )
            results = session.run(
                '''MATCH (p:people{job:"musician"})-[r:produce]->(a:album) RETURN p.name, r.role, a.name''',
                metadata={"graph": "music", "namespace": "ns"}
            )
            for record in results:
                print(f"{record['p.name']} played a role as {record['r.role']} in album: {record['a.name']}")
 
 
if __name__ == "__main__":
    main()

Or loading data from an object store. For the data loading result status, please refer to Import Job Status.


from neo4j import GraphDatabase
import time
import json
 
def main():
    URI = "neo4j://localhost:7687"
    AUTH = ("username", "password")
 
    with GraphDatabase.driver(URI, auth=AUTH) as driver:
        with driver.session() as session:
            session.run("CREATE NAMESPACE import")
            session.run("CREATE GRAPH test", metadata={"namespace": "import"})
            session.run("CREATE VERTEX Person (col1 BIGINT NOT NULL, col2 VARCHAR, col3 BIGINT) PRIMARY KEY col1", metadata={"graph": "test"})
            session.run("CREATE DIRECTED EDGE Knows (FROM Person TO Person, col1 VARCHAR)")
            results = session.run(
                '''
                BLOCKING IMPORT VERTEX Person COLUMNS("col1" = $0, "col2" = $1, "col3" = $2) FROM "s3://path/to/data" WITH (region = "xxx", access_key_id = "xxx", secret_access_key = "xxx") FORMAT AS CSV (has_header = true, delimiter = "|")
                '''
            )
            status = json.loads(results.single().value())
            # check data loading results
            if status['kind'] == 'Finished':
                print('Data loading finished successfully')
            elif status['kind'] == 'Failed' or status['kind'] == 'Cancelled':
                print('Data loading failed or cancelled')
            else:
                print('Running')
 
            session.run("DROP NAMESPACE import")
       
if __name__ == "__main__":
    main()

JAVA SDK

Adding Neo4j Java Driver Dependency

Using Maven as an example, add the Neo4j dependency to your pom.xml. The Java driver version requirements are the same as for Python.


<dependencies>
  <dependency>
      <groupId>org.neo4j.driver</groupId>
      <artifactId>neo4j-java-driver</artifactId>
      <version>5.28.8</version>
  </dependency>
</dependencies>

Example usage


package com.example;
import java.util.Map;
import org.neo4j.driver.AuthTokens;
import org.neo4j.driver.Config;
import org.neo4j.driver.GraphDatabase;
import org.neo4j.driver.Values;
 
public class App {
 
    public static void main(String[] args) {
        final String dbUri =
            "neo4j://localhost:7687?timezone=UTC&timeout=10&max_parallelism=4&chunk_size=1000";
        final String dbUser = "username";
        final String dbPassword = "password";
 
        try (
            var driver = GraphDatabase.driver(
                dbUri,
                AuthTokens.basic(dbUser, dbPassword),
                Config.builder().withMaxConnectionPoolSize(1).build()
            )
        ) {
            var session = driver.session();
            try {
                session.run("CREATE NAMESPACE rym");
                session.run(
                    "CREATE GRAPH music",
                    // set the namespace we work on
                    Values.parameters("metadata", Map.of("namespace", "rym"))
                );
                session.run(
                    "CREATE VERTEX album (name VARCHAR NOT NULL, genre VARCHAR) PRIMARY KEY name",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                session.run(
                    "CREATE VERTEX people (name VARCHAR NOT NULL, job VARCHAR) PRIMARY KEY name",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                session.run(
                    "CREATE DIRECTED EDGE produce (FROM people to album, role VARCHAR)",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                session.run(
                    "INSERT INTO album VALUES " +
                    "(\"Close to the Edge\", \"Art Rock\")," +
                    "(\"Igor\", \"Hip Hop\")," +
                    "(\"To Pimp a Butterfly\", \"Hip Hop\")," +
                    "(\"OK Computer\", \"Alternative Rock\")," +
                    "(\"In Rainbow\", \"Art Rock\")," +
                    "(\"Wise You Were Here\", \"Progressvie Rock\")," +
                    "(\"good kid, m.A.A.d city\", \"Consicious Hip Hop\")," +
                    "(\"In the Court of the Crimson King\", \"Progressive Rock\")," +
                    "(\"Madvillainy\", \"Abstract Hip Hop\")," +
                    "(\"Revolver\", \"Pop Rock\")," +
                    "(\"The Black Saint and the Sinner Lady\", \"Avant-Garde Jazz\")," +
                    "(\"Paranoid\", \"Heavy Metal\")," +
                    "(\"Vespertine\", \"Art Pop\")," +
                    "(\"A Love Supreme\", \"Spiritual Jazz\")",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                session.run(
                    "INSERT INTO people VALUES " +
                    "(\"Bill Bruford\", \"musician\")," +
                    "(\"Robert Fripp\", \"musician\")," +
                    "(\"Kendrick Lamar\", \"rapper\")," +
                    "(\"Thom Yorke\", \"musician\")," +
                    "(\"Roger Waters\", \"composer\")," +
                    "(\"Ringo Starr\", \"musician\")," +
                    "(\"John Lennon\", \"socialist\")," +
                    "(\"David Bowie\", \"singer\")," +
                    "(\"Charlie Mingus\", \"band leader\")," +
                    "(\"bjork\", \"songwriter\")," +
                    "(\"Jhon Coltrane\", \"saint\")," +
                    "(\"Miles Davis\", \"jazz pioneer\")," +
                    "(\"Kanye West\", \"social influener\")",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                session.run(
                    "INSERT INTO produce VALUES " +
                    "(\"Robert Fripp\", \"In the Court of the Crimson King\", \"guitar,composer\")," +
                    "(\"Bill Bruford\", \"Close to the Edge\", \"drums, percussion\")," +
                    "(\"Kendrick Lamar\", \"good kid, m.A.A.d city\", \"rap, art direction\")," +
                    "(\"Thom Yorke\", \"OK Computer\", \"vocals, guitar, pinano, programming, songwriter\")," +
                    "(\"Thom Yorke\", \"In Rainbow\", \"vocals\")," +
                    "(\"Roger Waters\", \"Wise You Were Here\", \"bass guitar, vocals, writer, lyrics\")," +
                    "(\"Ringo Starr\", \"Revolver\", \"drums, cowbell\")," +
                    "(\"John Lennon\", \"Revolver\", \"lead vocals, bass guitar, songwriter\")," +
                    "(\"bjork\", \"Vespertine\", \"writer, producer, vocals\")," +
                    "(\"Jhon Coltrane\", \"A Love Supreme\", \"tenor saxophone, liner notes, composer\")",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                var results = session.run(
                    "MATCH (p:people{job:\"musician\"})-[r:produce]->(a:album) RETURN p.name, r.role, a.name",
                    // set the graph we work on
                    Values.parameters("metadata", Map.of("namespace", "rym", "graph", "music"))
                );
                while (results.hasNext()) {
                    var record = results.next();
                    System.out.println(
                        record.get("p.name") +
                        " played a role as " +
                        record.get("r.role") +
                        " in album: " +
                        record.get("a.name")
                    );
                }
            } finally {
                session.close();
            }
        }
    }
}