Adding algorithms to GraphQL by arienandalibi · Pull Request #2696 · Pometry/Raphtory

arienandalibi · 2026-07-31T09:03:49Z

What changes were proposed in this pull request?

Exposing the algorithms in GraphQL. They are currently only available in core Rust and Python.

Why are the changes needed?

Accessing them in GraphQL.

Does this PR introduce any user-facing change? If yes is this documented?

Yes, many GraphQL queries. All documented.

How was this patch tested?

Unit tests for each algorithm.

Are there any further changes required?

Yes, potential follow-ups on GqlNodeState ( #2694 ) and the algorithms ( #2695 )

…r for NodeState (we use OutputTypedNodeState because there are no generic type parameters), similar to how PyOutputNodeState does it. Currently added pagerank

… contain all the values for that column. Each column is an output of the algorithm. We can then access the column's name and each output value. These values are row-aligned with the nodes of the node state. These nodes are queried and returned separately.

…/value output

…s to make

…tations. Added a comparison function to use for these. Added sum and mean functions in GraphQL. They can't use the Rust implementations because of trait bounds on the functions, so we must re-implement them to handle number casting (and possible errors there).

…by node) instead of by column. There is also a variant to return rows without column names

…in GraphQL

…lgorithms in GraphQL

…t_batch algorithms in GraphQL

…bounded, temporal_three_node_motif, and temporally_reachable_nodes algorithms in GraphQL

… input as well as an optional node filter. We want to match python by making this a general filter, which doesn't currently exist in GraphQL.

…s (NodeFilter, EdgeFilter, GraphFilter). This allows a combination of all 3 filters to be passed as a single filter. Use them in in_component and out_component.

…icient, global_reciprocity algorithms in GraphQL

…egree, min_out_degree, triangle_count, and triplet_count algorithms in GraphQL

…s in GraphQL

…ti, Matching, and max_weight_matching algorithms in GraphQL

…lub_coefficient algorithm by taking rolling window args in GraphQL.

github-actions

⚠️ Performance Alert ⚠️

Possible performance regression was detected for benchmark 'Rust Benchmark'.
Benchmark result of this commit is worse than the previous benchmark result exceeding threshold 2.

Benchmark suite	Current: `6aa20a0`	Previous: `9823ef7`	Ratio
`lotr_graph/num_edges`	`4` ns/iter (`± 0`)	`0` ns/iter (`± 0`)	`+∞`
`lotr_graph/num_nodes`	`6` ns/iter (`± 0`)	`1` ns/iter (`± 0`)	`6`
`lotr_graph/graph_latest`	`3` ns/iter (`± 0`)	`0` ns/iter (`± 0`)	`+∞`
`lotr_graph_materialise/materialize`	`7909266` ns/iter (`± 82084`)	`1564816` ns/iter (`± 35303`)	`5.05`
`lotr_graph_window_100/num_nodes`	`15` ns/iter (`± 0`)	`5` ns/iter (`± 0`)	`3`
`lotr_graph_window_100_materialise/materialize`	`7908831` ns/iter (`± 35091`)	`1669150` ns/iter (`± 10700`)	`4.74`
`lotr_graph_window_10/has_node_existing`	`136` ns/iter (`± 11`)	`62` ns/iter (`± 11`)	`2.19`
`lotr_graph_window_10_materialise/materialize`	`3317912` ns/iter (`± 14022`)	`971980` ns/iter (`± 4278`)	`3.41`
`lotr_graph_subgraph_10pc_materialise/materialize`	`2059252` ns/iter (`± 12281`)	`334634` ns/iter (`± 1287`)	`6.15`
`lotr_graph_subgraph_10pc_windowed/has_node_existing`	`148` ns/iter (`± 10`)	`62` ns/iter (`± 14`)	`2.39`
`lotr_graph_subgraph_10pc_windowed_materialise/materialize`	`1264716` ns/iter (`± 20374`)	`230399` ns/iter (`± 2617`)	`5.49`
`lotr_graph_window_50_layered/num_edges_temporal`	`146584` ns/iter (`± 2063`)	`70121` ns/iter (`± 7586`)	`2.09`
`lotr_graph_window_50_layered/has_node_existing`	`377` ns/iter (`± 22`)	`129` ns/iter (`± 12`)	`2.92`
`lotr_graph_window_50_layered/graph_latest`	`88810` ns/iter (`± 1281`)	`36649` ns/iter (`± 916`)	`2.42`
`lotr_graph_window_50_layered_materialise/materialize`	`28985918` ns/iter (`± 177795`)	`3488825` ns/iter (`± 24948`)	`8.31`
`lotr_graph_persistent_window_50_layered/num_edges_temporal`	`586545` ns/iter (`± 5990`)	`192686` ns/iter (`± 1569`)	`3.04`
`lotr_graph_persistent_window_50_layered/has_node_existing`	`425` ns/iter (`± 375`)	`174` ns/iter (`± 83`)	`2.44`
`lotr_graph_persistent_window_50_layered/has_node_nonexisting`	`5` ns/iter (`± 0`)	`2` ns/iter (`± 0`)	`2.50`
`lotr_graph_persistent_window_50_layered/graph_latest`	`124762` ns/iter (`± 2834`)	`57549` ns/iter (`± 4809`)	`2.17`
`lotr_graph_persistent_window_50_layered_materialise/materialize`	`51626948` ns/iter (`± 591544`)	`5298035` ns/iter (`± 147912`)	`9.74`

