Tutorial: Getting started with Declarative Native Apps

Introduction

This tutorial takes Snowflake data providers through the process of creating, publishing, and accessing a Snowflake Declarative Native App. The tutorial uses SnowCLI as well as a provided notebook file and a partially complete manifest file to create a Declarative Native App.

This tutorial includes two personas:

  • Provider: The provider creates a Declarative Native App, creates a listing for it, and shares it with a consumer

  • Consumer: The consumer installs the Declarative Native App and uses its features and functionality.

What you’ll learn

As a provider, you will learn how to:

  • Create a manifest that declares the data and logic of a Declarative Native App.

  • Package and test the app locally.

  • Create and share a listing for the app that a consumer can see.

and as a consumer:

  • Install a Declarative Native App listing into a test consumer account and explore its features.

Prerequisites

Before getting started, make sure that you meet the following requirements:

  • You are familiar with YAML. YAML is the language used to define the manifest of a Declarative Native App.

    If you are not familiar with YAML, see https://yaml.org/spec/ (https://yaml.org/spec/).

  • You have installed the SnowCLI command-line interface.

    SnowCLI allows you to manage Snowflake objects and perform various tasks.

    For more information on SnowCLI installation, see the Installing Snowflake CLI.

  • You’ll require access to two Snowflake accounts:

    • Provider account, used to create and publish the Declarative Native App. This account should have the necessary privileges to create and manage Snowflake objects such as databases, schemas, tables, and virtual warehouses.

    • Consumer account, A separate test account representing a consumer, used to test the Declarative Native App consumer experience. This account should have the necessary privileges to install apps and access shared data.

Each section in the tutorial specifies whether the steps should be completed using the provider or consumer account.

In addition, you need to do the following before you start the tutorial:

  • Download sample files provided for this exercise.

  • Create a database, and tables for this tutorial.

    These are the basic Snowflake objects needed for most Snowflake activities.

Preparing the tutorial environment

The tutorial provides sample data files and instructions for setting up your local environment.

Downloading the sample data files

For this tutorial, download the sample data files provided by Snowflake.

To download and unzip the sample data files:

  1. Click the name of the archive file, tutorial-getting-started.zip and save the link/file to your local file system.

  2. Unzip the sample files. The tutorial assumes you unpacked files in to the following directories:

  • Linux/macOS: /tmp/tutorial

  • Windows: C:temp\tutorial

For example to unzip the file on Linux/macOS, assuming they were downloaded to your Downloads folder execute the following command:

unzip /tmp/tutorial-getting-started.zip -d /tmp/tutorial
Copy

These files include:

  • SQL files for creating all required artifacts. These files can be used to speed the process of setting up and tearing down your tutorial environment.

  • A notebook file that contains the logic for the Declarative Native App.

  • A manifest file that contains the metadata for the Declarative Native App, which you will need to make minor modifications to during the tutorial.

  • A sample configuration file for SnowCLI, which you can use to configure your Snowflake connection.

Snowflake CLI configuration

The Snowflake CLI tool is required to build, deploy, and install the application in this tutorial. If you do not have Snowflake CLI on your machine, install it as per instructions available in Installing Snowflake CLI.

After SnowCLI is installed, you need to configure a connection to Snowflake in your configuration file. This tutorial uses connections.toml. connections.toml can be found in:

  • Mac OSX in ~/.snowflake/connections.toml

  • Microsoft Windows in %USERPROFILE%\.snowflake\connections.toml.

For more information on configuring SnowCLI connections, see Define connections.

To add and test a connection:

  1. Sign in to Snowsight.

  2. In the navigation menu, select Account » {your account} » View Account Details.

  3. In the Account Details pane copy the Account Identifier value.

  4. Using a text editor, open the connections.toml file.

  5. Add a new connection named tutorial_connection to the connections.toml file. The connection should look similar to:

    [tutorial_connection]
account = "your_account_identifier"
user = "your_username"
password = "your_password"
authenticator = "snowflake"
    Copy

  6. Save the connections.toml file.

  7. Open a command prompt or terminal window and execute the following command to test the connection:

    snow connection test
    Copy

    If the connection is successful, you should see output similar to:

    +-------------------------------------------------------------------+
| key             | value                                           |
|-----------------+-------------------------------------------------|
| Connection name | tutorial_connection                             |
| Status          | OK                                              |
| Host            | . . .                                           |
| Account         | . . .                                           |
| . . .                                                             |
+-------------------------------------------------------------------+

  8. Optionally, you can use the following to set the default connection for SnowCLI. Setting the default connection allows you to use the connection name without specifying it in every command.

    snow connection set-default tutorial_connection
    Copy

