INTEGRITY Документация

Начало работы

Это руководство проведёт вас через следующие шаги:

Предварительные требования

  1. Зарегистрируйтесь для получения Аккаунт Cloudflare ↗.
  2. Установка Node.js ↗.

менеджер версий Node.js

Используйте менеджер версий Node, например Volta ↗ или nvm ↗ чтобы избежать проблем с правами доступа и переключать версии Node.js. Wrangler, о котором пойдёт речь далее в этом руководстве, требует версию Node 16.17.0 или более поздней версии.

1. Создайте бакет R2 и включите каталог данных

  1. Если вы ещё не выполнили вход, выполните команду:

    npx wrangler login
  2. Создайте бакет R2:

    npx wrangler r2 bucket create r2-data-catalog-tutorial
  3. Включите каталог для своего бакета:

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

    При выполнении этой команды обратите внимание на Warehouse и Catalog URI. Они понадобятся вам позже.

  1. На панели управления Cloudflare перейдите к разделу R2 Data Catalog страницу.

    Перейдите в R2 Data Catalog ↗
  2. Выберите Создание каталога.

  3. Введите имя бакета r2-data-catalog-tutorial. Мастер автоматически создает бакет, если он еще не существует. При необходимости можно указать Location Hint.

  4. Проверьте конфигурацию и выберите Создание каталога.

  5. После создания на странице сведений о каталоге отображаются ваши Catalog URI и Имя хранилища. Сохраните эти значения, они понадобятся позже.

2. Создайте API токен

Клиенты Iceberg (включая PyIceberg ↗) должен пройти аутентификацию в каталоге с помощью R2 API-токен с правами доступа как к R2, так и к каталогу.

  1. На панели управления Cloudflare перейдите к разделу Объектное хранилище R2 страницу.

    Перейдите в Обзор ↗
  2. Выберите Управление API-токенами.

  3. Выберите Создание API-токена.

  4. Выберите R2 Token текст, чтобы изменить имя своего API токена.

  5. В разделе Разрешения, выберите Admin Read & Write прав доступа. В этом руководстве создаются таблицы и выполняется запись в них, поэтому требуются права на чтение и запись. Для клиентов, которые только выполняют запросы, можно использовать вместо этого Admin Read only токен. Подробнее о выборе подходящего уровня прав доступа см. в Настройте аутентификацию для своего движка Iceberg.

  6. Выберите Создать API-токен.

  7. Обратите внимание на Значение токена.

3. Установите uv

Вам потребуется установить менеджер пакетов Python. В этом руководстве используется uv ↗. Если у вас еще не установлен uv, следуйте руководство по установке uv ↗.

4. Установите marimo и настройте проект с помощью uv

Мы будем использовать marimo ↗ в виде блокнота Python.

  1. Создайте каталог для хранения блокнота:

    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 для работы с хранилищем данных

  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. Запустите редактор ноутбука в браузере:

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

    После того как ваш ноутбук подключится к каталогу, сам каталог вместе с его пространствами имён и таблицами появится на панели Datasources в marimo.

В приведённом выше Python-ноутбуке вы:

  1. Подключитесь к своему каталогу.
  2. Создайте default пространство имён.
  3. Создайте простую таблицу PyArrow.
  4. Создайте (или загрузите) people таблицу в default пространство имён.
  5. Добавьте примерные данные в таблицу.
  6. Выведите содержимое таблицы.
  7. (Необязательно) Удалите people таблицу, которую мы создали для этого руководства.

Подробнее

Управление каталогами

Включайте и отключайте R2 Data Catalog для бакета, получайте данные конфигурации и выполняйте аутентификацию своего движка Iceberg.

Подключение к движкам Iceberg

Ознакомьтесь с подробными инструкциями по настройке Apache Spark и других распространённых движков запросов.