Graphql docs and tests

[miratepuffin]

graphql-docs-and-tests — Top-level Summary

Branch focused on hardening Raphtory's GraphQL surface: documenting it, expanding what its inputs accept, and verifying it from Python. Also picks up housekeeping on the Python bindings (PyO3 stubs, PyProp constructors).

Fixes #1937 #2101 #2238 #2302 #2301 #2300

Need to get smmoosavi/dynamic-graphql#42 merged

1. GraphQL schema: documentation + tests

• Every resolver type, field, and argument now carries a doc comment intended for the public docs site.
• Permission requirements on every root-query / mutation now follow a consistent format (Requires READ on the graph., Requires WRITE on the parent namespace., etc.).
• Filled in coverage for previously untested resolvers; added Python integration tests around them.
• Picked up a forked dynamic-graphql branch that exposes per-argument desc attributes (the released crate has no such hook).

2. New / widened input scalars

Made a new NodeId for String or non-negative Int similar to TimeInput. The two scalars are wired through every relevant resolver: lookups (node, edge, hasNode, hasEdge), view transforms (subgraph, excludeNodes, sharedNeighbours), all mutations (addNode, addEdge, deleteEdge, batch variants, MutableGraph.{node,edge}), createSubgraph, and VectorSelection.{addNodes,addEdges}.

Node.id and Edge.id now return NodeId (so an integer-indexed graph returns integers, not stringified ones).

Filters already accepted both forms via the existing Value scalar — no schema change there, just verified.

3. Graph-semantics override

graph(path: ..., graphType: EVENT | PERSISTENT) (and the same arg on MutableGraph.graph) lets a caller re-interpret a stored graph at query time:

• An event graph queried with graphType: PERSISTENT carries values forward in windows after the addition.
• A persistent graph queried with graphType: EVENT only sees updates exactly at the queried time.

4. Temporal-property API changes

• TemporalProperty.values now returns typed PropValues instead of stringified values.
• Added Python-style aggregates on TemporalProperty: sum, mean, median, min, max, count, average. Returning null for non-numeric value types.
• unique and orderedDedupe return a TemporalProperty so the aggregates compose.

5. Python tests added

File	Coverage
test_gql_node_id.py	NodeId (Int + String) on every read/write surface
test_gql_mutation_time_input.py	TimeInput shapes (Int / RFC3339 / object) on every mutation
test_gql_graph_type.py	graphType override × stored type × window semantics
test_graphql_vectors.py	VectorisedGraphWindow with TimeInput
test_props.py	New Prop constructors (datetime, naive_datetime, decimal) — strings, Python Decimal, ints, floats; graph round-trip; list unification
test_load_from_pandas.py	Schema-driven loading with PropType.decimal(scale), PropType.datetime(), PropType.naive_datetime() — string columns, Arrow Decimal128, both nodes and edges

6. Python bindings (raphtory-api, raphtory)

New Prop / PropType constructors

• Prop.aware_datetime(dt) — tz-aware datetime (UTC-stored). Naive input rejected.
• Prop.naive_datetime(dt) — tz-naive datetime.
• Prop.decimal(value) — accepts decimal.Decimal, str, int, or float.
• PropType.decimal(scale) — schema-side companion (PropType.datetime() / PropType.naive_datetime() already existed). Lets load_nodes/load_edges accept schema={"col": PropType.decimal(2)} to cast string or Arrow Decimal128 columns.

Stub generation (gen-stubs.py)

• Audited every PyO3 method for missing docs / return types / parameter docs.
• Registered iterable wrapper classes (PyPropValueListList, PyTemporalPropsList, PyTemporalPropsListList, PyPropHistValueList, PyPropHistValueListList, PyTemporalPropList, PyTemporalPropListList, PyPropHistItemsList, PyPropHistItemsListList, PropIterable) plus EmbeddingServer, RunningEmbeddingServer, OutputNodeState so they resolve in generated stubs.
• Aliased raphtory.iterables and raphtory.gql into sys.modules so submodule imports resolve.
• Renamed Rust types in docstrings to match exported Python names (PyOutputNodeState → OutputNodeState, TypedNodeState → OutputNodeState, Str → str, NumpyArray → NDArray, etc.).
• Result: gen-stubs.py reports zero warnings; mypy -m raphtory passes. (other than GQL which we can fix later)

7. dynamic-graphql fork

