Merge branch 'docs' into 'main'

docs: update SQL queries description

See merge request picodata/picodata/docs!93

docs/index.md

@@ -17,7 +17,7 @@
 ### Справочные материалы
 * [Описание параметров запуска Picodata](cli)
 * [Поддерживаемые функции стандарта SQL](sbroad/sql_reference)
-* [Глоссарий основных терминов и определений](sbroad/sql_glossary)
+* [Глоссарий основных терминов и определений](glossary)
 
 На данном портале представлена техническая документация программного продукта Picodata. Информация о выгодах сотрудничества с компанией Picodata, корпоративных решениях и услугах, новостях, событиях находится на сайте [picodata.io](https://www.picodata.io){:target="_blank"}.
 

docs/sbroad/sql_index.md

@@ -36,7 +36,7 @@ SQL Broadcaster — это динамическая библиотека, кот
 * [Справочник команд SQL Broadcaster](../sql_queries)
 * [Перечень поддерживаемых типов данных](../sql_datatypes)
 * [Инструкция по установке SQL Broadcaster и тестового приложения](../sql_tutorial)
-* [Глоссарий основных терминов и определений](../sql_glossary)
+<!-- * [Глоссарий основных терминов и определений](../sql_glossary) -->
 * [Справочник поддерживаемых функций стандарта SQL](../sql_reference)
 
 ## Обратная связь и получение помощи

docs/sbroad/sql_queries.md

 # Справочник команд SQL Broadcaster
-Справочник команд предоставлят основные варианты использования команд SQL в Picodata при работе с распределенной СУБД.
+Справочник команд предоставляет основные варианты использования команд SQL в Picodata при работе с распределенной СУБД.
 
 Функциональность компонента SQL Broadcaster обеспечивает поддержку распределенных запросов SELECT и INSERT. Ниже на схеме показаны базовые варианты этих запросов.
 
@@ -17,11 +17,15 @@ Cхема возможных распределенных запросов `SELE
 
 
 ### Примеры запросов
+Ниже показаны некоторые примеры работающих SQL-запросов.
+
+Простой запрос строки из таблицы по известному ID:
+
 ```
 SELECT "identification_number", "product_code" FROM "hash_testing"
         WHERE "identification_number" = 1"
 ```
-
+Запрос с двумя вариантами условий, в каждом из которых используется оператор `AND`:
 ```
 SELECT "identification_number", "product_code"
         FROM "hash_testing"
@@ -29,6 +33,8 @@ SELECT "identification_number", "product_code"
         OR "identification_number" = 2 AND "product_code" = '2'
 ```
 
+Пример запроса со вложенными подзапросами `SELECT`, объединенными оператором `UNION ALL`:
+
 ```
 SELECT *
         FROM
@@ -131,25 +137,50 @@ SELECT *
 
 Схема возможных запросов `INSERT` показана ниже.
 
-**insert**
 
 ![Insert](ebnf/insert.svg)
 
 ### Пример запроса
+Для примера вставим строки значений из таблицы `t2`в таблицу `t1` с использованием подзапроса `SELECT`:
 ```
-INSERT INTO "t" VALUES(1, 2, 3, 4)
+INSERT INTO "t1" FROM (SELECT id, id2 FROM t2)
 ```
-
+t2
 Используется в:
 
 * query
 
+**_Примечание._**
+На данный момент команда `INSERT` не гарантирует транзакционность
+при записи данных на несколько инстансов. Возможна ситуация, когда данные
+будут успешно зафиксированы на одном инстансе, но отменены на другом. В
+результате, пользователь может получить данные в несогласованном состоянии.
+В случае же, если все вставляемые данные попадают на один инстанс, подобная
+несогласованность исключена. Поэтому, вставка данных больше чем на
+один инстанс крайне нежелательна в промышленной эксплуатации (но приемлема для
+тестов).
+
+## Использование VALUES
+Команда `VALUES` представляет собой конструктор строки значений для
+использования в запросах `SELECT` и `INSERT`. В некотором смысле,
+передаваемые с `VALUES` значения являются временной таблицей, которая
+существует только в рамках запроса.
+
+Пример использования с `SELECT`:
+```
+SELECT id, id2 FROM hash_testing WHERE (id, id2) in (VALUES (1, 2), (2, 3))
+```
+Здесь в таблицу hash_testing будет вставлены две строки: (1, 2) и (2, 3).
 
-### **values**
+Пример использования со вставкой строки значений в таблицу при помощи команды `INSERT`:
 
-![Values](ebnf/values.svg)
+```
+INSERT INTO "t" VALUES(1, 2, 3, 4)
+```
 
+### **values**
 
+![Values](ebnf/values.svg)
 
 Используется в:
 

mkdocs.yml

@@ -15,7 +15,7 @@ nav:
     - Пример работы с кластером Picodata: tutorial.md
   - Справочные материалы:
     - Описание параметров запуска Picodata: cli.md
-    - Глоссарий основных терминов и определений: sbroad/sql_glossary
+    - Глоссарий основных терминов и определений: glossary.md
     - Поддерживаемые функции стандарта SQL: sbroad/sql_reference.md