← R2 Data Catalog / r2-data-catalog

Správa katalogů

Naučíte se:

• Povolení a zakázání R2 Data Catalog na vašich bucketech.
• Povolení a zakázání údržba tabulek funkce jako kompaktace a expirace snímků.
• Ověřujte enginy Iceberg pomocí tokenů API.

Povolení katalogu pro bucket zapne rozhraní REST catalog a poskytne Catalog URI a Název warehouse vyžadovaná klienty Iceberg. Po povolení můžete v daném bucketu vytvářet tabulky Iceberg a spravovat je.

npx wrangler r2 bucket catalog enable <BUCKET_NAME>

Když deaktivujete katalog u bucketu, okamžitě přestane obsluhovat požadavky z rozhraní katalogu. Všechny odkazy na tabulky Iceberg uložené v tomto katalogu se stanou nedostupnými, dokud katalog znovu neaktivujete.

npx wrangler r2 bucket catalog disable <BUCKET_NAME>

Komprimace zlepšuje výkon dotazů tím, že slučuje mnoho malých souborů vytvořených při příjmu dat do menšího počtu větších souborů podle nastavené target file size. Další informace o kompaktaci a jejím přínosu najdete v O kompaktaci.

# 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

Po zapnutí se kompaktace zpětně použije na všechny existující tabulky (u kompaktace na úrovni katalogu), nebo na zadanou tabulku (u kompaktace na úrovni tabulky).

Zakázáním komprimace zabráníte jejímu spuštění pro všechny tabulky (na úrovni katalogu) nebo pro konkrétní tabulku (na úrovni tabulky). Kdykoli ji můžete znovu povolit.

# 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>

Vypršení platnosti snímků automaticky odstraňuje staré snímky tabulky a veškeré soubory bez odkazů, čímž snižuje režii metadat a náklady na úložiště. Můžete nastavit:

• Maximální stáří snapshotu - Snímky starší než tato doba jsou expirovány. Zadejte hodnotu následovanou jednotkou (d pro dny, h pro hodiny, m pro minuty, s pro sekundy). Například 7d expiruje snímky starší než 7 dní.
• Minimální počet uchovávaných snapshotů - Minimální počet snímků, které se mají zachovat bez ohledu na jejich stáří.

# 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

Zakázání expirace snímků zabrání jejímu spuštění pro všechny tabulky (na úrovni katalogu) nebo pro konkrétní tabulku (na úrovni tabulky). Expiraci snímků můžete kdykoli znovu povolit.

# 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>

Chcete-li připojit svůj Iceberg engine k R2 Data Catalog, musíte zadat token Cloudflare API s obě oprávnění R2 Data Catalog a oprávnění R2 Storage. Enginy Iceberg komunikují s R2 Data Catalog při provádění operací s tabulkami. Katalog enginům také poskytuje přihlašovací údaje SigV4, které jsou potřeba pro přístup k podkladovým datovým souborům uloženým v R2.

R2 Data Catalog podporuje tokeny jak pouze pro čtení, tak pro čtení a zápis:

• Pouze pro čtení operace (například výpis oborů názvů, načítání tabulek a dotazování na data) vyžadují token s oprávněním pro čtení z R2 Data Catalog a R2 Storage.
• Zápis operace (například vytváření nebo rušení tabulek a potvrzování transakcí) vyžadují token s oprávněním pro čtení i zápis do R2 Data Catalog a R2 Storage.

Pro query enginy a klienty, kteří pouze čtou data (například R2 SQL, DuckDB nebo čtečky PyIceberg), použijte token pouze pro čtení, a pro enginy a pipeline, které vytvářejí tabulky nebo zapisují data, použijte token pro čtení i zápis.

Vytvořte Token R2 API s oprávněními odpovídajícími vaší zátěži:

• Admin Read & Write je určen pro enginy a pipeliny, které čtou i zapisují data. Zahrnuje přístup pro čtení i zápis do R2 Data Catalog i úložiště R2.
• Admin Read only je určen pro dotazovací enginy a klienty, kteří pouze čtou data. Zahrnuje přístup pro čtení do R2 Data Catalog i úložiště R2.

Když výsledný token předáte svému Iceberg enginu, získá tím možnost spravovat metadata katalogu a provádět datové operace, tedy čtení nebo zápis do R2.

Chcete-li vytvořit token API programově pro použití s R2 Data Catalog, musíte zadat skupiny oprávnění R2 Data Catalog i R2 Storage ve svém Access Policy.

Pro enginy a pipeline, které vytvářejí tabulky nebo zapisují data, použijte skupiny oprávnění pro čtení i zápis:

[
	{
		"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"
			}
		]
	}
]

Pro query enginy a klienty, kteří pouze čtou data, použijte skupiny oprávnění pro čtení:

[
	{
		"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"
			}
		]
	}
]

Další informace o vytváření API tokenů pro R2 Data Catalog pomocí API, včetně požadovaných skupin oprávnění a příkladů použití, najdete v Vytvoření tokenů API podle dokumentace k API.

Local Uploads zapisuje data objektů do nejbližšího umístění a poté je asynchronně zkopíruje do vašeho bucketu. Data jsou okamžitě dotazovatelná a zůstávají silně konzistentní. Díky tomu se může výrazně zlepšit latence zápisů od klientů Apache Iceberg mimo region příslušného bucketu R2 Data Catalog.

Chcete-li povolit R2 Local Uploads, můžete použít následující příkaz Wrangler:

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

• R2 Data Catalog v současnosti nepodporuje R2 buckety mimo výchozí jurisdikci.