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

Содержание раздела
  1. Индексированные параметры (HTTP, JDBC)
  2. Именованные параметры (HTTP)
  3. Системные параметры (HTTP)
    1. Доступные системные параметры
    2. settings_for_system_time с меткой времени
    3. settings_for_system_time_finished с целочисленным диапазоном
    4. settings_for_system_time_finished с диапазоном меток времени
    5. settings_for_system_time_started с целочисленным диапазоном
    6. settings_for_system_time_started с диапазоном меток времени
    7. settings_for_system_time_as_of
    8. settings_for_system_time_as_of_delta_num
    9. settings_for_system_time_cn
    10. settings_for_system_time_finished_cn
    11. settings_for_system_time_finished_in
    12. settings_for_system_time_finished_ts
    13. settings_for_system_time_latest_uncommitted_delta
    14. settings_for_system_time_started_cn
    15. settings_for_system_time_started_in
    16. settings_for_system_time_started_ts
  4. Табличные параметры (HTTP)
    1. Поддержка параметров
    2. Как использовать параметр

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

Запрос может содержать максимум один табличный параметр (если поддерживается) и любое количество других поддерживаемых параметров.

Параметры доступны в запросах, перечисленных в таблице ниже.

Запрос Индексированные параметры Именованные параметры Системные параметры Табличные параметры
CHECK_READ_SLOTS + + – –
CHECK_SUM + + – –
CHECK_SUM_SNAPSHOT + + – –
DELETE + + + –
ERASE_READ_BALANCE + + – –
GET_CN + + – –
GET_READ_BALANCE + + – –
GET_TS + + – –
INSERT INTO download_external_table + + + –
INSERT SELECT + + + –
INSERT VALUES + + – –
RESET_READ_SLOTS + + – –
SELECT + + + +
SET_MODE_READONLY + + – –
SET_READ_BALANCE + + – –
TRUNCATE ACTUAL + + – –
TRUNCATE HISTORY + + – –
TRUNCATE TSLOG + + – –
UPDATE + + + –
UPSERT VALUES + + – –

В одном HTTP-запросе можно сочетать любые виды параметров, как показано в примере ниже.

Пример HTTP-запроса с индексированными, именованными и системными параметрами 
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"
     }
   ]
}'

Индексированные параметры (HTTP, JDBC)

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

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

Параметр задается так: он обозначается символом ? в основной части запроса, а его тип данных и значение определяются в секции params запроса (в HTTP-запросах) или с помощью методов .set<data_type>() интерфейса prepareStatement (в JDBC-запросах).

Пример HTTP-запроса с индексированными параметрами 
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"
    }
  ]
}'
Пример JDBC-запроса с индексированными параметрами 
Connection conn = DriverManager.getConnection("jdbc:prostore://10.92.3.86:9090");
PreparedStatement pst = conn.prepareStatement("SELECT * FROM marketing.sales\n" +
      "FOR SYSTEM_TIME AS OF ?\n" +
      "WHERE id = ?\n;");
pst.setTimestamp(1, Timestamp.valueOf("2024-05-10 13:12:09")); // метка времени 10 мая 2024 13:12:09 для FOR SYSTEM_TIME AS OF
pst.setInt(2, 123); // значение 123 для id
ResultSet rs = pst.executeQuery();

Именованные параметры (HTTP)

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

Параметр задается в запросе так: он обозначается в формате :<имя_параметра> в секции query, а его имя, тип данных и значение определяются в секции params. Один и тот же параметр может упоминаться в секции query многократно.

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

Пример HTTP-запроса с именованными параметрами 
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 AND transaction_date < :fst_timestamp",
  "queryId": "25322",
  "params": [
    {
      "name": "fst_timestamp",
      "value": "2024-05-10 13:12:09",
      "type": "TIMESTAMP"
    },
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    }
  ]
}'

Системные параметры (HTTP)

Системный параметр имеет системное имя и задает выражение FOR SYSTEM_TIME для всех сущностей запроса, для которых не задано свое выражение FOR SYSTEM_TIME. Набор доступных системных параметров перечислен в секции Доступные системные параметры.

Системный параметр не может использоваться в качестве именованного параметра. Запрос может содержать не более одного системного параметра.

Параметр задается в запросе так: его имя, тип и значение определяются в секции params. В секции query запроса параметр НЕ обозначается.

Пример HTTP-запроса с именованным и системным параметром 
curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: d115d085-6241-4ff8-af16-7f7589be7ac0' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56790",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started", 
      "value": "'2022-11-14 16:00:00', '2024-11-15 16:00:00'", 
      "type": "STRING"
    }
  ]
}'

