<?xml version="1.0" encoding="UTF-8"?><rss xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:content="http://purl.org/rss/1.0/modules/content/" xmlns:atom="http://www.w3.org/2005/Atom" version="2.0" xmlns:cc="http://cyber.law.harvard.edu/rss/creativeCommonsRssModule.html">
    <channel>
        <title><![CDATA[Stories by Masato Takada on Medium]]></title>
        <description><![CDATA[Stories by Masato Takada on Medium]]></description>
        <link>https://medium.com/@masato.takada?source=rss-a32a05d7f19------2</link>
        <image>
            <url>https://cdn-images-1.medium.com/fit/c/150/150/0*7uMJCW5hKXUvcS7d</url>
            <title>Stories by Masato Takada on Medium</title>
            <link>https://medium.com/@masato.takada?source=rss-a32a05d7f19------2</link>
        </image>
        <generator>Medium</generator>
        <lastBuildDate>Sun, 22 Nov 2026 12:42:23 GMT</lastBuildDate>
        <atom:link href="https://medium.com/@masato.takada/feed" rel="self" type="application/rss+xml"/>
        <webMaster><![CDATA[yourfriends@medium.com]]></webMaster>
        <atom:link href="http://medium.superfeedr.com/" rel="hub"/>
        <item>
            <title><![CDATA[Cortex AI Gateway Is Now GA: Testing What Changed Since the Preview]]></title>
            <link>https://medium.com/@masato.takada/cortex-ai-gateway-is-now-ga-testing-what-changed-since-the-preview-4fcaeb030187?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/4fcaeb030187</guid>
            <category><![CDATA[ai-gateway]]></category>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[snowflake-cortex]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Thu, 05 Nov 2026 11:17:36 GMT</pubDate>
            <atom:updated>2026-11-05T11:17:36.531Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><em>I work at Snowflake, but the views expressed in this article are my own and do not represent the official views of my employer.</em></blockquote><p><em>Information as of November 4, 2026. Inference, observability, and cost management for Cortex AI Gateway became generally available (GA) on November 3, 2026. Trace analytics, the Responses API, and Tools for Cortex AI Gateway are in preview. Check the </em><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway"><em>official documentation</em></a><em> for current availability.</em></p><p><em>This is a follow-up to </em><a href="https://medium.com/@masato.takada/cortex-ai-gateway-a-common-front-door-for-ai-on-snowflake-59165ab66b49"><em>Cortex AI Gateway: A Common Front Door for AI on Snowflake</em></a><em>. For the basics of how the gateway works and how to configure it with YAML and SQL, see that article.</em></p><h3>1. Introduction</h3><p><strong>About seven weeks after its preview launch in September 2026, Cortex AI Gateway reached GA, and it gained MCP-based connections to business tools (Tools) plus new cost-management features.</strong></p><p>My previous article covered setup, calling the gateway from Python, and reading logs and costs during the preview. This follow-up focuses on what changed since then, and on what I learned by running the GA version.</p><h3>1.1 What This Article Covers</h3><ul><li>What was added or changed since the preview</li><li>How to call GA inference from the official OpenAI and Anthropic SDKs, and what to watch out for</li><li>What traces and usage history record, and how completely</li><li>How to add AI Gateway to budgets and per-user quotas, and how long settings take to apply</li><li>What administrators can do with Tools (MCP), and the steps from enabling the Draw.io server to calling it</li></ul><h3>1.2 Test Environment</h3><p>All measurements come from a test account in the AWS Tokyo region, with cross-region inference enabled (CORTEX_ENABLED_CROSS_REGION = ANY_REGION).</p><pre>What I tested                                                           Date<br>----------------------------------------------------------------------  ----------------------------------------<br>MY_BUDGET_SUMMARY                                                       October 29, 2026<br>Tools for Cortex AI Gateway (what SQL can reach)                        October 30, 2026<br>Tools for Cortex AI Gateway (enabling in Snowsight and calling a tool)  November 4, 2026<br>GA inference, observability, and cost management                        November 4, 2026 (about 00:00–01:45 UTC)</pre><p>Clients used for the GA tests:</p><pre>Item                       Version<br>-------------------------  ---------<br>Python                     3.12<br>openai                     1.109.1<br>anthropic                  2.4.0<br>httpx                      0.28.1<br>Snowflake CLI              3.32.1<br>snowflake-snowpark-python  1.41.0<br>Snowflake (server)         10.40.100</pre><p>The gateway kept its default settings: all models exposed, logging on, and prompt and response bodies not captured. Throughout the article, I keep official specifications separate from what I observed.</p><h3>2. Updates Since the Preview</h3><h3>2.1 Release Timeline</h3><p><strong>The main changes are GA, Tools, more regions, and a function that lets users check their own limits.</strong></p><pre>Date        Stage    Change<br>----------  -------  ----------------------------------------------------------------------------------<br>2026-09-15  Preview  Cortex AI Gateway launched (covered in the previous article)<br>2026-09-16  GA       Weekly per-user quota limits, and including or excluding quota users by name<br>2026-10-16  ―        Available in Azure, Google Cloud, and AWS New Zealand<br>2026-10-19  Preview  Tools for Cortex AI Gateway (managing and distributing MCP servers)<br>2026-10-28  GA       SNOWFLAKE.LOCAL.MY_BUDGET_SUMMARY() to check your own quotas<br>2026-11-03  GA       Inference, observability, and cost management GA; trace analytics added in preview</pre><p>The GA release note also states that client applications can export their own OpenTelemetry traces to the gateway. <a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-11-03-cortex-ai-gateway-ga">Release note</a></p><h3>2.2 What Felt Different from My Previous Tests</h3><p><strong>Errors that were hard to interpret during the preview are much clearer in the GA version.</strong></p><pre>Item                               Preview (September 16, 2026)                              GA (November 4, 2026)<br>---------------------------------  --------------------------------------------------------  -------------------------------------<br>Claude sent to Chat Completions    503                                                       400 with an explanatory message<br>Responses API                      Two API formats only at the time of the previous article  Added in preview (OpenAI models only)<br>Regions                            AWS commercial regions, with some exceptions              Expanded to Azure and Google Cloud<br>MCP connections to business tools  None                                                      Tools (preview)</pre><p>I did not rerun every preview test under the same conditions. This table lists differences I noticed during the current tests.</p><h3>3. Trying GA Inference</h3><h3>3.1 Three API Formats and Which Models They Support</h3><p><strong>The gateway has one endpoint, but each model works with a specific API format.</strong></p><pre>API format               Path                  Supported models                                                       Stage<br>-----------------------  --------------------  ---------------------------------------------------------------------  -------<br>OpenAI Chat Completions  /v1/chat/completions  All except Claude (OpenAI, Grok, Llama, Mistral, DeepSeek, Snowflake)  GA<br>Anthropic Messages       /v1/messages          Claude only                                                            GA<br>OpenAI Responses         /v1/responses         OpenAI models only                                                     Preview</pre><p>Pick the one that matches the SDK your application uses. Chat Completions covers the most models; switch to Messages only for Claude. <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/inference">Inference with Cortex AI Gateway</a></p><h3>3.2 What You Need Before Calling It</h3><p><strong>You need five things: the endpoint, </strong><strong>USAGE on the gateway, a token, a model name, and access to that model itself.</strong></p><p>Get the endpoint with this SQL:</p><pre>DESCRIBE AI GATEWAY SNOWFLAKE;</pre><p>base_url came back in the form https://&lt;account-host&gt;/api/v2/aigateways/snowflake. A separate privatelink_base_url column is returned for private connectivity. Use this result rather than building the URL by hand.</p><p>USAGE is granted to PUBLIC by default. On the test account, the gateway had been created automatically, and PUBLIC had USAGE.</p><p>Send an OAuth access token, a key-pair JWT, or a programmatic access token (PAT) as Authorization: Bearer &lt;token&gt;. The documentation recommends short-lived tokens over PATs, which stay valid until they expire or are revoked. In my tests, I registered a key pair on a dedicated service user and used a JWT valid for 50 minutes.</p><p>USAGE on the gateway doesn&#39;t widen the set of models a user can use. You still need access to the model itself, such as the SNOWFLAKE.CORTEX_USER database role. The test role had SNOWFLAKE.CORTEX_USER as well.</p><h3>3.3 Classifying Support Tickets with the OpenAI SDK</h3><p><strong>With the OpenAI SDK, set </strong><strong>base_url to the gateway endpoint plus </strong><strong>/v1, and pass the token as </strong><strong>api_key.</strong></p><p>In testing, I had the model classify 10 support tickets by category and priority and return JSON. The following is a shortened version. Adding a conversation ID and traceparent as headers lets you match the request to traces later (Section 4.2).</p><pre>import json<br>import os<br>import secrets<br>from openai import OpenAI<br><br>client = OpenAI(<br>    api_key=os.environ[&quot;SNOWFLAKE_TOKEN&quot;],<br>    base_url=&quot;&lt;gateway-endpoint&gt;/v1&quot;,<br>)<br><br>tickets = [<br>    &quot;My invoice for October shows a double charge.&quot;,<br>    &quot;The dashboard takes 40 seconds to load every morning.&quot;,<br>    &quot;Our API calls return HTTP 500 since last night.&quot;,<br>]<br>prompt = (<br>    &quot;Classify each support ticket. Return only a JSON array of objects with keys &quot;<br>    &quot;id, category, priority (high|medium|low), summary.\n&quot;<br>    + &quot;\n&quot;.join(f&quot;{i + 1}. {t}&quot; for i, t in enumerate(tickets))<br>)<br>trace_id = secrets.token_hex(16)<br>response = client.chat.completions.create(<br>    model=&quot;openai-gpt-6-astra&quot;,<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: prompt}],<br>    extra_headers={<br>        &quot;x-snowflake-ai-gateway-conversation-id&quot;: &quot;support-triage&quot;,<br>        &quot;traceparent&quot;: f&quot;00-{trace_id}-{secrets.token_hex(8)}-01&quot;,<br>    },<br>)<br>text = response.choices[0].message.content.strip().strip(&quot;`&quot;).removeprefix(&quot;json&quot;).strip()<br>for row in json.loads(text):<br>    print(row[&quot;id&quot;], row[&quot;category&quot;], row[&quot;priority&quot;], row[&quot;summary&quot;])</pre><p>Results from the test. Each is a single run, and response times vary with network and model load.</p><pre>Language  Model               HTTP  Rows  Input tokens  Output tokens  Response time<br>--------  ------------------  ----  ----  ------------  -------------  -------------<br>English   openai-gpt-6-astra  200   10    180           327            13.3 s<br>Japanese  openai-gpt-6-astra  200   10    246           461            8.5 s</pre><p>Japanese summaries came back without encoding problems. For example, the double-charge ticket was classified as billing, and the HTTP 500 ticket as outage with high priority.</p><h3>3.4 Calling from the Anthropic SDK</h3><p><strong>With Anthropic Python SDK 2.4.0, passing the token as </strong><strong>auth_token worked.</strong></p><pre>import os<br>import anthropic<br><br>client = anthropic.Anthropic(<br>    base_url=&quot;&lt;gateway-endpoint&gt;&quot;,  # no /v1: the SDK appends /v1/messages<br>    auth_token=os.environ[&quot;SNOWFLAKE_TOKEN&quot;],<br>)<br>response = client.messages.create(<br>    model=&quot;claude-sonnet-5&quot;,<br>    max_tokens=2048,<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Answer in one word: what is the capital of Japan?&quot;}],<br>)<br>text = next(block.text for block in response.content if block.type == &quot;text&quot;)<br>print(text)</pre><p>The same classification task with claude-sonnet-5:</p><pre>Language  Model            HTTP  Rows  Input tokens  Output tokens  Response time<br>--------  ---------------  ----  ----  ------------  -------------  -------------<br>English   claude-sonnet-5  200   10    254           424            5.4 s<br>Japanese  claude-sonnet-5  200   10    334           621            7.0 s</pre><p>There are two reasons for writing the client this way.</p><h4>3.4.1 The httpx.Client Example on the Inference Page Raised a TypeError</h4><p>The Anthropic example on the inference page passes http_client=httpx.Client(...). With SDK 2.4.0, creating the client failed:</p><pre>TypeError: Invalid `http_client` argument; `httpx.Client` is from the `httpx` package, but this SDK uses `httpx2`. Use `httpx2.Client` instead.</pre><p>Switching to auth_token, as in the observability page example, returned HTTP 200. I did not check which SDK version switched to httpx2.</p><h4>3.4.2 content[0] Is Not Always Text</h4><p>With claude-sonnet-5, content came back as a thinking block followed by a text block, even without the thinking parameter. This happened in both the English and Japanese runs. Reading content[0].text raises an AttributeError. As in the example above, it is safer to look for the block where type == &quot;text&quot;. I did not confirm whether this comes from the gateway or from the model&#39;s default behavior.</p><h3>3.5 Streaming</h3><p><strong>Streaming (SSE) worked with the normal SDK code.</strong> With stream_options={&quot;include_usage&quot;: True}, the last chunk carries the token counts.</p><pre>stream = client.chat.completions.create(<br>    model=&quot;openai-gpt-6-astra&quot;,<br>    stream=True,<br>    stream_options={&quot;include_usage&quot;: True},<br>    messages=[{&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;In three sentences for middle-school students, explain why snowflakes are hexagonal.&quot;}],<br>)<br>for event in stream:<br>    if event.choices and event.choices[0].delta.content:<br>        print(event.choices[0].delta.content, end=&quot;&quot;)<br>    if event.usage:<br>        print(f&quot;\ninput {event.usage.prompt_tokens} / output {event.usage.completion_tokens}&quot;)</pre><p>In testing (with a Japanese prompt), I received 107 chunks. The first text arrived after 7.7 seconds, and the whole response took 11.9 seconds. Token counts were 28 input and 259 output. The Japanese text arrived intact.</p><h3>3.6 How Errors Come Back</h3><p><strong>Using the wrong API format for a model now returns HTTP 400 with a message that explains the cause.</strong> In my preview testing, the same case returned HTTP 503.</p><pre>Request                                  HTTP  Message<br>---------------------------------------  ----  --------------------------------------------------<br>Claude sent to Chat Completions          400   the requested model does not support this endpoint<br>OpenAI model sent to Messages            400   the requested model does not support this endpoint<br>gemini-4-argon sent to Chat Completions  400   unknown model &quot;gemini-4-argon&quot;<br>max_tokens sent to openai-gpt-5.6-terra  400   Use &#39;max_completion_tokens&#39; instead.<br>A model name that doesn&#39;t exist          401   Empty body<br>No authorization header                  401   Empty body</pre><p>Three takeaways:</p><ul><li>gemini-4-argon became GA the same day, but its Cortex Inference column in the model availability table is empty. Not being able to call it through the gateway matches the documentation. A model that works in AI Functions doesn&#39;t necessarily work through the gateway.</li><li>Newer OpenAI models require max_completion_tokens, even on Chat Completions. OpenAI&#39;s error body is passed through as-is.</li><li>A model name that doesn’t exist returned the same empty-body 401 as a missing authorization header, in both of two runs. When you see a 401, check the model name as well as the token.</li></ul><p>Separately, the very first call right after registering a public key on the test user returned 401 once, and retries immediately afterward returned 200. I don’t know whether this was key propagation or a transient failure.</p><h3>3.7 Using It from Coding Agents</h3><p><strong>The documentation describes launching a coding agent routed through the gateway with the Snowflake CLI </strong><strong>snow ai command.</strong></p><pre>snow ai opencode</pre><p>To configure OpenCode yourself, add the gateway as a provider in ~/.config/opencode/opencode.json; the documentation includes an example. I did not test coding-agent connections this time.</p><h3>4. Traces: What Happened</h3><h3>4.1 Trace Structure and Privileges</h3><p><strong>The gateway records an OpenTelemetry span for each request it serves, readable with </strong><strong>AGENT_TRACE_TABLE.</strong></p><pre>conversation_id   A conversation, from the x-snowflake-ai-gateway-conversation-id header (optional)<br>└── trace_id      One turn, from the traceparent header<br>    └── span      One inference call, gen_ai.operation.name = &#39;chat&#39;</pre><p>What you can see depends on privileges:</p><pre>Privilege                            Spans returned by AGENT_TRACE_TABLE<br>-----------------------------------  -----------------------------------<br>MONITOR or OWNERSHIP on the gateway  All users&#39; spans<br>USAGE on the gateway only            Your own spans only</pre><p>By default, only request metadata is recorded. Prompt and response bodies are captured only if you enable capture in the gateway specification. <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability">Observability for Cortex AI Gateway</a></p><h3>4.2 Commonly Used Columns and Attributes</h3><pre>Expression                                                     Meaning<br>-------------------------------------------------------------  -------------------------------------------------------<br>trace:&quot;trace_id&quot;                                               ID of one turn; taken directly from traceparent<br>record:&quot;status&quot;:&quot;code&quot;                                         STATUS_CODE_OK, STATUS_CODE_ERROR, or STATUS_CODE_UNSET<br>record:&quot;status&quot;:&quot;message&quot;                                      Reason for a failure<br>resource_attributes:&quot;user&quot;                                     The user who sent the request<br>record_attributes:&quot;gen_ai.request.model&quot;                       The requested model; unknown if it couldn&#39;t be resolved<br>record_attributes:&quot;gen_ai.conversation.id&quot;                     Conversation ID<br>record_attributes:&quot;gen_ai.usage.input_tokens&quot; / output_tokens  Input and output tokens<br>record_attributes:&quot;http.status_code&quot;                           HTTP status</pre><p>Prompt cache token counts (such as cache_read) are subsets of input_tokens. Adding them would count those tokens twice.</p><h3>4.3 Counting Successes and Failures per Conversation</h3><pre>SELECT record_attributes:&quot;gen_ai.conversation.id&quot;::string AS conversation_id,<br>       COUNT_IF(record:&quot;status&quot;:&quot;code&quot;::string = &#39;STATUS_CODE_OK&#39;)    AS ok_spans,<br>       COUNT_IF(record:&quot;status&quot;:&quot;code&quot;::string = &#39;STATUS_CODE_ERROR&#39;) AS error_spans<br>FROM TABLE(AGENT_TRACE_TABLE(&#39;SNOWFLAKE&#39;))<br>WHERE timestamp &gt;= DATEADD(&#39;day&#39;, -1, CURRENT_TIMESTAMP())<br>GROUP BY 1<br>ORDER BY 1;</pre><p>To see why requests failed, aggregate by record:&quot;status&quot;:&quot;message&quot; and model:</p><pre>SELECT record:&quot;status&quot;:&quot;code&quot;::string                   AS status,<br>       record:&quot;status&quot;:&quot;message&quot;::string                AS status_message,<br>       record_attributes:&quot;gen_ai.request.model&quot;::string AS req_model,<br>       COUNT(*)                                         AS spans<br>FROM TABLE(AGENT_TRACE_TABLE(&#39;SNOWFLAKE&#39;))<br>WHERE timestamp &gt;= DATEADD(&#39;day&#39;, -1, CURRENT_TIMESTAMP())<br>GROUP BY ALL<br>ORDER BY 1, 3;</pre><h3>4.4 What I Found in Testing</h3><h4>4.4.1 Failures Are Recorded Immediately, with Reasons</h4><p>Every HTTP 400 error from Section 3.6 was recorded right away as a STATUS_CODE_ERROR span. status.message was mostly client_error. The documentation says it is either client_error or server_error, but for the max_completion_tokens error it contained the full error message.</p><p>The traceparent ID sent by the client also appeared unchanged as the span&#39;s trace_id, so you can join application logs with gateway records on the same ID.</p><p>Requests that returned 401, however, left no span and no usage history row. To audit authentication failures, you need a record other than traces.</p><h4>4.4.2 Some Successful Requests Had No Span</h4><p><strong>In testing, some requests that returned HTTP 200 never showed up in </strong><strong>AGENT_TRACE_TABLE.</strong></p><pre>Item                       Result<br>-------------------------  ------------------------------------------------------------------<br>Successful spans recorded  19<br>HTTP 400 failure spans     All 10 recorded<br>Missing examples           6 of the earliest requests, including classification and streaming<br>Last check                 About 1 hour 45 minutes after the first request</pre><p>Spans for later requests were recorded within 15 minutes, including a long request that took 54 seconds. I found no difference between the official SDKs and direct httpx calls, or between models (openai-gpt-6-astra, claude-sonnet-5, openai-gpt-5-nano, claude-haiku-4-5).</p><p>The documentation says the gateway records traces for all requests traversing it. I don’t yet know whether this is a long ingestion delay or missing records. <strong>For now, don’t treat traces as the only basis for counts or audits; reconcile counts against usage history.</strong> I will update this article when I know the cause.</p><h3>4.5 Sending Client Traces to the Gateway</h3><p><strong>With GA, applications can send their own OpenTelemetry traces to the gateway and see them in the same table as the gateway’s spans.</strong> The following comes from the documentation; I did not test it this time.</p><p>Enable enable_client_telemetry in the gateway specification:</p><pre>ALTER AI GATEWAY SNOWFLAKE FROM SPECIFICATION $$<br>schema_version: 1<br>models:<br>  - name: &#39;*&#39;<br>logging:<br>  enabled: true<br>  enable_client_telemetry: true<br>$$;</pre><p><strong>FROM SPECIFICATION replaces the whole specification.</strong> Before running it, save the current settings from DESCRIBE AI GATEWAY SNOWFLAKE and add one line to them. The example above adds it to the default settings.</p><p>Export to &lt;gateway-endpoint&gt;/telemetry/v1/traces over http/protobuf or http/json, with the same Bearer token as inference. If the application sends traceparent on its inference calls, its spans and the gateway&#39;s spans share a trace_id. The documentation includes setup examples for OpenCode, the Claude SDKs, and Claude Code.</p><p>In my previous article, this endpoint returned 404. However, there is no record that enable_client_telemetry was enabled at the time, so it needs to be retested.</p><h3>4.6 Trace Analytics (Preview)</h3><p>Alongside GA, an <strong>Analytics</strong> tab was added in preview to the gateway’s Observability page in Snowsight. It charts model usage, failures and latency, MCP tool calls, and conversation length without SQL. <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability/trace-analytics">Trace analytics</a></p><p>I did not check it in the UI this time.</p><h3>4.7 Cost of Traces</h3><p>Traces are stored in an event table, so you pay for the serverless compute that ingests them and the storage they occupy. Capturing prompt and response bodies increases the data per request. Each record is capped at 1 MB; larger records are truncated in the middle.</p><h3>5. Usage History: How Much Was Used</h3><h3>5.1 Columns of AI_GATEWAY_USAGE_HISTORY</h3><p><strong>Per-request token counts and credits are recorded in </strong><strong>SNOWFLAKE.ACCOUNT_USAGE.AI_GATEWAY_USAGE_HISTORY.</strong> In testing, rows appeared within minutes of each request.</p><p>Actual columns from DESC VIEW:</p><pre>Column                     Type              Meaning<br>-------------------------  ----------------  ------------------------------------------------------<br>START_TIME                 TIMESTAMP_LTZ     Time of the request (rounded to the minute in testing)<br>GATEWAY_ID / GATEWAY_NAME  NUMBER / VARCHAR  Gateway<br>USER_ID                    NUMBER            The user who sent the request<br>SERVICE_TYPE               VARCHAR           AI_INFERENCE in testing<br>REQUEST_ID                 VARCHAR           Request ID<br>OPERATION_DETAILS          OBJECT            Token counts per model<br>CREDITS                    NUMBER            Credits consumed<br>CREDITS_GRANULAR           OBJECT            Credits per model<br>METADATA                   OBJECT            Other information</pre><p><strong>At test time, this partly differed from the documented column list.</strong> The documentation listed no START_TIME, and showed GATEWAY_ID and USER_ID as TEXT. When writing joins or comparisons, check the actual view with DESC VIEW.</p><h3>5.2 One Request’s Record</h3><p>The Japanese classification request from Section 3.3 was recorded like this:</p><pre>START_TIME          : 2026-11-04 00:02:00<br>SERVICE_TYPE        : AI_INFERENCE<br>OPERATION_DETAILS   : {&quot;openai-gpt-6-astra&quot;: {&quot;input_tokens&quot;: 246, &quot;output_tokens&quot;: 461}}<br>CREDITS             : 0.012755<br>CREDITS_GRANULAR    : {&quot;openai-gpt-6-astra&quot;: 0.012755}</pre><p>These token counts match the usage returned in the API response.</p><p><strong>For </strong><strong>claude-sonnet-5, however, the output token counts did not match.</strong> The Japanese classification request reported 334 input and 621 output tokens in the API usage, but usage history recorded 334 input and 732 output. I could not confirm whether the 111-token difference comes from the thinking block in Section 3.4.2. When estimating cost, it is safer to use usage history rather than the API usage.</p><h3>5.3 Aggregating by Model and by User</h3><p>Expand OPERATION_DETAILS with FLATTEN to aggregate by model:</p><pre>SELECT f.key                                AS model,<br>       COUNT(*)                             AS requests,<br>       SUM(f.value:&quot;input_tokens&quot;::number)  AS input_tokens,<br>       SUM(f.value:&quot;output_tokens&quot;::number) AS output_tokens,<br>       SUM(h.credits)                       AS credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.AI_GATEWAY_USAGE_HISTORY h,<br>     LATERAL FLATTEN(h.operation_details) f<br>WHERE h.start_time &gt;= DATEADD(&#39;day&#39;, -30, CURRENT_TIMESTAMP())<br>GROUP BY 1<br>ORDER BY credits DESC;</pre><p>To see user names, join ACCOUNT_USAGE.USERS on USER_ID:</p><pre>SELECT u.name         AS user_name,<br>       COUNT(*)       AS requests,<br>       SUM(h.credits) AS credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.AI_GATEWAY_USAGE_HISTORY h<br>JOIN SNOWFLAKE.ACCOUNT_USAGE.USERS u ON u.user_id = h.user_id<br>WHERE h.start_time &gt;= DATEADD(&#39;day&#39;, -30, CURRENT_TIMESTAMP())<br>GROUP BY 1<br>ORDER BY credits DESC;</pre><p>Usage is attributed to the user whose token made the request. If several applications share one PAT, you can’t tell which application used what. Giving each application its own service user turns this query into a per-application cost report.</p><h3>6. Setting Up Cost Management</h3><h3>6.1 Budgets vs. Per-User Quotas</h3><p><strong>Use a budget to track spend by team, and a per-user quota to actually stop usage.</strong></p><pre>Control                 Scope                                 When the threshold is reached                   How fast<br>----------------------  ------------------------------------  ----------------------------------------------  -------------------------------------------------------------------------<br>Shared resource budget  A group of users identified by a tag  Notification, plus stored procedures you write  Periodic evaluation; up to 6.5 hours (1 hour with the low-latency option)<br>Per-user quota          Each user (limits are never pooled)   Built-in blocking                               Within minutes</pre><p><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/cost-management">Cost management for Cortex AI Gateway</a></p><h3>6.2 Defining a Team with a Tag and Adding It to a Budget and a Quota</h3><p>In testing, I tagged a user and scoped a budget and a quota to users with that tag. The following SQL is the same procedure with names and limits replaced (the test used a 1-credit budget and a 1-credit daily quota). <strong>These are admin statements that change the account: running them creates a budget and a quota.</strong></p><pre>CREATE OR REPLACE TAG MY_DB.MY_SCHEMA.TEAM;<br>ALTER USER APP_USER SET TAG MY_DB.MY_SCHEMA.TEAM = &#39;SALES&#39;;<br><br>-- Budget: track AI Gateway spend by users tagged TEAM=SALES<br>CREATE OR REPLACE SNOWFLAKE.CORE.BUDGET MY_DB.MY_SCHEMA.SALES_BUDGET();<br>CALL MY_DB.MY_SCHEMA.SALES_BUDGET!SET_SPENDING_LIMIT(100);<br>CALL MY_DB.MY_SCHEMA.SALES_BUDGET!SET_USER_TAGS(<br>  [[(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;MY_DB.MY_SCHEMA.TEAM&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;SALES&#39;]],<br>  &#39;UNION&#39;);<br>CALL MY_DB.MY_SCHEMA.SALES_BUDGET!ADD_SHARED_RESOURCE(&#39;AI GATEWAY&#39;);<br>CALL MY_DB.MY_SCHEMA.SALES_BUDGET!GET_BUDGET_SCOPE();<br>-- Per-user quota: up to 10 credits per day for each user with the same tag<br>CREATE OR REPLACE SNOWFLAKE.CORE.QUOTA MY_DB.MY_SCHEMA.SALES_QUOTA();<br>CALL MY_DB.MY_SCHEMA.SALES_QUOTA!ADD_SHARED_RESOURCE(&#39;AI GATEWAY&#39;);<br>CALL MY_DB.MY_SCHEMA.SALES_QUOTA!SET_USER_TAGS(<br>  [[(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;MY_DB.MY_SCHEMA.TEAM&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;SALES&#39;]],<br>  &#39;UNION&#39;);<br>CALL MY_DB.MY_SCHEMA.SALES_QUOTA!SET_PER_USER_LIMIT(10, &#39;DAILY&#39;);<br>-- Check the configuration<br>CALL MY_DB.MY_SCHEMA.SALES_QUOTA!GET_QUOTA_SCOPE();<br>CALL MY_DB.MY_SCHEMA.SALES_QUOTA!GET_USERS();</pre><p><strong>The SQL above does not stop usage when the limit is exceeded.</strong> To block, call SET_BLOCK_ENFORCEMENT_ENABLED(TRUE, TRUE) on the quota (the second argument controls notifications to users). I did not enable blocking in this test, and I did not test notifications or blocking when a limit is reached. <a href="https://docs.snowflake.com/en/user-guide/budgets/per-user-quotas">Per-user quotas</a></p><h3>6.3 What I Found in Testing</h3><p><strong>Both </strong><strong>ADD_SHARED_RESOURCE(&#39;AI GATEWAY&#39;) calls completed without errors.</strong> GET_QUOTA_SCOPE showed:</p><pre>&quot;shared_resources&quot;: [<br>  {<br>    &quot;domain&quot;: &quot;AI_GATEWAY&quot;,<br>    &quot;id&quot;: -1,<br>    &quot;name&quot;: &quot;[ALL-AI GATEWAYS]&quot;<br>  }<br>]</pre><p>Two more findings:</p><ul><li><strong>Limits must be positive integers.</strong> SET_PER_USER_LIMIT(0.5, &#39;DAILY&#39;) failed with:</li></ul><pre>Invalid per-user limit. It must be a positive integer no greater than 1000000000.</pre><ul><li><strong>Target users take time to resolve.</strong> GET_USERS returned zero rows right after creating the quota, and returned the test user about 15–17 minutes later. According to the documentation, configuration takes about 5–10 minutes to propagate, and users identified by tag can take up to about 2 hours to appear in GET_USERS. Don&#39;t design operations that assume a setting takes effect immediately.</li></ul><h3>6.4 Letting Users Check Their Own Limits</h3><p><strong>With </strong><strong>MY_BUDGET_SUMMARY(), users can check the quotas that apply to them without asking an administrator.</strong> It became GA on October 28, 2026.</p><pre>SELECT name, cycle, per_user_limit, usage, usage_unit, percent_consumed, status, end_time<br>FROM TABLE(SNOWFLAKE.LOCAL.MY_BUDGET_SUMMARY())<br>ORDER BY name, cycle;</pre><p>It returns one row for each cycle (daily, weekly, monthly) that has a limit. Key columns:</p><pre>Column                  Meaning<br>----------------------  --------------------------------------------------------------<br>NAME / DOMAINS          Quota name and scope (AI FUNCTION, CORTEX AGENT, and so on)<br>CYCLE                   DAILY, WEEKLY, or MONTHLY<br>PER_USER_LIMIT / USAGE  The limit and usage in the current cycle<br>USAGE_UNIT              AI_CREDITS for AI functions and agents, CREDITS for warehouses<br>PERCENT_CONSUMED        Percentage consumed<br>STATUS                  BLOCKED when blocked, otherwise NULL</pre><p>On October 29, it returned results like these (quotas with Japanese names: “AI functions, Sales” and “Agents, company-wide”):</p><pre>NAME               CYCLE    PER_USER_LIMIT  USAGE   USAGE_UNIT  PERCENT_CONSUMED<br>-----------------  -------  --------------  ------  ----------  ----------------<br>AIfunctions_sales  DAILY       100         0.0045  AI_CREDITS  0.0<br>AIfunctions_sales  MONTHLY     1000        2.762   AI_CREDITS  0.28<br>Agents_Company     MONTHLY     3000        28.269  AI_CREDITS  0.94</pre><p>Findings:</p><ul><li>No privileges are needed to call the function, but it needed a warehouse. With the PUBLIC role and no warehouse, it failed with No active warehouse selected. A role with only USAGE on a warehouse could call it.</li><li>USAGE included usage in the current cycle from before the quota was created. The company-wide agent quota above exceeded 28 credits right after creation.</li><li>A new WAREHOUSE quota was missing at the first check after creation and appeared about 6 minutes later. After I dropped the schema containing the quotas, rows took about 28 minutes to disappear. Don’t rely on results right after creating or deleting a quota.</li><li>Quotas with Japanese names displayed correctly, and Japanese LIKE filters worked.</li><li>I tested AI FUNCTION, CORTEX AGENT, and WAREHOUSE quotas. I have not confirmed that AI GATEWAY quotas appear in this function.</li></ul><p>One way to use it: run it at the top of a notebook, and if the monthly percentage is high, postpone large batch jobs to the next month.</p><h3>7. Tools for Cortex AI Gateway (Preview)</h3><h3>7.1 What It Does</h3><p><strong>Tools connects AI clients to your business tools through MCP, and lets administrators decide what they can reach.</strong></p><pre>Capability             Details<br>---------------------  ---------------------------------------------------------------------------------------------------------------------<br>Enable from a catalog  MCP servers for Atlassian, GitHub, Google Workspace, Salesforce, Slack, Snowflake, and more<br>Distribute to users    Grant the SNOWFLAKE$OPS.MCP$USER database role to a role, and CoCo Desktop and CLI discover the servers automatically<br>Limit tools            Choose which tools each server exposes (for example, read-only tools only)<br>Custom MCP servers     Add one by URL<br>Review activity        AGENT_TRACE_TABLE or Activity</pre><p>It works with MCP-capable agents such as CoCo (CLI and Desktop), ChatGPT, Claude, and Cursor. Currently, only ACCOUNTADMIN can administer it. It is available in AWS commercial regions only, excluding Asia Pacific (New Zealand) and Middle East (UAE). Note that the gateway itself is available in New Zealand, but Tools is not. <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/tools">Tools</a></p><p>Tools connects AI clients outward to business tools. To expose Snowflake data to an external AI client instead, use the separate Snowflake-managed MCP server feature.</p><h3>7.2 What I Checked with SQL Before Enabling Anything</h3><p><strong>Enabling servers, adding custom MCP servers, and limiting tools are done in Snowsight.</strong> SQL covers two things: granting access and reviewing activity.</p><p>First, on October 30, I tried SQL without doing anything in Snowsight.</p><pre>Check                                   Result<br>--------------------------------------  ---------------------------------------------------------------------------------------------------<br>Does the SNOWFLAKE$OPS database exist?  Not found, even as ACCOUNTADMIN<br>Can MCP$USER be granted to a role?      Failed with Database &#39;SNOWFLAKE$OPS&#39; does not exist or not authorized.<br>Is there a Tools-specific SQL command?  SHOW AI GATEWAY TOOLS was a syntax error; none found<br>SHOW MCP SERVERS                        Lists Snowflake-managed MCP servers created with CREATE MCP SERVER, separate from the Tools catalog<br>Tool-call spans                         None (only inference spans were recorded)</pre><p>The documentation doesn’t say when SNOWFLAKE$OPS is created. So on November 4, I enabled one server in Snowsight and checked again. I used the Draw.io server, which the catalog lists with no authentication (Authentication: None). <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/tools/available-servers">Available MCP servers</a></p><h3>7.3 Enabling a Server in Snowsight</h3><h4>7.3.1 Opening the MCP Server List</h4><p><strong>On the AI Gateway screen, open “ACCOUNT &gt; MCP Servers” in the left menu to see the catalog servers.</strong> Before I enabled anything, every server visible in the list was Disabled (No tools).</p><p>The menu also has “USER &gt; MCP Connections” for end users and “Activity” for tool calls. <strong>Add custom server</strong> in the upper right adds a server that isn’t in the catalog. The Tools release note (October 19) gave the path as <strong>AI &amp; ML &gt; AI Gateway &gt; MCP &amp; Tools</strong>; the current documentation says <strong>AI Gateway &gt; MCP &amp; Tools</strong>. Menu names can change, so check the screen.</p><h4>7.3.2 Enabling Draw.io and Copying Its URL</h4><p><strong>Clicking “Enable” on Draw.io changes it to Enabled (All tools), and “Copy URL” gives you the connection URL.</strong></p><p>The URL had this form, with a per-server path under the gateway endpoint:</p><pre>https://&lt;org&gt;-&lt;account&gt;.snowflakecomputing.com/api/v2/aigateways/snowflake/v1/mcp/gateway/v2/profile/default/drawio/mcp</pre><h3>7.4 The SNOWFLAKE$OPS Database and Privileges</h3><p><strong>After I enabled the server, the </strong><strong>SNOWFLAKE$OPS database existed.</strong> Its created_on in SHOW DATABASES was a time on the day I enabled Draw.io (November 4).</p><p>After I granted USAGE on the database, the schema, and the MCP server in that order, SHOW DATABASE ROLES, which had failed on October 30, succeeded and returned MCP$ADMIN and MCP$USER. <strong>The following are the account-changing statements I ran in the test.</strong></p><pre>GRANT USAGE ON DATABASE SNOWFLAKE$OPS TO ROLE ACCOUNTADMIN;<br>GRANT USAGE ON SCHEMA SNOWFLAKE$OPS.MCP TO ROLE ACCOUNTADMIN;<br>GRANT USAGE ON MANAGED MCP SERVER SNOWFLAKE$OPS.MCP.&quot;DRAWIO&quot; TO ROLE ACCOUNTADMIN;</pre><pre>SHOW DATABASE ROLES IN DATABASE SNOWFLAKE$OPS;</pre><pre>| name      | is_inherited |<br>| MCP$ADMIN | Y            |<br>| MCP$USER  | Y            |</pre><p>Two takeaways:</p><ul><li>The enabled server was handled as a MANAGED MCP SERVER object in the SNOWFLAKE$OPS.MCP schema. This syntax is not in the documentation; it is what worked in my test.</li><li>SNOWFLAKE$OPS became visible before I granted anything. I didn&#39;t separate whether SHOW DATABASE ROLES succeeded because of the grants or because the database now existed.</li></ul><h3>7.5 Calling It from an AI Client</h3><h4>7.5.1 Adding the URL to the MCP Configuration</h4><p><strong>In Cortex Code’s </strong><strong>mcp.json, it worked with the same </strong><strong>type: http entry as other remote MCP servers.</strong></p><pre>&quot;drawio&quot;: {<br>  &quot;type&quot;: &quot;http&quot;,<br>  &quot;url&quot;: &quot;https://&lt;org&gt;-&lt;account&gt;.snowflakecomputing.com/api/v2/aigateways/snowflake/v1/mcp/gateway/v2/profile/default/drawio/mcp&quot;<br>}</pre><p>I wrote the URL by hand this time. I did not test whether CoCo Desktop or CLI discovers the server automatically for a user whose role has MCP$USER (Section 7.7).</p><h4>7.5.2 Listing the Tools</h4><p>With a PAT as the Bearer token, I sent the MCP initialize and tools/list requests from a Python script. Both returned HTTP 200; the server identified itself as natoma-proxy 0.1.0 and listed three tools:</p><pre>Tool                  Purpose<br>--------------------  -------------------------------------------------<br>create_diagram        Create a diagram<br>search_shapes         Search for shapes<br>get_drawio_reference  Return reference information for writing diagrams</pre><p><strong>The tool names differ from those of a locally run draw.io MCP server.</strong> Right after I switched the configuration, the client called an old tool name (open_drawio_mermaid) and got:</p><pre>-32601: Tool open_drawio_mermaid is not available for this server</pre><p>After switching to the gateway’s server, reload the client’s tool list, for example by restarting the client.</p><h4>7.5.3 Creating a Diagram</h4><p>Passing a Mermaid flowchart to create_diagram returned HTTP 200 with a URL that opens in draw.io. The diagram is not stored on the server or locally; its data is embedded in the URL.</p><h3>7.6 Reviewing Tool-Call Records</h3><p><strong>Tool calls were recorded in the same </strong><strong>AGENT_TRACE_TABLE as inference, as spans with </strong><strong>gen_ai.operation.name = &#39;execute_tool&#39;.</strong> Inference spans are chat, so this value tells them apart.</p><pre>SELECT start_timestamp,<br>       resource_attributes:&quot;snow.user.name&quot;::string  AS user_name,<br>       record_attributes:&quot;snow.mcp.server.id&quot;::string AS mcp_server,<br>       record_attributes:&quot;gen_ai.tool.name&quot;::string   AS tool_name,<br>       record:&quot;status&quot;:&quot;code&quot;::string                AS status,<br>       DATEDIFF(&#39;millisecond&#39;, start_timestamp, timestamp) AS duration_ms<br>FROM TABLE(SNOWFLAKE.LOCAL.AGENT_TRACE_TABLE(&#39;SNOWFLAKE&#39;))<br>WHERE record_attributes:&quot;gen_ai.operation.name&quot;::string = &#39;execute_tool&#39;<br>  AND start_timestamp &gt;= DATEADD(&#39;day&#39;, -7, CURRENT_TIMESTAMP())<br>ORDER BY start_timestamp DESC<br>LIMIT 100;</pre><pre>| START_TIMESTAMP            | USER_NAME | MCP_SERVER | TOOL_NAME      | STATUS         | DURATION_MS |<br>| 2026-11-04 11:10:28.797000 | &lt;user&gt;    | Draw.io    | create_diagram | STATUS_CODE_OK | 697         |</pre><pre>Attribute                                  Meaning<br>-----------------------------------------  ---------------------------------<br>record_attributes:&quot;gen_ai.operation.name&quot;  execute_tool for tool calls<br>record_attributes:&quot;snow.mcp.server.id&quot;     Server name (Draw.io in the test)<br>record_attributes:&quot;gen_ai.tool.name&quot;       Tool name<br>resource_attributes:&quot;snow.user.name&quot;       The calling user</pre><p>Three findings:</p><ul><li>Filtering on execute_tool, only tools/call (the actual tool call) was recorded. I did not check whether initialize and tools/list are recorded under a different value.</li><li>Within the same filter, the call that failed with -32601 because of the old tool name did not appear.</li><li>The span was visible when I checked about two and a half minutes after the call (approximate).</li></ul><p>For inference spans, the user is in resource_attributes:&quot;user&quot;, as documented. Tool spans had the user in snow.user.name (I did not check whether user is also present). The attribute table above shows observed values; none of them, including execute_tool, appears in the documentation.</p><h4>7.6.1 Viewing It on the Activity Screen in Snowsight</h4><p><strong>Without writing SQL, you can chart tool usage under “ACCOUNT &gt; Activity” in the left menu.</strong></p><p>The Dashboard tab showed four charts:</p><pre>Chart                          Meaning                                                              What it showed in the test<br>-----------------------------  -------------------------------------------------------------------  --------------------------<br>Installations per MCP Server   Top 5 servers by installations                                       Draw.io: 1<br>Total Tool Calls               Tool calls over time (per day over 7 and 30 days, per week over 90)  1 call on November 4<br>Top MCP Servers by Tool Calls  Most active servers in the last 30 days                              Draw.io: 1<br>Top Users by Tool Calls        Top 10 users by tool calls in the last 30 days                       The test user: 1</pre><p>The single tool call matches the one create_diagram call found with the SQL in Section 7.6. A <strong>Connections</strong> tab sits at the top of the screen, but I did not open it.</p><p>This screen is enough for a quick look at which servers are used and who uses them most. For narrower time ranges, failed calls, or durations, the SQL in Section 7.6 is the better fit.</p><h3>7.7 What I Did Not Test</h3><p>The following were outside the scope of this test:</p><pre>Item                                                                                                                 Status<br>-------------------------------------------------------------------------------------------------------------------  -----------<br>Granting MCP$USER to a role other than ACCOUNTADMIN, and whether CoCo Desktop / CLI discovers servers automatically  Not tested<br>Narrowing exposed tools with a tool policy                                                                           Not tested<br>Adding a custom MCP server (per the docs, the URL must end in /mcp and support streamable HTTP and OAuth)            Not tested<br>Servers that need third-party authorization, such as GitHub or Slack                                                 Not tested<br>The Connections tab of the Activity screen                                                                           Not checked</pre><h3>8. What to Check Before Adopting</h3><p><strong>With GA, basic inference and cost-management setup worked, but these points are worth checking in your own environment:</strong></p><pre>What to check                                                                                            Section<br>-------------------------------------------------------------------------------------------------------  --------<br>Does the model you want work through the gateway with the API format you want?                           3.1, 3.6<br>Do your SDK version and sample code match?                                                               3.4<br>When you get a 401, do you check both the token and the model name?                                      3.6<br>Do you reconcile trace counts against usage history?                                                     4.4.2<br>Do you estimate cost from usage history rather than the API usage?                                       5.2<br>Does each application use its own user so usage can be attributed?                                       5.3<br>Are budgets used for notification and quotas for blocking, with quota blocking enabled?                  6.1, 6.2<br>Have you allowed time for quota target users to resolve?                                                 6.3<br>For Tools, is your region supported, and did you enable the server in Snowsight before granting access?  7.1, 7.4<br>After switching to the gateway&#39;s server, did you reload the client&#39;s tool list?                          7.5.2<br>Can you review tool calls on the Activity screen or from execute_tool spans?                             7.6</pre><h3>9. References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway">Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/inference">Inference with Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability">Observability for Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability/trace-analytics">Trace analytics for Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/cost-management">Cost management for Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/tools">Tools</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/account-usage/ai_gateway_usage_history">AI_GATEWAY_USAGE_HISTORY</a></li><li><a href="https://docs.snowflake.com/en/user-guide/budgets/per-user-quotas">Per-user quotas</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/functions/my_budget_summary-snowflake-local">MY_BUDGET_SUMMARY</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-11-03-cortex-ai-gateway-ga">Release note: GA (November 3, 2026)</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-10-19-cortex-ai-gateway-tools">Release note: Tools (October 19, 2026)</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-10-16-cortex-ai-gateway-regions">Release note: New regions (October 16, 2026)</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-10-28-my-budget-summary">Release note: MY_BUDGET_SUMMARY (October 28, 2026)</a></li></ul><h3>10. Takeaways and Future Updates</h3><p><strong>With GA, Cortex AI Gateway has moved from an entry point you can try to an entry point for managing production AI usage.</strong></p><p>You can call it with the standard OpenAI and Anthropic SDKs, and errors now explain their cause more clearly. Usage is recorded per request with token counts and credits, and can be managed with budgets and per-user quotas. Users can check their remaining allowance with MY_BUDGET_SUMMARY. With Tools, after enabling a server in Snowsight and granting privileges, I could call it as an MCP server through the gateway, and those calls were recorded in traces. The gateway is starting to govern access to business tools as well as models.</p><p>Some items, such as successful requests missing from traces, are still under investigation. Tools and the Responses API are in public preview, and trace analytics is in preview (checked November 4, 2026). I confirmed the basic Tools flow with Draw.io; next I plan to test distribution to roles, tool policies, and servers that need third-party authorization. As new features arrive, I plan to test them and cover them on this blog.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=4fcaeb030187" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Building Real-Time Card Fraud Detection with Snowflake’s Online Feature Store]]></title>
            <link>https://medium.com/@masato.takada/building-real-time-card-fraud-detection-with-snowflakes-online-feature-store-7b9ef07f6534?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/7b9ef07f6534</guid>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[feature-store]]></category>
            <category><![CDATA[fraud-detection]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Fri, 30 Oct 2026 02:31:06 GMT</pubDate>
            <atom:updated>2026-10-30T02:31:06.194Z</atom:updated>
            <content:encoded><![CDATA[<p><em>Batch, stream, and real-time features in one REST call, with Snowpipe Streaming, ML Jobs, and Snowflake Postgres.</em></p><blockquote><em>I work at Snowflake, but the views expressed in this article are my own and do not represent the official views of my employer.</em></blockquote><blockquote><em>Information checked on October 29, 2026. The Online Feature Store became generally available (GA) on October 20, 2026. It is available in AWS and Azure commercial regions; Google Cloud is not supported. All tests were run in AWS Tokyo (ap-northeast-1).</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/960/1*wNDtfBJ2Jsx2zYeLUjo_Og.gif" /></figure><p><em>The demo’s live monitor, updating each transaction’s decision and latency in real time.</em></p><h3>1. Introduction</h3><p><strong>With Snowflake’s Online Feature Store, you can fetch the features needed for “decide right now” workloads such as card authorization in milliseconds, without leaving Snowflake.</strong> Without a separate Kafka or Redis stack, I retrieved three very different kinds of features — 60-day spending patterns, the card’s tap count over the last five minutes, and the current amount — in a single REST API call.</p><p>In this article I build a real-time card fraud detection demo and cover:</p><ul><li>How to use the three Feature View types (batch, stream, real-time) and Feature Groups</li><li>How they fit together with Snowpipe Streaming, ML Jobs, the Model Registry, and Snowflake Postgres</li><li>Measured latency and model accuracy</li><li>Pitfalls I hit along the way and how I worked around them</li></ul><p>The intended reader has used, or is about to use, ML features in Snowflake. All data is synthetic: 5,000 cards, 800 merchant terminals, and about 2.5 million yen-denominated transactions.</p><p>The demo code is available on GitHub. Code examples in this article are simplified for explanation; see the repository for the full implementation: <a href="https://github.com/sfc-gh-mtakada/fraud_detection_w_feature_store_on_postgres">sfc-gh-mtakada/fraud_detection_w_feature_store_on_postgres</a></p><h3>1.1 Background and Use Cases</h3><p>In card fraud detection, you must approve, hold, or decline the moment a payment terminal asks. This decision is called an <em>authorization</em>. The information you want comes in three time horizons.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/732/1*nb1xPDPSPY4ruazWrQKcag.png" /></figure><p>Traditionally, long-term patterns lived in a data warehouse and recent activity in a stream processor plus a key-value store, with everything stitched together at inference time. The Online Feature Store lets you define all three inside Snowflake and returns them together.</p><h3>1.2 Terms Used in This Article</h3><ul><li><strong>Feature</strong>: a numeric model input, such as “the card’s transaction count over the last 5 minutes.”</li><li><strong>Feature View (FV)</strong>: a unit that bundles feature definitions and computation. There are batch, stream, and real-time types.</li><li><strong>Feature Group</strong>: a versioned set of several FVs. The same set is used for both inference and training.</li><li><strong>Point-in-time join</strong>: a join that, when building training data, uses only values available at each transaction’s timestamp, preventing future data leakage.</li><li><strong>PAT</strong>: Programmatic Access Token, used to call REST APIs without a browser login.</li></ul><h3>2. Online Feature Store Overview</h3><h3>2.1 What It Does</h3><p><strong>The Online Feature Store uses a Snowflake-managed Postgres serving layer and returns the latest feature values over a REST API.</strong> According to the documentation, retrieval latency is typically under 10 ms at P50 (at 2,000 QPS), and end-to-end freshness for stream FVs, from ingest to readable value, is typically under 200 ms at P50.</p><p>The main parts are:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/743/1*IUARPh9PHbZoGMeKPo3hMw.png" /></figure><p>Events ingested into a stream FV are also written back to the offline side (Snowflake tables), so the features used online can be reused to build training data.</p><h3>2.2 Prerequisites and Scope</h3><ul><li>Regions: AWS and Azure commercial regions where Snowflake Postgres is available. GCP, AWS GovCloud, Azure Government, and China regions are not supported.</li><li>Package: snowflake-ml-python&gt;=2.5.</li><li>Authentication: the REST APIs use a PAT or key-pair JWT. A user authenticating with a PAT must be subject to a network policy.</li><li>Size: XS through 3XL. XS runs on a single node without high availability and cannot be resized later, so it is meant for testing and development. I used XS for this article.</li></ul><h3>3. Demo Architecture</h3><h3>3.1 Architecture Diagram</h3><p><strong>A simulator acts as the payment switch and sends each transaction down two paths: a decision path and a data platform path.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*gJVfTZr9ujioAY4Httjfpg.png" /><figcaption>Overall Architecture Diagram</figcaption></figure><p>Solid lines are data flows; dotted lines are feature reads.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/994/1*ADlKBMP0ebN4dG5Dk5I4OQ.png" /></figure><p>Snowflake Postgres appears twice: once as the Snowflake-managed serving layer behind the Online Feature Store, and once as the OLTP instance I created for the app’s decision log. Both live inside Snowflake, so decisions, storage, analytics, and training all run in one account.</p><h3>3.2 Why Two Ingestion Paths</h3><p><strong>The documented way to send online data into a stream FV is the Feature Store Ingest REST API.</strong> Snowpipe Streaming is not documented as an input for stream FVs, so I split the responsibilities.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1009/1*VNzCfwzJN1ke_wGXJBtYSg.png" /></figure><p>Only the columns needed for the decision go through the low-latency path; the full record lands in a table through Snowpipe Streaming.</p><h3>4. Feature Design and Implementation</h3><h3>4.1 Feature Views</h3><p><strong>Long-term patterns go to a batch FV, recent activity to stream FVs, and comparison with the current amount to a real-time FV.</strong> Feature names follow conventions common in fraud detection.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/998/1*5P_P31lUZdKtOPXYMmWQng.png" /></figure><p>ACCEPTORID_DISTINCT_CARDS_1H uses approx_count_distinct (an approximate distinct count based on HyperLogLog).</p><h3>4.2 Create the Online Service</h3><p><strong>You create one online service per feature store, and billing starts as soon as it exists.</strong> Pass the producer and consumer role names and wait for RUNNING.</p><pre>status = fs.get_online_service_status()<br>if status.status == &quot;NOT_FOUND&quot;:<br>    fs.create_online_service(&quot;FRAUD_FS_PRODUCER&quot;, &quot;FRAUD_FS_CONSUMER&quot;, size=&quot;XS&quot;)<br>    status = fs.get_online_service_status()<br>while status.status != &quot;RUNNING&quot;:<br>    time.sleep(30)<br>    status = fs.get_online_service_status()</pre><p>In this environment, when no service existed, get_online_service_status() did not raise; it returned status set to NOT_FOUND (I could not confirm this behavior in the documentation). Check the status value rather than catching an exception.</p><h3>4.3 Batch FV: 60- and 90-Day Patterns</h3><p><strong>A batch FV takes a Snowflake table as input and defines time-windowed aggregates.</strong> Setting store_type=OnlineStoreType.POSTGRES in OnlineConfig syncs it to the Postgres online store.</p><pre>ONLINE = OnlineConfig(enable=True, target_lag=&quot;1m&quot;, store_type=OnlineStoreType.POSTGRES)<br><br>fv = FeatureView(<br>    name=&quot;CARD_PROFILE&quot;,<br>    entities=[card],<br>    feature_df=src,                 # DataFrame built from RAW.CARD_TRANSACTIONS<br>    timestamp_col=&quot;TS&quot;,<br>    feature_granularity=&quot;1d&quot;,       # 1-day tiles<br>    refresh_freq=&quot;1h&quot;,              # offline refresh interval<br>    features=[<br>        Feature.count(&quot;AMOUNT&quot;, &quot;60d&quot;).alias(&quot;CARDID_COUNT_60D&quot;),<br>        Feature.avg(&quot;AMOUNT&quot;, &quot;60d&quot;).alias(&quot;CARDID_MEAN_AMOUNT_60D&quot;),<br>        Feature.stddev(&quot;AMOUNT&quot;, &quot;60d&quot;).alias(&quot;CARDID_STD_AMOUNT_60D&quot;),<br>        Feature.sum(&quot;IS_CONTACTLESS&quot;, &quot;90d&quot;).alias(&quot;CONTACTLESS_COUNT_90D&quot;),<br>    ],<br>    online_config=ONLINE,<br>)<br>fs.register_feature_view(fv, version=&quot;V1&quot;)</pre><p>refresh_freq is the refresh interval of the offline dynamic table; target_lag is the offline-to-online sync interval. They are independent, so the lag from source to online store is roughly their sum.</p><h3>4.4 Stream FV: 5-Minute and 1-Hour Counts</h3><p><strong>A stream FV registers the event schema with </strong><strong>StreamSource and specifies a transformation function and historical (backfill) data with </strong><strong>StreamConfig.</strong> With FeatureAggregationMethod.CONTINUOUS, aggregates update as each event arrives.</p><pre>stream = StreamSource(<br>    name=&quot;TXN_STREAM&quot;,<br>    schema=StructType([<br>        StructField(&quot;CARD_ID&quot;, StringType()),<br>        StructField(&quot;ACCEPTOR_ID&quot;, StringType()),<br>        StructField(&quot;TS&quot;, TimestampType(TimestampTimeZone.NTZ)),<br>        StructField(&quot;AMOUNT&quot;, DoubleType()),<br>        StructField(&quot;ENTRY_MODE&quot;, StringType()),<br>    ]),<br>)<br>fs.register_stream_source(stream)<br><br>def add_contactless_amount(df: pd.DataFrame) -&gt; pd.DataFrame:<br>    df[&quot;CONTACTLESS_AMOUNT&quot;] = df[&quot;AMOUNT&quot;].where(df[&quot;ENTRY_MODE&quot;] == &quot;CONTACTLESS&quot;, 0.0)<br>    return df<br><br>card_vel = FeatureView(<br>    name=&quot;CARD_VELOCITY&quot;,<br>    entities=[card],<br>    stream_config=StreamConfig(<br>        stream_source=stream,<br>        transformation_fn=add_contactless_amount,<br>        backfill_df=session.table(&quot;FRAUD_DEMO.RAW.TXN_STREAM_BACKFILL&quot;),<br>    ),<br>    timestamp_col=&quot;TS&quot;,<br>    refresh_freq=&quot;1 minute&quot;,<br>    feature_granularity=&quot;1 minute&quot;,<br>    features=[<br>        Feature.count(&quot;AMOUNT&quot;, &quot;5m&quot;).alias(&quot;CARDID_COUNT_5M&quot;),<br>        Feature.count(&quot;AMOUNT&quot;, &quot;1h&quot;).alias(&quot;CARDID_COUNT_1H&quot;),<br>        Feature.sum(&quot;CONTACTLESS_AMOUNT&quot;, &quot;4h&quot;).alias(&quot;CARDID_SUM_AMOUNT_CONTACTLESS_4H&quot;),<br>    ],<br>    online_config=OnlineConfig(enable=True, store_type=OnlineStoreType.POSTGRES),<br>    feature_aggregation_method=FeatureAggregationMethod.CONTINUOUS,<br>)</pre><p>The same transformation function runs at ingest time and during backfill, so live and historical data are computed the same way. Inside the function you can use pandas, numpy, re, copy, and Python built-ins.</p><h3>4.5 Real-Time FV: Current Amount vs. Usual Amount</h3><p><strong>A real-time FV computes features at request time in a Python function, from values passed with the request (here, the current amount) and the latest values of other FVs.</strong> Results are not stored online.</p><pre>def compute_txn_risk(request_df, profile_df, velocity_df):<br>    amt = request_df[&quot;TXN_AMOUNT&quot;].astype(float).reset_index(drop=True)<br>    n = len(amt)<br>    zeros = pd.Series([0.0] * n)<br>    # Rows are omitted for keys with no stored value, so fall back to zeros on a count mismatch<br>    if len(profile_df) == n:<br>        mean = profile_df[&quot;CARDID_MEAN_AMOUNT_60D&quot;].astype(float).fillna(0.0).reset_index(drop=True)<br>        std = profile_df[&quot;CARDID_STD_AMOUNT_60D&quot;].astype(float).fillna(0.0).reset_index(drop=True)<br>    else:<br>        mean, std = zeros, zeros<br>    if len(velocity_df) == n:<br>        cnt5m = velocity_df[&quot;CARDID_COUNT_5M&quot;].astype(float).fillna(0.0).reset_index(drop=True)<br>    else:<br>        cnt5m = zeros<br>    safe_mean = mean.where(mean &gt; 0, amt.where(amt &gt; 0, 1.0))<br>    safe_std = std.where(std &gt; 0, safe_mean)<br>    return pd.DataFrame({<br>        &quot;AMOUNT_TO_MEAN_RATIO&quot;: amt / safe_mean,<br>        &quot;AMOUNT_ZSCORE&quot;: (amt - mean) / safe_std,<br>        &quot;IS_BURST&quot;: (cnt5m &gt;= 4).astype(float),<br>    })<br><br>rt = FeatureView(<br>    name=&quot;TXN_RISK&quot;,<br>    entities=[card],<br>    realtime_config=RealtimeConfig(<br>        compute_fn=compute_txn_risk,<br>        sources=[            RequestSource(schema=StructType([StructField(&quot;TXN_AMOUNT&quot;, DoubleType())])),<br>            reg_profile,    # registered CARD_PROFILE<br>            reg_card_vel,   # registered CARD_VELOCITY<br>        ],<br>        output_schema=StructType([            StructField(&quot;AMOUNT_TO_MEAN_RATIO&quot;, DoubleType()),            StructField(&quot;AMOUNT_ZSCORE&quot;, DoubleType()),            StructField(&quot;IS_BURST&quot;, DoubleType()),        ]),<br>    ),<br>)</pre><p>Function arguments follow the order of sources: first the request values, then the latest values of each FV. Keys with no value in an upstream FV are dropped entirely, so the code checks row counts before using the inputs.</p><h3>4.6 Bundle Them in a Feature Group</h3><p><strong>Bundling the four FVs in a Feature Group gives you one Query API call at inference time and the same set for building training data.</strong></p><pre>fg = FeatureGroup(name=&quot;FRAUD_FG&quot;, features=[reg_profile, reg_card_vel, reg_acc_vel, reg_rt],<br>                  auto_prefix=False)<br>fs.register_feature_group(fg, &quot;V1&quot;)</pre><p>With auto_prefix=False, feature names are not prefixed with the FV name, so feature names must be unique across FVs.</p><p>After registering, check with SHOW ONLINE FEATURE TABLES that each FV&#39;s online table has finished setup. Once setup_status is SETUP_READY, it can serve reads. Even when the online service is RUNNING, individual tables may not be ready yet.</p><h3>5. Flow of a Single Authorization</h3><h3>5.1 Order of Operations</h3><p><strong>When a payment arrives, the code fetches features, scores and decides, ingests, and then records.</strong> Section 5.3 explains why ingest comes after the decision.</p><ol><li>Fetch FRAUD_FG through the Query API, passing the current amount as request_context.</li><li>Feed the 12 retrieved values plus the current amount (TXN_AMOUNT), 13 values in total, into the XGBoost model loaded from the Model Registry at startup and compute a score.</li><li>Compare the score to the thresholds to choose APPROVE, REVIEW, or DECLINE.</li><li>Send the transaction to the stream FVs through the Ingest API.</li><li>Write the decision and features to fraud.auth_decisions in Postgres; REVIEW and DECLINE also go to fraud.cases.</li></ol><h3>5.2 Calling the Query and Ingest APIs</h3><p><strong>Both are a JSON POST with the PAT in the </strong><strong>Authorization header.</strong> Get the endpoint URLs from online_service.endpoint_url().</p><pre>status = fs.get_online_service_status()<br>query_url = online_service.endpoint_url(https://medium.com/status,%20&quot;query&quot;) + &quot;/api/v1/query&quot;<br>ingest_url = online_service.endpoint_url(https://medium.com/status,%20&quot;ingest&quot;) + &quot;/api/v1/ingest&quot;<br>headers = {&quot;Authorization&quot;: f&#39;Snowflake Token=&quot;{pat}&quot;&#39;, &quot;Content-Type&quot;: &quot;application/json&quot;}<br><br># Fetch features (whole Feature Group in one call)<br>body = {<br>    &quot;name&quot;: &quot;FRAUD_FG&quot;, &quot;version&quot;: &quot;V1&quot;, &quot;object_type&quot;: &quot;feature_group&quot;,<br>    &quot;include_diagnostics&quot;: True,<br>    &quot;request_rows&quot;: [{<br>        &quot;entity&quot;: {&quot;CARD_ID&quot;: &quot;C000001&quot;, &quot;ACCEPTOR_ID&quot;: &quot;A00001&quot;},<br>        &quot;request_context&quot;: {&quot;TXN_AMOUNT&quot;: 48000.0},<br>    }],<br>    &quot;metadata_options&quot;: {&quot;include_names&quot;: True},<br>}<br>r = requests.post(query_url, json=body, headers=headers, timeout=10)<br><br># Ingest the transaction event<br>records = [{&quot;CARD_ID&quot;: &quot;C000001&quot;, &quot;ACCEPTOR_ID&quot;: &quot;A00001&quot;,<br>            &quot;TS&quot;: &quot;2026-10-29T05:00:00.000Z&quot;, &quot;AMOUNT&quot;: 48000.0, &quot;ENTRY_MODE&quot;: &quot;CONTACTLESS&quot;}]<br>r = requests.post(ingest_url, json={&quot;records&quot;: {&quot;TXN_STREAM&quot;: records}}, headers=headers, timeout=10)</pre><p>The example above is simplified. The demo code sends metadata_options, which returns feature names, only on the first call.</p><p>With include_diagnostics, the response includes server-side processing time. Comparing it with client-measured time separates out network round-trip time. Per the API references, one request allows up to 50 records per source for the Ingest API and up to 10 entities for the Query API. The demo code batches requests in those units.</p><h3>5.3 Why Read Features Before Ingesting</h3><p><strong>To give stream features the same meaning in training and inference.</strong></p><p>In this environment, point-in-time training data did not include the event at exactly the spine timestamp. For normal transactions, CARDID_COUNT_5M averaged 0.02 in the offline training data. In other words, the training value means &quot;the 5-minute count excluding the current transaction.&quot;</p><p>Ingesting first at inference time would count the current transaction once more and shift the meaning away from training. So the order is fetch → decide → ingest. This design is based on what I observed in this environment, not on a documented specification of point-in-time boundary handling. I recommend comparing training values and online values side by side on your own data.</p><h3>6. Training Flow</h3><h3>6.1 Build Training Data in an ML Job</h3><p><strong>Training ran as an ML Job on a Container Runtime compute pool, building the training data from the Feature Group definition.</strong></p><ol><li>Submit the train/ directory as an ML Job to the compute pool.</li><li>Use the last three days of transactions as the spine (the base rows of the training data) and point-in-time join the batch and stream FVs with generate_training_set.</li><li>Produce the real-time FV values by applying the same compute_txn_risk function in pandas (see 8.4).</li><li>Train XGBoost and choose thresholds on validation data.</li><li>Register the model and thresholds in the Model Registry and set it as the default version.</li></ol><h3>6.2 Choosing Thresholds</h3><p><strong>Thresholds are based on the false positive rate (FPR): REVIEW at 1% FPR and DECLINE at 0.3% FPR, computed on validation data.</strong> The thresholds are stored as Model Registry metrics, and the app loads them together with the model at startup. This prevents stale thresholds when the model is replaced.</p><h3>7. Results</h3><h3>7.1 Test Conditions</h3><p>I connected from a laptop in Tokyo through a corporate network to AWS Tokyo, with the online service at XS. All latencies are measured client-side and include network round trips. Measurements were taken on October 29, 2026.</p><h3>7.2 Latency</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/532/1*-IGqK5IN9n_rABfKau2APQ.png" /><figcaption>Latency</figcaption></figure><p>The documented “typically under 10 ms at P50” is service-side retrieval latency; my 25–30 ms is client-side and includes the network. The conditions differ, so the two numbers are not directly comparable. A shorter network path, such as an app in the same region, would likely be faster, but I did not measure that.</p><p>The most practical takeaway was that batch, stream, and real-time features came back in one REST call, faster than an equivalent warehouse query.</p><h3>7.3 Model Accuracy and Scenario Decisions</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1007/1*XNnNsecpB5_QTHx-5oRMuw.png" /></figure><p>In the card burst scenario, every tap updates the stream FV through the Ingest API, and the next request sees the higher count. This “previous transaction affects the next decision” behavior is only possible with the short ingest-to-read lag of stream FVs.</p><p>That said, this is synthetic data with only three fraud patterns, so these accuracy figures say nothing about real-world performance. They only confirm that the connected components return the expected decisions.</p><h3>8. Pitfalls and Workarounds</h3><h3>8.1 Summary</h3><p><strong>The two issues that needed the most care were a backfill that fails silently and a mismatch in transaction density.</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1008/1*O2WViIa8xTEbcyjJ1BjiuA.png" /></figure><h3>8.2 Check Permissions Before Stream FV Backfill</h3><p><strong>In this environment, stream FV backfill ran as a task owned by the producer role and did not succeed until that role was granted </strong><strong>EXECUTE TASK and </strong><strong>EXECUTE MANAGED TASK.</strong> I could not find this requirement in the documentation, so treat it as an observed finding. Without them, backfill failed, but FV registration itself did not error, and all offline stream features became 0. It is easy to miss until you inspect the training data.</p><p>You can check backfill state in the Feature Store metadata table:</p><pre>SELECT OBJECT_NAME, METADATA:backfill_state::STRING AS STATE<br>FROM FRAUD_DEMO.FS._FEATURE_STORE_METADATA<br>WHERE METADATA_TYPE = &#39;STREAM_CONFIG&#39;;</pre><p>If it shows FAILED, look in INFORMATION_SCHEMA.TASK_HISTORY for tasks whose names contain $BACKFILL. The official troubleshooting guide also describes re-registering the FV with overwrite=True after a backfill failure.</p><h3>9. Cost and Cleanup</h3><p><strong>The online service is billed for as long as it exists, whether or not it serves traffic.</strong> Billing has three components: hourly compute by size, extra nodes added by autoscaling, and online store storage. Separately, batch FV offline refresh and offline-to-online sync are billed as warehouse compute, and stream writeback as Snowpipe Streaming.</p><p>For the demo I prepared two cleanup levels:</p><ul><li>Drop the online service and suspend the Postgres instance and compute pool. Suspending stops compute billing, but storage billing may remain.</li><li>Drop every object created for the demo.</li></ul><p>Online service usage appears in SNOWFLAKE.ACCOUNT_USAGE.METERING_HISTORY under service types such as ONLINE_FEATURE_STORE_COMPUTE.</p><h3>10. References</h3><ul><li><a href="https://github.com/sfc-gh-mtakada/fraud_detection_w_feature_store_on_postgres">Demo code (GitHub)</a></li><li><a href="https://docs.snowflake.com/en/developer-guide/snowflake-ml/feature-store/online-feature-store">Serving online features</a></li><li><a href="https://docs.snowflake.com/en/developer-guide/snowflake-ml/feature-store/online-feature-store-ingest-api-reference">Ingest API reference</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-10-20-online-feature-store-ga">October 20, 2026: Online Feature Store (General availability)</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-07-10-online-feature-store-preview">July 10, 2026: Online Feature Store (Public Preview)</a></li></ul><h3>11. Takeaways and Future Updates</h3><p>With the Online Feature Store, I defined features with very different freshness — long-term patterns, recent activity, and the current transaction — inside Snowflake and retrieved them in one REST call. In this environment, feature retrieval took about 25–30 ms at p50 including the network, and the whole decision about 60 ms. Combined with Snowpipe Streaming, ML Jobs, the Model Registry, and Snowflake Postgres, decisions, storage, and training all run in one account.</p><p>If you try it, start with an XS online service and a small batch FV, then add a stream FV. When you add the stream FV, first check the producer role’s task privileges and confirm that training values and online values mean the same thing.</p><p>The Online Feature Store is generally available (GA) at the time of writing. I will keep tracking new features and changes, test them, and publish follow-up posts on usage and practical considerations.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=7b9ef07f6534" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cortex AI Gateway: A Common Front Door for AI on Snowflake]]></title>
            <link>https://medium.com/@masato.takada/cortex-ai-gateway-a-common-front-door-for-ai-on-snowflake-59165ab66b49?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/59165ab66b49</guid>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[ai-gateway]]></category>
            <category><![CDATA[snowflake-cortex]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Wed, 23 Sep 2026 10:26:31 GMT</pubDate>
            <atom:updated>2026-09-23T10:26:31.055Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><em>I work at Snowflake, but the views expressed in this article are my own and do not represent the official views of my employer.</em></blockquote><blockquote><em>As of September 23, 2026, Cortex AI Gateway is in Public Preview (PuPr). It is available in AWS commercial regions except Asia Pacific (New Zealand), Asia Pacific (Malaysia), and Europe (Spain). Check the </em><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway"><em>official documentation</em></a><em> for current availability.</em></blockquote><h3>1. Introduction</h3><p><strong>Cortex AI Gateway gives AI applications a common entry point to supported models, with access controls and usage visibility managed in Snowflake.</strong></p><p>Developers can keep using OpenAI or Anthropic SDKs, while platform teams can see who is using which models and how those calls behave. Think of it as a shared front door for AI, not a new AI model.</p><p>This guide walks through YAML and SQL configuration, a Python call, trace inspection, cost reporting, and the limitations I found in testing. The goal is to explain not just how to make a call, but what to check before a team starts using the gateway.</p><p>The hands-on results below come from a September 16, 2026 test in an AWS Tokyo account with cross-region inference enabled. They are observations from that environment, not a guarantee of model availability in every region or account. I distinguish these results from documented behavior throughout.</p><h3>1.1 Why a Shared Front Door Helps</h3><p><strong>Calling a model is often easier than managing all the applications that call it.</strong></p><p>Imagine a company with a document summarizer and a developer assistant. Each uses its own connection settings and credentials. As more tools appear, basic questions become harder to answer: Who has access? Which models are being used? Where are requests failing?</p><p>Cortex AI Gateway brings supported model calls through a common Snowflake endpoint.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*u7TV1MgcF_xWCjG7GM83Dg.png" /><figcaption><em>The gateway governs traffic sent through it. It does not automatically intercept every AI request in your organization.</em></figcaption></figure><h3>2. Capabilities</h3><h3>2.1 Familiar Ways to Call Models</h3><p><strong>You can use standard API formats instead of learning a new, proprietary request format.</strong></p><p>With the OpenAI Python SDK, for example, you point base_url at the gateway and supply a Snowflake token. You also select a model name available through Snowflake.</p><p>A common entry point does not mean a single API format for every model:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/851/1*WLE6RDSmLZvScDmn_2F9Wg.png" /></figure><p><strong>Use Messages for Claude.</strong> Do not assume that an OpenAI-compatible client can call Claude through the gateway’s Chat Completions endpoint.</p><h3>2.2 Separate Permissions for Calling and Monitoring</h3><p><strong>The gateway distinguishes permission to send requests from permission to inspect usage.</strong></p><p>USAGE permits inference requests through the gateway. MONITOR permits access to gateway usage information. Administrators assign these privileges to Snowflake roles and can configure which models the gateway exposes. See <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway#access-control">Access control</a>.</p><p>Gateway access does not grant new model entitlements. A caller still needs access to the underlying model. Permission to enter the front door is not permission to use everything behind it.</p><h3>2.3 Visibility Into Model Calls</h3><p><strong>With logging enabled, you can inspect users, models, token counts, timing, and errors.</strong></p><p>Tokens are the units models use to process text. Alongside timing and error information, they help you understand how your applications are using AI.</p><p>Execution records, called traces, are available through the AGENT_TRACE_TABLE table function. The documentation also describes an activity view in Snowsight under <strong>AI &amp; ML → Cortex AI Gateway</strong>. See <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability">Observability</a>.</p><p>There is an important boundary here: the gateway automatically observes the model requests it receives. It does not automatically see every internal application step or tool execution.</p><p>For cost reporting, a separate usage view named AI_GATEWAY_USAGE_HISTORY is available. Later sections explain how to read it and how team budgets differ from per-user quotas.</p><h3>3. Gateway Configuration With YAML and SQL</h3><p><strong>You do not need to create a gateway first. Snowflake automatically provisions one named </strong><strong>SNOWFLAKE in supported accounts.</strong></p><p>In practice, “setting up a gateway” means inspecting that existing object and configuring its models, logging, and permissions. It is not the same feature as the Snowflake ML CREATE GATEWAY command.</p><p>The configuration steps below are administrator tasks. A single gateway can serve multiple applications, so review the impact on existing callers before applying changes.</p><h3>3.1 Inspect the Current Configuration</h3><p>Run this in a Snowflake SQL editor:</p><pre>SHOW AI GATEWAYS;</pre><p>You can also inspect the configuration:</p><pre>DESCRIBE AI GATEWAY SNOWFLAKE;</pre><p>Use the endpoint returned for your account rather than building a URL by hand. Accounts using private connectivity have a different hostname.</p><p><strong>Keep a copy of the existing specification so you can restore it.</strong> Editing a local YAML file does not change the gateway. You must submit the specification through SQL.</p><h3>3.2 Define Models and Logging in YAML</h3><h4>3.2.1 Example Specification</h4><p>For example, maintain the following as gateway-spec.yaml. It exposes one OpenAI model and one Claude model, records request metadata, and leaves prompt and response capture off.</p><pre>schema_version: 1<br>models:<br>  - name: openai-gpt-5-nano<br>    type: cortex<br>  - name: claude-haiku-4-5<br>    type: cortex<br>logging:<br>  enabled: true<br>  capture_payload:<br>    request_response: false</pre><h4>3.2.2 Understanding the Settings</h4><p>Here is how to read it:</p><ul><li>schema_version: 1 identifies the configuration format, not a model version.</li><li>models lists the models exposed through this gateway. Use actual supported model IDs.</li><li>type: cortex identifies a model offered through Cortex.</li><li>logging.enabled: true enables gateway traces.</li><li>request_response: false keeps prompt and response bodies out of payload capture.</li></ul><p>You can replace the model list with models: [{name: &#39;*&#39;}] to expose the available gateway catalog without maintaining individual names. But <strong>&#39;*&#39; does not make arbitrary models, or every Cortex Inference model, available.</strong> Gateway support and the caller&#39;s underlying model permissions still apply.</p><h3>3.3 Apply the Whole Specification</h3><h4>3.3.1 Apply Settings With ALTER</h4><p>Pass the YAML inside a $$ ... $$ string to FROM SPECIFICATION. The dollar signs delimit a multiline SQL string.</p><pre>ALTER AI GATEWAY SNOWFLAKE FROM SPECIFICATION $$<br>schema_version: 1<br>models:<br>  - name: openai-gpt-5-nano<br>    type: cortex<br>  - name: claude-haiku-4-5<br>    type: cortex<br>logging:<br>  enabled: true<br>  capture_payload:<br>    request_response: false<br>$$;</pre><blockquote><em>This replaces the </em><strong><em>entire specification</em></strong><em>. It is not a patch. In an existing environment, edit the full specification returned by </em><em>DESCRIBE rather than applying this sample unchanged. Applying this example also replaces the exposed model list with these two models.</em></blockquote><h4>3.3.2 Verify the Applied Configuration</h4><p>Inspect the result afterwards:</p><pre>DESCRIBE AI GATEWAY SNOWFLAKE;</pre><p>In my tests, omitting the logging block during replacement stopped trace recording. However, the gateway&#39;s starting configuration already had logging.enabled: true. These are different observations: do not assume every provisioned gateway starts with logging off. <strong>Inspect the actual configuration and declare the settings you need explicitly.</strong></p><p>A successful ALTER also does not necessarily prove that your model names are valid. Follow configuration inspection with a small request to each allowed model. Those checks incur inference charges.</p><h3>3.4 Separate Application and Monitoring Roles</h3><p>The following examples assume AI_APP_ROLE and AI_MONITOR_ROLE already exist. Substitute your actual role names and run the statements as an administrator authorized to grant these privileges.</p><pre>GRANT USAGE ON AI GATEWAY SNOWFLAKE TO ROLE AI_APP_ROLE;<br>GRANT MONITOR ON AI GATEWAY SNOWFLAKE TO ROLE AI_MONITOR_ROLE;</pre><p>Inspect existing grants with:</p><pre>SHOW GRANTS ON AI GATEWAY SNOWFLAKE;</pre><p>By default, PUBLIC has USAGE. <strong>Granting access to one role does not make the gateway exclusive to that role.</strong> Restriction requires reviewing inherited privileges, including PUBLIC and parent roles.</p><p>My tests retained the PUBLIC grant. They verified that MONITOR controls trace access, but did not establish that revoking USAGE from an individual role would block inference while inherited access remained. Also check the privileges needed to read Account Usage views separately.</p><h3>4. Calling the Gateway From Python</h3><p><strong>The main client-side changes are the endpoint, credentials, and model name. The exact base URL depends on the SDK.</strong></p><p>You will also need:</p><ul><li>A <strong>Snowflake programmatic access token (PAT)</strong>, not an OpenAI API key.</li><li>Permission to use <strong>both the gateway and the selected model</strong>.</li><li>A <strong>supported model</strong>, with any required cross-region inference settings approved for your environment.</li></ul><p>See the <a href="https://docs.snowflake.com/en/user-guide/programmatic-access-tokens">PAT authentication guide</a> for token requirements.</p><h3>4.1 Use the OpenAI Python SDK</h3><h4>4.1.1 Prepare the SDK and Environment Variables</h4><p>Install the SDK:</p><pre>pip install openai</pre><p>Configure SNOWFLAKE_AI_GATEWAY_URL and SNOWFLAKE_PAT in your execution environment. The URL should be the gateway endpoint before appending /v1. Keep the PAT out of source code and version control.</p><h4>4.1.2 Make a Model Request</h4><pre>import os<br>from openai import OpenAI<br><br>gateway_url = os.environ[&quot;SNOWFLAKE_AI_GATEWAY_URL&quot;].rstrip(&quot;/&quot;)<br>client = OpenAI(<br>    api_key=os.environ[&quot;SNOWFLAKE_PAT&quot;],<br>    base_url=f&quot;{gateway_url}/v1&quot;,<br>)<br>response = client.chat.completions.create(<br>    model=&quot;openai-gpt-5-nano&quot;,<br>    messages=[<br>        {&quot;role&quot;: &quot;user&quot;, &quot;content&quot;: &quot;Explain cloud computing to a beginner in two sentences.&quot;}<br>    ],<br>    max_completion_tokens=500,<br>)<br>print(response.choices[0].message.content)</pre><p>This example uses openai-gpt-5-nano, which worked in my test environment. Choose a model available to your own account and gateway.</p><p>The key detail is simple: <strong>the SDK is OpenAI’s, but the endpoint and authentication are Snowflake’s.</strong> In my testing, the official SDKs worked for both regular responses and streaming, where the answer arrives incrementally.</p><h3>4.2 SDK Base URLs and API Paths</h3><p>Let G stand for the endpoint returned by SHOW AI GATEWAYS:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/547/1*ytE_gHXOHIvHjeMCe_0RpA.png" /></figure><p>The Anthropic SDK appends /v1/messages, so do not append /v1 to its base URL yourself. Both paths require a Snowflake PAT as a bearer token. For Anthropic, verify that the client sends Authorization: Bearer ...; simply supplying a provider API key is not the Snowflake authentication setup.</p><h3>4.3 Client Compatibility Requirements</h3><p><strong>Check what a client lets you configure, rather than relying on its product name.</strong> The documented requirements are a custom base URL, bearer-token authentication, and support for Chat Completions or Messages.</p><p>Cortex Code (CoCo), CoWork, and Cortex Agents do not automatically become gateway traffic merely because they are Snowflake products. This verification did not test switching those products’ inference paths to the gateway. Neither universal coverage nor blanket incompatibility follows from the product name: check each product’s supported configuration.</p><p>As of September 23, 2026, /v1/responses is not supported. A Responses-only client cannot migrate simply by changing its URL. See the <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/inference">documented client requirements</a>.</p><h3>5. Inspecting Activity Through Traces</h3><p><strong>Each row returned by </strong><strong>AGENT_TRACE_TABLE represents a span: one unit of work. Use identifiers to assemble an execution or conversation from those rows.</strong></p><h3>5.1 Conversations, Traces, and Spans</h3><p>For example, an application might receive a question, call a model, execute a tool, and call the model again with the result. Its model calls could be grouped like this:</p><pre>conversation_id: conversation-A<br>  |<br>  +-- trace_id: turn-1<br>  |     +-- span_id: model-call-1<br>  |     +-- span_id: model-call-2<br>  |<br>  +-- trace_id: turn-2<br>        +-- span_id: model-call-3</pre><ul><li>conversation_id optionally groups related turns into a conversation.</li><li>trace_id groups an execution, such as one agent turn.</li><li>span_id identifies an individual operation within it.</li></ul><p>The gateway does not infer this structure from the text of the conversation. A conversation ID comes from a header such as x-snowflake-ai-gateway-conversation-id. Trace context is propagated using the W3C traceparent header. Without propagated context, individual model calls can appear as separate traces.</p><h3>5.2 Inspect Recent Calls With SQL</h3><p>This query selects only the metadata needed for an initial inspection, covering the last day and returning at most 100 gateway-generated spans. It requires MONITOR on the gateway.</p><pre>SELECT<br>    start_timestamp,<br>    trace:&quot;trace_id&quot;::STRING AS trace_id,<br>    trace:&quot;span_id&quot;::STRING AS span_id,<br>    record_attributes:&quot;gen_ai.conversation.id&quot;::STRING AS conversation_id,<br>    resource_attributes:&quot;user&quot;::STRING AS user_name,<br>    record_attributes:&quot;gen_ai.request.model&quot;::STRING AS model,<br>    TRY_TO_NUMBER(record_attributes:&quot;http.status_code&quot;::STRING) AS http_status,<br>    TRY_TO_NUMBER(record_attributes:&quot;gen_ai.usage.input_tokens&quot;::STRING) AS input_tokens,<br>    TRY_TO_NUMBER(record_attributes:&quot;gen_ai.usage.output_tokens&quot;::STRING) AS output_tokens,<br>    DATEDIFF(&#39;millisecond&#39;, start_timestamp, timestamp) AS duration_ms<br>FROM TABLE(AGENT_TRACE_TABLE(&#39;SNOWFLAKE&#39;))<br>WHERE timestamp &gt;= DATEADD(&#39;day&#39;, -1, CURRENT_TIMESTAMP())<br>  AND timestamp &lt; CURRENT_TIMESTAMP()<br>  AND scope:&quot;name&quot;::STRING = &#39;aigateway/tracing&#39;<br>ORDER BY start_timestamp DESC<br>LIMIT 100;</pre><p>Objects such as record_attributes hold the semantic attributes; the colon operator extracts a field. Token counts can be missing on failed calls, so a NULL is not automatically equivalent to zero tokens.</p><p>This shows the model calls the gateway observed. Seeing tool execution and intermediate application steps requires client-side instrumentation, such as OpenTelemetry, and export of those spans.</p><h3>5.3 Capturing Prompts and Responses</h3><p>If an investigation requires prompts and responses, change this part of the <strong>existing full specification</strong>. This is a fragment to merge, not a complete replacement specification.</p><pre>logging:<br>  enabled: true<br>  capture_payload:<br>    request_response: true</pre><p>logging.enabled is the master switch. Setting request_response: true while logging is false does not capture the bodies.</p><p>Captured content remains in an event table in your account. Turning capture off later does not delete previously captured data. Decide access and retention policies first, and enable capture only when needed. In the test environment, gateway traces used a dedicated storage destination; do not assume the policies on an existing account event table automatically cover them.</p><p>Even with capture disabled, some error messages quoted request field values. Large records were also truncated. <strong>Treat traces as sensitive operational data, not as a complete conversation backup.</strong></p><h3>6. Usage and Cost Reporting</h3><p><strong>Traces explain what happened. Usage history explains credit consumption. Their row counts need not match.</strong></p><h3>6.1 Report Daily Inference Credits</h3><p>For example, this query reports daily gateway inference credits over the last seven days. It requires access to the Account Usage view. Day boundaries follow the session time zone.</p><pre>SELECT<br>    DATE_TRUNC(&#39;day&#39;, start_time) AS usage_day,<br>    gateway_name,<br>    SUM(credits) AS inference_credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.AI_GATEWAY_USAGE_HISTORY<br>WHERE start_time &gt;= DATEADD(&#39;day&#39;, -7, CURRENT_TIMESTAMP())<br>  AND start_time &lt; CURRENT_TIMESTAMP()<br>  AND gateway_name = &#39;SNOWFLAKE&#39;<br>  AND service_type = &#39;AI_INFERENCE&#39;<br>GROUP BY 1, 2<br>ORDER BY 1;</pre><p>This is an inference-credit total, not a currency invoice or a total including trace ingestion and storage. Usage reporting is delayed, so the most recent figures can be incomplete.</p><p>For model-level analysis, names and token counts are nested in OPERATION_DETAILS; per-model credits are in CREDITS_GRANULAR. Do not assume the gateway view has a top-level MODEL_NAME column.</p><h3>6.2 Avoid Double Counting Across Usage Views</h3><p>One important finding was overlap between the gateway and Cortex REST usage views. These results cover the same four-hour test window:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/476/1*qaSee4gJkONwaFEBZy8ttw.png" /></figure><p>Within this test window, 109 = 90 gateway requests + 19 direct Cortex Inference requests. Adding the views as 90 + 109 = 199 requests would count gateway traffic twice.</p><p><strong>This is overlapping reporting, not evidence of duplicate billing.</strong> Use the gateway view for gateway credits. When combining request counts or usage across the two views, check duplicates by REQUEST_ID. Verify the relationship in your own reporting environment rather than assuming this exact subset relationship is permanent.</p><h3>6.3 Trace Counts, Tokens, and Billing</h3><p>In a separate reconciliation, 85 of the 90 usage records matched a trace. The other five were requests made while logging was disabled. <strong>Disabling traces does not stop inference charges.</strong> Conversely, some failed test requests appeared in traces without a corresponding usage row.</p><p>Caching also changes how numbers should be read. One example reported 2,613 input tokens in the trace, 181 regular input tokens in usage history, and 2,432 cache-read tokens. Multiplying the trace’s total input count by a single rate would miss that distinction.</p><p>The <a href="https://docs.snowflake.com/en/sql-reference/account-usage/ai_gateway_usage_history">usage view documentation</a> also states that the view is not intended for near-real-time monitoring or exact request-for-request reconciliation with activity data. The fact that IDs could be matched in this test is not a guarantee of permanent one-to-one completeness.</p><h3>6.4 Budgets and Per-User Quotas</h3><p><strong>Decide whether you need a notification or a usage block.</strong> The following is based on public documentation; enforcement at a threshold was outside this verification’s scope.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/954/1*VGYWYFXX6f0CtYOwJ76wdQ.png" /></figure><p>Budget evaluation is periodic: the documentation describes up to 6.5 hours, or one hour with the low-latency option. Quota blocks apply within minutes, not instantaneously. Neither should be described as a perfectly immediate spending ceiling. Sharing one PAT also attributes calls to the same Snowflake user, so credential design matters for meaningful user and application attribution. See <a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/cost-management">Cost management</a>.</p><h3>7. Model Coverage Compared With Cortex Inference</h3><p><strong>Test the combination of model, API, and parameters, not just the model name.</strong></p><p>The following is a selection from the September 16 Chat Completions comparison. It is a test snapshot with cross-region inference enabled, not the current official model catalog.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/756/1*s8LCr_zyYEmkzIJl36oqKw.png" /></figure><p>The important point is that the gateway is not simply another URL for an identical Cortex Inference catalog. Some tested models worked only through one path, and some only through the other.</p><p>Claude requests sent to the gateway’s Chat Completions path returned 503, but <strong>that does not mean Claude is unavailable through the gateway</strong>. Separate tests succeeded using the correct Messages API. A compatibility table needs to name the API surface, not just the product.</p><h3>8. Current Limitations and Pre-Deployment Checks</h3><p><strong>Standard SDK inference and usage inspection worked, but Preview operations still need explicit configuration checks and troubleshooting procedures.</strong> These are findings from September 16, not confirmation that every issue remained unfixed on September 23 or later.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*71yurDyYYLkqn1P3YDJjSg.png" /></figure><h3>9. References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway">Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/inference">Inference with Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/observability">Observability for Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-ai-gateway/cost-management">Cost management for Cortex AI Gateway</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/account-usage/ai_gateway_usage_history">AI_GATEWAY_USAGE_HISTORY</a></li><li><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-09-15-cortex-ai-gateway">Preview announcement</a></li></ul><h3>10. Takeaways and Future Updates</h3><p><strong>Cortex AI Gateway is about making AI calls manageable as more people and applications start making them.</strong></p><p>Developers use familiar SDKs. Administrators manage gateway permissions and inspect usage in Snowflake. That division becomes useful as AI moves from an individual experiment to a shared organizational capability.</p><p>A practical first step is to route one small application through the gateway, then inspect its request records. You will see both sides of the feature: making the call and understanding what happened.</p><p>At the time of writing, Cortex AI Gateway is in <strong>Public Preview (PuPr)</strong>, with further additions and improvements expected. As new features become available, I will test them and publish follow-up blog posts covering how to use them and what to watch out for.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=59165ab66b49" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Benchmarking Snowflake’s Adaptive Warehouses — Gen1 vs Gen2 vs Adaptive on TPCH-1000]]></title>
            <link>https://medium.com/@masato.takada/benchmarking-snowflakes-adaptive-warehouses-gen1-vs-gen2-vs-adaptive-on-tpch-1000-c2538211486d?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/c2538211486d</guid>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[performance]]></category>
            <category><![CDATA[data-warehouse]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Mon, 18 May 2026 05:31:01 GMT</pubDate>
            <atom:updated>2026-05-18T05:31:01.183Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong><em>Disclaimer:</em></strong><em> I work at Snowflake, but this article reflects my personal views and is not an official statement from my employer.</em></blockquote><h3>1. Introduction</h3><p>In May 2025, I benchmarked Gen2 Standard Warehouses against Gen1 using TPCH-1000 (<a href="https://medium.com/@masato.takada/benchmarking-snowflakes-generation-2-standard-warehouses-4a3cb786932c">previous article</a>). Gen2 delivered a consistent 30–40% speed-up.</p><p>In late April 2026, <strong>Adaptive Warehouses</strong> became available in Public Preview. Unlike traditional fixed-size warehouses, Adaptive represents a fundamentally different compute architecture — one where Snowflake automatically manages sizing, scaling, and resource allocation.</p><p>This post extends the previous benchmark to include Adaptive, with a focus on performance.</p><blockquote><strong><em>TL;DR</em></strong><em> Adaptive delivered a </em><strong><em>47% speed-up</em></strong><em> over Gen1 across 22 TPCH queries, and was the fastest on 21 of 22.</em></blockquote><h3>2. What Is an Adaptive Warehouse?</h3><p>Adaptive Warehouses are a new compute model that eliminates manual infrastructure tuning:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*-imE5q7I4CWv52HwYOaPug.png" /></figure><p>You control behavior with just two parameters:</p><ul><li><strong>MAX_QUERY_PERFORMANCE_LEVEL</strong> — Upper bound on per-query resource allocation (t-shirt sizes)</li><li><strong>QUERY_THROUGHPUT_MULTIPLIER</strong> — Scale factor for concurrent throughput</li></ul><pre>CREATE ADAPTIVE WAREHOUSE my_adaptive_wh<br>  WITH MAX_QUERY_PERFORMANCE_LEVEL = SMALL<br>       QUERY_THROUGHPUT_MULTIPLIER = 2;</pre><p><strong>Requirements:</strong> Enterprise Edition or higher. Available in AWS US West 2 (Oregon), EU West 1 (Ireland), and <strong>AP Northeast 1 (Tokyo)</strong> during Public Preview.</p><h3>3. Benchmark Setup</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/880/1*gX65UjZOvMu7EZGCHwQYDg.png" /></figure><h3>Warehouse Configuration</h3><pre>-- Gen1 Standard Small<br>CREATE OR REPLACE WAREHOUSE compute_wh_gen1<br>  WAREHOUSE_SIZE = &#39;SMALL&#39;<br>  GENERATION = &#39;1&#39;<br>  AUTO_SUSPEND = 60<br>  AUTO_RESUME = TRUE;<br><br>-- Gen2 Standard Small<br>CREATE OR REPLACE WAREHOUSE compute_wh_gen2<br>  WAREHOUSE_SIZE = &#39;SMALL&#39;<br>  GENERATION = &#39;2&#39;<br>  AUTO_SUSPEND = 60<br>  AUTO_RESUME = TRUE;<br><br>-- Adaptive (MAX_QUERY_PERFORMANCE_LEVEL = SMALL for fair comparison)<br>CREATE OR REPLACE ADAPTIVE WAREHOUSE compute_wh_adaptive<br>  WITH MAX_QUERY_PERFORMANCE_LEVEL = SMALL<br>       QUERY_THROUGHPUT_MULTIPLIER = 2;</pre><blockquote><strong><em>Note:</em></strong><em> Use </em><em>GENERATION = &#39;2&#39; to create Gen2 warehouses. The older </em><em>RESOURCE_CONSTRAINT = STANDARD_GEN_2 syntax was deprecated in the 2026_02 bundle.</em></blockquote><h3>Session Settings</h3><p>In this experiment, I set a disabled cache parameter as below.</p><pre>-- Disable result cache for pure execution performance measurement<br>ALTER SESSION SET USE_CACHED_RESULT = FALSE;</pre><h3>4. Results</h3><p>In this section, it shows a result of adaptive warehouse across 22 queries over TPCH data, compared with Gen1 and Gen2.</p><h3>4.1 Performance Comparison</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*UZjdsSzDSRdMg2sujUYe8g.png" /></figure><figure><img alt="" src="https://cdn-images-1.medium.com/max/800/1*eTgvgBlMdQQd4xIU91UwTQ.png" /></figure><p>Adaptive was the fastest on 21 of 22 queries. Q17 was the only exception where Gen2 outperformed Adaptive.</p><h3>4.2 Cost (Reference Only)</h3><p>For reference, here are the credits consumed as measured from WAREHOUSE_METERING_HISTORY. Since Adaptive is in Public Preview, the billing model may change at GA.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/768/1*oelM2vhiJiIjUj3icpRn2Q.png" /></figure><p>At the time of testing (May 2026, Preview), Adaptive consumed the fewest credits. Whether this holds after GA is uncertain.</p><h3>5. Why Is Adaptive Faster/Cheaper Than Gen2 Small?</h3><p>The higher query performance and lower cost compared to standard warehouses can be explained by several factors.</p><h3>5.1 SMALL Is a Performance Ceiling, Not a Fixed Size</h3><p>The official documentation states:</p><blockquote><em>“Each t-shirt size conveys a </em><strong><em>similar or better</em></strong><em> level of performance than its commensurate classic warehouse size.”</em></blockquote><p>MAX_QUERY_PERFORMANCE_LEVEL = SMALL doesn&#39;t mean &quot;allocate exactly the same resources as a Gen2 Small.&quot; It means: <strong>cap the per-query performance level at SMALL, while dynamically allocating optimal resources within that envelope.</strong> For example, a query that only needs XS-level resources will receive just that on Adaptive, whereas a standard warehouse always allocates the full SMALL capacity — resulting in lower cost for lightweight queries.</p><blockquote><strong><em>Design philosophy:</em></strong><em> </em><em>MAX_QUERY_PERFORMANCE_LEVEL is not a fixed size specification. Adaptive dynamically allocates optimal resources per query within this upper bound.</em></blockquote><h3>5.2 Software Optimization and Hardware Differences</h3><p>Adaptive runs on a newer software stack than Gen2:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*DfQC33J4GkdMIKYFhlfTPg.png" /></figure><p>Gen2 brings “faster hardware + some software improvements,” but Adaptive goes further with advanced execution engine optimizations and intelligent scheduling. The <a href="https://docs.snowflake.com/en/user-guide/warehouses-adaptive">official documentation</a> explicitly states:</p><blockquote><em>“It also incorporates the latest hardware and performance enhancements”</em></blockquote><p>While Gen2 already uses newer hardware, Adaptive likely runs on even newer CPU generations (such as Graviton4) — <strong>a major factor behind the performance gap</strong> we observed. Additionally, the shared resource pool behind Adaptive is continuously updated with the latest hardware generations and versions, a benefit that fixed-size warehouses don’t automatically receive.</p><h3>5.3 Pooled Architecture</h3><pre>[ Standard Warehouse (Traditional) ]<br>  WH_A [████░░░░]  WH_B [██░░░░░░]  WH_C [░░░░░░░░]<br>       Active         Low usage        Idle (still billed)<br><br>→ Each WH owns dedicated clusters. You pay even when idle.<br><br>[ Adaptive Warehouse (New Model) ]<br>  Shared Pool [████████████████████░░░░░░░░]<br>  → Queries from WH_A, WH_B, WH_C optimally placed in shared pool<br>  → Idle nodes = no charge</pre><p>All Adaptive warehouses in an account share a server pool. The elimination of the “dedicated cluster per WH” constraint, combined with per-query execution-time billing, improves both resource and time efficiency — which in turn contributes to lower costs.</p><p>That said, the official documentation states that “<strong>adaptive warehouses can run significantly more queries at a similar cost to Gen2</strong>.” My personal view is that some aspects of the billing model may still be maturing during Public Preview.</p><h3>6. Cost Observations and Caveats</h3><blockquote><strong><em>Note:</em></strong><em> Adaptive is in Public Preview. The cost results below are based on the Preview billing model and may change at GA. When evaluating Adaptive, I recommend focusing on performance improvement and operational simplification as the primary adoption reasons, and managing costs with Budgets and Resource Monitors.</em></blockquote><p>While the documentation states that Adaptive can “run significantly more queries at a <strong>similar cost</strong> to Gen2,” our TPCH benchmark showed a ~20% cost reduction vs Gen2. This raised the question: are there workloads where Adaptive actually costs <em>more</em>? We designed two tests to find out.</p><h3>6.1 Cost Tests</h3><p>Adaptive uses per-query billing, but internally there are mechanisms to keep costs comparable to traditional warehouses. Since Adaptive runs on newer, higher-performance hardware, we hypothesized that the per-unit cost floor might be higher than a classic XS — making Adaptive <strong>more expensive for always-on, lightly utilized XS workloads</strong>.</p><p><strong>1. Trickle Load Test</strong> — 1 small query per minute for 10 minutes (Gen1 XS vs Adaptive XSMALL)</p><p><em>Test details: Considering the standard warehouse’s 1-minute minimum billing, we ran two patterns of sub-second queries at 1-minute intervals.</em></p><p><em>Results:</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/910/1*pP3CgjatyoHOFpTY_o7aKA.png" /></figure><p><strong>2. Saturation Test</strong> — 3 threads, continuous queries for 10 minutes (Gen1 XS vs Adaptive XSMALL)</p><p><em>Test details: Continuously submit queries from client threads for 10 minutes, then compare total queries processed and cost.</em></p><p><em>Results:</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/874/1*HkJelj7HFqoedJhMHpzhhw.png" /></figure><p><strong>Analysis:</strong> In the trickle tests, Adaptive was cheaper in both patterns. The SELECT 1 result was particularly striking — an <strong>880x</strong> difference. In the saturation test, total credits were 2x higher for Adaptive, but with 4.3x the throughput, the per-query cost was 54% lower. Adaptive automatically scales up resources, so if you want to control total spend, consider adjusting QUERY_THROUGHPUT_MULTIPLIER.</p><p>Again, these are <strong>Preview</strong>-stage results.</p><h3>6.2 Other Limitations</h3><ul><li>Converting to/from X5Large or X6Large warehouses is not yet supported</li><li>Converting to/from Snowpark-optimized or Interactive warehouses is not yet supported</li><li>Query-level cost visibility is planned for GA (Preview only shows warehouse-level aggregates)</li></ul><h3>7. Reproducible Benchmark Script</h3><pre>import re, time, os, csv<br>import snowflake.connector as sf<br><br>conn = sf.connect(<br>    connection_name=os.getenv(&quot;SNOWFLAKE_CONNECTION_NAME&quot;) or &quot;default&quot;<br>)<br>NUM_RUNS = 3<br>LABEL_RE = re.compile(r&#39;TPCH_Query\d+&#39;, re.I)<br>WAREHOUSES = [&quot;compute_wh_gen1&quot;, &quot;compute_wh_gen2&quot;, &quot;compute_wh_adaptive&quot;]<br>def run_benchmark(warehouse, sql_file):<br>    results = []<br>    cur = conn.cursor()<br>    cur.execute(f&quot;USE WAREHOUSE {warehouse}&quot;)<br>    cur.execute(&quot;ALTER SESSION SET USE_CACHED_RESULT = FALSE&quot;)<br>    cur.execute(&quot;USE DATABASE SNOWFLAKE_SAMPLE_DATA&quot;)<br>    cur.execute(&quot;USE SCHEMA TPCH_SF1000&quot;)<br>    with open(sql_file) as f:<br>        content = f.read()<br>    sql_blocks = [q.strip() for q in content.split(&quot;;&quot;) if q.strip()]<br>    for run in range(1, NUM_RUNS + 1):<br>        for block in sql_blocks:<br>            m = LABEL_RE.search(block)<br>            if not m:<br>                continue<br>            label = m.group(0)<br>            sql = block.split(&quot;\n&quot;, 1)[-1]<br>            t0 = time.time()<br>            cur.execute(sql)<br>            cur.fetchall()<br>            dt = time.time() - t0<br>            results.append({<br>                &quot;warehouse&quot;: warehouse, &quot;run&quot;: run,<br>                &quot;query&quot;: label, &quot;elapsed_sec&quot;: round(dt, 5)<br>            })<br>            print(f&quot;  {label}: {dt:.3f}s&quot;)<br>    return results<br>def main():<br>    os.makedirs(&quot;results&quot;, exist_ok=True)<br>    all_results = []<br>    for wh in WAREHOUSES:<br>        print(f&quot;\nBenchmarking: {wh}&quot;)<br>        all_results.extend(run_benchmark(wh, &quot;tpch.sql&quot;))<br>    with open(&quot;results/benchmark_results.csv&quot;, &quot;w&quot;, newline=&quot;&quot;) as f:<br>        writer = csv.DictWriter(<br>            f, fieldnames=[&quot;warehouse&quot;, &quot;run&quot;, &quot;query&quot;, &quot;elapsed_sec&quot;]<br>        )<br>        writer.writeheader()<br>        writer.writerows(all_results)<br>    print(f&quot;\nResults saved to results/benchmark_results.csv&quot;)<br>if __name__ == &quot;__main__&quot;:<br>    main()</pre><p>Run with:</p><pre>SNOWFLAKE_CONNECTION_NAME=my_connection python3 benchmark.py</pre><h3>8. Takeaways</h3><p>Before this benchmark, I expected Adaptive to perform roughly on par with standard warehouses. The 47% improvement over Gen1 was a pleasant surprise. I find the automatic resource scaling particularly compelling for workloads where data volume fluctuates — for example, using Adaptive as the backing warehouse for Dynamic Tables that process varying amounts of data throughout the day.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*Lco_-5tOMumdNo6IJSp2Ug.png" /></figure><ol><li><strong>Adaptive’s biggest win is performance</strong> — 47% faster than Gen1, fastest on 21 of 22 queries</li><li><strong>Operational simplification</strong> — No more choosing warehouse sizes, configuring MCW, QAS, or AUTO_SUSPEND</li><li><strong>Gen2 remains excellent</strong> — 36% speed-up with zero code changes</li><li><strong>Try it</strong> — Converting existing warehouses is an online operation with no downtime, and you can switch back just as easily</li></ol><pre>-- Convert to Adaptive (no downtime)<br>ALTER WAREHOUSE my_warehouse SET WAREHOUSE_TYPE = &#39;ADAPTIVE&#39;;<br><br>-- Revert to Standard<br>ALTER WAREHOUSE my_warehouse SET WAREHOUSE_TYPE = &#39;STANDARD&#39;;</pre><h3>References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/warehouses-adaptive">Snowflake Docs: Adaptive Compute</a></li><li><a href="https://docs.snowflake.com/en/user-guide/warehouses-gen2">Snowflake Docs: Gen2 Standard Warehouses</a></li><li><a href="https://zenn.dev/tf_takada/articles/507a94f8283bf0">Previous article: Gen2 Benchmark (Zenn, Japanese)</a></li><li><a href="https://medium.com/@masato.takada/benchmarking-snowflakes-generation-2-standard-warehouses-4a3cb786932c">Previous article: Gen2 Benchmark (Medium)</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=c2538211486d" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Cortex Search Batch Released: Cortex Search Now Supports Both BATCH and INTERACTIVE Search]]></title>
            <link>https://medium.com/@masato.takada/cortex-search-batch-released-cortex-search-now-supports-both-batch-and-interactive-search-3b37240cbdb5?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/3b37240cbdb5</guid>
            <category><![CDATA[cortex]]></category>
            <category><![CDATA[snowflake]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Wed, 01 Apr 2026 09:46:11 GMT</pubDate>
            <atom:updated>2026-04-01T09:46:11.572Z</atom:updated>
            <content:encoded><![CDATA[<p><em>The author is employed at Snowflake, but the views expressed in this article are personal and do not represent the official views of the organization.</em></p><h3>1. Introduction</h3><p>Snowflake’s <strong>Cortex Search</strong> is a managed hybrid search service (vector + keyword) for text data, optimized for real-time use cases like RAG chatbots and search bars.</p><p>However, for use cases that require <strong>processing large volumes of queries in batch</strong> — such as entity resolution, catalog mapping, and deduplication — the Interactive API (SEARCH_PREVIEW) is too slow, as it processes one query at a time.</p><p><strong>Batch Cortex Search</strong> (CORTEX_SEARCH_BATCH) solves this problem. In this article, I share my hands-on verification results based on the official Quickstart: <a href="https://www.snowflake.com/en/developers/guides/getting-started-with-batch-cortex-search/">Getting Started with Batch Cortex Search</a>.</p><h3>Test Environment</h3><ul><li><strong>Embedding Model</strong>: snowflake-arctic-embed-l-v2.0 (multilingual, 1024 dimensions, 512 tokens)</li><li><strong>Data Source</strong>: Snowflake Marketplace — Wikipedia dataset</li><li><strong>Row Count</strong>: 100,000</li><li><strong>Warehouse Size</strong>: SMALL (primary) / MEDIUM (warehouse-independence test)</li></ul><h3>2. Batch Cortex Search Overview</h3><h3>What is Batch Cortex Search?</h3><p>CORTEX_SEARCH_BATCH is a table function that submits <strong>batches of queries</strong> to an existing Cortex Search Service. A single service supports <strong>both Interactive and Batch modes</strong> — no separate service is needed.</p><h3>6 Key Features</h3><ul><li><strong>Table Function</strong> — CORTEX_SEARCH_BATCH sends query batches to an existing Cortex Search Service</li><li><strong>Same Index</strong> — Uses the same underlying service and index. No additional objects to create or manage</li><li><strong>Dedicated Compute</strong> — Leverages additional compute resources for significantly higher throughput (QPS)</li><li><strong>Warehouse-Independent</strong> — Throughput is unaffected by warehouse size. Dedicated batch resources handle the load</li><li><strong>Concurrency</strong> — Scales with concurrent batch queries against a given service</li><li><strong>Zero Interference</strong> — Interactive and Batch run simultaneously with no degradation to Interactive performance</li></ul><h3>Key Use Cases</h3><ul><li><strong>Entity Resolution</strong> — Match records across systems even with name variations</li><li><strong>Catalog Mapping</strong> — Efficiently map supplier products to standardized internal SKUs</li><li><strong>Deduplication</strong> — Automatically identify and merge duplicate records</li><li><strong>Audience Matching</strong> — Identify customer overlap across marketing lists</li><li><strong>Content Tagging</strong> — Auto-tag documents with relevant categories</li><li><strong>Similar Item Discovery</strong> — Power recommendation engines by identifying similar items at scale</li></ul><h3>Interactive vs Batch Comparison</h3><ul><li><strong>Purpose</strong>: Interactive is for low-latency user-facing search (RAG chatbots, search bars); Batch is for offline high-throughput search across many queries</li><li><strong>Workload</strong>: Interactive handles one query at a time (online/transactional); Batch processes many queries from a table (offline/analytical)</li><li><strong>Latency</strong>: Interactive is optimized for low latency (p50 ~200–300ms at 15–30 QPS); Batch is optimized for throughput (~30s startup, then QPS &gt;100)</li><li><strong>Concurrency</strong>: Both support concurrency — multiple batch jobs can run simultaneously</li><li><strong>Mutual Impact</strong>: Batch runs without degrading Interactive performance</li><li><strong>Separate Service?</strong>: No — a single Cortex Search Service supports both Interactive and Batch</li></ul><h3>3 Steps to Get Started</h3><ol><li><strong>Create a Cortex Search Service</strong> — Build a service on your text data</li><li><strong>Prepare a query table</strong> — Create a table or CTE with queries and optional filters</li><li><strong>Run </strong><strong>CORTEX_SEARCH_BATCH</strong> — LATERAL join your queries to the batch function</li></ol><h3>3. Verification Results</h3><h3>3.1 Environment Setup &amp; Data Preparation</h3><p>We acquire a Wikipedia dataset from the Marketplace and create a 100K-row table.</p><p>SYSTEM$ACCEPT_LEGAL_TERMS accepts the Marketplace listing&#39;s terms of service, then CREATE DATABASE ... FROM LISTING creates the database. We then extract 100K rows into our BATCH_DEMO database.</p><pre>USE ROLE ACCOUNTADMIN;<br><br>CALL SYSTEM$ACCEPT_LEGAL_TERMS(&#39;DATA_EXCHANGE_LISTING&#39;, &#39;GZT0Z4C8RF3FT&#39;);<br>CREATE DATABASE IF NOT EXISTS AI_TRAINING_DATASET_FROM_WIKIPEDIA<br>FROM LISTING &#39;GZT0Z4C8RF3FT&#39;;<br><br>CREATE DATABASE IF NOT EXISTS BATCH_DEMO;<br>CREATE WAREHOUSE IF NOT EXISTS BATCH_SEARCH_WH<br>    WITH WAREHOUSE_SIZE = &#39;SMALL&#39;<br>    AUTO_SUSPEND = 300<br>    AUTO_RESUME = TRUE;<br><br>USE DATABASE BATCH_DEMO;<br>USE SCHEMA PUBLIC;<br>USE WAREHOUSE BATCH_SEARCH_WH;<br><br>CREATE OR REPLACE TABLE wikipedia_articles AS<br>SELECT URL, TITLE, RAW_TEXT, TABLE_OF_CONTENTS, SEE_ALSO<br>FROM AI_TRAINING_DATASET_FROM_WIKIPEDIA.PUBLIC.WIKIPEDIA<br>LIMIT 100000;</pre><h3>3.2 Creating the Cortex Search Service</h3><p>CREATE CORTEX SEARCH SERVICE creates the service. Key parameters:</p><ul><li>ON RAW_TEXT — specifies the text column to search</li><li>ATTRIBUTES TITLE — attribute columns included in results (also usable for filtering)</li><li>TARGET_LAG — maximum delay for reflecting source data changes in the index</li><li>EMBEDDING_MODEL — the embedding model to use (defaults if omitted)</li><li>AS SELECT ... — the query that returns data to index</li></ul><pre>CREATE OR REPLACE CORTEX SEARCH SERVICE wikipedia_search_service<br>ON RAW_TEXT<br>ATTRIBUTES TITLE<br>WAREHOUSE = BATCH_SEARCH_WH<br>TARGET_LAG = &#39;1 hour&#39;<br>EMBEDDING_MODEL = &#39;snowflake-arctic-embed-l-v2.0&#39;<br>AS<br>SELECT TITLE, RAW_TEXT<br>FROM wikipedia_articles;</pre><p>After creation, verify the service status is ACTIVE with SHOW CORTEX SEARCH SERVICES, and confirm the embedding model with DESCRIBE CORTEX SEARCH SERVICE.</p><h3>3.3 Interactive Search (SEARCH_PREVIEW)</h3><p>First, verify Interactive search behavior using the SEARCH_PREVIEW function.</p><p>SEARCH_PREVIEW takes parameters as a JSON string and returns results as JSON. You need PARSE_JSON to parse the output and FLATTEN to expand the results array into rows.</p><pre>SELECT<br>    r.value:TITLE::VARCHAR AS title,<br>    LEFT(r.value:RAW_TEXT::VARCHAR, 200) AS raw_text_preview<br>FROM TABLE(FLATTEN(<br>    input =&gt; PARSE_JSON(<br>        SNOWFLAKE.CORTEX.SEARCH_PREVIEW(<br>            &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>            &#39;{<br>                &quot;query&quot;: &quot;machine learning artificial intelligence&quot;,<br>                &quot;columns&quot;: [&quot;TITLE&quot;, &quot;RAW_TEXT&quot;],<br>                &quot;limit&quot;: 5<br>            }&#39;<br>        )<br>    ):results<br>)) AS r;</pre><p>The second argument to SEARCH_PREVIEW must be a <strong>JSON string literal</strong> — column references and dynamic expressions are not allowed. This means you cannot loop over many queries in pure SQL, making the Batch API essential for high-volume search.</p><p>Filtering is also supported via the filter parameter on columns specified in ATTRIBUTES:</p><pre>SELECT<br>    r.value:TITLE::VARCHAR AS title<br>FROM TABLE(FLATTEN(<br>    input =&gt; PARSE_JSON(<br>        SNOWFLAKE.CORTEX.SEARCH_PREVIEW(<br>            &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>            &#39;{<br>                &quot;query&quot;: &quot;history of ancient civilizations&quot;,<br>                &quot;columns&quot;: [&quot;TITLE&quot;, &quot;RAW_TEXT&quot;],<br>                &quot;filter&quot;: {&quot;@eq&quot;: {&quot;TITLE&quot;: &quot;Energy and Civilization: A History&quot;}},<br>                &quot;limit&quot;: 5<br>            }&#39;<br>        )<br>    ):results<br>)) AS r;</pre><h3>3.4 Batch Cortex Search Basics</h3><p>Create a query table and run CORTEX_SEARCH_BATCH for bulk search.</p><p>The basic syntax uses a LATERAL join from the query table to CORTEX_SEARCH_BATCH. Each row&#39;s query_text column is used directly as the search query.</p><pre>CREATE OR REPLACE TEMPORARY TABLE ten_searches (query_text VARCHAR);<br><br>INSERT INTO ten_searches VALUES<br>    (&#39;quantum physics&#39;),<br>    (&#39;world war history&#39;),<br>    (&#39;climate change&#39;),<br>    (&#39;solar system&#39;),<br>    (&#39;ancient rome&#39;),<br>    (&#39;machine learning&#39;),<br>    (&#39;french revolution&#39;),<br>    (&#39;deep ocean&#39;),<br>    (&#39;renewable energy&#39;),<br>    (&#39;human brain&#39;);<br><br>SELECT<br>    q.query_text,<br>    s.*<br>FROM ten_searches AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    query =&gt; q.query_text,<br>    limit =&gt; 1<br>) AS s;</pre><p>Key parameters for CORTEX_SEARCH_BATCH:</p><ul><li>service_name — fully qualified name of the target Cortex Search Service</li><li>query — column reference from the query table (unlike SEARCH_PREVIEW, dynamic column references are supported)</li><li>limit — number of results per query</li></ul><p>The key difference from SEARCH_PREVIEW: while SEARCH_PREVIEW requires a JSON string literal, CORTEX_SEARCH_BATCH accepts column references like query =&gt; q.query_text.</p><h3>3.5 Scalability &amp; Performance Comparison</h3><p>We scaled query counts from 100 → 1,000 → 10,000 and compared execution times between Interactive (SEARCH_PREVIEW) and Batch (CORTEX_SEARCH_BATCH).</p><p>Query tables are created by randomly sampling TITLEs from the existing wikipedia_articles table:</p><pre>CREATE OR REPLACE TABLE hundred_searches AS<br>SELECT DISTINCT TITLE AS query_text<br>FROM wikipedia_articles<br>ORDER BY RANDOM()<br>LIMIT 100;<br><br>CREATE OR REPLACE TABLE thousand_searches AS<br>SELECT DISTINCT TITLE AS query_text<br>FROM wikipedia_articles<br>ORDER BY RANDOM()<br>LIMIT 1000;<br><br>CREATE OR REPLACE TABLE ten_thousand_searches AS<br>SELECT DISTINCT TITLE AS query_text<br>FROM wikipedia_articles<br>ORDER BY RANDOM()<br>LIMIT 10000;</pre><p>Batch search runs via SQL LATERAL join:</p><pre>SELECT q.query_text, s.*<br>FROM thousand_searches AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    query =&gt; q.query_text,<br>    limit =&gt; 1<br>) AS s;</pre><p>Interactive search, due to SEARCH_PREVIEW&#39;s constraint (constant string arguments only), cannot iterate over table rows in pure SQL. We measured it by calling SEARCH_PREVIEW one query at a time from Python.</p><h4>Performance Results</h4><ul><li><strong>100 queries</strong>: Interactive 59.4s (1.7 QPS) → Batch 9.0s (11.2 QPS) — <strong>6.6x speedup</strong></li><li><strong>1,000 queries</strong>: Interactive 602.9s (1.7 QPS) → Batch 13.2s (75.6 QPS) — <strong>45.6x speedup</strong></li><li><strong>10,000 queries</strong>: Interactive 5,985s* (1.7 QPS) → Batch 50.9s (196.3 QPS) — <strong>117.5x speedup</strong></li></ul><p><em>Interactive at 10,000 queries is estimated from the measured QPS average (1.67 QPS) at 100 and 1,000 queries.</em></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*PcYx_z9DkItBR2Ha4KiWQg.png" /></figure><p>The Batch API has approximately 30 seconds of startup overhead, but after that it processes at high throughput — so the speedup multiplier grows as query count increases. Interactive QPS remains nearly constant (~1.7 QPS) regardless of query count, while Batch QPS scales up with query volume.</p><h4>Warehouse-Size Independence</h4><p>CORTEX_SEARCH_BATCH uses dedicated compute resources, so warehouse size does not affect throughput. Running the same 1,000-query batch on SMALL vs MEDIUM warehouses produced nearly identical execution times. A SMALL warehouse is sufficient for batch execution.</p><h3>3.6 SQL Syntax Variations</h3><p>The LATERAL join in CORTEX_SEARCH_BATCH supports various query sources: regular tables, TEMPORARY TABLEs, VIEWs, and CTEs (WITH clauses).</p><pre>WITH cte_queries AS (<br>    SELECT &#39;artificial intelligence&#39; AS query_text<br>    UNION ALL<br>    SELECT &#39;global warming&#39;<br>    UNION ALL<br>    SELECT &#39;space exploration&#39;<br>)<br>SELECT q.query_text, s.*<br>FROM cte_queries AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    query =&gt; q.query_text,<br>    limit =&gt; 3<br>) AS s;</pre><p>VIEWs work with the same LATERAL pattern:</p><pre>CREATE OR REPLACE VIEW search_queries_view AS<br>SELECT DISTINCT TITLE AS query_text<br>FROM wikipedia_articles<br>ORDER BY RANDOM()<br>LIMIT 10;<br><br>SELECT q.query_text, s.*<br>FROM search_queries_view AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    query =&gt; q.query_text,<br>    limit =&gt; 3<br>) AS s;</pre><p>All syntax variations were confirmed to work correctly.</p><h3>3.7 Batch Execution with Suspended Service</h3><p>We tested behavior when the Cortex Search Service is in a Suspended state. After stopping the service with ALTER ... SUSPEND, we ran both Interactive and Batch searches:</p><pre>ALTER CORTEX SEARCH SERVICE wikipedia_search_service SUSPEND;<br><br>-- Interactive search → Error<br>SELECT SNOWFLAKE.CORTEX.SEARCH_PREVIEW(<br>    &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    &#39;{&quot;query&quot;: &quot;machine learning&quot;, &quot;columns&quot;: [&quot;TITLE&quot;], &quot;limit&quot;: 1}&#39;<br>) AS test_result;<br><br>-- Batch search → Works normally<br>SELECT q.query_text, s.*<br>FROM ten_searches AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKIPEDIA_SEARCH_SERVICE&#39;,<br>    query =&gt; q.query_text,<br>    limit =&gt; 1<br>) AS s;</pre><p>Interactive search returns an error when the service is Suspended, but <strong>Batch search returns results normally</strong>. This is documented behavior — Batch processing uses dedicated compute resources separate from Interactive, so it does not depend on the service’s Serving state.</p><blockquote><strong><em>Tip</em></strong><em>: When Interactive search is not needed, you can Suspend the service to reduce Serving cost while continuing to run Batch processing.</em></blockquote><h3>3.8 Multi-Index Search (multi_index_query)</h3><p>The standard CREATE CORTEX SEARCH SERVICE ... ON syntax creates a single-column index. Using the TEXT INDEXES / VECTOR INDEXES syntax, you can create <strong>indexes of different types on multiple columns</strong>.</p><h4>Service Creation</h4><p>For a multi-index service, TEXT INDEXES specifies keyword search columns and VECTOR INDEXES specifies vector search columns:</p><pre>CREATE OR REPLACE TABLE wiki_multi AS<br>SELECT<br>    TITLE,<br>    LEFT(RAW_TEXT, 500) AS RAW_TEXT<br>FROM wikipedia_articles<br>LIMIT 1000;<br><br>CREATE OR REPLACE CORTEX SEARCH SERVICE wiki_multi_search_service<br>    TEXT INDEXES TITLE<br>    VECTOR INDEXES RAW_TEXT (model=&#39;snowflake-arctic-embed-l-v2.0&#39;)<br>    WAREHOUSE = BATCH_SEARCH_WH<br>    TARGET_LAG = &#39;1 hour&#39;<br>    AS SELECT TITLE, RAW_TEXT FROM wiki_multi;</pre><p>VECTOR INDEXES requires (model=&#39;...&#39;) after the column name to specify the embedding model. TEXT INDEXES requires no model specification.</p><h4>Query Syntax</h4><p>For multi-index services, use multi_index_query instead of the query parameter. Use OBJECT_CONSTRUCT with index column names as keys and ARRAY_CONSTRUCT to specify the search method for each column.</p><p>Two search methods are available:</p><ul><li>OBJECT_CONSTRUCT(&#39;text&#39;, ...) — the service embeds the text for vector search, or performs keyword search (for text indexes)</li><li>OBJECT_CONSTRUCT(&#39;vector&#39;, ...) — BYOV (Bring Your Own Vector): pass a pre-generated embedding directly</li></ul><h4>Vector Index Only</h4><p>Search using only the RAW_TEXT vector index, specifying a single index column in multi_index_query.It is little bit confusing. Because RAW_TEXT (a vector index column) is queried with the &#39;text&#39; type, and the service automatically embeds the text inside system:</p><pre>SELECT q.query_text, s.*<br>FROM (SELECT &#39;quantum physics&#39; AS query_text) AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKI_MULTI_SEARCH_SERVICE&#39;,<br>    multi_index_query =&gt; OBJECT_CONSTRUCT(<br>        &#39;RAW_TEXT&#39;, ARRAY_CONSTRUCT(<br>            OBJECT_CONSTRUCT(&#39;text&#39;, q.query_text)<br>        )<br>    ),<br>    limit =&gt; 3<br>) AS s;</pre><h4>Using a Text Index</h4><p>Attempting to search with only a text index results in the error: &quot;At least one vector index must be supplied in each query&quot;. <strong>A minimum of one vector index is required in multi_index_query.</strong></p><p>Therefore, text indexes must be used in combination with a vector index. In the query below, RAW_TEXT (a vector index column) is queried with the &#39;text&#39; type — the service automatically embeds the text and performs vector search on vector index columns, so the query executes successfully:</p><pre>SELECT q.query_text, s.*<br>FROM (SELECT &#39;machine learning&#39; AS query_text) AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKI_MULTI_SEARCH_SERVICE&#39;,<br>    multi_index_query =&gt; OBJECT_CONSTRUCT(<br>        &#39;TITLE&#39;, ARRAY_CONSTRUCT(<br>            OBJECT_CONSTRUCT(&#39;text&#39;, q.query_text)<br>        ),<br>        &#39;RAW_TEXT&#39;, ARRAY_CONSTRUCT(<br>            OBJECT_CONSTRUCT(&#39;text&#39;, q.query_text)<br>        )<br>    ),<br>    limit =&gt; 3<br>) AS s;</pre><h4>Keyword + Vector Hybrid Query (BYOV)</h4><p>Combine keyword search on TITLE with a pre-generated embedding vector from AI_EMBED on RAW_TEXT:</p><pre>SELECT q.query_text, s.*<br>FROM (<br>    SELECT<br>        &#39;climate change&#39; AS query_text,<br>        AI_EMBED(<br>            &#39;snowflake-arctic-embed-l-v2.0&#39;,<br>            &#39;climate change&#39;<br>        )::ARRAY AS query_embedding<br>) AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;BATCH_DEMO.PUBLIC.WIKI_MULTI_SEARCH_SERVICE&#39;,<br>    multi_index_query =&gt; OBJECT_CONSTRUCT(<br>        &#39;TITLE&#39;, ARRAY_CONSTRUCT(<br>            OBJECT_CONSTRUCT(&#39;text&#39;, q.query_text)<br>        ),<br>        &#39;RAW_TEXT&#39;, ARRAY_CONSTRUCT(<br>            OBJECT_CONSTRUCT(&#39;vector&#39;, q.query_embedding)<br>        )<br>    ),<br>    limit =&gt; 3<br>) AS s;</pre><p>Use AI_EMBED with the same model specified during service creation, and cast to ::ARRAY before passing.</p><h4>scoring_config (Not Yet Enabled)</h4><p>The options parameter with scoring_config allows you to control weights for text, vector, and reranker scoring:</p><pre>-- As of April 2025, scoring_config is not yet enabled<br>SELECT q.query_text, s.*<br>FROM (...) AS q,<br>LATERAL CORTEX_SEARCH_BATCH(<br>    service_name =&gt; &#39;...&#39;,<br>    multi_index_query =&gt; OBJECT_CONSTRUCT(...),<br>    options =&gt; OBJECT_CONSTRUCT(<br>        &#39;scoring_config&#39;, OBJECT_CONSTRUCT(<br>            &#39;weights&#39;, OBJECT_CONSTRUCT(<br>                &#39;texts&#39;, 1,<br>                &#39;vectors&#39;, 4,<br>                &#39;reranker&#39;, 0<br>            )<br>        )<br>    ),<br>    limit =&gt; 3<br>) AS s;</pre><blockquote><strong><em>Note</em></strong><em>: As of April 2025, the </em><em>scoring_config parameters (</em><em>weights and </em><em>text_boosts) are not yet enabled (</em><em>feature is not enabled error). Once enabled, they will allow fine-grained control over the scoring balance between vector and keyword search.</em></blockquote><h3>4. Cost Structure</h3><p>Understanding the cost structure is important when using Batch Cortex Search, as it differs from Interactive search.</p><h3>4.1 Batch Cortex Search Pricing</h3><p>According to the Snowflake consumption table, Batch Cortex Search is priced at <strong>0.12 Credits per GB/hr of indexed data</strong>.</p><h4>Pricing Formula</h4><p>Cost estimates follow three steps:</p><p><strong>Step 1: Estimate Index Size (GB)</strong></p><pre>GB = num_rows × count_indexes × dimension × (4 + 500) / 1e9</pre><ul><li>num_rows — Number of rows in the index</li><li>count_indexes — Number of embedding columns in the index</li><li>dimension — Embedding model dimension (768 or 1024)</li><li>4 + 500 — Bytes per row (4-byte vector + 500-byte metadata)</li></ul><p><strong>Step 2: Estimate Processing Time (HR)</strong></p><pre>HR = query_size / 100 / 3600</pre><ul><li>query_size — Number of input queries</li><li>100 — Standard QPS for Cortex Batch Search</li></ul><p><strong>Step 3: Calculate Cost</strong></p><pre>Batch Serving Cost = 0.12 × GB × HR (Credits)</pre><p><strong>Example (100K rows, 1024 dimensions, 10,000 queries):</strong></p><pre>Step 1: GB = 100,000 × 1 × 1024 × (4 + 500) / 1e9 ≈ 0.0516 GB<br>Step 2: HR = 10,000 / 100 / 3600 = 0.0278 hours (~100 seconds)<br>Step 3: Batch Serving Cost = 0.12 × 0.0516 × 0.0278 ≈ 0.000172 Credits</pre><p>At the 100K-row scale, the Batch Serving Cost itself is very low.</p><h4>3 Cost Components</h4><p>Total cost for Batch search includes three components:</p><ul><li><strong>Serving cost</strong> — Charged per the formula above (0.12 Credits/GB/hr). Startup time is excluded. Uses dedicated compute resources separate from Interactive</li><li><strong>Query embedding cost</strong> — Charged based on input query token count. <strong>Interactive query embedding is free, but Batch query embedding is charged</strong></li><li><strong>Virtual warehouse cost</strong> — Compute charges for the warehouse running the batch job. WH size doesn’t affect throughput, so SMALL is sufficient</li></ul><blockquote><strong><em>Important</em></strong><em>: Interactive search query embedding is free, but </em><strong><em>Batch search query embedding is charged</em></strong><em>. Factor this into your cost estimates when submitting large query volumes.</em></blockquote><h3>4.2 Overall Cortex Search Service Costs (Interactive / Batch Common)</h3><p>Service maintenance costs should also be understood. Note that <strong>Batch search can execute queries even when the service is Suspended</strong>, so Serving costs can be reduced.</p><ul><li><strong>Embedding tokens compute</strong> — Cost for vectorizing source text. Incurred at creation + data add/update (Credits / 1M tokens)</li><li><strong>Serving compute</strong> — Multi-tenant infrastructure cost. <strong>Charged while running, even with no queries</strong> (Credits / GB / month)</li><li><strong>Warehouse compute</strong> — Used for service refresh (change detection + index rebuild) (WH size × runtime)</li><li><strong>Storage</strong> — Materialized source data + search index storage (per-TB flat rate)</li><li><strong>Cloud services</strong> — Cloud Services compute for change detection (excess over 10% of daily WH cost)</li></ul><h3>4.3 Embedding Model Cost Impact</h3><p>Since Serving cost is charged per GB of indexed data, models with larger vector dimensions cost more. If multilingual support is not needed, the default model (768 dimensions) is more cost-efficient.</p><h3>4.4 Cost Optimization Tips</h3><ul><li><strong>SMALL WH is sufficient</strong> — Batch throughput is independent of warehouse size</li><li><strong>Suspend when not needed</strong> — Serving cost is always charged while the service is running. Suspend during development</li><li><strong>Batch works while Suspended</strong> — Batch operates even in Suspended state — Suspend to reduce Serving cost while running Batch</li><li><strong>Set TARGET_LAG to match business needs</strong> — Too short increases refresh frequency and WH costs</li><li><strong>Define PRIMARY KEYs</strong> — Optimizes refresh, significantly reducing cost and latency</li><li><strong>Monitor costs</strong> — Use CORTEX_SEARCH_BATCH_QUERY_USAGE_HISTORY view for Batch-specific cost monitoring</li></ul><h3>5. Summary</h3><ol><li><strong>Environment Setup</strong> — ✅ Marketplace integration, 100K-row table created</li><li><strong>Cortex Search Service</strong> — ✅ Service created, ACTIVE status, embedding model confirmed</li><li><strong>Interactive Search</strong> — ✅ Single query, filter, limit parameter behavior confirmed</li><li><strong>Batch Basics</strong> — ✅ LATERAL join, column returns, limit control confirmed</li><li><strong>Scalability</strong> — ✅ Up to 117.5x speedup with increasing query count</li><li><strong>SQL Syntax &amp; Operations</strong> — ✅ TABLE/VIEW/CTE support, Batch works in Suspended state</li><li><strong>Multi-Index Search</strong> — ✅ Vector-only, text+vector, BYOV hybrid confirmed. scoring_config not yet enabled</li></ol><h3>6. Takeaways &amp; Best Practices</h3><ul><li>Batch Cortex Search shows clear advantages over Interactive starting at <strong>around 100 queries</strong>. At 10,000 queries, we observed a <strong>117.5x speedup</strong></li><li>Batch QPS scales with query count (11 QPS → 76 QPS → 196 QPS). After the ~30-second startup, throughput stabilizes at high levels</li><li>Warehouse size has no impact, so <strong>SMALL WH is sufficient</strong> for cost optimization</li><li>The LATERAL syntax supports flexible query sources: tables, VIEWs, and CTEs</li><li>Batch works in Suspended state, enabling the pattern of <strong>Suspending the service to reduce Serving cost while running Batch processing</strong> when Interactive is not needed</li><li>Interactive’s SEARCH_PREVIEW is limited to constant string arguments, making high-volume search impractical in pure SQL. For bulk search, the Batch API is effectively required</li></ul><h3>7. Cleanup</h3><p>After verification, delete resources with the following SQL:</p><pre>USE ROLE ACCOUNTADMIN;<br>USE DATABASE BATCH_DEMO;<br>USE SCHEMA PUBLIC;<br><br>DROP CORTEX SEARCH SERVICE IF EXISTS WIKIPEDIA_SEARCH_SERVICE;<br>DROP TABLE IF EXISTS wikipedia_articles;<br>DROP TABLE IF EXISTS hundred_searches;<br>DROP TABLE IF EXISTS thousand_searches;<br>DROP TABLE IF EXISTS ten_thousand_searches;<br>DROP VIEW IF EXISTS search_queries_view;<br>DROP WAREHOUSE IF EXISTS BATCH_SEARCH_WH_MEDIUM;<br><br>-- Optional: Drop DB and WH<br>-- DROP DATABASE IF EXISTS BATCH_DEMO;<br>-- DROP WAREHOUSE IF EXISTS BATCH_SEARCH_WH;<br>-- DROP DATABASE IF EXISTS AI_TRAINING_DATASET_FROM_WIKIPEDIA;</pre><h3>References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview">Cortex Search Overview — Snowflake Documentation</a></li><li><a href="https://www.snowflake.com/en/developers/guides/getting-started-with-batch-cortex-search/">Getting Started with Batch Cortex Search — Quickstarts</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/sql/create-cortex-search">CREATE CORTEX SEARCH SERVICE — SQL Reference</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-overview#cost-considerations">Cortex Search Billing — Snowflake Documentation</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/batch-cortex-search">Batch Cortex Search Documentation</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=3b37240cbdb5" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Snowflake Cortex Agent Evaluations is now in GA]]></title>
            <link>https://medium.com/@masato.takada/snowflake-cortex-agent-evaluations-is-now-in-ga-a19001273518?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/a19001273518</guid>
            <category><![CDATA[snowflake-cortex-agent]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Wed, 18 Mar 2026 05:05:14 GMT</pubDate>
            <atom:updated>2026-03-18T05:05:14.785Z</atom:updated>
            <content:encoded><![CDATA[<blockquote>The author is employed by Snowflake, but the views expressed in this article are personal and do not represent the official position of the organization.</blockquote><h3>Introduction</h3><p>Building an AI agent is just the first step. To deliver reliable applications in production, <strong>quantitatively evaluating</strong> agent performance is essential.</p><p>Snowflake Cortex Agent Evaluations is a native feature for measuring Cortex Agent performance from multiple perspectives. A key advantage is that everything from running evaluations to retrieving results can be accomplished with SQL alone.</p><p>In this article, we’ll walk through Cortex Agent Evaluations using an e-commerce customer support Agent as a practical example. The diagram below shows the overall flow.</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/1*8mxTvsHdDE2Ib8DPEMKqog.png" /></figure><h3>What You’ll Learn</h3><ul><li>Basic concepts and built-in metrics of Cortex Agent Evaluations</li><li>How to create evaluation datasets</li><li>Running evaluations with EXECUTE_AI_EVALUATION</li><li>Retrieving and analyzing results with GET_AI_EVALUATION_DATA</li><li>Defining custom metrics</li></ul><h3>What is Cortex Agent Evaluations?</h3><p>Cortex Agent Evaluations is a feature for systematically measuring and improving Cortex Agent behavior and performance.</p><h3>Built-in Metrics</h3><p>Snowflake provides the following evaluation metrics out of the box:</p><p>MetricDescriptionCharacteristics<strong>Answer Correctness</strong>How well the agent’s response matches the expected answer (Ground Truth)Requires Ground Truth<strong>Logical Consistency</strong>Consistency across agent instructions, planning, and tool callsReference-free (no Ground Truth needed)</p><h3>Custom Metrics</h3><p>In addition to built-in metrics, you can define custom metrics using the LLM-as-Judge pattern. This enables evaluations tailored to your use case, such as politeness assessment in Japanese or domain-specific quality criteria.</p><h3>Validation Scenario</h3><p>In this article, we’ll evaluate an <strong>e-commerce customer support Agent</strong>.</p><p>This Agent has the following capabilities:</p><ul><li><strong>Product information lookup</strong>: Uses Semantic View (Text-to-SQL)</li><li><strong>FAQ search</strong>: Uses Cortex Search Service</li><li><strong>Order status check</strong>: Uses Semantic View (Text-to-SQL)</li></ul><p>In this sector, We will learn how to evaluate Cortex Agents by using some script. My experiment was originally utilizing <strong>JAPANESE</strong> dataset. Please note that your result may be different between this articles after your execution.</p><h3>Phase 1: Environment Setup</h3><h3>Creating Database and Schemas</h3><pre>-- Create database<br>CREATE DATABASE IF NOT EXISTS CORTEX_AGENTS_EVAL;<br><br>-- Create schemas<br>CREATE SCHEMA IF NOT EXISTS CORTEX_AGENTS_EVAL.RAW_DATA;<br>CREATE SCHEMA IF NOT EXISTS CORTEX_AGENTS_EVAL.SEARCH;<br>CREATE SCHEMA IF NOT EXISTS CORTEX_AGENTS_EVAL.ANALYST;<br>CREATE SCHEMA IF NOT EXISTS CORTEX_AGENTS_EVAL.AGENTS;<br>CREATE SCHEMA IF NOT EXISTS CORTEX_AGENTS_EVAL.EVALUATION;<br>-- Create warehouse<br>CREATE WAREHOUSE IF NOT EXISTS CORTEX_AGENTS_WH<br>    WAREHOUSE_SIZE = &#39;XSMALL&#39;<br>    AUTO_SUSPEND = 60<br>    AUTO_RESUME = TRUE;</pre><h3>Creating Test Data</h3><pre>-- Product master<br>CREATE OR REPLACE TABLE CORTEX_AGENTS_EVAL.RAW_DATA.PRODUCTS (<br>    product_id VARCHAR,<br>    product_name VARCHAR,<br>    category VARCHAR,<br>    price NUMBER(10, 0),<br>    stock INT,<br>    description VARCHAR<br>);<br><br>INSERT INTO CORTEX_AGENTS_EVAL.RAW_DATA.PRODUCTS VALUES<br>(&#39;P001&#39;, &#39;Wireless Earphones Pro&#39;, &#39;Audio&#39;, 12800, 50, &#39;High-quality Bluetooth 5.0 with noise cancellation&#39;),<br>(&#39;P002&#39;, &#39;Bluetooth Speaker Mini&#39;, &#39;Audio&#39;, 8500, 30, &#39;Compact and portable, IPX5 waterproof&#39;),<br>(&#39;P003&#39;, &#39;Smart Watch Fit&#39;, &#39;Wearable&#39;, 35000, 20, &#39;Heart rate monitor, GPS, sleep tracking&#39;),<br>(&#39;P004&#39;, &#39;Fast Wireless Charger&#39;, &#39;Accessories&#39;, 3500, 100, &#39;15W fast charging, Qi compatible&#39;),<br>(&#39;P005&#39;, &#39;USB Hub 7-Port&#39;, &#39;Accessories&#39;, 2800, 80, &#39;USB 3.0, 5Gbps transfer speed&#39;);<br><br>-- Order history<br>CREATE OR REPLACE TABLE CORTEX_AGENTS_EVAL.RAW_DATA.ORDERS (<br>    order_id VARCHAR,<br>    customer_id VARCHAR,<br>    product_id VARCHAR,<br>    order_date DATE,<br>    status VARCHAR,<br>    total_amount NUMBER(10, 0)<br>);<br>INSERT INTO CORTEX_AGENTS_EVAL.RAW_DATA.ORDERS VALUES<br>(&#39;ORD001&#39;, &#39;C001&#39;, &#39;P001&#39;, &#39;2026-03-01&#39;, &#39;Delivered&#39;, 12800),<br>(&#39;ORD002&#39;, &#39;C001&#39;, &#39;P004&#39;, &#39;2026-03-05&#39;, &#39;Shipped&#39;, 3500),<br>(&#39;ORD003&#39;, &#39;C002&#39;, &#39;P003&#39;, &#39;2026-03-08&#39;, &#39;Preparing&#39;, 35000),<br>(&#39;ORD004&#39;, &#39;C002&#39;, &#39;P002&#39;, &#39;2026-03-10&#39;, &#39;Confirmed&#39;, 8500),<br>(&#39;ORD005&#39;, &#39;C001&#39;, &#39;P005&#39;, &#39;2026-03-12&#39;, &#39;Confirmed&#39;, 2800);<br><br>-- FAQ documents<br>CREATE OR REPLACE TABLE CORTEX_AGENTS_EVAL.RAW_DATA.FAQ_DOCS (<br>    doc_id VARCHAR,<br>    question VARCHAR,<br>    answer VARCHAR,<br>    category VARCHAR<br>);<br>INSERT INTO CORTEX_AGENTS_EVAL.RAW_DATA.FAQ_DOCS VALUES<br>(&#39;FAQ001&#39;, &#39;Can I return or exchange items?&#39;, &#39;Returns and exchanges are accepted within 14 days of delivery. Items must be unopened and unused. To request a return, please contact customer support with your order number and reason for return. Shipping costs for customer-initiated returns are the customer&#39;&#39;s responsibility.&#39;, &#39;Returns&#39;),<br>(&#39;FAQ002&#39;, &#39;How long does shipping take?&#39;, &#39;Standard delivery takes 3-5 business days. Remote areas may require an additional 2-3 days. For urgent orders, next-day delivery is available for an additional $5 fee.&#39;, &#39;Shipping&#39;),<br>(&#39;FAQ003&#39;, &#39;What payment methods are available?&#39;, &#39;We accept credit cards (VISA, MasterCard, JCB, AMEX), bank transfer, convenience store payment, and cash on delivery. Cash on delivery incurs a $3 handling fee.&#39;, &#39;Payment&#39;);</pre><h3>Phase 2: Creating Cortex Search + Semantic View</h3><h3>Cortex Search Service (for FAQ Search)</h3><pre>CREATE OR REPLACE CORTEX SEARCH SERVICE CORTEX_AGENTS_EVAL.SEARCH.FAQ_SEARCH_SERVICE<br>ON answer<br>ATTRIBUTES category, question<br>WAREHOUSE = CORTEX_AGENTS_WH<br>TARGET_LAG = &#39;1 hour&#39;<br>AS (<br>    SELECT <br>        doc_id,<br>        question,<br>        answer,<br>        category<br>    FROM CORTEX_AGENTS_EVAL.RAW_DATA.FAQ_DOCS<br>);</pre><h3>Semantic View (for Product and Order Queries)</h3><pre>CREATE OR REPLACE SEMANTIC VIEW CORTEX_AGENTS_EVAL.ANALYST.EC_DATA_SEMANTIC_VIEW<br>  TABLES (<br>    products AS CORTEX_AGENTS_EVAL.RAW_DATA.PRODUCTS<br>      WITH SYNONYMS = (&#39;product&#39;, &#39;item&#39;, &#39;goods&#39;, &#39;merchandise&#39;)<br>      PRIMARY KEY (product_id)<br>      AS (<br>        product_id WITH SYNONYMS = (&#39;product ID&#39;, &#39;item ID&#39;, &#39;product code&#39;),<br>        product_name WITH SYNONYMS = (&#39;product name&#39;, &#39;item name&#39;, &#39;name&#39;),<br>        category WITH SYNONYMS = (&#39;category&#39;, &#39;type&#39;, &#39;classification&#39;),<br>        price WITH SYNONYMS = (&#39;price&#39;, &#39;cost&#39;, &#39;amount&#39;, &#39;unit price&#39;),<br>        stock WITH SYNONYMS = (&#39;stock&#39;, &#39;inventory&#39;, &#39;quantity&#39;, &#39;available&#39;),<br>        description WITH SYNONYMS = (&#39;description&#39;, &#39;details&#39;, &#39;product description&#39;)<br>      ),<br>    orders AS CORTEX_AGENTS_EVAL.RAW_DATA.ORDERS<br>      WITH SYNONYMS = (&#39;order&#39;, &#39;purchase&#39;, &#39;transaction&#39;, &#39;purchase history&#39;)<br>      PRIMARY KEY (order_id)<br>      AS (<br>        order_id WITH SYNONYMS = (&#39;order ID&#39;, &#39;order number&#39;, &#39;transaction ID&#39;),<br>        customer_id WITH SYNONYMS = (&#39;customer ID&#39;, &#39;client ID&#39;, &#39;user ID&#39;),<br>        product_id WITH SYNONYMS = (&#39;product ID&#39;, &#39;item ID&#39;),<br>        order_date WITH SYNONYMS = (&#39;order date&#39;, &#39;purchase date&#39;, &#39;transaction date&#39;),<br>        status WITH SYNONYMS = (&#39;status&#39;, &#39;state&#39;, &#39;progress&#39;),<br>        total_amount WITH SYNONYMS = (&#39;total amount&#39;, &#39;total&#39;, &#39;order amount&#39;, &#39;amount&#39;)<br>      )<br>  )<br>  RELATIONSHIPS (<br>    orders (product_id) REFERENCES products (product_id)<br>  )<br>  FACTS (<br>    products.price AS price_fact,<br>    products.stock AS stock_fact,<br>    orders.total_amount AS order_amount_fact<br>  )<br>  DIMENSIONS (<br>    products.category AS product_category,<br>    orders.status AS order_status<br>  )<br>  METRICS (<br>    SUM(orders.total_amount) AS total_sales WITH SYNONYMS = (&#39;total revenue&#39;, &#39;sales total&#39;),<br>    AVG(products.price) AS avg_price WITH SYNONYMS = (&#39;average price&#39;, &#39;mean price&#39;)<br>  );</pre><h3>Phase 3: Creating the Cortex Agent</h3><pre>CREATE OR REPLACE AGENT CORTEX_AGENTS_EVAL.AGENTS.EC_SUPPORT_AGENT<br>EXTERNAL_ACCESS_INTEGRATIONS = ()<br>SPEC = $$<br>{<br>  &quot;models&quot;: {<br>    &quot;orchestration&quot;: &quot;claude-4-sonnet&quot;<br>  },<br>  &quot;orchestration&quot;: {<br>    &quot;budget&quot;: {<br>      &quot;seconds&quot;: 60,<br>      &quot;tokens&quot;: 32000<br>    }<br>  },<br>  &quot;instructions&quot;: {<br>    &quot;response&quot;: &quot;You are an e-commerce customer support agent. Please respond to customer inquiries politely and accurately.&quot;,<br>    &quot;orchestration&quot;: &quot;Select the appropriate tool based on the customer&#39;s question. Use product_query for product information and order status, and faq_search for FAQs.&quot;,<br>    &quot;system&quot;: &quot;Scope: 1. Product information (price, stock, details) 2. Order status check 3. FAQ (returns, shipping, payment, etc.). Politely decline questions outside this scope.&quot;<br>  },<br>  &quot;tools&quot;: [<br>    {<br>      &quot;tool_spec&quot;: {<br>        &quot;type&quot;: &quot;cortex_analyst_text_to_sql&quot;,<br>        &quot;name&quot;: &quot;product_query&quot;,<br>        &quot;description&quot;: &quot;Searches product information, inventory status, and order history. Can search by product ID, category, customer ID, order number, etc.&quot;<br>      }<br>    },<br>    {<br>      &quot;tool_spec&quot;: {<br>        &quot;type&quot;: &quot;cortex_search&quot;,<br>        &quot;name&quot;: &quot;faq_search&quot;,<br>        &quot;description&quot;: &quot;Searches frequently asked questions (FAQ). Can answer common questions about returns, shipping, payment methods, etc.&quot;<br>      }<br>    }<br>  ],<br>  &quot;tool_resources&quot;: {<br>    &quot;product_query&quot;: {<br>      &quot;semantic_view&quot;: &quot;CORTEX_AGENTS_EVAL.ANALYST.EC_DATA_SEMANTIC_VIEW&quot;<br>    },<br>    &quot;faq_search&quot;: {<br>      &quot;search_service&quot;: &quot;CORTEX_AGENTS_EVAL.SEARCH.FAQ_SEARCH_SERVICE&quot;<br>    }<br>  }<br>}<br>$$;</pre><h3>Phase 4: Creating the Evaluation Dataset</h3><h3>Creating the Dataset Table</h3><p>The evaluation dataset requires the following two columns:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/386/1*PaAAVN-hYlweX3EgOkhBNw.png" /></figure><pre>CREATE OR REPLACE TABLE CORTEX_AGENTS_EVAL.EVALUATION.AGENT_EVAL_DATASET (<br>    input_query VARCHAR,<br>    ground_truth VARIANT<br>);</pre><h3>Inserting Evaluation Data</h3><p><strong><em>Important</em></strong><em>: The </em><em>GROUND_TRUTH column must be </em><strong><em>VARIANT type</em></strong><em>. Use the </em><em>PARSE_JSON function to convert properly.</em></p><pre>INSERT INTO CORTEX_AGENTS_EVAL.EVALUATION.AGENT_EVAL_DATASET<br>SELECT <br>    &#39;What is the stock status of product P001?&#39; AS input_query,<br>    PARSE_JSON(&#39;{<br>        &quot;ground_truth_output&quot;: &quot;Product P001 (Wireless Earphones Pro) has 50 units in stock. Priced at $128, it features high-quality Bluetooth 5.0 with noise cancellation.&quot;<br>    }&#39;) AS ground_truth<br>UNION ALL<br>SELECT <br>    &#39;Can I return an item?&#39;,<br>    PARSE_JSON(&#39;{<br>        &quot;ground_truth_output&quot;: &quot;Yes, returns are accepted within 14 days of delivery. Items must be unopened and unused. To request a return, please contact customer support with your order number and reason. Shipping costs are the customer&#39;&#39;s responsibility.&quot;<br>    }&#39;)<br>UNION ALL<br>SELECT <br>    &#39;I want to check the status of order ORD001&#39;,<br>    PARSE_JSON(&#39;{<br>        &quot;ground_truth_output&quot;: &quot;Here is the status of order ORD001. Status: Delivered, Order Date: March 1, 2026, Product: Wireless Earphones Pro, Amount: $128. This order has been delivered.&quot;<br>    }&#39;)<br>-- ... add other evaluation data similarly<br>;</pre><h3>Phase 5: Running the Evaluation</h3><h3>Step 1: Registering the Evaluation Dataset</h3><p><strong><em>Critical Point</em></strong><em>: Before running an evaluation, you must register the dataset using </em><em>SYSTEM$CREATE_EVALUATION_DATASET.</em></p><pre>CALL SYSTEM$CREATE_EVALUATION_DATASET(<br>    &#39;Cortex Agent&#39;,<br>    &#39;CORTEX_AGENTS_EVAL.EVALUATION.AGENT_EVAL_DATASET&#39;,<br>    &#39;CORTEX_AGENTS_EVAL.EVALUATION.EC_SUPPORT_EVAL_DS&#39;,<br>    OBJECT_CONSTRUCT(<br>        &#39;query_text&#39;, &#39;INPUT_QUERY&#39;, <br>        &#39;expected_tools&#39;, &#39;GROUND_TRUTH&#39;<br>    )<br>);</pre><p><strong>Parameter Description</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/545/1*RHGK6VgqaWJZKwr4G-6ypg.png" /></figure><h3>Step 2: Creating the Evaluation Configuration YAML</h3><pre># eval_config_basic.yaml<br>evaluation:<br>  agent_params:<br>    agent_name: &quot;CORTEX_AGENTS_EVAL.AGENTS.EC_SUPPORT_AGENT&quot;<br>    agent_type: &quot;CORTEX AGENT&quot;<br>  run_params:<br>    label: &quot;baseline_evaluation&quot;<br>    description: &quot;Baseline evaluation of EC support agent&quot;<br>  source_metadata:<br>    type: &quot;dataset&quot;  # Must be lowercase (important!)<br>    dataset_name: &quot;CORTEX_AGENTS_EVAL.EVALUATION.EC_SUPPORT_EVAL_DS&quot;<br><br>metrics:<br>  - &quot;answer_correctness&quot;<br>  - &quot;logical_consistency&quot;</pre><p><strong><em>Note</em></strong><em>: </em><em>source_metadata.type must be specified in </em><strong><em>lowercase</em></strong><em> as </em><em>&quot;dataset&quot;. Using uppercase </em><em>&quot;DATASET&quot; will cause an error.</em></p><h3>Step 3: Uploading the YAML File</h3><pre>-- Create stage<br>CREATE OR REPLACE STAGE CORTEX_AGENTS_EVAL.EVALUATION.EVAL_CONFIG_STAGE<br>    ENCRYPTION = (TYPE = &#39;SNOWFLAKE_SSE&#39;)<br>    DIRECTORY = (ENABLE = TRUE);</pre><p>We now use Snow CLI to upload the YAML file in this blog:</p><pre>snow stage copy eval_config_basic.yaml \<br>    @CORTEX_AGENTS_EVAL.EVALUATION.EVAL_CONFIG_STAGE \<br>    --connection &lt;connection_name&gt; \<br>    --overwrite</pre><h3>Step 4: Starting the Evaluation</h3><pre>CALL EXECUTE_AI_EVALUATION(<br>    &#39;START&#39;,<br>    OBJECT_CONSTRUCT(&#39;run_name&#39;, &#39;basic_eval_run_001&#39;),<br>    &#39;@CORTEX_AGENTS_EVAL.EVALUATION.EVAL_CONFIG_STAGE/eval_config_basic.yaml&#39;<br>);</pre><p><strong>Result</strong>:</p><pre>| RESULT                          |<br>|---------------------------------|<br>| Function executed successfully. |</pre><h3>Step 5: Checking Status</h3><p>Evaluation runs asynchronously. Check the status to wait for completion:</p><pre>CALL EXECUTE_AI_EVALUATION(<br>    &#39;STATUS&#39;,<br>    OBJECT_CONSTRUCT(&#39;run_name&#39;, &#39;basic_eval_run_001&#39;),<br>    &#39;@CORTEX_AGENTS_EVAL.EVALUATION.EVAL_CONFIG_STAGE/eval_config_basic.yaml&#39;<br>);</pre><p><strong>Status Transitions</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/428/1*xlPLxN3hzCqDUboeJ6W8zA.png" /></figure><h3>Viewing Results in Snowsight UI</h3><p>Evaluation results can be viewed not only via SQL but also through the Snowsight UI.</p><h3>Accessing the Evaluations Tab</h3><ol><li>Select <strong>AI &amp; ML</strong> → <strong>Agents</strong></li><li>Click on the target agent (e.g., EC_SUPPORT_AGENT)</li><li>Select the <strong>Evaluations</strong> tab</li></ol><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*K7GbxIhHG-t_Zaz8.png" /></figure><p>The Evaluations tab displays a list of executed evaluations:</p><ul><li><strong>Run Name</strong>: Name of the evaluation run (e.g., basic_eval_run_001)</li><li><strong>Status</strong>: Completion status (checkmark indicates completion)</li><li><strong>Dataset</strong>: Dataset name used</li><li><strong># of Records</strong>: Number of records evaluated</li><li><strong>AC (Answer Correctness)</strong>: Answer accuracy score (0.13 = 13%)</li><li><strong>LC (Logical Consistency)</strong>: Logical consistency score (0.93 = 93%)</li></ul><h3>Viewing Evaluation Details</h3><p>Click on an evaluation run to see details for each record.</p><p>The top of the screen shows aggregated information as graphs:</p><ul><li><strong>Answer Correctness</strong>: 0.13 (orange/red bar indicating low score)</li><li><strong>Logical Consistency</strong>: 0.93 (green bar indicating high score)</li></ul><p>For each record, you can see the correspondence between input (INPUT) and output (OUTPUT), along with scores. This helps quickly identify which queries have issues.</p><blockquote><strong><em>Analysis of Current Results</em></strong><em>: While Logical Consistency is high at 93%, Answer Correctness is low at 13%. This is because the agent responded with general knowledge without making tool calls. This indicates that Agent SPEC adjustments or forced tool call settings are needed.</em></blockquote><figure><img alt="" src="https://cdn-images-1.medium.com/max/1024/0*hAIiMYY6o1DIODJZ.png" /></figure><p><strong>What you can do in the UI</strong>:</p><ul><li>Create evaluation runs</li><li>Filter and search evaluation results</li><li>View score trends over time</li><li>View details and traces for each record</li></ul><h3>Phase 6: Retrieving and Analyzing Results</h3><h3>Basic Result Retrieval</h3><pre>SELECT <br>    RECORD_ID,<br>    INPUT,<br>    OUTPUT,<br>    GROUND_TRUTH,<br>    METRIC_NAME,<br>    EVAL_AGG_SCORE,<br>    DURATION_MS<br>FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA(<br>    &#39;CORTEX_AGENTS_EVAL&#39;,<br>    &#39;AGENTS&#39;,<br>    &#39;EC_SUPPORT_AGENT&#39;,<br>    &#39;cortex agent&#39;,<br>    &#39;basic_eval_run_001&#39;<br>))<br>ORDER BY TIMESTAMP;</pre><p><strong>Example Output</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/556/1*9IherTZTYoQBjIQ6Fep0qg.png" /></figure><h3>Aggregation by Metric</h3><pre>SELECT <br>    METRIC_NAME,<br>    COUNT(*) AS record_count,<br>    AVG(EVAL_AGG_SCORE) AS avg_score,<br>    MIN(EVAL_AGG_SCORE) AS min_score,<br>    MAX(EVAL_AGG_SCORE) AS max_score<br>FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_EVALUATION_DATA(<br>    &#39;CORTEX_AGENTS_EVAL&#39;,<br>    &#39;AGENTS&#39;,<br>    &#39;EC_SUPPORT_AGENT&#39;,<br>    &#39;cortex agent&#39;,<br>    &#39;basic_eval_run_001&#39;<br>))<br>GROUP BY METRIC_NAME;</pre><p><strong>Example Results</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/524/1*bXIgRgBw-VJ8txCbE63vkQ.png" /></figure><h3>Retrieving Traces for Specific Records</h3><p>To analyze low-scoring records in detail, retrieve trace information:</p><pre>SELECT *<br>FROM TABLE(SNOWFLAKE.LOCAL.GET_AI_RECORD_TRACE(<br>    &#39;CORTEX_AGENTS_EVAL&#39;,<br>    &#39;AGENTS&#39;,<br>    &#39;EC_SUPPORT_AGENT&#39;,<br>    &#39;CORTEX AGENT&#39;,<br>    &#39;&lt;RECORD_ID&gt;&#39;<br>))<br>ORDER BY START_TIMESTAMP;</pre><h3>Phase 7: Defining Custom Metrics</h3><p>In addition to built-in metrics, you can define custom metrics based on business requirements.</p><h3>Example YAML with Custom Metrics</h3><pre>evaluation:<br>  agent_params:<br>    agent_name: &quot;CORTEX_AGENTS_EVAL.AGENTS.EC_SUPPORT_AGENT&quot;<br>    agent_type: &quot;CORTEX AGENT&quot;<br>  source_metadata:<br>    type: &quot;dataset&quot;<br>    dataset_name: &quot;CORTEX_AGENTS_EVAL.EVALUATION.EC_SUPPORT_EVAL_DS&quot;<br><br>metrics:<br>  # Built-in metrics<br>  - &quot;answer_correctness&quot;<br>  - &quot;logical_consistency&quot;<br>  <br>  # Custom metric: Response politeness<br>  - name: &quot;response_politeness&quot;<br>    score_ranges:<br>      min_score: [1, 3]<br>      median_score: [4, 6]<br>      max_score: [7, 10]<br>    prompt: |<br>      Evaluate the politeness and professionalism of the customer support response.<br>      <br>      Criteria:<br>      1-3: Rude or unprofessional language<br>      4-6: Basic politeness but room for improvement<br>      7-10: Polite and appropriate business language<br>      <br>      Response: {{output}}<br>      <br>      Respond with only a numeric score (1-10).<br>  # Custom metric: Answer completeness<br>  - name: &quot;answer_completeness&quot;<br>    score_ranges:<br>      min_score: [1, 3]<br>      median_score: [4, 6]<br>      max_score: [7, 10]<br>    prompt: |<br>      Evaluate whether the response comprehensively addresses the user&#39;s question.<br>      <br>      Criteria:<br>      1-3: Only partially addresses the question<br>      4-6: Includes main information but lacks supplementary details<br>      7-10: Complete and appropriately detailed response<br>      <br>      Question: {{input}}<br>      Response: {{output}}<br>      Expected response: {{ground_truth}}<br>      <br>      Respond with only a numeric score (1-10).</pre><h3>Available Placeholders</h3><p>The following placeholders can be used in custom metric prompts:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/328/1*RO-p9xT-MF1wr6pZYnnjbQ.png" /></figure><h3>Required Permissions</h3><p>The following permissions are required to run Cortex Agent Evaluations:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/468/1*uw9Rwg1Hu3zc0lFuwNgZQA.png" /></figure><pre>-- Example permission grants<br>GRANT DATABASE ROLE SNOWFLAKE.CORTEX_USER TO ROLE MY_ROLE;<br>GRANT EXECUTE TASK ON ACCOUNT TO ROLE MY_ROLE;<br>GRANT USAGE ON DATABASE CORTEX_AGENTS_EVAL TO ROLE MY_ROLE;<br>GRANT ALL ON SCHEMA CORTEX_AGENTS_EVAL.EVALUATION TO ROLE MY_ROLE;</pre><h3>Summary</h3><p>With Cortex Agent Evaluations, you can accomplish the following workflow using SQL alone:</p><pre>┌──────────────────────────────────────────────────────────────┐<br>│                   Evaluation Workflow                         │<br>│                                                              │<br>│  1. Register Dataset                                         │<br>│     SYSTEM$CREATE_EVALUATION_DATASET(...)                    │<br>│                    ↓                                         │<br>│  2. Start Evaluation                                         │<br>│     EXECUTE_AI_EVALUATION(&#39;START&#39;, ...)                      │<br>│                    ↓                                         │<br>│  3. Check Status                                             │<br>│     EXECUTE_AI_EVALUATION(&#39;STATUS&#39;, ...)                     │<br>│                    ↓                                         │<br>│  4. Retrieve Results                                         │<br>│     GET_AI_EVALUATION_DATA(...)                              │<br>│                    ↓                                         │<br>│  5. Analyze Traces                                           │<br>│     GET_AI_RECORD_TRACE(...)                                 │<br>│                    ↓                                         │<br>│  6. Improve → Re-evaluate → Compare                          │<br>└──────────────────────────────────────────────────────────────┘</pre><h3>Key Points</h3><ol><li><strong>Dataset registration is mandatory</strong>: Always run SYSTEM$CREATE_EVALUATION_DATASET first</li><li><strong>YAML config </strong><strong>type must be lowercase</strong>: Use &quot;dataset&quot; (uppercase causes errors)</li><li><strong>Ground Truth must be VARIANT type</strong>: Convert using PARSE_JSON</li><li><strong>Evaluation runs asynchronously</strong>: Poll with STATUS to confirm completion</li></ol><h3>References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-evaluations">Cortex Agent Evaluations Documentation</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/functions/execute_ai_evaluation">EXECUTE_AI_EVALUATION Function Reference</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/functions/get_ai_evaluation_data-snowflake-local">GET_AI_EVALUATION_DATA Function Reference</a></li><li><a href="https://www.snowflake.com/en/developers/guides/getting-started-with-cortex-agent-evaluations/">Getting Started with Cortex Agent Evaluations</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=a19001273518" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Mastering AI Cost Control in Snowflake: A Deep Dive into Resource Budgets for Cortex AI (Updated on…]]></title>
            <link>https://medium.com/@masato.takada/mastering-ai-cost-control-in-snowflake-a-deep-dive-into-resource-budgets-for-cortex-agents-9a377a694ef9?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/9a377a694ef9</guid>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Wed, 18 Mar 2026 01:58:12 GMT</pubDate>
            <atom:updated>2026-08-07T03:43:13.112Z</atom:updated>
            <content:encoded><![CDATA[<h3>Mastering AI Cost Control in Snowflake: A Deep Dive into Resource Budgets for Cortex AI (Updated on 8/7/2026)</h3><p><em>Disclaimer: The author is employed by Snowflake, but the views expressed in this article are personal and do not represent the official position of the organization.</em></p><blockquote><strong><em>GA Release (April 10, 2026):</em></strong><em> </em><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-04-10-budgets-ai-features-ga"><em>Budgets for AI features</em></a><em> is now generally available. You can track and control credit consumption for AI Functions, CoCo, Cortex Agents, and Snowflake CoWork by tagging users and managing budgets per team or cost center.</em></blockquote><h3>1. Introduction</h3><p>On March 11, 2026, Snowflake released two new features to enhance AI cost management: <strong>Resource Budgets for Cortex Agents</strong> and <strong>Resource Budgets for CoWork (formerly Snowflake Intelligence)</strong>. This article provides a hands-on verification of these features and explains how to control monthly credit consumption for AI services.</p><h3>Why Resource Budgets Matter</h3><p>While Cortex Agents and CoWork (formerly Snowflake Intelligence) are powerful features, they come with challenges:</p><ul><li><strong>Unpredictable costs</strong>: LLM invocation counts and token consumption are difficult to forecast</li><li><strong>Rapid cost increases</strong>: Costs can spike unexpectedly as usage grows</li><li><strong>Difficulty in departmental management</strong>: Hard to track which team consumes how much</li></ul><p>Resource Budgets solve these challenges through a <strong>tag-based cost attribution model</strong>.</p><h3>2. Feature Overview</h3><h3>Supported Services</h3><ul><li><strong>Cortex Agents</strong> — AI agents powered by LLMs</li><li><strong>CoWork</strong> (formerly Snowflake Intelligence) — Natural language data analysis service</li></ul><h3>Key Features</h3><ul><li><strong>Cost Attribution</strong> — Group resources using tags</li><li><strong>Actions</strong> — Automatically execute stored procedures when thresholds are reached</li><li><strong>Threshold Types</strong> — Two types: <strong>ACTUAL</strong> (actual consumption) and <strong>PROJECTED</strong> (forecasted consumption)</li><li><strong>Data Refresh</strong> — Standard: up to 8 hours / <strong>TIER_1H</strong>: up to 1 hour</li></ul><h3>How Custom Actions Work</h3><pre>Budget Usage → Threshold Reached → Stored Procedure Executed → Notification/Access Control</pre><h3>3. SNOWFLAKE.CORE.BUDGET Class Reference</h3><p>This section explains the methods of the SNOWFLAKE.CORE.BUDGET class, the core of Resource Budgets.</p><h3>3.1 Key Methods Overview</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/998/1*FH-2Aj-G1Eclo72l8gz4QA.png" /></figure><h3>3.2 SET_SPENDING_LIMIT — Setting Spending Limits</h3><p>Sets the monthly credit consumption limit.</p><pre>CALL &lt;budget_name&gt;!SET_SPENDING_LIMIT( &lt;spending_limit&gt; )</pre><p><strong>Parameter:</strong></p><ul><li>spending_limit (INTEGER) — Monthly credit limit. <strong>Only positive integers are allowed.</strong> Decimals like 0.5 will throw an error. Minimum value is 1.</li></ul><pre>-- Set 100 credits monthly limit<br>CALL my_budget!SET_SPENDING_LIMIT(100);<br><br>-- Check the limit<br>CALL my_budget!GET_SPENDING_LIMIT();</pre><h3>3.3 SET_RESOURCE_TAGS — Tag-Based Scope Configuration</h3><p>Configures tagged resources to be tracked by the Budget.</p><pre>CALL &lt;budget_name&gt;!SET_RESOURCE_TAGS( &lt;tag_pairs&gt;, &lt;operation_mode&gt; )</pre><p><strong>Parameters:</strong></p><ul><li>tag_pairs (ARRAY) — Array of tag reference and value pairs</li><li>operation_mode (STRING) — &#39;UNION&#39; (OR logic) or &#39;INTERSECTION&#39; (AND logic)</li></ul><p><strong>Operation Mode Difference:</strong></p><ul><li><strong>UNION</strong> — Include resources matching <em>any</em> tag (OR). Use case: Track combined usage across multiple teams</li><li><strong>INTERSECTION</strong> — Include only resources matching <em>all</em> tags (AND). Use case: Track specific team × specific environment only</li></ul><pre>-- Track resources with cortex-agent tag (UNION)<br>CALL my_budget!SET_RESOURCE_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;DB.TAGS.COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;cortex-agent&#39;]<br>  ],<br>  &#39;UNION&#39;<br>);<br><br>-- Multiple tag combination (resources with both tags only: INTERSECTION)<br>CALL my_budget!SET_RESOURCE_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;DB.TAGS.COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;production&#39;],<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;DB.TAGS.TEAM&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;data-science&#39;]<br>  ],<br>  &#39;INTERSECTION&#39;<br>);</pre><blockquote><strong><em>Required privilege</em></strong><em>: </em><em>APPLYBUDGET privilege on the tag is required.</em></blockquote><h3>3.4 SET_REFRESH_TIER — Setting Data Refresh Interval</h3><p>Sets the refresh frequency for Budget usage data.</p><pre>CALL &lt;budget_name&gt;!SET_REFRESH_TIER( &#39;&lt;refresh_interval&gt;&#39; )</pre><p><strong>Available Tiers:</strong></p><ul><li>TIER_6H — Up to 6.5 hours delay, standard cost, for normal operations (default)</li><li>TIER_1H — Up to 1 hour delay, <strong>12x cost</strong>, for when real-time monitoring is required</li></ul><blockquote><em>⚠️ </em><strong><em>Cost Warning</em></strong><em>: </em><em>TIER_1H costs </em><strong><em>12 times</em></strong><em> more than the standard tier. Carefully evaluate the necessity for production use.</em></blockquote><pre>-- Set to 1-hour interval (for testing)<br>CALL my_budget!SET_REFRESH_TIER(&#39;TIER_1H&#39;);<br><br>-- Revert to standard<br>CALL my_budget!SET_REFRESH_TIER(&#39;TIER_6H&#39;);<br><br>-- Check current setting<br>CALL my_budget!GET_REFRESH_TIER();</pre><h3>3.5 ADD_CUSTOM_ACTION — Adding Custom Actions</h3><p>Configures stored procedures to be automatically executed when thresholds are reached.</p><pre>CALL &lt;budget_name&gt;!ADD_CUSTOM_ACTION(<br>  &lt;stored_procedure_reference&gt;,<br>  &lt;array_of_arguments&gt;,<br>  &lt;trigger_type&gt;,<br>  &lt;threshold&gt;<br>)</pre><p><strong>Parameters:</strong></p><ul><li>stored_procedure_reference (REFERENCE) — Procedure reference obtained via SYSTEM$REFERENCE()</li><li>array_of_arguments (ARRAY) — Array of arguments to pass to the procedure</li><li>trigger_type (STRING) — &#39;ACTUAL&#39; (actual consumption) or &#39;PROJECTED&#39; (forecasted consumption)</li><li>threshold (INTEGER) — Threshold (0–1000, percentage)</li></ul><p><strong>Trigger Type Difference:</strong></p><ul><li><strong>ACTUAL</strong> — Based on actual consumption. Triggers when actual consumption reaches the threshold.</li><li><strong>PROJECTED</strong> — Based on forecasted consumption. Triggers when forecasted end-of-month consumption is expected to reach the threshold.</li></ul><pre>-- Alert at 80% actual consumption (ACTUAL)<br>CALL my_budget!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;DB.SCH.ALERT_PROC(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;80&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;,<br>  80<br>);<br><br>-- Early warning at 50% projected (PROJECTED)<br>CALL my_budget!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;DB.SCH.ALERT_PROC(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;50_PROJECTED&#39;, &#39;admin@example.com&#39;),<br>  &#39;PROJECTED&#39;,<br>  50<br>);</pre><blockquote>⚠️ <strong>Critical Requirements (Discovered During Testing)</strong>:</blockquote><blockquote>1.Procedures must be created with <strong>EXECUTE AS OWNER</strong></blockquote><blockquote><strong>2.</strong><strong>APPLICATION SNOWFLAKE</strong> must be granted USAGE privilege</blockquote><blockquote>Without these, you’ll get INVALID_PROCEDURE_OR_MISSING_PERMISSIONS error.</blockquote><h3>3.6 SET_CYCLE_START_ACTION — Cycle Start Action</h3><p>Sets an action to be automatically executed at the beginning of the month (Budget cycle start). Useful for automatically reinstating access after it was revoked at 100%.</p><pre>CALL &lt;budget_name&gt;!SET_CYCLE_START_ACTION(<br>  &lt;stored_procedure_reference&gt;,<br>  &lt;array_of_arguments&gt;<br>)<br><br>-- Auto-reinstate access at month start<br>CALL my_budget!SET_CYCLE_START_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;DB.SCH.REINSTATE_ACCESS(string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;USER_ROLE&#39;)<br>);<br><br>-- Check configuration<br>CALL my_budget!GET_CYCLE_START_ACTION();<br><br>-- Remove configuration<br>CALL my_budget!REMOVE_CYCLE_START_ACTION();</pre><h3>3.7 GET_SERVICE_TYPE_USAGE_V2 — Getting Usage by Service Type</h3><p>Retrieves credit usage by service type for resources in the Budget.</p><pre>CALL &lt;budget_name&gt;!GET_SERVICE_TYPE_USAGE_V2( &#39;&lt;start_month&gt;&#39;, &#39;&lt;end_month&gt;&#39; )</pre><p><strong>Return columns:</strong></p><figure><img alt="" src="https://cdn-images-1.medium.com/max/840/1*qCqf9G0JJHvyg1meOjYHzg.png" /></figure><pre>-- Get March 2026 usage<br>CALL my_budget!GET_SERVICE_TYPE_USAGE_V2(&#39;2026-03&#39;, &#39;2026-03&#39;);<br><br>-- Example result:<br>-- SERVICE_TYPE      | NAME           | CREDITS_USED<br>-- CORTEX_AGENT      | TPCH_ASSISTANT | 0.3456<br>-- AI_SERVICES       | -              | 0.1234</pre><h3>3.8 REFRESH_USAGE — Force Refresh Usage</h3><p>Forces an immediate update of Budget usage data (normally up to 6.5 hours delay with TIER_6H, up to 1 hour with TIER_1H).</p><pre>CALL &lt;budget_name&gt;!REFRESH_USAGE()</pre><blockquote><strong><em>Note</em></strong><em>: Even with force refresh, it won’t be completely real-time. Data source delays remain, so expect </em><strong><em>a few minutes to tens of minutes</em></strong><em> of delay.</em></blockquote><h3>3.9 Other Useful Methods</h3><pre>-- Get budget configuration<br>CALL my_budget!GET_CONFIG();<br><br>-- Get custom actions list<br>CALL my_budget!GET_CUSTOM_ACTIONS();<br><br>-- Check scope (tracked resources)<br>CALL my_budget!GET_BUDGET_SCOPE();<br><br>-- Get spending history<br>CALL my_budget!GET_SPENDING_HISTORY();<br><br>-- Remove custom actions<br>CALL my_budget!REMOVE_CUSTOM_ACTIONS();</pre><h3>4. Hands-On: Environment Setup</h3><h3>4.1 Create Database and Schemas</h3><pre>USE ROLE ACCOUNTADMIN;<br>CREATE DATABASE IF NOT EXISTS BUDGET_DEMO_DB;<br>CREATE SCHEMA IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS;<br>CREATE SCHEMA IF NOT EXISTS BUDGET_DEMO_DB.TAGS;<br>CREATE SCHEMA IF NOT EXISTS BUDGET_DEMO_DB.AGENTS;</pre><h3>4.2 Create Tags</h3><p>Create tags to group AI features:</p><pre>CREATE OR REPLACE TAG BUDGET_DEMO_DB.TAGS.COST_CENTER<br>  ALLOWED_VALUES &#39;cortex-agent&#39;, &#39;snowflake-intelligence&#39;<br>  COMMENT = &#39;Tag for AI feature cost management&#39;;</pre><h3>4.3 Create Log Tables</h3><p>Prepare tables to record alerts and access control history:</p><pre>CREATE TABLE IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS (<br>  ALERT_TIME TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),<br>  SERVICE_TYPE STRING,<br>  OBJECT_NAME STRING,<br>  THRESHOLD_PCT STRING,<br>  MESSAGE STRING<br>);<br><br>CREATE TABLE IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.ACCESS_REVOKE_LOG (<br>  REVOKE_TIME TIMESTAMP_NTZ DEFAULT CURRENT_TIMESTAMP(),<br>  SERVICE_TYPE STRING,<br>  OBJECT_NAME STRING,<br>  ROLE_NAME STRING,<br>  ACTION STRING<br>);</pre><h3>5. Hands-On: Cortex Agent Cost Management</h3><h3>5.1 Create Cortex Agent</h3><p>Create a Cortex Agent for testing, using TPCH SF1 data under SNOWFLAKE_SAMPLE_DATA. The important thing is to apply TAG to Cortex Agent at the last part.</p><pre>-- Prepare search data<br>CREATE OR REPLACE TABLE BUDGET_DEMO_DB.AGENTS.PRODUCT_DOCS AS<br>SELECT <br>  P_PARTKEY AS DOC_ID,<br>  P_NAME AS TITLE,<br>  P_NAME || &#39; - &#39; || P_MFGR || &#39; - &#39; || P_BRAND AS CONTENT<br>FROM SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.PART<br>LIMIT 1000;<br><br>-- Create Cortex Search Service<br>CREATE OR REPLACE CORTEX SEARCH SERVICE BUDGET_DEMO_DB.AGENTS.PRODUCT_SEARCH<br>  ON CONTENT<br>  WAREHOUSE = BUDGET_DEMO_WH<br>  TARGET_LAG = &#39;1 hour&#39;<br>  AS (SELECT DOC_ID, TITLE, CONTENT FROM BUDGET_DEMO_DB.AGENTS.PRODUCT_DOCS);<br><br>-- Create Cortex Agent<br>CREATE OR REPLACE AGENT BUDGET_DEMO_DB.AGENTS.TPCH_ASSISTANT<br>  COMMENT = &#39;TPCH product search assistant&#39;<br>  FROM SPECIFICATION<br>  $$<br>  models:<br>    orchestration: claude-4-sonnet<br><br>  instructions:<br>    system: |<br>      You are a TPCH product catalog search assistant.<br>      Search for product information to answer user questions.<br>  tools:<br>    - tool_spec:<br>        type: &quot;cortex_search&quot;<br>        name: &quot;ProductSearch&quot;<br>        description: &quot;Search TPCH product catalog&quot;<br>  tool_resources:<br>    ProductSearch:<br>      name: &quot;BUDGET_DEMO_DB.AGENTS.PRODUCT_SEARCH&quot;<br>      max_results: &quot;5&quot;<br>  $$;<br><br>-- Apply tag (Important: Required for Budget tracking)<br>ALTER AGENT BUDGET_DEMO_DB.AGENTS.TPCH_ASSISTANT<br>  SET TAG BUDGET_DEMO_DB.TAGS.COST_CENTER = &#39;cortex-agent&#39;;</pre><h3>5.2 Notification Stored Procedure</h3><blockquote><em>⚠️ </em><strong><em>Important</em></strong><em>: Procedures used for custom actions must be created with </em><em>EXECUTE AS OWNER and granted </em><em>USAGE privilege to </em><em>APPLICATION SNOWFLAKE.</em></blockquote><pre>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_ALERT_AGENT_BUDGET(<br>  AGENT_NAME STRING, <br>  THRESHOLD_PCT STRING,<br>  ADMIN_EMAIL STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER  -- Important: EXECUTE AS OWNER is required<br>AS<br>&#39;<br>var insert_sql = `INSERT INTO BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS <br>  (ALERT_TIME, SERVICE_TYPE, OBJECT_NAME, THRESHOLD_PCT, MESSAGE)<br>VALUES (<br>  CURRENT_TIMESTAMP(), <br>  &#39;&#39;CORTEX_AGENT&#39;&#39;, <br>  &#39;&#39;` + AGENT_NAME + `&#39;&#39;, <br>  &#39;&#39;` + THRESHOLD_PCT + `&#39;&#39;,<br>  &#39;&#39;Budget threshold ` + THRESHOLD_PCT + `% reached for agent: ` + AGENT_NAME + `&#39;&#39;<br>)`;<br>snowflake.execute({sqlText: insert_sql});<br>return &quot;Alert logged for &quot; + AGENT_NAME + &quot; at &quot; + THRESHOLD_PCT + &quot;%&quot;;<br>&#39;;<br><br>-- Grant privilege to APPLICATION SNOWFLAKE (Important)<br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_ALERT_AGENT_BUDGET(STRING, STRING, STRING) <br>  TO APPLICATION SNOWFLAKE;</pre><h3>5.3 Access Revocation Stored Procedure</h3><pre>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_REVOKE_AGENT_ACCESS(<br>  AGENT_NAME STRING, <br>  ROLE_NAME STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>&#39;<br>var revoke_sql = &quot;REVOKE USAGE ON AGENT BUDGET_DEMO_DB.AGENTS.&quot; + AGENT_NAME + &quot; FROM ROLE &quot; + ROLE_NAME;<br>try {<br>  snowflake.execute({sqlText: revoke_sql});<br>} catch(e) {}<br><br>var insert_sql = `INSERT INTO BUDGET_DEMO_DB.BUDGETS.ACCESS_REVOKE_LOG <br>  (REVOKE_TIME, SERVICE_TYPE, OBJECT_NAME, ROLE_NAME, ACTION)<br>VALUES (<br>  CURRENT_TIMESTAMP(), <br>  &#39;&#39;CORTEX_AGENT&#39;&#39;, <br>  &#39;&#39;` + AGENT_NAME + `&#39;&#39;, <br>  &#39;&#39;` + ROLE_NAME + `&#39;&#39;,<br>  &#39;&#39;REVOKED&#39;&#39;<br>)`;<br>snowflake.execute({sqlText: insert_sql});<br>return &quot;Access revoked for &quot; + AGENT_NAME + &quot; from role &quot; + ROLE_NAME;<br>&#39;;<br><br>-- Grant privilege to APPLICATION SNOWFLAKE (Important)<br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_REVOKE_AGENT_ACCESS(STRING, STRING) <br>  TO APPLICATION SNOWFLAKE;</pre><h3>5.4 Budget Creation and Configuration</h3><pre>-- Grant base privileges to SNOWFLAKE application<br>GRANT USAGE ON DATABASE BUDGET_DEMO_DB TO APPLICATION SNOWFLAKE;<br>GRANT USAGE ON SCHEMA BUDGET_DEMO_DB.BUDGETS TO APPLICATION SNOWFLAKE;<br>GRANT SELECT, INSERT ON TABLE BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS TO APPLICATION SNOWFLAKE;<br>GRANT SELECT, INSERT ON TABLE BUDGET_DEMO_DB.BUDGETS.ACCESS_REVOKE_LOG TO APPLICATION SNOWFLAKE;<br><br>-- Create Budget<br>CREATE SNOWFLAKE.CORE.BUDGET IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET()<br>  WITH COMMENT = &#39;Budget for Cortex Agents&#39;;<br><br>-- Set monthly limit (positive integers only)<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!SET_SPENDING_LIMIT(100);<br><br>-- Configure tag-based scope<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!SET_RESOURCE_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;BUDGET_DEMO_DB.TAGS.COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;cortex-agent&#39;]<br>  ],<br>  &#39;UNION&#39;);<br><br>-- Enable low latency option (1-hour refresh interval)<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!SET_REFRESH_TIER(&#39;TIER_1H&#39;);</pre><h3>5.5 Configure Custom Actions</h3><pre>-- Alert notification at 80%<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_ALERT_AGENT_BUDGET(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;80&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;,<br>  80<br>);<br><br>-- Revoke access at 100%<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_REVOKE_AGENT_ACCESS(string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;CORTEX_AGENT_USER_ROLE&#39;),<br>  &#39;ACTUAL&#39;,<br>  100<br>);</pre><h3>6. Advanced Configuration</h3><h3>6.1 200% Threshold (Emergency Shutdown)</h3><p>Even after revoking access at 100%, administrators may manually reinstate it. Setting a 200% threshold provides an emergency hard stop:</p><pre>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_EMERGENCY_AGENT_SHUTDOWN(<br>  AGENT_NAME STRING, <br>  THRESHOLD_PCT STRING,<br>  ADMIN_EMAIL STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>&#39;<br>var insert_sql = `INSERT INTO BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS <br>  (ALERT_TIME, SERVICE_TYPE, OBJECT_NAME, THRESHOLD_PCT, MESSAGE)<br>VALUES (<br>  CURRENT_TIMESTAMP(), <br>  &#39;&#39;CORTEX_AGENT&#39;&#39;, <br>  &#39;&#39;` + AGENT_NAME + `&#39;&#39;, <br>  &#39;&#39;` + THRESHOLD_PCT + `&#39;&#39;,<br>  &#39;&#39;[EMERGENCY] Budget exceeded 200%! Immediate shutdown required for agent: ` + AGENT_NAME + `&#39;&#39;<br>)`;<br>snowflake.execute({sqlText: insert_sql});<br><br>// Revoke access from all roles<br>var revoke_sql = `REVOKE USAGE ON CORTEX AGENT BUDGET_DEMO_DB.AGENTS.` + AGENT_NAME + ` FROM ROLE PUBLIC`;<br>try {<br>  snowflake.execute({sqlText: revoke_sql});<br>} catch (e) {}<br>return &quot;[EMERGENCY] 200% threshold exceeded - agent &quot; + AGENT_NAME + &quot; access revoked&quot;;<br>&#39;;<br><br>-- Grant privilege to APPLICATION SNOWFLAKE (Important)<br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_EMERGENCY_AGENT_SHUTDOWN(VARCHAR, VARCHAR, VARCHAR) <br>  TO APPLICATION SNOWFLAKE;<br><br>-- Add custom action at 200% threshold<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_EMERGENCY_AGENT_SHUTDOWN(VARCHAR, VARCHAR, VARCHAR)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;200&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;,<br>  200<br>);</pre><h3>6.2 Projection-Based Alerts (PROJECTED)</h3><p>Using the <strong>PROJECTED</strong> threshold calculates forecasted end-of-month consumption based on current spending pace, allowing early warnings:</p><pre>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_PROJECTED_ALERT_AGENT(<br>  AGENT_NAME STRING, <br>  THRESHOLD_PCT STRING,<br>  ADMIN_EMAIL STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>&#39;<br>var insert_sql = `INSERT INTO BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS <br>  (ALERT_TIME, SERVICE_TYPE, OBJECT_NAME, THRESHOLD_PCT, MESSAGE)<br>VALUES (<br>  CURRENT_TIMESTAMP(), <br>  &#39;&#39;CORTEX_AGENT&#39;&#39;, <br>  &#39;&#39;` + AGENT_NAME + `&#39;&#39;, <br>  &#39;&#39;PROJECTED_` + THRESHOLD_PCT + `&#39;&#39;,<br>  &#39;&#39;[PROJECTED] Budget is projected to reach ` + THRESHOLD_PCT + `% by end of cycle for agent: ` + AGENT_NAME + `&#39;&#39;<br>)`;<br>snowflake.execute({sqlText: insert_sql});<br>return &quot;[PROJECTED] Alert logged - budget projected to reach &quot; + THRESHOLD_PCT + &quot;% for &quot; + AGENT_NAME;<br>&#39;;<br><br>-- Grant privilege to APPLICATION SNOWFLAKE (Important)<br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_PROJECTED_ALERT_AGENT(VARCHAR, VARCHAR, VARCHAR) <br>  TO APPLICATION SNOWFLAKE;<br><br>-- Early warning at 50% projected<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_PROJECTED_ALERT_AGENT(VARCHAR, VARCHAR, VARCHAR)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;50&#39;, &#39;admin@example.com&#39;),<br>  &#39;PROJECTED&#39;,<br>  50<br>);<br><br>-- Warning at 100% projected<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_PROJECTED_ALERT_AGENT(VARCHAR, VARCHAR, VARCHAR)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;100&#39;, &#39;admin@example.com&#39;),<br>  &#39;PROJECTED&#39;,<br>  100<br>);</pre><h3>6.3 Automatic Recovery at Cycle Start</h3><p>Automatically reinstating access at month start reduces operational burden:</p><pre>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_REINSTATE_AGENT_ACCESS(<br>  AGENT_NAME STRING, <br>  ROLE_NAME STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>&#39;<br>var grant_sql = &quot;GRANT USAGE ON AGENT BUDGET_DEMO_DB.AGENTS.&quot; + AGENT_NAME + &quot; TO ROLE &quot; + ROLE_NAME;<br>try {<br>  snowflake.execute({sqlText: grant_sql});<br>} catch(e) {}<br>return &quot;Access reinstated for &quot; + AGENT_NAME + &quot; to role &quot; + ROLE_NAME;<br>&#39;;<br><br>-- Grant privilege to APPLICATION SNOWFLAKE (Important)<br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_REINSTATE_AGENT_ACCESS(STRING, STRING) <br>  TO APPLICATION SNOWFLAKE;<br><br>-- Set cycle start auto-recovery<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!SET_CYCLE_START_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_REINSTATE_AGENT_ACCESS(string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;TPCH_ASSISTANT&#39;, &#39;CORTEX_AGENT_USER_ROLE&#39;)<br>);</pre><h3>7. Load Testing and Monitoring</h3><h3>7.1 Agent Invocation via DATA_AGENT_RUN</h3><p>Calling DATA_AGENT_RUN with SQL to execute Cortex Agents</p><pre>-- Query Cortex Agent<br>SELECT<br>  TRY_PARSE_JSON(<br>    SNOWFLAKE.CORTEX.DATA_AGENT_RUN(<br>      &#39;BUDGET_DEMO_DB.AGENTS.TPCH_ASSISTANT&#39;,<br>      $${ <br>        &quot;messages&quot;: [<br>          {<br>            &quot;role&quot;: &quot;user&quot;,<br>            &quot;content&quot;: [<br>              { &quot;type&quot;: &quot;text&quot;, &quot;text&quot;: &quot;Tell me 3 products from Manufacturer#1&quot; }<br>            ]<br>          }<br>        ]<br>      }$$<br>    )<br>  ) AS response;</pre><h3>7.2 Usage Monitoring</h3><pre>-- Check Budget usage<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_SERVICE_TYPE_USAGE_V2(<br>  &#39;2026-03&#39;,<br>  &#39;2026-03&#39;<br>);<br><br>-- Force refresh (immediate usage update)<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!REFRESH_USAGE();<br><br>-- Check custom action configuration<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_CUSTOM_ACTIONS();<br><br>-- Check alert log<br>SELECT * FROM BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS ORDER BY ALERT_TIME DESC;</pre><h3>8. Verification Results</h3><p>Actual testing confirmed that the following custom actions work correctly:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/484/1*f534eEdl6EEp8Zz9rDHMTg.png" /></figure><h3>8.1 Budget Configuration Check (GET_CONFIG)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_CONFIG();</pre><p><strong>Result:</strong></p><ul><li>NOTIFICATION_EMAIL: (empty)</li><li>LAST_NOTIFICATION_TIME: -1</li><li>SPEND_LIMIT: <strong>1</strong> (set to 1 credit for testing to accelerate threshold triggering)</li><li>NOTIFICATION_MUTE_FLAG: false</li><li>BUDGET_TYPE: USER_BUDGET</li></ul><h3>8.2 Custom Actions Configuration Check (GET_CUSTOM_ACTIONS)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_CUSTOM_ACTIONS();</pre><figure><img alt="" src="https://cdn-images-1.medium.com/max/936/1*lD92pcIzDLPPoStIIlXvwA.png" /></figure><p>The LAST_TRIGGER_ATTEMPT_TIME column confirms that <strong>PROJECTED</strong> actions (50%, 100%) were actually triggered.</p><h3>8.3 Alert Log Check (BUDGET_ALERTS Table)</h3><pre>SELECT * FROM BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS ORDER BY ALERT_TIME DESC;</pre><p><strong>Results:</strong></p><ul><li>2026/03/14 06:03:23 | CORTEX_AGENT | TPCH_ASSISTANT | PROJECTED_100 | [PROJECTED] Budget is projected to reach 100% by end of cycle</li><li>2026/03/14 05:33:23 | CORTEX_AGENT | TPCH_ASSISTANT | PROJECTED_50 | [PROJECTED] Budget is projected to reach 50% by end of cycle</li><li>2026/03/14 05:29:45 | CORTEX_AGENT | TPCH_ASSISTANT | 200 | [EMERGENCY] Budget exceeded 200%! (Manual test)</li></ul><p>Projection alerts (PROJECTED 50%, 100%) were automatically triggered and logged.</p><h3>8.4 Service Type Usage Check (GET_SERVICE_TYPE_USAGE_V2)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_SERVICE_TYPE_USAGE_V2(&#39;2026-03&#39;, &#39;2026-03&#39;);</pre><p><strong>Result:</strong></p><ul><li>SERVICE_TYPE: AI_SERVICES</li><li>ENTITY_TYPE: CORTEX AGENT</li><li>NAME: TPCH_ASSISTANT</li><li>CREDITS_USED: <strong>0.4522</strong></li><li>CREDITS_COMPUTE: 0.4522</li><li>CREDITS_CLOUD: 0</li></ul><p>With a 1 credit Budget limit, approximately 0.45 credits (<strong>45%</strong>) have been consumed.</p><h3>8.5 Spending History Check (GET_SPENDING_HISTORY)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_SPENDING_HISTORY();</pre><p><strong>Daily credit consumption:</strong></p><ul><li>2026–03–13 | AI_SERVICES | 0.3399 credits</li><li>2026–03–14 | AI_SERVICES | 0.1123 credits</li></ul><h3>8.6 Cycle Start Action Check (GET_CYCLE_START_ACTION)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_CYCLE_START_ACTION();</pre><p><strong>Result:</strong></p><ul><li>PROCEDURE_FQN: SP_REINSTATE_AGENT_ACCESS</li><li>PROCEDURE_ARGS: TPCH_ASSISTANT,CORTEX_AGENT_USER_ROLE</li><li>LAST_TRIGGER_ATTEMPT_TIME: (Scheduled for month start)</li></ul><p>Auto-recovery is configured to execute automatically at month start.</p><h3>8.7 Refresh Tier Check (GET_REFRESH_TIER)</h3><pre>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_REFRESH_TIER();<br>-- Result: TIER_1H</pre><p>The 1-hour low latency option is enabled.</p><h3>9. Shared Resource Budgets (User-Tag-Based Budget Management)</h3><blockquote><strong><em>GA Release (April 10, 2026):</em></strong><em> </em><a href="https://docs.snowflake.com/en/release-notes/2026/other/2026-04-10-budgets-ai-features-ga"><em>Budgets for AI features</em></a><em> is now generally available. You can track and control credit consumption for AI Functions, CoCo, Cortex Agents, and Snowflake CoWork by tagging users and managing budgets per team or cost center.</em></blockquote><h3>9.1 How It Differs from Resource Budgets</h3><p>The Resource Budgets covered in previous sections apply <strong>tags to AI objects</strong> for cost tracking. Shared Resource Budgets take a different approach — <strong>tags are applied to users</strong>, enabling multiple teams to share the same AI features while managing budgets independently per team.</p><p><strong>Resource Budget:</strong></p><ul><li>Tags applied to: AI objects (e.g., ALTER AGENT ... SET TAG)</li><li>Configuration: SET_RESOURCE_TAGS</li><li>Use case: Per-object budget management</li><li>Multi-team: Not supported</li><li>Domains: Cortex Agent, Snowflake CoWork</li></ul><p><strong>Shared Resource Budget:</strong></p><ul><li>Tags applied to: <strong>Users</strong> (e.g., ALTER USER ... SET TAG)</li><li>Configuration: SET_USER_TAGS + ADD_SHARED_RESOURCE</li><li>Use case: <strong>Per-team/department budget management</strong></li><li>Multi-team: <strong>Supported</strong> (same resource tracked across multiple budgets)</li><li>Domains: Cortex Agent, SI, <strong>AI Function, CoCo</strong></li></ul><h3>9.2 How It Works</h3><pre>1. Apply tags to users (ALTER USER ... SET TAG)<br>2. Associate user tags with the Budget (SET_USER_TAGS)<br>3. Add AI features as shared resources (ADD_SHARED_RESOURCE)<br>4. AI usage by tagged users is tracked independently<br>5. Custom actions fire when thresholds are reached</pre><h3>9.3 Setup</h3><h4>Create User Tags and Apply to Users</h4><pre>-- Create user cost center tag<br>CREATE OR REPLACE TAG BUDGET_DEMO_DB.TAGS.USER_COST_CENTER<br>  ALLOWED_VALUES &#39;finance_dept&#39;, &#39;marketing_dept&#39;, &#39;engineering_dept&#39;<br>  COMMENT = &#39;User-based cost management tag for Shared Resource Budgets&#39;;<br><br>-- Apply tag to user<br>ALTER USER ADMIN SET TAG BUDGET_DEMO_DB.TAGS.USER_COST_CENTER = &#39;finance_dept&#39;;<br><br>-- Verify tag assignment<br>SELECT SYSTEM$GET_TAG(&#39;BUDGET_DEMO_DB.TAGS.USER_COST_CENTER&#39;, &#39;ADMIN&#39;, &#39;USER&#39;);<br>-- → finance_dept</pre><blockquote><strong><em>Key difference</em></strong><em>: Resource Budgets tag objects with </em><em>ALTER AGENT ... SET TAG, while Shared Resource Budgets tag users with </em><em>ALTER USER ... SET TAG.</em></blockquote><h4>Create Budget and SET_USER_TAGS</h4><pre>-- Create Shared Resource Budget<br>CREATE SNOWFLAKE.CORE.BUDGET IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET()<br>  WITH COMMENT = &#39;Shared Resource Budget for finance_dept&#39;;<br><br>-- Set monthly limit<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!SET_SPENDING_LIMIT(50)<br><br>-- Associate user tags with the Budget<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!SET_USER_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;BUDGET_DEMO_DB.TAGS.USER_COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)),<br>    &#39;finance_dept&#39;]<br>  ],<br>  &#39;UNION&#39;);<br>-- → Successfully removed 0 and set 1 user tag(s) for budget</pre><h4>Add Shared Resources (ADD_SHARED_RESOURCE)</h4><p>Four AI feature domains can be added as shared resources:</p><ul><li>CORTEX AGENT — Cortex Agent</li><li>SNOWFLAKE INTELLIGENCE — Snowflake Cowork</li><li>AI FUNCTION — AI_CLASSIFY, AI_COMPLETE, etc.</li><li>CORTEX CODE — CoCo (CLI, Snowsight)</li></ul><pre>-- Add specific Cortex Agent as shared resource<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!ADD_SHARED_RESOURCE(<br>  &#39;CORTEX AGENT&#39;,<br>  (SELECT SYSTEM$REFERENCE(&#39;CORTEX AGENT&#39;, &#39;BUDGET_DEMO_DB.AGENTS.TPCH_ASSISTANT&#39;))<br>);<br><br>-- Add all Snowflake Intelligence<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!ADD_SHARED_RESOURCE(<br>  &#39;SNOWFLAKE INTELLIGENCE&#39;<br>);<br><br>-- Add all AI Functions<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!ADD_SHARED_RESOURCE(<br>  &#39;AI FUNCTION&#39;<br>);<br><br>-- Add Cortex Code<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!ADD_SHARED_RESOURCE(<br>  &#39;CORTEX CODE&#39;<br>);</pre><blockquote><em>You can use </em><em>SYSTEM$SHOW_BUDGET_SHARED_RESOURCE_CANDIDATES(&#39;AI_FUNCTION&#39;) to list available AI functions (returns ~15 functions including AI_COMPLETE, AI_CLASSIFY, AI_EXTRACT, etc.).</em></blockquote><h4>Verify Configuration</h4><pre>-- Check added shared resources<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!GET_SHARED_RESOURCES();<br>-- Returns: AI_FUNCTION (all), CORTEX_AGENT (TPCH_ASSISTANT),<br>--          SNOWFLAKE_INTELLIGENCE (all), CORTEX_CODE (all)<br><br>-- Check Budget config<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!GET_CONFIG();<br>-- → SPEND_LIMIT: 50, BUDGET_TYPE: USER_BUDGET</pre><h3>9.4 Custom Actions</h3><p>Custom actions work the same way as Resource Budgets:</p><pre>-- Create notification procedure (EXECUTE AS OWNER required)<br>CREATE OR REPLACE PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_ALERT_SHARED_BUDGET(<br>  DEPT_NAME STRING, THRESHOLD_PCT STRING, ADMIN_EMAIL STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>&#39;<br>var insert_sql = &quot;INSERT INTO BUDGET_DEMO_DB.BUDGETS.BUDGET_ALERTS &quot;<br>  + &quot;(ALERT_TIME, SERVICE_TYPE, OBJECT_NAME, THRESHOLD_PCT, MESSAGE) &quot;<br>  + &quot;VALUES (CURRENT_TIMESTAMP(), &#39;&#39;SHARED_RESOURCE&#39;&#39;, &#39;&#39;&quot; + DEPT_NAME<br>  + &quot;&#39;&#39;, &#39;&#39;&quot; + THRESHOLD_PCT + &quot;&#39;&#39;, &#39;&#39;[SHARED] Budget threshold &quot;<br>  + THRESHOLD_PCT + &quot;% reached for dept: &quot; + DEPT_NAME + &quot;&#39;&#39;)&quot;;<br>snowflake.execute({sqlText: insert_sql});<br>return &quot;Shared budget alert logged for &quot; + DEPT_NAME + &quot; at &quot; + THRESHOLD_PCT + &quot;%&quot;;<br>&#39;;<br><br>GRANT USAGE ON PROCEDURE BUDGET_DEMO_DB.BUDGETS.SP_ALERT_SHARED_BUDGET(STRING, STRING, STRING)<br>  TO APPLICATION SNOWFLAKE;<br><br>-- Alert at 80%<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;BUDGET_DEMO_DB.BUDGETS.SP_ALERT_SHARED_BUDGET(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;finance_dept&#39;, &#39;80&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;,<br>  80<br>);</pre><h3>9.5 Multi-Team Setup</h3><p>The key advantage of Shared Resource Budgets is <strong>independent budget management for multiple teams sharing the same AI features</strong>:</p><pre>-- Create marketing_dept budget<br>CREATE SNOWFLAKE.CORE.BUDGET IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.MARKETING_SHARED_BUDGET()<br>  WITH COMMENT = &#39;Shared Resource Budget for marketing_dept&#39;;<br><br>CALL BUDGET_DEMO_DB.BUDGETS.MARKETING_SHARED_BUDGET!SET_SPENDING_LIMIT(30);<br><br>CALL BUDGET_DEMO_DB.BUDGETS.MARKETING_SHARED_BUDGET!SET_USER_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;BUDGET_DEMO_DB.TAGS.USER_COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)),<br>    &#39;marketing_dept&#39;]<br>  ],<br>  &#39;UNION&#39;);<br><br>-- Add the same shared resources<br>CALL BUDGET_DEMO_DB.BUDGETS.MARKETING_SHARED_BUDGET!ADD_SHARED_RESOURCE(<br>  &#39;CORTEX AGENT&#39;,<br>  (SELECT SYSTEM$REFERENCE(&#39;CORTEX AGENT&#39;, &#39;BUDGET_DEMO_DB.AGENTS.TPCH_ASSISTANT&#39;))<br>);<br><br>CALL BUDGET_DEMO_DB.BUDGETS.MARKETING_SHARED_BUDGET!ADD_SHARED_RESOURCE(&#39;AI FUNCTION&#39;);</pre><p>This creates the following structure:</p><ul><li><strong>FINANCE_SHARED_BUDGET</strong> — finance_dept, 50 credits, Agent + AI Function + SI + CoCo</li><li><strong>MARKETING_SHARED_BUDGET</strong> — marketing_dept, 30 credits, Agent + AI Function</li></ul><p>Each budget is <strong>evaluated independently</strong> — finance_dept consumption never affects marketing_dept’s budget.</p><h3>9.6 INTERSECTION Mode (Multiple Tags with AND Logic)</h3><p>When &#39;INTERSECTION&#39; is specified as the operation_mode in SET_USER_TAGS, <strong>only users with ALL specified tags</strong> are tracked by the budget:</p><pre>-- Create project tag<br>CREATE OR REPLACE TAG BUDGET_DEMO_DB.TAGS.PROJECT<br>  ALLOWED_VALUES &#39;project_alpha&#39;, &#39;project_beta&#39;;<br><br>-- Assign both tags to user<br>ALTER USER ADMIN SET TAG BUDGET_DEMO_DB.TAGS.PROJECT = &#39;project_alpha&#39;;<br><br>-- Create INTERSECTION budget<br>CREATE SNOWFLAKE.CORE.BUDGET IF NOT EXISTS BUDGET_DEMO_DB.BUDGETS.INTERSECTION_BUDGET()<br>  WITH COMMENT = &#39;INTERSECTION mode - finance_dept AND project_alpha&#39;;<br><br>CALL BUDGET_DEMO_DB.BUDGETS.INTERSECTION_BUDGET!SET_SPENDING_LIMIT(20);<br><br>-- INTERSECTION: only users with BOTH tags are tracked<br>CALL BUDGET_DEMO_DB.BUDGETS.INTERSECTION_BUDGET!SET_USER_TAGS(<br>  [<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;BUDGET_DEMO_DB.TAGS.USER_COST_CENTER&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;finance_dept&#39;],<br>    [(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;BUDGET_DEMO_DB.TAGS.PROJECT&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;project_alpha&#39;]<br>  ],<br>  &#39;INTERSECTION&#39;);<br><br>CALL BUDGET_DEMO_DB.BUDGETS.INTERSECTION_BUDGET!ADD_SHARED_RESOURCE(&#39;AI FUNCTION&#39;);</pre><p><strong>UNION vs INTERSECTION:</strong></p><ul><li><strong>UNION</strong> — Track users matching <em>any</em> tag (OR logic). Use case: Department-level management.</li><li><strong>INTERSECTION</strong> — Track only users matching <em>all</em> tags (AND logic). Use case: Cross-cutting management such as department × project.</li></ul><h3>9.7 Budget Precedence</h3><p>When a user is covered by multiple budgets (both Resource Budget and Shared Resource Budget), <strong>each budget evaluates independently</strong>, and <strong>whichever reaches its threshold first fires its actions</strong>.</p><pre>-- Check both budgets<br>CALL BUDGET_DEMO_DB.BUDGETS.FINANCE_SHARED_BUDGET!GET_CONFIG();<br>-- → SPEND_LIMIT: 50<br>CALL BUDGET_DEMO_DB.BUDGETS.CORTEX_AGENT_BUDGET!GET_CONFIG();<br>-- → SPEND_LIMIT: 1 (set low for testing)</pre><p>For example, if user ADMIN has the finance_dept tag AND the TPCH_ASSISTANT Agent has the cortex-agent tag:</p><ul><li>CORTEX_AGENT_BUDGET (1 credit) hits threshold first → its action fires</li><li>FINANCE_SHARED_BUDGET (50 credits) continues tracking independently</li></ul><h3>10. Resource Budgets for Cortex Search</h3><p>Cortex Search Services can also be managed with Resource Budgets. The tag-based cost attribution model tracks credit consumption for indexing and serving. A key differentiator is <strong>SUSPEND/RESUME</strong> — you can stop both indexing and serving costs entirely when the budget is exceeded.</p><h3>10.1 Setup</h3><pre>-- Apply tag to Cortex Search Service<br>ALTER CORTEX SEARCH SERVICE my_search_service<br>  SET TAG cost_mgmt_db.tags.cost_center = &#39;cortex-search&#39;;</pre><pre>-- Create Resource Budget<br>CREATE SNOWFLAKE.CORE.BUDGET IF NOT EXISTS budgets_db.budgets_schema.search_budget()<br>  WITH COMMENT = &#39;Resource Budget for Cortex Search&#39;;</pre><pre>CALL search_budget!SET_SPENDING_LIMIT(10);</pre><pre>CALL search_budget!SET_RESOURCE_TAGS(<br>  [[(SELECT SYSTEM$REFERENCE(&#39;TAG&#39;, &#39;cost_mgmt_db.tags.cost_center&#39;, &#39;SESSION&#39;, &#39;APPLYBUDGET&#39;)), &#39;cortex-search&#39;]],<br>  &#39;UNION&#39;);</pre><pre>CALL search_budget!SET_REFRESH_TIER(&#39;TIER_1H&#39;);</pre><h3>10.2 SUSPEND/RESUME for Cost Control</h3><p>Unlike other AI services, Cortex Search allows <strong>suspending the entire service</strong> to stop ongoing costs (both indexing and serving):</p><pre>-- Revoke access + SUSPEND procedure<br>CREATE OR REPLACE PROCEDURE sp_revoke_search_access(<br>  service_name STRING, role_name STRING<br>)<br>RETURNS STRING<br>LANGUAGE SQL<br>EXECUTE AS OWNER<br>AS<br>BEGIN<br>  EXECUTE IMMEDIATE &#39;REVOKE USAGE ON CORTEX SEARCH SERVICE &#39; || :service_name || &#39; FROM ROLE &#39; || :role_name;<br>  EXECUTE IMMEDIATE &#39;ALTER CORTEX SEARCH SERVICE &#39; || :service_name || &#39; SUSPEND&#39;;<br>  RETURN &#39;Access revoked and service suspended for &#39; || :service_name;<br>END;</pre><pre>-- Resume + reinstate procedure<br>CREATE OR REPLACE PROCEDURE sp_reinstate_search_access(<br>  service_name STRING, role_name STRING<br>)<br>RETURNS STRING<br>LANGUAGE SQL<br>EXECUTE AS OWNER<br>AS<br>BEGIN<br>  EXECUTE IMMEDIATE &#39;ALTER CORTEX SEARCH SERVICE &#39; || :service_name || &#39; RESUME&#39;;<br>  EXECUTE IMMEDIATE &#39;GRANT USAGE ON CORTEX SEARCH SERVICE &#39; || :service_name || &#39; TO ROLE &#39; || :role_name;<br>  RETURN &#39;Service resumed and access reinstated for &#39; || :service_name;<br>END;</pre><h3>10.3 Custom Actions</h3><pre>-- 80% alert<br>CALL search_budget!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;sp_alert_search(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;my_search_service&#39;, &#39;80&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;, 80<br>);</pre><pre>-- 100% revoke + suspend<br>CALL search_budget!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;sp_revoke_search_access(string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;my_search_service&#39;, &#39;PUBLIC&#39;),<br>  &#39;ACTUAL&#39;, 100<br>);</pre><pre>-- Auto-recovery at cycle start (RESUME + GRANT)<br>CALL search_budget!SET_CYCLE_START_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;sp_reinstate_search_access(string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;my_search_service&#39;, &#39;PUBLIC&#39;)<br>);</pre><h3>10.4 Exception Handling Flow</h3><p>For peak periods, you can manually reinstate access after 100% and set a 200% hard stop:</p><pre>100% → SUSPEND + REVOKE (automatic)<br>   ↓ Admin manually calls RESUME + GRANT (exception period)<br>200% → SUSPEND + REVOKE again (hard stop)</pre><h3>11. Per-User Quotas (Individual User Credit Limits)</h3><blockquote><strong><em>Preview Feature</em></strong><em>: </em><a href="https://docs.snowflake.com/en/user-guide/budgets/per-user-quotas"><em>Per-User Quotas</em></a><em> enforce spending limits at per-user granularity with </em><strong><em>built-in blocking</em></strong><em> — automatically denying AI requests when a user reaches their limit. While Shared Resource Budgets manage “team-level budgets,” Per-User Quotas provide “individual hard limits.”</em></blockquote><h3>11.1 Comparison with Budgets</h3><p><strong>Resource Budget:</strong></p><ul><li>Target: Objects</li><li>Enforcement: Threshold actions (delayed)</li><li>Granularity: Monthly only</li><li>Latency: Up to 1–8 hours</li></ul><p><strong>Shared Resource Budget:</strong></p><ul><li>Target: Teams (user tags)</li><li>Enforcement: Threshold actions (delayed)</li><li>Granularity: Monthly only</li><li>Latency: Up to 1–8 hours</li></ul><p><strong>Per-User Quotas:</strong></p><ul><li>Target: <strong>Individual users</strong></li><li>Enforcement: <strong>Blocking (immediate denial)</strong></li><li>Granularity: <strong>Monthly + Daily</strong></li><li>Latency: <strong>Within minutes</strong></li><li>Additional domains: Warehouse (tracking only)</li></ul><h3>11.2 Setup</h3><pre>-- Create Quota (SNOWFLAKE.CORE.QUOTA class)<br>CREATE SNOWFLAKE.CORE.QUOTA IF NOT EXISTS budgets_db.budgets_schema.ai_user_quota()<br>  WITH COMMENT = &#39;Per-user quota for AI feature consumption&#39;;</pre><pre>-- Add monitored domains<br>CALL ai_user_quota!ADD_SHARED_RESOURCE(&#39;AI FUNCTION&#39;);<br>CALL ai_user_quota!ADD_SHARED_RESOURCE(&#39;CORTEX AGENT&#39;);<br>CALL ai_user_quota!ADD_SHARED_RESOURCE(&#39;SNOWFLAKE INTELLIGENCE&#39;);</pre><blockquote><em>By default, a new quota monitors </em><strong><em>all users</em></strong><em> in the account. Use </em><em>SET_USER_TAGS to narrow scope to specific user groups.</em></blockquote><h3>11.3 Setting Limits</h3><pre>-- Monthly limit: 5 credits per user<br>CALL ai_user_quota!SET_PER_USER_LIMIT(5);</pre><pre>-- Daily limit: 1 credit per user<br>CALL ai_user_quota!SET_PER_USER_LIMIT(1, &#39;DAILY&#39;);</pre><pre>-- Verify<br>CALL ai_user_quota!GET_CONFIG();<br>-- → PER_USER_LIMIT: 5, PER_USER_LIMIT_DAILY: 1, BLOCK_ENFORCEMENT_ENABLED: true</pre><h3>11.4 Block Enforcement</h3><p>The key differentiator of Per-User Quotas is <strong>immediate blocking</strong> when limits are reached:</p><pre>-- Enable blocking<br>CALL ai_user_quota!SET_BLOCK_ENFORCEMENT_ENABLED(TRUE);</pre><p><strong>How enforcement works:</strong></p><ol><li>User issues AI requests → usage attributed within minutes</li><li>Usage reaches limit → block recorded</li><li>Blocked user receives notification email</li><li>Subsequent AI requests return “quota exhausted” error immediately</li><li>Block auto-releases at daily reset (UTC midnight) or monthly reset (first of month)</li></ol><pre>-- Check who is currently blocked<br>CALL ai_user_quota!GET_ACTIVE_BLOCKS();</pre><pre>-- View blocking/unblocking history<br>CALL ai_user_quota!GET_ENFORCEMENT_HISTORY(&#39;2026-08-01&#39;, &#39;2026-08-31&#39;);</pre><h3>11.5 Notifications</h3><pre>-- Notify user at 80% projected spend<br>CALL ai_user_quota!ADD_NOTIFICATION_THRESHOLD(80, &#39;PROJECTED&#39;, TRUE);</pre><pre>-- Notify user at 100% actual spend<br>CALL ai_user_quota!ADD_NOTIFICATION_THRESHOLD(100, &#39;ACTUAL&#39;, TRUE);</pre><pre>-- Admin summary emails<br>CALL ai_user_quota!SET_ADMIN_EMAILS(&#39;admin@example.com&#39;);</pre><h3>11.6 Custom Actions</h3><blockquote><strong><em>Important</em></strong><em>: Per-User Quotas automatically inject the </em><strong><em>user name as the first argument</em></strong><em> when calling custom action procedures. Your procedure must include </em><em>USER_NAME STRING as the first parameter.</em></blockquote><pre>CREATE OR REPLACE PROCEDURE sp_alert_user_quota(<br>  USER_NAME STRING,      -- ← automatically injected by the system<br>  THRESHOLD_PCT STRING,<br>  ADMIN_EMAIL STRING<br>)<br>RETURNS STRING<br>LANGUAGE JAVASCRIPT<br>EXECUTE AS OWNER<br>AS<br>$$<br>var sql = `INSERT INTO budget_alerts (ALERT_TIME, SERVICE_TYPE, OBJECT_NAME, THRESHOLD_PCT, MESSAGE)<br>VALUES (CURRENT_TIMESTAMP(), &#39;PER_USER_QUOTA&#39;, &#39;` + USER_NAME + `&#39;, &#39;` + THRESHOLD_PCT + `&#39;,<br>&#39;[QUOTA] Threshold ` + THRESHOLD_PCT + `% reached for user: ` + USER_NAME + `&#39;)`;<br>snowflake.execute({sqlText: sql});<br>return &#39;Alert logged at &#39; + THRESHOLD_PCT + &#39;% for user &#39; + USER_NAME;<br>$$;</pre><pre>-- Register custom action (ARRAY_CONSTRUCT contains explicit args only; user_name is injected)<br>CALL ai_user_quota!ADD_CUSTOM_ACTION(<br>  SYSTEM$REFERENCE(&#39;PROCEDURE&#39;, &#39;sp_alert_user_quota(string, string, string)&#39;, &#39;SESSION&#39;, &#39;USAGE&#39;),<br>  ARRAY_CONSTRUCT(&#39;80&#39;, &#39;admin@example.com&#39;),<br>  &#39;ACTUAL&#39;, 80<br>);</pre><h3>11.7 Daily vs Monthly Limit Precedence</h3><p>Daily and monthly limits are evaluated <strong>independently</strong>:</p><pre>Day 1: 1 credit consumed → Daily block (auto-releases at UTC midnight)<br>Day 2: Released → 1 credit consumed → Daily block<br>...<br>Day 5: Cumulative 5 credits → Monthly block also fires (not released until next month)</pre><h3>11.8 Unblocking Methods</h3><ul><li><strong>Daily cycle reset (UTC midnight)</strong> — Automatic</li><li><strong>Monthly cycle reset (first of month)</strong> — Automatic</li><li><strong>Raise the limit</strong> (SET_PER_USER_LIMIT) — Immediate</li><li><strong>Disable blocking</strong> (SET_BLOCK_ENFORCEMENT_ENABLED(FALSE)) — Within ~15 minutes</li><li><strong>Drop the quota</strong> — Immediate</li></ul><h3>11.9 Key Considerations</h3><ul><li><strong>REFRESH_TIER is deprecated</strong> for Quotas — evaluation interval is short by default at no extra cost</li><li><strong>LANGUAGE SQL procedures not supported</strong> — Use LANGUAGE JAVASCRIPT for custom actions</li><li><strong>User name auto-injection</strong> — Custom action procedures receive USER_NAME as first argument automatically</li><li><strong>Tag-based exclusion</strong> — Use EXCLUDE_USERS(&#39;TAG&#39;, [...]) to exclude specific tagged users from the quota</li></ul><h3>12. Limitations and Considerations</h3><h3>10.1 Shared Resource Budget Limitations</h3><ul><li><strong>Individual user tagging</strong> — No bulk tagging. Each user must be tagged individually via ALTER USER.</li><li><strong>Tag propagation delay</strong> — Changes to user tags may take up to 8 hours to reflect in the budget.</li><li><strong>Fixed monthly cycle</strong> — Custom budget periods are not supported.</li><li><strong>Role-based revocation only</strong> — Direct blocking of individual users is not supported; dedicated roles are required.</li></ul><blockquote><strong><em>SCIM Integration</em></strong><em>: If you use a SCIM identity provider, you can automatically apply tags using the </em><em>snowflakeTags attribute when users are created or updated. Microsoft Entra ID and Okta are supported.</em></blockquote><h3>10.2 Data Refresh Delay</h3><ul><li><strong>Standard (TIER_6H)</strong> — Up to 8 hours delay, suitable for normal operations</li><li><strong>TIER_1H</strong> — Up to 1 hour delay, for when real-time monitoring is needed</li></ul><blockquote><em>Even with TIER_1H enabled, it’s not truly real-time. In testing, usage was reflected within approximately 30 minutes to 1 hour.</em></blockquote><h3>10.3 Custom Action Procedure Requirements</h3><p>Stored procedures used for custom actions have the following requirements:</p><ol><li>Must be created with <strong>EXECUTE AS OWNER</strong></li><li>Must grant USAGE privilege to <strong>APPLICATION SNOWFLAKE</strong></li></ol><pre>-- Correct example<br>CREATE PROCEDURE my_proc(...) ... EXECUTE AS OWNER ...;<br>GRANT USAGE ON PROCEDURE my_proc(...) TO APPLICATION SNOWFLAKE;</pre><pre>-- Incorrect example (won&#39;t work)<br>CREATE PROCEDURE my_proc(...) ... EXECUTE AS CALLER ...;  -- NG</pre><h3>10.4 SET_SPENDING_LIMIT Constraints</h3><p>Only positive integers are valid:</p><ul><li>CALL budget!SET_SPENDING_LIMIT(100); — ✅ OK</li><li>CALL budget!SET_SPENDING_LIMIT(0.5); — ❌ Error</li><li>CALL budget!SET_SPENDING_LIMIT(0); — ❌ Error</li></ul><h3>12.5 Cost Attribution When Agents Are Called via CoWork</h3><p>When CoWork (formerly Snowflake Intelligence) internally calls a Cortex Agent, costs are attributed to <strong>CoWork</strong>.</p><h3>13. Best Practices</h3><h3>13.1 Choosing the Right Cost Control Mechanism</h3><ul><li><strong>Single team using dedicated AI features</strong> → Resource Budget (simpler)</li><li><strong>Cortex Search cost management</strong> → Resource Budget + SUSPEND/RESUME</li><li><strong>Multiple teams sharing the same AI features</strong> → Shared Resource Budget (per-team management)</li><li><strong>Department × project cross-cutting management</strong> → Shared Resource Budget with INTERSECTION mode</li><li><strong>Preventing individual user overspend</strong> → Per-User Quotas (blocking)</li><li><strong>Daily granularity control</strong> → Per-User Quotas (daily + monthly limits)</li></ul><h3>13.2 Multi-Layer Defense Threshold Configuration</h3><pre>50% PROJECTED  → Early warning (consider plan revision)<br>80% ACTUAL     → Warning (check usage status)<br>100% ACTUAL    → Revoke general user access<br>100% PROJECTED → Projection warning<br>200% ACTUAL    → Emergency shutdown (all users)</pre><h3>13.3 Leverage Automatic Recovery</h3><p>Setting up auto-recovery with SET_CYCLE_START_ACTION at month start:</p><ul><li>Reduces operational burden</li><li>Improves user experience (available from month start)</li></ul><h3>13.4 Utilize Alert Logs</h3><p>Integrating the BUDGET_ALERTS table with monitoring dashboards enables:</p><ul><li>Slack/Teams notifications</li><li>Email alerts</li><li>Dashboard visualization</li></ul><h3>14. Summary</h3><p>Resource Budgets for Cortex Agents, CoWork, and Cortex Search, combined with Shared Resource Budgets and Per-User Quotas, provide a comprehensive AI cost management toolkit.</p><p><strong>Key Benefits:</strong></p><ul><li><strong>Flexible tag-based scope configuration</strong> — Department and project-level management</li><li><strong>Multi-tier threshold settings</strong> — Multi-layer defense combining ACTUAL and PROJECTED</li><li><strong>Automated access control</strong> — Automatic response when thresholds are reached</li><li><strong>Cycle-based management</strong> — Automatic reset/recovery at month start</li><li><strong>Shared Resource Budgets</strong> — User-tag-based independent management for teams sharing AI features</li><li><strong>Cortex Search Budgets</strong> — SUSPEND/RESUME for service-level cost control</li><li><strong>Per-User Quotas</strong> — Individual blocking with daily + monthly granularity (within minutes)</li><li><strong>Broad AI domain coverage</strong> — Cortex Agent, CoWork, AI Function, CoCo, Cortex Search, Warehouse</li></ul><p>For confident AI feature deployment in production environments, we strongly recommend utilizing Resource Budgets.</p><h3>References</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-agents-resource-budgets">Resource budgets for Cortex Agents</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-intelligence/si-resource-budgets">Resource budgets for CoWork</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/cortex-search/cortex-search-resource-budgets">Resource budgets for Cortex Search</a></li><li><a href="https://docs.snowflake.com/en/user-guide/budgets/per-user-quotas">Per-user quotas</a></li><li><a href="https://docs.snowflake.com/en/user-guide/budgets/custom-actions">Custom actions for budgets</a></li><li><a href="https://docs.snowflake.com/user-guide/budgets">Monitor credit usage with budgets</a></li><li><a href="https://docs.snowflake.com/en/user-guide/budgets/budget-shared-resources">Using budgets for AI features (shared resources)</a></li><li><a href="https://docs.snowflake.com/en/user-guide/snowflake-cortex/snowflake-intelligence/si-shared-budgets">CoWork shared resource budgets</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/classes/budget/methods/set_user_tags">SET_USER_TAGS</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/classes/budget/methods/add_shared_resource">ADD_SHARED_RESOURCE</a></li></ul><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=9a377a694ef9" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Comprehensive Testing of Snowflake’s New SQL Syntax for Semantic Views]]></title>
            <link>https://medium.com/@masato.takada/comprehensive-testing-of-snowflakes-new-sql-syntax-for-semantic-views-db4485d90556?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/db4485d90556</guid>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[semantic-layer]]></category>
            <category><![CDATA[sql]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Thu, 15 Jan 2026 04:58:16 GMT</pubDate>
            <atom:updated>2026-01-15T04:58:16.106Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong><em>Disclaimer:</em></strong><em> The author works at Snowflake, but the views expressed in this article are personal and do not represent the official position of the organization.</em></blockquote><h3>Introduction</h3><p>Snowflake recently released a new SQL syntax for querying <strong>Semantic Views</strong>, enabling more intuitive and standard SQL queries for semantic layers.</p><blockquote><strong><em>Note:</em></strong><em> For the release notes about this feature, please visit </em><a href="https://docs.snowflake.com/en/release-notes/2025/9_40#semantic-views-using-standard-sql-clauses-to-query-semantic-views-preview"><em>this link</em></a><em>.</em></blockquote><p>In this article, I’ll thoroughly test the new syntax using Snowflake’s TPC-H sample data, and explain the differences from the traditional syntax, limitations, and best practices.</p><h3>What is Semantic View?</h3><p>Semantic View is Snowflake’s implementation of a <strong>semantic layer</strong>, featuring:</p><ul><li>Definition of business logic integrating multiple tables</li><li>Clear distinction between dimensions, facts, and metrics</li><li>Definition of reusable business metrics</li><li>Query simplification through data model abstraction</li></ul><h3>What Has Changed?</h3><h3>Traditional Syntax</h3><p>Previously, you had to explicitly specify dimensions and metrics using the SEMANTIC_VIEW() clause:</p><pre>SELECT * FROM SEMANTIC_VIEW(<br>    customer_order_analysis<br>    DIMENSIONS customer.customer_market_segment<br>    METRICS orders.total_revenue, orders.average_order_value<br>)<br>ORDER BY customer_market_segment;</pre><h3>New Syntax</h3><p>With the new syntax, you can specify the Semantic View name directly in the FROM clause and use <strong>standard GROUP BY syntax</strong>:</p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_revenue) AS revenue,<br>    AGG(average_order_value) AS avg_value<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment<br>ORDER BY customer_market_segment;</pre><p><strong>Key Points:</strong></p><ul><li><strong>More intuitive and readable</strong></li><li><strong>Metrics must be wrapped with functions like </strong><strong>AGG()</strong></li><li><strong>No special implementation needed when accessing semantic models from third-party or external tools</strong></li></ul><h3>Verification Environment Setup</h3><h3>Data Used</h3><p>We’ll use TPC-H sample data (Scale Factor 1):</p><pre>-- Create database and schema<br>CREATE DATABASE IF NOT EXISTS semantic_view_test;<br>USE DATABASE semantic_view_test;<br>CREATE SCHEMA IF NOT EXISTS public;<br>USE SCHEMA public;</pre><h3>Creating a Semantic View</h3><p>Let’s create a Semantic View integrating three tables: CUSTOMER, ORDERS, and LINEITEM:</p><pre>CREATE OR REPLACE SEMANTIC VIEW customer_order_analysis<br>  TABLES (<br>    customer AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER <br>      PRIMARY KEY (C_CUSTKEY),<br>    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS <br>      PRIMARY KEY (O_ORDERKEY),<br>    lineitem AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.LINEITEM<br>  )<br>  RELATIONSHIPS (<br>    -- Order → Customer relationship<br>    orders_to_customer AS orders(O_CUSTKEY) <br>      REFERENCES customer(C_CUSTKEY),<br>    -- LineItem → Order relationship<br>    lineitem_to_orders AS lineitem(L_ORDERKEY) <br>      REFERENCES orders(O_ORDERKEY)<br>  )<br>  DIMENSIONS (<br>    -- Customer dimensions<br>    customer.customer_name AS C_NAME,<br>    customer.customer_market_segment AS C_MKTSEGMENT,<br>    customer.customer_nation AS C_NATIONKEY,<br>    <br>    -- Order dimensions<br>    orders.order_status AS O_ORDERSTATUS,<br>    orders.order_priority AS O_ORDERPRIORITY,<br>    orders.order_date AS O_ORDERDATE,<br>    orders.order_year AS YEAR(O_ORDERDATE),<br>    orders.order_month AS MONTH(O_ORDERDATE)<br>  )<br>  METRICS (<br>    -- Order metrics<br>    orders.total_order_count AS COUNT(*) <br>      WITH SYNONYMS = (&#39;Total orders&#39;, &#39;Order count&#39;),<br>    <br>    orders.total_revenue AS SUM(O_TOTALPRICE) <br>      WITH SYNONYMS = (&#39;Total revenue&#39;, &#39;Revenue&#39;),<br>    <br>    orders.average_order_value AS AVG(O_TOTALPRICE) <br>      WITH SYNONYMS = (&#39;Average order value&#39;, &#39;AOV&#39;),<br>    <br>    orders.max_order_value AS MAX(O_TOTALPRICE) <br>      WITH SYNONYMS = (&#39;Maximum order value&#39;, &#39;Max order&#39;),<br>    <br>    -- LineItem metrics<br>    lineitem.total_quantity AS SUM(L_QUANTITY) <br>      WITH SYNONYMS = (&#39;Total quantity&#39;, &#39;Quantity&#39;),<br>    <br>    lineitem.avg_discount AS AVG(L_DISCOUNT) <br>      WITH SYNONYMS = (&#39;Average discount&#39;, &#39;Discount rate&#39;)<br>  );</pre><blockquote><strong><em>Important Notes</em></strong></blockquote><ul><li>RELATIONSHIPs must be defined in the direction “child table → parent table”</li><li><strong>Clause order is critical</strong>: When defining FACTS, DIMENSIONS, and METRICS together, they must be written in this exact order. Incorrect order will result in errors</li></ul><h3>Basic Usage of the New Syntax</h3><h3>1. Basic GROUP BY</h3><p>The simplest example — aggregating by customer segment:</p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue,<br>    AGG(average_order_value) AS avg_value<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment<br>ORDER BY customer_market_segment;</pre><p><strong>Sample Results:</strong></p><pre>+---------------------------+-------------+-------------------+------------------+<br>| CUSTOMER_MARKET_SEGMENT   | ORDER_COUNT | REVENUE           | AVG_VALUE        |<br>+---------------------------+-------------+-------------------+------------------+<br>| AUTOMOBILE                | 29752       | 142570259.47      | 4792.55          |<br>| BUILDING                  | 30142       | 142425379.88      | 4725.92          |<br>| FURNITURE                 | 29968       | 142563633.14      | 4756.38          |<br>| HOUSEHOLD                 | 30189       | 141659947.53      | 4692.15          |<br>| MACHINERY                 | 29949       | 142655915.51      | 4764.00          |<br>+---------------------------+-------------+-------------------+------------------+</pre><h3>2. Filtering with WHERE Clause</h3><p>Aggregate only completed orders (status=’F’):</p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue<br>FROM customer_order_analysis<br>WHERE order_status = &#39;F&#39;  -- Completed orders only<br>GROUP BY customer_market_segment<br>ORDER BY customer_market_segment;</pre><h3>3. Filtering After Aggregation with HAVING Clause</h3><p>Extract only segments with total revenue exceeding $30 million:</p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment<br>HAVING AGG(total_revenue) &gt; 30000000<br>ORDER BY revenue DESC;</pre><h3>4. GROUP BY with Multiple Dimensions</h3><p>Aggregate by combination of customer segment and order status:</p><pre>SELECT <br>    customer_market_segment,<br>    order_status,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment, order_status<br>ORDER BY customer_market_segment, order_status<br>LIMIT 20;</pre><h3>Complex Query Patterns</h3><h3>Combining with CTEs</h3><p>Perform staged aggregation using CTEs and add ranking:</p><pre>WITH segment_stats AS (<br>    SELECT <br>        customer_market_segment,<br>        AGG(total_order_count) AS order_count,<br>        AGG(total_revenue) AS revenue,<br>        AGG(average_order_value) AS avg_value<br>    FROM customer_order_analysis<br>    GROUP BY customer_market_segment<br>)<br>SELECT <br>    customer_market_segment,<br>    order_count,<br>    revenue,<br>    avg_value,<br>    RANK() OVER (ORDER BY revenue DESC) AS revenue_rank<br>FROM segment_stats<br>ORDER BY revenue_rank;</pre><h3>Combining with Conditional Expressions (CASE)</h3><p>Categorize by revenue scale:</p><pre>SELECT <br>    customer_market_segment,<br>    order_status,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue,<br>    CASE <br>        WHEN AGG(total_revenue) &gt; 50000000 THEN &#39;High&#39;<br>        WHEN AGG(total_revenue) &gt; 30000000 THEN &#39;Medium&#39;<br>        ELSE &#39;Low&#39;<br>    END AS revenue_category<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment, order_status<br>ORDER BY revenue DESC<br>LIMIT 20;</pre><h3>Calculating Percentages with Subqueries</h3><p>Calculate each segment’s percentage of total revenue:</p><pre>WITH segment_revenue AS (<br>    SELECT <br>        customer_market_segment AS segment,<br>        AGG(total_revenue) AS revenue<br>    FROM customer_order_analysis<br>    GROUP BY customer_market_segment<br>),<br>total_calc AS (<br>    SELECT SUM(revenue) AS total_revenue<br>    FROM segment_revenue<br>)<br>SELECT <br>    segment,<br>    revenue,<br>    ROUND(revenue / total_revenue * 100, 2) AS revenue_percentage<br>FROM segment_revenue<br>CROSS JOIN total_calc<br>ORDER BY revenue DESC;</pre><p><strong>Sample Results:</strong></p><pre>+-------------+-------------------+--------------------+<br>| SEGMENT     | REVENUE           | REVENUE_PERCENTAGE |<br>+-------------+-------------------+--------------------+<br>| MACHINERY   | 142655915.51      | 20.01              |<br>| AUTOMOBILE  | 142570259.47      | 20.00              |<br>| FURNITURE   | 142563633.14      | 19.99              |<br>| BUILDING    | 142425379.88      | 19.98              |<br>| HOUSEHOLD   | 141659947.53      | 19.87              |<br>+-------------+-------------------+--------------------+</pre><h3>Time Series Analysis</h3><p>Analyze revenue trends by year and segment:</p><pre>SELECT <br>    order_year,<br>    customer_market_segment,<br>    AGG(total_order_count) AS order_count,<br>    AGG(total_revenue) AS revenue<br>FROM customer_order_analysis<br>GROUP BY order_year, customer_market_segment<br>ORDER BY order_year, customer_market_segment;</pre><h3>Advanced Analysis with Window Function Metrics</h3><p>By incorporating window function metrics into the Semantic View definition, you can achieve advanced analysis like year-over-year comparisons, cumulative values, and moving averages with simple queries.</p><h3>Defining Window Function Metrics</h3><pre>CREATE SEMANTIC VIEW customer_order_with_window_metrics<br>  TABLES (<br>    customer AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER <br>      PRIMARY KEY (C_CUSTKEY),<br>    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS <br>      PRIMARY KEY (O_ORDERKEY)<br>  )<br>  RELATIONSHIPS (<br>    orders_to_customer AS orders(O_CUSTKEY) <br>      REFERENCES customer(C_CUSTKEY)<br>  )<br>  DIMENSIONS (<br>    customer.customer_market_segment AS C_MKTSEGMENT,<br>    orders.order_year AS YEAR(O_ORDERDATE)<br>  )<br>  METRICS (<br>    -- Basic metric (must be defined first)<br>    orders.total_revenue AS SUM(O_TOTALPRICE),<br>    <br>    -- Window function metric: cumulative revenue<br>    orders.cumulative_revenue AS SUM(total_revenue) OVER (<br>      PARTITION BY customer.customer_market_segment<br>      ORDER BY orders.order_year<br>      ROWS BETWEEN UNBOUNDED PRECEDING AND CURRENT ROW<br>    ),<br>    <br>    -- Window function metric: previous year&#39;s revenue<br>    orders.prev_year_revenue AS LAG(total_revenue, 1) OVER (<br>      PARTITION BY customer.customer_market_segment<br>      ORDER BY orders.order_year<br>    ),<br>    <br>    -- Window function metric: year-over-year percentage<br>    orders.revenue_yoy_pct AS (<br>      (total_revenue - LAG(total_revenue, 1) OVER (<br>        PARTITION BY customer.customer_market_segment<br>        ORDER BY orders.order_year<br>      )) / LAG(total_revenue, 1) OVER (<br>        PARTITION BY customer.customer_market_segment<br>        ORDER BY orders.order_year<br>      ) * 100<br>    ),<br>    <br>    -- Window function metric: 3-year moving average<br>    orders.moving_avg_3y AS AVG(total_revenue) OVER (<br>      PARTITION BY customer.customer_market_segment<br>      ORDER BY orders.order_year<br>      ROWS BETWEEN 2 PRECEDING AND CURRENT ROW<br>    )<br>  );</pre><blockquote><strong><em>Important Points:</em></strong></blockquote><blockquote><em>When defining window function metrics, note:</em></blockquote><ul><li><strong>Define basic metrics first</strong>: Window functions must reference already-defined metrics</li><li><strong>Required dimensions</strong>: Dimensions specified in PARTITION BY or ORDER BY are mandatory when querying</li><li><strong>Same entity</strong>: Metrics must belong to the same table (entity)</li></ul><h3>Querying with Window Function Metrics</h3><p>Using defined window function metrics enables complex time series analysis with simple queries:</p><pre>-- Get revenue trends and various indicators by year<br>SELECT <br>    customer_market_segment,<br>    order_year,<br>    AGG(total_revenue) AS revenue,<br>    AGG(cumulative_revenue) AS cumulative_revenue,<br>    AGG(prev_year_revenue) AS prev_year_revenue,<br>    ROUND(AGG(revenue_yoy_pct), 2) AS yoy_pct,<br>    ROUND(AGG(moving_avg_3y), 2) AS moving_avg_3y<br>FROM customer_order_with_window_metrics<br>GROUP BY customer_market_segment, order_year<br>ORDER BY customer_market_segment, order_year;</pre><p><strong>Sample Results (AUTOMOBILE segment):</strong></p><pre>+--------+----------+-------------+---------------+--------+-------------+<br>| YEAR   | REVENUE  | CUMULATIVE  | PREV_YEAR_REV | YOY_%  | MOVING_AVG  |<br>+--------+----------+-------------+---------------+--------+-------------+<br>| 1992   | 9234567  | 9234567     | NULL          | NULL   | 9234567     |<br>| 1993   | 23456789 | 32691356    | 9234567       | 153.99 | 16345678    |<br>| 1994   | 28765432 | 61456788    | 23456789      | 22.64  | 20485596    |<br>| 1995   | 31234567 | 92691355    | 28765432      | 8.58   | 27818929    |<br>+--------+----------+-------------+---------------+--------+-------------+</pre><h3>Analyzing Specific Segments</h3><pre>-- Time series analysis for AUTOMOBILE segment only<br>SELECT <br>    order_year,<br>    AGG(total_revenue) AS revenue,<br>    AGG(cumulative_revenue) AS cumulative_revenue,<br>    ROUND(AGG(revenue_yoy_pct), 2) AS yoy_pct,<br>    ROUND(AGG(moving_avg_3y), 2) AS moving_avg_3y<br>FROM customer_order_with_window_metrics<br>WHERE customer_market_segment = &#39;AUTOMOBILE&#39;<br>GROUP BY order_year<br>ORDER BY order_year;</pre><h3>Advantages of Window Function Metrics</h3><ol><li><strong>Centralized business logic management</strong>: Consolidate calculation formulas like year-over-year comparisons in Semantic View</li><li><strong>Simplified queries</strong>: No need to write complex window functions on the query side</li><li><strong>Reusability</strong>: Use defined metrics across multiple queries</li><li><strong>Improved maintainability</strong>: Calculation logic changes only require updates to Semantic View definition</li></ol><h3>Constraints and Error Cases</h3><p>The new syntax has the following constraints. Let me explain them with actual error messages.</p><h3>1. Metrics Must Use AGG()</h3><p>❌ <strong>Error Example:</strong></p><pre>SELECT <br>    customer_market_segment,<br>    total_revenue  -- Not wrapped with AGG()<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment;</pre><p><strong>Error Message:</strong></p><pre>SQL compilation error: error line 3 at position 5<br>&#39;CUSTOMER_ORDER_ANALYSIS.TOTAL_REVENUE&#39; in select clause is <br>neither an aggregate nor in the group by clause.</pre><p>✅ <strong>Correct Example:</strong></p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_revenue) AS revenue  -- Wrap with AGG()<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment;</pre><h3>2. Metrics Cannot Be Included in GROUP BY Clause</h3><p>❌ <strong>Error Example:</strong></p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_revenue) AS revenue<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment, total_revenue;  -- Including metric in GROUP BY</pre><p><strong>Error Message:</strong></p><pre>SQL compilation error:<br>Requested semantic expression &#39;ORDERS.TOTAL_REVENUE&#39; in DIMENSIONS clause <br>must be one of the following types: (DIMENSION, FACT).</pre><h3>3. Window Functions Cannot Be Used Directly in Queries</h3><p>You cannot use window functions directly within queries.</p><p>❌ <strong>Error Example:</strong></p><pre>SELECT <br>    customer_market_segment AS segment,<br>    AGG(total_revenue) AS revenue,<br>    SUM(AGG(total_revenue)) OVER () AS total_revenue  -- Window function<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment;</pre><p><strong>Error Message:</strong></p><pre>Unsupported feature &#39;WINDOW FUNCTIONS&#39;.</pre><p>✅ <strong>Recommended Solution: Use Window Function Metrics</strong></p><p><strong>The best approach is to incorporate window functions as metrics in the Semantic View definition.</strong> This enables advanced analysis with simple SELECT statements on the query side.</p><pre>-- Incorporate window functions in Semantic View definition<br>CREATE SEMANTIC VIEW customer_order_with_window_metrics<br>  TABLES (...)<br>  RELATIONSHIPS (...)<br>  DIMENSIONS (<br>    customer.customer_market_segment AS C_MKTSEGMENT<br>  )<br>  METRICS (<br>    -- Basic metric (define first)<br>    orders.total_revenue AS SUM(O_TOTALPRICE),<br>    <br>    -- Window function metric: percentage of total<br>    orders.revenue_percentage AS (<br>      total_revenue / SUM(total_revenue) OVER () * 100<br>    )<br>  );</pre><p>The query side becomes very simple:</p><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_revenue) AS revenue,<br>    ROUND(AGG(revenue_percentage), 2) AS revenue_percentage<br>FROM customer_order_with_window_metrics<br>GROUP BY customer_market_segment<br>ORDER BY revenue DESC;</pre><p><strong>Sample Results:</strong></p><pre>+---------------------------+-------------------+--------------------+<br>| CUSTOMER_MARKET_SEGMENT   | REVENUE           | REVENUE_PERCENTAGE |<br>+---------------------------+-------------------+--------------------+<br>| MACHINERY                 | 142655915.51      | 20.01              |<br>| AUTOMOBILE                | 142570259.47      | 20.00              |<br>| FURNITURE                 | 142563633.14      | 19.99              |<br>+---------------------------+-------------------+--------------------+</pre><p><strong>Alternative: Using CTEs</strong></p><p>If you don’t define window function metrics, you can also perform calculations stepwise using CTEs (see “Complex Query Patterns” section for details).</p><h3>Comparing Results: Traditional vs. New Syntax</h3><p>Let’s execute the same query in both syntaxes and verify that results match.</p><h3>Traditional Syntax</h3><pre>SELECT * FROM SEMANTIC_VIEW(<br>    customer_order_analysis<br>    DIMENSIONS customer.customer_market_segment<br>    METRICS orders.total_revenue<br>)<br>ORDER BY customer_market_segment;</pre><h3>New Syntax</h3><pre>SELECT <br>    customer_market_segment,<br>    AGG(total_revenue) AS total_revenue<br>FROM customer_order_analysis<br>GROUP BY customer_market_segment<br>ORDER BY customer_market_segment;</pre><p>Both produce the same results:</p><pre>+---------------------------+-------------------+<br>| CUSTOMER_MARKET_SEGMENT   | TOTAL_REVENUE     |<br>+---------------------------+-------------------+<br>| AUTOMOBILE                | 142570259.47      |<br>| BUILDING                  | 142425379.88      |<br>| FURNITURE                 | 142563633.14      |<br>| HOUSEHOLD                 | 141659947.53      |<br>| MACHINERY                 | 142655915.51      |<br>+---------------------------+-------------------+</pre><h3>Performance Considerations</h3><p>In actual testing, I found no significant performance differences between the new and traditional syntaxes. Both exhibit the following characteristics:</p><ul><li>Equivalent query plans</li><li>Same data scan volume</li><li>Similar execution times</li></ul><p>Rather than performance, the main advantages of the new syntax are <strong>readability</strong> and <strong>compatibility with standard SQL</strong>.</p><h3>Common Pitfalls When Creating Semantic Views</h3><p>Here are errors I encountered during testing and their solutions.</p><h3>1. Clause Order is Critical (FACTS, DIMENSIONS, METRICS)</h3><p>Semantic View definition has <strong>strict clause ordering requirements</strong>. When defining both FACTS and METRICS, you must follow this order:</p><ol><li>TABLES</li><li>RELATIONSHIPS</li><li><strong>FACTS</strong> (first)</li><li><strong>DIMENSIONS</strong></li><li><strong>METRICS</strong> (last)</li></ol><p>❌ <strong>Error-Causing Definition (wrong order):</strong></p><pre>CREATE SEMANTIC VIEW customer_order_analysis<br>  TABLES (...)<br>  RELATIONSHIPS (...)<br>  DIMENSIONS (...)  -- Writing DIMENSIONS first...<br>  FACTS (...)       -- Makes FACTS error out!<br>  METRICS (...);</pre><p><strong>Error Message:</strong></p><pre>SQL compilation error:<br>syntax error line 14 at position 2 unexpected &#39;FACTS&#39;.</pre><p>✅ <strong>Correct Definition (proper order):</strong></p><pre>CREATE SEMANTIC VIEW customer_order_analysis<br>  TABLES (...)<br>  RELATIONSHIPS (...)<br>  FACTS (          -- Define FACTS first<br>    orders.order_total_price AS O_TOTALPRICE<br>  )<br>  DIMENSIONS (     -- Then DIMENSIONS<br>    customer.customer_market_segment AS C_MKTSEGMENT,<br>    orders.order_status AS O_ORDERSTATUS<br>  )<br>  METRICS (        -- Finally METRICS<br>    orders.total_order_count AS COUNT(*),<br>    orders.total_revenue AS SUM(O_TOTALPRICE),<br>    orders.average_order_value AS AVG(O_TOTALPRICE)<br>  );</pre><p><strong>Reference:</strong> <a href="https://docs.snowflake.com/ja/en/sql-reference/sql/create-semantic-view">Snowflake Official Documentation — CREATE SEMANTIC VIEW</a></p><blockquote><em>Clause order is important. For example, you must specify the FACTS clause before the DIMENSIONS clause.</em></blockquote><p><strong>Using FACTS and METRICS:</strong></p><ul><li><strong>FACTS</strong>: Use for row-level raw data (without aggregation)</li><li><strong>METRICS</strong>: Use for calculated indicators using aggregate functions (SUM, AVG, COUNT, etc.)</li><li><strong>Both can be defined together</strong>: If you follow the proper order, you can define both FACTS and METRICS simultaneously</li></ul><h3>2. Watch RELATIONSHIP Direction</h3><p>❌ <strong>Error-Causing Definition:</strong></p><pre>RELATIONSHIPS (<br>  customer(C_CUSTKEY) REFERENCES orders(O_CUSTKEY)  -- Wrong direction!<br>)</pre><p><strong>Error Message:</strong></p><pre>SQL compilation error:<br>The referenced key in the relationship &#39;CUSTOMER REFERENCES ORDERS&#39; <br>must be the primary or unique key of the referenced entity.</pre><p>✅ <strong>Correct Definition:</strong></p><pre>RELATIONSHIPS (<br>  orders(O_CUSTKEY) REFERENCES customer(C_CUSTKEY)  -- Child → Parent<br>)</pre><p>RELATIONSHIPs must be defined in the direction “<strong>table with foreign key → table with primary key</strong>”.</p><h3>Supplemental: Complete Example Defining Both FACTS and METRICS</h3><p>Here’s a complete example incorporating both notes above — defining both FACTS and METRICS:</p><pre>CREATE SEMANTIC VIEW customer_order_with_facts_and_metrics<br>  TABLES (<br>    customer AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.CUSTOMER <br>      PRIMARY KEY (C_CUSTKEY),<br>    orders AS SNOWFLAKE_SAMPLE_DATA.TPCH_SF1.ORDERS <br>      PRIMARY KEY (O_ORDERKEY)<br>  )<br>  RELATIONSHIPS (<br>    -- Correct direction: child table → parent table<br>    orders_to_customer AS orders(O_CUSTKEY) <br>      REFERENCES customer(C_CUSTKEY)<br>  )<br>  FACTS (<br>    -- Define FACTS first (order matters!)<br>    orders.order_total_price AS O_TOTALPRICE,<br>    orders.order_clerk AS O_CLERK<br>  )<br>  DIMENSIONS (<br>    -- DIMENSIONS after FACTS<br>    customer.customer_market_segment AS C_MKTSEGMENT,<br>    orders.order_status AS O_ORDERSTATUS<br>  )<br>  METRICS (<br>    -- METRICS last<br>    orders.total_order_count AS COUNT(*),<br>    orders.total_revenue AS SUM(O_TOTALPRICE)<br>  );</pre><p>This way, you can use all of FACTS, DIMENSIONS, and METRICS within the same view.</p><p><strong>Query-time Constraint</strong>: However, when querying, <strong>you cannot specify both FACTS and METRICS in the same SEMANTIC_VIEW clause</strong>. You must choose one or the other.</p><pre>-- ✅ Using only FACTS<br>SELECT * FROM SEMANTIC_VIEW(<br>    customer_order_with_facts_and_metrics<br>    DIMENSIONS customer.customer_market_segment<br>    FACTS orders.order_total_price<br>);</pre><pre>-- ✅ Using only METRICS<br>SELECT * FROM SEMANTIC_VIEW(<br>    customer_order_with_facts_and_metrics<br>    DIMENSIONS customer.customer_market_segment<br>    METRICS orders.total_revenue<br>);</pre><pre>-- ❌ Both cannot be specified simultaneously<br>-- SELECT * FROM SEMANTIC_VIEW(<br>--     customer_order_with_facts_and_metrics<br>--     DIMENSIONS customer.customer_market_segment<br>--     FACTS orders.order_total_price<br>--     METRICS orders.total_revenue  -- Error<br>-- );<br>-- Error message: <br>-- SQL compilation error:<br>-- Invalid semantic view query: Facts and metrics cannot be requested in the same query.</pre><h3>Best Practices</h3><p>Based on the testing, here are best practices that emerged:</p><h3>1. Prefer the New Syntax</h3><p>By using the new syntax closer to standard SQL:</p><ul><li>Code readability improves</li><li>Developers familiar with SQL can intuitively understand it</li><li>Easier integration with BI tools</li></ul><h3>2. Leverage Window Function Metrics</h3><p>For complex analysis (year-over-year comparisons, cumulative values, moving averages, etc.), <strong>incorporate them as window function metrics in the Semantic View definition</strong>:</p><p><strong>Advantages:</strong></p><ul><li>Centralized business logic management</li><li>Simplified queries</li><li>Enhanced reusability</li><li>Easy calculation formula changes</li></ul><p><strong>Example:</strong></p><pre>METRICS (<br>  -- Basic metric<br>  orders.total_revenue AS SUM(O_TOTALPRICE),<br>  <br>  -- Window function metric<br>  orders.revenue_yoy_pct AS (<br>    (total_revenue - LAG(total_revenue, 1) OVER (...)) <br>    / LAG(total_revenue, 1) OVER (...) * 100<br>  )<br>)</pre><p>This way, the query side can get year-over-year comparisons simply by calling AGG(revenue_yoy_pct).</p><h3>3. Use CTEs for Stepwise Processing</h3><p>When not defining window function metrics or when complex multi-stage aggregations are needed, using CTEs stepwise:</p><ul><li>Clarifies logic</li><li>Eases debugging</li><li>Improves readability</li></ul><h3>4. Use Meaningful Metric Names</h3><pre>METRICS (<br>  orders.total_revenue AS SUM(O_TOTALPRICE) <br>    WITH SYNONYMS = (&#39;Total revenue&#39;, &#39;Revenue&#39;)  -- Set synonyms too<br>)</pre><p>By setting synonyms:</p><ul><li>Support for natural language queries (like Snowflake Copilot)</li><li>Multilingual support possible</li></ul><h3>5. Be Mindful of Dimension Granularity</h3><p>Design queries considering the relationship (granularity) between dimensions and metrics. When granularity doesn’t match, you can check which dimensions are available:</p><pre>SHOW SEMANTIC DIMENSIONS IN customer_order_analysis <br>FOR METRIC total_revenue;</pre><h3>6. Watch Clause Order (Important!)</h3><p>When defining Semantic Views, <strong>clause order is strictly determined</strong>:</p><pre>CREATE SEMANTIC VIEW view_name<br>  TABLES (...)<br>  RELATIONSHIPS (...)<br>  FACTS (...)        -- First<br>  DIMENSIONS (...)   -- Then<br>  METRICS (...);     -- Last</pre><p>Not following this order will cause errors. Especially careful when defining both FACTS and METRICS.</p><h3>Summary</h3><p>Through testing Snowflake Semantic View’s new SQL syntax, we learned:</p><h3>Advantages</h3><p>✅ High compatibility with standard SQL, intuitive to use<br>✅ Equivalent performance to traditional syntax<br>✅ Easy combination with CTEs and subqueries<br>✅ <strong>Window function metrics</strong> enable advanced analysis with simple queries</p><h3>Cautions</h3><p>⚠️ Metrics require functions like AGG()<br>⚠️ Window functions can&#39;t be used directly in queries (<strong>define as window function metrics</strong> recommended)<br>⚠️ Metrics can&#39;t be included in GROUP BY clause</p><h3>Which Should You Use?</h3><p><strong>We recommend the new SQL syntax for new development.</strong></p><p>Reasons:</p><ol><li>Close to standard SQL, low learning cost</li><li>High readability, easy to maintain</li><li>No functional differences from traditional syntax</li></ol><p>However, traditional syntax remains an option for existing queries or specific constraints.</p><h3>Reference Materials</h3><ul><li><a href="https://docs.snowflake.com/en/user-guide/views-semantic/querying">Snowflake Official Documentation: Querying semantic views</a></li><li><a href="https://docs.snowflake.com/en/user-guide/views-semantic">Snowflake Official Documentation: Semantic Views Overview</a></li><li><a href="https://docs.snowflake.com/en/sql-reference/sql/create-semantic-view">Snowflake Official Documentation: CREATE SEMANTIC VIEW</a></li></ul><h3>Conclusion</h3><p>The new Semantic View syntax makes the semantic layer more accessible. Developers familiar with standard SQL can start using it with minimal learning cost.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=db4485d90556" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Understanding Snowflake Cortex AI Pricing Changes: A Comprehensive Guide]]></title>
            <link>https://medium.com/@masato.takada/understanding-snowflake-cortex-ai-pricing-changes-a-comprehensive-guide-cdb629bb4375?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/cdb629bb4375</guid>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[cortex]]></category>
            <category><![CDATA[pricing]]></category>
            <category><![CDATA[snowflake]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Tue, 23 Dec 2025 04:39:13 GMT</pubDate>
            <atom:updated>2025-12-23T04:39:13.261Z</atom:updated>
            <content:encoded><![CDATA[<blockquote><strong><em>Disclaimer:</em></strong><em> The author works at Snowflake, but this article represents personal views and not the official position of the organization.</em></blockquote><h3>1. Introduction</h3><p>Before diving into cost monitoring and management methods for Cortex-related features, it’s important to understand that Snowflake changed its Cortex AI billing structure in November 2025. This update shifts from the traditional billing system to a <strong>token-based billing model</strong>, aligning more closely with AI market standards. This article examines these changes in detail and their implications for users.</p><h3>2. Background</h3><p>The primary goal of this pricing model change is to promote standardization with pricing practices in the Generative AI market. Specifically, it aims to achieve three objectives:</p><ul><li><strong>Stronger alignment with market standards</strong></li><li><strong>Improved transparency</strong></li><li><strong>More equitable cost structure</strong></li></ul><p>Users can now manage costs more accurately and intuitively based on the resources consumed (token volume and storage capacity). For detailed information, please refer to the <a href="https://www.snowflake.com/legal-files/CreditConsumptionTable.pdf"><strong>Consumption Table</strong></a>.</p><h3>3. Summary of Changes</h3><p>Here’s an overview of the changes for each feature and their effective dates:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/786/1*W4sYpXRgREck3p5ez8D_lQ.png" /></figure><h3>4. Detailed Breakdown of Changes by Feature</h3><p>Here are the specific changes for each feature:</p><h3>4–1. Snowflake Intelligence &amp; Cortex Agents</h3><p>The free preview period has ended, and full pay-as-you-go billing has begun. It’s crucial to understand that the cost for these features is calculated using a “two-tier” structure: the “brain” (LLM) and the “hands” (tools).</p><p><strong>Change</strong>: Free during preview → Token-based billing begins</p><p><strong>Billing Mechanism (Two-tier Structure)</strong>:</p><ul><li><strong>Orchestrator LLM Usage Fee</strong>: Cost based on token consumption of the model serving as the agent’s “brain” (e.g., Claude) for reasoning and planning.</li><li><strong>Connected Tools Usage Fee</strong>: Costs for functions called by the agent (Cortex Search queries, Analyst analyses, external API executions, etc.).</li><li><strong>Key Point</strong>: When an agent performs complex tasks and repeatedly calls tools, costs accumulate for each tool invocation.</li></ul><h3>4–2. Cortex REST API (AI_COMPLETE)</h3><p>The billing unit for direct LLM calls via Cortex (such as the AI_COMPLETE function) has been revamped. This aligns with standard billing practices of LLM providers like OpenAI, enabling more granular management.</p><p><strong>Changes</strong>:</p><ul><li>Credit-based / No classification → Dollar-based※ / 4 classifications (input, output, cache).</li><li>Token type refinement (uniform → <strong>4 categories</strong>).</li></ul><p><strong>Four New Billing Elements</strong>:</p><figure><img alt="" src="https://cdn-images-1.medium.com/max/760/1*WQLATS9aP3uhN92MfO7Z4w.png" /></figure><p><strong>Important Notes (※)</strong>:</p><ul><li>The shift to dollar-based pricing means that pricing is now uniform across Standard, Enterprise, and Business Critical editions, removing edition-based variations.</li><li>Cache functionality is only available for <strong>Anthropic Claude</strong> and <strong>OpenAI</strong> models.</li></ul><h3>4–3. Cortex Analyst</h3><p>A hybrid billing system has been introduced, varying between “<strong>flat-rate message-based billing</strong>” and “<strong>consumption-based token billing</strong>” depending on the usage scenario.</p><p><strong>Pattern A: Standalone Usage (Direct Interaction via Web UI / API)</strong></p><ul><li><strong>Billing Unit</strong>: Message-based</li><li><strong>Pricing</strong>: 67 credits / 1,000 messages</li><li><strong>Additional Cost</strong>: Separate virtual warehouse (WH) costs for executing generated SQL.</li><li><strong>Typical Scenario</strong>: Standard use where users perform data analysis via chat.</li></ul><p><strong>Pattern B: Used as a Tool by SI / Agents (via Agents)</strong></p><ul><li><strong>Change</strong>: System changed on November 10</li><li><strong>Billing Unit</strong>: Input/output token-based (per million tokens)</li><li><strong>Rationale</strong>: When an agent calls Analyst as a “tool” behind the scenes, token volume varies with conversational context, making token-based billing more equitable than message-based billing.</li></ul><h3>4–4. Cortex Search</h3><p>This is the foundational search feature for RAG (Retrieval-Augmented Generation). Pay attention to “<strong>serving indexed data</strong>” and “<strong>index creation via Embedding</strong>”.</p><p><strong>1. Serving (Retention &amp; Search) Cost:</strong></p><ul><li><strong>Pricing: 6.3 credits / GB / month</strong></li><li><strong>Details</strong>: Fee for maintaining created search indexes in memory and keeping them ready to respond to queries (serverless compute).</li><li><strong>Important</strong>: Costs accrue <strong>as long as Cortex Search is running</strong>, even when not actively searching. <strong>Suspend when not in use</strong> is strongly recommended.</li></ul><p><strong>2. Index Creation &amp; Update Cost:</strong></p><ul><li>Vectorizing (embedding) text data incurs separate computing costs.</li><li>Credits are consumed during initial creation or data updates via warehouse or serverless compute.</li></ul><h3>5. Cost Calculation Examples</h3><p>Let me introduce cost calculation scenarios when combining multiple features. The key point here is that planning costs arise from <strong>either</strong> Snowflake Intelligence <strong>or</strong> Cortex Agents, not both.</p><h3>Scenario 1: Business Automation Using Snowflake Intelligence (SI)</h3><p><strong>1. Scenario Assumptions (Connected Tool Configuration)</strong> This agent utilizes the following four tools based on user instructions:</p><ul><li>Cortex Analyst for financial data (structured data analysis)</li><li>Cortex Analyst for marketing data (structured data analysis)</li><li>Cortex Search for document retrieval (unstructured data search)</li><li>Stored procedure (SPROC) for email sending (external actions)</li></ul><p><strong>2. Total Cost Calculation Formula</strong> Total cost in this case is the sum of four elements:</p><pre>Total Cost = <br>  ① Planning Cost (Snowflake Intelligence) <br>  + ② Tool Usage Cost (Cortex Analyst) <br>  + ③ Tool Usage Cost (Cortex Search) <br>  + ④ Compute Cost (Warehouse)</pre><ul><li>① <strong>Snowflake Intelligence Fee</strong>: Token volume consumed by the orchestrator LLM for thinking and planning.</li><li>② <strong>Cortex Analyst Fees</strong>: Input/output token volume when the SI agent calls Analyst (※consumption-based billing for tool usage).</li><li>③ <strong>Cortex Search Fee</strong>: Capacity-based billing for maintaining search indexes.</li><li>④ <strong>WH Cost for Tool Execution</strong>: Warehouse costs for executing SQL generated by Analyst and running email-sending SPROCs.</li></ul><p><strong>Important Note</strong>: While a Cortex Agent is configured behind Snowflake Intelligence, you might think costs accrue from both Snowflake Intelligence and Cortex Agents. However, <strong>only Snowflake Intelligence costs are charged</strong>.</p><h3>Scenario 2: Business Automation Using Cortex Agent from Any Client</h3><p><strong>1. Scenario Assumptions (Connected Tool Configuration)</strong> This agent utilizes the following four tools based on user instructions:</p><ul><li>Cortex Analyst for financial data (structured data analysis)</li><li>Cortex Analyst for marketing data (structured data analysis)</li><li>Cortex Search for document retrieval (unstructured data search)</li><li>Stored procedure (SPROC) for email sending (external actions)</li></ul><p><strong>2. Total Cost Calculation Formula</strong> Total cost in this case is the sum of four elements:</p><pre>Total Cost = <br>  ① Planning Cost (Cortex Agent) <br>  + ② Tool Usage Cost (Cortex Analyst) <br>  + ③ Tool Usage Cost (Cortex Search) <br>  + ④ Compute Cost (Warehouse)</pre><ul><li>① <strong>Cortex Agent Fee</strong>: Token volume consumed by the orchestrator LLM for thinking and planning.</li><li>② <strong>Cortex Analyst Fees</strong>: Input/output token volume when the agent calls Analyst (※consumption-based billing for tool usage).</li><li>③ <strong>Cortex Search Fee</strong>: Capacity-based billing for maintaining search indexes.</li><li>④<strong>WH Cost for Tool Execution</strong>: Warehouse costs for executing SQL generated by Analyst and running email-sending SPROCs.</li></ul><h3>6. Conclusion</h3><p>In November 2025, Snowflake revamped its Cortex AI pricing structure, making a significant shift toward “<strong>token-based</strong>” billing aligned with market standards. The core of this change is to enhance cost transparency and achieve fair billing that reflects actual usage.</p><p>Major changes include the <strong>Cortex REST API’s transition to dollar-based pricing</strong> and <strong>separate billing for input and output tokens in Cortex functions</strong>. Additionally, <strong>Snowflake Intelligence</strong> and <strong>Cortex Agents</strong>, previously in free preview, are now <strong>paid services</strong> with a billing structure that aggregates orchestrator costs and connected tool usage (Analyst, Search, etc.). Notably, Cortex Analyst shifts from <strong>message-based</strong> to <strong>token-based</strong> billing when used via Agents, which is a significant change to consider.</p><p>Understanding these changes will help you better manage and optimize your AI workload costs on Snowflake’s platform.</p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=cdb629bb4375" width="1" height="1" alt="">]]></content:encoded>
        </item>
        <item>
            <title><![CDATA[Complete Guide to Monitoring Snowflake Cortex AI: Adding Cortex Agents & Snowflake Intelligence…]]></title>
            <link>https://medium.com/@masato.takada/complete-guide-to-monitoring-snowflake-cortex-organizing-cortex-services-views-82c11aaac283?source=rss-a32a05d7f19------2</link>
            <guid isPermaLink="false">https://medium.com/p/82c11aaac283</guid>
            <category><![CDATA[usage]]></category>
            <category><![CDATA[ai]]></category>
            <category><![CDATA[snowflake]]></category>
            <category><![CDATA[cortex]]></category>
            <category><![CDATA[monitoring]]></category>
            <dc:creator><![CDATA[Masato Takada]]></dc:creator>
            <pubDate>Tue, 23 Dec 2025 04:23:22 GMT</pubDate>
            <atom:updated>2026-02-20T06:58:52.592Z</atom:updated>
            <content:encoded><![CDATA[<h3>Complete Guide to Monitoring Snowflake Cortex AI: Adding Cortex Agents &amp; Snowflake Intelligence Views</h3><blockquote><strong><em>Disclaimer</em></strong><em>: While the author is affiliated with Snowflake, this article represents personal views and not the official position of the organization.</em></blockquote><h3>📢 Breaking News (February 20, 2026)</h3><p><strong>New monitoring views for Snowflake Intelligence and Cortex Agents are now available!</strong></p><ul><li>SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY</li><li>SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY</li></ul><p>These preview features enable detailed cost analysis and token-level monitoring, including cache optimization tracking. This article covers comprehensive usage examples and best practices.</p><h3>1. Background</h3><p>Snowflake has been actively updating its Cortex AI-related features in recent years. While various AI capabilities such as AI Functions, Cortex Analyst, and Cortex Search have been added, the views for monitoring each service’s usage are scattered across ACCOUNT_USAGE, ORGANIZATION_USAGE, INFORMATION_SCHEMA, LOCAL, and other schemas, making it difficult to grasp the full picture.</p><p>In this article, I’ll systematically organize Snowflake Cortex-related monitoring views and introduce efficient monitoring methods with practical examples.</p><h3>2. Summary: Cortex Monitoring Views Overview</h3><figure><img alt="" src="https://cdn-images-1.medium.com/max/868/1*sJ0UtdpCfYCMWToD9HWImg.png" /></figure><h3>3. Monitoring Methods for Each Tool</h3><h3>3.1 AI Functions</h3><h4>📝 Overview</h4><p>CORTEX_AISQL_USAGE_HISTORY records the usage of Cortex AI Functions such as AI_COMPLETE, SENTIMENT, and TRANSLATE on a per-function-call basis.</p><ul><li><strong>Target</strong>: Cortex AI Functions (AI_COMPLETE, SENTIMENT, etc.)</li><li><strong>Granularity</strong>: Per function call</li><li><strong>Key Columns</strong>: usage_time, model_name, function_name, tokens, token_credits, query_id</li><li><strong>Use Case</strong>: Detailed cost analysis and model-specific usage tracking for AI functions</li></ul><h4>💡 Example 1: Recent AI Function Usage History</h4><pre>SELECT <br>    usage_time,<br>    model_name,<br>    function_name,<br>    tokens,<br>    token_credits,<br>    query_id,<br>    warehouse_id<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AISQL_USAGE_HISTORY<br>ORDER BY usage_time DESC<br>LIMIT 100;</pre><h4>💡 Example 2: Usage Summary by Model (Last 7 Days)</h4><pre>SELECT <br>    model_name,<br>    function_name,<br>    COUNT(*) AS call_count,<br>    SUM(tokens) AS total_tokens,<br>    SUM(token_credits) AS total_credits,<br>    AVG(tokens) AS avg_tokens_per_call,<br>    AVG(token_credits) AS avg_credits_per_call<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AISQL_USAGE_HISTORY<br>WHERE usage_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>GROUP BY model_name, function_name<br>ORDER BY total_credits DESC;</pre><h4>💡 Example 3: AI Function Usage by User</h4><p>By joining with QUERY_HISTORY, you can retrieve usernames and query details.</p><pre>SELECT <br>    q.user_name,<br>    c.model_name,<br>    c.function_name,<br>    COUNT(*) AS call_count,<br>    SUM(c.tokens) AS total_tokens,<br>    SUM(c.token_credits) AS total_credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AISQL_USAGE_HISTORY c<br>INNER JOIN SNOWFLAKE.ACCOUNT_USAGE.QUERY_HISTORY q <br>    ON c.query_id = q.query_id<br>WHERE c.usage_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY q.user_name, c.model_name, c.function_name<br>ORDER BY total_credits DESC;</pre><h3>3.2 Cortex Analyst</h3><h4>📝 Overview</h4><p>Cortex Analyst is a service for performing data analysis using natural language. It can be monitored through two views.</p><h4>3.2.1 CORTEX_ANALYST_USAGE_HISTORY</h4><ul><li><strong>Target</strong>: Cortex Analyst service</li><li><strong>Granularity</strong>: Hourly aggregation</li><li><strong>Key Columns</strong>: start_time, end_time, username, request_count, credits</li><li><strong>Use Case</strong>: Per-user usage time and cost monitoring</li></ul><p>💡 Example 1: Hourly Cost Verification</p><pre>SELECT <br>    start_time,<br>    end_time,<br>    username,<br>    request_count,<br>    credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY <br>ORDER BY start_time DESC<br>LIMIT 100;</pre><p>💡 Example 2: Per-User Summary (Last 30 Days)</p><pre>SELECT <br>    username,<br>    COUNT(*) AS time_periods,<br>    SUM(request_count) AS total_requests,<br>    SUM(credits) AS total_credits,<br>    AVG(credits) AS avg_credits_per_period<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY<br>WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY username<br>ORDER BY total_credits DESC;</pre><h4>3.2.2 CORTEX_ANALYST_REQUESTS_V (Local View)</h4><ul><li><strong>Target</strong>: Individual Analyst requests</li><li><strong>Granularity</strong>: Request-level details</li><li><strong>Key Columns</strong>: request_id, generated_sql, latest_question, semantic_model_name, response_status_code</li><li><strong>Use Case</strong>: Specific SQL generation content and error analysis</li></ul><blockquote><strong><em>⚠️ Warning</em></strong><em>: This is an account-specific local view and may not exist in all environments.</em></blockquote><p>💡 Example: Request Details Verification</p><pre>SELECT<br>    timestamp,<br>    request_id,<br>    generated_sql,<br>    latest_question,<br>    semantic_model_type,<br>    semantic_model_name,<br>    response_status_code,<br>    warnings,<br>    response_metadata<br>FROM SNOWFLAKE.LOCAL.CORTEX_ANALYST_REQUESTS_V<br>ORDER BY timestamp DESC<br>LIMIT 100;</pre><h3>3.3 Cortex Search</h3><p>Cortex Search can be monitored in a <strong>multi-layered approach with 3 views</strong>.</p><h4>3.3.1 INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICES ✨ Newly Added</h4><ul><li><strong>Data Source</strong>: INFORMATION_SCHEMA (metadata)</li><li><strong>Target</strong>: Cortex Search service configuration and status information</li><li><strong>Key Columns</strong>:</li><li>Configuration: service_name, search_column, embedding_model, warehouse</li><li>Data Size: source_data_bytes, serving_data_bytes, source_data_num_rows</li><li>Status: indexing_state, serving_state, data_timestamp</li><li><strong>Use Case</strong>: Service configuration verification, cost prediction based on data size, index status monitoring</li></ul><p>💡 Example 1: Retrieving Service Details</p><pre>SELECT <br>    service_catalog AS database_name,<br>    service_schema AS schema_name,<br>    service_name,<br>    created,<br>    target_lag,<br>    warehouse,<br>    search_column,<br>    attribute_columns,<br>    embedding_model,<br>    -- Data size information<br>    source_data_num_rows,<br>    source_data_bytes,<br>    ROUND(source_data_bytes / 1024 / 1024, 2) AS source_data_mb,<br>    serving_data_bytes,<br>    ROUND(serving_data_bytes / 1024 / 1024, 2) AS serving_data_mb,<br>    -- Status information<br>    indexing_state,<br>    serving_state, <br>    data_timestamp,<br>    indexing_error,<br>    comment<br>FROM &lt;YOUR_DATABASE&gt;.INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICES<br>ORDER BY service_catalog, service_schema, service_name;</pre><p>💡 Example 2: Cost Prediction</p><p>Serving costs can be predicted by converting serving_data_bytes to GB/month.</p><pre>SELECT <br>    service_catalog || &#39;.&#39; || service_schema || &#39;.&#39; || service_name AS full_service_name,<br>    source_data_num_rows,<br>    ROUND(serving_data_bytes / 1024 / 1024 / 1024, 4) AS serving_data_gb,<br>    -- Estimated monthly cost (assuming 6.3 credits/GB/month)<br>    ROUND((serving_data_bytes / 1024 / 1024 / 1024) * 6.3, 2) AS estimated_monthly_credits,<br>    indexing_state,<br>    serving_state,<br>    embedding_model<br>FROM &lt;YOUR_DATABASE&gt;.INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICES<br>WHERE serving_state = &#39;ACTIVE&#39;<br>ORDER BY serving_data_bytes DESC;</pre><blockquote><strong><em>Note</em></strong><em>: Please refer to the </em><a href="https://www.snowflake.com/legal/snowflake-service-consumption-table/"><em>Snowflake Service Consumption Table</em></a><em> for credit rates.</em></blockquote><h4>3.3.2 CORTEX_SEARCH_DAILY_USAGE_HISTORY</h4><ul><li><strong>Aggregation Level</strong>: Daily aggregation</li><li><strong>Target</strong>: Actual costs for index creation and updates</li><li><strong>Key Columns</strong>: usage_date, consumption_type, credits, tokens</li><li><strong>Use Case</strong>: Long-term cost trend analysis and capacity planning</li></ul><p>💡 Example 1: Daily Usage Verification</p><pre>SELECT <br>    usage_date,<br>    database_name,<br>    schema_name,<br>    service_name,<br>    consumption_type,<br>    credits,<br>    model_name,<br>    tokens<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_SEARCH_DAILY_USAGE_HISTORY<br>ORDER BY usage_date DESC, credits DESC<br>LIMIT 100;</pre><p>💡 Example 2: Per-Service Cost Summary (Last 30 Days)</p><pre>SELECT <br>    database_name,<br>    schema_name,<br>    service_name,<br>    consumption_type,<br>    SUM(credits) AS total_credits,<br>    SUM(tokens) AS total_tokens,<br>    COUNT(DISTINCT usage_date) AS active_days<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_SEARCH_DAILY_USAGE_HISTORY<br>WHERE usage_date &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY database_name, schema_name, service_name, consumption_type<br>ORDER BY total_credits DESC;</pre><h4>3.3.3 CORTEX_SEARCH_SERVING_USAGE_HISTORY</h4><ul><li><strong>Aggregation Level</strong>: Hourly</li><li><strong>Target</strong>: Search query execution costs</li><li><strong>Key Columns</strong>: start_time, end_time, service_name, credits</li><li><strong>Use Case</strong>: Real-time usage monitoring and performance analysis</li></ul><p>💡 Example: Hourly Serving Cost Verification</p><pre>SELECT <br>    start_time,<br>    end_time,<br>    database_name,<br>    schema_name,<br>    service_name,<br>    credits<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_SEARCH_SERVING_USAGE_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h4>3.3.4 CORTEX_SEARCH_REFRESH_HISTORY</h4><ul><li><strong>Target</strong>: Index update performance</li><li><strong>Key Columns</strong>: start_time, warehouse_name, rows_inserted/updated/deleted, bytes_inserted/updated/deleted</li><li><strong>Use Case</strong>: Performance and cost analysis for index updates</li></ul><p>💡 Example: Refresh History Verification</p><pre>SELECT <br>    start_time,<br>    end_time,<br>    database_name,<br>    schema_name,<br>    service_name,<br>    warehouse_name,<br>    DATEDIFF(&#39;second&#39;, start_time, end_time) AS duration_seconds,<br>    rows_inserted,<br>    rows_updated,<br>    rows_deleted,<br>    bytes_inserted,<br>    bytes_updated,<br>    bytes_deleted<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_SEARCH_REFRESH_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h4>📊 Cortex Search Monitoring: 3-Layer Architecture</h4><p><strong>Layer 1: Configuration &amp; Prediction (Planning Phase)</strong></p><ul><li>View: CORTEX_SEARCH_SERVICES</li><li>Purpose: Cost prediction, capacity design</li></ul><p><strong>Layer 2: Actual Tracking (Post-Analysis)</strong></p><ul><li>View: CORTEX_SEARCH_DAILY_USAGE_HISTORY</li><li>Purpose: Monthly reports, trends</li></ul><p><strong>Layer 3: Real-time (Operations Monitoring)</strong></p><ul><li>View: CORTEX_SEARCH_SERVING_USAGE_HISTORY</li><li>Purpose: Anomaly detection, optimization</li></ul><p><strong>Use Case Differences</strong>:</p><p><strong>Planning Phase: </strong><strong>INFORMATION_SCHEMA.CORTEX_SEARCH_SERVICES</strong></p><ul><li>Cost estimation before creating new services</li><li>Monthly cost prediction based on data size</li><li>Service configuration verification and auditing</li></ul><p><strong>Daily Monitoring: </strong><strong>CORTEX_SEARCH_DAILY_USAGE_HISTORY</strong></p><ul><li>Monthly/weekly report creation</li><li>Budget management and cost forecasting</li><li>Service-specific usage trend analysis</li></ul><p><strong>Real-time Monitoring: </strong><strong>CORTEX_SEARCH_SERVING_USAGE_HISTORY</strong></p><ul><li>Immediate anomaly detection</li><li>Time-based load analysis</li><li>Performance optimization</li></ul><h3>3.4 Document AI</h3><h4>3.4.1 DOCUMENT_AI_USAGE_HISTORY (Deprecated Feature)</h4><ul><li><strong>Target</strong>: Legacy Document AI functionality</li><li><strong>Key Columns</strong>: operation_name, page_count, document_count, credits_used</li></ul><blockquote><strong><em>⚠️ Warning</em></strong><em>: Document AI is a deprecated feature. For new development, please use </em><em>CORTEX_DOCUMENT_PROCESSING_USAGE_HISTORY instead.</em></blockquote><p>💡 Example: Document AI Usage</p><pre>SELECT <br>    start_time,<br>    end_time,<br>    query_id,<br>    operation_name,<br>    page_count,<br>    document_count,<br>    feature_count,<br>    credits_used<br>FROM SNOWFLAKE.ACCOUNT_USAGE.DOCUMENT_AI_USAGE_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h4>3.4.2 CORTEX_DOCUMENT_PROCESSING_USAGE_HISTORY</h4><ul><li><strong>Target</strong>: New document processing features like AI_PARSE_DOCUMENT</li><li><strong>Key Columns</strong>: model_name, page_count, credits_used</li></ul><p>💡 Example: Cortex Document Processing Usage</p><pre>SELECT <br>    start_time,<br>    end_time,<br>    model_name,<br>    page_count,<br>    credits_used<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_DOCUMENT_PROCESSING_USAGE_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h3>3.5 Cortex Agents (✨ Preview Feature)</h3><h4>📝 Overview</h4><p>CORTEX_AGENT_USAGE_HISTORY is a new view for tracking Cortex Agents usage (released February 20, 2026).</p><ul><li><strong>Target</strong>: Cortex Agent invocations</li><li><strong>Granularity</strong>: Per request</li><li><strong>Key Columns</strong>: start_time, user_name, agent_name, request_id, parent_request_id, tokens, token_credits, tokens_granular, credits_granular</li><li><strong>Use Case</strong>: Agent usage monitoring, underlying tool analysis (Cortex Analyst/Search), parent-child request tracking</li></ul><h4>🔍 TOKENS_GRANULAR Detailed Structure</h4><p>A key feature of Cortex Agents is the ability to view <strong>detailed token usage</strong> through the TOKENS_GRANULAR column. This column contains a JSON structure with the following information:</p><pre>{<br>  &quot;request_id&quot;: {<br>    &quot;cortex_agents&quot;: {<br>      &quot;claude-sonnet-4-5&quot;: {<br>        &quot;cache_read_input&quot;: 21593,<br>        &quot;cache_write_input&quot;: 52915,<br>        &quot;input&quot;: 4,<br>        &quot;output&quot;: 411<br>      }<br>    },<br>    &quot;start_time&quot;: &quot;2026/02/19 06:20-21&quot;<br>  }<br>}</pre><p><strong>Field Descriptions</strong>:</p><ul><li><strong>service_type</strong>: Service type used (e.g., cortex_agents, cortex_analyst)</li><li><strong>model</strong>: Model name used (e.g., claude-sonnet-4-5)</li><li><strong>input</strong>: New input tokens (standard cost, cache not used)</li><li><strong>output</strong>: Output tokens (generated response)</li><li><strong>cache_read_input</strong>: Input tokens read from cache (<strong>key to cost savings</strong>)</li><li><strong>cache_write_input</strong>: Input tokens written to cache (occurs on first request)</li><li><strong>start_time</strong>: Request start time</li></ul><h4>💰 Cost Optimization with Caching</h4><p>The cache_read_input and cache_write_input fields are particularly important. With prompt caching:</p><ul><li><strong>cache_read_input</strong>: <strong>90% cheaper</strong> than standard input tokens (0.1x cost)</li><li><strong>cache_write_input</strong>: 25% more expensive than standard input tokens (1.25x cost)</li></ul><p><strong>Real-World Impact</strong>:</p><p>Based on the example above:</p><ul><li>cache_read_input: <strong>21,593 tokens</strong> → Processed at 10% of normal input cost</li><li>cache_write_input: <strong>52,915 tokens</strong> → Initial investment for future cache hits</li><li>input: 4 tokens (new input, cache not used)</li><li>output: 411 tokens (generated response)</li></ul><p><strong>Cost Savings Calculation</strong>:</p><p>Assuming standard input token cost = 1.0:</p><ul><li>Without cache: 21,593 tokens × 1.0 = 21,593 cost units</li><li>With cache: 21,593 tokens × 0.1 = 2,159.3 cost units</li><li><strong>Savings</strong>: ~19,434 cost units (<strong>~90% reduction</strong>)</li></ul><p>By leveraging prompt caching, you can achieve <strong>dramatic cost reductions</strong> in production scenarios.</p><blockquote><strong><em>⚠️ Important</em></strong><em>: Regularly analyzing </em><em>TOKENS_GRANULAR and </em><em>CREDITS_GRANULAR allows you to quantify cache effectiveness and optimize agent design.</em></blockquote><h4>💡 Example 1: Recent Usage History</h4><pre>SELECT <br>    start_time,<br>    end_time,<br>    user_name,<br>    agent_database_name,<br>    agent_schema_name,<br>    agent_name,<br>    request_id,<br>    parent_request_id,<br>    token_credits,<br>    tokens<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h4>💡 Example 2: Per-Agent Cost Summary (Last 30 Days)</h4><pre>SELECT <br>    agent_database_name,<br>    agent_schema_name,<br>    agent_name,<br>    COUNT(DISTINCT user_name) AS unique_users,<br>    COUNT(*) AS total_requests,<br>    SUM(tokens) AS total_tokens,<br>    SUM(token_credits) AS total_credits,<br>    MIN(start_time) AS first_usage,<br>    MAX(start_time) AS last_usage<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY agent_database_name, agent_schema_name, agent_name<br>ORDER BY total_credits DESC;</pre><h4>💡 Example 3: Detailed Token Analysis (TOKENS_GRANULAR)</h4><pre>SELECT <br>    start_time,<br>    user_name,<br>    agent_name,<br>    request_id,<br>    tokens_granular,<br>    token_credits,<br>    DATEDIFF(&#39;second&#39;, start_time, end_time) AS duration_seconds<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>WHERE start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>ORDER BY start_time DESC<br>LIMIT 50;</pre><h4>💡 Example 4: Parent-Child Request Tracking</h4><p>When agents call other tools, parent-child relationships are recorded.</p><pre>SELECT <br>    parent_request_id,<br>    COUNT(*) AS child_request_count,<br>    SUM(tokens) AS total_tokens,<br>    SUM(token_credits) AS total_credits,<br>    MIN(start_time) AS first_child_start,<br>    MAX(end_time) AS last_child_end<br>FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>WHERE parent_request_id IS NOT NULL<br>    AND start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>GROUP BY parent_request_id<br>ORDER BY total_credits DESC<br>LIMIT 100;</pre><h3>3.6 Snowflake Intelligence (✨ Preview Feature)</h3><h4>📝 Overview</h4><p>SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY is a new view for tracking Snowflake Intelligence usage (released February 20, 2026). It has a similar structure to Cortex Agents but enables instance-level monitoring.</p><ul><li><strong>Target</strong>: Snowflake Intelligence instance invocations</li><li><strong>Granularity</strong>: Per request</li><li><strong>Key Columns</strong>: start_time, user_name, snowflake_intelligence_name, agent_name, request_id, tokens, token_credits, tokens_granular, credits_granular</li><li><strong>Use Case</strong>: Snowflake Intelligence instance usage monitoring, multi-agent processing cost analysis</li></ul><h4>🔍 Differences from Cortex Agents</h4><p>Snowflake Intelligence can integrate multiple Cortex Agents, providing additional information:</p><ul><li>snowflake_intelligence_id / snowflake_intelligence_name: Instance identification</li><li>snowflake_intelligence_tags: Instance-level tags (useful for cost allocation)</li><li><strong>Multi-agent integration monitoring</strong>: Total cost tracking when one Snowflake Intelligence instance calls multiple agents</li></ul><p>Snowflake Intelligence also supports TOKENS_GRANULAR and CREDITS_GRANULAR, enabling detailed token analysis and cache effectiveness measurement.</p><h4>💡 Example 1: Recent Usage History</h4><pre>SELECT <br>    start_time,<br>    end_time,<br>    user_name,<br>    snowflake_intelligence_name,<br>    agent_name,<br>    request_id,<br>    parent_request_id,<br>    token_credits,<br>    tokens<br>FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>ORDER BY start_time DESC<br>LIMIT 100;</pre><h4>💡 Example 2: Per-Instance Cost Summary (Last 30 Days)</h4><pre>SELECT <br>    snowflake_intelligence_name,<br>    agent_database_name,<br>    agent_schema_name,<br>    agent_name,<br>    COUNT(DISTINCT user_name) AS unique_users,<br>    COUNT(*) AS total_requests,<br>    SUM(tokens) AS total_tokens,<br>    SUM(token_credits) AS total_credits,<br>    MIN(start_time) AS first_usage,<br>    MAX(start_time) AS last_usage<br>FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY snowflake_intelligence_name, agent_database_name, agent_schema_name, agent_name<br>ORDER BY total_credits DESC;</pre><h4>💡 Example 3: Parent-Child Request Chain Analysis</h4><p>Snowflake Intelligence can call multiple agents. This query analyzes complex request chains.</p><pre>WITH parent_requests AS (<br>    SELECT <br>        request_id,<br>        start_time,<br>        end_time,<br>        user_name,<br>        snowflake_intelligence_name,<br>        token_credits,<br>        tokens<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>    WHERE parent_request_id IS NULL<br>        AND start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>),<br>child_requests AS (<br>    SELECT <br>        parent_request_id,<br>        COUNT(*) AS child_count,<br>        SUM(tokens) AS child_tokens,<br>        SUM(token_credits) AS child_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>    WHERE parent_request_id IS NOT NULL<br>        AND start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>    GROUP BY parent_request_id<br>)<br>SELECT <br>    p.request_id,<br>    p.start_time,<br>    p.user_name,<br>    p.snowflake_intelligence_name,<br>    p.tokens AS parent_tokens,<br>    p.token_credits AS parent_credits,<br>    COALESCE(c.child_count, 0) AS child_request_count,<br>    COALESCE(c.child_tokens, 0) AS child_total_tokens,<br>    COALESCE(c.child_credits, 0) AS child_total_credits,<br>    p.tokens + COALESCE(c.child_tokens, 0) AS total_tokens,<br>    p.token_credits + COALESCE(c.child_credits, 0) AS total_credits<br>FROM parent_requests p<br>LEFT JOIN child_requests c ON p.request_id = c.parent_request_id<br>ORDER BY total_credits DESC<br>LIMIT 100;</pre><h3>3.9 Organization-Level Integrated Monitoring</h3><h4>ORGANIZATION_USAGE.METERING_DAILY_HISTORY</h4><ul><li><strong>Target</strong>: Consolidated costs for all AI services (service_type = &#39;AI_SERVICES&#39;)</li><li><strong>Granularity</strong>: Daily, by service type</li><li><strong>Use Case</strong>: Overall AI cost tracking at the organization level</li></ul><p>💡 Example 1: AI_SERVICES Overall Cost (Last 30 Days)</p><pre>SELECT <br>    usage_date,<br>    service_type,<br>    SUM(credits_used) AS total_credits<br>FROM SNOWFLAKE.ORGANIZATION_USAGE.METERING_DAILY_HISTORY<br>WHERE service_type = &#39;AI_SERVICES&#39;<br>    AND usage_date &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>GROUP BY usage_date, service_type<br>ORDER BY usage_date DESC;</pre><p>💡 Example 2: Monthly AI Service Cost Trends</p><pre>SELECT <br>    DATE_TRUNC(&#39;month&#39;, usage_date) AS usage_month,<br>    SUM(credits_used) AS monthly_credits<br>FROM SNOWFLAKE.ORGANIZATION_USAGE.METERING_DAILY_HISTORY<br>WHERE service_type = &#39;AI_SERVICES&#39;<br>    AND usage_date &gt;= DATEADD(month, -6, CURRENT_TIMESTAMP())<br>GROUP BY DATE_TRUNC(&#39;month&#39;, usage_date)<br>ORDER BY usage_month DESC;</pre><h3>3.8 Comprehensive Cost Report</h3><p>You can visualize costs across all Cortex features by integrating multiple views.</p><h4>💡 Example 1: Daily Cost Summary by Cortex Feature (All Services)</h4><pre>WITH ai_functions AS (<br>    SELECT <br>        DATE_TRUNC(&#39;day&#39;, usage_time) AS usage_day,<br>        &#39;AI_FUNCTIONS&#39; AS service_category,<br>        SUM(token_credits) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AISQL_USAGE_HISTORY<br>    WHERE usage_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;day&#39;, usage_time)<br>),<br>analyst AS (<br>    SELECT <br>        DATE_TRUNC(&#39;day&#39;, start_time) AS usage_day,<br>        &#39;CORTEX_ANALYST&#39; AS service_category,<br>        SUM(credits) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_ANALYST_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;day&#39;, start_time)<br>),<br>search AS (<br>    SELECT <br>        usage_date AS usage_day,<br>        &#39;CORTEX_SEARCH&#39; AS service_category,<br>        SUM(credits) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_SEARCH_DAILY_USAGE_HISTORY<br>    WHERE usage_date &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY usage_date<br>),<br>document_ai AS (<br>    SELECT <br>        DATE_TRUNC(&#39;day&#39;, start_time) AS usage_day,<br>        &#39;DOCUMENT_AI&#39; AS service_category,<br>        SUM(credits_used) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.DOCUMENT_AI_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;day&#39;, start_time)<br>),<br>cortex_agents AS (<br>    SELECT <br>        DATE_TRUNC(&#39;day&#39;, start_time) AS usage_day,<br>        &#39;CORTEX_AGENTS&#39; AS service_category,<br>        SUM(token_credits) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;day&#39;, start_time)<br>),<br>snowflake_intelligence AS (<br>    SELECT <br>        DATE_TRUNC(&#39;day&#39;, start_time) AS usage_day,<br>        &#39;SNOWFLAKE_INTELLIGENCE&#39; AS service_category,<br>        SUM(token_credits) AS daily_credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -30, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;day&#39;, start_time)<br>)<br>SELECT <br>    usage_day,<br>    service_category,<br>    daily_credits<br>FROM ai_functions<br>UNION ALL<br>SELECT usage_day, service_category, daily_credits FROM analyst<br>UNION ALL<br>SELECT usage_day, service_category, daily_credits FROM search<br>UNION ALL<br>SELECT usage_day, service_category, daily_credits FROM document_ai<br>UNION ALL<br>SELECT usage_day, service_category, daily_credits FROM cortex_agents<br>UNION ALL<br>SELECT usage_day, service_category, daily_credits FROM snowflake_intelligence<br>ORDER BY usage_day DESC, service_category;</pre><h4>💡 Example 2: Hourly Usage Pattern Analysis</h4><p>Identify peak hours for resource planning.</p><pre>WITH hourly_usage AS (<br>    SELECT <br>        DATE_TRUNC(&#39;hour&#39;, start_time) AS usage_hour,<br>        HOUR(start_time) AS hour_of_day,<br>        DAYOFWEEK(start_time) AS day_of_week,<br>        &#39;CORTEX_AGENTS&#39; AS service_type,<br>        COUNT(*) AS request_count,<br>        SUM(token_credits) AS credits<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.CORTEX_AGENT_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;hour&#39;, start_time), HOUR(start_time), DAYOFWEEK(start_time)<br>    <br>    UNION ALL<br>    <br>    SELECT <br>        DATE_TRUNC(&#39;hour&#39;, start_time),<br>        HOUR(start_time),<br>        DAYOFWEEK(start_time),<br>        &#39;SNOWFLAKE_INTELLIGENCE&#39;,<br>        COUNT(*),<br>        SUM(token_credits)<br>    FROM SNOWFLAKE.ACCOUNT_USAGE.SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY<br>    WHERE start_time &gt;= DATEADD(day, -7, CURRENT_TIMESTAMP())<br>    GROUP BY DATE_TRUNC(&#39;hour&#39;, start_time), HOUR(start_time), DAYOFWEEK(start_time)<br>)<br>SELECT <br>    hour_of_day,<br>    CASE day_of_week<br>        WHEN 0 THEN &#39;Sunday&#39;<br>        WHEN 1 THEN &#39;Monday&#39;<br>        WHEN 2 THEN &#39;Tuesday&#39;<br>        WHEN 3 THEN &#39;Wednesday&#39;<br>        WHEN 4 THEN &#39;Thursday&#39;<br>        WHEN 5 THEN &#39;Friday&#39;<br>        WHEN 6 THEN &#39;Saturday&#39;<br>    END AS day_name,<br>    service_type,<br>    AVG(request_count) AS avg_requests_per_hour,<br>    AVG(credits) AS avg_credits_per_hour,<br>    SUM(credits) AS total_credits<br>FROM hourly_usage<br>GROUP BY hour_of_day, day_of_week, service_type<br>ORDER BY hour_of_day, day_of_week, service_type;</pre><h3>4. Conclusion</h3><p>In this article, I’ve systematically organized Snowflake Cortex-related monitoring views, including the newly released features.</p><h3>📌 Key Monitoring Points</h3><ol><li><strong>AI Functions</strong>: Per-call cost analysis using CORTEX_AISQL_USAGE_HISTORY</li><li><strong>Cortex Analyst</strong>: Per-user usage monitoring with CORTEX_ANALYST_USAGE_HISTORY</li><li><strong>Cortex Search</strong>: Multi-layered monitoring with 4 views (configuration, daily, real-time, refresh)</li><li><strong>Cortex Agents</strong> ✨: Agent usage and cache efficiency analysis with CORTEX_AGENT_USAGE_HISTORY</li><li><strong>Snowflake Intelligence</strong> ✨: Instance-level monitoring with SNOWFLAKE_INTELLIGENCE_USAGE_HISTORY</li><li><strong>Organization-wide</strong>: Overall cost tracking using ORGANIZATION_USAGE.METERING_DAILY_HISTORY</li></ol><h3>🔍 Monitoring Hierarchy</h3><pre>Planning → Implementation → Operations → Analysis<br>    ↓           ↓              ↓            ↓<br>Pre-emptive   Daily         Hourly       Monthly<br>Prediction   Monitoring    Monitoring     Trends</pre><p>This multi-layer architecture enables comprehensive monitoring and management of Cortex features throughout all phases: <strong>planning → implementation → operations → analysis</strong>.</p><h3>💡 New Feature Highlight: TOKENS_GRANULAR</h3><p>The standout feature of Cortex Agents and Snowflake Intelligence is <strong>detailed token analysis through the </strong><strong>TOKENS_GRANULAR column</strong>:</p><p><strong>Analysis Capabilities</strong>:</p><ul><li><strong>By service_type</strong>: Which tools were used (cortex_agents, cortex_analyst, etc.)</li><li><strong>By model</strong>: Which AI models were used (claude-sonnet-4–5, etc.)</li><li><strong>By token type</strong>:</li><li>input: New input tokens (standard cost)</li><li>output: Output tokens (standard cost)</li><li>cache_read_input: Cache hits (<strong>90% cost reduction</strong>)</li><li>cache_write_input: Cache writes (1.25x cost, but enables future savings)</li></ul><p>This information enables <strong>quantitative measurement of prompt cache effectiveness</strong> and informed cost optimization strategies.</p><h3>🚀 Future Outlook</h3><blockquote><strong><em>Note</em></strong><em>: This article covers all Cortex services including the </em><strong><em>Snowflake Intelligence</em></strong><em> and </em><strong><em>Cortex Agents</em></strong><em> monitoring views released on February 20, 2026. These are currently offered as preview features, with further enhancements expected after general availability (GA).</em></blockquote><p>As Snowflake Cortex features continue to expand, cost management and usage visibility become increasingly important. Use the views and SQL queries introduced in this article to achieve efficient AI service operations.</p><p><em>Found this helpful? Follow me for more Snowflake tips and best practices!</em></p><img src="https://medium.com/_/stat?event=post.clientViewed&referrerSource=full_rss&postId=82c11aaac283" width="1" height="1" alt="">]]></content:encoded>
        </item>
    </channel>
</rss>