This comment was automatically generated by workflow using github-action-benchmark.

miratepuffin

Probably a good idea to split the algorithms folder into a similar structure as the actual algorithms folder

miratepuffin · 2026-08-04T11:40:18Z

+pub(crate) mod weakly_connected_components;
+
+/// A graph algorithm executable through the GraphQL API.
+pub(crate) trait GqlExecutableAlgorithm: 'static {


There is a lot packed into this mod - I would split it out into different files

Ideally docs would be sync'd with python docs somehow

miratepuffin · 2026-08-04T11:42:36Z

    Layers(GraphLayersExpr),
 }

+/// A composite filter producing a graph view, bundling the graph-view, node,


I have something similar to this in my PR, we will need to merge - I don't think you are support And/Or here?

miratepuffin · 2026-08-04T11:45:10Z

    }

+    #[tokio::test]
+    async fn test_algorithm_node_state_ops() {


I would put all of the tests into the actual algorithms themselves, gonna be easier to see which ones haven't been tested then.

Might not be a terrible idea to sanity check in python by running on the local graph and then via graphql and seeing if we get the same result?

# Conflicts: # raphtory-graphql/src/model/graph/mod.rs # raphtory-graphql/src/model/mod.rs # raphtory/src/errors.rs

…nto respective files

…core rust

…ectories

… mod.rs short and structural.

miratepuffin · 2026-08-05T09:29:41Z

        Ok(alternating_mask(graph).into())
    }
 }
+


I don't think we need to expose this - its a test algorithm

miratepuffin · 2026-08-05T09:30:28Z

