Tutorial: Create a Declarative Share with Cortex Code¶

Introduction¶

This tutorial walks you through creating a declarative share — a data application package with TYPE = DATA and a manifest — using Cortex Code (CoCo), either from the CLI or the Web UI in Snowsight. Consumers can install the result as an app and query the shared data.

The entire workflow uses a single prompt: CoCo validates your environment, finds or creates data, builds auxiliary objects, generates a manifest, creates and releases the application package, and publishes a private listing.

Along the way, the tutorial explains what CoCo does at each stage so you understand the underlying SQL and concepts.

What you’ll learn¶

In this tutorial, you’ll learn how to:

• Use a single prompt to have CoCo create a data product end-to-end: environment validation, data selection, secure views, a semantic view, a Cortex Agent, a manifest, an application package, a LIVE release, and a private listing.
• Verify the published app from a consumer account.
• Clean up provider and consumer resources when you’re done.

The prompt works identically in CoCo CLI and CoCo Web.

Declarative sharing background¶

If you’re new to declarative sharing, see About Declarative Sharing for an overview of how it compares to traditional data sharing and full native apps.

Prerequisites¶

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

• Access to two Snowflake accounts:

  • A provider account that will create and publish the declarative share.
  • A consumer account that will install and verify the published app.

• CoCo CLI or CoCo Web (Snowsight):

  CoCo CLICoCo Web (Snowsight)

  Cortex Code CLI installed and configured with connections to both accounts in your connections.toml:

  • macOS: ~/.snowflake/connections.toml
  • Windows: %USERPROFILE%\.snowflake\connections.toml

Open CoCo¶

cortex -c <your_provider_connection>

Run the prompt¶

A single prompt drives the entire workflow. Copy the prompt below and replace the placeholders with your own values, or leave them as-is — CoCo will validate your environment setup then create the declarative share.

1. Enter the following prompt:

   Expand code block

   I want to create and publish a declarative share so consumers
   can explore and query the data in natural language. Show me
   what data I have and let me decide what to share — if nothing
   fits, offer to create a small synthetic dataset. Publish as a
   private listing to <CONSUMER_ORG.ACCOUNT>.

   Show lessSee more

   Scroll to top
   • Replace <CONSUMER_ORG.ACCOUNT> with your consumer account’s data sharing identifier, which is typically the organization name and account name separated by a dot (for example, MYORG.MYCONSUMER). You can find this under Admin > Accounts in Snowsight.

2. CoCo walks through each stage and asks you to approve the commands before running them. Review the proposed SQL at each step and confirm. If CoCo encounters issues (a missing warehouse or insufficient permissions), it walks you through how to resolve each one before proceeding.

The following sections describe what CoCo does at each stage.

Identifying the dataset¶

CoCo validates your environment, then finds existing data or creates a small synthetic dataset. It inspects table structures, samples a few rows, and proposes a plan:

I found (or created) two tables in SALES_DB.PUBLIC:
- PRODUCTS (5 rows): name, category, price
- ORDERS (12 rows): product_id, quantity, order_date

Here's the plan:
1. Create schemas (data vs agent objects)
2. Create a secure summary view
3. Create a semantic view for natural-language querying
4. Create a Cortex Agent backed by the semantic view
5. Write manifest, create package, release, and publish

Creating auxiliary objects¶

CoCo creates objects to enhance the consumer experience. You can accept or decline each suggestion. Depending on your data, CoCo may offer:

Secure views — Aggregated or filtered views of the underlying tables. Views must be created with CREATE SECURE VIEW to work in declarative shares.

Semantic view — Maps tables, columns, and metrics so consumers can query the data using natural language through Cortex Analyst. For more information, see Semantic views.

Cortex Agent — A chat interface backed by the semantic view, giving consumers a conversational way to explore data without writing SQL. For more information, see Cortex Agents.

CoCo may also create notebooks, UDFs, and other objects depending on what makes sense for your dataset.

Writing the manifest¶

The manifest is a YAML file that declares which objects are shared and which app roles can access them. CoCo generates the manifest based on your data and the objects it created. The manifest for your dataset will be different from this example, and that’s the point: CoCo tailors the structure to match your objects. All you need to do is review it. If there’s an entry you don’t want to share, just tell CoCo to remove it.

Here’s an example of what the generated manifest might look like:

roles:
  - app_user:
      comment: "Read-only access to shared data"

shared_content:
  databases:
    - SALES_DB:
        schemas:
          - AGENT_SCHEMA:
              roles: [app_user]
              cortex_agents:
                - SALES_AGENT:
                    roles: [app_user]
          - DATA_SCHEMA:
              roles: [app_user]
              views:
                - ORDER_SUMMARY:
                    roles: [app_user]
              semantic_views:
                - SALES_SEMANTIC_VIEW:
                    roles: [app_user]
          - PUBLIC:
              roles: [app_user]
              tables:
                - PRODUCTS:
                    roles: [app_user]
                - ORDERS:
                    roles: [app_user]

The manifest follows a shared_content > databases > schemas > objects hierarchy. Shared-by-copy objects (agents) and shared-by-reference objects (tables, views, semantic views) go in separate schemas. For the full specification, see Manifest reference.

Creating the application package¶

CoCo creates an application package with TYPE = DATA, uploads the manifest, and releases the LIVE version:

CREATE APPLICATION PACKAGE SALES_DATA_PKG TYPE = DATA;

CoCo writes the manifest to the Workspace, then copies it into the package:

COPY FILES INTO snow://package/SALES_DATA_PKG/versions/LIVE/
  FROM 'snow://workspace/USER$.PUBLIC.DEFAULT$/versions/live/'
  FILES = ('manifest.yml');

