Documentation - FactorPrism® for Snowflake

Quick Start

Get up and running with FactorPrism® in under 5 minutes.

Enable Cortex (Required)
Go to the Privileges tab in the app and grant the CORTEX_USER database role. Snowflake Cortex powers guided setup, the Finding narrative, and investigation suggestions.
Open the App
Navigate to Apps in Snowsight and click on FactorPrism® to launch.
Start a New Finding
Open New Finding. In the Data step, connect a table or view and grant read-only access to the Snowflake object containing the metric.
Define the Question
In the Question step, choose the date field, metric, time grain, business dimensions, and comparison window.
Create the Finding
In the Finding step, name the business question and create it. FactorPrism® opens the factors behind the change, their contributions, supporting evidence, and recommended Investigation Plan.

Administrator Install Checklist

These required items match the permissions and references declared by the FactorPrism® package:

Required for interactive analysis

Install the app: Install FactorPrism® from the Snowflake Marketplace. If other account roles will launch it, grant the installed app's APP_PUBLIC application role to those roles.
Review diagnostic sharing: The package marks ERRORS_AND_WARNINGS event sharing as mandatory. USAGE_LOGS remains optional.
Enable Cortex: In the app's Privileges tab, grant the CORTEX_USER database role. This is required for the interactive Finding experience; the headless API runs the analytics engine directly without Cortex.
Bind one source: In References, bind either Source Data Table or Source Data View to the intended object. Each reference requests SELECT only. The Data step in New Finding opens the same Snowflake authorization flow.
Verify the intended role: Launch the app with an intended user role and confirm that the source shows as connected and the AI status shows as enabled.

Optional capabilities

Do not grant these unless the corresponding feature is needed:

CREATE DATABASE: only for an explicit, opt-in copy of saved sessions to a consumer-owned database. Internal application storage is the default.
EXECUTE TASK plus Monitoring Warehouse (USAGE on an existing warehouse): only for an administrator-approved recurring metric watch. FactorPrism® does not create or resize a warehouse.

Data Requirements

Your source table or view must include the following column types:

Column Type	Description	Examples
Date	Time dimension for analysis (DATE or TIMESTAMP)	ORDER_DATE, TRANSACTION_DATE, CREATED_AT
Metric	Numeric value to analyze	REVENUE, SALES_QTY, COST, COUNT
Dimensions	Categorical columns to break down by	REGION, PRODUCT_TYPE, CUSTOMER_SEGMENT, CHANNEL

Minimum Requirements

At least 2 time periods of data
At least 1 dimension column
Additive numeric metric values that can be summed (or use row count mode for counting records)
For ratios, averages, prices, rates, or snapshot balances, prepare the intended calculation in a view first

Tip: For best results, use data with at least 4-6 weeks of history and multiple dimension values per column.

Enabling Cortex

FactorPrism® is AI-native: Snowflake Cortex powers its intelligence end to end. With Cortex granted, you get:

Finding Narrative: A concise answer to "what moved and why?" at the top of each Finding
Smart Configuration: AI suggests the best date, metric, and hierarchy columns
Executive Summaries: Natural language explanations of findings
Hypothesis Generation: AI suggests possible business causes for observed patterns

How to Enable

Go to the Privileges tab in the app and grant the CORTEX_USER database role.

Note: Snowflake Cortex is required for the interactive Finding experience. Until it is granted, the app shows setup guidance. The programmatic API runs the analytics engine directly and does not use Cortex.

Cortex Availability

Snowflake Cortex is available in most regions. If you see "AI Analysis Unavailable" and the CORTEX_USER role is already granted, Claude models may not be available in your region yet — an ACCOUNTADMIN can enable cross-region inference with ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';. See the cross-region inference documentation.

Connecting Your Data

Granting Table or View Access

FactorPrism® needs read-only access to one source object. In New Finding → Data, choose a Snowflake table or curated view. Snowflake then prompts you to grant SELECT access to that specific object.

Choose the source type
Open New Finding, stay on the Data step, and choose Connect Table or Connect View. The two actions use separate package references so the selected object type is preserved.
Select the object
In Snowflake's authorization flow, navigate to the database and schema, then select the table or view you want to analyze.
Confirm read access
Review and confirm the SELECT grant. FactorPrism® shows the connected source after Snowflake completes the binding.

Security Note: Both source references request SELECT (read-only) access only. FactorPrism® cannot modify or delete the bound table or view, and all analysis runs within your Snowflake environment.

Changing Sources

To use a different object, open New Finding → Data and choose the other table or view connection. Confirm the new object in Snowflake's authorization flow.

Creating a Finding

Data: Select Your Fields

Date Field	The column containing dates or timestamps for time-based analysis
Metric Field	The numeric column to analyze (e.g., Revenue, Quantity). Select "Row Count" to count records instead.
Date Rollup	How to aggregate dates: Day, Week, Month, or Year

