Request data sharing with app specifications¶

Share data from an app with providers or third parties¶

Some Snowflake Native Apps need to share data back with the provider or with third-party Snowflake accounts for various business purposes. Common use cases include the following:

• Compliance reporting: Sharing audit logs or compliance data with regulatory accounts

• Telemetry and analytics: Sending usage metrics back to the provider for product improvement

• Data preprocessing: Sharing transformed data with partner accounts

• Support and troubleshooting: Providing diagnostic data to support teams

To enable data sharing from an app, Snowflake provides shares and listings. A share contains the database objects to be shared, while a listing provides the mechanism to share data across accounts and regions.

To configure an app to share data using listings, do the following:

• Use automated granting of privileges to request privileges from the consumer to create shares and listings.

• Create a share and grant database objects to it.

• Create an external listing attached to the share.

• Use application specifications to request permission from the consumer to share data with specific target accounts.

App specification workflow for sharing data¶

The general workflow for configuring an app to share data using listings is as follows:

1. Providers configure automated granting of privileges for the app. This allows consumers to give permission to an app to create shares and listings.

   Note

   App specifications require that manifest_version = 2 be set in the manifest file.

2. Providers add the CREATE SHARE and CREATE LISTING privileges to the manifest file.

3. Providers add SQL statements to the setup script to create the following objects as required:

   • Share

   • External listing

   • App specification

   The setup script creates the share and listing when the app is installed or upgraded. The app specification can be created during setup or at runtime through a stored procedure.

4. When configuring the app, consumers review and approve the target accounts and auto-fulfillment settings on the listing. Auto-fulfillment settings is only applicable for cross-region sharing. For more information on how consumers view and approve app specifications, see Approve connections to external resources using app specifications.

App specification definition for sharing data¶

For app specification of type LISTING, the app specification definition contains the following entries:

• TARGET_ACCOUNTS: A comma-separated list of target accounts to share data with, enclosed in single quotes. Each account must be specified in the format OrgName.AccountName. For example: 'ProviderOrg.ProviderAccount, PartnerOrg.PartnerAccount'.

• LISTING: The identifier of the listing object created by the app.

• AUTO_FULFILLMENT_REFRESH_SCHEDULE: Optional. The refresh schedule for cross-region data sharing. Can be specified as <num> MINUTE or USING CRON <expression>.

Set the version of the manifest file¶

To enable automated granting of privileges for an app, set the version at the beginning of the manifest file as shown in the following example:

manifest_version: 2

Add the CREATE SHARE and CREATE LISTING privileges to the manifest file¶

The CREATE SHARE and CREATE LISTING privileges allow the app to create shares and listings during installation or upgrade. To configure an app to request these privileges, add the following code to the privileges section of the manifest file:

manifest_version: 2
...
privileges:
  - CREATE SHARE:
      description: "Create a share for sharing compliance data with provider"
  - CREATE LISTING:
      description: "Create a listing for cross-region sharing of compliance data"
...

If you specify manifest_version to 2 in the manifest file, Snowflake automatically grants the CREATE SHARE and CREATE LISTING privileges to the app during installation or upgrade.

Create a share and grant objects to it¶

To create a share for data sharing, add the CREATE SHARE command to the setup script as shown in the following example:

CREATE SHARE compliance_share;

After creating the share, grant the database objects you want to share as shown in the following example:

-- Grant usage on a table in the app's database:
GRANT USAGE ON TABLE app_schema.compliance_data TO SHARE compliance_share;

-- If sharing from a database created by the app, do the following:
GRANT USAGE ON DATABASE app_created_db TO SHARE compliance_share;
GRANT USAGE ON SCHEMA app_created_db.reporting TO SHARE compliance_share;
GRANT SELECT ON TABLE app_created_db.reporting.metrics TO SHARE compliance_share;

Create an external listing¶

To create an external listing attached to the share, add the CREATE LISTING command to the setup script as shown in the following example:

CREATE EXTERNAL LISTING compliance_listing
  SHARE compliance_share
  AS
  $$
    title: "Compliance Data Share"
    subtitle: "Regulatory compliance reporting data"
    description: "Share compliance and audit data with authorized accounts"
    listing_terms:
      type: "OFFLINE"
  $$
  PUBLISH = FALSE
  REVIEW = FALSE;

Create an app specification for a listing¶

The following example shows how to create an app specification for a listing:

ALTER APPLICATION SET SPECIFICATION shareback_spec
  TYPE = LISTING
  LABEL = 'Compliance Data Sharing'
  DESCRIPTION = 'Share compliance data with provider for regulatory reporting'
  TARGET_ACCOUNTS = 'ProviderOrg.ProviderAccount, AuditorOrg.AuditorAccount'
  LISTING = compliance_listing
  AUTO_FULFILLMENT_REFRESH_SCHEDULE = '60 MINUTE';

This command creates an app specification named shareback_spec that requests permission to share data with the specified target accounts.

For cross-region sharing, the AUTO_FULFILLMENT_REFRESH_SCHEDULE parameter is required. You can set it to one of the following:

• '<num> MINUTE' - Number of minutes, minimum 10 minutes, maximum 8 days or 11520 minutes

• 'USING CRON <expression> <time_zone>' - Cron expression with time zone

Validate the listing configuration¶

Apps can validate that the listing has been properly configured after approval by running the following commands:

-- Check if the app specification is approved:
SHOW APPROVED SPECIFICATIONS IN APPLICATION;

-- Validate the listing configuration:
DESC LISTING compliance_listing;

Consumer approval workflow¶

When a consumer approves a LISTING app specification, the following occurs:

• Snowflake automatically adds the target accounts to the listing.

• If specified, Snowflake configures the auto-fulfillment refresh schedule.

• The listing becomes visible to the target accounts.

• Data attached to the listing would be queryable from the approved accounts.

When a consumer declines a LISTING app specification, the following occurs:

• The listing becomes unpublished, and any existing target accounts are removed from the listing.

• Auto-fulfillment is disabled.

• The listing is no longer visible to any target accounts

Best practices for LISTING app specifications¶

When implementing data sharing through app specification, please keep the following best practices in mind:

1. Data protection: Store sensitive data in the application where it’s protected from consumer modifications.

2. Share integrity: Snowflake does not prevent consumers from modifying shares created by the app. If you have concerns about the integrity of your data, you should add data to the share from inside the application itself. This ensures that at least the content of the data cannot be modified by consumers, as data within the app’s database is protected from external modifications.

3. Error handling: Implement proper error handling for cases where the app specification is declined or not yet approved.

4. Cross-region considerations: Set appropriate refresh schedules based on data freshness requirements and cost considerations.

5. Compliance: Document clearly what data you are sharing, and why you are sharing it, in the app specification description.

Using callback functions with LISTING app specifications¶

Apps can use lifecycle callbacks to respond when consumers approve or decline listing specifications by adding the following to the manifest file:

lifecycle_callbacks:
  specification_action: callbacks.on_spec_update

In the setup script, add the following callback stored procedure:

CREATE OR REPLACE PROCEDURE callbacks.on_spec_update (
  name STRING,
  status STRING,
  payload STRING)
RETURNS STRING
LANGUAGE SQL
AS
$$
BEGIN
  IF (name = 'shareback_spec' AND status = 'APPROVED') THEN
    -- Start populating shared tables
    CALL populate_compliance_data();
  ELSEIF (name = 'shareback_spec' AND status = 'DECLINED') THEN
    -- Clean up or notify provider
    CALL cleanup_share_data();
  END IF;
  RETURN 'Processed specification update';
END;
$$;

The procedure allows the app to react appropriately to consumer decisions about app’s data sharing request.