PUT file:///workspace/manifest.yml
    snow://package/SALES_DATA_PKG/versions/LIVE/
    OVERWRITE=TRUE AUTO_COMPRESS=false;

ALTER APPLICATION PACKAGE SALES_DATA_PKG RELEASE LIVE VERSION;

These commands upload files into the package’s LIVE version stage. Unlike versioned native apps, declarative shares use LIVE versions that update automatically when you re-upload and re-release. For more information about the CREATE APPLICATION PACKAGE command, see CREATE APPLICATION PACKAGE.

Publishing the listing¶

CoCo creates a private listing targeted at your consumer account and publishes it:

CREATE EXTERNAL LISTING SALES_DATA_LISTING
APPLICATION PACKAGE SALES_DATA_PKG AS
$$
title: "Sales Data Product"
subtitle: "Product catalog, orders, and a Cortex Agent"
description: "Two tables, a secure summary view, and a Cortex Agent
              for conversational analytics."
listing_terms:
  type: "OFFLINE"
targets:
  accounts: ["MYORG.MYCONSUMER"]
$$
PUBLISH = FALSE
REVIEW = FALSE;

ALTER LISTING SALES_DATA_LISTING PUBLISH;

For details on listing configuration, see Creating a listing.

At this point the declarative share is fully published. CoCo verifies the package and listing, then presents a summary of everything it created.

Verify as a consumer¶

After CoCo finishes, confirm that the app is visible and working from your consumer account.

1. Sign in to Snowsight on your consumer account.

2. Navigate to Data Products > Apps.

3. Find the installed app and explore the schemas, tables, and views it exposes.

4. Open a worksheet and run a quick query:

   Copy codeExpand code block

   SELECT * FROM <app_name>.DATA_SCHEMA.ORDER_SUMMARY LIMIT 10;

   Show lessSee more

   Scroll to top

5. To try the Cortex Agent, open AI & ML > Snowflake Intelligence in Snowsight and select the agent bundled with the app. Ask a question like “Which product had the most orders?”

Troubleshooting and limitations¶

Privileges¶

• If you see errors about CREATE APPLICATION PACKAGE, switch to a role with that privilege or have an admin grant it before retrying.

Manifest issues¶

• If consumers can’t see objects, check manifest.yml to ensure the shared_content.databases: schemas: objects hierarchy is correct. For the full specification, see Manifest reference.

Schema mixing¶

• Don’t mix shared-by-copy and shared-by-reference objects in the same schema; use separate schemas. Shared-by-copy objects include agents, UDFs, and procedures. Shared-by-reference objects include tables, views, and semantic views.

Object limits¶

• A single application package supports up to 1,000 objects in shared_content. For details, see Limitations.

Notebooks¶

• Notebooks can only access data inside the same application package.
• Ensure each code cell has correct language metadata; otherwise SQL cells may be interpreted as Python and fail.

Summary, clean up, and additional resources¶

Congratulations! You’ve completed this tutorial.

Summary and key points¶

Using a single prompt in CoCo (CLI or Web), you:

• Had CoCo validate your environment, find (or create) a dataset, build a secure view, a semantic view, a Cortex Agent, a manifest, a TYPE = DATA application package, a LIVE release, and a private listing — all in one workflow.

Additional prompt examples¶

After you finish the tutorial, you can use prompts like these to extend or adapt the workflow. Replace placeholders (<...>) with your own object names.

• Publish a private listing for an existing package — Create a private listing for my application package <PACKAGE> targeting <CONSUMER_ORG.ACCOUNT>.
• Distribute cross-region — My consumer for <PACKAGE> is in a different region. Update the listing so it auto-fulfills cross-region. CoCo configures auto_fulfillment.refresh_type: SUB_DATABASE_WITH_REFERENCE_USAGE for you, which is required for TYPE = DATA packages.
• Convert a traditional data share — Take my data share <SHARE_NAME>, generate a declarative sharing manifest from it, then create the application package and release LIVE.
• Combine multiple data shares into one — Combine my data shares <SHARE_A> and <SHARE_B> into a single declarative manifest spanning both databases, then package and release. Declarative shares can span multiple databases; traditional shares cannot.
• Audit drift between manifest and listing — Compare the objects exposed by my published listing for <PACKAGE> against the manifest. Flag anything missing or out of sync.
• Iterate on the manifest — Add <SCHEMA>.<TABLE> to my <PACKAGE> manifest and release a new LIVE version.
• Add a Cortex Agent over a shared semantic view — Add a Cortex Agent over <SCHEMA>.<SEMANTIC_VIEW> to my <PACKAGE>. Put it in its own agent schema, update the manifest, and release LIVE.
• Bundle a getting-started notebook (CoCo CLI only) — Create a notebook with three sample queries against the shared views in <PACKAGE>, add it to the package, and re-release LIVE.

Cleanup (optional)¶

CoCo can generate the cleanup SQL for you.

Consumer account¶

1. In CoCo, connect to the consumer account.
2. Use a cleanup prompt:
   Expand code block

   Clean up the data app installed from the tutorial.
   Drop the tutorial application if it exists.

   Show lessSee more

   Scroll to top

Provider account¶

1. In CoCo, connect to the provider account.

2. Use a cleanup prompt:

   Expand code block

   Clean up the tutorial resources I created on the provider side:
   unpublish and drop the listing first, then drop the application
   package, then drop any tables, views, semantic views, agents, and
   schemas created only for this tutorial.

   Show lessSee more

   Scroll to top

   The order matters — you can’t drop a package while a published listing still references it.

Learn more¶

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

• About Declarative Sharing in the Native Application Framework
• Tutorial: Getting started with Declarative Native Apps
• Manifest reference
• Application packages
• Creating a listing
• Command reference