Snowflake Native App manifest reference¶

A manifest file is a text-based YAML (https://yaml.org/spec/) file with the filename: manifest.yml. The manifest file is used to define a Snowflake Native App and its associated data and logic. This topic describes the structure and fields of the manifest file.

For information about creating the manifest file for an app, see Create the manifest file for an app.

Snowflake Native App manifest¶

The general format of a Snowflake Native App manifest is:

manifest_version:           # required manifest version
version:                    # optional version metadata
artifacts:                  # required app resources and scripts
configuration:              # optional logging/tracing/metrics and callbacks
lifecycle_callbacks:        # optional lifecycle callbacks
privileges:                 # optional requested privileges in consumer account
references:                 # optional requested references in consumer account
restricted_callers_rights:  # optional restricted callers rights config
restricted_features:        # optional restricted features config

Manifest fields¶

Snowflake Native App manifests include the following fields. Each section below describes a field’s purpose and structure, and provides an example.

manifest_version field¶

The manifest_version field (Integer, required) specifies the version of the Snowflake Native App manifest file format. This value controls which manifest features are available and how Snowflake interprets the rest of the manifest.

manifest_version: 1¶

This version of the manifest file supports the current and legacy functionality of Snowflake Native Apps.

manifest_version: 2¶

清单文件的这一版本支持其他功能，包括自动授予权限。

manifest_version field example¶

manifest_version: 2

version field¶

The version field (block, optional) defines metadata about the version of the Snowflake Native App being published, including the version name, default patch number, display label, and an optional comment. When present, this block helps providers track and present releases. For more information about versions and patches, see Update an app (Legacy).

version.name field¶

Specifies the name of the version. The version name can only contain alphanumeric characters, underscores (_), hyphens (-), dollar signs ($), periods (.), and spaces.

此字段是可选字段。

Example: name: v1

version.patch field¶

指定默认补丁编号。

此字段是可选字段。

Example: patch: 1

version.label field¶

指定显示给使用者的版本的名称。

此字段是可选字段。

Example: label: "Initial Release"

version.comment field¶

Specifies a comment for the version. This comment is visible in Snowsight or when the provider runs the SHOW VERSIONS IN APPLICATION PACKAGE command.

此字段是可选字段。

Example: comment: "This is the initial release of the app."

version field example¶

version:
  name: v1
  patch: 1
  label: "Initial Release"
  comment: "This is the initial release of the app."

artifacts field¶

The artifacts field (block, required) defines the core resources that the Snowflake Native App uses, such as the setup script, readme, default Streamlit app, and any container image configuration. This block tells Snowflake where to find the code and assets needed to install, upgrade, and run the app.

artifacts.setup_script field¶

Specifies the path and filename of the setup script that is run when the Snowflake Native App is installed or upgraded. If you do not specify a value, the app uses the default value of setup.sql in the same directory as the manifest file. The setup script name and path can only contain alphanumeric characters, underscores (_), hyphens (-), periods (.), backslashes (), and forward slashes (/).

Example: setup_script: scripts/setup.sh

artifacts.readme field¶

指定 Markdown 自述文件的路径，该文件提供应用程序及其功能的概述。

In the case of a Streamlit app, if no value is specified for the default_streamlit property, the contents of this file is displayed to consumers when viewing the installed Snowflake Native App.

此文件的位置是相对于清单文件的位置指定的。

此字段是可选字段，但 Snowflake 建议您在应用程序中包含自述文件。

Example: readme: docs/README.md

artifacts.default_streamlit_app field¶

If the Snowflake Native App includes a Streamlit app, this property specifies the schema and name of the default Streamlit app available to consumers.

如果应用程序包含 Streamlit 应用程序，则此字段为必填字段。

artifacts.extension_code field¶

Enables or disables the use of extension code languages, including Java, Python, and Scala.

Example: extension_code: true

artifacts.container_services field¶

Specifies the location of the container images used by an app with containers. See Specify the container images used by an app with containers for more information.

对于带容器的应用程序，此字段为必填字段。

artifacts.container_services.uses_gpu field¶

表示带容器的应用程序使用 GPU。

对于带容器的应用程序，此字段为必填字段。

Example: uses_gpu: true

artifacts.container_services.images field¶

指定带容器的应用程序使用的每个容器镜像的路径。

对于带容器的应用程序，此字段为必填字段。

示例：

images:
- /spcs_app/napp/img_repo/eap_frontend
- /spcs_app/napp/img_repo/eap_backend
- /spcs_app/napp/img_repo/eap_router

artifacts field example¶

artifacts:
  setup_script: scripts/setup.sql
  readme: docs/README.md
  default_streamlit_app: apps/main.py
  extension_code: true
  container_services:
    uses_gpu: true
    images:
      - /spcs_app/napp/img_repo/eap_frontend
      - /spcs_app/napp/img_repo/eap_backend

configuration field¶

The configuration field (block, optional) specifies runtime configuration for the Snowflake Native App, including logging, tracing, and metrics levels, and — when applicable — the callback used to provision container resources. Providers use this block to control how much operational telemetry the app emits and how certain setup tasks are performed during installation.

configuration.log_level field¶

Specifies the logging level to use for the app Snowflake Native App.

If you do not set a value for this property, the default log data is not captured.

For information about supported values, see Setting levels for logging, metrics, and tracing.

configuration.trace_level field¶

指定要用于应用程序的跟踪事件级别。在提供商启用跟踪时，应用程序会自动获取所有查询和存储过程调用的开始时间和结束时间。

If you do not set a value for this property, trace events are not captured.

For the supported values of the trace_level property, see Setting levels for logging, metrics, and tracing.

configuration.metric_level field¶

指定要用于应用程序的指标级别。当提供商启用指标时，应用程序会自动向事件表发出自动检测的资源指标数据点。

See Set the log and trace levels for an app for more information.

For the supported values of the metric_level property, see Setting levels for logging, metrics, and tracing.

log_event_level:¶

Specifies the event logging level to use for the Snowflake Native App.

If you do not set a value for this property, log events are not captured.

For the supported values of the log_event_level property, see LOG_EVENT_LEVEL.

grant_callback:¶

configuration.grant_callback field¶

Specifies the schema and name of the callback function for an app with containers. The callback function is a stored procedure that can create compute pools, services, and perform other setup tasks required by the application.

对于带容器的应用程序，此字段为必填字段。

For more information, see Create a service by using the `grant_callback` property.

Example: grant_callback: my_schema.my_grant_callback

configuration field example¶

configuration:
  log_level: INFO
  trace_level: OFF
  metric_level: BASIC
  log_event_level: INFO
  grant_callback: my_schema.my_grant_callback

lifecycle_callbacks field¶

The lifecycle_callbacks field (block, optional) defines stored procedures that Snowflake runs at specific points in the Snowflake Native App lifecycle. Each entry in this block names a lifecycle callback and points to the procedure that implements it, allowing the app to validate configuration changes, prepare resources, or react to other lifecycle events when those callbacks are invoked.

For more information, see Callbacks.

lifecycle_callbacks.\<callback_name\> field¶

Specifies the name of a lifecycle callback for the app.

This field is required if the lifecycle_callbacks property is specified.

lifecycle_callbacks field example¶

lifecycle_callbacks:
  before_configuration_change: app_schema.before_config_change_callback

privileges field¶

The privileges field (block, optional) defines the privileges that the Snowflake Native App requests in a consumer account. Each entry in this block describes a specific privilege, along with a human-readable explanation of why the app needs it, so consumers can make informed decisions when granting access.

This field is required if the app requests privileges in the consumer account.

privileges.\<privilege_name\> field¶

Specifies the name of a privilege that the app requests in a consumer account.

This field is required if the privileges property is specified.

privileges.description field¶

Provides a description of the privilege being requested. The text specified in description is displayed to the consumer when the privilege is displayed in Snowsight using the Python Permission SDK, or when the SHOW PRIVILEGES command is run.

As a provider, you should include as much information as possible about why the Snowflake Native App needs this privilege and if the privilege is required or optional.

This field is required if the privileges field is specified.

privileges field example¶

privileges:
- CREATE TABLE:
  description: 'Required to create tables in the consumer account.'
- CREATE COMPUTE POOL:
  description: 'Required to allow the app to create a compute pool in the consumer account.'
- BIND SERVICE ENDPOINT:
  description: 'Required to allow endpoints to be externally accessible.'

references field¶

The references field (block, optional) describes the external objects in a consumer account — such as tables, views, secrets, or integrations — that the Snowflake Native App expects to bind to. Each reference entry specifies a label, description, required privileges, and other properties that guide consumers through providing the correct objects and permissions.

如果应用程序在使用者账户中请求引用，则此字段为必填字段。

references.\<reference_name\> field¶

指定应用程序在使用者账户中请求的引用的名称。

This field is required if the references property is specified.

references.\<reference_name\>.label field¶

指定向使用者显示的引用的标签。

This field is required if the references property is specified.

Example: label: "Orders table"

references.\<reference_name\>.description field¶

Provides a description of the reference being requested. The text specified in description is displayed to the consumer when the reference is displayed in Snowsight using the Python Permission SDK, or when the SHOW REFERENCES command is run.

This field is required if the references property is specified.

references.\<reference_name\>.privileges field¶

指定应用程序对使用者账户中引用绑定到的对象所需的权限列表。

This field is required if the references property is specified.

示例：

privileges:
  - SELECT
  - INSERT

references.\<reference_name\>.object_type field¶

指定与引用关联的对象的类型，例如架构和表，或者 API 集成。

This field is required if the references field is specified.

Example: object_type: TABLE

For more information, see Object types and privileges that a reference can contain.

references.\<reference_name\>.multi_valued field¶

允许多个对象与引用关联。使用此属性将多个使用者对象绑定到同一引用。当指定此属性时，将对具有单个值引用的对象执行相同的操作。该属性还可以用于具有多值引用的对象。

This field is optional. The default value is false.

For more information, see Request references and object-level privileges from consumers.

Example: multi_valued: true

references.\<reference_name\>.register_callback field¶

指定使用者将引用绑定到其账户中的对象时运行的回调函数的架构和名称。

This field is required if the references property is specified.

Example: register_callback: my_schema.my_register_callback

references.\<reference_name\>.configuration_callback field¶

指定回调函数的名称，该函数将为绑定到此引用的对象提供所需的配置。

This property is required if object_type is EXTERNAL ACCESS INTEGRATION or SECRET. This property is not applicable to other types of objects.

references.\<reference_name\>.required_at_setup field¶

表示必须在安装应用程序时绑定引用。

Example: required_at_setup: true

references field example¶

references:
- ORDERS_TABLE:
    label: "Orders table"
    description: "Orders table in TPC-H samples"
    privileges:
      - SELECT
    object_type: VIEW
    multi_valued: false
    register_callback: v1.register_single_callback

- EXTERNAL_ENDPOINT_EAI:
    label: "Allows egress to an external API"
    description: "EAI for Egress from NA+SPCS"
    privileges: [USAGE]
    object_type: EXTERNAL_ACCESS_INTEGRATION
    register_callback: v1.register_single_callback
    configuration_callback: v1.get_configuration
    required_at_setup: true

restricted_callers_rights field¶

The restricted_callers_rights field (block, optional) controls whether the Snowflake Native App is allowed to create executables — such as stored procedures or services — that run with restricted callers’ rights. Providers use this block to declare that the app needs to run certain logic with the caller’s privileges and to explain why that behavior is required.

This field is required if the app creates stored procedures or Snowpark Container Services services that run with restricted caller’s rights.

For more information, see Use owner’s rights and restricted caller’s rights in an app.

restricted_callers_rights.enabled field¶

指定是否允许应用程序创建调用方权限受限的可执行文件。

Providers must set this property to true if the app creates stored procedures or Snowpark Container Services services that run with restricted caller’s rights.

restricted_callers_rights.description field¶

说明应用程序需要创建调用方权限受限的可执行文件的原因。

restricted_callers_rights field example¶

restricted_callers_rights:
  enabled: true
  description: "Required to create stored procedures that run with restricted caller's rights."

restricted_features field¶

The restricted_features field (block, optional) declares any features that require explicit consumer approval before the Snowflake Native App can enable them, such as access to external or Apache Iceberg™ data. This block helps providers document potentially sensitive capabilities and allows consumers to review and consent to their use during installation.

restricted_features.external_data field¶

If present, specifies that the app shares external tables or Iceberg tables. For more information, see Request access to external and Apache Iceberg™ tables.

restricted_features.external_data.description field¶

Provides a description of the external or Iceberg table being requested.

This field is required if the restricted_features.external_data property is specified.

restricted_features field example¶

restricted_features:
  - external_data:
      description: "The reason for enabling an external or Iceberg table."

Manifest file example¶

The following code block is an example of a Snowflake Native App manifest file.

manifest_version: 2

version:
  name: v1
  patch: 1
  label: "Initial Release"
  comment: "This is the initial release of the app."

artifacts:
  setup_script: scripts/setup.sql
  readme: docs/README.md
  default_streamlit_app: apps/main.py
  extension_code: true
  container_services:
    uses_gpu: true
    images:
      - /spcs_app/napp/img_repo/eap_frontend
      - /spcs_app/napp/img_repo/eap_backend
      - /spcs_app/napp/img_repo/eap_router

configuration:
  log_level: INFO
  trace_level: OFF
  metric_level: BASIC
  grant_callback: my_schema.my_grant_callback

lifecycle_callbacks:
  <callback_name>:
    # See callbacks documentation for the full shape of each callback entry.
    # This is a placeholder showing that callback names appear under lifecycle_callbacks.
    # Example:
    #   procedure: v1.before_configuration_change

privileges:
  - CREATE TABLE:
      description: "Required to create tables in the consumer account."
  - CREATE COMPUTE POOL:
      description: "Required to allow the app to create a compute pool in the consumer account."
  - BIND SERVICE ENDPOINT:
      description: "Required to allow endpoints to be externally accessible."

references:
  - ORDERS_TABLE:
      label: "Orders table"
      description: "Orders table in TPC-H samples"
      privileges:
        - SELECT
      object_type: VIEW
      multi_valued: false
      register_callback: v1.register_single_callback

  - EXTERNAL_ENDPOINT_EAI:
      label: "Allows egress to an external API"
      description: "EAI for Egress from NA+SPCS"
      privileges: [USAGE]
      object_type: EXTERNAL_ACCESS_INTEGRATION
      register_callback: v1.register_single_callback
      configuration_callback: v1.get_configuration
      required_at_setup: true

restricted_callers_rights:
  enabled: true
  description: "Required to create stored procedures that run with restricted caller's rights."

restricted_features:
  - external_data:
      description: "The reason for enabling an external or Iceberg table."