Skip to content

SQLRec Architecture ​

SQLRec compiles and schedules SQL recommendation flows within the JVM, using UDFs for custom computation, Connectors for storage access, and HTTP for model inference. This page covers compilation, scheduling, state isolation, and external access.

Core Components ​

text
                        ┌──────────────────────────────────────────┐
                        │             sqlrec-frontend              │
                        │         Thrift / REST / CLI / UI         │
                        └───────────────┬──────────────────────────┘
                                        │ calls
                        ┌───────────────▼──────────────────────────┐
                        │               sqlrec-core                │
                        │ statement routing / Calcite compilation  │
                        │  function execution / metadata / models  │
                        └──┬───────────────┬───────────────┬───────┘
                           │               │               │
              ┌────────────▼───┐   ┌───────▼──────┐  ┌─────▼────────┐
              │  sqlrec-sql-   │   │ sqlrec-model │  │  sqlrec-udf  │
              │     parser     │   │    model     │  │   built-in   │
              │  two parsers   │   │   backends   │  │  functions   │
              └────────────────┘   └──────────────┘  └──────────────┘
                           │               │               │
                        ┌──▼───────────────▼───────────────▼───────┐
                        │              sqlrec-common               │
                        │  table abstractions / context / config   │
                        └───────────────┬──────────────────────────┘
                                        │ runtime SPI discovery
                        ┌───────────────▼──────────────────────────┐
                        │            sqlrec-connectors             │
                        │    Redis / JDBC / MongoDB / Milvus /     │
                        │            Kafka / filesystem            │
                        └──────────────────────────────────────────┘

Arrows show module collaboration and runtime SPI discovery, rather than Maven dependencies. Connectors implement interfaces from sqlrec-common.

LayerMain implementationResponsibility
Service entry pointssqlrec-frontendHTTP, Thrift/JDBC, CLI, UI, session management
SQL compilationsqlrec-sql-parser, the compiler package in sqlrec-coreParsing, query compilation, function compilation
Flow runtimeThe runtime package in sqlrec-coreDAG scheduling, variables, returns, timeouts, cancellation
Data and function adapterssqlrec-connectors, sqlrec-udfStorage operators, scalar and table functions
Metadata and model managementThe db and model packages in sqlrec-core, sqlrec-modelDefinitions and caches, model tasks, inference services
Shared interfacessqlrec-commonTable schemas, contexts, extension contracts
Execution levelWhat it determinesImplementation
SQL-function DAGDependencies and parallel execution across statementsSQLRec execution nodes and scheduler
Relational plan for one SQL statementScans, filters, joins, sorting, and other operationsCalcite + SQLRec storage operators

Request Entry Points and Execution Paths ​

HTTP Recommendation API ​

text
HTTP request
  → Netty I/O: decode
  → HttpServerHandler: handle on business threads
  → RestFunctionExecutor: resolve API and compiled function
  → Create root schema; bind input CacheTables and execution variables
  → SqlFunctionBindable: execute the function DAG
  → Materialize RETURN result → JSON response

Process-wide: API mappings, compiled function plans
Per request: input tables, intermediate tables, execution variables
StepKey implementation
Separate network and business threadsRestServer uses Netty I/O threads and a separate business executor group; node concurrency uses the engine executor
API → functionSqlApiCache holds name mappings; CompileManager / SqlFunctionCache retrieves compiled functions
Bind request dataCalciteSchemaFactory creates the root schema; JSON rows become input tables, and params populate ExecuteContextImpl

SQL Entry Points and Statement Dispatch ​

CLI, REST SQL, and Thrift sessions dispatch through SqlExecutor:

Statement categoryExecution path
SQL-function definitionCollect inputs and body, compile, and save the definition
Local queries, writes, and control statementsCompileManager → execution node → bind
Metadata-only DDL for databases, tables, and Java UDFsMetadata adapters; remote mode writes HMS through HiveCatalog
SHOW, DESCRIBERead metadata or session cache tables
Model, checkpoint, and Service commandsResource managers; submit external tasks when needed
Forwardable remote statementsRemote-mode Thrift session → Flink SQL Gateway

Remote routing is considered only when local handling produces no result. Local compilation or execution errors return directly, without a Gateway retry.

SQL Parsing and Compilation ​

text
One SQL statement · NormalSqlCompiler
  Parse and validate → Relational expressions → Optimize plan
    → Enumerable code generation → CalciteBindable

SQL function · FunctionCompiler
  Register schema placeholders → Compile each node → Check RETURN schema
    → Build dependency DAG → SqlFunctionBindable

Parsing and Local Execution Checks ​

StageImplementation and checks
Parse standard SQLSqlRecSqlParser first tries Flink parsing
Parse extensionsSeparate SQLRec grammar handles CACHE TABLE, function calls, model management, and other extensions
Check local capabilitySqlTypeChecker checks statement types and table adapters; CTEs currently bypass the local query path

