# Змінні сеансу

> Змінні сеансу в StackQL: типізовані скалярні значення з SET, розіменування через $name у предикатах і виразах, імена відношень і стовпців з IDENTIFIER.

Source: https://stackql.io/uk/getting-started/session-variables

Див. також:  
[[` SET `]](/language-spec/set) [[` UNSET `]](/language-spec/unset) [[ Сеанси провайдерів ]](/getting-started/provider-sessions) [[ Використання змінних ]](/getting-started/variables)

Змінні сеансу - це скалярні значення, які зберігає поточний сеанс і на які посилаються наступні інструкції.  Вони доступні в StackQL `v1.0` і новіших версіях і працюють в інтерактивній оболонці, у скриптах `exec`, через мережевий протокол PostgreSQL і через сервер MCP.

Змінні сеансу відрізняються від змінних шаблонізації, описаних на сторінці [Використання змінних](/getting-started/variables).  Змінні шаблонізації передаються команді `stackql exec` через `--iqldata` і `--var` і підставляються в текст скрипту до його синтаксичного аналізу.  Змінні сеансу визначаються всередині проаналізованої інструкції, зберігають свій тип і можуть змінюватися між інструкціями.

## Встановлення та видалення змінних

Інструкція [`SET`](/language-spec/set) присвоює рядкове значення, число, логічне значення або `null`.  Інструкція [`UNSET`](/language-spec/unset) видаляє змінну; `SET name = DEFAULT` діє так само.  Явне значення `null` - це збережене значення, а не скидання.

```sql
SET region = 'ap-southeast-2';
SET minimum_count = 3;
SET enabled = true;
SET optional_value = null;
UNSET region;
```

Масиви й об'єкти не є скалярними значеннями.  Щоб зберегти документ JSON, запишіть його як рядкове значення:

```sql
SET "providers.saved" = '{"provider":"aws","tenancy":"production"}';
```

## Розіменування змінної

Використовуйте `$name` без лапок у будь-якій позиції виразу.  Рядкові значення екрануються як літерали SQL; числа, логічні значення та `null` зберігають свій тип.  `'$name'` в одинарних лапках - це літеральний текст `$name`, а не розіменування.  Посилання на змінну, якої не існує, завершується помилкою ще до будь-якого запиту до провайдера.

Визначені значення можна використовувати у звичайних виразах SQL, зокрема в `CAST`, `CONVERT`, конкатенації через `||` і викликах функцій:

```sql
SET some_id = 42;
SET suffix = 'East';

SELECT CAST($some_id AS TEXT) AS id_text,
       CONVERT($some_id, TEXT) || '-' || lower($suffix) AS label,
       md5(lower(CONVERT($some_id, TEXT) || '-' || $suffix)) AS digest,
       '$some_id' AS literal_text;
```

Присвоєння приймають лише скалярні літерали або прямі посилання; застосовуйте перетворення та інші вирази там, де змінну використовують, а не в інструкції `SET`.

## Змінні в предикатах

Змінна в реченні `WHERE` визначається до планування інструкції, тому вона передається в API провайдера точно так, як і літерал.  Отже, обов'язкові параметри можна передавати зі змінних:

```sql
SET project = 'stackql-demo';
SET zone = 'australia-southeast1-a';

SELECT name, status
FROM google.compute.instances
WHERE project = $project AND zone = $zone;
```

Типізовані значення порівнюються з урахуванням їхнього типу.  `WHERE active = $enabled` із `SET enabled = false` фільтрує за логічним значенням, а `WHERE id = CAST($some_id AS TEXT)` - це форма, яку слід використовувати, коли стовпець провайдера рядковий, а змінна є числом.

## Змінні як імена об'єктів

Змінні можуть бути не лише значеннями, а й іменами відношень і стовпців.  Імена перетворюються на ідентифікатори в проаналізованій інструкції й ніколи не вставляються в текст SQL, тому значення, яке містить інструкцію, порожнє або не є рядковим, відхиляється ще до будь-якого звернення до провайдера.

| Позиція | Форма |
|--|--|
| Речення `FROM` | `FROM $relation_name` або за компонентами: `FROM $provider.$service.$resource` |
| Стовпець у виразі | `IDENTIFIER($column_name)`, див. [`IDENTIFIER`](/language-spec/functions/general/identifier) |
| Псевдонім стовпця або таблиці | `AS "$alias_name"` |
| `ORDER BY` | `ORDER BY IDENTIFIER($column_name)` |
| `LIMIT` | `LIMIT $row_count` |
| Імена стовпців у DDL, списки стовпців в `INSERT`, цілі `UPDATE` | форма `"$name"` у подвійних лапках |

```sql
SET relation_name = 'aws.s3.buckets';
SET column_name = 'name';
SET output_name = 'bucket';
SET row_count = 10;

SELECT IDENTIFIER($column_name) AS "$output_name"
FROM $relation_name
WHERE region = 'ap-southeast-2'
ORDER BY IDENTIFIER($column_name)
LIMIT $row_count;
```

З'єднання, CTE і підзапити так само визначають свої змінні відношень.  Значення відношень із крапками мають до чотирьох компонентів.  Змінні не є довільними фрагментами SQL: ключове слово, список стовпців через кому або ціле речення `WHERE` підставити не можна.

## Область дії та ізоляція

Змінні належать сеансу, який їх встановив.  Окремі з'єднання із сервером `stackql srv` мають окремі змінні, як і окремі виклики `exec`.  Кожен запит MCP є окремим сеансом, тому інструкцію `SET` і запит, який використовує змінну, потрібно надсилати в одному пакеті інструкцій.  Нові сеанси починаються без змінних.

Сеанс - єдина область дії.  `SET SESSION` і `UNSET SESSION` приймаються й означають те саме, що `SET` і `UNSET`; це ключове слово існує для скриптів, які мають читатися так само, як у базах даних, де налаштування сеансу й глобальні налаштування відрізняються.  `GLOBAL` відхиляється, оскільки спільного для сеансів стану немає.

Підготовлені інструкції визначають змінні під час виконання, а не під час підготовки, і план, що містить прив'язані значення сеансу, не використовується повторно між виконаннями.

Якщо ввімкнено [керування доступом](/command-line-usage/access-management), для читання змінної потрібен дозвіл `session/variables:read`, а для її встановлення або скидання - `session/config:write`.  Визначення змінної як імені об'єкта не надає жодного дозволу на цей об'єкт; визначене відношення, як зазвичай, авторизується перед виконанням.