+        args: A::Args,
+    ) -> Result<A::Output, GraphError> {
+        let graph = self.graph.clone();
+        blocking_compute(move || A::execute(&graph, args)).await


This is probably not an issue right now, but we should probably highly weight some of these algorithms in terms of graphql complexity?

ljeub-pometry

I think all the extra abstraction and code for each algorithm isn't actually needed?

ljeub-pometry · 2026-08-05T09:09:48Z

+    /// Name of the column.
+    name: String,
+    /// The values of this column; `values[i]` belongs to `NodeState.nodes[i]`.
+    values: Vec<GqlNodeStateValue>,


This isn't great, you need to reallocate a new vector to make this instead of reusing the underlying column!

Also, SimpleObject is probably not the right thing to use here? Should be resolved with accessors for stuff like sum etc...

ljeub-pometry · 2026-08-05T09:14:57Z

+
+impl GqlNodeState {
+    /// A slice of `limit` rows starting at `start`, as a node state of its own.
+    fn slice(&self, start: usize, limit: usize) -> GqlNodeState {


we should expose an api like this on the NodeState itself

ljeub-pometry · 2026-08-05T09:17:52Z

+    }
+
+    /// Returns the values for a node, one entry per column; null if the node has no value in this NodeState.
+    async fn get(


shouldn't this return a Option<GqlNodeStateRow>?

ljeub-pometry · 2026-08-05T09:21:55Z

+    async fn min(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<GqlNodeStateItem> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            let item = self_clone
+                .node_state
+                .min_item_by(column_cmp(&column, true))?;
+            self_clone.item_from_row(&column, item)
+        })
+        .await
+    }
+
+    /// Maximum `(node, value)` of a column. Null if the column does not exist, is empty,
+    /// or its values are not comparable (e.g. contains nodes).
+    async fn max(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<GqlNodeStateItem> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            let item = self_clone
+                .node_state
+                .max_item_by(column_cmp(&column, false))?;
+            self_clone.item_from_row(&column, item)
+        })
+        .await
+    }
+
+    /// Sum of a column's values, skipping empty cells. Null if the column does not exist, is empty,
+    /// or is not additive (e.g. contains nodes).
+    async fn sum(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<GqlPropertyOutputVal> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            let mut values = self_clone.column_value_iter(&column)?;
+            let mut acc = values.next()?;
+            if !acc.dtype().has_add() {
+                return None;
+            }
+            for value in values {
+                acc = acc.add(value)?;
+            }
+            Some(GqlPropertyOutputVal(acc))
+        })
+        .await
+    }
+
+    /// Mean of a column's values as a float, skipping empty cells. Null if the column does not exist,
+    /// is empty, or has any non-numeric value.
+    async fn mean(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<GqlPropertyOutputVal> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            let mut values = self_clone.column_value_iter(&column)?;
+            let mut sum = values.next()?.as_f64()?;
+            let mut count = 1usize;
+            for value in values {
+                sum += value.as_f64()?;
+                count += 1;
+            }
+            Some(GqlPropertyOutputVal(Prop::F64(sum / count as f64)))
+        })
+        .await
+    }
+
+    /// Median `(node, value)` of a column (upper median on even lengths). Null if the column
+    /// does not exist, is empty, or is not comparable (e.g. contains nodes).
+    async fn median(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<GqlNodeStateItem> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            let item = self_clone
+                .node_state
+                .median_item_by(column_cmp(&column, true))?;
+            self_clone.item_from_row(&column, item)
+        })
+        .await
+    }
+
+    /// Returns the `k` rows with the largest values in a column. Empty cells rank
+    /// lowest, so they are only included if fewer than `k` rows have a value.
+    /// Null if the column does not exist, is empty, or is not comparable.
+    async fn top_k(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+        #[graphql(desc = "Number of rows to return.")] k: usize,
+    ) -> Option<GqlNodeState> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            Some(GqlNodeState {
+                node_state: self_clone
+                    .node_state
+                    .top_k_by(column_cmp(&column, false), k),
+            })
+        })
+        .await
+    }
+
+    /// Returns the `k` rows with the smallest values in a column. Empty cells rank
+    /// highest, so they are only included if fewer than `k` rows have a value.
+    /// Null if the column does not exist, is empty, or is not comparable.
+    async fn bottom_k(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+        #[graphql(desc = "Number of rows to return.")] k: usize,
+    ) -> Option<GqlNodeState> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            Some(GqlNodeState {
+                node_state: self_clone
+                    .node_state
+                    .bottom_k_by(column_cmp(&column, true), k),
+            })
+        })
+        .await
+    }
+
+    /// Returns a view of this node state with the rows sorted by a column's values,
+    /// ascending with empty cells last. `reverse` flips the whole ordering, putting
+    /// empty cells first. Null if the column does not exist, is empty, or is not
+    /// comparable.
+    async fn sort_by_values(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+        #[graphql(desc = "Sort in descending order instead. Defaults to false.")] reverse: Option<
+            bool,
+        >,
+    ) -> Option<GqlNodeState> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            self_clone.check_comparable(&column)?;
+            let cmp = column_cmp(&column, true);
+            let node_state = if reverse.unwrap_or(false) {
+                self_clone
+                    .node_state
+                    .sort_by_values_by(|a, b| cmp(a, b).reverse())
+            } else {
+                self_clone.node_state.sort_by_values_by(cmp)
+            };
+            Some(GqlNodeState { node_state })
+        })
+        .await
+    }
+
+    /// Groups the nodes by their value in a column. Nodes with an empty cell form
+    /// their own group. Null if the column does not exist or contains nodes.
+    async fn group_by(
+        &self,
+        #[graphql(desc = "Column name.")] column: String,
+    ) -> Option<Vec<GqlNodeStateGroup>> {
+        let self_clone = self.clone();
+        blocking_compute(move || {
+            if !self_clone.is_prop_column(&column) {
+                return None;
+            }
+            let groups = self_clone.node_state.group_by(|mut row| {
+                GroupKey::new(row.swap_remove(&column).flatten().map(|value| value.0))
+            });
+            Some(
+                groups
+                    .into_iter_groups()
+                    .map(|(key, nodes)| GqlNodeStateGroup {
+                        value: key.value.map(GqlPropertyOutputVal),
+                        nodes: GqlNodes::new(nodes),
+                    })
+                    .collect(),
+            )
+        })
+        .await
+    }