Parsing, metadata persistence, and local execution are checked at separate stages.

One SQL Statement: From Relational Plan to Executable Code ​

StepKey implementation and output
Name and type validationResolve table schemas and function signatures from the current schema
Plan optimizationVolcanoPlanner applies Calcite rules and SQLRec rules for KV joins, vector joins, writes, and UNION
Code generationConvert to an Enumerable plan; EnumerableInterpretable.toBindable() compiles an executable object within the JVM
Execution and materializationCalciteBindable binds the schema, variables, and parameters through SqlRecDataContextImpl, materializing results as row arrays
DiagnosticsRetain logical plans, physical plans, and generated code for the UI

SQL Functions: Build Schemas and Nodes at Compile Time ​

After compiling input declarations and cache-table statements, FunctionCompiler registers CacheTable placeholders with schemas but no request data, allowing later statements to validate. The top-level RETURN completes return-schema checks and DAG initialization.

Execution nodeRole
CalciteBindableLocal query or write
CacheTableBindableExecute a child node and publish a named result table
CallSqlFunctionBindable / JavaFunctionBindableSQL subfunction / Java evaluate call
IfBindable / ReturnBindableBranch / return
SqlFunctionBindableNodes, schemas, and dependencies for the whole function

Functions are compiled and validated when defined and may be recompiled when metadata loads. SqlFunctionCache reuses compiled results within the process; remote mode recompiles according to refresh policies.

Call formTarget binding and schema handling
Static SQL subfunctionBind at compile time and obtain its return schema; check compatibility when LIKE is present
Dynamic callFunctionProxyBindable resolves the function name at runtime; LIKE declares the schema at compile time

UDF Registration and Execution ​

Java UDFs include scalar functions embedded in SQL expressions and table functions that process whole tables through CALL. SQL subfunctions are compiled by FunctionCompiler as described above.

Registration and Execution Paths ​

text
Function name → Java class name
  ├── Built-in: FunctionConfigs
  └── Custom: CREATE FUNCTION → Metadata
                       ↓ Load from the runtime classpath
Scalar function
  HmsSchema → UdfManager → SqlRecScalarFunctionImpl
    → Calcite type checking, overload resolution, and code generation
    → SQL expression result

Java table function
  CALL → FunctionBindableFactory → JavaFunctionUtils
    → JavaFunctionBindable → Inject arguments and invoke evaluate reflectively
    → CacheTable rows → Subsequent DAG nodes
TypeIntegrationComputation and use
Scalar functionAdapt public evaluate methods as Calcite ScalarFunction implementationsCompute row values in expressions, such as l2_norm and array_contains
Java table functionJavaFunctionBindable wraps an execution node and selects an evaluate overload from static argument typesBatch processing of CacheTable inputs, literals, or variables, such as dedup, weighted_merge, and call_service

Registration stores only the name-to-class mapping. Deploy the JAR and its dependencies on each SQLRec process's classpath beforehand; UDFs execute within the SQLRec JVM.

Compile-Time Contracts and Runtime State ​

MechanismImplementation and limits
Scalar-function contextSqlRecCallNotNullImplementor injects DataContext into generated calls without consuming an explicit SQL argument
Scalar-function determinismRead the deterministic / stateful flags from @UDFType and propagate them to Calcite to prevent constant folding of nondeterministic calls
Table-function return schemaLIKE supplies the compile-time contract; without it, functions returning CacheTable run at compile time by default to infer fields. ENABLE_JAVA_FUNCTION_SCHEMA_INFERENCE=false disables this behavior
Table-function contextAutomatically inject ReadonlyContext / ExecuteContext at runtime; a writable context makes the node nonparallel, as described in the next section
Table-function resultsMaterialize returned CacheTable rows and adapt them to the compiled fields; operations with no result may return Void and provide no result table
Instance stateJavaFunctionBindable holds the UDF instance, which may be reused across requests with the compiled plan; pass request state through arguments and contexts

Use explicit LIKE for table functions that access the network or have side effects. See Custom UDFs for implementation and deployment, and CALL for syntax.

DAG Scheduling and Runtime Contexts ​

Building Dependencies ​

TopologicalSortUtils reads each node's getReadTables(), getWriteTables(), and parallelism declaration in statement order:

ConstraintDependency
RAW: later read depends on earlier writeWait for the table to be produced or updated
WAR: later write depends on earlier readFinish reading before overwriting
WAW: later write depends on earlier writePreserve write order for the same table
Execution barrierWait for earlier nodes; later nodes wait for the barrier

