/register-snowflake-dataset

name: register-snowflake-dataset
description: |
  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
  already exists.
  Use when: "register this table as a dataset", "register a Snowflake
  dataset from SQL", "onboard my_table to Narrative", "script dataset
  registration", "add this view to my data plane".
  (narrative-common)
license: MIT
compatibility: >-
  Requires a way to execute SQL against the Snowflake account hosting
  the Narrative native app — Bash with a Snowflake client, or an
  equivalent capability — as a role holding dataset_registration plus
  SELECT and REFERENCES on the source object. The application itself
  needs a granted warehouse and outbound access for its Narrative API
  token. Recommends AskUserQuestion, a Claude Code primitive with a
  prose fallback documented in the body.
metadata:
  version: 0.1.0
  narrative:
    args:
      - name: "--object"
        value: "<db.schema.name>"
        required: false
        description: >-
          Fully qualified source table or view. If omitted, the skill asks.
      - name: "--display-name"
        value: "<text>"
        required: false
        description: >-
          Dataset name on the platform. Must be unique among registered
          datasets. If omitted, the skill asks — it is never invented.
      - name: "--machine-name"
        value: "<text>"
        required: false
        description: >-
          The dataset's machine name. Optional; Snowflake defaults it to
          the display name with every character that is not a letter,
          number or underscore replaced by an underscore.
      - name: "--description"
        value: "<text>"
        required: false
        description: >-
          Free text stored on the dataset. Omitted when not supplied.
      - name: "--app"
        value: "<application>"
        required: false
        default: NARRATIVE_DATA_COLLABORATION
        description: >-
          The installed native app. Verified before use; discovered with
          SHOW APPLICATIONS only when the default does not resolve.
    requires:
      tools:
        - Bash
    recommends:
      skills:
        - narrative-common:generate-rosetta-stone-mappings
        - narrative-common:profile-dataset
      tools:
        - AskUserQuestion

<!-- 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