Доступные системные параметры

В таблице ниже перечислены доступные системные параметры и соответствующие им выражения FOR SYSTEM_TIME. Формат и примеры использования параметров доступны в отдельных секциях ниже.

Системный параметр Задаваемое выражение
settings_for_system_time с меткой времени FOR SYSTEM_TIME AS OF '<datetime>'
settings_for_system_time_finished с целочисленным диапазоном FOR SYSTEM_TIME FINISHED IN (<delta_num1>, <delta_num2>)
settings_for_system_time_finished с диапазоном меток времени FOR SYSTEM_TIME FINISHED TS (<datetime1>, <datetime2>)
settings_for_system_time_started с целочисленным диапазоном FOR SYSTEM_TIME STARTED IN (<delta_num1>, <delta_num2>)
settings_for_system_time_started с диапазоном меток времени FOR SYSTEM_TIME STARTED TS (<datetime1>, <datetime2>)
settings_for_system_time_as_of FOR SYSTEM_TIME AS OF '<datetime>'
settings_for_system_time_as_of_delta_num FOR SYSTEM_TIME AS OF DELTA_NUM <delta_num>
settings_for_system_time_cn FOR SYSTEM_TIME AS OF CN <sys_cn>
settings_for_system_time_finished_cn FOR SYSTEM_TIME FINISHED CN (<sys_cn1>, <sys_cn2>)
settings_for_system_time_finished_in FOR SYSTEM_TIME FINISHED IN (<delta_num1>, <delta_num2>)
settings_for_system_time_finished_ts FOR SYSTEM_TIME FINISHED TS (<datetime1>, <datetime2>)
settings_for_system_time_latest_uncommitted_delta FOR SYSTEM_TIME AS OF LATEST_UNCOMMITTED_DELTA
settings_for_system_time_started_cn FOR SYSTEM_TIME STARTED CN (<sys_cn1>, <sys_cn2>)
settings_for_system_time_started_in FOR SYSTEM_TIME STARTED IN (<delta_num1>, <delta_num2>)
settings_for_system_time_started_ts FOR SYSTEM_TIME STARTED TS (<datetime1>, <datetime2>)

settings_for_system_time с меткой времени

Задает выражение FOR SYSTEM_TIME AS OF '<datetime>' в формате:

