- API-ключ с соответствующими разрешениями
- роль Admin в консоли
Минимальные разрешенияЧтобы отправлять запросы к конечной точке API, API-ключу нужна роль организации
Member с доступом к сервису Query Endpoints. Роль базы данных настраивается при создании конечной точки.1
Создание сохраненного запроса
Если у вас уже есть сохраненный запрос, этот шаг можно пропустить.Откройте новую вкладку запроса. Для примера мы будем использовать датасет YouTube, который содержит примерно 4,5 миллиарда записей.
Следуйте инструкциям в разделе “Create table”, чтобы создать таблицу в вашем сервисе Cloud и вставить в нее данные.В качестве примера мы получим 10 лучших загрузчиков по среднему числу просмотров на видео с параметром Обратите внимание, что этот запрос содержит параметр (
Затем сохраните запрос:
Дополнительную информацию о сохраненных запросах можно найти в разделе “Saving a query”.
year, который задает пользователь.year), который выделен в примере выше.
Параметры запроса можно задавать в формате { } вместе с типом параметра.
Редактор запросов в консоли SQL автоматически распознает выражения параметров в запросах к ClickHouse и показывает отдельное поле ввода для каждого параметра.Давайте быстро выполним этот запрос, чтобы убедиться, что он работает: укажите год 2010 в поле переменных запроса справа в редакторе SQL:

2
Настройка эндпоинта Query API
Эндпоинты Query API можно настраивать прямо из представления запроса: нажмите кнопку Share и выберите 
После выбора ключа API вам будет предложено:
Для удобства ниже приведена команда
API Endpoint.
Затем вам будет предложено указать, какие ключ API смогут обращаться к этому эндпоинту Query API:
- Выбрать роль базы данных, которая будет использоваться для выполнения запроса (
Full access,Read onlyилиCreate a custom role) - Указать разрешенные домены CORS
curl, чтобы вы могли отправить тестовый запрос:
curl, отображаемая в интерфейсе:3
Параметры Query API
Параметры в запросе можно задавать с помощью синтаксиса
{parameter_name: type}. Эти параметры будут автоматически обнаружены, а пример тела запроса будет содержать объект queryVariables, через который их можно передавать.4
Тестирование и мониторинг
После создания эндпоинта Query API вы можете проверить его работу с помощью 
После отправки первого запроса сразу справа от кнопки Share должна появиться новая кнопка. При нажатии на нее откроется выдвижная панель с данными мониторинга по запросу:
curl или любого другого HTTP-клиента:

Когда использовать GET:
- Простые запросы без сложных вложенных данных
- Параметры легко передаются в URL-кодировке
- Кэширование использует преимущества семантики HTTP GET
- Сложные переменные запроса (массивы, объекты, длинные строки)
- Когда тело запроса предпочтительнее с точки зрения безопасности и конфиденциальности
- Потоковая загрузка файлов или больших объёмов данных
Статус:
200 OK
Запрос успешно выполнен.
- Убедитесь, что запрос содержит действительные учетные данные для аутентификации
- Проверьте
queryEndpointIdиqueryVariablesперед отправкой - Реализуйте корректную обработку ошибок с понятными сообщениями
Чтобы перейти с версии 1 на версию 2:
- Добавьте заголовок
x-clickhouse-endpoint-upgradeсо значением1 - Добавьте заголовок
x-clickhouse-endpoint-versionсо значением2
- Поддержку всех форматов ClickHouse
- Возможность потоковой передачи ответов
- Более высокую производительность и расширенную функциональность
- cURL
- JavaScript
- GET (cURL)
- POST (cURL)
- JavaScript
Ответ
- GET (cURL)
- POST (cURL)
- JavaScript
Ответ
- cURL
- JavaScript
- GET (cURL)
- POST (cURL)
- JavaScript
- TypeScript
Вывод
./samples/my_first_table_2024-07-11.csv со следующим содержимым: