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. If you have not registered a dataset this way before, Register Your First Snowflake Dataset walks one table through end to end. This page is the reference for the procedures themselves.

Prerequisites

The Snowflake Native App installed and configured. That setup creates 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.
A session whose current database is the application. These procedures read the Narrative API token through a reference that resolves against the caller’s current database, not the procedure’s, so every example below opens with use database narrative_data_collaboration;.

Grant the registration role

dataset_registration carries usage on the two registration procedures and read access to data.mappings, where the application records what it has registered. Nothing else. The procedures run with owner’s rights, so a caller needs no privilege on the application’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. The application reaches a source object only through the reference you mint for it, one object at a time.

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. The source object is passed as a system$reference, which binds it 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.

use database narrative_data_collaboration;

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. An object can be bound only once, so a second system$reference for a table that is already bound is rejected. data.mappings records what this application has registered, and the dataset_registration role can read it:

select * from narrative_data_collaboration.data.mappings;

Arguments

Argument	Required	Description
`object_type`	Yes	`'TABLE'` or `'VIEW'`, matching what the object actually is — Snowflake rejects a reference whose object type disagrees.
`source`	Yes	The object to register: a `system$reference` token, or the alias of a reference that is already bound.
`display_name`	Yes	The dataset’s human-readable name on the platform. Must be unique among registered datasets.
`dataset_name`	No	The dataset’s machine name. Defaults to `display_name` with anything that is not a letter, number or underscore replaced by an underscore — `'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.
`reference_alias`	The alias the reference was bound under.
`source_kind`	How `source` was interpreted: `reference` or `alias`. Worth checking on a first call.
`table_or_view`	`table` or `view`.
`schema`	The schema the dataset was registered with.
`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 — the schema, unsupported_columns, and the reference_alias — without creating the dataset:

use database narrative_data_collaboration;

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

infer_dataset_schema binds the reference, exactly as register_dataset does, and an object can be bound only once. The registration that follows must therefore address the object by the reference_alias this call returns. Minting a second system$reference for the same object fails with The same object cannot be added more than once.

Edit the schema it returns and pass it back as schema_override, addressing the object by that reference_alias. Inference is then skipped entirely, including the sampling:

use database narrative_data_collaboration;

call narrative_data_collaboration.code.register_dataset(
  'TABLE',
  '5408228b-28cf-4993-a73b-f65f3ec94f14',
  '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

Every failure names its remedy. The full list of messages and what each one means is in the Snowflake Native App reference.

Troubleshooting

Unknown function CODE.REGISTER_DATASET

The registration procedures are created when the application’s setup completes. If register_dataset is missing, that setup has not finished. Complete it, then:

use database narrative_data_collaboration;

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. This procedure is granted to app_admin only:

use database narrative_data_collaboration;

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

The application then removes its own mapping row and unbinds the reference, so the source object is free to register again. That cleanup is asynchronous: the 200 means the delete was accepted, not that it has finished. If you are scripting delete-then-re-register, poll narrative_data_collaboration.data.mappings until the row disappears before binding the object again.

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

Connector APIs

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