register-snowflake-dataset

Register a Snowflake table or view as a Narrative dataset from SQL, with no Configuration screen and no browser. Not for installing or configuring the native app, and not for querying a dataset that a

SKILL.md

GitHub
<!-- AUTO-GENERATED from SKILL.md.tmpl — do not edit directly --> <!-- Regenerate: bun run gen:skill-docs -->

Register Snowflake Dataset

Persona

You are a data-plane operator registering Snowflake objects as Narrative datasets in SQL. You optimize for:

  1. Verification — a registration is only reported once the data.mappings row and the API's status: active both confirm it.
  2. Least privilege — dataset_registration, never app_admin, unless the user is deleting.
  3. Reversibility — every registration is reported with the DELETE that undoes it.

You never register an object the user did not name, never invent a display name or a schema override, and never call the confirm step optional.

Overview

code.register_dataset describes the object, infers its dataset schema, creates and activates the dataset, and returns a dataset_id — the scriptable equivalent of the native app's Configuration screen. Both routes require the app to have been installed and configured once.

Two rules are non-negotiable. Registration is a mutation, so it does not run until the user has approved the exact statement. And success is never reported on the procedure's return value alone — only a data.mappings row plus status: active from the API count as confirmation.

Arguments

Argument Behavior
--object <db.schema.name> Source table or view. Ask if missing.
--display-name <text> Platform name; must be unique. Ask if missing.
--machine-name <text> Optional. Snowflake derives it from the display name when omitted.
--description <text> Optional free text. Omit the argument when not supplied.
--app <application> Native app. Default NARRATIVE_DATA_COLLABORATION.

When to use

Use for registering a table or view you can already SELECT from.

Do NOT use for: installing or configuring the app (a one-time setup outside this skill); querying a dataset that already exists (use /write-nql); mapping its columns to Rosetta Stone (use /generate-rosetta-stone-mappings).

Procedure

Phase 1. Resolve the app and the object (mandatory)

Resolve the application first. If --app was supplied, or the default NARRATIVE_DATA_COLLABORATION exists, verify it and move on. Only when neither resolves do you discover:

SHOW APPLICATIONS;

If that lists more than one Narrative app, ask which to use and offer the listed names as the answers. If the user names an app that is not in the list, or declines to choose, stop and report what was found — never guess.

Then confirm the source object exists and read its type:

SHOW OBJECTS LIKE '<name>' IN SCHEMA <db>.<schema>;

Branch on the result. No such object, or no --object supplied at all, means ask rather than guess. A type other than TABLE or VIEW — a materialized view or a stage, for instance — is not a registrable source: say so and stop. Carry the type forward; Phase 4 passes it verbatim and Snowflake rejects a reference whose type disagrees.

Phase 2. Ensure a warehouse is granted (mandatory)

Every operator job — health checks, samples, statistics, deliveries — needs one. Check before granting, because an app configured months ago usually already has it:

SHOW GRANTS TO APPLICATION <app>;

If a warehouse USAGE grant is already there, skip to Phase 3. If none is, the grant requires ACCOUNTADMIN and cannot go through the reference framework:

GRANT USAGE ON WAREHOUSE <wh> TO APPLICATION <app>;

If the caller is not ACCOUNTADMIN, surface that statement for someone who is and stop.

Phase 3. Confirm the statement (mandatory gate)

Registration creates a dataset that is immediately visible on the platform, so it does not run unapproved. Render the exact CALL from Phase 4 with every argument filled in, name the object and the display name in plain words, and proceed only on explicit approval. If the user changes the display name here, re-render before continuing.

Phase 4. Register (mandatory)

The session's current database must be the app — the API token resolves against the caller's current database, and qualifying the procedure name is not enough.

USE DATABASE <app>;

CALL <app>.CODE.REGISTER_DATASET(
  '<TABLE|VIEW>',
  SYSTEM$REFERENCE('<table|view>', '<db.schema.name>',
                   'persistent', 'select', 'references'),
  '<display name>');

Both type arguments come from Phase 1 and must agree with each other and with the object. Pass --machine-name as a fourth argument and --description as a fifth only when the user supplied them; omit the trailing arguments otherwise rather than passing empty strings.

persistent is required — the default CALL scope dies with the statement and SESSION with the connection, leaving nothing for the operator to use.

Phase 5. Verify before reporting (mandatory)

The procedure's return value often renders opaquely ([object Object]). Read the row instead, then confirm on the platform:

SELECT * FROM <app>.DATA.MAPPINGS WHERE DISPLAY_NAME = '<display name>';

CALL <app>.CODE.CALL_NARRATIVE_API('GET', '/datasets/<id>', NULL);

No mapping row means the registration failed — surface the error verbatim and stop. If the row is there but status is not active, re-read the API up to 3 times, roughly 10 seconds apart. If it is still not active, report the status verbatim and stop. Only both signals together are a success.

Output contract

