polyglot_sql/
lib.rs

1//! Polyglot Core - SQL parsing and dialect translation library
2//!
3//! This library provides the core functionality for parsing SQL statements,
4//! building an abstract syntax tree (AST), and generating SQL in different dialects.
5//!
6//! # Architecture
7//!
8//! The library follows a pipeline architecture:
9//! 1. **Tokenizer** - Converts SQL string to token stream
10//! 2. **Parser** - Builds AST from tokens
11//! 3. **Generator** - Converts AST back to SQL string
12//!
13//! Each stage can be customized per dialect.
14
15pub mod ast_transforms;
16pub mod builder;
17pub mod dialects;
18pub mod diff;
19pub mod error;
20pub mod expressions;
21pub mod generator;
22pub mod helper;
23pub mod lineage;
24pub mod optimizer;
25pub mod parser;
26pub mod planner;
27pub mod resolver;
28pub mod schema;
29pub mod scope;
30pub mod time;
31pub mod tokens;
32pub mod transforms;
33pub mod traversal;
34pub mod trie;
35
36pub use dialects::{Dialect, DialectType, CustomDialectBuilder, unregister_custom_dialect};
37pub use error::{Error, Result, ValidationError, ValidationResult, ValidationSeverity};
38pub use expressions::Expression;
39pub use generator::Generator;
40pub use helper::{
41    csv, find_new_name, is_date_unit, is_float, is_int, is_iso_date, is_iso_datetime,
42    merge_ranges, name_sequence, seq_get, split_num_words, tsort, while_changing, DATE_UNITS,
43};
44pub use parser::Parser;
45pub use resolver::{is_column_ambiguous, resolve_column, Resolver, ResolverError, ResolverResult};
46pub use schema::{ensure_schema, from_simple_map, normalize_name, MappingSchema, Schema, SchemaError};
47pub use scope::{
48    build_scope, find_all_in_scope, find_in_scope, traverse_scope, walk_in_scope, ColumnRef, Scope,
49    ScopeType, SourceInfo,
50};
51pub use time::{format_time, is_valid_timezone, subsecond_precision, TIMEZONES};
52pub use tokens::{Token, TokenType, Tokenizer};
53pub use traversal::{
54    contains_aggregate, contains_subquery, contains_window_function, find_ancestor, find_parent,
55    get_columns, get_tables, is_aggregate, is_column, is_function, is_literal, is_select,
56    is_subquery, is_window_function, transform, transform_map, BfsIter, DfsIter, ExpressionWalk,
57    ParentInfo, TreeContext,
58    // Extended type predicates
59    is_insert, is_update, is_delete, is_union, is_intersect, is_except,
60    is_boolean, is_null_literal, is_star, is_identifier, is_table,
61    is_eq, is_neq, is_lt, is_lte, is_gt, is_gte, is_like, is_ilike,
62    is_add, is_sub, is_mul, is_div, is_mod, is_concat,
63    is_and, is_or, is_not,
64    is_in, is_between, is_is_null, is_exists,
65    is_count, is_sum, is_avg, is_min_func, is_max_func, is_coalesce, is_null_if,
66    is_cast, is_try_cast, is_safe_cast, is_case,
67    is_from, is_join, is_where, is_group_by, is_having, is_order_by, is_limit, is_offset,
68    is_with, is_cte, is_alias, is_paren, is_ordered,
69    is_create_table, is_drop_table, is_alter_table, is_create_index, is_drop_index,
70    is_create_view, is_drop_view,
71    // Composite predicates
72    is_query, is_set_operation, is_comparison, is_arithmetic, is_logical, is_ddl,
73};
74pub use ast_transforms::{
75    add_select_columns, remove_select_columns, set_distinct,
76    add_where, remove_where,
77    set_limit, set_offset, remove_limit_offset,
78    rename_columns, rename_tables, qualify_columns,
79    replace_nodes, replace_by_type, remove_nodes,
80    get_column_names, get_table_names, get_identifiers, get_functions, get_literals,
81    get_subqueries, get_aggregate_functions, get_window_functions, node_count,
82};
83pub use trie::{new_trie, new_trie_from_keys, Trie, TrieResult};
84pub use optimizer::{annotate_types, TypeAnnotator, TypeCoercionClass};
85
86/// Transpile SQL from one dialect to another.
87///
88/// # Arguments
89/// * `sql` - The SQL string to transpile
90/// * `read` - The source dialect to parse with
91/// * `write` - The target dialect to generate
92///
93/// # Returns
94/// A vector of transpiled SQL statements
95///
96/// # Example
97/// ```
98/// use polyglot_sql::{transpile, DialectType};
99///
100/// let result = transpile(
101///     "SELECT EPOCH_MS(1618088028295)",
102///     DialectType::DuckDB,
103///     DialectType::Hive
104/// );
105/// ```
106pub fn transpile(sql: &str, read: DialectType, write: DialectType) -> Result<Vec<String>> {
107    let read_dialect = Dialect::get(read);
108    let write_dialect = Dialect::get(write);
109
110    let expressions = read_dialect.parse(sql)?;
111
112    expressions
113        .into_iter()
114        .map(|expr| {
115            let transformed = write_dialect.transform(expr)?;
116            write_dialect.generate(&transformed)
117        })
118        .collect()
119}
120
121/// Parse SQL into an AST.
122///
123/// # Arguments
124/// * `sql` - The SQL string to parse
125/// * `dialect` - The dialect to use for parsing
126///
127/// # Returns
128/// A vector of parsed expressions
129pub fn parse(sql: &str, dialect: DialectType) -> Result<Vec<Expression>> {
130    let d = Dialect::get(dialect);
131    d.parse(sql)
132}
133
134/// Parse a single SQL statement.
135///
136/// # Arguments
137/// * `sql` - The SQL string containing a single statement
138/// * `dialect` - The dialect to use for parsing
139///
140/// # Returns
141/// The parsed expression, or an error if multiple statements found
142pub fn parse_one(sql: &str, dialect: DialectType) -> Result<Expression> {
143    let mut expressions = parse(sql, dialect)?;
144
145    if expressions.len() != 1 {
146        return Err(Error::Parse(format!(
147            "Expected 1 statement, found {}",
148            expressions.len()
149        )));
150    }
151
152    Ok(expressions.remove(0))
153}
154
155/// Generate SQL from an AST.
156///
157/// # Arguments
158/// * `expression` - The expression to generate SQL from
159/// * `dialect` - The target dialect
160///
161/// # Returns
162/// The generated SQL string
163pub fn generate(expression: &Expression, dialect: DialectType) -> Result<String> {
164    let d = Dialect::get(dialect);
165    d.generate(expression)
166}
167
168/// Validate SQL syntax.
169///
170/// # Arguments
171/// * `sql` - The SQL string to validate
172/// * `dialect` - The dialect to use for validation
173///
174/// # Returns
175/// A validation result with any errors found
176pub fn validate(sql: &str, dialect: DialectType) -> ValidationResult {
177    let d = Dialect::get(dialect);
178    match d.parse(sql) {
179        Ok(expressions) => {
180            // Reject bare expressions that aren't valid SQL statements.
181            // The parser accepts any expression at the top level, but bare identifiers,
182            // literals, function calls, etc. are not valid statements.
183            for expr in &expressions {
184                if !expr.is_statement() {
185                    let msg = format!("Invalid expression / Unexpected token");
186                    return ValidationResult::with_errors(vec![
187                        ValidationError::error(msg, "E004"),
188                    ]);
189                }
190            }
191            ValidationResult::success()
192        }
193        Err(e) => {
194            let error = match &e {
195                Error::Syntax {
196                    message,
197                    line,
198                    column,
199                } => ValidationError::error(message.clone(), "E001").with_location(*line, *column),
200                Error::Tokenize {
201                    message,
202                    line,
203                    column,
204                } => ValidationError::error(message.clone(), "E002").with_location(*line, *column),
205                Error::Parse(msg) => ValidationError::error(msg.clone(), "E003"),
206                _ => ValidationError::error(e.to_string(), "E000"),
207            };
208            ValidationResult::with_errors(vec![error])
209        }
210    }
211}
212
213/// Transpile SQL from one dialect to another, using string dialect names.
214///
215/// This supports both built-in dialect names (e.g., "postgresql", "mysql") and
216/// custom dialects registered via [`CustomDialectBuilder`].
217///
218/// # Arguments
219/// * `sql` - The SQL string to transpile
220/// * `read` - The source dialect name
221/// * `write` - The target dialect name
222///
223/// # Returns
224/// A vector of transpiled SQL statements, or an error if a dialect name is unknown.
225pub fn transpile_by_name(sql: &str, read: &str, write: &str) -> Result<Vec<String>> {
226    let read_dialect = Dialect::get_by_name(read)
227        .ok_or_else(|| Error::parse(format!("Unknown dialect: {}", read)))?;
228    let write_dialect = Dialect::get_by_name(write)
229        .ok_or_else(|| Error::parse(format!("Unknown dialect: {}", write)))?;
230
231    let expressions = read_dialect.parse(sql)?;
232
233    expressions
234        .into_iter()
235        .map(|expr| {
236            let transformed = write_dialect.transform(expr)?;
237            write_dialect.generate(&transformed)
238        })
239        .collect()
240}
241
242/// Parse SQL into an AST using a string dialect name.
243///
244/// Supports both built-in and custom dialect names.
245pub fn parse_by_name(sql: &str, dialect: &str) -> Result<Vec<Expression>> {
246    let d = Dialect::get_by_name(dialect)
247        .ok_or_else(|| Error::parse(format!("Unknown dialect: {}", dialect)))?;
248    d.parse(sql)
249}
250
251/// Generate SQL from an AST using a string dialect name.
252///
253/// Supports both built-in and custom dialect names.
254pub fn generate_by_name(expression: &Expression, dialect: &str) -> Result<String> {
255    let d = Dialect::get_by_name(dialect)
256        .ok_or_else(|| Error::parse(format!("Unknown dialect: {}", dialect)))?;
257    d.generate(expression)
258}
polyglot_sql/lib.rs

polyglot_sql/
lib.rs
