Skip to main content

uqa_execution/catalog/
graph_reads.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Attribute consumed graph catalog projections to the retained query participant.
8
9use super::CatalogReadView;
10use std::{borrow::Cow, sync::Arc};
11use uqa_core::CancellationToken;
12use uqa_graph::{GraphStore, GraphStoreError, GraphStoreHandle};
13use uqa_sql::SQLError;
14use uqa_storage::{
15    catalog::graph_observations::GraphDefinitionKind, mvcc::SerializableReadContext,
16    StorageBackendError,
17};
18
19pub(super) struct GraphCatalogRead {
20    template: GraphStoreHandle,
21    context: SerializableReadContext,
22    cancellation: CancellationToken,
23}
24
25fn graph_error(error: GraphStoreError) -> SQLError {
26    crate::storage_errors::storage_error(
27        "read graph catalog",
28        &StorageBackendError::backend("graph", error),
29    )
30}
31
32impl CatalogReadView {
33    pub(crate) fn metadata_view(&self) -> Cow<'_, Self> {
34        if self.graph_reads.is_none() {
35            return Cow::Borrowed(self);
36        }
37        let mut view = self.clone();
38        view.graph_reads = None;
39        Cow::Owned(view)
40    }
41
42    /// Retain the original participant independently from the catalog's immutable definitions. Binding alone records no reads.
43    pub fn with_graph_reads(
44        mut self,
45        template: GraphStoreHandle,
46        context: SerializableReadContext,
47        cancellation: &CancellationToken,
48    ) -> Self {
49        self.graph_reads = Some(Arc::new(GraphCatalogRead {
50            template: template.with_serializable_read(context.clone(), cancellation),
51            context,
52            cancellation: cancellation.clone(),
53        }));
54        self
55    }
56
57    fn graph_read(&self, name: &str) -> Result<Option<Cow<'_, GraphStoreHandle>>, SQLError> {
58        if let Some(read) = &self.graph_reads {
59            read.template
60                .observe_definition(GraphDefinitionKind::NamedGraph, Some(name))
61                .map_err(graph_error)?;
62        }
63        let store = if let Some(overlay) = &self.snapshot.graph_overlay {
64            overlay
65                .names
66                .contains(name)
67                .then(|| Cow::Owned(GraphStoreHandle::Persistent(overlay.store.as_ref().clone())))
68        } else {
69            self.snapshot
70                .definitions
71                .graphs
72                .get(name)
73                .map(|store| Cow::Borrowed(store.as_ref()))
74        };
75        Ok(
76            store.map(|store| match (&self.graph_reads, store.as_ref()) {
77                (Some(read), GraphStoreHandle::Persistent(store)) => Cow::Owned(
78                    GraphStoreHandle::Persistent(store.clone())
79                        .with_serializable_read(read.context.clone(), &read.cancellation),
80                ),
81                _ => store,
82            }),
83        )
84    }
85
86    /// Catalog row consumption observes the complete name set, including an empty result.
87    pub fn read_graph_names(&self) -> Result<Vec<String>, SQLError> {
88        self.observe_graph_names()?;
89        Ok(self.graph_names())
90    }
91
92    pub(super) fn observe_graph_names(&self) -> Result<(), SQLError> {
93        if let Some(read) = &self.graph_reads {
94            read.template
95                .observe_definition(GraphDefinitionKind::NamedGraph, None)
96                .map_err(graph_error)?;
97        }
98        Ok(())
99    }
100
101    pub fn graph_labels(
102        &self,
103        graph: &str,
104    ) -> Result<Option<Vec<uqa_graph::GraphLabelInfo>>, SQLError> {
105        self.graph_read(graph)?
106            .map(|store| store.graph_labels(graph))
107            .transpose()
108            .map_err(graph_error)
109    }
110
111    pub fn graph_label_kind(
112        &self,
113        graph: &str,
114        label: &str,
115    ) -> Result<Option<uqa_graph::LabelKind>, SQLError> {
116        self.graph_read(graph)?
117            .map(|store| store.graph_label_kind(graph, label))
118            .transpose()
119            .map(Option::flatten)
120            .map_err(graph_error)
121    }
122
123    /// Unobserved names for binding and restoration; row consumers use `read_graph_names`.
124    pub fn graph_names(&self) -> Vec<String> {
125        self.graph_names_iter().map(str::to_owned).collect()
126    }
127
128    pub fn contains_graph(&self, name: &str) -> bool {
129        self.snapshot.graph_overlay.as_ref().map_or_else(
130            || self.snapshot.definitions.graphs.contains_key(name),
131            |overlay| overlay.names.contains(name),
132        )
133    }
134
135    /// Borrow the selected namespace without producing graph handles or names.
136    pub fn graph_names_iter(&self) -> impl Iterator<Item = &str> {
137        self.snapshot
138            .graph_overlay
139            .as_ref()
140            .into_iter()
141            .flat_map(|overlay| overlay.names.iter().map(String::as_str))
142            .chain(
143                self.snapshot
144                    .graph_overlay
145                    .is_none()
146                    .then_some(&self.snapshot.definitions.graphs)
147                    .into_iter()
148                    .flat_map(|graphs| graphs.keys().map(String::as_str)),
149            )
150    }
151
152    pub fn graph_next_label_id(&self, graph: &str) -> Result<Option<u32>, SQLError> {
153        self.graph_read(graph)?
154            .map(|store| {
155                store
156                    .label_registry(graph)
157                    .map(|registry| registry.next_label_id)
158            })
159            .transpose()
160            .map_err(graph_error)
161    }
162
163    pub fn graph_label_count(
164        &self,
165        graph: &str,
166        label: &str,
167        kind: uqa_graph::LabelKind,
168    ) -> Result<Option<usize>, SQLError> {
169        self.graph_read(graph)?
170            .map(|store| match kind {
171                uqa_graph::LabelKind::Vertex => store
172                    .vertex_ids_by_label(label, graph)
173                    .map(|identities| identities.len()),
174                uqa_graph::LabelKind::Edge => store
175                    .edge_ids_by_label(label, graph)
176                    .map(|identities| identities.len()),
177            })
178            .transpose()
179            .map_err(graph_error)
180    }
181
182    pub fn graph_vertices(&self, graph: &str) -> Result<Option<Vec<uqa_core::Vertex>>, SQLError> {
183        self.graph_read(graph)?
184            .map(|store| store.vertices_in_graph(graph))
185            .transpose()
186            .map_err(graph_error)
187    }
188
189    pub fn graph_edges(&self, graph: &str) -> Result<Option<Vec<uqa_core::Edge>>, SQLError> {
190        self.graph_read(graph)?
191            .map(|store| store.edges_in_graph(graph))
192            .transpose()
193            .map_err(graph_error)
194    }
195}
196
197#[cfg(test)]
198mod tests {
199    use super::*;
200
201    #[test]
202    fn catalog_graph_reads_preserve_cancellation_resource_and_serialization_diagnostics() {
203        let memory = uqa_core::memory::MemoryBudget::new(0)
204            .reserve(1)
205            .unwrap_err();
206        for (error, state) in [
207            (
208                GraphStoreError::from(StorageBackendError::Cancelled(
209                    uqa_core::QueryCancelled::USER_REQUEST,
210                )),
211                "57014",
212            ),
213            (
214                GraphStoreError::from(StorageBackendError::Memory(memory)),
215                "53200",
216            ),
217            (
218                GraphStoreError::SerializationFailure("completed reader".into()),
219                "40001",
220            ),
221        ] {
222            assert_eq!(graph_error(error).sqlstate(), Some(state));
223        }
224    }
225}