/datamarts[/{datamart}]/query

Содержание раздела
  1. Режимы выполнения запросов
  2. Формат ответа
    1. Поддерживаемые форматы данных
    2. Avro-формат ответа
    3. Состав ответов при потоковом чтении данных
  3. Режимы чтения данных
  4. URL
    1. {baseUrl}
    2. [ {datamart} ]
    3. [ format ]
    4. [ compressionLevel ]
  5. Заголовки запроса
    1. [ x-request-id ]
  6. Тело запроса
    1. query
    2. [ queryId ]
    3. [ sqlRequestPriority ]
    4. [ maxRowsToRead ]
    5. [ fetchSize ]
    6. [ fetchTimeoutMs ]
    7. [ params ]
    8. async
  7. Примеры запросов
    1. Чтение данных одной порцией
    2. Потоковое чтение порциями заданного размера
      1. Потоковое чтение данных в Avro-формате
      2. Потоковое чтение данных в JSON-формате
    3. Обновление данных в синхронном режиме
    4. Обновление данных в асинхронном режиме
    5. Параметризованные запросы
      1. Запрос на синхронное обновление данных с индексированными параметрами
      2. Запрос на асинхронное обновление данных с индексированными параметрами
      3. Запрос на чтение данных с индексированными параметрами
      4. Запрос на чтение данных с именованными параметрами
      5. Запрос на чтение данных с индексированными, именованными и системными параметрами
    6. Создание логических сущностей
      1. Создание временной прокси-таблицы в вычисленном датасорсе из указанных
      2. Создание временной прокси-таблицы в вычисленном из всех включенных датасорсов

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

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

Для SELECT-запросов с табличными параметрами используйте /query-upload.

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

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

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

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

Поддерживаемые форматы данных

Метод поддерживает возврат данных в различных форматах — JSON, Avro и plain. По умолчанию метод возвращает ответ в JSON-формате. При необходимости вы можете задать другой формат ответа с помощью параметра format в URL.

Avro-формат ответа

При использовании Avro-формата ответа в поле doc схемы Avro возвращается информация о логических типах данных, содержащихся в выборке, как показано в примере ниже.

Пример схемы Avro в ответе, представленной для наглядности в JSON-формате:

{
  "type": "record",
  "name": "QueryResultRow",
  "namespace": "query.result",
  "doc": {
    "metadata": [
      {
        "name": "id",
        "type": "BIGINT",
        "size": null,
        "nullable": false
      },
      {
        "name": "transaction_date",
        "type": "TIMESTAMP",
        "size": 6,
        "nullable": false
      },
      {
        "name": "product_code",
        "type": "VARCHAR",
        "size": 256,
        "nullable": false
      },
      {
        "name": "product_units",
        "type": "BIGINT",
        "size": null,
        "nullable": false
      },
      {
        "name": "store_id",
        "type": "BIGINT",
        "size": null,
        "nullable": false
      },
      {
        "name": "description",
        "type": "VARCHAR",
        "size": 256,
        "nullable": true
      },
      {
        "name": "test_column",
        "type": "ANY",
        "size": null,
        "nullable": true
      }  
    ]
  },
  "fields": [
    {"name": "id", "type": "long"},
    {"name": "transaction_date", "type": {"type": "long", "logicalType": "timestamp-micros"}},
    {"name": "product_code", "type": {"type": "string", "avro.java.string": "String"}},
    {"name": "product_units", "type": "long"},
    {"name": "store_id", "type": "long"},
    {"name": "description", "type": ["null", {"type": "string", "avro.java.string": "String"}], "default": null},
    {"name" : "test_column", "type" : [ "null", "long", "double", "int", "float", "boolean", {"type" : "string", "avro.java.string" : "String"}], "default" : null}
  ]
}

Для столбца с неопределенным типом в поле doc указывается тип ANY, а в поле fields — union-элемент со всеми типами Avro (см. пример ниже для столбца test_column). Пример запроса, в котором столбец test_column имеет неопределенный тип данных: SELECT *, null AS test_column FROM marketing.sales.

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

Состав ответов при потоковом чтении данных зависит от заданного формата ответа:

  • в plain-формате:
    • [первый ответ] содержит список имен столбцов, присутствующих в выборке;
    • [последующие ответы] содержат порции записей без метаданных;
  • в Avro-формате:
    • [первый ответ] содержит заголовок со схемой данных Avro (см. пример выше);
    • [последующие ответы] содержат блоки данных без заголовка и схемы;
  • в JSON-формате — состав ответов см. в таблице ниже, пример ответов — в секции Потоковое чтение данных в JSON-формате.
Элемент ответа (JSON) Первый ответ Последующие ответы, кроме последнего Последний ответ
queryId Значение queryId null Значение queryId
rows null null Итоговое количество строк в ResultSet (с учетом всех порций записей)
statistics null null
  • elapsedTotalMs — общее время, прошедшее от получения запроса до отправки последнего ответа;
  • elapsedDbMs — общее время исполнения всех запросов в СУБД
metadata Логическая схема данных (столбцы ResultSet) null null
result null Порция записей (строки ResultSet) Порция записей (строки ResultSet)

Режимы чтения данных

Метод поддерживает следующие режимы чтения данных:

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

По умолчанию метод возвращает результат чтения одним ответом, но, если в теле запроса задан параметр fetchSize, результат чтения возвращается в виде потока.

Потоковое чтение данных по HTTP API доступно только при подключении по протоколу HTTP/2 и чтении из СУБД ADB и (или) ADP. Подробнее см. в разделе Потоковое чтение данных.

URL

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

{baseUrl}

Адрес ноды Prostore, состоящий из IP-адреса или доменного имени и номера порта.

[ {datamart} ]

Имя логической базы данных, используемой по умолчанию. Если не указано, должно быть указано в query для каждой сущности отдельно.

Не учитывается для запросов с командами:

[ format ]

Формат ответа. Возможные значения:

  • json — JSON-строка (по умолчанию);
  • plain — текстовое представление;
  • avro — Avro-формат без сжатия;
  • avro-deflate — Avro-формат со сжатием по алгоритму Deflate;
  • avro-snappy — Avro-формат со сжатием по алгоритму Snappy;
  • avro-bzip2 — Avro-формат со сжатием по алгоритму BZip2;
  • avro-xz — Avro-формат со сжатием по алгоритму XZ;
  • avro-zstandard — Avro-формат со сжатием по алгоритму Zstandard.

[ compressionLevel ]

Коэффициент сжатия данных.

Должен быть указан, если в format задан Avro-формат со сжатием. Возможные значения коэффициента зависят от выбранного алгоритма сжатия; подробнее см. в документации Apache Avro.

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

[ x-request-id ]

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

Тело запроса

Тело запроса может содержать параметры, описанные ниже. В квадратных скобках [ parameter ] отмечены опциональные параметры.

query

Запрос SQL+ из числа поддерживаемых. Значения в запросе можно указать как константы и (или) параметры.

[ queryId ]

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

В SELECT-запросах и запросах на создание прокси-таблиц параметр влияет на выбор датасорса. Подробнее см. в разделах Выбор датасорса для исполнения запроса и Прокси-таблица соответственно.

Запросы с одинаковым значением queryId выбирают одинаковый датасорс, если он остается включен и состав датасорсов не меняется в списке подходящих для исполнения запроса (для SELECT-запросов) или в DATASOURCE_TYPE/конфигурации (для прокси-таблиц).

[ sqlRequestPriority ]

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

Если отсутствует в запросе чтения или выгрузки:

Запрос также обрабатывается без балансировки, если для его приоритета нет подходящих настроек балансировки.

[ maxRowsToRead ]

Максимальное число записей, возвращаемых по запросу. При потоковом чтении учитывает все порции данных.

Если параметр не задан, равен 0 или null, число записей не ограничено.

[ fetchSize ]

Максимальное число записей в порции данных, возвращаемой в одном ответе при потоковом чтении.

Если параметр не задан, равен 0 или null, все записи возвращаются одним ответом (потоковое чтение выключено).

Потоковое чтение доступно только для HTTP/2 и только при чтении из ADP или ADB. Подробнее см. в разделе Потоковое чтение данных.

Потоковое чтение недоступно в асинхронном режиме обработки запроса. Если в запросе указаны async=true и fetchSize > 0, приоритет имеет async: запрос выполняется асинхронно, и возвращается один ответ с уведомлением о начале обработки (см. пример ниже).

[ fetchTimeoutMs ]

Максимальное время, выделяемое на исполнение SELECT-запроса в системе, если запрос исполняется в ADP или ADB. Указывается в миллисекундах и применяется как при обычном чтении (одной порцией со всей выборкой), так и потоковом.

Время отсчитывается с момента получения запроса системой до завершения передачи всех запрошенных данных. При превышении лимита система принудительно завершает запрос.

Если параметр не задан, равен 0 или null, время исполнения не ограничено.

[ 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
}'

Потоковое чтение порциями заданного размера

