ONNX Model Inference
Import a trained model as a SQL function when its artifact matches Gnok's ONNX adapter. ONNX can represent many kinds of models, but the current scalar SQL adapter serves numeric tabular input with one numeric result per row. Exportability alone does not establish compatibility.
The imported-model tutorial includes a complete small artifact, expected predictions, and version activation. For custom tensor contracts, consider the remote-model tutorial.
Runtime
ONNX inference is built into the hosted service. There is no runtime library to install or configure. Successful registration does not replace a scoring check: score representative rows after you register a model.
Input and output contract
| Aspect | Current scalar adapter |
|---|---|
| Input | SQL feature columns combined into one Float32 tensor of shape [rows, features], sent to the artifact's first input |
| Numeric conversion | Float32, Float64, Int32, and Int64 arrays can be converted to Float32; use a matching SQL signature and explicit casts when needed |
| Output | First artifact output must be a Float32 tensor of shape [rows] or [rows, 1] |
| SQL return | The scalar result is cast to the declared SQL return type |
| Unsupported output shapes | Multi-column vectors, maps, and arbitrary tensors are not scalar predictions |
Use a dynamic batch dimension so different SQL batch sizes can be scored. Preserve feature order and preprocessing. A classifier exported with an integer label output or a probability map needs an adapted export with the intended scalar Float32 output first. Merely declaring RETURNS FLOAT does not change an artifact's output tensor.
Text, image, and embedding models usually need tokenization, extra input tensors, or vector outputs. Do not register them as model(VARCHAR) RETURNS FLOAT and assume that preprocessing or output selection happens automatically. Use EMBED for the documented embedding SQL path.
Registering models
These are registration templates: replace the stage path, URI, or base64 text with an artifact accessible to the engine. The containing catalog and schema must exist.
CREATE MODEL analytics.models.fraud_scorer(FLOAT, FLOAT, FLOAT)
RETURNS FLOAT
USING FRAMEWORK 'onnx'
AS FROM STAGE @models/fraud.onnx;
For a file/object URI, use the FILE keyword:
CREATE MODEL analytics.models.fraud_scorer(FLOAT, FLOAT, FLOAT)
RETURNS FLOAT
USING FRAMEWORK 'onnx'
AS FROM FILE 's3://example-model-bucket/fraud.onnx';
Inline bytes use AS FROM '<base64-encoded-artifact>'. A URI in the inline-byte position is not an artifact. Use CREATE OR REPLACE MODEL when an intentional in-place replacement is appropriate.
Calling from SQL
After registration, both forms invoke the model:
SELECT transaction_id,
analytics.models.fraud_scorer(
CAST(amount_scaled AS FLOAT),
CAST(velocity_scaled AS FLOAT),
CAST(distance_scaled AS FLOAT)) AS risk
FROM analytics.models.transactions;
SELECT ML_PREDICT('analytics.models.fraud_scorer',
CAST(0.8 AS FLOAT), CAST(0.7 AS FLOAT), CAST(0.6 AS FLOAT)) AS risk;
These examples assume a matching three-feature model and an existing source table. Casting controls types; it does not perform the model's scaling or category encoding.
Versioning
Stage a new artifact, inspect its version and predictions, then activate it. Put VERSION after the model name and before the signature:
CREATE MODEL analytics.models.fraud_scorer VERSION 'v2'
(FLOAT, FLOAT, FLOAT) RETURNS FLOAT
USING FRAMEWORK 'onnx'
AS FROM STAGE @models/fraud-candidate.onnx;
SHOW MODEL VERSIONS analytics.models.fraud_scorer;
Activate the intended staged version using the positive version number reported by SHOW MODEL VERSIONS. If that number is 2, for example:
ALTER MODEL analytics.models.fraud_scorer ACTIVATE VERSION 'v2';
Activation accepts a positive version number, its v-prefixed form, or LATEST; arbitrary labels are not activation identifiers. Use an explicit version for controlled rollout; LATEST can select a different candidate if another version is staged concurrently. OR REPLACE and version staging have different purposes and cannot be combined. The version tutorial demonstrates how predictions change after activation.
Quantisation
QUANTISATION 'none', 'int8', 'int4', or 'fp16' records the artifact's declared quantisation. It does not convert a floating-point artifact into a quantised model. Export the desired representation externally, keep a compatible input/output contract, and compare predictions and latency before activation.
GPU acceleration
Accelerator availability is managed by Gnok; ask Gnok support whether GPU inference is available for your account. GPU availability does not imply every operator runs on a GPU or that small batches execute faster; compare representative predictions and latency.
Caching and lifecycle
The service caches loaded models by artifact content, so repeated scoring doesn't reload the artifact each time. Model identity, version, and authorization remain tenant-scoped. The first call after a model is registered or activated can take longer while the artifact loads.
SHOW MODELS;
SHOW MODEL VERSIONS analytics.models.fraud_scorer;
Troubleshooting
| Symptom | Check |
|---|---|
| Model cannot load | Artifact bytes (complete, correctly encoded), supported operators and opset |
| Input shape or type mismatch | One Float32 tensor, feature count/order, dynamic batch dimension |
| Output type or shape mismatch | First output is Float32 with exactly one value per input row |
| Valid-looking but wrong predictions | Preprocessing, feature order, active version, Float32 precision |
| Internal error reference | Give Gnok support the reference and timestamp; catalog and artifact failures can surface during scoring |
Inference errors can fail the SQL query. Do not rely on automatic per-row NULL recovery for imported models. Check representative normal, missing, extreme, and invalid inputs before using a model in an application.