feat(graph-query): add edge querying endpoint and support for edge body fields

- Introduced a new endpoint `POST /v1/graph/query/edges` to query edges using a request shape similar to vertex queries.
- Added support for edge schemas with body fields, returning relevant edge details including `cell_id`, `from_id`, `to_id`, `schema_id`, `edge_type`, and `body`.
- Updated the HTTP API documentation to reflect the new edge query capabilities.
- Enhanced the graph engine to handle edge lookups and validate edge schemas.

Author: shisoft

HTTP_API.md

@@ -280,6 +280,22 @@ Request shape is the same as `/v1/query` and returns matching graph vertices:
 
 Request shape is the same as `/v1/query/explain`.
 
+`POST /v1/graph/query/edges`
+
+Query edge body cells using the same request shape as `/v1/query`:
+
+```json
+{
+  "schema_name": "my_edge",
+  "selection": "(= weight 7u64)",
+  "order_by_field": "weight",
+  "limit": 20
+}
+```
+
+- Edge query currently supports edge schemas with body fields.
+- Response includes `cell_id`, `from_id`, `to_id`, `schema_id`, `edge_type`, and `body`.
+
 `POST /v1/graph/query/traverse`
 
 Request:

crates/morpheus-http-client/src/lib.rs

@@ -353,6 +353,21 @@ impl MorpheusHttpClient {
         parse_json(res).await
     }
 
