Register a Snowflake Dataset from SQL

code.register_dataset registers a Snowflake table or view as a Narrative dataset in code, without launching the Native App’s Configuration screen — from a worksheet, the Snowflake SQL API, or a scheduled task. Use it to script dataset onboarding, or to run it from the pipeline that already builds the table. The Configuration screen is unchanged and is still the simplest way to register your first dataset. Both routes produce the same dataset, and both depend on the app having been installed and configured once — see Install the Snowflake Native App for that setup.

Prerequisites

The Snowflake Native App installed, with its external access integration and API token configured. These also create the Narrative data plane the dataset attaches to.
At least one warehouse granted to the application, because every job the operator later runs against the dataset — health checks, samples, statistics, deliveries — needs one. This grant cannot be requested through Snowflake’s reference framework and has to be run by an ACCOUNTADMIN:
grant usage on warehouse my_warehouse to application narrative_data_collaboration;
The dataset_registration application role, or app_admin.

Grant the registration role

dataset_registration carries usage on the two registration procedures and read access to the app’s mapping table, and nothing else. The procedures run with owner’s rights, so a caller needs no privilege on the source object, the API token, or the app’s own state.

grant application role narrative_data_collaboration.dataset_registration to role my_role;

app_admin also works, since it holds dataset_registration. Prefer the smaller role for anyone whose job is registering datasets — app_admin additionally grants full write access to the application’s state, every function it exposes, and its compute pools and services.

Neither role confers anything in your account outside the application, and neither can read your tables. Access to your own objects is granted separately, per object, as described next.

Register a table or view

code.register_dataset describes the object, derives its schema, creates and activates the dataset, and returns the new dataset_id. There are two ways to give it the source object.

By reference (recommended)
By fully qualified name

system$reference mints a token that binds the object through Snowflake’s reference framework. Nothing is granted to the application, Snowflake lists the binding among the app’s references, and deleting the dataset unbinds it again.

call narrative_data_collaboration.code.register_dataset(
  'TABLE',
  system$reference('table', 'mydb.myschema.events', 'persistent', 'select', 'references'),
  'My Events'
);

The nested arguments matter:

Argument	Meaning
`'table'`	Snowflake’s own object-type check. Must agree with the first argument to `register_dataset`.
`'mydb.myschema.events'`	The object, resolved with your privileges.
`'persistent'`	The reference scope. The default, `CALL`, expires when the statement ends, and `SESSION` dies with the connection. Only `PERSISTENT` survives for the operator to use later.
`'select', 'references'`	The privileges handed to the app: `select` to read rows, `references` for the metadata that health checks read.

system$reference runs as your role, so you need select and references on the object to call it.

Granting the application access directly works too. The trade-off is that the grant is then ordinary Snowflake state: it can be revoked out of band without the app noticing, and there is no binding for Snowflake to show alongside the application’s other references.

grant usage on database mydb to application narrative_data_collaboration;
grant usage on schema mydb.myschema to application narrative_data_collaboration;
grant select, references on table mydb.myschema.events to application narrative_data_collaboration;

call narrative_data_collaboration.code.register_dataset(
  'TABLE', 'MYDB.MYSCHEMA.EVENTS', 'My Events');

The name must be exactly three identifier parts. Unquoted parts are upper-cased, matching how Snowflake resolves them; quote a part to preserve its case (mydb.myschema."My Events").

An object can only be bound once per reference. A second system$reference for the same table is rejected with “The same object cannot be added more than once” — including when the Configuration screen bound it. To register an object that is already bound, pass its alias in place of the reference:

call narrative_data_collaboration.code.register_dataset(
  'VIEW', '5408228b-28cf-4993-a73b-f65f3ec94f14', 'My Events');

To register the same table as a second dataset, address it by name rather than by reference.

Arguments

Argument	Required	Description
`object_type`	Yes	`'TABLE'` or `'VIEW'`, matching what the object actually is — Snowflake rejects a reference whose object type disagrees. Case and surrounding whitespace are ignored.
`source`	Yes	The object to register: a `system$reference` token, a fully qualified name, or a bound alias.
`display_name`	Yes	The dataset’s human-readable name on the platform. Must be unique among registered datasets. The check runs before anything is bound, so a clash cannot leave a stray reference behind.
`dataset_name`	No	The dataset’s machine name. Defaults to `display_name` with every non-word character replaced by an underscore, truncated to 256 characters — `'My Events'` becomes `My_Events`.
`description`	No	Free text stored on the dataset.
`schema_override`	No	A dataset schema to use instead of the inferred one. See Override the inferred schema.

What it returns

