This section describes how to build and query a graph of the social network data in KùzuDB. It uses Kùzu's client API to perform the ingestion and querying.
Note
All timing numbers shown below are on an M3 Macbook Pro with 32 GB of RAM.
Because Kùzu is an embedded graph database, the database is tightly coupled with the application layer -- there is no server to set up and run. Simply pip install kuzu and you're good to go!
The script build_graph.py contains the necessary methods to connect to the KùzuDB DB and ingest the data from the CSV files, in batches for large amounts of data.
python build_graph.py --batch_size 50000The numbers shown below are for when we ingest 100K person nodes, ~10K location nodes and ~2.4M edges into the graph.
As expected, the nodes load much faster than the edges, since there are many more edges than nodes. The run times for ingesting nodes and edges are output to the console.
$ python build_graph.py
Nodes loaded in 0.1542s
Edges loaded in 0.3803s
Successfully loaded nodes and edges into KùzuDB!The script query.py contains a suite of queries that can be run to benchmark various aspects of the DB's performance.
python query.pyAs per the Neo4j docs, "transactions are single-threaded, confined, and independent". To keep a fair comparison with Neo4j, we thus limit the number of threads that Kùzu executes queries on to a single thread.
In the Python client, this is done as follows.
CONNECTION.set_max_threads_for_exec(1)Query 1:
MATCH (follower:Person)-[:Follows]->(person:Person)
RETURN person.id AS personID, person.name AS name, count(follower.id) AS numFollowers
ORDER BY numFollowers DESC LIMIT 3;
Top 3 most-followed persons:
shape: (3, 3)
┌──────────┬───────────────────┬──────────────┐
│ personID ┆ name ┆ numFollowers │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ i64 │
╞══════════╪═══════════════════╪══════════════╡
│ 85723 ┆ Melissa Murphy ┆ 4998 │
│ 68753 ┆ Jocelyn Patterson ┆ 4985 │
│ 54696 ┆ Michael Herring ┆ 4976 │
└──────────┴───────────────────┴──────────────┘
Query 2:
MATCH (follower:Person)-[:Follows]->(person:Person)
WITH person, count(follower.id) as numFollowers
ORDER BY numFollowers DESC LIMIT 1
MATCH (person) -[:LivesIn]-> (city:City)
RETURN person.name AS name, numFollowers, city.city AS city, city.state AS state, city.country AS country;
City in which most-followed person lives:
shape: (1, 5)
┌────────────────┬──────────────┬────────┬───────┬───────────────┐
│ name ┆ numFollowers ┆ city ┆ state ┆ country │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ str ┆ str ┆ str │
╞════════════════╪══════════════╪════════╪═══════╪═══════════════╡
│ Melissa Murphy ┆ 4998 ┆ Austin ┆ Texas ┆ United States │
└────────────────┴──────────────┴────────┴───────┴───────────────┘
Query 3:
MATCH (p:Person) -[:LivesIn]-> (c:City) -[*1..2]-> (co:Country)
WHERE co.country = $country
RETURN c.city AS city, avg(p.age) AS averageAge
ORDER BY averageAge LIMIT 5;
Cities with lowest average age in United States:
shape: (5, 2)
┌─────────────┬────────────┐
│ city ┆ averageAge │
│ --- ┆ --- │
│ str ┆ f64 │
╞═════════════╪════════════╡
│ Austin ┆ 37.655491 │
│ Kansas City ┆ 37.742365 │
│ Miami ┆ 37.7763 │
│ San Antonio ┆ 37.810841 │
│ Houston ┆ 37.817708 │
└─────────────┴────────────┘
Query 4:
MATCH (p:Person)-[:LivesIn]->(ci:City)-[*1..2]->(country:Country)
WHERE p.age >= $age_lower AND p.age <= $age_upper
RETURN country.country AS countries, count(country) AS personCounts
ORDER BY personCounts DESC LIMIT 3;
Persons between ages 30-40 in each country:
shape: (3, 2)
┌────────────────┬──────────────┐
│ countries ┆ personCounts │
│ --- ┆ --- │
│ str ┆ i64 │
╞════════════════╪══════════════╡
│ United States ┆ 30733 │
│ Canada ┆ 3046 │
│ United Kingdom ┆ 1816 │
└────────────────┴──────────────┘
Query 5:
MATCH (p:Person)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
AND lower(p.gender) = lower($gender)
WITH p, i
MATCH (p)-[:LivesIn]->(c:City)
WHERE c.city = $city AND c.country = $country
RETURN count(p) AS numPersons
Number of male users in London, United Kingdom who have an interest in fine dining:
shape: (1, 1)
┌────────────┐
│ numPersons │
│ --- │
│ i64 │
╞════════════╡
│ 52 │
└────────────┘
Query 6:
MATCH (p:Person)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
AND lower(p.gender) = lower($gender)
WITH p, i
MATCH (p)-[:LivesIn]->(c:City)
RETURN count(p.id) AS numPersons, c.city AS city, c.country AS country
ORDER BY numPersons DESC LIMIT 5
City with the most female users who have an interest in tennis:
shape: (5, 3)
┌────────────┬────────────┬────────────────┐
│ numPersons ┆ city ┆ country │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞════════════╪════════════╪════════════════╡
│ 66 ┆ Birmingham ┆ United Kingdom │
│ 66 ┆ Houston ┆ United States │
│ 65 ┆ Raleigh ┆ United States │
│ 64 ┆ Montreal ┆ Canada │
│ 62 ┆ Phoenix ┆ United States │
└────────────┴────────────┴────────────────┘
Query 7:
MATCH (p:Person)-[:LivesIn]->(:City)-[:CityIn]->(s:State)
WHERE p.age >= $age_lower AND p.age <= $age_upper AND s.country = $country
WITH p, s
MATCH (p)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
RETURN count(p.id) AS numPersons, s.state AS state, s.country AS country
ORDER BY numPersons DESC LIMIT 1
State in United States with the most users between ages 23-30 who have an interest in photography:
shape: (1, 3)
┌────────────┬────────────┬───────────────┐
│ numPersons ┆ state ┆ country │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞════════════╪════════════╪═══════════════╡
│ 168 ┆ California ┆ United States │
└────────────┴────────────┴───────────────┘
Query 8:
MATCH (a:Person)-[r1:Follows]->(b:Person)-[r2:Follows]->(c:Person)
RETURN count(*) AS numPaths
Number of second-degree paths:
shape: (1, 1)
┌──────────┐
│ numPaths │
│ --- │
│ i64 │
╞══════════╡
│ 58431994 │
└──────────┘
Query 9:
MATCH (a:Person)-[r1:Follows]->(b:Person)-[r2:Follows]->(c:Person)
WHERE b.age < $age_1 AND c.age > $age_2
RETURN count(*) as numPaths
Number of paths through persons below 50 to persons above 25:
shape: (1, 1)
┌──────────┐
│ numPaths │
│ --- │
│ i64 │
╞══════════╡
│ 46220422 │
└──────────┘
Queries completed in 1.1074s
We can also let Kùzu choose the optimal number of threads to run the queries on, in a multi-threaded fashion (this is the default behaviour).
Query 1:
MATCH (follower:Person)-[:Follows]->(person:Person)
RETURN person.id AS personID, person.name AS name, count(follower.id) AS numFollowers
ORDER BY numFollowers DESC LIMIT 3;
Top 3 most-followed persons:
shape: (3, 3)
┌──────────┬───────────────────┬──────────────┐
│ personID ┆ name ┆ numFollowers │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ i64 │
╞══════════╪═══════════════════╪══════════════╡
│ 85723 ┆ Melissa Murphy ┆ 4998 │
│ 68753 ┆ Jocelyn Patterson ┆ 4985 │
│ 54696 ┆ Michael Herring ┆ 4976 │
└──────────┴───────────────────┴──────────────┘
Query 2:
MATCH (follower:Person)-[:Follows]->(person:Person)
WITH person, count(follower.id) as numFollowers
ORDER BY numFollowers DESC LIMIT 1
MATCH (person) -[:LivesIn]-> (city:City)
RETURN person.name AS name, numFollowers, city.city AS city, city.state AS state, city.country AS country;
City in which most-followed person lives:
shape: (1, 5)
┌────────────────┬──────────────┬────────┬───────┬───────────────┐
│ name ┆ numFollowers ┆ city ┆ state ┆ country │
│ --- ┆ --- ┆ --- ┆ --- ┆ --- │
│ str ┆ i64 ┆ str ┆ str ┆ str │
╞════════════════╪══════════════╪════════╪═══════╪═══════════════╡
│ Melissa Murphy ┆ 4998 ┆ Austin ┆ Texas ┆ United States │
└────────────────┴──────────────┴────────┴───────┴───────────────┘
Query 3:
MATCH (p:Person) -[:LivesIn]-> (c:City) -[*1..2]-> (co:Country)
WHERE co.country = $country
RETURN c.city AS city, avg(p.age) AS averageAge
ORDER BY averageAge LIMIT 5;
Cities with lowest average age in United States:
shape: (5, 2)
┌─────────────┬────────────┐
│ city ┆ averageAge │
│ --- ┆ --- │
│ str ┆ f64 │
╞═════════════╪════════════╡
│ Austin ┆ 37.655491 │
│ Kansas City ┆ 37.742365 │
│ Miami ┆ 37.7763 │
│ San Antonio ┆ 37.810841 │
│ Houston ┆ 37.817708 │
└─────────────┴────────────┘
Query 4:
MATCH (p:Person)-[:LivesIn]->(ci:City)-[*1..2]->(country:Country)
WHERE p.age >= $age_lower AND p.age <= $age_upper
RETURN country.country AS countries, count(country) AS personCounts
ORDER BY personCounts DESC LIMIT 3;
Persons between ages 30-40 in each country:
shape: (3, 2)
┌────────────────┬──────────────┐
│ countries ┆ personCounts │
│ --- ┆ --- │
│ str ┆ i64 │
╞════════════════╪══════════════╡
│ United States ┆ 30733 │
│ Canada ┆ 3046 │
│ United Kingdom ┆ 1816 │
└────────────────┴──────────────┘
Query 5:
MATCH (p:Person)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
AND lower(p.gender) = lower($gender)
WITH p, i
MATCH (p)-[:LivesIn]->(c:City)
WHERE c.city = $city AND c.country = $country
RETURN count(p) AS numPersons
Number of male users in London, United Kingdom who have an interest in fine dining:
shape: (1, 1)
┌────────────┐
│ numPersons │
│ --- │
│ i64 │
╞════════════╡
│ 52 │
└────────────┘
Query 6:
MATCH (p:Person)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
AND lower(p.gender) = lower($gender)
WITH p, i
MATCH (p)-[:LivesIn]->(c:City)
RETURN count(p.id) AS numPersons, c.city AS city, c.country AS country
ORDER BY numPersons DESC LIMIT 5
City with the most female users who have an interest in tennis:
shape: (5, 3)
┌────────────┬────────────┬────────────────┐
│ numPersons ┆ city ┆ country │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞════════════╪════════════╪════════════════╡
│ 66 ┆ Houston ┆ United States │
│ 66 ┆ Birmingham ┆ United Kingdom │
│ 65 ┆ Raleigh ┆ United States │
│ 64 ┆ Montreal ┆ Canada │
│ 62 ┆ Phoenix ┆ United States │
└────────────┴────────────┴────────────────┘
Query 7:
MATCH (p:Person)-[:LivesIn]->(:City)-[:CityIn]->(s:State)
WHERE p.age >= $age_lower AND p.age <= $age_upper AND s.country = $country
WITH p, s
MATCH (p)-[:HasInterest]->(i:Interest)
WHERE lower(i.interest) = lower($interest)
RETURN count(p.id) AS numPersons, s.state AS state, s.country AS country
ORDER BY numPersons DESC LIMIT 1
State in United States with the most users between ages 23-30 who have an interest in photography:
shape: (1, 3)
┌────────────┬────────────┬───────────────┐
│ numPersons ┆ state ┆ country │
│ --- ┆ --- ┆ --- │
│ i64 ┆ str ┆ str │
╞════════════╪════════════╪═══════════════╡
│ 168 ┆ California ┆ United States │
└────────────┴────────────┴───────────────┘
Query 8:
MATCH (a:Person)-[r1:Follows]->(b:Person)-[r2:Follows]->(c:Person)
RETURN count(*) AS numPaths
Number of second-degree paths:
shape: (1, 1)
┌──────────┐
│ numPaths │
│ --- │
│ i64 │
╞══════════╡
│ 58431994 │
└──────────┘
Query 9:
MATCH (a:Person)-[r1:Follows]->(b:Person)-[r2:Follows]->(c:Person)
WHERE b.age < $age_1 AND c.age > $age_2
RETURN count(*) as numPaths
Number of paths through persons below 50 to persons above 25:
shape: (1, 1)
┌──────────┐
│ numPaths │
│ --- │
│ i64 │
╞══════════╡
│ 46220422 │
└──────────┘
Queries completed in 0.7561s
The benchmark is run using pytest-benchmark package as follows.
$ pytest benchmark_query.py --benchmark-min-rounds=5 --benchmark-warmup-iterations=5 --benchmark-disable-gc --benchmark-sort=fullname ✘ 130 update-kuzu ✱
====================================================================================================== test session starts =======================================================================================================
platform darwin -- Python 3.11.7, pytest-8.1.1, pluggy-1.4.0
benchmark: 4.0.0 (defaults: timer=time.perf_counter disable_gc=True min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=5)
rootdir: /Users/prrao/code/kuzudb-study/kuzudb
plugins: Faker-23.1.0, benchmark-4.0.0
collected 9 items
benchmark_query.py ......... [100%]
-------------------------------------------------------------------------------------- benchmark: 9 tests --------------------------------------------------------------------------------------
Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_query1 254.0487 (77.28) 331.9569 (65.09) 272.2583 (72.23) 33.5090 (118.10) 258.9573 (70.13) 24.4201 (82.49) 1;1 3.6730 (0.01) 5 1
test_benchmark_query2 293.4545 (89.27) 388.5836 (76.19) 334.0680 (88.63) 48.9350 (172.46) 301.8217 (81.74) 88.7258 (299.73) 2;0 2.9934 (0.01) 5 1
test_benchmark_query3 10.4950 (3.19) 12.3280 (2.42) 11.2442 (2.98) 0.3642 (1.28) 11.2188 (3.04) 0.4407 (1.49) 19;2 88.9345 (0.34) 62 1
test_benchmark_query4 8.6238 (2.62) 11.0205 (2.16) 9.3746 (2.49) 0.4232 (1.49) 9.2816 (2.51) 0.4236 (1.43) 15;6 106.6709 (0.40) 76 1
test_benchmark_query5 3.2872 (1.0) 5.1003 (1.0) 3.7691 (1.0) 0.3535 (1.25) 3.6925 (1.0) 0.2960 (1.0) 23;9 265.3119 (1.0) 104 1
test_benchmark_query6 32.8883 (10.00) 35.4205 (6.94) 33.5387 (8.90) 0.5317 (1.87) 33.3696 (9.04) 0.6214 (2.10) 6;1 29.8163 (0.11) 28 1
test_benchmark_query7 6.2537 (1.90) 7.7147 (1.51) 7.0166 (1.86) 0.2837 (1.0) 7.0423 (1.91) 0.3966 (1.34) 34;0 142.5183 (0.54) 91 1
test_benchmark_query8 86.9893 (26.46) 91.6528 (17.97) 90.1817 (23.93) 1.5253 (5.38) 90.8585 (24.61) 2.1688 (7.33) 1;0 11.0887 (0.04) 9 1
test_benchmark_query9 98.5566 (29.98) 105.5151 (20.69) 101.6341 (26.96) 2.2933 (8.08) 101.5073 (27.49) 2.8376 (9.59) 2;0 9.8392 (0.04) 7 1
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Legend:
Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
OPS: Operations Per Second, computed as 1 / Mean
======================================================================================================= 9 passed in 11.30s =======================================================================================================$ pytest benchmark_query.py --benchmark-min-rounds=5 --benchmark-warmup-iterations=5 --benchmark-disable-gc --benchmark-sort=fullname ✘ 130 update-kuzu ✱
====================================================================================================== test session starts =======================================================================================================
platform darwin -- Python 3.11.7, pytest-8.1.1, pluggy-1.4.0
benchmark: 4.0.0 (defaults: timer=time.perf_counter disable_gc=True min_rounds=5 min_time=0.000005 max_time=1.0 calibration_precision=10 warmup=False warmup_iterations=5)
rootdir: /Users/prrao/code/kuzudb-study/kuzudb
plugins: Faker-23.1.0, benchmark-4.0.0
collected 9 items
benchmark_query.py ......... [100%]
-------------------------------------------------------------------------------------- benchmark: 9 tests --------------------------------------------------------------------------------------
Name (time in ms) Min Max Mean StdDev Median IQR Outliers OPS Rounds Iterations
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
test_benchmark_query1 143.7831 (36.84) 252.6395 (38.09) 167.8478 (36.78) 47.4400 (111.50) 147.9915 (33.16) 29.3312 (60.86) 1;1 5.9578 (0.03) 5 1
test_benchmark_query2 198.2216 (50.79) 205.8762 (31.04) 202.4746 (44.37) 3.0336 (7.13) 203.0530 (45.50) 4.6756 (9.70) 2;0 4.9389 (0.02) 5 1
test_benchmark_query3 13.5389 (3.47) 15.5465 (2.34) 14.4884 (3.17) 0.4255 (1.0) 14.4661 (3.24) 0.4819 (1.0) 15;1 69.0209 (0.31) 52 1
test_benchmark_query4 12.5585 (3.22) 14.5405 (2.19) 13.6137 (2.98) 0.4390 (1.03) 13.5607 (3.04) 0.5406 (1.12) 20;1 73.4555 (0.34) 55 1
test_benchmark_query5 3.9030 (1.0) 6.6330 (1.0) 4.5634 (1.0) 0.4712 (1.11) 4.4623 (1.0) 0.4962 (1.03) 16;5 219.1327 (1.0) 101 1
test_benchmark_query6 32.6305 (8.36) 42.6955 (6.44) 34.6170 (7.59) 2.0708 (4.87) 34.1572 (7.65) 0.7366 (1.53) 3;3 28.8876 (0.13) 27 1
test_benchmark_query7 6.9358 (1.78) 9.6718 (1.46) 7.8832 (1.73) 0.4438 (1.04) 7.8641 (1.76) 0.4891 (1.02) 22;2 126.8526 (0.58) 91 1
test_benchmark_query8 65.6220 (16.81) 125.4942 (18.92) 77.7316 (17.03) 21.5360 (50.61) 66.9292 (15.00) 3.3628 (6.98) 3;3 12.8648 (0.06) 14 1
test_benchmark_query9 64.6778 (16.57) 68.5543 (10.34) 66.3754 (14.55) 1.0579 (2.49) 66.3023 (14.86) 1.0378 (2.15) 4;1 15.0658 (0.07) 14 1
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
Legend:
Outliers: 1 Standard Deviation from Mean; 1.5 IQR (InterQuartile Range) from 1st Quartile and 3rd Quartile.
OPS: Operations Per Second, computed as 1 / Mean
======================================================================================================= 9 passed in 10.13s =======================================================================================================