If you already have a connection configured and would like to use it with the connector, use its name instead of tutorial_connection whenever this connection is used in this tutorial.

Note

The tutorial_connection connection is used throughout this tutorial to refer to the provider account. The remainder of this tutorial assumes you have set this as the default connection for SnowCLI.

When connecting to the consumer account, you will use Snowsight. For instructions on how to access Snowsight, see Snowflake in 20 minutes: Prerequisites, and then return to this tutorial.

Create Snowflake objects

During this step, you, as a provider, will use SnowCLI and create the required Snowflake objects.

  • A database (DB_TO_SHARE)

  • A schema (SCHEMA_TO_SHARE)

  • A table (TABLE_TO_SHARE).

  • Sample data for the table.

At the completion of this tutorial, you’ll remove these objects.

Note

Commands are shown at the command line using SnowCLI as well as in combination using files.

For example, the following command creates a database named DB_TO_SHARE using SnowCLI and the required connection.

snow sql -q "CREATE OR REPLACE DATABASE DB_TO_SHARE"
Copy

Assuming the same SQL command exists in a text file named create_db.sql, you can also run the command using SnowCLI as follows:

snow sql -f create_db.sql
Copy

Assuming you set a default connection, you can also run the command without specifying the connection:

snow sql -f create_db.sql
Copy

Review each of the following steps to create the required objects. Again, as a reminder, a script is provided which can be used to create all the objects in one command.

  1. Create the DB_TO_SHARE database using the CREATE DATABASE command:

    snow sql -q "CREATE OR REPLACE DATABASE DB_TO_SHARE;"
    Copy

  2. Create the SCHEMA_TO_SHARE schema using the CREATE SCHEMA command:

    snow sql -q "CREATE OR REPLACE SCHEMA DB_TO_SHARE.SCHEMA_TO_SHARE;"
    Copy

    Note

    The database and schema you just created are now in use for your current session. You can also use the context functions to get this information.

  3. Create the table named TABLE_TO_SHARE in SCHEMA_TO_SHARE using the CREATE TABLE command:

    snow sql -q "CREATE OR REPLACE TABLE DB_TO_SHARE.SCHEMA_TO_SHARE.TABLE_TO_SHARE (random_number INTEGER); \
    "
    Copy

  4. Add data to the table.

    To add a row containing a random value use the INSERT command:

    snow sql -q "INSERT INTO DB_TO_SHARE.SCHEMA_TO_SHARE.TABLE_TO_SHARE (random_number) \
    SELECT UNIFORM(1, 100, RANDOM()) AS RANDOMNUMBER;"
    Copy

    Validate that data was inserted.

    snow sql -q "SELECT * FROM DB_TO_SHARE.SCHEMA_TO_SHARE.TABLE_TO_SHARE;"
    Copy

At this point the backing database, schema, and populated table exist and are ready for use.

To create all the objects in one step, you can use the provided 1.create-database-artifacts.sql.

For example:

snow sql  -f /tmp/tutorial/sql/1.create-database-artifacts.sql
Copy

Create and package a Declarative Native App

As a provider, create and package the Declarative Native App. Note that this step uses:

  • A provided NOTEBOOK file that contains the logic for the Declarative Native App. This notebook contains a single SQL statement that queries the table created in the previous step.

Creating a Declarative Native App involves:

  1. Defining a YAML manifest representing the data and logic in the Declarative Native App. A starting point for the manifest is provided in the manifest.yml file.

  2. Creating the Declarative Native App package.

  3. Packaging the app with its manifest and the associated notebook.

  4. Validating the Declarative Native App package.

See the Declarative Native App manifest reference for a complete list of all required and optional fields.

Create the application package

Creating the application package involves creating the application package file, and then adding a notebook and a manifest.

In Snowsight, complete the following procedure in your worksheet.

  1. Create a new application package using CREATE APPLICATION PACKAGE. Creating the application package also creates a live version of the application package that you can modify.

    snow sql -q "CREATE APPLICATION PACKAGE DECL_SHARE_APP_PKG TYPE=DATA;"
    Copy

  2. To verify that your app was created, use SHOW APPLICATION PACKAGES:

    snow sql -q "SHOW APPLICATION PACKAGES LIKE '%DECL_SHARE_%';"
    Copy

    Which will return a result similar to:

    +-------------------------------+--------------------+-. . .-+
