← R2 SQL / r2-sql

Запрос данных

Запрос Apache Iceberg ↗ таблиц, управляемых R2 Data Catalog. Запросы R2 SQL можно выполнять через Wrangler или HTTP API.

Чтобы выполнять запросы к данным с помощью R2 SQL, вам понадобится имя warehouse, связанное с вашим catalog. Чтобы получить его, выполните r2 bucket catalog get команда:

npx wrangler r2 bucket catalog get <BUCKET_NAME>

Также вы можете найти это на панели управления, перейдя в Объектное хранилище R2 странице, выбрав бакет, переключившись на Настройки вкладку, прокрутив до R2 Data Catalog, и поиск Имя хранилища.

Для начала установите npm ↗. Затем установите Wrangler, интерфейс командной строки платформы разработчика.

Для выполнения запросов Wrangler требуется API токен с правами доступа к R2 Data Catalog, хранилищу R2 и R2 SQL. r2 sql query команда ищет токен в WRANGLER_R2_SQL_AUTH_TOKEN переменную окружения.

Настройте рабочую среду:

export WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Или создайте .env файл с помощью:

WRANGLER_R2_SQL_AUTH_TOKEN=YOUR_API_TOKEN

Где YOUR_API_TOKEN это токен, который вы создали с помощью необходимые разрешения. Дополнительную информацию об установке переменных среды см. Системные переменные окружения Wrangler.

Чтобы выполнить SQL-запрос, выполните r2 sql query команда:

npx wrangler r2 sql query <WAREHOUSE> "SELECT * FROM namespace.table_name limit 10;"

Полный список поддерживаемых SQL-команд см. в Справочник R2 SQL.

Ниже приведён пример использования R2 SQL через конечную точку REST API:

curl -X POST \
  "https://api.sql.cloudflarestorage.com/api/v1/accounts/{ACCOUNT_ID}/r2-sql/query/{BUCKET_NAME}" \
  -H "Authorization: Bearer ${WRANGLER_R2_SQL_AUTH_TOKEN}" \
  -H "Content-Type: application/json" \
  -d '{
    "query": "SELECT * FROM namespace.table_name limit 10;"
  }'

API требует токен API с соответствующими разрешениями в заголовке Authorization. См. Аутентификация для получения сведений о создании токена.

Полный список поддерживаемых SQL-команд см. в Справочник R2 SQL.

Чтобы выполнять запросы к данным с помощью R2 SQL, вы должны указать токен API Cloudflare с разрешениями R2 SQL, R2 Data Catalog и R2 storage. Эти разрешения необходимы R2 SQL для доступа к метаданным каталога и чтения исходных файлов данных, хранящихся в R2.

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

• Доступ к R2 Data Catalog (только чтение)
• Доступ к хранилищу R2 (Admin, чтение и запись)
• Доступ к R2 SQL (только чтение)

Используйте это значение токена для WRANGLER_R2_SQL_AUTH_TOKEN переменную окружения при выполнении запросов через Wrangler или в заголовке Authorization при использовании REST API.

Чтобы создать токен API программным способом для использования с R2 SQL, вам потребуется указать группы разрешений R2 SQL, 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": "f45430d92e2b4a6cb9f94f2594c141b8",
				"name": "Workers R2 SQL Read"
			},
			{
				"id": "d229766a2f7f4d299f20eaa8c9b1fde9",
				"name": "Workers R2 Data Catalog Write"
			},
			{
				"id": "bf7481a1826f439697cb59a20b22293e",
				"name": "Workers R2 Storage Write"
			}
		]
	}
]

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