Operator Module · Tier 2

Cortex Code Fundamentals
From Install to First Generation

Set up Cortex Code, understand what it is and what it isn't, and produce your first useful generations against a real Snowflake account. Built for engineers who want to ship — not for a tutorial loop.

Learning objectives

01
Understand what Cortex Code is, how it differs from external LLM coding assistants, and the Snowflake-native advantages.
02
Install and authenticate Cortex Code CLI across Windows, macOS, and Linux.
03
Configure access to your Snowflake account with the appropriate role and warehouse.
04
Run your first generation in both Snowsight and the CLI, comparing the two delivery modes.
05
Diagnose authentication, role, and credit-related failures using a structured matrix.
06
Apply productive prompt patterns that produce useful first-pass code, not demo-grade hallucinations.

Level

Operator
Hands-on

Duration

60 minutes
plus lab

Prerequisites

Snowflake account
Cortex enabled

Why this matters

Cortex Code reached general availability in March 2026 and ships features every few weeks. Most engineers who try it form an opinion in the first 15 minutes — and most form the wrong opinion because they use it like a generic LLM coding assistant rather than a Snowflake-native tool. This module corrects that, fast.

00

Module Contents

What this module covers

This module is the foundation of the Cortex Code series. It covers what Cortex Code is, how to install it, how to authenticate, how to produce useful first generations, and how to diagnose the most common early failures. By the end you will have a working Cortex Code installation, a configured connection, and a productive prompt pattern that scales.

01

What Cortex Code is — and what it isn't
The Snowflake-native AI coding assistant. Why it differs from external LLM tools and where that difference matters in production.

p.03
02

Anatomy of a Cortex Code session
CLI versus Snowsight delivery modes, prompt structure, schema-aware context, and the role of the active warehouse.

p.04
03

The five-step install and authenticate
Download, install, authenticate, configure role and warehouse, and run your first generation against a real account.

p.05
04

Diagnosing first-session failures
A structured matrix for the six most common ways a Cortex Code session fails before useful output appears.

p.06
05

Authentication and role configuration
SSO, key-pair, environment variables, and the role selection patterns that determine what Cortex Code can see and do.

p.07
06

Productive prompt patterns
The four prompt structures that produce useful first-pass code. The three patterns that produce hallucinated garbage.

p.08
07

Hands-on lab worksheet
Install, authenticate, and produce three working generations against your own Snowflake account.

p.09
08

Knowledge check
Five questions covering installation, authentication, prompt patterns, and failure diagnosis.

p.10
09

Glossary and reference
Key terminology, command cheat sheet, and a production readiness checklist.

p.11
10

Module completion and next steps
Module summary, completion certificate, and the next module in the Cortex Code series.

p.12

01

Chapter 01

What Cortex Code is — and what it isn't

Cortex Code is Snowflake's native AI coding assistant. It generates SQL, Python, and Streamlit code, runs inside Snowsight or via the Cortex Code CLI, and — this is the part that matters — has direct, governed access to your account's schema, tables, and metadata at generation time. That last point is what separates it from every external LLM coding tool.

An engineer who has used GitHub Copilot, Cursor, or ChatGPT for SQL generation will pattern-match Cortex Code to those tools and use it the same way. That is the first mistake. Those tools generate code from training data alone. Cortex Code generates code against your actual schema, your actual table names, your actual column types, and your actual role's permissions. The accuracy difference is enormous.

External LLM vs. Cortex Code

External LLM coding tool

Generates from training data and the prompt you provide. Has no knowledge of your schema. Will invent plausible-sounding column names that don't exist. Useful for syntax help, dangerous for production queries.

Cortex Code

Generates against your actual schema using @-injection to reference real tables and columns. Respects RBAC — you only see what your role permits. Output is grounded in production reality.

Three places Cortex Code earns its keep

Schema-grounded SQL generation. Ask for "a query joining orders to customers with last-30-days revenue by region" and Cortex Code produces SQL referencing your real FACT_ORDERS, DIM_CUSTOMER, and the correct foreign keys — not invented column names that match a generic example.

Streamlit app scaffolding. Ask for a Streamlit dashboard showing top customers by revenue and Cortex Code produces working Python that queries your schema correctly. Deployment to Streamlit in Snowflake is one command away.

Cortex Analyst semantic model authoring. Cortex Code can scaffold the YAML semantic model required for Cortex Analyst, pulling real columns and inferring measures and dimensions. The output still needs human review, but the starting point is hours ahead of writing it by hand.

The framing that changes how you use it

Stop thinking of Cortex Code as a generic LLM coding assistant. Start thinking of it as a senior engineer who has read your entire schema and can write code against it, but who will only write code your role is allowed to write. That mental model produces better prompts, better results, and a faster learning curve.

02

Chapter 02

Anatomy of a Cortex Code session

A Cortex Code session has three moving parts: the delivery mode (Snowsight UI or CLI), the active session context (role, warehouse, database), and the prompt itself with its embedded schema references. Get any of these wrong and the output quality drops. Get them right and Cortex Code produces useful code on the first try.

The two delivery modes

Snowsight UI. Cortex Code panel appears in worksheets and notebooks. Best for interactive exploration, schema discovery, and ad-hoc generation. The active role and warehouse from your worksheet apply to the generation context. Output appears inline and can be inserted into the active worksheet with one click.

Cortex Code CLI. A command-line tool that runs in your terminal and integrates with your local development environment. Best for scripted generation, CI/CD integration, and engineers who prefer working outside the browser. Standalone $20/month subscription available for non-Snowflake-customer use — but most production use happens against your Snowflake account.

The session context

# The four context elements that determine what Cortex Code can do ROLE: Determines what schemas, tables, and columns are visible WAREHOUSE: Compute used for any queries Cortex Code runs during generation DATABASE: Default database for schema references (overridable per prompt) SCHEMA: Default schema (overridable per prompt with fully-qualified names) # Example: set context explicitly in CLI cortex code config set role ANALYST_ROLE cortex code config set warehouse ANALYST_WH cortex code config set database ANALYTICS_PROD

The prompt anatomy

A good Cortex Code prompt has four elements: the task (what you want), the schema reference (what tables to use, often via @-injection), the constraints (filters, time windows, output format), and the style (verbosity, comments, error handling). Skipping any element produces vaguer output.

# A well-structured prompt Generate a SQL query that: # 1. The task - Returns the top 10 customers by trailing-30-day revenue # 2. The schema reference - Joins @ANALYTICS_PROD.SALES.FACT_ORDERS to @ANALYTICS_PROD.SALES.DIM_CUSTOMER # 3. The constraints - Filters out test accounts (customer_type != 'TEST') - Excludes refunded orders (refund_flag = FALSE) # 4. The style - Uses CTEs for readability, includes a single-line comment per CTE

The accuracy principle

Cortex Code accuracy is a direct function of prompt structure and schema references. A vague prompt produces vague code. A prompt with explicit @-references and constraints produces production-quality code on the first generation. This is the single most important habit to develop.

03

Chapter 03

The five-step install and authenticate

Step 01

Install the Cortex Code CLI

For Snowsight UI use, no install required — Cortex Code is built into Snowsight worksheets and notebooks as of the March 2026 GA. For CLI use, install via the official Snowflake distribution. Verify with the version command after install.

# macOS / Linux
curl -L https://sfc-repo.snowflakecomputing.com/cortex-code/install.sh | bash

# Windows (PowerShell)
iwr -useb https://sfc-repo.snowflakecomputing.com/cortex-code/install.ps1 | iex

# Verify
cortex code --version

Step 02

Authenticate to your Snowflake account

Cortex Code inherits the Snowflake CLI authentication. Use externalbrowser for interactive (SSO) work, key-pair for headless CI/CD use. The authentication once-and-done — subsequent commands reuse the cached session.

cortex code auth login \
  --account orgname-accountname \
  --user first.last \
  --authenticator externalbrowser

Step 03

Configure role, warehouse, and default schema

Set the session context Cortex Code will use by default. Use a dedicated role with read access to development data — not your personal role with broad privileges. The active role determines schema visibility, so a too-permissive role produces noisy generation context.

cortex code config set role CORTEX_DEV_ROLE
cortex code config set warehouse CORTEX_DEV_WH
cortex code config set database ANALYTICS_DEV
cortex code config set schema PUBLIC

Step 04

Run your first generation

Start with a simple, schema-grounded prompt. Pick a table you know well. Use the @-injection syntax to reference it explicitly. Inspect the output before running it — the goal is to develop the habit of reading generated code, not pasting blindly.

