Snowflake Native App

Overview

The Snowflake Native App installs as a customer-hosted data plane within your Snowflake environment. It runs the operator component that bridges Narrative’s control plane with your Snowflake data—polling for jobs, executing NQL queries, and returning results, all without your data leaving your Snowflake account.

Capabilities

Register Snowflake tables and views as Narrative datasets
Register one or more Snowflake warehouses as compute pools
Execute NQL queries directly in your Snowflake environment
Participate in cross-data-plane data collaboration
Keep data within your Snowflake security perimeter

Requirements

Requirement	Details
Snowflake role	ACCOUNTADMIN or equivalent
Narrative account	Required (create account)
API token	With specific permissions (see below)
Snowflake warehouse	For query execution
Marketplace access	Access to the Narrative listing on the Snowflake Marketplace

Privileges

The app requires the following Snowflake privileges:

Privilege	Purpose
`EXECUTE TASK`	Schedule and run jobs on behalf of Narrative’s control plane
`CREATE COMPUTE POOL`	Provision compute resources for query execution
`BIND SERVICE ENDPOINT`	Communicate with Narrative’s control plane API

Registering warehouses as compute pools

To register a Snowflake warehouse as a compute pool, grant the app usage on the warehouse:

GRANT USAGE ON WAREHOUSE <warehouse_name> TO APPLICATION NARRATIVE_DATA_COLLABORATION;

You can register multiple warehouses to separate workloads across different compute pools.

API token permissions

Your Narrative API token must include the following permissions:

Permission	Access level
Compute Pools	Read and Write
Data Planes	Read and Write
Data Plane Logs	Read and Write
Datasets	Read and Write
Jobs	Read and Write
Models	Read

See API Keys for instructions on creating and managing tokens.

Registering datasets

A Snowflake table or view becomes a Narrative dataset by either of two routes, which produce the same result:

The app’s Configuration screen, covered in the installation guide
The code.register_dataset stored procedure, callable from a worksheet, the Snowflake SQL API, or a task — see Register a Snowflake dataset from SQL

Registration requires the dataset_registration application role, which carries the registration procedures and nothing else, or app_admin, which holds it. Either way the app must already have its external access integration, API token, and at least one granted warehouse.

Dataset naming conventions

When you name a dataset on the Configuration screen, the name must use:

Uppercase letters only (A–Z)
Numbers (0–9)
Underscores (_)

For example: MY_DATASET_NAME, CUSTOMER_EVENTS_2024. Registering from SQL takes a human-readable display_name and derives the machine name from it, replacing every non-word character with an underscore, so 'My Events' becomes My_Events. Pass dataset_name explicitly to set it yourself.

Registration errors

Both code.register_dataset and code.infer_dataset_schema fail with a named message rather than a generic error.

Message	Meaning
`Object 'reference('NARRATIVE_API_TOKEN')' does not exist or not authorized`	The session’s current database is not the application. Run `use database narrative_data_collaboration;` and call again. Qualifying the procedure name is not enough — only the current database counts.
`object_type must be 'TABLE' or 'VIEW'`	Materialized views, stages and the like are not registrable sources.
`a dataset named '…' is already registered`	`display_name` is taken.
`… is already registered as '…'`	This object already has a dataset. Delete that one first if you meant to re-register.
`could not describe table …`	The binding no longer resolves: the reference was removed, or the object it pointed at is gone.
`'…' is not a bound SOURCE_TABLE reference`	The alias passed is not bound. The message lists the ones that are.
`could not bind the SOURCE_TABLE reference`	Usually the object is already bound. The message lists the bound alias and name pairs, so re-run with the alias of the one you meant.
`this account has no Narrative data plane yet`	The application’s setup has not been completed. See Install the Snowflake Native App.
`none of the columns of … have a dataset equivalent`	Every column was unsupported. Register a view that projects supported types instead.

Installation

For step-by-step installation instructions, see Install the Snowflake Native App.

Installation Guide

Step-by-step setup instructions

Data Planes

Understand how data planes and operators work

Execution Context

Learn how queries are executed across data planes

API Keys

Manage API tokens and permissions

Overview

Connectors

Integrations

Workflow Reference

Webhook Reference

Security Reference

Architecture Reference

Error Reference

API Policies

Deprecations

Model Inference Reference

Rosetta Stone Reference

UI Reference

SDKs

Glossary

Billing

Overview

Capabilities

Requirements

Privileges

Registering warehouses as compute pools

API token permissions

Registering datasets

Dataset naming conventions

Registration errors

Installation

Installation Guide

Data Planes

Execution Context

API Keys

​Overview

​Capabilities

​Requirements

​Privileges

​Registering warehouses as compute pools

​API token permissions

​Registering datasets

​Dataset naming conventions

​Registration errors

​Installation

​Related content

Installation Guide

Data Planes

Execution Context

API Keys

Overview

Capabilities

Requirements

Privileges

Registering warehouses as compute pools

API token permissions

Registering datasets

Dataset naming conventions

Registration errors

Installation

Related content