本指南将引导您完成以下操作:
- 创建第一个 R2 存储桶并启用其数据 catalog。
- 创建查询引擎与数据 catalog 进行身份验证所需的 API 令牌。
- 使用 PyIceberg ↗ 在 marimo ↗ Python notebook 中创建第一张 Iceberg 表。
- 使用 PyIceberg ↗ 将示例数据加载到表中并查询。
- 注册 Cloudflare 账户 ↗。
- 安装
Node.js↗。
Node.js 版本管理器
使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。
-
如果尚未登录,请运行:
npx wrangler login -
创建 R2 存储桶:
npx wrangler r2 bucket create r2-data-catalog-tutorial -
在存储桶上启用 catalog:
npx wrangler r2 bucket catalog enable r2-data-catalog-tutorial运行此命令时,请记下 Warehouse 和 Catalog URI。稍后需要用到这些值。
-
在 Cloudflare 仪表板中,前往 R2 Data Catalog 页面。
Go to R2 Data Catalog ↗ -
选择 Create catalog(创建目录)。
-
输入存储桶名称
r2-data-catalog-tutorial。由于此存储桶尚不存在,向导将为您创建它。可选地选择位置提示。 -
输入存储桶名称
r2-data-catalog-tutorial。如果存储桶尚不存在,向导会自动创建。可选地选择位置提示。 -
查看配置并选择 Create catalog(创建目录)。
-
创建完成后,catalog 详情页会显示 Catalog URI 和 Warehouse name。请记下这些值以备后用。
Iceberg 客户端(包括 PyIceberg ↗)必须使用同时具有 R2 和 catalog 权限的 R2 API 令牌 向 catalog 进行身份验证。
-
在 Cloudflare 仪表板中,前往 R2 object storage(R2 对象存储) 页面。
Go to Overview ↗ -
选择 Manage API tokens(管理 API 令牌)。
-
选择 Create API token(创建 API 令牌)。
-
选择 R2 Token(R2 令牌) 文本以编辑 API 令牌名称。
-
在 Permissions(权限) 下,选择 Admin Read & Write(管理员读取和写入) 权限。本指南会创建并写入表,因此需要读写访问权限。对于仅查询的客户端,可以使用 Admin Read only(仅管理员读取) 令牌。有关如何选择正确权限级别的详情,请参阅为 Iceberg 引擎进行身份验证。
-
选择 Create API Token(创建 API 令牌)。
-
记下 Token value。
您需要安装 Python 包管理器。本指南使用 uv ↗。如果尚未安装 uv,请按照安装 uv 指南 ↗操作。
我们将使用 marimo ↗ 作为 Python notebook。
-
创建用于存放 notebook 的目录:
mkdir r2-data-catalog-notebook -
进入新目录:
cd r2-data-catalog-notebook -
初始化新的 uv 项目(这将创建
.venv和pyproject.toml):uv init -
添加 marimo 和所需依赖项:
uv add marimo pyiceberg pyarrow pandas
-
创建名为
r2-data-catalog-tutorial.py的文件。 -
将以下代码片段粘贴到
r2-data-catalog-tutorial.py文件中:import marimo __generated_with = "0.11.31" app = marimo.App(width="medium") @app.cell def _(): import marimo as mo return (mo,) @app.cell def _(): import pandas import pyarrow as pa import pyarrow.compute as pc import pyarrow.parquet as pq from pyiceberg.catalog.rest import RestCatalog # Define catalog connection details (replace variables) WAREHOUSE = "<WAREHOUSE>" TOKEN = "<TOKEN>" CATALOG_URI = "<CATALOG_URI>" # Connect to R2 Data Catalog catalog = RestCatalog( name="my_catalog", warehouse=WAREHOUSE, uri=CATALOG_URI, token=TOKEN, ) return ( CATALOG_URI, RestCatalog, TOKEN, WAREHOUSE, catalog, pa, pandas, pc, pq, ) @app.cell def _(catalog): # Create default namespace if needed catalog.create_namespace_if_not_exists("default") return @app.cell def _(pa): # Create simple PyArrow table df = pa.table({ "id": [1, 2, 3], "name": ["Alice", "Bob", "Charlie"], "score": [80.0, 92.5, 88.0], }) return (df,) @app.cell def _(catalog, df): # Create or load Iceberg table test_table = ("default", "people") if not catalog.table_exists(test_table): print(f"Creating table: {test_table}") table = catalog.create_table( test_table, schema=df.schema, ) else: table = catalog.load_table(test_table) return table, test_table @app.cell def _(df, table): # Append data table.append(df) return @app.cell def _(table): print("Table contents:") scanned = table.scan().to_arrow() print(scanned.to_pandas()) return (scanned,) @app.cell def _(): # Optional cleanup. To run uncomment and run cell # print(f"Deleting table: {test_table}") # catalog.drop_table(test_table) # print("Table dropped.") return if __name__ == "__main__": app.run() -
将
CATALOG_URI、WAREHOUSE和TOKEN变量分别替换为第 1 节和第 2 节中的值。 -
在浏览器中启动 notebook 编辑器:
uv run marimo edit r2-data-catalog-tutorial.pynotebook 连接到 catalog 后,catalog 及其 namespace 和表将显示在 marimo 的 Datasources 面板中。
在上面的 Python notebook 中,您将:
- 连接到 catalog。
- 创建
defaultnamespace。 - 创建简单的 PyArrow 表。
- 在
defaultnamespace 中创建(或加载)people表。 - 向表追加示例数据。
- 打印表内容。
- (可选)删除本教程创建的
people表。