跳转到内容
本站为社区维护的非官方中文翻译,与 Cloudflare, Inc. 无关联。本站不提供账户登录,请勿在任何非官方站点输入您的 Cloudflare 账户信息。官方文档:developers.cloudflare.com

快速入门

最后更新 查看 MarkdownAgent 设置

本指南将引导您完成以下操作:

前提条件

  1. 注册 Cloudflare 账户 ↗。
  2. 安装 Node.js ↗。

Node.js 版本管理器

使用 Vite+ (vp env) ↗ 安装和管理 Node.js 版本。

有关支持的 Node.js 版本,请参阅 Wrangler 系统要求。

1. 创建 R2 存储桶并启用数据 catalog

  1. 如果尚未登录,请运行:

    npx wrangler login
  2. 创建 R2 存储桶:

    npx wrangler r2 bucket create r2-data-catalog-tutorial
  3. 在存储桶上启用 catalog:

    npx wrangler basin catalog enable r2-data-catalog-tutorial

    运行此命令时,请记下 Warehouse 和 Catalog URI。稍后需要用到这些值。

  1. 在 Cloudflare 仪表板中,前往 Basin Catalog 页面。

    前往 Basin Catalog ↗
  2. 选择 Create catalog(创建目录)。

  3. 输入存储桶名称 r2-data-catalog-tutorial。如果存储桶尚不存在,向导会自动创建。可选地选择位置提示。

  4. 查看配置并选择 Create catalog(创建目录)。

  5. 创建完成后,catalog 详情页会显示 Catalog URI 和 Warehouse name。请记下这些值以备后用。

2. 创建 API 令牌

Iceberg 客户端(包括 PyIceberg ↗)必须使用同时具有 R2 和 catalog 权限的 R2 API 令牌 向 catalog 进行身份验证。

  1. 在 Cloudflare 仪表板中,前往 R2 object storage(R2 对象存储) 页面。

    前往 Overview(概览) ↗
  2. 选择 Manage API tokens(管理 API 令牌)。

  3. 选择 Create API token(创建 API 令牌)。

  4. 选择 R2 Token(R2 令牌) 文本以编辑 API 令牌名称。

  5. 在 Permissions 下,选择 Admin Read & Write 权限。本指南会创建表并向其中写入数据,因此需要读写权限。如果客户端只需查询,可以改用 Admin Read only 令牌。有关选择适当权限级别的详细信息,请参阅对 Iceberg 引擎进行身份验证。

  6. 选择 Create API Token(创建 API 令牌)。

  7. 记下 Token value。

3. 安装 uv

您需要安装 Python 包管理器。本指南使用 uv ↗。如果尚未安装 uv,请按照安装 uv 指南 ↗操作。

4. 使用 uv 安装 marimo 并设置项目

我们将使用 marimo ↗ 作为 Python notebook。

  1. 创建用于存放 notebook 的目录:

    mkdir r2-data-catalog-notebook
  2. 进入新目录:

    cd r2-data-catalog-notebook
  3. 初始化新的 uv 项目(这将创建 .venv 和 pyproject.toml):

    uv init
  4. 添加 marimo 和所需依赖项:

    uv add marimo pyiceberg pyarrow pandas

5. 创建 Python notebook 与数据仓库交互

  1. 创建名为 r2-data-catalog-tutorial.py 的文件。

  2. 将以下代码片段粘贴到 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 Basin 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()
  3. 将 CATALOG_URI、WAREHOUSE 和 TOKEN 变量分别替换为第 1 节和第 2 节中的值。

  4. 在浏览器中启动 notebook 编辑器:

    uv run marimo edit r2-data-catalog-tutorial.py

    notebook 连接到 catalog 后,catalog 及其 namespace 和表将显示在 marimo 的 Datasources 面板中。

在上面的 Python notebook 中,您将:

  1. 连接到 catalog。
  2. 创建 default namespace。
  3. 创建简单的 PyArrow 表。
  4. 在 default namespace 中创建(或加载)people 表。
  5. 向表追加示例数据。
  6. 打印表内容。
  7. (可选)删除本教程创建的 people 表。

了解更多

管理 catalog

在存储桶上启用或禁用 Basin Catalog、获取配置详情,并对 Iceberg 引擎进行身份验证。

这篇文档对您有帮助吗?