Cortex Embeddings, Vector Functions and Helper Functions

1.AI_EMBED: turning text into vectors

An embedding converts unstructured data such as text into a numeric vector, so that semantic similarity becomes geometric closeness. A help desk, for example, can find already-resolved cases that resemble a new one even when they share no keywords, because the search goes beyond keyword matching to semantic similarity.

AI_EMBED generates an embedding vector for text or image input. The vector can be used for similarity search, clustering and classification. AI_EMBED is a Cortex AI Function, so the same access controls apply as for the others. Older material uses EMBED_TEXT_768 and EMBED_TEXT_1024, where the number is the output dimension. The model you choose determines the dimension, so it has to match the VECTOR column you store into.

ALTER TABLE issues ADD COLUMN issue_vec VECTOR(FLOAT, 768);

UPDATE issues
  SET issue_vec = AI_EMBED('snowflake-arctic-embed-m', issue_text);

If you only need a similarity score between two inputs and don't want to store vectors, AI_SIMILARITY calculates the embedding similarity between two inputs in a single call.

Sources12

2.Vector functions: similarity, manipulation and aggregation

Once you have vectors, SQL vector functions work with them. They fall into three families:

- Similarity: VECTOR_INNER_PRODUCT, VECTOR_L1_DISTANCE, VECTOR_L2_DISTANCE and VECTOR_COSINE_SIMILARITY. Each takes two VECTOR arguments of equal element type and dimension and returns a metric. - Manipulation: VECTOR_TRUNCATE and VECTOR_NORMALIZE. Each takes one vector and returns a new vector, for example a truncated or normalized one. - Aggregation: VECTOR_SUM, VECTOR_MIN, VECTOR_MAX and VECTOR_AVG. These work element-wise down a column of vectors within a group.

Two details are worth remembering. The functions are optimized in a way that can reduce floating-point precision, with a margin of error up to 1e-4. And VECTOR_COSINE_SIMILARITY isn't supported in the Snowpark API, so Snowpark Python examples use functions such as vector_l2_distance instead.

A little more detail on each family. VECTOR_INNER_PRODUCT, VECTOR_L1_DISTANCE and VECTOR_L2_DISTANCE compute the inner product, the L1 distance and the L2 distance of two vectors. VECTOR_COSINE_SIMILARITY computes their cosine similarity, which is why the search examples rank it with ORDER BY ... DESC. The Snowpark example that uses vector_l2_distance sorts by the distance to put the nearest vector first.

On the manipulation side, VECTOR_TRUNCATE truncates a VECTOR to a smaller dimension. VECTOR_NORMALIZE normalizes a VECTOR in the L2 vector space so that it has a magnitude of 1. On the aggregation side, VECTOR_SUM, VECTOR_MIN, VECTOR_MAX and VECTOR_AVG compute the element-wise sum, minimum, maximum and average of the vectors in an aggregate, for example VECTOR_AVG over a group of embeddings.

SELECT a,  ? (a, [1,2,3]::VECTOR(FLOAT, 3)) AS similarity
    FROM vectors
ORDER BY similarity DESC
LIMIT 1;

Sources34

3.From vectors to answers: semantic search and RAG

Semantic search combines the pieces. First store embeddings for the documents and keep them up to date as documents change. Then embed the search term, compare it with the stored vectors using a similarity function, and use ORDER BY and LIMIT to keep the top k matches.

One performance rule: put the similarity call in the SELECT clause, not the WHERE clause. That way it runs only on rows that survive other filters, such as a date range. To filter on similarity, give the call a column alias in SELECT and test the alias in WHERE.

Retrieval-augmented generation (RAG) adds one more step. The best-matching document goes to an LLM together with the user's question, which gives the model context for its answer.

WITH result AS (
    SELECT
        w.content,
        $query AS query_text,
        VECTOR_COSINE_SIMILARITY(w.vec, q.query_vec) AS similarity
    FROM wiki w, query_table q
    ORDER BY similarity DESC
    LIMIT 1
)

-- Pass to large language model as context
SELECT AI_COMPLETE('mistral-7b',
    CONCAT('Answer this question: ', query_text, ' using this text: ', content)) FROM result;

Sources2

4.AI_COUNT_TOKENS: estimating input before you spend

AI_COUNT_TOKENS takes a function name and, where relevant, a model name, the input text, and options that affect the count, such as AI_CLASSIFY categories. It returns an INTEGER estimate of the *input* tokens. Rules to know:

