← R2 Data Catalog / r2-data-catalog

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

Вы узнаете, как:

• Включение и отключение R2 Data Catalog для ваших бакетов.
• Включение и отключение обслуживание таблиц такие функции, как сжатие и истечение срока действия снимков.
• Аутентифицируйте движки Iceberg с помощью API токенов.

Включение каталога для бакета активирует интерфейс REST-каталога и предоставляет Catalog URI и Имя хранилища необходимые клиентам Iceberg. После включения вы можете создавать таблицы Iceberg в этом бакете и управлять ими.

npx wrangler r2 bucket catalog enable <BUCKET_NAME>

Когда вы отключаете каталог для bucket, он немедленно перестаёт обрабатывать запросы через интерфейс каталога. Все ссылки на таблицы Iceberg, хранящиеся в этом каталоге, становятся недоступны, пока вы снова его не включите.

npx wrangler r2 bucket catalog disable <BUCKET_NAME>

Уплотнение повышает производительность запросов, объединяя множество небольших файлов, созданных при загрузке данных, в меньшее количество более крупных файлов в соответствии с заданным target file size. Дополнительную информацию об уплотнении и его пользе см. в Об уплотнении.

# Enable catalog-level compaction (all tables)
npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> --target-size 128 --token <API_TOKEN>

# Enable compaction for a specific table
npx wrangler r2 bucket catalog compaction enable <BUCKET_NAME> <NAMESPACE> <TABLE> --target-size 128

После включения уплотнение применяется задним числом ко всем существующим таблицам (при уплотнении на уровне каталога) или к указанной таблице (при уплотнении на уровне таблицы).

Отключение уплотнения останавливает этот процесс для всех таблиц (на уровне каталога) или для конкретной таблицы (на уровне таблицы). Вы можете снова включить его в любой момент.

# Disable catalog-level compaction (all tables)
npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME>

# Disable compaction for a specific table
npx wrangler r2 bucket catalog compaction disable <BUCKET_NAME> <NAMESPACE> <TABLE>

Истечение срока действия снимков автоматически удаляет старые снимки таблиц и файлы данных, на которые нет ссылок, снижая накладные расходы на метаданные и затраты на хранение. Вы можете настроить:

• Максимальный возраст снимка - Снимки старше этого срока считаются просроченными. Укажите значение, а после него единицу измерения (d для дней, h для часов, m для минут, s для секунд). Например, 7d считает просроченными снимки старше 7 дней.
• Минимальное число сохраняемых снимков - Минимальное количество снимков, которые нужно сохранять, независимо от их возраста.

# Enable catalog-level snapshot expiration (all tables)
npx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> \
  --token <API_TOKEN> \
  --older-than-days 7 \
  --retain-last 10

# Enable snapshot expiration for a specific table
npx wrangler r2 bucket catalog snapshot-expiration enable <BUCKET_NAME> <NAMESPACE> <TABLE> \
  --older-than-days 2 \
  --retain-last 5

Отключение истечения срока действия снимков останавливает этот процесс для всех таблиц (на уровне каталога) или для конкретной таблицы (на уровне таблицы). Вы можете снова включить истечение срока действия снимков в любой момент.

# Disable catalog-level snapshot expiration (all tables)
npx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME>

# Disable snapshot expiration for a specific table
npx wrangler r2 bucket catalog snapshot-expiration disable <BUCKET_NAME> <NAMESPACE> <TABLE>

Чтобы подключить движок Iceberg к R2 Data Catalog, необходимо указать API-токен Cloudflare с оба права доступа R2 Data Catalog и права доступа к хранилищу R2. Движки Iceberg взаимодействуют с R2 Data Catalog для выполнения операций с таблицами. Каталог также предоставляет движкам учётные данные SigV4, необходимые для доступа к файлам данных, хранящимся в R2.

R2 Data Catalog поддерживает токены как только для чтения, так и для чтения и записи:

• Только для чтения операции (например, получение списка пространств имён, загрузка таблиц и выполнение запросов к данным) требуют токена с правами на чтение из R2 Data Catalog и хранилища R2.
• Write операции (например, создание или удаление таблиц и подтверждение транзакций) требуют токена с правами на чтение и запись в R2 Data Catalog и хранилище R2.

Используйте токен только для чтения для движков запросов и клиентов, которые только читают данные (например, R2 SQL, DuckDB или PyIceberg readers), и токен для чтения и записи для движков и пайплайнов, которые создают таблицы или записывают данные.

Создайте R2 API-токен с разрешениями, соответствующими вашей нагрузке:

• Admin Read & Write : для движков и конвейеров, которые читают и записывают данные. Включает доступ на чтение и запись как к R2 Data Catalog, так и к хранилищу R2.
• Admin Read only : для движков запросов и клиентов, которые только читают данные. Включает доступ на чтение как к R2 Data Catalog, так и к хранилищу R2.

Передав полученное значение токена движку Iceberg, вы даете ему возможность управлять метаданными каталога и выполнять операции с данными (чтение и запись в R2).

Чтобы создать API-токен программно для использования с R2 Data Catalog, укажите группы разрешений R2 Data Catalog и R2 storage в вашем Access Policy.

Используйте группы разрешений на чтение и запись для движков и пайплайнов, которые создают таблицы или записывают данные:

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "2efd5506f9c8494dacb1fa10a3e7d5b6",
				"name": "Workers R2 Storage Bucket Item Write"
			}
		]
	}
]

Используйте группы разрешений на чтение для движков запросов и клиентов, которые только читают данные:

[
	{
		"id": "f267e341f3dd4697bd3b9f71dd96247f",
		"effect": "allow",
		"resources": {
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_default_my-bucket": "*",
			"com.cloudflare.edge.r2.bucket.4793d734c0b8e484dfc37ec392b5fa8a_eu_my-eu-bucket": "*"
		},
		"permission_groups": [
			{
				"id": "45db74139a62490b9b60eb7c4f34994b",
				"name": "Workers R2 Data Catalog Read"
			},
			{
				"id": "6a018a9f2fc74eb6b293b0c548f38b39",
				"name": "Workers R2 Storage Bucket Item Read"
			}
		]
	}
]

Подробнее о создании API-токенов для R2 Data Catalog через API, включая необходимые группы разрешений и примеры использования, см. Документация по созданию API токенов через API.

Local Uploads записывает данные объекта в ближайшее расположение, а затем асинхронно копирует их в ваш бакет. Данные доступны для запросов сразу же и остаются строго согласованными. Это может значительно снизить задержку записи для клиентов Apache Iceberg, находящихся за пределами региона соответствующего бакета R2 Data Catalog.

Чтобы включить R2 Local Uploads, используйте следующую команду Wrangler:

npx wrangler r2 bucket catalog local-uploads enable <R2_Data_Catalog_BUCKET_NAME>

• В настоящее время R2 Data Catalog не поддерживает бакеты R2 с юрисдикцией, отличной от стандартной.