Потоковое чтение данных в Avro-формате 

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=avro-zstandard&compressionLevel=10' \
  -H 'x-request-id: dabf0e53-ca97-40fb-a97e-ba0b4d3088fa' \
  -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": 1000,
  "fetchSize": 100,
  "fetchTimeoutMs": 60000
}'

Потоковое чтение данных в JSON-формате

Запрос:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query?format=json' \
  -H 'x-request-id: 84706c2d-ba4a-4bb5-85e3-a367090f5882' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE store_id = 123",
  "queryId": "72848562",
  "maxRowsToRead": 100,
  "fetchSize": 3
}'

Первый ответ в потоке ответов:

{
  "queryId": "84706c2d-ba4a-4bb5-85e3-a367090f5882",
  "rows": null,
  "statistics": null,
  "metadata": [
    {
      "name": "id",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    },
    {
      "name": "transaction_date",
      "type": "TIMESTAMP",
      "size": 6,
      "nullable": false
    },
    {
      "name": "product_code",
      "type": "VARCHAR",
      "size": 256,
      "nullable": false
    },
    {
      "name": "product_units",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    },
    {
      "name": "store_id",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    },
    {
      "name": "description",
      "type": "VARCHAR",
      "size": 256,
      "nullable": true
    }
  ],
  "result": null
}

Следующий ответ в потоке ответов:

{
  "queryId": null,
  "rows": null,
  "statistics": null,
  "metadata": null,
  "result": [
    {
      "id": 300123,
      "transaction_date": "2023-08-22 13:17:47",
      "product_code": "ABC0002",
      "product_units": 4,
      "store_id": 123,
      "description": "Покупка по акции \"Лето\""
    },
    {
      "id": 300021,
      "transaction_date": "2023-08-21 23:34:10",
      "product_code": "ABC0001",
      "product_units": 2,
      "store_id": 123,
      "description": "Покупка по акции \"1+1\""
    },
    {
      "id": 300133,
      "transaction_date": "2023-08-23 18:01:04",
      "product_code": "ABC0002",
      "product_units": 4,
      "store_id": 123,
      "description": "Покупка по акции \"Лето\""
    }
  ]
}

Последний ответ в потоке с остатком записей, число которых может быть меньше fetchSize:

{
  "queryId": "84706c2d-ba4a-4bb5-85e3-a367090f5882",
  "rows": 59,
  "statistics" : {
    "elapsedTotalMs" : 1522,
    "elapsedDbMs" : 364
  },
  "metadata": null,
  "result": [
    {
      "id": 300031,
      "transaction_date": "2021-08-25 15:34:10",
      "product_code": "ABC0001",
      "product_units": 2,
      "store_id": 123,
      "description": "Покупка по акции \"1+1\""
    },
    {
      "id": 11,
      "transaction_date": "2021-09-11 10:23:40",
      "product_code": "ABC0004",
      "product_units": 2,
      "store_id": 123,
      "description": "Покупка по акции \"1+1\""
    }
  ]
}

Обновление данных в синхронном режиме

Запрос:

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"
}'

Ответ:

{
  "queryId":"1y3ty4y",
  "rows":1,
  "statistics":{
    "elapsedTotalMs":7337,
    "elapsedDbMs":1627
  },
  "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
    }
  ],
  "result":[
    {
      "sysCn":1745409314354302,
      "ts":"2025-04-23 11:55:21.668927",
      "rowsAffected":1
    }
  ]
}

Обновление данных в асинхронном режиме

Запрос:

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"
}

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

Запрос на синхронное обновление данных с индексированными параметрами 

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": "BIGINT"
    },
    {
      "value": "2022-08-23 09:34:10",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0003",
      "type": "VARCHAR"
    },
    {
      "value": 3,
      "type": "BIGINT"
    },
    {
      "value": 123,
      "type": "BIGINT"
    },
    {
      "value": 300015,
      "type": "BIGINT"
    },
    {
      "value": "2022-08-23 20:05:56",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0001",
      "type": "VARCHAR"
    },
    {
      "value": 6,
      "type": "BIGINT"
    },
    {
      "value": 234,
      "type": "BIGINT"
    }
  ]
}'

