Tutorial setup and troubleshooting

Start in Studio

1. Sign in to your tenant and select a working Gnok connection. New-user onboarding can provision the connection. If none is available, ask your administrator or Gnok support to check the account setup.
2. In the SQL editor's sidebar, open the Saved tab and expand Shared with me. The 17 tutorials are listed there by name, such as Tutorial: Churn Prediction End-to-End. Type tutorial in Search saved queries... to filter the list; search matches names, SQL text, and tags. Alternatively, download a tutorial's SQL from this documentation and paste it into a new editor tab.
3. Read that tutorial's prerequisites. Most tutorials need nothing beyond a working connection. The AI tutorials need AI Governance to be set up for your organization first.
4. Run the script in order. Inspect statement results and the final values, rather than treating a successful training acknowledgement as proof of correct predictions.

The fixtures reset their objects

The examples use CREATE OR REPLACE TABLE, model replacement, and in some cases explicit DROP or online-learning reset statements. Use a sandbox tenant or schema. Do not reuse these object names for data you need to keep, and avoid running two copies of the same tutorial against the same tenant concurrently.

Model loading and metadata queries depend on the hosted catalog and query services. Report service errors with the query/error reference; customers do not need to restart these services. See Quickstart and connection setup.

Inputs, outputs, and evaluation

• Keep feature order identical in training and prediction. A matching numeric type does not prevent a swapped-column mistake.
• Native supervised examples put the label first and cast integer labels to DOUBLE. The model argument list describes features, not the label.
• Preserve any scaling at inference time. The house-price tutorial returns a scaled target, while streaming scoring scales each feature before calling the model.
• PCA returns ARRAY<DOUBLE> because each prediction contains several component values. Classification IDs and probability scores have different meanings even when both are represented numerically.
• Treat evaluation on training rows as a fixture check. Use separate data and a suitable business metric before relying on a model operationally.

SHOW MODELS may include models from other tutorials visible in your tenant. Locate the qualified model name; do not expect a fixed total row count. Version numbers also depend on prior runs.

AI features and AI Governance

AI features are off for each organization until an organization administrator enables them. This covers the AISQL functions (AI_COMPLETE, AI_CLASSIFY_TEXT, AI_SUMMARIZE, and the others), RAG answers, ASK and SUGGEST QUERIES, and dashboard AI. These calls use Gnok's AI provider under your organization's AI Governance, so you don't need your own provider API key. Without a budget and an enabled policy, every AI call is refused.

To enable AI, an organization administrator opens Operations → AI Governance in Studio and does the following:

1. Under Monthly token budget, enter a Monthly token limit, set Control state to Available, and select Save budget.
2. Under Rollout policy, fill in Allowed providers (anthropic) and Allowed models (claude-haiku-4-5-20251001), and select the Allowed operations your workload uses.
3. Enter the Egress approval reference and Retention approval reference for your organization's approvals, then check Egress approved and Retention approved.
4. Check Enabled and select Save rollout policy. The page lists any remaining Enablement blockers.

Tutorial	Operations to allow
AISQL cookbook	ai_classify_text, ai_summarize, ai_extract_answer, ai_translate, ai_complete
Vector search and RAG	ai_complete (for the final AI_AGG answer)
Natural language to SQL	No specific operation; the policy must allow the provider and model above. EXPLAIN ASK makes no provider call.
BM25 and hybrid retrieval	None; it makes no AI calls

Embeddings are separate. EMBED() uses Gnok's embedding provider within your organization's monthly embedding allowance, and it doesn't need AI Governance. That covers the embedding steps of the vector-search and hybrid-retrieval tutorials.

The examples use synthetic content. Sending real documents or rows to a provider requires your organization's authorization. Re-running a provider-backed statement can incur additional usage, including unsuccessful attempts that reached the provider.

Keep the embedding model and dimension consistent for both documents and queries. Inspect generated text against its source: check facts, scope, missing information, and whether the SQL or language response actually answers the intended question. LIMIT is an upper bound; a constrained text-output budget can produce fewer complete suggestions.

See AI & ML configuration for hosted prerequisites and natural-language functions for the SQL interface.

Imported and remote models

The imported-model walkthrough includes a complete small ONNX artifact. ONNX inference is built into the hosted service; there is nothing to install. PyTorch and sklearn models need their own runtime and artifact format; the ONNX example does not test those paths.

The remote-model walkthrough calls a demo scorer that Gnok hosts for that tutorial, so it runs as written. Your own remote models must be public HTTPS endpoints that Gnok has approved; remote-model egress is allowlisted, and loopback, link-local, and private-network addresses are refused.

Background workloads

Feature materialization, online learning, and derived streams continue outside the interactive SQL request. The catalog provisions a tenant-scoped gnok-engine service identity automatically for signup or on trusted first use for an existing active tenant. Users do not need to create a background password.

Identity provisioning does not grant unrestricted data access. An administrator must authorize the workload's source reads and required output writes. Feature refresh needs to read its source tables and replace its designated output. Online learning needs its labelled feedback; stream processing needs its source and output access. Keep grants scoped to those resources.

Feature storage is enabled by default in the engine. Effective availability, capacity, and background execution are managed by the hosted service. Your workload still requires its source and output grants.

The short examples distinguish configuration from processing. An online learner with an empty feedback table has nothing to consume. A new drift monitor may not yet have a comparison baseline. Use progress, output rows, model versions, and run records to confirm that work actually occurred.

Common problems

Symptom	Check and recovery
PCA fails with a return-type mismatch	Use the current RETURNS ARRAY<DOUBLE> declaration, not the earlier scalar version.
An old tutorial keeps reappearing	Studio preserves editor drafts. Save any personal changes, close the old tab, and reopen the shared tutorial, or paste the downloadable SQL into a new tab. A page refresh need not replace the draft.
Internal error [ref …]	Give Gnok support the reference and timestamp. A service dependency failure can affect model or vector metadata; changing SQL may not resolve it.
A query was interrupted during an outage	Inspect query history and the submitted query ID before retrying a write. Once dependencies recover, retry the failed read/query as appropriate. Do not blindly rerun every reset statement over data you need.
Permission denied in a background task	Check the tenant's managed service identity and resource grants, not just the signed-in user's permissions.
A feature result is empty immediately after registration	Wait for refresh, or use the tutorial's bounded backfill with wait = true; then inspect failures and target rows.
A remote model cannot connect	Confirm the endpoint is a public HTTPS URL that Gnok has approved, and verify its batch payload and response shape.
AI calls are refused or the budget is denied	Ask an organization administrator to check Operations → AI Governance: the budget's control state must be Available with tokens remaining, and the rollout policy must be enabled, approved, and allow the provider, model, and operation.
A model returns plausible but incorrect numbers	Compare feature order, numeric types, scaling, target units, and active model version with the tutorial.

Choose a tutorial when the prerequisites are ready.