cortex code generate "Write a SQL query that returns
  the row count and last-updated timestamp for
  @ANALYTICS_DEV.PUBLIC.CUSTOMERS"

Step 05

Compare CLI output to Snowsight output

Run the same prompt in the Snowsight Cortex Code panel. The output should be comparable — but the UI provides richer context, suggestion follow-ups, and the ability to insert into the worksheet. Use whichever fits the moment.

Operator Tip

Create a dedicated CORTEX_DEV_ROLE with read-only access to your development databases. Never give Cortex Code your personal admin role — the schema visibility becomes overwhelming and generation accuracy drops as the model wades through irrelevant tables.

04

Chapter 04

Diagnosing first-session failures

First Cortex Code sessions fail in six predictable ways. The matrix below maps symptom to cause to fix. Keep it next to your terminal for the first week of use — the same six causes will produce the same six symptoms across every new install.

Symptom	Root cause and fix
"Authentication failed" on first generation	Snowflake CLI authentication cache expired or never completed. Run cortex code auth login again with the correct account identifier. Account identifier is orgname-accountname — not your Snowsight URL.
"Role does not exist" or "insufficient privileges"	Configured role hasn't been granted to your user. Run SHOW GRANTS TO USER <user> in Snowsight to verify, then ask an admin to grant the missing role.
Generation runs but produces invented column names	Schema reference missing or wrong database context. Use explicit @-injection like @DB.SCHEMA.TABLE in the prompt. Cortex Code falls back to training data when it can't resolve a schema reference.
"Cortex feature not enabled for this account"	Cortex Code is not enabled at the account level. Snowflake admin must enable Cortex AI features via account parameters. Cortex Code is GA but still requires explicit enablement.
Credit limit exceeded	Per-user daily credit cap hit. Default cap is 20 credits per user per day via CORTEX_CODE_SNOWSIGHT_DAILY_EST_CREDIT_LIMIT_PER_USER. Admin can raise the cap, or wait until midnight UTC for reset.
"Warehouse suspended" mid-generation	Configured warehouse auto-suspended before generation completed. Either increase the auto-suspend interval, or use a smaller-cost warehouse with a longer suspend window for Cortex Code work.

The standard debug order

Authentication first. Role second. Cortex enablement third. Credit cap fourth. Schema reference fifth. Warehouse sixth. Most engineers chase schema problems first because the symptom is most visible — but four times out of five the real cause is one of the first three. Walk the order.

05

Chapter 05

Authentication and role configuration

Cortex Code uses Snowflake's standard authentication patterns. The choice of authentication method depends on whether you're working interactively or in headless automation. Get this right at setup and you won't think about it again. Get it wrong and you'll fight it every day.

Four authentication patterns

Externalbrowser (SSO). Default for interactive use. Opens a browser tab for SAML/SSO login on first command, caches the token for subsequent commands. The right choice for engineers using Cortex Code from their laptops.
Key-pair authentication. Default for headless and CI/CD use. Register a public key against your Snowflake user, store the private key on disk with restricted permissions. No browser, no prompts — perfect for automated generation in pipelines.
Username/password with MFA. Available but increasingly discouraged. MFA prompts interrupt automated workflows and password rotation creates ongoing maintenance. Use only for environments where SSO is unavailable.
OAuth (federated identity). Best for enterprise environments with existing OAuth infrastructure. Cortex Code accepts standard OAuth tokens via the standard authenticator parameter. Same pattern as Snowflake CLI.

Recommended role design

A dedicated CORTEX_DEV_ROLE with read-only access to development databases is the right starting point. The role should grant SELECT on the schemas you want Cortex Code to reference for generation, plus USAGE on the warehouse you're using for the session.

# SQL to create the recommended role and grant pattern CREATE ROLE CORTEX_DEV_ROLE; GRANT USAGE ON DATABASE ANALYTICS_DEV TO ROLE CORTEX_DEV_ROLE; GRANT USAGE ON ALL SCHEMAS IN DATABASE ANALYTICS_DEV TO ROLE CORTEX_DEV_ROLE; GRANT SELECT ON ALL TABLES IN DATABASE ANALYTICS_DEV TO ROLE CORTEX_DEV_ROLE; GRANT USAGE ON WAREHOUSE CORTEX_DEV_WH TO ROLE CORTEX_DEV_ROLE; # Future grants ensure new objects also become visible GRANT SELECT ON FUTURE TABLES IN DATABASE ANALYTICS_DEV TO ROLE CORTEX_DEV_ROLE; GRANT ROLE CORTEX_DEV_ROLE TO USER first.last;