- Write function and model names in lowercase. The function name must start with ai_. It doesn't work with functions in the SNOWFLAKE.CORTEX namespace or with fine-tuned models. - It accepts text only, not images, audio or video. - It incurs compute cost only and isn't billed per token. It is available in all regions, even for models that aren't available there. - For actual billed input and output tokens, use the CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY view. - With AI_COMPLETE structured output on Anthropic Claude models, billed input tokens can be materially higher than the estimate.

SELECT AI_COUNT_TOKENS('ai_sentiment',
  'This place makes the best truffle pizza in the world! Too bad I cannot afford it');

Sources5

5.TRY_COMPLETE and the text-splitting helpers

TRY_COMPLETE (SNOWFLAKE.CORTEX) does the same thing as COMPLETE, but returns NULL instead of raising an error when the operation can't be performed. That made it the safe choice for long batch jobs that use the legacy function. It is now a legacy function that will be deprecated by the end of 2026. Snowflake directs new work to AI_COMPLETE, which already returns NULL for failed rows by default.

One syntax difference matters when you migrate. In the legacy TRY_COMPLETE and COMPLETE, response_format (structured output) is a key inside the options object. In AI_COMPLETE it moves out into its own named argument, response_format, and the hyperparameters go in model_parameters. If you leave response_format inside model_parameters, it isn't recognized and the response comes back as an unstructured string.

For RAG, long documents must be split into chunks before embedding. Two helpers do this.

SPLIT_TEXT_RECURSIVE_CHARACTER splits text recursively and returns an array of chunks. It tries its separators in order: the defaults for the chosen format, or those you pass in separators. Any chunk still longer than chunk_size is split again with the next separator. overlap is optional.

SPLIT_TEXT_MARKDOWN_HEADER first splits a Markdown document on the header levels you list in headers_to_split_on, such as # and ##, then splits each section to chunk_size characters. Each chunk it returns is an object with the chunk text and the headers it falls under, so chunk boundaries follow the document's sections.

SNOWFLAKE.CORTEX.SPLIT_TEXT_RECURSIVE_CHARACTER (
  '<text_to_split>',
  '<format>',
  <chunk_size>,
  [ <overlap> ],
  [ <separators> ]
)

Sources6789

Exam traps

Each one states something that sounds right. Open it to see what is actually true.

1. 1.AI_COUNT_TOKENS predicts the full token bill for a batch.Why is that wrong?

   It estimates input tokens only. Output tokens are billed on top, and the CORTEX_FUNCTIONS_QUERY_USAGE_HISTORY view shows the actual billed counts.

   Covered in AI_COUNT_TOKENS: estimating input before you spend

2. 2.Every SQL vector function, including VECTOR_COSINE_SIMILARITY, is also available in the Snowpark Python API.Why is that wrong?

   VECTOR_COSINE_SIMILARITY isn't supported in Snowpark. Use SQL, or another metric such as vector_l2_distance, in Snowpark code.

   Covered in Vector functions: similarity, manipulation and aggregation

3. 3.TRY_COMPLETE is the recommended long-term way to make completions error-tolerant.Why is that wrong?

   TRY_COMPLETE is a legacy function that will be deprecated by the end of 2026. New work should use AI_COMPLETE.

   Covered in TRY_COMPLETE and the text-splitting helpers

Practise it for real

Build a small semantic search and RAG flow over a support-issues table using AI_EMBED, VECTOR_COSINE_SIMILARITY and AI_COMPLETE

1. 1.Run ALTER TABLE issues ADD COLUMN issue_vec VECTOR(FLOAT, 768); then UPDATE issues SET issue_vec = AI_EMBED('snowflake-arctic-embed-m', issue_text);

   Why: Stored document embeddings are the index that semantic search compares against.

   You should see: Every row has a 768-element vector in issue_vec.

2. 2.Run AI_COUNT_TOKENS('ai_embed', 'snowflake-arctic-embed-m', <a sample issue_text>) on a few representative rows.

   Why: This checks input size against the model's 512-token context window before you embed at scale.

   You should see: An INTEGER per row. It is an input-only estimate.

3. 3.SELECT issue_text and VECTOR_COSINE_SIMILARITY(issue_vec, AI_EMBED('snowflake-arctic-embed-m', 'User could not install Facebook app on his phone')) AS similarity, ORDER BY similarity DESC, LIMIT 5.

   Why: Embed the query with the same model, then rank by cosine similarity to get the top k matches.

   You should see: Five issues, most similar first, with similarity values between -1 and 1.

4. 4.Wrap the LIMIT 1 version in a CTE and call AI_COMPLETE('mistral-7b', CONCAT('Answer this question: ', <question>, ' using this text: ', issue_text)).

   Why: Passing the retrieved text to the LLM as context is the generation step of RAG.

   You should see: One generated answer based on the closest matching issue. It is NULL only if the completion fails for that row.