{
  "name": "settings_for_system_time",
  "value": "<datetime>",
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time",
  "value": "2023-08-23 18:01:04",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 10d857b2-3c4b-4328-bcf8-92e18b571844' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time", 
      "value": "2023-08-23 18:01:04", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_finished с целочисленным диапазоном

Задает выражение FOR SYSTEM_TIME FINISHED IN (<delta_num1>, <delta_num2>) в формате:

{
  "name": "settings_for_system_time_finished",
  "value": "<delta_num1>, <delta_num2>",
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_finished", 
  "value": "12, 15", 
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: c66e1a50-da37-4c11-a392-ce37a2552bcb' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_finished", 
      "value": "12, 15", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_finished с диапазоном меток времени

Задает выражение FOR SYSTEM_TIME FINISHED TS (<datetime1>, <datetime2>) в формате:

{
  "name": "settings_for_system_time_finished", 
  "value": "<datetime1>, <datetime2>",
  "type": "STRING"
}

Значения <datetime1> и <datetime2> можно указать в одинарных кавычках или без них.

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

{
  "name": "settings_for_system_time_finished",
  "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 3b50e96f-a407-4b99-8945-c4b201ef7329' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_finished", 
      "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_started с целочисленным диапазоном

Задает выражение FOR SYSTEM_TIME STARTED IN (<delta_num1>, <delta_num2>) в формате:

{
  "name": "settings_for_system_time_started", 
  "value": "<delta_num1>, <delta_num2>", 
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_started",
  "value": "10, 39",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: dc6f24f2-be23-4fa6-852c-c37790625064' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started", 
      "value": "10, 39", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_started с диапазоном меток времени

Задает выражение FOR SYSTEM_TIME STARTED TS (<datetime1>, <datetime2>) в формате:

{
  "name": "settings_for_system_time_started", 
  "value": "<datetime1>, <datetime2>", 
  "type": "STRING"
}

Значения <datetime1> и <datetime2> можно указать в одинарных кавычках или без них.

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

{
  "name": "settings_for_system_time_started",
  "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 84915503-c19e-4dea-a9a2-eafc5469b639' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started", 
      "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_as_of

Задает выражение FOR SYSTEM_TIME AS OF '<datetime>' в формате:

{
  "name": "settings_for_system_time_as_of",
  "value": "<datetime>",
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_as_of", 
  "value": "2023-08-23 18:01:04", 
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 5be24e82-5f2b-4a9c-ac89-35db27fc240a' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_as_of", 
      "value": "2023-08-23 18:01:04", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_as_of_delta_num

Задает выражение FOR SYSTEM_TIME AS OF DELTA_NUM <delta_num> в формате:

{
  "name": "settings_for_system_time_as_of_delta_num",
  "value": "<delta_num>", 
  "type": "LONG"
}

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

{
  "name": "settings_for_system_time_as_of_delta_num",
  "value": 12,
  "type": "LONG"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: f213fa62-614a-45f1-b25e-8c970f11bac4' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_as_of_delta_num", 
      "value": "12", 
      "type": "LONG"
    }
  ]
}'

settings_for_system_time_cn

Задает выражение FOR SYSTEM_TIME AS OF CN <sys_cn> в формате:

{
  "name": "settings_for_system_time_cn", 
  "value": "<sys_cn>", 
  "type": "LONG"
}

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

{
  "name": "settings_for_system_time_cn", 
  "value": 1724904923111000, 
  "type": "LONG"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 946bf32f-a34b-4b86-8eb7-b0af2a9587aa' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_cn", 
      "value": "1724904923111000", 
      "type": "LONG"
    }
  ]
}'

settings_for_system_time_finished_cn

Задает выражение FOR SYSTEM_TIME FINISHED CN (<sys_cn1>, <sys_cn2>) в формате:

{
  "name": "settings_for_system_time_finished_cn", 
  "value": "<sys_cn1>, <sys_cn2>", 
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_finished_cn", 
  "value": "1724508923111000, 1724904923111000", 
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: dd62b0a1-3d8d-4ada-b3b1-0839f535ad25' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_finished_cn", 
      "value": "1724508923111000, 1724904923111000", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_finished_in

Задает выражение FOR SYSTEM_TIME FINISHED IN (<delta_num1>, <delta_num2>) в формате:

{
  "name": "settings_for_system_time_finished_in",
  "value": "<delta_num1>, <delta_num2>",
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_finished_in",
  "value": "12, 15",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: d15da36e-efde-4118-bcb2-501255753c77' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_finished_in", 
      "value": "12, 15", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_finished_ts

Задает выражение FOR SYSTEM_TIME FINISHED TS (<datetime1>, <datetime2>) в формате:

{
  "name": "settings_for_system_time_finished_ts", 
  "value": "<datetime1>, <datetime2>",
  "type": "STRING"
}

Значения параметра можно указать в любом из форматов:

  • строковая метка времени — метка времени в любом из форматов, описанных в разделе Форматы даты и времени в запросах, в одинарных кавычках или без них;
  • Unix-время — целое число микросекунд с 00:00:00 UTC 1 января 1970 года.

Пример параметра со значением в виде строковой метки в запросе:

{
  "name": "settings_for_system_time_finished_ts", 
  "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'", 
  "type": "STRING"
}

Пример параметра со значением в виде Unix-метки в запросе:

{
  "name": "settings_for_system_time_finished_ts",
  "value": "1716022800000000, 1718701200000000",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: a6733494-39e3-4770-895a-66126a51b993' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_finished_ts", 
      "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_latest_uncommitted_delta

Задает выражение FOR SYSTEM_TIME AS OF LATEST_UNCOMMITTED_DELTA в формате:

{
  "name": "settings_for_system_time_latest_uncommitted_delta",
  "value": <any_value_of_the_type>,
  "type": "<any_supported_type>"
}

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

{
  "name": "settings_for_system_time_latest_uncommitted_delta",
  "value": null,
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 0e613a74-469f-4c25-8ee3-b808efe2d4c7' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_latest_uncommitted_delta", 
      "value": null, 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_started_cn

Задает выражение FOR SYSTEM_TIME STARTED CN (<sys_cn1>, <sys_cn2>) в формате:

{
  "name": "settings_for_system_time_started_cn", 
  "value": "<sys_cn1>, <sys_cn2>", 
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_started_cn",
  "value": "1724508923111000, 1724904923111000",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: da4b212a-3ce2-416d-adca-578552da3896' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started_cn", 
      "value": "1724508923111000, 1724904923111000", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_started_in

Задает выражение FOR SYSTEM_TIME STARTED IN (<delta_num1>, <delta_num2>) в формате:

{
  "name": "settings_for_system_time_started_in", 
  "value": "<delta_num1>, <delta_num2>", 
  "type": "STRING"
}

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

{
  "name": "settings_for_system_time_started_in",
  "value": "10, 39",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 83249747-8d5d-4d66-adc3-381a5112a6d9' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started_in", 
      "value": "10, 39", 
      "type": "STRING"
    }
  ]
}'

settings_for_system_time_started_ts

Задает выражение FOR SYSTEM_TIME STARTED TS (<datetime1>, <datetime2>) в формате:

{
  "name": "settings_for_system_time_started_ts", 
  "value": "<datetime1>, <datetime2>", 
  "type": "STRING"
}

Значения параметра можно указать в любом из форматов:

  • строковая метка времени — метка времени в любом из форматов, описанных в разделе Форматы даты и времени в запросах, в одинарных кавычках или без них;
  • Unix-время — целое число микросекунд с 00:00:00 UTC 1 января 1970 года.

Пример параметра со значением в виде строковой метки в запросе:

{
  "name": "settings_for_system_time_started_ts",
  "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'",
  "type": "STRING"
}

Пример параметра со значением в виде Unix-метки в запросе:

{
  "name": "settings_for_system_time_started_ts",
  "value": "1716022800000000, 1718701200000000",
  "type": "STRING"
}

Пример cURL-запроса с параметром:

curl -X 'POST' \
  'http://localhost:9090/api/v1/datamarts/marketing/query?format=json' \
  -H 'x-request-id: 14e2e3dc-3229-4cfa-93e2-eac5441d0ab2' \
  -H 'Content-Type: application/json' \
  -d '{
  "query": "SELECT * FROM marketing.sales WHERE id = :id_value",
  "queryId": "56784",
  "params": [
    {
      "name": "id_value",
      "value": 123,
      "type": "LONG"
    },
    {
      "name": "settings_for_system_time_started_ts", 
      "value": "'2024-05-18 10:00:00', '2024-06-18 10:00:00'", 
      "type": "STRING"
    }
  ]
}'

Табличные параметры (HTTP)

Табличный параметр — параметр, подставляемый в шаблон SELECT-запроса в виде временной таблицы.

Табличный параметр позволяет передать временный набор данных в запрос. Его можно использовать как таблицу в JOIN, UNION, INTERSECT и т.д. с другими сущностями, существующими в системе, а его столбцы — в JOIN, WHERE и других операциях над столбцами.

Например, с помощью табличного параметра можно отфильтровать записи через JOIN с логической таблицей.

Поддержка параметров

Табличные параметры поддерживаются только в SELECT-запросах, кроме SELECT … FROM INFORMATION_SCHEMA. Они недоступны в других запросах, включая содержащие SELECT-подзапросы: INSERT SELECT, CREATE VIEW, CREATE MATERIALIZED VIEW и т.д.

Запрос может содержать максимум один табличный параметр (с любым количеством упоминаний его имени и столбцов в SELECT) и любое количество других параметров.

Как использовать параметр

Чтобы использовать табличный параметр:

  • в секции params определите имя параметра и список его столбцов;
  • в секции query в составе SELECT-запроса укажите имя параметра в формате @<имя_параметра> и (или) имена его столбцов в любом из форматов:
    • @<имя_параметра>.<имя_столбца>;
    • <имя_параметра>.<имя_столбца>;
    • <алиас_параметра>.<имя_столбца> (после задания SQL-алиаса для параметра в SELECT, как для обычной таблицы).

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

В примере ниже показана JSON-часть тела запроса с табличным параметром, представленная для наглядности в незакодированном виде (в реальном запросе должна быть в UTF-8). Подробнее см. в разделе Чтение с табличным параметром.

Фрагмент HTTP-запроса с табличным параметром 
{
  "query": "SELECT s.* FROM marketing.sales s JOIN @store_and_product_filter ON s.store_id = @store_and_product_filter.store_id AND s.product_code = @store_and_product_filter.product_code WHERE s.transaction_date >= DATE_TRUNC(MONTH, TIMESTAMPADD(MONTH, -1, current_date)) AND s.transaction_date < DATE_TRUNC(MONTH, current_date) DATASOURCE_TYPE = '\''adp'\''",
  "params": [
    {
      "name": "store_and_product_filter",
      "columns": [
        { 
          "name": "store_id", 
          "type": "LONG"
        },
        { 
          "name": "product_code", 
          "type": "STRING"
        }
      ]
    }
  ],
  "queryId": "5345678",
  "maxRowsToRead": 100,
  "fetchSize": 100,
  "fetchTimeoutMs": 30000
}