← R2 Data Catalog / r2-data-catalog
Начало работы
Это руководство проведёт вас через следующие шаги:
- Создание первой Бакет R2 и включив её каталог данных.
- Создание API-токен необходимые движкам запросов для аутентификации в вашем каталоге данных.
- Использование PyIceberg ↗ для создания первой таблицы Iceberg в marimo ↗ блокнот Python.
- Использование PyIceberg ↗ для загрузки примера данных в таблицу и выполнения запросов к ней.
Предварительные требования
- Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
- Установка
Node.js↗.
менеджер версий Node.js
Используйте менеджер версий Node, например Volta ↗ или nvm ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. 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 ↗ -
Выберите Создание каталога.
-
Введите имя бакета
r2-data-catalog-tutorial. Мастер автоматически создает бакет, если он еще не существует. При необходимости можно указать Location Hint. -
Проверьте конфигурацию и выберите Создание каталога.
-
После создания на странице сведений о каталоге отображаются ваши Catalog URI и Имя хранилища. Сохраните эти значения, они понадобятся позже.
2. Создайте API токен
Клиенты Iceberg (включая PyIceberg ↗) должен пройти аутентификацию в каталоге с помощью R2 API-токен с правами доступа как к R2, так и к каталогу.
-
На панели управления Cloudflare перейдите к разделу Объектное хранилище R2 страницу.
Перейдите в Обзор ↗ -
Выберите Управление API-токенами.
-
Выберите Создание API-токена.
-
Выберите R2 Token текст, чтобы изменить имя своего API токена.
-
В разделе Разрешения, выберите Admin Read & Write прав доступа. В этом руководстве создаются таблицы и выполняется запись в них, поэтому требуются права на чтение и запись. Для клиентов, которые только выполняют запросы, можно использовать вместо этого Admin Read only токен. Подробнее о выборе подходящего уровня прав доступа см. в Настройте аутентификацию для своего движка Iceberg.
-
Выберите Создать API-токен.
-
Обратите внимание на Значение токена.
3. Установите uv
Вам потребуется установить менеджер пакетов Python. В этом руководстве используется uv ↗. Если у вас еще не установлен uv, следуйте руководство по установке uv ↗.
4. Установите marimo и настройте проект с помощью uv
Мы будем использовать marimo ↗ в виде блокнота Python.
-
Создайте каталог для хранения блокнота:
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После того как ваш ноутбук подключится к каталогу, сам каталог вместе с его пространствами имён и таблицами появится на панели Datasources в marimo.
В приведённом выше Python-ноутбуке вы:
- Подключитесь к своему каталогу.
- Создайте
defaultпространство имён. - Создайте простую таблицу PyArrow.
- Создайте (или загрузите)
peopleтаблицу вdefaultпространство имён. - Добавьте примерные данные в таблицу.
- Выведите содержимое таблицы.
- (Необязательно) Удалите
peopleтаблицу, которую мы создали для этого руководства.