/datamarts/{datamart}/entities/{entity}/upload

Содержание раздела

Способы установки значения sys_op
URL
Заголовки запроса
Тело запроса
Примеры запросов
Формат ответа

POST-метод выполняет потоковую загрузку данных в указанную таблицу.

Загрузка данных возможна в форматах CSV и Avro. Формат данных задается в заголовке Content-Type, а сами данные передаются в теле запроса.

При разрыве соединения во время потоковой загрузки система по умолчанию завершает соответствующую операцию записи как неуспешную и отменяет данные, которые уже успели загрузиться в этой операции. Если при разрыве соединения требуется завершить операцию как успешную и сохранить загруженные данные, включите опцию commitOnDisconnect в URL-строке запроса.

Способы установки значения sys_op

При загрузке данных в логические таблицы можно задать значение sys_op следующими способами:

задать общее значение для всех записей с помощью опции sysOp в URL-строке запроса;
задать индивидуальные значения для записей, определив в составе каждой записи поле sys_op со значением 0 или 1.

Приоритетным считается общее значение sysOp. Если общее значение не задано, к записи применяется индивидуальное значение sys_op, заданное в самой записи. Если не задано ни общее, ни индивидуальное значение (в том числе, если поле sys_op пустое), запись вставляется в таблицу (sys_op=0).

При загрузке данных в прокси-таблицы и standalone-таблицы опция sysOp игнорируется, а значение поля sys_op, если такое указано, сохраняется в таблицу как есть.

URL

{baseUrl}/api/v1/datamarts/{datamart}/entities/{entity}/upload[?[sysOp={sysOpValue}][&queryId={queryIdValue}][&commitOnDisconnect={booleanValue}]]

Параметры

baseUrl — адрес ноды Prostore, состоящий из IP-адреса или доменного имени и номера порта;
datamart — имя логической базы данных, которой принадлежит целевая таблица. Для загрузки данных в standalone-таблицу укажите логическую БД, которой принадлежит связанная внешняя writable-таблица;
entity — имя таблицы, куда загружаются данные. Возможные значения:
- имя логической таблицы любого вида,
- имя прокси-таблицы,
- имя внешней writable-таблицы, связанной с целевой standalone-таблицей;
sysOpValue — значение опции sysOp;
queryIdValue — значение опции queryId;
booleanValue — значение опции commitOnDisconnect.

Опция sysOp

Устанавливает значение sys_op для всех загружаемых записей.

Опция предназначена для загрузки данных в логические таблицы; для прокси- и standalone-таблиц опция игнорируется. Опция имеет приоритет над индивидуальными значениями записей, если они заданы для записей в столбце sys_op.

Возможные значения:

0 — вставить записи в таблицу, то есть добавить новые записи и (или) обновить текущие записи таблицы загруженными данными;
1 — удалить из таблицы записи, соответствующие загруженным.

Удаление данных с помощью потоковой загрузки возможно только из логических таблиц. Подробнее см. в разделе О системе Prostore > Основные понятия > Загрузка данных.

Опция queryId

Устанавливает идентификатор запроса SQL+, по которому можно отследить обработку запроса с помощью логов.

Опция commitOnDisconnect

Управляет загруженными данными и завершением операции записи при разрыве соединения во время потоковой загрузки, как показано в таблице ниже.

Целевая таблица	commitOnDisconnect=false (по умолчанию)	commitOnDisconnect=true
Логическая таблица	1. Данные, загруженные в буфер и датасорсы, отменяются 2. Операция записи завершается как неуспешная	1. Данные из буфера догружаются в датасорсы 2. Данные, загруженные в датасорсы, сохраняются как текущая версия данных в логической БД 3. Операция записи завершается как успешная
Прокси- или standalone-таблица	Данные, загруженные в буфер, отменяются	Данные, загруженные в буфер, догружаются в датасорсы

Заголовки запроса

Заголовок x-request-id

Опциональный заголовок задает уникальный идентификатор HTTP-запроса. Если не указан, система генерирует UUID-значение и возвращает его в качестве идентификатора в ответе.

Заголовок Authorization

Опциональный заголовок задает тип аутентификации и авторизационный токен (JWT). Возможное значение заголовка — Bearer.

Подробнее об аутентификации запросов см. в разделе Аутентификация.

Заголовок Content-Type

Обязательный заголовок определяет формат данных, содержащихся в теле запроса. Возможные значения:

text/csv — CSV-формат;
application/avro — Avro-формат.

Тело запроса

Тело запроса содержит загружаемые данные в CSV- или Avro-формате в виде строки.

Формат данных должен соответствовать формату, заданному в заголовке Content-Type. Данные должны иметь полное и корректное представление, то есть включать:

CSV-заголовок и строки данных — в CSV-формате;
Avro-файл, состоящий из заголовка со схемой данных и блоков данных, — в Avro-формате.

Разделители, кавычки, символы экранирования и способ указания null-значений в CSV-данных должны соответствовать настроенным в секции конфигурации csvParser.

Avro-данные могут быть упакованы без сжатия или со сжатием по любому из алгоритмов. Степень сжатия и алгоритм указывать в запросе не нужно.

Если в загружаемых данных пропущены некоторые столбцы целевой таблицы, при записи данных в таблицу эти столбцы заполняются значениями, используемыми в целевой СУБД по умолчанию (обычно это NULL).

Примеры запросов

