polars_cypher/lib.rs
1// Copyright 2026 c-fraser
2//
3// Licensed under the Apache License, Version 2.0 (the "License");
4// you may not use this file except in compliance with the License.
5// You may obtain a copy of the License at
6//
7// http://www.apache.org/licenses/LICENSE-2.0
8//
9// Unless required by applicable law or agreed to in writing, software
10// distributed under the License is distributed on an "AS IS" BASIS,
11// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
12// See the License for the specific language governing permissions and
13// limitations under the License.
14
15//! # polars-cypher
16//!
17//! Run [Cypher](https://neo4j.com/docs/cypher-manual/current/) queries on a property [`Graph`]
18//! stored as [Parquet](https://parquet.apache.org/), using [Polars](https://docs.pola.rs/).
19//!
20//! A graph is written with a [`GraphWriter`], or exported from *Neo4j* with [`Export`] (behind
21//! the `neo4j` feature). [`Graph::query`] then plans a query as a *Polars* `LazyFrame`, to
22//! collect or compose further.
23//!
24//! ```rust,no_run
25//! use polars_cypher::Graph;
26//!
27//! # fn main() -> Result<(), polars_cypher::Error> {
28//! let graph = Graph::open("graph/")?;
29//! let lf = graph
30//! .query("MATCH (p:Person) WHERE p.born < $year RETURN p.name")
31//! .parameter("year", 1970)
32//! .lazy()?;
33//! # Ok(())
34//! # }
35//! ```
36//!
37//! ## Cypher
38//!
39//! Queries are read-only, of the form `MATCH ... [WHERE ...] RETURN ...`, supporting:
40//!
41//! - One or more comma-separated patterns, with node labels, relationship directions and types
42//! (`:A|B`), and inline property maps
43//! - Comparisons, arithmetic, `AND`/`OR`/`NOT`/`XOR`, `IS [NOT] NULL`, `IN [...]`, and
44//! `STARTS WITH`/`ENDS WITH`/`CONTAINS`
45//! - Parameters (`$x`), bound with [`QueryBuilder::parameter`]
46//! - `RETURN` with aliases, `DISTINCT`, `ORDER BY`, `SKIP`, and `LIMIT`
47//! - Aggregations (`count`, `sum`, `avg`, `min`, `max`, `collect`) with implicit grouping
48//! - Functions `id`, `labels`, `type`, `coalesce`, `toUpper`, `toLower`, `size`, and `abs`
49//!
50//! Variable-length relationships, `OPTIONAL MATCH`, `WITH`, `UNWIND`, and `CASE` aren't
51//! supported yet.
52//!
53#![cfg_attr(feature = "neo4j", doc = "[`Export`]: Export")]
54#![cfg_attr(
55 not(feature = "neo4j"),
56 doc = "[`Export`]: https://docs.rs/polars-cypher/latest/polars_cypher/struct.Export.html"
57)]
58
59use std::error::Error as StdError;
60use std::fmt;
61
62mod cypher;
63mod layout;
64#[cfg(feature = "neo4j")]
65mod neo4j;
66mod plan;
67mod query;
68
69pub use layout::{
70 Graph, GraphWriter, Manifest, NodeId, NodeTable, Properties, PropertySchema, PropertyType,
71 RelTable, Value,
72};
73#[cfg(feature = "neo4j")]
74pub use neo4j::Export;
75pub use query::{BoundParameter, QueryBuilder};
76
77/// A failure writing, opening, or querying a graph, with the underlying error as its
78/// [`source`](StdError::source) when there is one.
79#[derive(Debug)]
80pub struct Error {
81 message: String,
82 source: Option<Box<dyn StdError + Send + Sync>>,
83}
84
85impl Error {
86 pub(crate) fn new(message: impl Into<String>) -> Self {
87 Self {
88 message: message.into(),
89 source: None,
90 }
91 }
92
93 pub(crate) fn wrap(
94 message: impl Into<String>,
95 source: impl StdError + Send + Sync + 'static,
96 ) -> Self {
97 Self {
98 message: message.into(),
99 source: Some(Box::new(source)),
100 }
101 }
102}
103
104impl fmt::Display for Error {
105 fn fmt(&self, f: &mut fmt::Formatter<'_>) -> fmt::Result {
106 write!(f, "{}", self.message)
107 }
108}
109
110impl StdError for Error {
111 fn source(&self) -> Option<&(dyn StdError + 'static)> {
112 self.source
113 .as_ref()
114 .map(|e| e.as_ref() as &(dyn StdError + 'static))
115 }
116}