+    pub async fn graph_query_edges(
+        &self,
+        req: &GraphLookupRequest,
+    ) -> Result<ApiResponse<Vec<GraphLookupEdgeDto>>, ClientError> {
+        let url = self.endpoint("/v1/graph/query/edges")?;
+        let res = self
+            .client
+            .post(url)
+            .json(req)
+            .send()
+            .await
+            .map_err(ClientError::http)?;
+        parse_json(res).await
+    }
+
     pub async fn graph_query_traverse(
         &self,
         req: &GraphTraverseRequest,

crates/morpheus-http-client/src/types.rs

@@ -272,6 +272,16 @@ pub struct GraphTraverseResult {
     pub edges: Vec<GraphTraverseEdgeDto>,
 }
 
+#[derive(Debug, Deserialize, Serialize)]
+pub struct GraphLookupEdgeDto {
+    pub cell_id: String,
+    pub from_id: String,
+    pub to_id: String,
+    pub schema_id: u32,
+    pub edge_type: Value,
+    pub body: Value,
+}
+
 #[cfg(test)]
 mod tests {
     use serde_json::from_str;

src/graph/query.rs

@@ -2,19 +2,26 @@ use std::collections::{HashSet, VecDeque};
 
 use neb::dovahkiin::expr::serde::Expr;
 use neb::dovahkiin::integrated::lisp::parse_to_serde_expr;
+use neb::dovahkiin::types::Map;
 use neb::index::ranged::tree::btree::Ordering;
 use neb::query::planner::{ClauseOrderExplain, QueryPlanExplain};
-use neb::ram::cell::OwnedCell;
-use neb::ram::types::Id;
+use neb::ram::cell::{OwnedCell, ReadError};
+use neb::ram::types::{Id, OwnedMap, OwnedValue};
 
+use crate::graph::edge::directed::DirectedEdge;
+use crate::graph::edge::undirectd::UndirectedEdge;
 use crate::graph::edge::bilateral::BilateralEdge;
 use crate::graph::{EdgeDirection, EdgeType, GraphEngine};
+use crate::server::schema::GraphSchema;
 
 #[derive(Debug)]
 pub enum GraphQueryError {
     InvalidSelectionExpr(String),
     InvalidOrdering(String),
     InvalidDirection(String),
+    SchemaNotEdge(u32),
+    SchemaRequiresEdgeBody(u32),
+    InvalidEdgeCell(String),
     EdgeSchemasRequired,
     Internal(String),
 }
@@ -61,6 +68,16 @@ pub struct GraphTraverseResult {
     pub edges: Vec<GraphTraverseEdge>,
 }
 
+#[derive(Debug, Clone)]
+pub struct GraphLookupEdge {
+    pub id: Id,
+    pub from_id: Id,
+    pub to_id: Id,
+    pub schema_id: u32,
+    pub edge_type: EdgeType,
+    pub body: OwnedMap,
+}
+
 #[derive(Debug, Clone)]
 pub struct GraphQueryPlanExplain {
     pub disjunction: bool,
@@ -78,10 +95,7 @@ pub struct GraphClauseOrderExplain {
 }
 
 impl GraphEngine {
-    pub async fn lookup_vertex_ids(
-        &self,
-        req: &GraphLookupParams,
-    ) -> Result<Vec<Id>, GraphQueryError> {
+    async fn lookup_ids(&self, req: &GraphLookupParams) -> Result<Vec<Id>, GraphQueryError> {
         let selection = parse_selection_expr(&req.selection)?;
         let ordering = parse_ordering(req.ordering.as_deref())?;
         let mut cursor = self
@@ -105,11 +119,18 @@ impl GraphEngine {
         Ok(ids)
     }
 
+    pub async fn lookup_vertex_ids(
+        &self,
+        req: &GraphLookupParams,
+    ) -> Result<Vec<Id>, GraphQueryError> {
+        self.lookup_ids(req).await
+    }
+
     pub async fn lookup_vertices(
         &self,
         req: &GraphLookupParams,
     ) -> Result<Vec<OwnedCell>, GraphQueryError> {
-        let ids = self.lookup_vertex_ids(req).await?;
+        let ids = self.lookup_ids(req).await?;
         let mut vertices = Vec::new();
         for id in ids {
             if let Some(vertex) = self.vertex_by(id).await.map_err(internal_error)? {
@@ -119,6 +140,72 @@ impl GraphEngine {
         Ok(vertices)
     }
 
+    pub async fn lookup_edges(
+        &self,
+        req: &GraphLookupParams,
+    ) -> Result<Vec<GraphLookupEdge>, GraphQueryError> {
+        let edge_attrs = match self.schemas.schema_type(req.schema_id) {
+            Some(GraphSchema::Edge(attrs)) => attrs,
+            _ => return Err(GraphQueryError::SchemaNotEdge(req.schema_id)),
+        };
+        if !edge_attrs.has_body {
+            return Err(GraphQueryError::SchemaRequiresEdgeBody(req.schema_id));
+        }
+
+        let ids = self.lookup_ids(req).await?;
+        let mut edges = Vec::new();
+        for id in ids {
+            let cell = match self.neb_client.read_cell(id).await {
+                Err(e) => return Err(internal_error(e)),
+                Ok(Err(ReadError::CellDoesNotExisted)) => continue,
+                Ok(Err(e)) => return Err(internal_error(e)),
+                Ok(Ok(cell)) => cell,
+            };
+
+            let (from_field, to_field, edge_type) = match edge_attrs.edge_type {
+                EdgeType::Directed => (
+                    DirectedEdge::edge_a_field(),
+                    DirectedEdge::edge_b_field(),
+                    EdgeType::Directed,
+                ),
+                EdgeType::Undirected => (
+                    UndirectedEdge::edge_a_field(),
+                    UndirectedEdge::edge_b_field(),
+                    EdgeType::Undirected,
+                ),
+            };
+
+            let body = match cell.data {
+                OwnedValue::Map(m) => m,
+                other => {
+                    return Err(GraphQueryError::InvalidEdgeCell(format!(
+                        "edge {id:?} body is not a map: {other:?}"
+                    )));
+                }
+            };
+
+            let (from_id, to_id) = match (body.get_by_key_id(from_field), body.get_by_key_id(to_field)) {
+                (&OwnedValue::Id(from), &OwnedValue::Id(to)) => (from, to),
+                (from, to) => {
+                    return Err(GraphQueryError::InvalidEdgeCell(format!(
+                        "edge {id:?} missing endpoint ids from fields {from_field}/{to_field}: {from:?}/{to:?}"
+                    )));
+                }
+            };
+
+            edges.push(GraphLookupEdge {
+                id,
+                from_id,
+                to_id,
+                schema_id: req.schema_id,
+                edge_type,
+                body,
+            });
+        }
+
+        Ok(edges)
+    }
+
     pub async fn lookup_explain_plan(
         &self,
         req: &GraphLookupExplainParams,
@@ -482,4 +569,100 @@ mod tests {
         assert!(out.contains(&ids[1]));
         assert!(out.contains(&ids[2]));
     }
+
+    async fn setup_edge_body_fixture(
+        port: u32,
+        group: &str,
+    ) -> (std::sync::Arc<crate::server::MorpheusServer>, u32, u32, Vec<Id>) {
+        let server = start_server(port, group).await.expect("server should start");
+        let graph: &GraphEngine = &server.graph;
+
+        let vertex_schema = MorpheusSchema::new("gq_vertex_for_edges", None, &EMPTY_FIELDS, true);
+        let edge_schema = MorpheusSchema::new(
+            "gq_edge_with_body",
+            None,
+            &vec![Field::new_indexed("weight", Type::U64, vec![IndexType::Hashed])],
+            false,
+        );
+        let vertex_schema_id = graph
+            .new_vertex_group(vertex_schema)
+            .await
+            .expect("vertex schema should be created");
+        let edge_schema_id = graph
+            .new_edge_group(edge_schema, EdgeAttributes::new(EdgeType::Directed, true))
+            .await
+            .expect("edge schema should be created");
+
+        let ids = vec![Id::new(0, 201), Id::new(0, 202), Id::new(0, 203)];
+        for id in ids.iter().copied() {
+            graph
+                .new_vertex_with_id(vertex_schema_id, id, OwnedMap::new())
+                .await
+                .expect("vertex create");
+        }
+
+        let mut body_a = OwnedMap::new();
+        body_a.insert("weight", OwnedValue::U64(7));
+        let body_a = Some(body_a);
+        graph
+            .link(ids[0], edge_schema_id, ids[1], &body_a)
+            .await
+            .expect("link tx 1")
+            .expect("link 1");
+
+        let mut body_b = OwnedMap::new();
+        body_b.insert("weight", OwnedValue::U64(9));
+        let body_b = Some(body_b);
+        graph
+            .link(ids[1], edge_schema_id, ids[2], &body_b)
+            .await
+            .expect("link tx 2")
+            .expect("link 2");
+
+        (server, vertex_schema_id, edge_schema_id, ids)
+    }
+
+    #[tokio::test]
+    async fn edge_lookup_supports_body_field_name_selection() {
+        let (server, _vertex_schema_id, edge_schema_id, ids) =
+            setup_edge_body_fixture(4045, "graph_query_edge_body_lookup").await;
+        let graph: &GraphEngine = &server.graph;
+
+        let params = GraphLookupParams {
+            schema_id: edge_schema_id,
+            selection: "(= weight 7u64)".to_string(),
+            ordering: None,
+            order_by_field: None,
+            limit: None,
+            offset: None,
+        };
+
+        let edges = graph.lookup_edges(&params).await.expect("edge lookup should succeed");
+        assert_eq!(edges.len(), 1);
+        assert_eq!(edges[0].from_id, ids[0]);
+        assert_eq!(edges[0].to_id, ids[1]);
+        assert!(matches!(edges[0].body.get("weight"), OwnedValue::U64(7)));
+    }
+
+    #[tokio::test]
+    async fn edge_lookup_rejects_non_body_edge_schema() {
+        let (server, _vertex_schema_id, edge_schema_id, _ids) =
+            setup_graph_fixture(4046, "graph_query_edge_non_body_reject", "score").await;
+        let graph: &GraphEngine = &server.graph;
+
+        let params = GraphLookupParams {
+            schema_id: edge_schema_id,
+            selection: "(= score 20u64)".to_string(),
+            ordering: None,
+            order_by_field: None,
+            limit: None,
+            offset: None,
+        };
+
+        let result = graph.lookup_edges(&params).await;
+        assert!(matches!(
+            result,
+            Err(crate::graph::query::GraphQueryError::SchemaRequiresEdgeBody(_))
+        ));
+    }
 }

src/http_gateway/graph_query.rs

@@ -11,6 +11,7 @@ use crate::graph::query::{
 use super::cell_id::id_to_base58;
 use super::cells::CellDto;
 use super::types::{ApiError, ApiResponse};
+use super::value::HttpMap;
 use super::HttpState;
 
 #[derive(Debug, Deserialize)]
@@ -131,6 +132,16 @@ pub struct GraphTraverseEdgeDto {
     pub edge_type: crate::graph::edge::EdgeType,
 }
 
+#[derive(Debug, Serialize)]
+pub struct GraphLookupEdgeDto {
+    pub cell_id: String,
+    pub from_id: String,
+    pub to_id: String,
+    pub schema_id: u32,
+    pub edge_type: crate::graph::edge::EdgeType,
+    pub body: HttpMap,
+}
+
 #[derive(Debug, Serialize)]
 pub struct QueryPlanExplainDto {
     pub disjunction: bool,
@@ -158,6 +169,17 @@ fn map_graph_query_error(err: GraphQueryError) -> ApiError {
         GraphQueryError::InvalidDirection(message) => {
             ApiError::bad_request("invalid_direction", message)
         }
+        GraphQueryError::SchemaNotEdge(schema_id) => ApiError::bad_request(
+            "schema_not_edge",
+            format!("schema {schema_id} is not an edge schema"),
+        ),
+        GraphQueryError::SchemaRequiresEdgeBody(schema_id) => ApiError::bad_request(
+            "edge_schema_body_required",
+            format!("edge schema {schema_id} has no body and cannot be queried by body fields"),
+        ),
+        GraphQueryError::InvalidEdgeCell(message) => {
+            ApiError::internal(format!("invalid edge cell: {message}"))
+        }
         GraphQueryError::EdgeSchemasRequired => ApiError::bad_request(
             "edge_schemas_required",
             "at least one edge schema is required".to_string(),
@@ -232,6 +254,31 @@ pub async fn lookup_vertices(
     Ok(Json(ApiResponse::ok(vertices)))
 }
 
+pub async fn lookup_edges(
+    State(state): State<HttpState>,
+    Json(req): Json<GraphLookupRequest>,
+) -> Result<Json<ApiResponse<Vec<GraphLookupEdgeDto>>>, ApiError> {
+    let params = to_lookup_params(&state, &req)?;
+    let edges = state
+        .server
+        .graph()
+        .lookup_edges(&params)
+        .await
+        .map_err(map_graph_query_error)?;
+    let data = edges
+        .into_iter()
+        .map(|edge| GraphLookupEdgeDto {
+            cell_id: id_to_base58(&edge.id),
+            from_id: id_to_base58(&edge.from_id),
+            to_id: id_to_base58(&edge.to_id),
+            schema_id: edge.schema_id,
+            edge_type: edge.edge_type,
+            body: HttpMap::from(edge.body),
+        })
+        .collect();
+    Ok(Json(ApiResponse::ok(data)))
+}
+
 pub async fn lookup_explain(
     State(state): State<HttpState>,
     Json(req): Json<GraphLookupExplainRequest>,

src/http_gateway/mod.rs

@@ -74,6 +74,10 @@ fn router(server: Arc<MorpheusServer>) -> Router {
             "/v1/graph/query/vertices/explain",
             axum::routing::post(graph_query::lookup_explain),
         )
+        .route(
+            "/v1/graph/query/edges",
+            axum::routing::post(graph_query::lookup_edges),
+        )
         .route(
             "/v1/graph/query/traverse",
             axum::routing::post(graph_query::traverse_from_lookup),