hamelin_lib 0.9.2

Core library for Hamelin query language
Documentation 
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139

//! Options structs for parsing, type-checking, and translation pipelines.
//!
//! All Hamelin options types live here. They are re-exported from
//! [`crate::tree::ast`] and the crate root so existing import paths continue to work.
//!
//! Use `bon::Builder` to construct options, then pass them to the corresponding
//! function (e.g., [`crate::parse_with_options`], [`crate::type_check_with_options`]).

use std::sync::Arc;

use crate::func::def::FunctionTranslationContext;
use crate::func::registry::FunctionRegistry;
use crate::interner::Interner;
use crate::provider::{EnvironmentProvider, NoOpProvider};
use crate::tree::ast::expression::Expression;
use crate::tree::ast::identifier::Identifier;
use crate::tree::typed_ast::environment::TypeEnvironment;

// ---------------------------------------------------------------------------
// ParseOptions
// ---------------------------------------------------------------------------

/// Options for configuring how AST nodes are parsed.
#[derive(bon::Builder, Default)]
pub struct ParseOptions {
    /// String interner for memory-efficient identifier storage.
    ///
    /// When set, all identifier strings go through the interner,
    /// deduplicating identical strings to share the same allocation.
    pub interner: Option<Arc<Interner>>,
}

// ---------------------------------------------------------------------------
// TypeCheckOptions
// ---------------------------------------------------------------------------

/// Options for type-checking a parsed AST or a Hamelin query string.
///
/// Used by both [`crate::type_check_with_options`] and
/// [`crate::parse_and_typecheck_with_options`].
#[derive(bon::Builder, Clone)]
pub struct TypeCheckOptions {
    /// Custom function registry.
    #[builder(default = Arc::new(FunctionRegistry::default()))]
    pub registry: Arc<FunctionRegistry>,

    /// Environment provider for table schema lookups.
    #[builder(default = Arc::new(NoOpProvider::default()) as Arc<dyn EnvironmentProvider>)]
    pub provider: Arc<dyn EnvironmentProvider>,

    /// String interner shared across parse and type-check passes.
    pub interner: Option<Arc<Interner>>,

    /// Time range expression to inject after FROM commands.
    pub time_range: Option<Arc<Expression>>,

    /// Timestamp field used by `WITHIN` and time range filtering.
    /// Defaults to `"timestamp"` when not set.
    pub timestamp_field: Option<Identifier>,

    /// Message field used by `PARSE` and similar commands.
    /// Defaults to `"event.original"` when not set.
    pub message_field: Option<Identifier>,
}

impl Default for TypeCheckOptions {
    fn default() -> Self {
        Self {
            registry: Arc::new(FunctionRegistry::default()),
            provider: Arc::new(NoOpProvider::default()),
            interner: None,
            time_range: None,
            timestamp_field: None,
            message_field: None,
        }
    }
}

// ---------------------------------------------------------------------------
// ExpressionTypeCheckOptions
// ---------------------------------------------------------------------------

/// Options for type-checking Expression AST nodes.
///
/// Unlike Query/Pipeline options which take an `EnvironmentProvider`, expression options
/// take `bindings` (the already-resolved environment at the expression's location) and
/// `fctx` (function translation context for window functions, etc).
#[derive(bon::Builder, Default)]
pub struct ExpressionTypeCheckOptions {
    /// Custom function registry.
    #[builder(default = Arc::new(FunctionRegistry::default()))]
    pub registry: Arc<FunctionRegistry>,

    /// Environment bindings (available fields/variables).
    #[builder(default)]
    pub bindings: Arc<TypeEnvironment>,

    /// Function translation context (for window functions, etc.).
    #[builder(default)]
    pub fctx: FunctionTranslationContext,

    /// String interner for deduplication.
    pub interner: Option<Arc<Interner>>,
}

// ---------------------------------------------------------------------------
// TranslateOptions
// ---------------------------------------------------------------------------

/// Options for translating a type-checked AST to a backend-specific representation.
///
/// This struct is shared across all backends (Trino, DataFusion, etc.).
#[derive(bon::Builder)]
pub struct TranslateOptions {
    /// Custom function registry for normalization's re-type-check pass.
    #[builder(default = Arc::new(FunctionRegistry::default()))]
    pub registry: Arc<FunctionRegistry>,

    /// Environment provider / catalog used during normalization.
    #[builder(default = Arc::new(NoOpProvider::default()) as Arc<dyn EnvironmentProvider>)]
    pub provider: Arc<dyn EnvironmentProvider>,

    /// Timestamp field used by `WITHIN` and time range filtering.
    pub timestamp_field: Option<Identifier>,

    /// Message field used by `PARSE` and similar commands.
    pub message_field: Option<Identifier>,
}

impl Default for TranslateOptions {
    fn default() -> Self {
        Self {
            registry: Arc::new(FunctionRegistry::default()),
            provider: Arc::new(NoOpProvider::default()),
            timestamp_field: None,
            message_field: None,
        }
    }
}