| Created_on                    | name               |       |
+-------------------------------+--------------------+-. . .-+
+ 2025-06-12 09:40:08.845 -0700 | DECL_SHARE_APP_PKG | . . . |
+-------------------------------+--------------------+-. . .-+

Populate the application package

  1. Add a notebook. Note that this command assumes the notebook is named NOTEBOOK.ipynb and is located in the /tmp/tutorial/app folder. For more information see PUT.

    The notebook file provided contains a single SQL statement that queries the previously created table.

    Note

    The command below assume that the tutorial files are located in the /tmp/tutorial/app folder. You may need to modify the path to the notebook file based on where you unzipped the tutorial files.

    snow sql -q "put file:////tmp/tutorial/app/NOTEBOOK.ipynb \
             snow://package/DECL_SHARE_APP_PKG/versions/LIVE/ \
             OVERWRITE=TRUE AUTO_COMPRESS=false;"
    Copy

    Which will return a result similar to:

    +----------------------------------------------------------------------------------------------------------------------------+
| source         | target         | source_size | target_size | source_compression | target_compression | status   | message |
|----------------+----------------+-------------+-------------+--------------------+--------------------+----------+---------|
| NOTEBOOK.ipynb | NOTEBOOK.ipynb | 817         | 832         | NONE               | NONE               | UPLOADED |         |
+----------------------------------------------------------------------------------------------------------------------------+

  2. Add a manifest. Note that this command assumes the manifest located in the /tmp/tutorial/app folder.

    snow sql -q "put file:////tmp/tutorial/app/manifest.yml \
             snow://package/DECL_SHARE_APP_PKG/versions/LIVE/ \
             OVERWRITE=TRUE AUTO_COMPRESS=false;"
    Copy

Which will return a result similar to:

+------------------------------------------------------------------------------------------------------------------------+
| source       | target       | source_size | target_size | source_compression | target_compression | status   | message |
|--------------+--------------+-------------+-------------+--------------------+--------------------+----------+---------|
| manifest.yml | manifest.yml | 359         | 368         | NONE               | NONE               | UPLOADED |         |
+------------------------------------------------------------------------------------------------------------------------+

  1. Verify the application package contents.

    snow sql -q "ALTER APPLICATION PACKAGE DECL_SHARE_APP_PKG BUILD;"
    Copy

    Which will return a result similar to:

    +--------------------------------------------------------------------------------+
| status                                                                         |
|--------------------------------------------------------------------------------|
| Built the live version of APPLICATION PACKAGE DECL_SHARE_APP_PKG successfully. |
+--------------------------------------------------------------------------------+

To create, package, and test the app in one step, use the provided 2.create-package-build-app.sql file containing all SQL commands to create, package, test a Declarative Native App.

snow sql  -f /tmp/tutorial/sql/2.create-package-build-app.sql
Copy

Version and release the app

Once an application package has been created and populated with a notebook and manifest, all that remains is to commit and release it.

  1. Release the newly updated version using a commands similar to:

snow sql -q "ALTER APPLICATION PACKAGE DECL_SHARE_APP_PKG RELEASE LIVE VERSION;"
Copy

Which will return a result similar to:

+-------------------------------------------------------------------------------------------+
| status                                                                                    |
|-------------------------------------------------------------------------------------------|
| Released LIVE version (VERSION$2) of APPLICATION PACKAGE DECL_SHARE_APP_PKG successfully. |
+-------------------------------------------------------------------------------------------+

To release the app use the provided 3.release-app.sql file containing SQL commands to release a Declarative Native App.

snow sql  -f /tmp/tutorial/sql/3.release-app.sql
Copy

Test a Declarative Native App

Once a Declarative Native App is packaged and released the database and logic it contains can be tested locally.

This section describes how to complete the following tasks:

  • Create an app from an application package.

  • Create a database from an application package.

  • Examine the contents of a database created from an application package.

Note

These steps are used by providers to test their app before it is published.

Create an app from an application package

  1. Using the CREATE APPLICATION command, create an app from an application package using a command similar to:

snow sql -q "CREATE APPLICATION DECL_SHARE FROM APPLICATION PACKAGE DECL_SHARE_APP_PKG;"
Copy

Examine app contents

You can test your Declarative Native App by examining the contents using either SQL commands or the Snowsight.

snow sql -q "USE DATABASE DECL_SHARE;
             DESCRIBE DATABASE  DECL_SHARE; \
             SHOW SCHEMAS IN DATABASE DECL_SHARE; \
             SHOW TABLES IN DATABASE DECL_SHARE; "
