Skip to main content

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}