Operator Tip

Never give Cortex Code your personal role or ACCOUNTADMIN. Two reasons: schema visibility becomes overwhelming and generation accuracy drops, and any audit log entry from Cortex Code will show as the wrong user. Dedicated role per developer is the production pattern.

06

Chapter 06

Productive prompt patterns

Cortex Code rewards prompts that follow a structure. The four patterns below produce useful first-pass code reliably. The three anti-patterns below produce hallucinated garbage even on a well-configured installation. Internalize the patterns; recognize and reject the anti-patterns.

Four prompt patterns that work

Pattern 01 — Task + schema reference + constraints. The default productive pattern. State what you want, name the tables explicitly with @-injection, list filters and time windows. Produces accurate code on the first generation roughly 80 percent of the time.

Pattern 02 — Modify this existing query. Paste working SQL into the prompt and ask for a specific modification. Useful for refactoring, adding a window function, switching to a CTE structure. Higher accuracy than generating from scratch because the model anchors on real syntax.

Pattern 03 — Generate the test for this query. Paste a query, ask for assertions that validate its output. Cortex Code knows your row counts and column types, so it can generate meaningful tests rather than generic ones.

Pattern 04 — Explain what this query does in business terms. Paste SQL, ask for a plain-English explanation suitable for a stakeholder. Useful for documentation, code review, and onboarding.

Three anti-patterns to avoid

Anti-pattern

Vague task, no schema reference. "Give me a query showing customers." Cortex Code has nothing to anchor on. Output references invented tables.

Anti-pattern

Conversational tone with too many requirements. Five-paragraph prompts mixing task, style, history, and reasoning produce confused output. Be specific and structured.

A worked comparison

# Anti-pattern — vague, no anchor "Show me top customers" # Pattern 01 — task + schema + constraints "Generate SQL returning the top 10 customers by revenue over the last 30 days. Use @ANALYTICS.SALES.FACT_ORDERS joined to @ANALYTICS.SALES.DIM_CUSTOMER. Exclude rows where customer_type = 'TEST'. Format with CTEs."

Operator Tip

Build a personal library of prompt templates. The same five or six prompt structures will cover 80 percent of your daily Cortex Code use. Save them, parameterize them, and you'll cut your time-to-useful-output in half within a week.

07

Chapter 07

Hands-on lab worksheet

A guided exercise to install Cortex Code, authenticate against your own Snowflake account, and produce three working generations. Estimated time: 45–60 minutes against a sandbox account.

Task 01

Install the Cortex Code CLI and verify version

10 min

Run the install script for your platform. Open a fresh terminal so PATH updates take effect. Capture the installed version with cortex code --version.

Task 02

Authenticate via externalbrowser and confirm

10 min

Run cortex code auth login with your account identifier. Complete the browser SSO flow. Verify with cortex code auth status — output should show your username and active session.

Task 03

Configure a dedicated CORTEX_DEV_ROLE

15 min

Use the SQL pattern from Chapter 05 to create the role, grant SELECT on a dev schema, and grant the role to your user. Switch your Cortex Code config to use this role.

Task 04

Run three generations using Pattern 01

15 min

Pick three real tables in your dev schema. For each, generate a query using the task + @-reference + constraints pattern. Compare the generated SQL to what you would have written. Record any accuracy gaps.

Task 05

Trigger and diagnose one deliberate failure

10 min

Generate against a table your CORTEX_DEV_ROLE cannot see (or use a vague no-schema prompt). Confirm the failure mode. Use the matrix from Chapter 04 to identify the root cause. Document your diagnosis.

08

Chapter 08

Knowledge check

Five questions covering the core concepts of this module. Answer key appears on the closing page. A passing score is four of five correct.

Question 01

What is the most important way Cortex Code differs from external LLM coding assistants?

A
It runs faster than external tools
B
It has direct, governed access to your account's schema at generation time
C
It uses a larger language model than competitors
D
It only generates SQL, not Python or Streamlit

Question 02

For a scheduled CI/CD job using Cortex Code, what is the correct authentication pattern?