Question: Configure Business Dimensions

Hierarchies define how FactorPrism® groups and analyzes your data. You can create multiple hierarchy groups, each with multiple levels.

Example: Geographic + Product Hierarchy

Group 1 - Geography: Region > Country > City

Group 2 - Product: Category > Subcategory > SKU

FactorPrism® will analyze all combinations: which regions, products, or specific region-product combinations are driving changes.

Question: Select the Time Range

Choose the comparison and results periods:

Comparison Period: The baseline period (e.g., last month)
Results Period: The period to analyze (e.g., this month)

Custom Baseline (Optional)

By default, the first period of your selected window is the baseline that everything is compared against. Under Baseline period you can instead choose one or more specific periods as the baseline—the whole window is then compared to them, and several periods are averaged. This is useful for anchoring on a "normal" reference rather than a single, possibly noisy, period. The baseline must sit entirely before the analysis window—if it overlaps, the app flags it and the run is blocked, since a period can't be both the reference and an analyzed period. (This is the interactive equivalent of the baseline_period argument in the Programmatic API.)

Finding: Name and Create It

Give the business question a clear name, then click Create Finding. Analysis time depends on data volume—typically 10-60 seconds. Completed Findings return to the Findings library, where they can be searched, renamed, and pinned.

Using a Finding

Finding

The opening view leads with the current answer, followed by the business drivers ranked by impact and the next investigations suggested by the evidence:

Factor Name: The segment or combination (e.g., "Northeast > New York")
Impact: How much this factor contributed to the total change
Percentage: This factor's share of the total change

Segment-Wide Impact

When you see "Segment-Wide Impact," it means the change affected your entire selected scope uniformly. This typically indicates:

Market-wide trends
Seasonal effects
Company-wide initiatives
Economic factors

Evidence

The trend chart shows your metric over time with the analysis periods highlighted. You can:

Click and drag to select different time ranges
Hover over points to see exact values
Use the controls to zoom or pan

Investigation Plan

Every Finding includes AI-guided next steps:

Current answer: Plain-language explanation of the movement
Working hypotheses: Possible business reasons for the observed patterns
Next investigations: Focused checks to confirm or reject those hypotheses

Choose the depth you need

Finding: The factors behind the change, their contributions, top evidence, and next investigations.
Evidence: Inspect a dimension, select a segment, and drill into its factor timeline.
Compare: Put two segments from the current analysis side by side.
History: Compare the current result with an earlier compatible run to see whether the movement or leading driver shifted.

Findings library

Findings keeps completed questions as a reusable decision library. Search by question, source, or date; rename a Finding in business language; and pin important questions to the top. Backup and import controls let you carry saved work between app installations.

History checks that the source, metric, units, time grouping, plan basis, and business dimensions match before showing a comparison. A different date window is expected; a different question is not presented as a trend.

Monitoring a Finding

From an open Finding, expand Watch this finding. FactorPrism® can rerun the latest-period check on a daily, weekly, or monthly schedule and keep a history of unusual moves attached to the business question.

Automatic setup

An administrator grants the optional EXECUTE TASK privilege and chooses an existing warehouse. FactorPrism® receives USAGE on that warehouse only—it cannot create, resize, suspend, or otherwise administer the warehouse. One account-level watch is installed only after the user clicks Install automatic watch, and it can be paused from the same panel.

Administrator-reviewed SQL

If your governance process requires the task and history table to live in a consumer-owned schema, open Administrator-reviewed SQL. FactorPrism® generates the SQL using the current result's date, metric, row-count, and dimension settings; a task administrator reviews and runs it in Snowsight.

Cost boundary: scheduled checks consume the warehouse the administrator selects. Quiet periods use the lightweight verdict path and skip the deeper analysis.

Programmatic API (Headless)

The app organizes each result as a Finding for people. The API is the programmable analysis surface for SQL, Snowflake tasks, alerting pipelines, and approved agent workflows. When your own monitoring flags a spike, call the analytics engine automatically and route the structured result to whoever owns the movement.

This is the quick version. For a full reference—every parameter explained, how to structure hierarchies, the return columns, persistence, and a scheduling example—see the Headless API Reference.

Run a decomposition

API.RUN_DECOMPOSITION aggregates your bound source server-side, runs the analytics engine, and returns the ranked factor/contribution table. The app organizes that output as a human-facing Finding with evidence navigation, a plan, and history.

CALL FACTORPRISM.API.RUN_DECOMPOSITION(
  source_ref      => 'SOURCE_VIEW',   -- 'SOURCE_TABLE' or 'SOURCE_VIEW'
  date_field      => 'ORDER_DATE',
  metric_field    => 'REVENUE',        -- or NULL with use_row_count => TRUE
  use_row_count   => FALSE,
  rollup          => 'WEEK',           -- DAY | WEEK | MONTH | YEAR
  hierarchies     => PARSE_JSON('[["REGION","DIVISION","STATE"],["CATEGORY","PRODUCT"],["CHANNEL"]]'),
  period_start    => '2025-01-06',
  period_end      => '2025-06-30');
  -- baseline_period and persist are optional and can be omitted

