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, the app needs to provide both shares and listings. A share contains the database objects to be shared, and a listing provides the mechanism to share data across accounts and regions.

For more information about data shares, see About Secure Data Sharing.

To configure an app to share data using listings, follow these steps:

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

2. Create a share and grant database objects to it.

3. Create an external listing attached to the share.

4. To request permission from the consumer to share data with specific target accounts, use application specifications.

App specification workflow for sharing data¶

Configuring an app to share data by using listings follows this general workflow:

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 manifest_version = 2 to 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 are 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 an 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.

1. 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"
   ...
   

   Copy

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¶

1. 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;

1. 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;

Copy

Create an external listing¶

1. 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;
   

   Copy

Create an app specification for a listing¶

1. To create an app specification for a listing, follow this example:

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 = '720 MINUTE';

Copy

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

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

   • '<num> MINUTE': Number of minutes, with a minimum of 10 minutes,

   • and a maximum of 8 days or 11520 minutes (eight days)

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

Validating 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¶

Consumer approval of a LISTING app specification triggers this workflow:

• 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 can be queried from the approved accounts.

Consumer rejection of a LISTING app specification triggers this workflow:

• 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, consider the following best practices:

• Share integrity: Snowflake does not prevent consumers from modifying

  shares created by an application. As a result, the provider is responsible for implementing measures to protect the integrity of the underlying shared data.

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

• Cross-region considerations: The app provider is responsible for setting refresh schedules that balance data freshness requirements with cost considerations. Although Listing Auto Fulfillment costs are billed to the app consumer, the provider’s choice of schedule should be cost-aware to minimize the unnecessary cost for the app consumer.

• 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 code 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.

Limitations¶

This section describes limitations when using app specifications.

Auditing

Snowflake doesn’t offer built-in auditing for data that an app shares back to the provider. If a consumer has compliance or regulatory requirements that include an audit trail, they must coordinate directly with the provider to implement their own separate monitoring solutions.

Sharing from within the application

Snowflake does not recommend data sharing with the provider directly from within the application because Listing Auto Fulfillment is not currently supported for data shared in this manner.