Управление запросами¶

Просмотр списка активных запросов¶

Эта возможность не поддерживается в текущей версии TCS.

Отмена запроса¶

Эта возможность не поддерживается в текущей версии TCS.

Отправка нескольких SQL-инструкций (multi-statement)¶

На HTTP-адрес /sql можно отправлять сразу несколько SQL-инструкций, разделенных точкой с запятой (;). Это могут быть любые SQL-инструкции, поддерживаемые TCS.

TCS обрабатывает инструкции в указанном порядке и возвращает список статусов.

Если обработка какой-либо инструкции заканчивается ошибкой, то TCS прекращает обработку инструкций и возвращает список статусов.

Пример запроса:

POST http://localhost:7777/sql HTTP/1.1
Content-Type: application/json

SELECT name FROM users; INSERT INTO names SELECT name FROM users; SELECT * FROM names ORDER BY name

Если, например, вторая инструкция (INSERT INTO names SELECT name FROM users) завершится ошибкой, то третья инструкция тоже не выполнится.

Управление транзакциями¶

В текущей версии TCS ни в одном из интерфейсов (HTTP, JDBC\ADBC) не поддерживается интерактивное управление транзакциями (COMMIT, ROLLBACK).

Однако, если SQL-операция по изменению данных (DELETE, INSERT, UPDATE) затрагивает большой массив данных (больше максимального размера пакета), то она разбивается на несколько под-операций, которые далее обрабатываются как единая транзакция. При этом если какая-либо из под-операций завершается некорректно, то оставшиеся под-операции не выполняются, но (в отличие от классических транзакций) результат предыдущих под-операций не откатывается.

Пример: При удалении 50 тысяч строк создается 7 под-операций удаления (50000 / 8192 примерно равно 6,1). Если пятая под-операция из этих 7 завершится некорректно, то эта и остальные две под-операции не применятся, но результат первых 4 операций останется в базе.

Отправка параметризованных SQL-запросов по HTTP¶

TCS поддерживает отправку параметризованных SQL-запросов по HTTP. Параметры запроса передаются списком в соответствующей переменной:

• args – список параметров при однократном вызове запроса (поддерживается для всех видов запросов):

  curl -u tcs:tcs -X POST -H "Content-Type: application/json" -d '{ "query": "SELECT * FROM t WHERE a>$1", "args": [0] }' http://localhost:7777/sql
  

• bulk_args – список списков параметров для множественных вызовов (поддерживается для запросов INSERT, UPDATE, DELETE):

  curl -u tcs:tcs -X POST -H "Content-Type: application/json" -d '{ "query": "INSERT INTO t VALUES($1, $2)", "bulk_args": [[1,1], [2,2]] }' http://localhost:7777/sql
  

Принудительная маршрутизация запросов¶

В режиме проксирования экземпляры Scheduler могут принудительно отправлять запросы лишь на те экземпляры Storage, которые настроены на работу только в режиме чтения (read-only) – либо наборот, принудительно исключать такие экземпляры Storage из маршрутизации.

Для отправки запроса на определенный вид экземпляров Storage нужно в заголовке запроса указать параметр x-tcs-route и тот тип экземпляров Storage, на которые нужно маршрутизировать запрос:

• ro для отправки на экземпляры, настроенные только на чтение;

• rw для исключения read-only экземпляров из маршрутизации (в этом случае запрос будет отправлен на экземпляр, настроенный на чтение-запись);

• any для отправки на все типы экземпляров (это аналогично тому, когда заголовок x-tcs-route не указан).

Балансировка нагрузки для таких запросов осуществляется только среди указанного типа экземпляров Storage.

Далее приводятся примеры отправки запросов на RW-экземпляр Storage для разных интерфейсов.

• Для ADBC/JDBC:

  header_key = f"{DatabaseOptions.RPC_CALL_HEADER_PREFIX.value}x-tcs-route"
               db_kwargs[header_key] = rw
  
        self.conn = adbc_driver_flightsql.dbapi.connect(
            self.uri,
            db_kwargs=db_kwargs,
            autocommit=True,
        )
  
  

• Для HTTP:

  curl --location-trusted -L -X POST -u tcs:tcs -H "x-tcs-route:rw" -d 'CREATE TABLE t(a int)' http://localhost:7780/sql
  

Включение схемы данных в ответ¶

По умолчанию, ответы на запросы к TCS содержат массив данных без указания схемы. Например:

$ curl -u tcs:tcs -d 'insert into t values(1)' http://127.0.0.1:7777/sql
{"responses":[{"is_success":true,"rows":[{"count":1}],"timings":{"collect":"494.295µs"}}]}%

При необходимости можно включить в ответ схему данных. Для этого в заголовке запроса нужно указать параметр x-tcs-include-schema: true. Тогда в начале ответа возвращается схема данных в формате колонка:тип. Причем схема данных включается в ответ, даже если возвращается 0 строк. Например:

$ curl -u tcs:tcs  -d 'insert into t values(1)' -H 'x-tcs-include-schema: true' http://127.0.0.1:7777/sql
{"responses":[{"is_success":true,"schema":[{"name":"count","type":"UInt64"}],"rows":[{"count":1}],"timings":{"collect":"311.063µs"}}]}

Работа со сложными запросами¶

TCS не накладывает ограничений на следующее:

• глубина вложенности подзапросов;

• количество таблиц\представлений, участвующих в запросе;

• количество полей данных в результате;

• количество подзапросов.

Разрешено использовать подзапросы, а также расчетные значения подзапросов в последующих подзапросах.

Работа с пользовательскими функциями и процедурами¶

Текущая версия TCS не поддерживает работу с пользовательскими функциями/процедурами.