/datamarts[/{datamart}]/query

Содержание раздела
  1. Режимы выполнения запросов
  2. URL
  3. Заголовки запроса
    1. Ограничения x-request-id
  4. Тело запроса
  5. Примеры запросов
    1. Запрос на чтение данных без авторизационного токена
    2. Запрос на чтение данных с авторизационным токеном
    3. Синхронный запрос на обновление данных
    4. Асинхронный запрос на обновление данных
    5. Подготовленный запрос (prepared statement) без токена
    6. Асинхронный подготовленный запрос (prepared statement) с токеном

POST-метод выполняет запрос SQL+, заданный в теле сообщения. Поддерживается как выполнение простого вопроса, так и подготовленного запроса (prepared statement).

Запрос можно выполнить в выбранной логической базе данных. Чтобы выбрать логическую БД, укажите параметр {datamart} в URL метода.

Режимы выполнения запросов

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

Режим выполнения задается параметром async в теле запроса. По умолчанию, если параметр async имеет значение false или не задан, запрос исполняется в синхронном режиме и система возвращает ответ только после завершения обработки запроса; если параметр имеет значение true, ответ возвращается при принятии запроса на обработку, а не по завершении обработки.

URL

{baseUrl}/api/v1/datamarts[/{datamart}]/query[?format={format}]

Параметры:

  • baseUrl — адрес ноды Prostore, состоящий из IP-адреса или доменного имени и номера порта;
  • datamart (опциональный) — имя логической базы данных, используемой по умолчанию;
  • format (опциональный) — формат ответа. Возможные значения:
    • json — JSON-строка (по умолчанию),
    • plain — текстовое представление.

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

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

  • x-request-id — задает уникальный идентификатор HTTP-запроса. Если не указан, система генерирует UUID-значение и возвращает его в качестве идентификатора в ответе;
  • Authorization — задает тип аутентификации и авторизационный токен (JWT). Возможное значение типа аутентификации — Bearer.

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

В асинхронных запросах x-request-id имеет ограничения на символы, описанные в секции ниже.

Ограничения x-request-id

В идентификаторах x-request-id асинхронных запросов не поддерживаются следующие символы (подробнее см. в документации ZooKeeper):

  • точка или две точки без добавления других символов;
  • спецсимволы Unicode;
  • строка zookeeper без добавления других символов.

Тело запроса

Тело запроса может содержать следующие параметры:

  • query — любой поддерживаемый запрос SQL+. В простом запросе указывайте значения как есть, в подготовленном — замените каждое значение на символ ?;
  • queryId (опциональный) — идентификатор запроса SQL+. По этому идентификатору можно отследить обработку запроса в логах;
  • maxRowsToRead (опциональный) — максимальное количество строк, возвращаемых в ответе;
  • params (опциональный) — список параметров подготовленного запроса;
  • async — признак режима выполнения запроса. Возможные значения:
    • false (по умолчанию) — синхронный режим выполнения;
    • true — асинхронный режим выполнения.

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

Ниже показаны примеры запросов:

  • без авторизационного токена — для случаев, когда аутентификация отключена;
  • с авторизационным токеном — для случаев, когда аутентификация включена;
  • с запуском в асинхронном режиме;
  • с параметрами (подготовленные запросы).

Запрос на чтение данных без авторизационного токена 

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=json' \
  -H 'x-request-id: ee7c7570-1eec-11ed-861d-0242ac120002' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT st.id, st.category, s.product_code FROM marketing.stores AS st INNER JOIN marketing_new.sales AS s ON st.id = s.store_id DATASOURCE_TYPE = '\''adb'\''",
  "queryId": "12345",
  "maxRowsToRead": 100
}'

Запрос на чтение данных с авторизационным токеном 

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=json' \
  -H 'x-request-id: ee7c7570-1eec-11ed-861d-0242ac120002' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
  -d '{
  "query": "SELECT st.id, st.category, s.product_code FROM marketing.stores AS st INNER JOIN marketing_new.sales AS s ON st.id = s.store_id DATASOURCE_TYPE = '\''adb'\''",
  "queryId": "12345",
  "maxRowsToRead": 100
}'

Синхронный запрос на обновление данных

Запрос:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=json' \
  -H 'x-request-id: 048d4ed9-5fe3-48a2-93a2-fc95885fc037' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "INSERT INTO marketing.sales VALUES (11, '\''2021-07-11 23:34:10'\'', '\''ABC0004'\'', 2, 123, '\''Покупка по акции \"1+1\"'\'')",
  "queryId": "1y3ty4y"
}'

Ответ:

{
  "result": [
	{
      "sysCn": 94
	}
  ],
  "metadata": [
	{
      "name": "sysCn",
      "type": "BIGINT",
      "size": null,
	  "nullable": false
	}
  ],
  "rows": 1,
  "queryId": "1y3ty4y",
  "statistics": {
	"elapsedTotalMs": 454,
	"elapsedDbMs": 1105
  }
}

Асинхронный запрос на обновление данных

Запрос:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=json' \
  -H 'x-request-id: 4519785b-4a9b-4d3b-b332-a39e5b56ae1d' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "INSERT INTO marketing.sales VALUES (11, '\''2021-07-11 23:34:10'\'', '\''ABC0004'\'', 2, 123, '\''Покупка по акции \"1+1\"'\'')",
  "queryId": "34678765hd6",
  "async": true
}'

Ответ:

{
  "requestId": "4519785b-4a9b-4d3b-b332-a39e5b56ae1d",
  "message": "Async operation started"
}

Подготовленный запрос (prepared statement) без токена 

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: ee7c7570-1eec-11ed-861d-0242ac120002' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "INSERT INTO sales (id, transaction_date, product_code, product_units, store_id) values (?, ?, ?, ?, ?), (?, ?, ?, ?, ?)",
  "queryId": "98765",
  "params": [
    {
      "value": 300014,
      "type": "INT"
    },
    {
      "value": "2022-08-23 09:34:10",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0003",
      "type": "VARCHAR"
    },
    {
      "value": 3,
      "type": "INT"
    },
    {
      "value": 123,
      "type": "INT"
    },
    {
      "value": 300015,
      "type": "INT"
    },
    {
      "value": "2022-08-23 20:05:56",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0001",
      "type": "VARCHAR"
    },
    {
      "value": 6,
      "type": "INT"
    },
    {
      "value": 234,
      "type": "INT"
    }
  ]
}'

Асинхронный подготовленный запрос (prepared statement) с токеном 

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 1f6d3043-4c54-43ca-8653-9bf090a51971' \
  -H 'Content-Type: application/json' \
  -H 'Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c' \
  -d '{
  "query": "INSERT INTO sales (id, transaction_date, product_code, product_units, store_id) values (?, ?, ?, ?, ?), (?, ?, ?, ?, ?)",
  "queryId": "398775",
  "async": true,
  "params": [
    {
      "value": 300014,
      "type": "INT"
    },
    {
      "value": "2022-08-23 09:34:10",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0003",
      "type": "VARCHAR"
    },
    {
      "value": 3,
      "type": "INT"
    },
    {
      "value": 123,
      "type": "INT"
    },
    {
      "value": 300015,
      "type": "INT"
    },
    {
      "value": "2022-08-23 20:05:56",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0001",
      "type": "VARCHAR"
    },
    {
      "value": 6,
      "type": "INT"
    },
    {
      "value": 234,
      "type": "INT"
    }
  ]
}'