surrealdb_gql/lib.rs
1//! The GQL dialect of SurrealQL.
2//!
3//! Lexer, parser and AST for GQL queries, and the lowering that turns a
4//! parsed query into a `PreparedGqlQuery` — the `LogicalOp::Match` operator
5//! the engine runs, whose scalars are the logical plan's
6//! `LogicalExpr`.
7//!
8//! This crate is an internal implementation detail of SurrealDB: its API is
9//! unstable and changes without notice. Depend on the `surrealdb` SDK or
10//! `surrealdb-core` instead.
11
12pub mod ast;
13pub mod lexer;
14pub mod lower;
15pub mod parser;
16pub mod token;
17
18// The module tree spells intra-layer paths as `crate::gql::<name>` and names
19// its neighbours as `crate::<layer>`; these aliases keep those paths valid.
20pub use surrealdb_expr::{expr, val};
21
22pub use self::lower::PreparedGqlQuery;
23
24pub(crate) mod gql {
25 //! Self-alias so `crate::gql::` paths written inside the module tree
26 //! resolve against the crate root.
27 pub(crate) use crate::*;
28}
29
30impl Default for GqlParserSettings {
31 fn default() -> Self {
32 GqlParserSettings {
33 object_recursion_limit: 100,
34 expr_recursion_limit: 128,
35 }
36 }
37}
38use parse_common::error::SyntaxError;
39use parse_common::span::Span;
40use parse_common::syntax_error;
41
42/// Settings which control the behaviour of the GQL parser.
43#[derive(Clone, Debug)]
44pub struct GqlParserSettings {
45 /// Disallow a query to have objects/expressions nested deeper than the
46 /// limit. Lists and property maps count towards this limit.
47 pub object_recursion_limit: usize,
48 /// Bounds the depth of the expression operator tree, including flat
49 /// left-associative spines (`1 + 1 + 1 + …`) and prefix chains, which
50 /// are otherwise unbounded and overflow the call stack when the lowered
51 /// `LogicalExpr` tree is later walked recursively (dropped, formatted or
52 /// compiled). Mirrors
53 /// [`GqlParserSettings::expr_recursion_limit`].
54 pub expr_recursion_limit: usize,
55}
56
57/// Parses a GQL query with the default parser settings.
58pub fn parse_str(input: &str) -> Result<ast::GqlQuery, SyntaxError> {
59 parse_with_settings(input, GqlParserSettings::default())
60}
61
62/// Parses a GQL query with the given parser settings.
63///
64/// During parsing the nesting depth of expressions counts against the limit
65/// in the settings; exceeding it is a parse error rather than unbounded
66/// recursion.
67pub fn parse_with_settings(
68 input: &str,
69 settings: GqlParserSettings,
70) -> Result<ast::GqlQuery, SyntaxError> {
71 // `parse_with_capabilities` rejects oversized input with the dedicated
72 // `ParseError::QueryTooLarge` (mirroring `syn`); this guard keeps the `u32`
73 // span arithmetic safe for direct callers of the raw parser API.
74 if input.len() > u32::MAX as usize {
75 return Err(syntax_error!(
76 "Cannot parse query, the query exceeded the maximum size of 4GB",
77 @Span::empty()
78 ));
79 }
80 let mut parser = parser::Parser::new_with_settings(input, settings);
81 parser.parse_query()
82}
83
84/// Lowers a parsed GQL query into a [`PreparedGqlQuery`] (the declarative
85/// [`MatchPlan`](crate::expr::match_plan::MatchPlan) carried by a
86/// `LogicalOp::Match`; `doc/gql/V2_DESIGN.md` §8).
87///
88/// The returned plan executes through the engine; no
89/// SurrealQL surface AST is generated.
90pub fn lower(query: ast::GqlQuery) -> Result<PreparedGqlQuery, SyntaxError> {
91 Ok(PreparedGqlQuery(lower::lower(query)?))
92}
93
94/// Parses a GQL query and lowers it into a [`PreparedGqlQuery`], with the given
95/// parser settings.
96pub fn parse_to_plan_with_settings(
97 input: &str,
98 settings: GqlParserSettings,
99) -> Result<PreparedGqlQuery, SyntaxError> {
100 let query = parse_with_settings(input, settings)?;
101 lower(query)
102}