RETURN and nonparallel nodes form barriers, including SET, ASSERT, and Java table functions declaring writable ExecuteContext. Using only ReadonlyContext does not impose this restriction. The graph undergoes topological sorting and redundant-edge removal; arbitrary external side effects inside Java UDFs are not inferred.

This function-body fragment assumes the subfunctions are defined, both recall paths return the same schema, have no additional shared writes, and allow parallel execution.

sql
CACHE TABLE interest AS CALL interest_recall(user_info);
CACHE TABLE hot AS CALL hot_recall(user_info);
CACHE TABLE candidates AS
SELECT * FROM interest UNION ALL SELECT * FROM hot;
CACHE TABLE ranked AS CALL rank_items(candidates);
RETURN ranked;
text
interest_recall → interest ─┐
                           ├→ UNION ALL → candidates → rank_items → ranked → RETURN
hot_recall ─────→ hot ──────┘

Recall paths run in parallel; merging waits for both, ranking waits for merging,
and RETURN forms an execution barrier.

SQL-subfunction read/write information maps back to the caller for outer dependency analysis. Rewriting a cache table also waits for earlier reads to finish.

Parallelism, Partitioning, and Async Calls ​

ModeImplementationResults and limits
DAG parallelismSqlFunctionBindable waits for dependencies with CompletableFuture, then submits nodesExecutorServiceUtils uses a virtual thread per task; disabling PARALLELISM_EXEC runs nodes sequentially
Partitioned callsPartitionExecutor splits inputs and creates a schema per partitionExecute targets concurrently, then merge results
ASYNCSubmit a background call and return immediatelyNo synchronous result for the current CACHE TABLE / RETURN

This concurrency runs within the SQLRec process; it does not submit a distributed job for each node.

Shared Plans, Isolated Data, and Function Returns ​

text
Process-wide resources
├── Compiled function plans
├── Database HmsSchema objects
└── Connector table objects
        ↑ Reuse
        ├── Request A (independent state)
        │   ├── Root schema: input and intermediate tables
        │   ├── Variable map ←→ Shared with SQL subfunctions
        │   └── SQL subfunction: own schema, local tables, return frame
        └── Request B (independent state, same structure)

Cancellation state: parent context → child context
ImplementationState handling
CallSqlFunctionBindableCheck argument/parameter schemas and bind by position in a new schema; local tables remain hidden from the caller
ExecuteContextImplManage variables, call stacks, Trace, cancellation, and return frames; subfunctions share the variable map but have separate return frames
CacheTableBindableFully materialize results → check cancellation → publish to the current schema; later nodes reuse results by table name

Table-scope isolation does not copy variables. Query results and intermediate tables primarily reside in memory and are constrained by JVM memory.

Failures, Timeouts, and Result Publication ​

LevelImplementation and handling
NodeProxyAllBindable handles timeouts, cancellation checks, Trace, duration, row counts, and merge-branch fallback
DAGUnrecovered errors end waiting early and cancel the current function scope; child contexts observe cancellation through the parent chain, and tasks exit cooperatively
TIMEINIfBindable executes THEN in a child context; failure or timeout cancels it and runs ELSE, preventing late cache or return values from overwriting fallback results
PartitionFail the whole call or discard failed partitions and merge the rest, depending on configuration

Cancellation does not guarantee immediate termination of network requests. Completed external writes have no unified rollback across Connectors. See Exception Recovery and Observability.

Metadata, Table Objects, and Storage Execution ​

Metadata Management ​

MetadataAccess separates schema definitions, resource records, and model-file access. MetadataAccessFactory selects the implementation based on SQL_SCHEMA_DIR.

ModeSchema definitionsResources and files
RemoteHmsSchemaAccess → HMS; DDL through HiveCatalogDbStoreAccess → PostgreSQL; file access through Hadoop interfaces
Local filesSqlFileParser → SqlFileSchemaAccessInMemoryStoreAccess; Services may point to existing endpoints
ObjectReuse and updates
Root schemaCreated by CalciteSchemaFactory for each executor
Database HmsSchemaReused within the process, loading tables and functions in both metadata modes
Connector TableCreated from table definitions through factories for compilation and execution
Local in-memory DDLNeither writes back to files nor shares changes across instances; restarting restores file definitions
Remote persistent definitionsShared across instances; each instance still maintains its own execution objects and caches

See Metadata DDL for definition scope.

How Connectors Enter Query Plans ​

text
Table metadata → SPI / HmsTableFactory → Calcite Table
  → Select operators by table capabilities and query shape

KV primary-key join (INNER / LEFT)
  Materialize left input; deduplicate join keys, ignoring NULL
    → Convert key types → Check table cache → Batch-fetch missing keys
    → Merge by key and join rows; LEFT fills unmatched rows with NULL

Vector lookup join
  Recognize sorting, Top K, and filters
    → Build VectorSearchRequest per left row
    → Search through VectorSearchable / Milvus
    → Combine left row, right row, and score → Continue outer relational plan
