Skip to main content

uqa_execution/query/
routine_invocation.rs

1//
2// Unified Query Algebra
3//
4// Copyright (c) 2023-2026 Cognica, Inc.
5//
6
7//! Invocation services for compiled SQL routines.
8
9use crate::functions::SQLTableFunctionResult;
10use crate::routines::invocation::RoutineProjectionResult;
11use uqa_core::Value;
12use uqa_sql::{ast::FunctionBinding, routines::SQLUserFunction, SQLError};
13
14/// Execute a routine through the caller's transaction and session context.
15pub trait SQLRoutineInvoker {
16    fn has_user_function(
17        &self,
18        name: &str,
19        binding: Option<&FunctionBinding>,
20    ) -> Result<bool, SQLError>;
21    /// Reuse successful metadata only when the adapter validates its current scope.
22    fn has_user_function_with_descriptions(
23        &self,
24        name: &str,
25        binding: Option<&FunctionBinding>,
26        _descriptions: &uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions,
27    ) -> Result<bool, SQLError> {
28        self.has_user_function(name, binding)
29    }
30    fn user_function_returns_set(
31        &self,
32        name: &str,
33        binding: Option<&FunctionBinding>,
34        arguments: &[(Option<String>, Value)],
35    ) -> Option<Result<bool, SQLError>>;
36    fn call_user_scalar_function(
37        &self,
38        name: &str,
39        binding: Option<&FunctionBinding>,
40        arguments: &[(Option<String>, Value)],
41    ) -> Option<Result<Value, SQLError>>;
42    fn call_user_table_function(
43        &self,
44        name: &str,
45        binding: Option<&FunctionBinding>,
46        arguments: &[(Option<String>, Value)],
47    ) -> Option<Result<SQLTableFunctionResult, SQLError>>;
48    /// Native adapters can resolve and execute one invocation. External adapters
49    /// retain their existing classification, callbacks and disappearing-call errors.
50    fn invoke_projection_function(
51        &self,
52        name: &str,
53        binding: Option<&FunctionBinding>,
54        arguments: &[(Option<String>, Value)],
55        _descriptions: &uqa_sql::routines::invocation::descriptions::RoutineCallDescriptions,
56    ) -> crate::ExecResult<RoutineProjectionResult> {
57        let missing = |kind: &str| {
58            crate::ExecError::Other(format!(
59                "user function `{name}` disappeared during {kind}projection"
60            ))
61        };
62        let returns_set = self
63            .user_function_returns_set(name, binding, arguments)
64            .ok_or_else(|| missing(""))??;
65        if returns_set {
66            self.call_user_table_function(name, binding, arguments)
67                .ok_or_else(|| missing("set "))?
68                .map(RoutineProjectionResult::Table)
69                .map_err(Into::into)
70        } else {
71            self.call_user_scalar_function(name, binding, arguments)
72                .ok_or_else(|| missing("scalar "))?
73                .map(RoutineProjectionResult::Scalar)
74                .map_err(Into::into)
75        }
76    }
77    /// Enforce EXECUTE on a user routine that a FROM item calls, as `PostgreSQL` checks it when it initializes the scan, before the routine runs for any row.
78    fn require_user_function_execute(&self, function: &SQLUserFunction) -> Result<(), SQLError>;
79}