Submitted upstream PR adding desc attribute support on ResolvedObjectFieldsArg / InterfaceMethodArg / ExpandObjectFieldsArg. Branch add-arg-descriptions of miratepuffin/dynamic-graphql is referenced from this repo's Cargo.toml until upstream merges.

[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: 2b6e39e	Previous: 9823ef7	Ratio
lotr_graph/num_edges	5 ns/iter (± 0)	0 ns/iter (± 0)	+∞
lotr_graph/num_nodes	127 ns/iter (± 23)	1 ns/iter (± 0)	127
lotr_graph/graph_latest	3 ns/iter (± 0)	0 ns/iter (± 0)	+∞
lotr_graph_window_100/num_edges	29 ns/iter (± 0)	8 ns/iter (± 0)	3.63
lotr_graph_window_100/num_nodes	141 ns/iter (± 24)	5 ns/iter (± 0)	28.20
lotr_graph_window_100/has_node_existing	45 ns/iter (± 0)	22 ns/iter (± 0)	2.05
lotr_graph_window_10/has_node_existing	148 ns/iter (± 8)	62 ns/iter (± 11)	2.39
lotr_graph_window_10/iterate nodes	36416 ns/iter (± 178)	11339 ns/iter (± 40)	3.21
lotr_graph_window_10/iterate edges	100640 ns/iter (± 496)	48684 ns/iter (± 211)	2.07
lotr_graph_subgraph_10pc/has_edge_existing	255 ns/iter (± 13)	93 ns/iter (± 1)	2.74
lotr_graph_subgraph_10pc/num_nodes	125 ns/iter (± 40)	4 ns/iter (± 0)	31.25
lotr_graph_subgraph_10pc/has_node_existing	117 ns/iter (± 1)	34 ns/iter (± 0)	3.44
lotr_graph_subgraph_10pc/iterate nodes	2751 ns/iter (± 139)	839 ns/iter (± 5)	3.28
lotr_graph_subgraph_10pc_windowed/has_node_existing	142 ns/iter (± 8)	62 ns/iter (± 14)	2.29
lotr_graph_subgraph_10pc_windowed/iterate nodes	4857 ns/iter (± 100)	1365 ns/iter (± 3)	3.56
lotr_graph_window_50_layered/num_edges_temporal	155195 ns/iter (± 2540)	70121 ns/iter (± 7586)	2.21
lotr_graph_window_50_layered/num_nodes	63638 ns/iter (± 454)	21435 ns/iter (± 536)	2.97
lotr_graph_window_50_layered/has_node_existing	946 ns/iter (± 70)	129 ns/iter (± 12)	7.33
lotr_graph_window_50_layered/max_id	70546 ns/iter (± 934)	25556 ns/iter (± 252)	2.76
lotr_graph_window_50_layered/iterate nodes	139766 ns/iter (± 626)	19308 ns/iter (± 47)	7.24
lotr_graph_window_50_layered/iterate edges	194754 ns/iter (± 708)	83616 ns/iter (± 1318)	2.33
lotr_graph_window_50_layered/graph_latest	106963 ns/iter (± 2396)	36649 ns/iter (± 916)	2.92
lotr_graph_persistent_window_50_layered/num_edges_temporal	724801 ns/iter (± 21157)	192686 ns/iter (± 1569)	3.76
lotr_graph_persistent_window_50_layered/num_nodes	82577 ns/iter (± 1730)	31517 ns/iter (± 779)	2.62
lotr_graph_persistent_window_50_layered/has_node_existing	1102 ns/iter (± 181)	174 ns/iter (± 83)	6.33
lotr_graph_persistent_window_50_layered/max_id	91868 ns/iter (± 2666)	38024 ns/iter (± 490)	2.42
lotr_graph_persistent_window_50_layered/iterate nodes	184646 ns/iter (± 1102)	35886 ns/iter (± 191)	5.15
lotr_graph_persistent_window_50_layered/iterate edges	194421 ns/iter (± 418)	84161 ns/iter (± 596)	2.31
lotr_graph_persistent_window_50_layered/iterate_exploded_edges	3417218 ns/iter (± 12964)	1659940 ns/iter (± 19402)	2.06
lotr_graph_persistent_window_50_layered/graph_latest	163084 ns/iter (± 2341)	57549 ns/iter (± 4809)	2.83
lotr_graph_persistent_window_50_layered_materialise/materialize	12810010 ns/iter (± 57934)	5298035 ns/iter (± 147912)	2.42
lotr_graph/proto_encode	5818991 ns/iter (± 60410)	1157897 ns/iter (± 73709)	5.03

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