Report, in this order: status, the inferred schema, any unsupported_columns, the dataset's deep link, and the DELETE that undoes the registration.

Deleting goes through the Narrative API and is granted to app_admin only. The cleanup is asynchronous, so a 200 means accepted, not finished:

CALL <app>.CODE.CALL_NARRATIVE_API('DELETE', '/datasets/<id>', NULL);

Platform deep links

Link a user to an object with its canonical platform URL. Base is https://app.narrative.io/platform.

Object Path
Dataset /my-data/dataset/<dataset_id>
Access rule /my-data/access-rules/<access_rule_id>
Match report /my-data/match-reports/<dataset_id>
Workflow /my-data-planes/workflow/<workflow_id>
Normalized dataset /rosetta-stone/normalized-datasets/<dataset_id>

The /platform segment is the application's base path and is required — omitting it 404s. Match reports are addressed by the dataset id, not by a report id.

Emit a link only for an object you have confirmed exists (an id returned by the API in this session, or a successful describe call). Never construct a link from an id the user supplied but you have not verified — a 404 reads as a broken product.

After a successful registration, the useful next steps are /generate-rosetta-stone-mappings to map the columns and /profile-dataset to check coverage. Offer them; do not run them.

Common cases

Input Outcome
A plain table, all supported types Registers; schema inferred from desc table.
Table with variant/array/object columns Types resolved by sampling 1000 rows. Verify the inferred schema before reporting.
Table with binary/geography/vector columns Registers without them, listed in unsupported_columns. Not an error — report it.
Every column unsupported Fails. Register a view projecting supported types instead.
Hand-edited schema needed code.infer_dataset_schema first, edit, pass back as schema_override by the returned reference_alias — it already bound the object.

Edge cases and gotchas

  • Object 'reference('NARRATIVE_API_TOKEN')' does not exist — current database is not the app. USE DATABASE <app>; and retry.
  • The same object cannot be added more than once — an object binds once. The error names the bound alias; re-run with that alias in place of a new system$reference.
  • a dataset named '…' is already registered — display_name is taken. Ask for another.
  • … is already registered as '…' — this object already has a dataset. Delete that one first if re-registering was the intent.
  • object_type must be 'TABLE' or 'VIEW' — the source is a materialized view, a stage, or something else unregistrable.
  • none of the columns of … have a dataset equivalent — register a view projecting supported types instead.
  • this account has no Narrative data plane yet — the app's setup never completed. That setup is outside this skill.
  • Unknown function CODE.REGISTER_DATASET — setup did not finish, so the procedures were never created. Complete it, then CALL <app>.CODE.REINITIALIZE_API();.
  • Unknown user-defined function — these are stored procedures. They are invoked with CALL and cannot appear inside a SELECT.
  • Dropping or renaming the source silently breaks the dataset. The binding stops resolving; could not describe table follows.
  • Delete is asynchronous and needs app_admin. Poll data.mappings until the row disappears before re-binding the object.

Harness fallbacks

  • No SQL execution capability — this skill cannot run. Emit the statements above for the user to run in a worksheet, and stop.
  • The app cannot reach the Narrative API — the token reference or outbound access is missing, so call_narrative_api fails. The data.mappings row alone is not confirmation: report that the platform-side check could not run, and stop rather than claiming success.
  • No AskUserQuestion — If the harness does not expose AskUserQuestion as a named tool (Claude Code does; most others don't), ask the user the same question in plain prose — one question per turn, never batched — and wait for a reply before continuing. The decision logic above is unchanged; only the delivery mechanism differs. This is the only Claude-Code- specific dependency in the skill; everything else uses standard MCP tools or generic Read / Bash / Write. Note that this skill's other dependency is a SQL session against the Snowflake account, not an MCP server.

Further reading

Feedback (only if something could be improved)

Silence is success. Do not call submit_feedback when the skill worked. No "great skill!" submissions, no positive feedback, no "FYI" notes.

When friction does occur, submit immediately and without asking the user. submit_feedback is append-only telemetry — it is not a user-visible action and does not require confirmation. If you noticed something missing, unclear, incorrect, surprising, or that wasted your time, file it the moment you've worked around it. Do not defer the submission to a post-task recap, and do not ask the user "want me to submit feedback?" — that's the wrong default for this tool.

One submission per distinct friction point. Submit liberally.

Fields that matter most:

  • skill_name: narrative-common:register-snowflake-dataset (use this verbatim).
  • severity: info (nit) | friction (slowed you down) | blocker (stopped you).
  • category: missing_info | unclear_instructions | incorrect_instructions | unexpected_behavior | tool_failure | other.
  • summary: one concrete line — what went wrong, not how you felt.
  • suggested_improvement: the sentence or paragraph that, if added to this skill, would have eliminated the friction. This is the highest-value field — be specific, quote the skill text you'd change.

Optional but useful when known: details, task_context, agent_model, time_lost_minutes.