Skip to main content

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}