streamlit-snowflake

Snowflake 中的 Streamlit 技能

在 Snowflake 中原生构建和部署 Streamlit 应用，包括以 Native Apps 形式发布到 Marketplace。

快速入门

1. 初始化项目

将模板复制到项目中：

# Create project directory
mkdir my-streamlit-app && cd my-streamlit-app

# Copy templates (Claude will provide these)

2. 配置 snowflake.yml

更新 snowflake.yml 中的占位符：

definition_version: 2
entities:
  my_app:
    type: streamlit
    identifier: my_streamlit_app        # ← Your app name
    stage: my_app_stage                 # ← Your stage name
    query_warehouse: my_warehouse       # ← Your warehouse
    main_file: streamlit_app.py
    pages_dir: pages/
    artifacts:
      - common/
      - environment.yml

3. 部署

# Deploy to Snowflake
snow streamlit deploy --replace

# Open in browser
snow streamlit deploy --replace --open

何时使用此技能

适用于：

• 构建在 Snowflake 中原生运行的数据应用
• 需要通过 Snowpark 集成访问数据
• 将应用发布到 Snowflake Marketplace
• 为 Snowflake 中的 Streamlit 设置 CI/CD

不适用于：

• 在外部托管 Streamlit（请使用 Streamlit Community Cloud）
• 构建通用 Snowpark 管道（请使用 Snowpark 专用技能）
• 需要自定义 Streamlit 组件（SiS 不支持）

运行时环境

Snowflake 为 Streamlit 应用提供两种运行时选项：

仓库运行时（默认）

• 为每位查看者创建一个独立实例
• 使用 Snowflake Anaconda Channel 中的 environment.yml
• Python 3.9、3.10 或 3.11
• Streamlit 1.22.0 - 1.35.0
• 最适合：间歇性使用、隔离会话

容器运行时（预览版）

• 为所有查看者创建一个共享实例
• 使用包含 PyPI 软件包的 requirements.txt 或 pyproject.toml
• 仅支持 Python 3.11
• Streamlit 1.49+
• 成本显著更低（约 $2.88/天，而同等计算能力约为 $48/天）
• 最适合：频繁使用、优化成本

容器运行时配置：

CREATE STREAMLIT my_app
  FROM '@my_stage/app_folder'
  MAIN_FILE = 'streamlit_app.py'
  RUNTIME_NAME = 'SYSTEM$ST_CONTAINER_RUNTIME_PY3_11'
  COMPUTE_POOL = my_compute_pool
  QUERY_WAREHOUSE = my_warehouse;

主要区别：容器运行时允许使用外部 PyPI 软件包，而不局限于 Snowflake Anaconda Channel。

参见：运行时环境

安全模型

Streamlit 应用支持两种权限模型：

所有者权限（默认）

• 应用以所有者的权限而非查看者的权限执行
• 应用使用由所有者预配的仓库
• 查看者可以使用所有者角色的全部权限与数据交互

安全影响：

• 向应用角色授予写入权限时务必谨慎
• 使用专用角色创建和查看应用
• 查看者可以访问所有者角色能够访问的任何数据
• 最适合：供可信用户使用的内部工具

调用者权限（v1.53.0+）

• 应用以查看者的权限执行
• 每位查看者只能看到自己有权访问的数据
• 在多租户场景中提供数据隔离

以下情况使用调用者权限：

• 构建公开或面向外部的应用
• 需要按用户控制数据访问
• 构建需要数据隔离的多租户应用

参见下文的调用者权限连接模式。

项目结构

my-streamlit-app/
├── snowflake.yml           # Project definition (required)
├── environment.yml         # Package dependencies (required)
├── streamlit_app.py        # Main entry point
├── pages/                  # Multi-page apps
│   └── data_explorer.py
├── common/                 # Shared utilities
│   └── utils.py
└── .gitignore

关键模式

Snowpark 会话连接

import streamlit as st

# Get Snowpark session (native SiS connection)
conn = st.connection("snowflake")
session = conn.session()

# Query data
df = session.sql("SELECT * FROM my_table LIMIT 100").to_pandas()
st.dataframe(df)

调用者权限连接（v1.53.0+）