PathImplementation and limits
FactoryTableFactoryUtils discovers HmsTableFactory through SPI and creates a Table using the connector option
KV primary-key joinSqlrecEnumerableKvJoin → KvJoinUtils → SqlRecKvTable.getByPrimaryKey(); support multiple rows per key, filling unmatched LEFT rows with NULL
KV non-key joinBuild filtered scans for distinct join keys, with different costs from batched primary-key access
Vector joinSqlRecVectorJoinRule → SqlrecEnumerableVectorLookupJoin → VectorJoinExecutor; build vector, field, filter, and Top K requests per left row
Subsequent computationContinue outer projections and sorting after combining search results; supported local plans handle predicates that were not pushed down

These specialized paths depend on table capabilities and query shape. Unsupported queries are rejected; see Built-in Connectors.

Caches and Definition Refresh ​

Cache or dataLocationUpdates and invalidation
CACHE TABLEExecution schemaPublished after the statement completes; scoped to the request, session, or subfunction
Table schemas and Connector objectsDatabase schemaCompare metadata; reuse unchanged objects and rebuild changed ones
Compiled functionsSqlFunctionCacheReuse on cache hits; recompile after definition refresh or invalidation
Primary-key cacheCaffeine within a TableTTL, size eviction, and affected-key invalidation after SQLRec writes
Filesystem dataFile snapshot within a TableWrites affect memory only; rebuilding the object reloads the file
OperationWhat is retained or rebuilt
Normal metadata refreshRetain unchanged Tables, primary-key caches, and Filesystem data
FLUSHInvalidate definition caches and Tables; retain session cache tables and local in-memory DDL without rereading SQL files
External-system writesDo not proactively clear primary-key caches; visibility depends on TTL and other policies

See Query Caching and FLUSH for details.

Model Tasks and Online Inference ​

ModelManager and ServiceManager call backends through the ModelController SPI to generate training, export, and inference workload configurations.

Task Management and Artifacts ​

text
Preparation (training backends)
  Model / ModelController
    → Training and export Jobs (Kubernetes)
    → Checkpoint metadata + model files
    → Deploy inference workload (Deployment / Service)
      → HTTP endpoint for online calls

Online call
  Input CacheTable → CallServiceFunction feature encoding
    → PredictionClient HTTP inference → Append predictions → New CacheTable

An API publishes a recommendation flow; a Service provides model predictions.
Object or stageStored or executed content
ModelFields, model type, configuration
Checkpoint metadataModel-definition snapshot, name, type, task DDL/YAML, and status; locate artifacts from the snapshot and name
Model storageActual weights and exported files; training backends export origin to export artifacts
Before export / service creationCheck the source checkpoint's completion status and type
Hosted-service creationValidate configuration → submit to Kubernetes → save the definition and URL; submission success does not mean readiness
Load a Service in file modeBuild call configuration only; do not deploy to Kubernetes

How Inference Results Enter SQL Results ​

StepImplementation
Resolve inputs and outputsCallServiceFunction reads Service configuration and model fields
RequestSelect input columns according to the Model, encode row-based or User-Item JSON, and send HTTP through PredictionClient
ResponseAppend declared prediction fields by input position to form a new CacheTable; missing or short output columns are filled with NULL

The service provider must still preserve response row count and order. Inference services run and scale independently. Hugging Face can deploy a downloaded origin directly; external connects to an existing endpoint. An API publishes the flow; a Service provides predictions. See the Model Guide for backend differences.

Execution Boundaries ​

Gateway Forwarding Boundaries ​

AreaImplementation and limits
Session and operation ownershipSessionManager manages each session's SqlExecutor, distinguishing local and remote operations
Remote executionGatewayClient connects on demand, synchronizes the database and session settings, and executes RPCs
Forwarding entry pointsThrift/JDBC in remote metadata mode only; REST API, REST SQL, and CLI have no transparent forwarding
Routing limitsForwardable statements such as CTEs go to Gateway; forwarding cannot bypass SQLRec extension restrictions
Metadata-only DDLLocal adapters write HMS without creating a Flink execution environment

See the SQL Reference and Client Connections.

Memory and State Boundaries ​

Entry point or resourceState scope
HTTP recommendation APIIndependent inputs, variables, and root schema for each call
REST SQLOne shared executor within a request
Thrift/JDBCCurrent session retains its executor, default database, and cache tables
Local CLICurrent process, with memory independent of the HTTP service
Connectors, model services, Flink jobsSeparate storage, compute, and resource lifecycles

Local queries materialize in memory, without a general spill-to-disk or continuous streaming execution mechanism. Use the appropriate Flink path for continuous large-scale processing; training and hosted-model deployment depend on Kubernetes.