/datamarts[/{datamart}]/query

Содержание раздела
  1. Режимы выполнения запросов
  2. Формат ответа
    1. Поддерживаемые форматы данных
    2. Avro-формат ответа
    3. Состав ответов при потоковом чтении данных
  3. Режимы чтения данных
  4. URL
  5. Заголовки запроса
    1. Заголовок x-request-id
    2. Заголовок Authorization
  6. Тело запроса
  7. Примеры запросов
    1. Чтение данных одной порцией
    2. Потоковое чтение порциями заданного размера
      1. Потоковое чтение данных в Avro-формате
      2. Потоковое чтение данных в JSON-формате
    3. Обновление данных в синхронном режиме
    4. Обновление данных в асинхронном режиме
    5. Параметризованные запросы
      1. Запрос на синхронное обновление данных с индексированными параметрами
      2. Запрос на асинхронное обновление данных с токеном и индексированными параметрами
      3. Запрос на чтение данных с индексированными параметрами
      4. Запрос на чтение данных с именованными параметрами
      5. Запрос на чтение данных с индексированными, именованными и системными параметрами

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

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

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

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

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

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

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

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

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

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

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

Пример схемы 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}
  ]
}

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

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

  • в JSON-формате:
    • первый ответ потока содержит массив metadata с логической схемой данных, а также пустые массивы result и statistics;
    • все последующие ответы потока содержат массив result с порцией записей, а также пустые массивы metadata и statistics (см. пример ниже);
  • в Avro-формате:
    • первый ответ потока содержит заголовок со схемой данных Avro (см. пример выше);
    • все последующие ответы потока содержат блоки данных без заголовка и схемы;
  • в plain-формате:
    • первый ответ потока содержит список имен столбцов, присутствующих в выборке;
    • все последующие ответы потока содержат порции записей без метаданных.

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

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

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

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

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

URL

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

Параметры:

  • baseUrl — адрес ноды Prostore, состоящий из IP-адреса или доменного имени и номера порта;
  • datamart (опциональный) — имя логической базы данных, используемой по умолчанию. Не учитывается для запросов с командами CREATE INDEX, DROP INDEX, GET_INDEXES, CREATE SEQUENCE, DROP SEQUENCE и GET_SEQUENCES;
  • 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 — коэффициент сжатия данных. Должен быть указан для всех перечисленных выше Avro-форматов, кроме avro. Возможные значения коэффициента зависят от выбранного алгоритма сжатия; подробнее см. в документации Apache Avro.

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

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

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

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

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

Заголовок Authorization

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

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

Тело запроса

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

query

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

[ queryId ]

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

[ maxRowsToRead ]

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

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

[ fetchSize ]

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

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

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

Потоковое чтение данных недоступно в асинхронном режиме обработки запроса. При наличии в запросе параметра async со значением true и параметра fetchSize со значением больше 0 учитывается только параметр async — система выполняет запрос в асинхронном режиме и возвращает один ответ, сообщающий о начале обработки запроса (см. пример ниже).

[ fetchTimeoutMs ]

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

Параметр применяется при потоковом чтении данных. Если он не задан или его значение равно 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
}'

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

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

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

Потоковое чтение данных в 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",
  "result": 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
    }
  ],
  "rows": null,
  "statistics": null
}

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

{
  "queryId": 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": "Покупка по акции \"Лето\""
    }
  ],
  "metadata": null,
  "rows": null,
  "statistics": null
}

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

{
  "queryId": 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\""
    }
  ],
  "metadata": null,
  "rows": null,
  "statistics": null
}

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

Запрос:

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",
  "result": [
    {
      "sysCn": 94
    }
  ],
  "metadata": [
    {
      "name": "sysCn",
      "type": "BIGINT",
      "size": null,
      "nullable": false
    }
  ],
  "rows": 1,
  "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"
}

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

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

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' \
  -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": "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"
     }
   ]
}'