以查看者而非所有者的权限执行查询：

import streamlit as st

# Use caller's rights for data isolation
conn = st.connection("snowflake", type="callers_rights")

# Each viewer sees only data they have permission to access
df = conn.query("SELECT * FROM sensitive_customer_data")
st.dataframe(df)

安全性对比：

连接类型	权限模型	使用场景
type="snowflake"（默认）	所有者权限	内部工具、可信用户
type="callers_rights"（v1.53.0+）	调用者权限	公开应用、数据隔离

来源：Streamlit v1.53.0 发布说明

缓存开销较大的查询

@st.cache_data(ttl=600)  # Cache for 10 minutes
def load_data(query: str):
    conn = st.connection("snowflake")
    return conn.session().sql(query).to_pandas()

# Use cached function
df = load_data("SELECT * FROM large_table")

警告：在 Streamlit v1.22.0-1.53.0 中，params 参数不会包含在缓存键中。使用带参数的查询时，请设置 ttl=0 以禁用缓存；也可以在 1.54.0+ 可用后升级（问题 #13644）。

优化 Snowpark DataFrame 性能

在图表或表格中使用 Snowpark DataFrame 时，仅选择所需的列，避免获取不必要的数据：

# ❌ Fetches all 50 columns even though chart only needs 2
df = session.table("wide_table")  # 50 columns
st.line_chart(df, x="date", y="value")

# ✅ Fetch only needed columns for better performance
df = session.table("wide_table").select("date", "value")
st.line_chart(df, x="date", y="value")
# 5-10x faster for wide tables

重要性：st.dataframe() 和图表组件会调用 df.to_pandas()，从而计算所有列，即使可视化只需要其中一部分。预先选择列可以减少数据传输并提升性能（Issue #11701）。

环境配置

environment.yml（必需格式）：

name: sf_env
channels:
  - snowflake          # REQUIRED - only supported channel
dependencies:
  - streamlit=1.35.0   # Explicit version (default is old 1.22.0)
  - pandas
  - plotly
  - altair=4.0         # Version 4.0 supported in SiS
  - snowflake-snowpark-python

错误预防

此技能可预防 14 个已记录的错误：

错误	原因	预防方法
PackageNotFoundError	使用 conda-forge 或外部 channel	使用 channels: - snowflake（或使用 Container Runtime 安装 PyPI 包）
缺少 Streamlit 功能	默认版本为 1.22.0	显式设置 streamlit=1.35.0（或使用 Container Runtime 以获得 1.49+ 版本）
ROOT_LOCATION deprecated	CLI 语法过时	使用 Snowflake CLI 3.14.0+ 和 FROM source_location
身份验证失败（2026 年起）	仅使用密码进行身份验证	使用密钥对或 OAuth（参见 references/authentication.md）
文件上传失败	文件大于 200MB	将上传文件控制在 200MB 限制以内
DataFrame 显示失败	数据大于 32MB	在显示前对数据分页或进行限制
page_title not supported	SiS 限制	不要在 st.set_page_config() 中使用 page_title、page_icon 或 menu_items
自定义组件错误	SiS 限制	仅使用不调用外部服务的组件
找不到 _snowflake module	迁移到 Container Runtime	使用 from snowflake.snowpark.context import get_active_session 替代 from _snowflake import get_active_session（迁移指南）
使用不同参数时缓存的查询返回错误数据	params 未包含在缓存键中（v1.22.0-1.53.0）	对带参数的查询使用 ttl=0 禁用缓存，或在 1.54.0+ 可用时升级（Issue #13644）
仅使用 kwargs 时出现 Invalid connection_name 'default'	缺少 secrets.toml 或 connections.toml	创建包含 [connections.snowflake] 部分的最简 .streamlit/secrets.toml（Issue #9016）
Native App 意外升级	隐式使用默认 Streamlit 版本（BCR-1857）	在 environment.yml 中显式设置 streamlit=1.35.0，以防止版本自动变更（BCR-1857）
Container Runtime 子目录中的文件路径失效	某些命令使用相对于入口点的路径	使用 pathlib 解析绝对路径：Path(__file__).parent / "assets/logo.png"（Runtime 文档）
宽 Snowpark DataFrame 性能缓慢	st.dataframe() 会获取所有列，即使有些列未使用	传给 Streamlit 前仅选择所需列：df.select("col1", "col2")（Issue #11701）