В этой секции приведены примеры как с авторизационным токеном, так и без него. Примеры без токена предназначены для случаев, когда аутентификация отключена, с токеном — для случаев, когда аутентификация включена.

Загрузка данных в CSV-формате без дополнительных опций

Запросы без дополнительных опций, показанные ниже, вставляют записи с sys_op=0 и удаляют записи с sys_op=1. При разрыве соединения результаты загрузки отменяются.

Запрос без токена:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload' \
  -H 'accept: application/json' \
  -H 'x-request-id: f65ae2b4-7ee0-4e8b-aab4-fa856d32c723' \
  -H 'Content-Type: text/csv' \
  -d 'id;varchar_col;sys_op
     1;aaa;0
     2;bbb;1
     3;ccc;0'

Запрос с токеном:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload' \
  -H 'accept: application/json' \
  -H 'x-request-id: f5cd0be6-7047-46e2-a7f3-2d7dcc79b53f' \
  -H 'Content-Type: text/csv' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
  -d 'id;varchar_col;sys_op
     1;aaa;0
     2;bbb;1
     3;ccc;0'

Загрузка данных в CSV-формате с дополнительными опциями

Запрос на вставку данных (sysOp=0) с указанным идентификатором запроса (queryId=12345) и сохранением результатов загрузки при разрыве соединения (commitOnDisconnect=true):

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload?sysOp=0&queryId=12345&commitOnDisconnect=true' \
  -H 'accept: application/json' \
  -H 'x-request-id: 8600581d-adde-44ea-b691-a992027f928c' \
  -H 'Content-Type: text/csv' \
  -d 'id;varchar_col
     1;aaa
     2;bbb
     3;ccc'

Запрос на удаление данных (sysOp=1) с указанным идентификатором запроса (queryId=43345) и отменой результатов загрузки при разрыве соединения (commitOnDisconnect=false):

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload?sysOp=1&queryId=43345&commitOnDisconnect=false' \
  -H 'accept: application/json' \
  -H 'x-request-id: 4b6c9d58-d0e0-4911-96d4-838bf95319a5' \
  -H 'Content-Type: text/csv' \
  -d 'id;varchar_col
     1;aaa
     2;bbb
     3;ccc'

Загрузка данных в Avro-формате без дополнительных опций

Запросы без дополнительных опций, показанные ниже, вставляют записи. При разрыве соединения результаты загрузки отменяются.

Запрос без токена:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload' \
  -H 'accept: application/json' \
  -H 'x-request-id: 5db80212-db9d-437a-8e64-4815795b77a5' \
  -H 'Content-Type: application/avro' \
  -d 'string<AVRO>'

Запрос с токеном:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload' \
  -H 'accept: application/json' \
  -H 'x-request-id: 91118e07-03d5-4d76-8f73-3bb2ad4ba449' \
  -H 'Content-Type: application/avro' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
  -d 'string<AVRO>'

Загрузка данных в Avro-формате с дополнительными опциями

Запрос на вставку данных (sysOp=0) с указанным идентификатором запроса (queryId=76765) и сохранением результатов загрузки при разрыве соединения (commitOnDisconnect=true):

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload?sysOp=0&queryId=76765&commitOnDisconnect=true' \
  -H 'accept: application/json' \
  -H 'x-request-id: f1f7a335-e008-4665-9535-e5471305d131' \
  -H 'Content-Type: application/avro' \
  -d 'string<AVRO>'

Запрос на удаление данных (sysOp=1) с указанным идентификатором запроса (queryId=265384) и отменой результатов загрузки при разрыве соединения (commitOnDisconnect=false):

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/entities/sales/upload?sysOp=1&queryId=265384&commitOnDisconnect=false' \
  -H 'accept: application/json' \
  -H 'x-request-id: 2204bc82-714d-4f97-9e3e-fc7909547666' \
  -H 'Content-Type: application/avro' \
  -d 'string<AVRO>'

Формат ответа

Ответ возвращается в JSON-формате.

Варианты ответа:

неуспешный ответ (промежуточный или финальный),
промежуточный успешный ответ,
финальный успешный ответ.

Промежуточные ответы возвращаются только при загрузке по HTTP/2. Финальные ответы возвращаются как при загрузке по HTTP/2, так и по HTTP/1.1.

Неуспешный ответ

Неуспешный ответ возвращается:

при ошибке загрузки данных;
при разрыве соединения, если запрос выполнялся с отключенной опцией commitOnDisconnect.

Пример неуспешного ответа:

{
  "exceptionMessage": "error"
}

Промежуточный успешный ответ

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

Пример промежуточного успешного ответа:

{
  "rowsReceivedTotal": 103
}

Финальный успешный ответ

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

при успешной загрузке всех порций данных из потока загрузки;
при разрыве соединения, если запрос выполнялся с включенной опцией commitOnDisconnect.

Пример финального успешного ответа:

{
  "queryId": "112233",
  "result": [
    {
      "sysCn": 10,
      "ts": "2024-07-22 07:58:11.723",
      "rowsAffected": 1206
    }
  ],
  "metadata": [
    {
      "name": "sysCn",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    },
    {
      "name": "ts",
      "type": "TIMESTAMP",
      "size": 6,
      "nullable": false
    },
    {
      "name": "rowsAffected",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    }
  ],
  "rows": 1,
  "statistics": {
    "elapsedTotalMs": 6338,
    "elapsedDbMs": 459
  }
}