Monitor with `RUN_VERDICT`

API.RUN_VERDICT (version 5.4+) is the one-row companion for scheduled monitoring: it judges whether the latest period's move is unusual against the metric's own typical period-to-period swing. Quiet periods answer "steady" from a single aggregate query—no full analysis—so alerting becomes one predicate:

CALL FACTORPRISM.API.RUN_VERDICT();   -- zero arguments; columns detected automatically
SELECT MODE, SENTENCE, LEAD_FACTORS
FROM   TABLE(RESULT_SCAN(LAST_QUERY_ID()))
WHERE  MODE NOT IN ('steady','flat'); -- zero rows on a quiet week

It returns MODE, a plain-language SENTENCE, the percent change and the typical swing it was judged against, the compared window, and the lead factors as JSON. Full column reference in the Headless API Reference.

Choosing a baseline

The baseline_period is the reference the window is compared against, and is optional:

Omitted (NULL) — the first period of the analysis window is the baseline.
A single date — that period is the baseline; the entire window is compared to it.
Several dates (a comma-separated list or a JSON array) — those periods are averaged into the baseline, useful for comparing against a "normal" reference rather than a single, possibly noisy, period.

Fetch a saved run

Every run is also saved to APP_RESULTS.SAVED_SESSIONS (and can be reopened in the app). Fetch the ranked drivers later, or point a BI tool at this query:

SELECT d.value:FACTOR::string                     AS factor,
       d.value:NET_CONTRIBUTION_PER_PERIOD::float AS net_contribution,
       d.value:SHARE_OF_NET_CHANGE_PCT::float     AS share_pct
FROM   FACTORPRISM.APP_RESULTS.SAVED_SESSIONS s,
       LATERAL FLATTEN(input => s.session_blob:headless_drivers) d
WHERE  s.session_id = '<id from your run>'
ORDER  BY d.value:RANK::int;

Performance: aggregation runs in the warehouse of the calling session and only the aggregated result is materialized. For very large inputs, call the procedure on a Snowpark-optimized warehouse so the analysis has ample memory.

Security & Privacy

Data Protection

Your data stays in your account: FactorPrism® runs entirely within your Snowflake environment
No data extraction: We never copy or transmit your data outside Snowflake
Read-only access: We only request SELECT permissions—we cannot modify your data
Server-side processing: All computation happens via Snowpark within Snowflake's secure infrastructure

Results Storage

Analysis results are stored in tables within the FactorPrism® application schema by default. An optional CREATE DATABASE grant is used only when an administrator explicitly chooses to copy saved sessions to a consumer-owned database.

Diagnostic sharing

The package requires Snowflake's ERRORS_AND_WARNINGS event-sharing level; USAGE_LOGS is optional. Product usage events do not include source rows or analysis-result values. Optional usage events use fixed, data-free categories rather than source names, column names, values, factor labels, SQL, or feedback notes.

Optional monitoring access

Interactive analysis does not require task privileges. Automatic monitoring separately requests EXECUTE TASK and a warehouse reference with USAGE only. Both are optional, explicitly approved by the consumer, and used only after a watch is installed. The administrator-reviewed SQL route remains available without granting task execution to the app.

AI Features

When using Cortex AI features, your data is processed by Snowflake's Cortex service, which operates within Snowflake's security boundary. No data is sent to external AI providers.

For our complete privacy policy, see Privacy Policy.

Troubleshooting

Common Issues

Issue	Solution
"No significant factors found"	Ensure your date range spans multiple periods Try a broader rollup (weekly instead of daily) Check that your metric has meaningful variation
"AI Analysis Unavailable"	Grant CORTEX_USER role (see Enabling Cortex) If the role is granted, enable cross-region inference: `ALTER ACCOUNT SET CORTEX_ENABLED_CROSS_REGION = 'ANY_REGION';` The interactive Finding experience requires Cortex; the headless API does not
"Unable to connect to table or view"	Verify the table or view exists and you have `SELECT` access Check that the object is in an accessible database and schema Use New Finding → Data to grant access again
Analysis runs slowly	Use weekly or monthly rollups instead of daily Reduce the number of hierarchy levels Narrow the date range

Support

We're here to help you get the most out of FactorPrism®.

Contact Us

Email: info@factorprism.com
Bug reports and feature requests: Email public support

Additional Resources

How FactorPrism® Works - Learn about the science behind driver discovery
Privacy Policy - How we handle your data

FactorPrism® Documentation

Table of Contents