Запрос на асинхронное обновление данных с индексированными параметрами 

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' \
  -d '{
  "query": "INSERT INTO sales (id, transaction_date, product_code, product_units, store_id) values (?, ?, ?, ?, ?), (?, ?, ?, ?, ?)",
  "queryId": "398775",
  "async": true,
  "params": [
    {
      "value": 300014,
      "type": "BIGINT"
    },
    {
      "value": "2022-08-23 09:34:10",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0003",
      "type": "VARCHAR"
    },
    {
      "value": 3,
      "type": "BIGINT"
    },
    {
      "value": 123,
      "type": "BIGINT"
    },
    {
      "value": 300015,
      "type": "BIGINT"
    },
    {
      "value": "2022-08-23 20:05:56",
      "type": "TIMESTAMP"
    },
    {
      "value": "ABC0001",
      "type": "VARCHAR"
    },
    {
      "value": 6,
      "type": "BIGINT"
    },
    {
      "value": 234,
      "type": "BIGINT"
    }
  ]
}'

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

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: e89cc2fc-8fc1-415f-9dee-02deb30c6f34' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales FOR SYSTEM_TIME AS OF ? WHERE id = ?",
  "queryId": "72840",
  "params": [
    {
      "value": "2024-05-10 13:12:09",
      "type": "TIMESTAMP"
    },
    {
      "value": 123,
      "type": "LONG"
    }
  ]
}'

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

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: da3fb795-42ec-4b4f-afb8-9d9575ce194b' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales FOR SYSTEM_TIME AS OF :fst_timestamp WHERE id = :id_value",
  "queryId": "25322",
  "params": [
    {
      "name": "fst_timestamp",
      "value": "2024-05-10 13:12:09",
      "type": "TIMESTAMP"
    },
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    }
  ]
}'

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

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/testdb/query?format=json' \
  -H 'x-request-id: 9a544722-eaab-4b02-8448-6f4229407c2c' \
  -H 'Content-Type: application/json' \
  -d '{
   "query": "SELECT t1.*
FROM testdb.all_types
JOIN testdb.all_types AS t2 ON t1.id = t2.id
WHERE t1.boolean_col = ? # индексированный параметр [1]
 AND t1.varchar_col = ? # индексированный параметр [2]
 AND t1.id IN (SELECT id FROM testdb.all_types2) 
 AND t2.id IN (SELECT id FROM testdb.all_types3) # именованный параметр :p_delta
 AND t2.timestamp_col > :p_timestamp # именованный параметр :p_timestamp
 AND t2.bigint_col < :p_bigint # именованный параметр :p_bigint
 AND t2.float_col < ? # индексированный параметр [3]", 
   "params": [
     {# индексированный параметр [1]
      "value": true, "type": "BOOLEAN"
     },
     {# индексированный параметр [2]
      "value": "A", "type": "STRING"
     },
     {# именованный параметр :p_delta
      "name": "p_delta", "value": 1, "type": "LONG"
     },
     {# именованный параметр :p_timestamp
      "name": "p_timestamp", "value": "2023-11-17 21:11:12", "type": "TIMESTAMP"
     },
     {# именованный параметр :p_bigint
      "name": "p_bigint", "value": 10, "type": "LONG"
     },
     {# индексированный параметр [3]
      "value": 1.1, "type": "FLOAT"
     },
     {# системный параметр FOR SYSTEM_TIME STARTED TS
      "name": "settings_for_system_time_started", "value": "'2023-11-14 16:00:00', '2024-11-14 16:00:00'", "type": "STRING"
     }
   ]
}'

Создание логических сущностей

Создание временной прокси-таблицы в вычисленном датасорсе из указанных

Прокси-таблица без первичного ключа и ключа шардирования с размещением в датасорсе, вычисленном по queryId из указанных в DATASOURCE_TYPE:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query' \
  -H 'x-request-id: 5ae7018b-c1d8-49ed-a344-d68693e710a0' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "CREATE PROXY TABLE marketing.payments_proxy_temp_in_seed_listed_ds (id BIGINT NOT NULL, agreement_id BIGINT, type_code VARCHAR(16), amount DOUBLE, currency_code VARCHAR(3), description VARCHAR) DATASOURCE_TYPE ('adp', 'adp2') OPTIONS ('set.entity.ttl.ms=120000;')",
  "queryId": "3456878"
}'

Создание временной прокси-таблицы в вычисленном из всех включенных датасорсов

Создание временной прокси-таблицы без первичного ключа и ключа шардирования с размещением в датасорсе, вычисленном по queryId из всех включенных (без указания DATASOURCE_TYPE):

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/query' \
  -H 'x-request-id: a9a8300e-32fc-4b02-a10b-6d7d553985ad' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "CREATE PROXY TABLE marketing.payments_proxy_temp_in_seed_configured_ds (id BIGINT NOT NULL, agreement_id BIGINT, type_code VARCHAR(16), amount DOUBLE, currency_code VARCHAR(3), description VARCHAR) OPTIONS ('set.entity.ttl.ms=120000;')",
  "queryId": "28258592"
}'