We need proper single-column apis in the rust layer. However, the ordering based apis here should work with multiple columns, same as in rust.

ljeub-pometry · 2026-08-05T09:23:03Z

+
+    /// The columns of the node state, one per output field of the algorithm.
+    /// `values` are row-aligned with `nodes`.
+    async fn columns(&self) -> Vec<GqlNodeStateColumn> {


there should be column(name) as well to get a single column

ljeub-pometry · 2026-08-05T09:52:39Z

+        #[graphql(desc = "Edge property to use as weight. If unset, all edges have weight 1.")]
+        weight: Option<String>,
+    ) -> Result<GqlNodeState, GraphError> {
+        self.run::<GqlPagerank>(GqlPagerankArgs {


what is the point in the whole executable machinery when you are still writing all these functions here anyway? You could have e.g., just called blocking_compute(|| {pagerank()).await here?

ljeub-pometry · 2026-08-05T09:56:34Z

+        #[graphql(desc = "Edge property to use as weight. If unset, all edges have weight 1.")]
+        weight: Option<String>,
+    ) -> Result<GqlNodeState, GraphError> {
+        self.run::<GqlPagerank>(GqlPagerankArgs {


This whole executable machinery seems to be entirely useless? You could just change the run method to take a closure that has a DynamicGraph as input and a generic as output and have everything inline here without all the extra code for each algorithm!

arienandalibi added 30 commits July 14, 2026 04:52

Adding algorithms to GraphQL defined statically. Added GraphQL wrappe…

1a821ed

…r for NodeState (we use OutputTypedNodeState because there are no generic type parameters), similar to how PyOutputNodeState does it. Currently added pagerank

Update pagerank test to match new output query.

84d94f8

Rustfmt

5710bc4

Add python test for graphql pagerank algorithm with the new nodestate…

d3597dd

…/value output

Merge branch 'db_v4' into db_v4_graphql_algorithms

a613dea

cargo.lock and rustfmt changes

5a63273

update python test

763914c

Added get and sortById on GqlNodeState, along with a test for them

adc53c2

First iteration of min/max/median for GraphQL. Still have some change…

8f341d0

…s to make

Added GraphQL queries to return the NodeState's values by row (keyed …

7b2517d

…by node) instead of by column. There is also a variant to return rows without column names

Rename field

e60f633

Adding single source shortest path to GraphQL algorithms.

0e6c136

Adding out components to GraphQL algorithms.

1f4e7fa

Adding in components and dijkstra to GraphQL algorithms.

8068934

Merge branch 'db_v4' into db_v4_graphql_algorithms

bda581e

Added degree_centrality, betweenness_centrality, and hits algorithms …

19aa86c

…in GraphQL

Added label_propagation and louvain algorithms in GraphQL

dced393

Added strongly_connected_components and weakly_connected_components a…

801b5ce

…lgorithms in GraphQL

Added all_local_reciprocity, balance, and local_clustering_coefficien…

e01dc3c

…t_batch algorithms in GraphQL

Added cohesive_fruchterman_reingold, fast_rp, fruchterman_reingold_un…

43a18af

…bounded, temporal_three_node_motif, and temporally_reachable_nodes algorithms in GraphQL

Adding in_component and out_component to GraphQL. They take a node as…

be192b8

… input as well as an optional node filter. We want to match python by making this a general filter, which doesn't currently exist in GraphQL.

Added GqlViewFilter to GraphQL, which combines the three other filter…

8e08fae

…s (NodeFilter, EdgeFilter, GraphFilter). This allows a combination of all 3 filters to be passed as a single filter. Use them in in_component and out_component.

Updating f32 algorithms to use f64

0cbd4d1

Added average_degree, directed_graph_density, global_clustering_coeff…

3d20e6b

…icient, global_reciprocity algorithms in GraphQL

Added max_degree, max_in_degree, max_out_degree, min_degree, min_in_d…

72ab648

…egree, min_out_degree, triangle_count, and triplet_count algorithms in GraphQL

Added local_clustering_coefficient and local_triangle_count algorithm…

a906520

…s in GraphQL

Added global_temporal_three_node_motif, temporal_three_node_motif_mul…

014df50

…ti, Matching, and max_weight_matching algorithms in GraphQL

Added alternating_mask and temporal_SEIR algorithms in GraphQL

bdb802c

arienandalibi added 5 commits July 30, 2026 06:13

Fixing temporal_SEIR probability infection and adding temporal_rich_c…

dd6a414

…lub_coefficient algorithm by taking rolling window args in GraphQL.

Update schema.graphql

11915a2

Added top_k, bottom_k, sort_by_values, and group_by to GqlNodeState

f77fa8e

Merge branch 'db_v4' into db_v4_graphql_algorithms

2f1498b

Update TODO and FIXME

8e21120

github-actions Bot reviewed Jul 31, 2026

View reviewed changes

arienandalibi added 2 commits August 3, 2026 01:09

Merge branch 'db_v4' into db_v4_graphql_algorithms

8e752c2

Added paging for GqlNodeState

29eac50

miratepuffin requested changes Aug 4, 2026

View reviewed changes

arienandalibi added 6 commits August 4, 2026 17:02

Merge branch 'db_v4' into db_v4_graphql_algorithms

403f01d

# Conflicts: # raphtory-graphql/src/model/graph/mod.rs # raphtory-graphql/src/model/mod.rs # raphtory/src/errors.rs

Moving algorithm, node state, and filtering tests out of lib.rs and i…

30d0479

…nto respective files

Move tests from lib.rs to the individual algorithm's rust file

de13847

Change directory structure of algorithms in GraphQL to match that of …

02b1143

…core rust

Fixing new directory structures. Mainly adding mod.rs files to subdir…

aeb15a2

…ectories

Splitting GraphQL's src/model/algorithms.mod.rs into 3 files, keeping…

bbd791c

… mod.rs short and structural.

miratepuffin approved these changes Aug 5, 2026

View reviewed changes

Rename test_algorithms.py to test_algorithms_graphql.py

6aa20a0

ljeub-pometry requested changes Aug 5, 2026

View reviewed changes

miratepuffin closed this Aug 6, 2026

Uh oh!

Conversation

arienandalibi commented Jul 31, 2026

What changes were proposed in this pull request?

Why are the changes needed?

Does this PR introduce any user-facing change? If yes is this documented?

How was this patch tested?

Are there any further changes required?

Uh oh!

github-actions Bot left a comment • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

⚠️ Performance Alert ⚠️

Uh oh!

miratepuffin left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

ljeub-pometry left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

3 participants

github-actions Bot left a comment •

edited

Loading