Native App Framework: Build & Distribute Declarative Apps

Imagine you've built a powerful data pipeline that cleans and transforms raw data into actionable insights. You want to share this pipeline with other teams or even external customers, but they don't have your exact setup. Traditionally, you'd have to export data, write documentation, and hope they can replicate your environment. Snowflake Native Apps change that: you can package your entire application—including logic, user interfaces, and data—into a single entity that runs inside Snowflake, leveraging Snowflake's compute and security.

The Snowflake Native App Framework, especially with the Declarative Apps paradigm, allows you to define your app using SQL and YAML manifests. This approach reduces boilerplate code and lets you focus on the business logic. In this tutorial, you'll learn how to build a declarative Snowflake Native App from scratch, deploy it, and distribute it via the Snowflake Marketplace. We'll cover the architecture, step-by-step creation, debugging in production, and common pitfalls. By the end, you'll be able to create your own native apps that can be shared securely and efficiently.

Understanding Snowflake Native App Architecture

Snowflake Native Apps are built on the concept of an Application Package, which is a container that holds all the components of the app: the manifest, setup script, stored procedures, Streamlit UIs, and any other artifacts. The app runs in a consumer's Snowflake account but is managed by the provider. The key components are:

• Provider Account: The account where the app is developed and from which it is shared or published.
• Application Package: A versioned collection of the app's files. It can be shared with consumer accounts or published on the Marketplace.
• Manifest (manifest.yml): A YAML file that defines the app's metadata, required privileges, and references to other files.
• Setup Script: A SQL script that runs when the app is installed. It creates the app's objects (e.g., schemas, tables, procedures) within the app's sandbox.
• App Roles: Roles defined in the setup script that control access to app objects.
• Streamlit App: Optional UI component for interactive dashboards.

The Declarative Apps framework simplifies this by allowing you to define the app's behavior using SQL and YAML without writing complex code. The manifest declares what the app needs, and Snowflake handles the rest.

manifest_version: 1
name: my_app
version: "1.0"
label: "My First Native App"
description: "A simple app that transforms data."
privileges:
  - USAGE
  - SELECT
references:
  - name: my_shared_data
    label: "Shared Data"
    description: "A database shared by the provider."
    privileges:
      - IMPORTED PRIVILEGES
setup_script: setup.sql
streamlit_apps:
  - name: my_dashboard
    stage: app_src
    main: dashboard.py

Setting Up Your Development Environment

To build a Snowflake Native App, you need a Snowflake account with the ACCOUNTADMIN role (or a role with CREATE APPLICATION PACKAGE privilege). You'll also need a stage to upload your app files. Here's how to set up:

1. Create a new database and schema for your app development.
2. Create a stage (internal or external) to store your app files.
3. Create an application package using SQL.
4. Upload your manifest, setup script, and any other files to the stage.
5. Alter the application package to add a version.

Let's walk through an example. We'll create a simple app that reads from a shared database and returns aggregated results.

-- Create a schema for the app
CREATE SCHEMA IF NOT EXISTS app_schema;

-- Create a table to store processed results
CREATE TABLE IF NOT EXISTS app_schema.results (
    id INTEGER AUTOINCREMENT,
    category STRING,
    total NUMBER,
    created_at TIMESTAMP DEFAULT CURRENT_TIMESTAMP()
);

-- Create a stored procedure to populate the table
CREATE OR REPLACE PROCEDURE app_schema.process_data()
RETURNS STRING
LANGUAGE SQL
AS
$$
    INSERT INTO app_schema.results (category, total)
    SELECT category, SUM(amount)
    FROM my_shared_data.public.transactions
    GROUP BY category;
    RETURN 'Data processed successfully';
$$;

-- Create an app role and grant privileges
CREATE APPLICATION ROLE app_admin;
GRANT USAGE ON SCHEMA app_schema TO APPLICATION ROLE app_admin;
GRANT SELECT, INSERT ON TABLE app_schema.results TO APPLICATION ROLE app_admin;
GRANT USAGE ON PROCEDURE app_schema.process_data() TO APPLICATION ROLE app_admin;

Creating the Application Package and Version

Once your files are ready, you need to create an application package and add a version. The application package is a container that holds all versions of your app. Here's the SQL to do that:

1. Create the application package.
2. Add a version by pointing to the stage where your files are located.
3. Optionally, add a default release directive for the latest version.

After creating the package, you can share it with other accounts or publish it to the Marketplace.

-- Create the application package
CREATE APPLICATION PACKAGE my_app_package
    COMMENT = 'My first native app package';

-- Add a version from the stage
ALTER APPLICATION PACKAGE my_app_package
    ADD VERSION v1_0
    USING '@my_stage/app_src'
    LABEL = 'Initial release';

-- Set the default release directive
ALTER APPLICATION PACKAGE my_app_package
    SET DEFAULT RELEASE DIRECTIVE
    VERSION = v1_0
    PATCH = 0;

Installing the App in a Consumer Account

To test your app, you can install it in a different account (or a different role in the same account). The consumer must have the IMPORT SHARE privilege to install the app. Here's the process:

1. The provider shares the application package with the consumer account.
2. The consumer creates an application from the shared package.
3. The setup script runs, creating the app's objects.
4. The consumer can then use the app's stored procedures and Streamlit UIs.

Let's see how the consumer installs the app.

-- Consumer: Create an application from the shared package
CREATE APPLICATION my_app
    FROM APPLICATION PACKAGE my_app_package
    USING '@my_stage/app_src'
    COMMENT = 'My installed app';

-- Grant app role to a user
GRANT APPLICATION ROLE app_admin
    TO SHARE my_app;

-- Execute the stored procedure
CALL my_app.app_schema.process_data();

-- Query the results
SELECT * FROM my_app.app_schema.results;

Adding a Streamlit UI to Your App

Snowflake Native Apps can include Streamlit apps for interactive user interfaces. To add a Streamlit app, you need to include it in the manifest and upload the Python file to the stage. The Streamlit app runs within Snowflake and can call the app's stored procedures.

Here's an example Streamlit app that displays the results from our stored procedure.

import streamlit as st
import snowflake.snowpark as snowpark

# Create a session
session = snowpark.Session.builder.configs(st.secrets["snowflake"]).create()

st.title("My App Dashboard")

if st.button("Process Data"):
    result = session.sql("CALL my_app.app_schema.process_data()").collect()
    st.success(result[0][0])

# Display results
df = session.sql("SELECT * FROM my_app.app_schema.results").to_pandas()
st.dataframe(df)

Distributing Your App via the Snowflake Marketplace

Once your app is ready, you can list it on the Snowflake Marketplace to reach a wider audience. The Marketplace allows consumers to discover and install your app with a few clicks. To publish:

1. Ensure your application package is complete and tested.
2. Create a listing in the Marketplace via the Snowflake UI or SQL.
3. Provide a compelling description, pricing (if any), and support information.
4. Approve the listing after review.

Here's how to create a listing using SQL.

-- Create a listing for the application package
CREATE APPLICATION PACKAGE LISTING my_app_listing
    FOR my_app_package
    WITH
        TITLE = 'My App'
        SHORT_DESCRIPTION = 'A simple data processing app'
        LONG_DESCRIPTION = 'This app processes transaction data and provides aggregated results.'
        CATEGORIES = ('Analytics', 'Data Processing')
        PRICING = 'Free'
        SUPPORT_CONTACT = 'support@example.com'
        TERMS_OF_SERVICE_URL = 'https://example.com/tos'
        PRIVACY_POLICY_URL = 'https://example.com/privacy';