A
Externalbrowser SSO
B
Username/password with MFA
C
Key-pair authentication
D
No authentication — Cortex Code is open

Question 03

Cortex Code produces a query referencing column names that don't exist in your schema. The most likely cause is:

A
Cortex Code is broken — file a support ticket
B
The prompt lacks @-injection references and Cortex Code fell back to training data
C
Your warehouse is undersized
D
The Cortex Code CLI is the wrong version

Question 04

Which role should you configure for daily Cortex Code work?

A
ACCOUNTADMIN — gives Cortex Code maximum visibility
B
Your personal role with all your usual privileges
C
A dedicated CORTEX_DEV_ROLE with read access to development data only
D
No role — Cortex Code operates outside RBAC

Question 05

Which prompt structure produces the most accurate first-pass output?

A
A conversational five-paragraph prompt mixing context, history, and requirements
B
A single sentence with no schema reference
C
Task statement + explicit @-injection schema references + constraints
D
Just the table name with no other context

09

Chapter 09

Glossary and reference

Key terminology

Cortex Code

Snowflake's native AI coding assistant. Generates SQL, Python, and Streamlit code against your real schema, with RBAC inheritance and governed access to metadata.

@-injection

The syntax used in Cortex Code prompts to reference real database objects. Format: @DATABASE.SCHEMA.TABLE. Anchors the generation to your actual schema rather than training data.

Snowsight Cortex panel

The Cortex Code interface built into Snowsight worksheets and notebooks. Inherits the active worksheet's role and warehouse for the generation context.

Cortex Code CLI

Command-line interface for Cortex Code. Used for scripted generation, CI/CD integration, and local development workflows. Authenticates with the same patterns as Snowflake CLI.

Schema awareness

The capability that distinguishes Cortex Code from external LLM tools. Cortex Code can see your real tables and columns at generation time via @-injection, governed by your role.

CORTEX_DEV_ROLE

A recommended dedicated role pattern for Cortex Code work. Read-only access to development data, separate from your personal role to control schema visibility and audit clarity.

Daily credit limit

Per-user cap on Cortex Code credit consumption, set via CORTEX_CODE_SNOWSIGHT_DAILY_EST_CREDIT_LIMIT_PER_USER. Defaults to 20 credits per user per day.

Command cheat sheet

Authenticate

cortex code auth login \
  --account ORG-ACCT \
  --user USER \
  --authenticator externalbrowser

Configure context

cortex code config set role CORTEX_DEV_ROLE
cortex code config set warehouse CORTEX_DEV_WH
cortex code config set database ANALYTICS_DEV

Generate

cortex code generate "Task + @DB.SCHEMA.TABLE
  + constraints + style"

Verify status

cortex code --version
cortex code auth status
cortex code config list

Production readiness checklist

Cortex Code CLI installed and version verified
Authentication configured with externalbrowser (interactive) or key-pair (CI/CD)
Dedicated CORTEX_DEV_ROLE created with appropriate read-only grants
Per-user daily credit limit set at the account level
Warehouse sized appropriately for Cortex Code workload (XS or S sufficient)
Personal prompt template library started — at least 5 patterns saved
QUERY_HISTORY monitoring confirmed active for Cortex Code sessions

10

Chapter 10

Module completion

What you learned

Concept

What Cortex Code is, how it differs from external LLM coding assistants, and the schema-awareness advantage that distinguishes it in production environments.

Installation

The five-step install and authenticate pattern across all three operating systems. Role configuration with the recommended CORTEX_DEV_ROLE pattern.

Diagnostics

The six common first-session failure modes and the structured matrix mapping each to its root cause and specific fix. The standard debug order.

Prompting

Four productive prompt patterns that produce useful first-pass output, three anti-patterns to avoid, and the @-injection syntax that anchors generation to real schema.

Cloud On Demand · Operator Module Completion

Cortex Code
Fundamentals

Awarded to the practitioner who completed module OPR-001

Recipient signature

Issued by Cloud On Demand · OPR-001 · v1.0

Next in series

OPR-011 · Schema-Aware Code Generation with @-Injection

→

Cortex Code FundamentalsFrom Install to First Generation

Why this matters

The framing that changes how you use it

The accuracy principle

The standard debug order

Concept

Installation

Diagnostics

Prompting

Cortex Code Fundamentals
From Install to First Generation