跳转到内容
搜索文档

快速入门

最后更新 查看 MarkdownAgent 设置

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

前提条件

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

Node.js 版本管理器

使用 Voltanvm 等 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

    运行此命令时,请记下 WarehouseCatalog 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 URIWarehouse 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 项目(这将创建 .venvpyproject.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_URIWAREHOUSETOKEN 变量分别替换为第 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 引擎进行身份验证。

这篇文档对您有帮助吗?