跳转到内容
搜索文档

快速入门

最后更新 查看 MarkdownAgent 设置

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

前提条件

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

Node.js 版本管理器

使用 Volta ↗ 或 nvm ↗ 等 Node 版本管理器,以避免权限问题并切换 Node.js 版本。本指南后续将介绍的 Wrangler 需要 Node 版本 16.17.0 或更高。

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

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

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

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

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

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

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

    Go to R2 Data Catalog ↗
  2. 选择 Create catalog(创建目录)。

  3. 输入存储桶名称 r2-data-catalog-tutorial。由于此存储桶尚不存在,向导将为您创建它。可选地选择位置提示。

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

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

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

2. 创建 API 令牌

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

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

    Go to 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 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()
  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

在存储桶上启用或禁用 R2 Data Catalog、检索配置详情,并为 Iceberg 引擎进行身份验证。

这篇文档对您有帮助吗?