Algo extension

The algo extension allows you to run common graph algorithms such as PageRank, Connected Components, and Louvain on the graph stored in Kuzu. The algorithms are exposed as Cypher functions and execute directly inside Kuzu.

Currently, the algo extension provides the following algorithms:

• K-Core Decomposition
• Louvain
• PageRank
• Strongly Connected Components
• Weakly Connected Components

Usage

INSTALL algo;
LOAD algo;

Projected graphs

The graph algorithms run on projected graphs instead of operating directly on Kuzu database tables.

A projected graph contains only the nodes and relationships that are relevant for the algorithm you want to run, and is created by matching on a given table name and predicates.

Example dataset

Let’s first create the node and relationship tables we will use for creating projected graphs.

CREATE NODE TABLE Person(name STRING PRIMARY KEY);
CREATE REL TABLE KNOWS(FROM Person to Person, id INT64);
CREATE  (u0:Person {name: 'Alice'}),
        (u1:Person {name: 'Bob'}),
        (u2:Person {name: 'Charlie'}),
        (u3:Person {name: 'Derek'}),
        (u4:Person {name: 'Eve'}),
        (u5:Person {name: 'Frank'}),
        (u6:Person {name: 'George'}),
        (u7:Person {name: 'Hina'}),
        (u8:Person {name: 'Ira'}),
        (u0)-[:KNOWS {id: 0}]->(u1),
        (u1)-[:KNOWS {id: 1}]->(u2),
        (u5)-[:KNOWS {id: 2}]->(u4),
        (u6)-[:KNOWS {id: 3}]->(u4),
        (u6)-[:KNOWS {id: 4}]->(u5),
        (u6)-[:KNOWS {id: 5}]->(u7),
        (u7)-[:KNOWS {id: 6}]->(u4),
        (u6)-[:KNOWS {id: 7}]->(u5);

Simple projection

You can create a projected graph on a specific set of node and relationship tables:

CALL PROJECT_GRAPH(
    <GRAPH_NAME>,
    [<NODE_TABLE_0>, <NODE_TABLE_1>, ...], // node tables
    [<REL_TABLE_0>, <REL_TABLE_1>, ...]    // relationship tables
);

• GRAPH_NAME: Name of the projected graph
  • Type: STRING
• NODE_TABLE_x: A node table to project
  • Type: STRING
• REL_TABLE_x: A relationship table to project
  • Type: STRING

Example

For example, to create a projected graph named Graph with the node table Person and the relationship table KNOWS, use:

CALL PROJECT_GRAPH('Graph', ['Person'], ['KNOWS']);

Filtered projection

You can also create a projected graph with filters on the node or relationship tables:

CALL PROJECT_GRAPH(
    <GRAPH_NAME>,
    {
        <NODE_TABLE_0> :  <NODE_PREDICATE_0>,
        <NODE_TABLE_1> :  <NODE_PREDICATE_1>,
        ...
    },
    {
        <REL_TABLE_0> :  <REL_PREDICATE_0>,
        <REL_TABLE_1> :  <REL_PREDICATE_1>,
        ...
    }
);

• GRAPH_NAME: Name of the projected graph
  • Type: STRING
• NODE_TABLE_x: A node table to project
  • Type: STRING
• REL_TABLE_x: A relationship table to project
  • Type: STRING
• NODE_PREDICATE_x: Predicate used to filter the node table
  • Type: STRING
• REL_PREDICATE_x: Predicate used to filter the relationship table
  • Type: STRING

Note

• Predicates must depend only on their corresponding node/relationship tables. Predicates involving multiple tables are not supported.
• Use n to refer to the nodes and r to refer to the relationships. Properties can be accessed as n.property_name or r.property_name.

Example

For example, to create a projected graph named filtered_graph with the node table Person and the relationship table KNOWS, and filter the nodes with name not equal to Ira and the relationships with id less than 3, use:

CALL PROJECT_GRAPH(
    'filtered_graph',
    {
        'Person': 'n.name <> "Ira"'
    },
    {
        'KNOWS': 'r.id < 3'
    }
);

List projected graphs

To list all available projected graphs, use:

CALL SHOW_PROJECTED_GRAPHS();

Drop a projected graph

You can explicitly drop a projected graph using:

CALL DROP_PROJECTED_GRAPH(<GRAPH_NAME>);

• GRAPH_NAME: Name of the projected graph to drop
  • Type: STRING

Example

For example, to drop the projected graph filtered_graph, use:

CALL DROP_PROJECTED_GRAPH('filtered_graph');

Lifecycle of projected graphs

A projected graph is kept alive until:

• It is dropped explicitly, or
• The connection is closed.

A projected graph is evaluated only when an algorithm is executed. Kuzu does not materialize projected graphs in memory, and the corresponding data is scanned from disk on the fly.

Note

When creating projected graphs with the Python async API, you may encounter the following error:

Binder exception: Cannot find graph filtered_graph.

This error is because projected graphs are bound to a specific Connection instance, as mentioned above. The async API, however, executes queries using a connection pool. Depending on which connection is used to execute a query, the projected graph may not be available. This is a known limitation and will be addressed in a future release.

Edge direction

In Kuzu, both the base graph and projected graphs are directed. For algorithms that are only well-defined on undirected graphs, such as Weakly Connected Components, the graph is treated as undirected by ignoring the edge direction.