Field	Description
`dataset_id`	The dataset’s id on the Narrative platform.
`name`, `display_name`	As registered.
`external_id`	How Narrative addresses the object — either a reference or the qualified name.
`reference_alias`	The alias the reference was bound under, or the qualified name when there is no reference.
`source_kind`	How `source` was interpreted: `reference`, `alias`, or `name`. Worth checking on a first call.
`table_or_view`	`table` or `view`.
`schema`	The schema that was sent.
`unsupported_columns`	Columns left out because their Snowflake type has no dataset equivalent — `binary`, `geography`, `geometry`, `vector` and the like.

unsupported_columns is not an error. The dataset registers without those columns, so check this field if a column you expected is missing downstream.

Override the inferred schema

By default the schema comes from desc table or desc view, with variant, array and object columns resolved by sampling 1000 rows. code.infer_dataset_schema returns what register_dataset would infer, without creating anything:

call narrative_data_collaboration.code.infer_dataset_schema('TABLE', 'MYDB.MYSCHEMA.EVENTS');

infer_dataset_schema takes object_type and source exactly as register_dataset does, which means passing a system$reference token here will bind the reference. Pass a qualified name or an already-bound alias when you only want to look.

Edit what it returns and pass it back as schema_override. Inference is then skipped entirely, including the sampling:

call narrative_data_collaboration.code.register_dataset(
  'TABLE',
  'MYDB.MYSCHEMA.EVENTS',
  'My Events',
  'my_events',
  'Events from our warehouse',
  parse_json('{"type":"object","properties":{"ID":{"type":"string"},"COUNT":{"type":"long"}}}')
);

The format is Narrative’s dataset schema: an object whose properties map column names to types, where a type is one of string, long, double, boolean, timestamptz, {"type":"array","items":…}, or {"type":"object","properties":{…}}. Property names must match the column names Snowflake reports, which are upper-case unless the column was created quoted. Do not include file_config — the procedure adds it.

Errors

The procedure validates before it changes anything, and every failure names its remedy.

Message	Meaning
`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. Checked first, before any reference is bound.
`… is already registered as '…'`	This object already has a dataset. Delete that one first if you meant to re-register.
`could not describe table …`	For a qualified name, the application has not been granted access, and the message lists the three `grant` statements to run. For a reference or alias, the binding no longer resolves.
`'…' 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 external access integration and API token steps have not been completed.
`none of the columns of … have a dataset equivalent`	Every column was unsupported. Register a view that projects supported types instead.

Troubleshooting

Unknown function CODE.REGISTER_DATASET

The procedure is created once the external access integration is bound, and recreated on every app upgrade. If it is missing, the integration or the API token is not configured. Configure them, then force the pass:

call narrative_data_collaboration.code.reinitialize_api();

This returns external access integration not available if the integration still is not bound.

Unknown user-defined function

Everything here is a stored procedure, so it is invoked with CALL and cannot be used inside a SELECT expression. Snowflake reports that as Unknown user-defined function, which reads like the procedure is missing when it is only being called the wrong way.

A registered dataset stops working after the source is dropped or renamed

The dataset keeps pointing at the old object. Remove it and register the replacement.

Remove a dataset

Removing a dataset goes through the Narrative API. code.call_narrative_api calls it with the account’s configured token, and is granted to app_admin only:

call narrative_data_collaboration.code.call_narrative_api('DELETE', '/datasets/12345', null);

The operator then removes the app’s mapping, and the reference too if there was one. The same procedure inspects a dataset:

call narrative_data_collaboration.code.call_narrative_api('GET', '/datasets/12345', null);

select parse_json(CALL_NARRATIVE_API) from table(result_scan(last_query_id()));

Install the Snowflake Native App

One-time setup, and registering a dataset through the Configuration screen

Snowflake Native App Reference

Capabilities, requirements, privileges, and naming conventions

Data Planes

How a customer-hosted data plane executes work

Compute Pools

The warehouses that run jobs against your registered datasets

Overview

Platform

Data Ingestion

Data Planes

Querying with NQL

Data Collaboration

Identity Resolution

Data Activation

Audience Studio

Connectors

Compliance

Rosetta Stone

Account Settings

Workflows

Webhooks

Data Collaboration MCP Server

Tools

SDKs

Prerequisites

Grant the registration role

Register a table or view

Arguments

What it returns

Override the inferred schema

Errors

Troubleshooting

Remove a dataset

Install the Snowflake Native App

Snowflake Native App Reference

Data Planes

Compute Pools

​Prerequisites

​Grant the registration role

​Register a table or view

​Arguments

​What it returns

​Override the inferred schema

​Errors

​Troubleshooting

​Remove a dataset

​Related content

Install the Snowflake Native App

Snowflake Native App Reference

Data Planes

Compute Pools

Prerequisites

Grant the registration role

Register a table or view

Arguments

What it returns

Override the inferred schema

Errors

Troubleshooting

Remove a dataset

Related content