部署命令

基本部署

# Deploy and replace existing
snow streamlit deploy --replace

# Deploy and open in browser
snow streamlit deploy --replace --open

# Deploy specific entity (if multiple in snowflake.yml)
snow streamlit deploy my_app --replace

CI/CD 部署

GitHub Actions 工作流模板请参见 references/ci-cd.md。

Marketplace 发布（Native App）

要将 Streamlit 应用发布到 Snowflake Marketplace：

1. 转换为 Native App - 使用 templates-native-app/ 模板
2. 创建 Provider Profile - Marketplace 列表所必需
3. 提交审核 - Snowflake 会在发布前进行审核

完整工作流请参见 templates-native-app/README.md。

Native App 结构

my-native-app/
├── manifest.yml            # Native App manifest
├── setup.sql               # Installation script
├── streamlit/
│   ├── environment.yml
│   ├── streamlit_app.py
│   └── pages/
└── README.md

软件包可用性

仅提供 Snowflake Anaconda Channel 中的软件包：

-- Query available packages
SELECT * FROM information_schema.packages
WHERE language = 'python'
ORDER BY package_name;

-- Search for specific package
SELECT * FROM information_schema.packages
WHERE language = 'python'
AND package_name ILIKE '%plotly%';

常见的可用软件包：

• pandas、numpy、scipy
• plotly、altair（4.0）、matplotlib
• scikit-learn、xgboost
• snowflake-snowpark-python
• streamlit（默认版本为 1.22.0，显式指定版本时为 1.35.0）

不可用：

• conda-forge 中的软件包
• 自定义／私有软件包
• 需要原生编译的软件包

参见：Snowpark Python Packages Explorer

已知限制

数据与大小限制

• 后端／前端之间的消息大小上限为 32 MB（会影响大型 st.dataframe）
• 文件上传上限为 200 MB（通过 st.file_uploader）
• 不支持 .so 文件——不支持原生编译库
• 不支持外部暂存区——仅支持内部暂存区（客户端加密）

UI 限制

• st.set_page_config——不支持 page_title、page_icon、menu_items
• st.bokeh_chart——不支持
• 自定义 Streamlit 组件——仅支持不调用外部服务的组件
• 内容安全策略——会阻止外部脚本、样式、字体和 iframe
• 禁止使用 eval()——CSP 会阻止不安全的 JavaScript 执行

缓存（仓库运行时）

• 仅限会话范围——st.cache_data 和 st.cache_resource 不会跨用户持久化
• 容器运行时支持在不同查看者之间完整共享缓存

软件包限制（仓库运行时）

• 仅限 Snowflake Anaconda Channel——不支持 conda-forge，也不支持 pip
• 容器运行时允许使用 PyPI 软件包

网络与访问

• 不支持 Azure Private Link／GCP Private Service Connect
• 不支持复制 Streamlit 对象

身份验证（重要——截止日期为 2026 年）

仅使用密码的身份验证方式正在弃用：

里程碑	日期	要求
里程碑 1	2025 年 9 月至 2026 年 1 月	Snowsight 用户必须使用 MFA
里程碑 2	2026 年 5 月至 7 月	所有新用户必须使用 MFA
里程碑 3	2026 年 8 月至 10 月	所有用户必须使用 MFA 或密钥对／OAuth

推荐的身份验证方式：

• 密钥对身份验证（适用于服务账户）
• OAuth 客户端凭据（适用于 M2M）
• 工作负载身份联合（适用于云原生应用）

实现模式请参见 references/authentication.md。

资源

官方文档

• Snowflake 中的 Streamlit
• Snowflake CLI Streamlit 命令
• 使用 Streamlit 构建 Native Apps
• Marketplace 发布

示例

• snowflake-demo-streamlit
• native-apps-templates
• GitLab 的 Streamlit 框架

工具

• Snowpark Python Packages Explorer
• Snowflake MCP Server（用于 Claude 集成）