# DESCRIBE

> DESCRIBE у StackQL: виведення полів ресурсу або параметрів і типу значення, що повертається, певного методу перед запитом до нього чи зміненням даних.

Source: https://stackql.io/uk/language-spec/describe

Описує ресурс або певний метод ресурсу.

Див. також:
[[ Ієрархія ресурсів StackQL ]](/getting-started/resource-hierarchy)

* * *

## Синтаксис

*describeStatement::=*

&nbsp;
&nbsp;

```sql
DESCRIBE [ METHOD ] [ EXTENDED ] <multipartIdentifier> ;
DESC [ EXTENDED ] <multipartIdentifier> ;
```

Під час опису ресурсу `DESC` можна використовувати як псевдонім `DESCRIBE`; `DESCRIBE METHOD` потребує повного ключового слова.

## Відповідь

**DESCRIBE**

| Стовпець | Опис |
| --- | --- |
| `name` | Ім'я поля |
| `type` | Тип даних (`string`, `integer`, `boolean`, `number`, `object`, `array`) |
| `description` | Опис поля (якщо вказано `EXTENDED`) |

**DESCRIBE METHOD**

| Стовпець | Опис |
| --- | --- |
| `name` | Ім'я поля |
| `type` | Тип даних (`string`, `integer`, `boolean`, `number`, `object`, `array`) |
| `param_type` | `input_required`, `input_optional` або `output` |
| `shape` | Підмножина JSON Schema для полів з об'єктами й масивами; порожня для скалярних полів. Містить вкладені `properties`, `items`, `required`, `enum`, `default`, `description`, а також, якщо провайдер їх надає, логічні значення (`readOnly`, `writeOnly`, `deprecated`) |
| `description` | Опис поля (якщо вказано `EXTENDED`) |

* * *

## Приклади

### Базова інструкція `DESCRIBE`
Виконайте базову інструкцію `DESCRIBE`, щоб вивести список полів ресурсу з автентифікованого сеансу.

```sql
-- Show the available fields in a Compute Engine resource
DESCRIBE google.compute.instances;
```

### Розширена інструкція `DESCRIBE`
Виконайте розширену інструкцію `DESCRIBE`, щоб вивести список полів ресурсу та їхні описи з автентифікованого сеансу.

```sql
-- Show the available fields in a Compute Engine resource
DESCRIBE EXTENDED google.compute.instances;
```

### Псевдонім `DESC`
`DESC` - скорочений запис `DESCRIBE` для ресурсу, з `EXTENDED` або без нього.  Його вважають інструкцією лише для читання скрізь, де такою вважають `DESCRIBE`, зокрема в інструменті `run_select_query` сервера MCP у режимах `read_only` і `safe`.

```sql
-- Same result as DESCRIBE EXTENDED google.compute.instances
DESC EXTENDED google.compute.instances;
```

### Базова інструкція `DESCRIBE METHOD`
Отримайте опис окремого методу ресурсу. Результат містить вхідні параметри й поля відповіді, а вкладену структуру відображено в стовпці `shape`.

```sql
-- Show the inputs and outputs for the buckets.get method
DESCRIBE METHOD google.storage.buckets.get;
```

### Розширена інструкція `DESCRIBE METHOD`
Виконайте розширену інструкцію `DESCRIBE METHOD`, щоб разом із формою отримати опис кожного поля.

```sql
-- Show inputs, outputs, and descriptions for the buckets.insert method
DESCRIBE METHOD EXTENDED google.storage.buckets.insert;
```

### Визначення корисного навантаження для `INSERT`
`DESCRIBE METHOD` - канонічний спосіб дізнатися, які поля приймає `INSERT` (або будь-який метод, що змінює дані). Стовпець `shape` містить вкладену структуру, за якою агенти й люди можуть сформувати корисне навантаження за один запит.

```sql
-- See what google.compute.instances.insert requires
DESCRIBE METHOD EXTENDED google.compute.instances.insert;
```