Copy

Declarative Native Apps includes a special schema, APP$UI, which when in use shows the notebooks contained with the app.

For example:

USE APP$UI;
SHOW NOTEBOOKS;
Copy

Use the provided 4.test-locally-app.sql file which contains commands to examine the content of a Declarative Native App. In addition the file, 4.test-only-app.sql, contains commands to test the app but does not attempt to create an database from the application package.

snow sql  -f /tmp/tutorial/sql/4.test-locally-app.sql
Copy

Share your Declarative Native App using a listing

After successfully creating and testing a Declarative Native App, we can create a listing and add the app as a data product for that listing. Making the app available as a listing allows other Snowflake users to discover and install the app.

This allows you to share your app with other Snowflake users and allows them to install and use the app in their account.

Create a listing for your app

Note

The following steps are performed by a provider to create a listing for the Declarative Native App. The listing is then used by consumers to install the Declarative Native App.

To create a listing for your app:

  1. Sign in to Snowsight.

  2. In the navigation menu, select Data Products » Provider Studio.

  3. In the + Create Listing menu, select Specified consumers for selected accounts.

  4. Under What’s the title of the listing?, enter Declarative Sharing Tutorial.

  5. Select Only Specified Consumers. Select Next.

  6. Under What’s in the listing, click + Select.

  7. Select DECL_SHARE_APP_PKG.

  8. Optional: Enter a description for your listing.

  9. Under Consumer Data Sharing Account ID, provide a valid account identifier to share the listing to.

    Note

    The account identifier is a unique identifier for your Snowflake account. It is used to identify your account when sharing data and apps with other Snowflake accounts. To find your account identifier see Account identifiers.

  10. Select Publish.

Install the app in a consumer account

Important

The consumer account installing an app must specify a default warehouse.

To create a warehouse:

  1. In the navigation menu, select Admin » Warehouses

  2. Click + Warehouse.

  3. Configure the warehouse as needed.

To set a default warehouse:

  1. In the navigation menu lower right select your account, then select Settings » Preferences.

  2. Select warehouse from the Default Warehouse drop-down list.

To install your app from the listing:

  1. Sign in to Snowsight.

  2. In the navigation menu, select Data Products » Apps.

  3. Select the tile for the listing under Recently shared with you.

  4. Select Get.

  5. Select Options and enter a name for the app. For this tutorial, use SimpleAppConsumer.

  6. Select the warehouse where you want to install the app.

  7. Select Get.

  8. Select Open to view your listing or Done to finish.

  9. Explore the listing as you would any other listing.

    For more information see Access content in a Declarative Native App.

Summary, clean up, and additional resources

Congratulations! You’ve successfully completed this tutorial.

Take a few minutes to review a short summary and the key points covered in the tutorial.

You might also want to consider cleaning up by dropping any objects you created in the tutorial. Learn more by reviewing other topics in the Snowflake Documentation.

Summary and key points

In summary, Declarative Native Apps:

  • Can be easily used to expose databases, tables, views, and schemas.

  • Have a well-defined lifecycle.

  • Can be accessed by consumers using listings or app.

Cleanup (Optional)

On the consumer account used to install the Declarative Native App, to uninstall the listing, follow these steps:

  1. Sign in to Snowsight.

  2. In the navigation menu, select Data Products » Apps.

  3. In the row for SimpleAppConsumer on the … menu, select Uninstall.

If the objects you created in this tutorial are no longer needed, you can remove them from the system using the following commands:

As the provider who originally created the objects, run the following commands using SnowCLI

snow sql -q "DROP LISTING IF EXISTS SIMPLE_APP_TUTORIAL; \
             DROP APPLICATION IF EXISTS DECL_SHARE; \
             DROP APPLICATION PACKAGE IF EXISTS DECL_SHARE_APP_PKG; \
             DROP TABLE IF EXISTS DB_TO_SHARE.SCHEMA_TO_SHARE.TABLE_TO_SHARE; \
             DROP SCHEMA IF EXISTS DB_TO_SHARE.SCHEMA_TO_SHARE; \
             DROP DATABASE IF EXISTS DB_TO_SHARE; "
Copy

For simplicity, you can use the provided teardown-tutorial.sql file containing all SQL commands to remove the objects created in this tutorial.

snow sql  -f /tmp/tutorial/sql/teardown-tutorial.sql
Copy

Learn more

To learn more about Declarative Native Apps, see the following topics:

Language: English