はじめに · Cloudflare R2 Data Catalog ドキュメント

このガイドでは、次の手順を説明します。

最初の R2 バケットを作成し、そのデータカタログを有効にする。
クエリエンジンがデータカタログへ認証するために必要な API トークンを作成する。
PyIceberg ↗ を使い、marimo ↗ の Python ノートブックで最初の Iceberg テーブルを作成する。
PyIceberg ↗ を使い、サンプルデータをテーブルへ読み込み、クエリする。

前提条件

Cloudflare アカウント ↗ に登録します。
Node.js ↗ をインストールします。

Node.js のバージョンマネージャー

権限の問題を避け、Node.js のバージョンを切り替えられるよう、Volta ↗ や nvm ↗ などの Node バージョンマネージャーを使います。このガイドの後半で説明する Wrangler には、Node バージョン 16.17.0 以降が必要です。

1. R2 バケットを作成し、データカタログを有効にする

まだログインしていない場合は、次を実行します。
```
npx wrangler login
```

R2 バケットを作成します。

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

バケットでカタログを有効にします。
```
npx wrangler r2 bucket catalog enable r2-data-catalog-tutorial
```
このコマンドを実行したら、Warehouse と Catalog URI を控えてください。あとで使います。

Cloudflare ダッシュボードで R2 Data Catalog ページを開きます。
R2 Data Catalog を開く ↗
Create catalog を選びます。
バケット名 r2-data-catalog-tutorial を入力します。バケットがまだない場合、ウィザードは自動で作成します。必要に応じて Location Hint を選びます。
設定を確認し、Create catalog を選びます。
作成後、カタログの詳細ページに Catalog URI と Warehouse name が表示されます。あとで使うため、これらの値を控えてください。

2. API トークンを作成する

Iceberg クライアント（PyIceberg ↗ を含む）は、R2 とカタログの両方の権限を持つ R2 API トークンでカタログに認証する必要があります。

Cloudflare ダッシュボードで R2 object storage ページを開きます。
Overview を開く ↗
Manage API tokens を選びます。
Create API token を選びます。
R2 Token のテキストを選び、API トークン名を編集します。
Permissions で Admin Read & Write 権限を選びます。このガイドではテーブルの作成と書き込みを行うため、読み取りと書き込みの権限が必要です。クエリ専用のクライアントでは、代わりに Admin Read only トークンを使えます。適切な権限レベルの選び方は、Iceberg エンジンを認証するを参照してください。
Create API Token を選びます。
Token value を控えます。

3. uv をインストールする

Python のパッケージマネージャーをインストールする必要があります。このガイドでは uv ↗ を使います。uv をまだインストールしていない場合は、uv のインストールガイド ↗ に従ってください。

4. marimo をインストールし、uv でプロジェクトをセットアップする

Python ノートブックとして marimo ↗ を使います。

ノートブックを保存するディレクトリを作成します。
```
mkdir r2-data-catalog-notebook
```
作成したディレクトリに移動します。
```
cd r2-data-catalog-notebook
```
新しい uv プロジェクトを初期化します（.venv と pyproject.toml が作成されます）。
```
uv init
```
marimo と必要な依存関係を追加します。
```
uv add marimo pyiceberg pyarrow pandas
```

5. データウェアハウスを操作する Python ノートブックを作成する

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 で控えた値に置き換えます。
ブラウザーでノートブックエディターを起動します。
```
uv run marimo edit r2-data-catalog-tutorial.py
```
ノートブックがカタログに接続すると、marimo の Datasources パネルにカタログ、名前空間、テーブルが表示されます。

上記の Python ノートブックでは、次を行います。

カタログへ接続する。
default 名前空間を作成する。
簡単な PyArrow テーブルを作成する。
default 名前空間に people テーブルを作成する（または読み込む）。
サンプルデータをテーブルへ追加する。
テーブルの内容を表示する。
（任意）このチュートリアルで作成した people テーブルを削除する。

さらに学ぶ

カタログの管理

バケットで R2 Data Catalog を有効または無効にし、設定の詳細を取得し、Iceberg エンジンを認証します。

Iceberg エンジンに接続する

Apache Spark やその他の一般的なクエリエンジンの詳細なセットアップ手順を確認します。