[Документация Yandex Cloud](../../index.md) > [Yandex Object Storage](../index.md) > [Концепции](index.md) > Язык запросов S3 Select

# Синтаксис языка запросов S3 Select

{% note info %}

Чтобы получить возможность отправлять запросы на языке S3 Select, обратитесь в [техническую поддержку](https://center.yandex.cloud/support).

{% endnote %}

Язык S3 Select использует только оператор `SELECT` из стандартного языка SQL. Поддерживаются следующие стандартные ANSI-предложения:

* SELECT
* FROM
* WHERE
* LIMIT

Вложенные запросы и соединения не поддерживаются.

## SELECT {#select-list}

Данные объекта, которые возвращает запрос: имена столбцов, функций и выражений.

Синтаксис:

```sql
SELECT *
SELECT projection [ AS column_alias | column_alias ] [, ...]
```

Первая форма предложения возвращает каждую строку, удовлетворяющую условию в предложении `WHERE`, как есть. Вторая форма возвращает строку с пользовательской проекцией выходных скалярных выражений для каждого столбца.


## FROM {#from-clause}

Источник данных для `SELECT`. В качестве аргумента принимает имя объекта Object Storage.

Синтаксис:

```sql
FROM S3Object
FROM S3Object alias
FROM S3Object AS alias
```

Как и в стандартном языке SQL, предложение `FROM` создает строки, которые фильтруются в предложении `WHERE` и возвращаются в виде списка данных, указанных в `SELECT`.


## WHERE {#where-clause}

Фильтрует строки на основе заданного условия. Условие задается в виде логического выражения. В результате возвращаются только те строки, для которых значение выражения равно `TRUE`.

Синтаксис:

```sql
WHERE condition
```


## LIMIT {#limit-clause}

Ограничивает количество записей, которые возвращает запрос.

Синтаксис:

```sql
LIMIT number
```


## Доступ к атрибутам {#attribute-access}

Предложения `SELECT` и `WHERE` могут ссылаться на запись данных с помощью атрибутов файлов.

Атрибуты CSV-файлов:

* Номера столбцов.

  Вы можете ссылаться в запросе на определенный столбец с помощью имени `_N`, где `N` — порядковый номер столбца в файле.

  Нумерация столбцов начинается с 1. Например, первый столбец будет иметь имя `_1`, второй — `_2`.

  Имя столбца может быть задано как в формате `_N`, так и `alias._N`. Например, имена `_2` и `myAlias._2` являются допустимыми для ссылки на столбец в предложениях `SELECT` и `WHERE`.

* Заголовки столбцов.

  Как и в традиционном SQL, в выражениях внутри предложений `SELECT` и `WHERE` можно ссылаться на столбцы с помощью имени заголовка — `alias.column_name` или `column_name`.

Атрибуты JSON-файлов:

* Документ.

  Получить доступ к полям JSON-файла можно по их имени — `alias.name`.


**Примеры**

Образец данных в формате JSON:

```json
{"timestamp":"2021-02-26T01:27:19Z","object_key":"name1","status":404,"request_time":16}
{"timestamp":"2021-02-26T01:27:19Z","object_key":"name2","status":200,"request_time":12}
{"timestamp":"2021-02-26T01:27:20Z","object_key":"name3","status":200,"request_time":6}
```

Запрос:

```sql
SELECT "timestamp", object_key, request_time FROM S3Object WHERE status >= 400
```

Результат:

```json
{"timestamp":"2021-02-26T01:27:19Z","object_key":"name1","request_time":16}
```

Запрос:

```sql
SELECT * FROM S3Object WHERE request_time >= 10
```

Результат:

```json
{"timestamp":"2021-02-26T01:27:19Z","object_key":"name1","status":404,"request_time":16}
{"timestamp":"2021-02-26T01:27:19Z","object_key":"name2","status":200,"request_time":12}
```


## Чувствительность к регистру имен заголовков и атрибутов {#sensitivity}

Чтобы указать, что заголовки столбцов CSV-файлов или атрибуты JSON-файлов чувствительны к регистру, используются двойные кавычки. Заголовки и атрибуты объектов без двойных кавычек не будут чувствительны к регистру. Ошибка запроса в таком случае может возникнуть при неоднозначности имени поля.

**Примеры**

1. Запрашиваемый объект имеет заголовок/атрибут **NAME**.

    Если чувствительность к регистру не обозначена, запрос успешно возвращает данные объекта:

    ```sql
    SELECT s.name FROM S3Object s
    ```

    Если заключить заголовок/атрибут в двойные кавычки, запрос приводит к ошибке с кодом 400 `MissingHeaderName`:

    ```sql
    SELECT s."name" FROM S3Object s
    ```

1. Запрашиваемый объект имеет один заголовок/атрибут с именем **NAME** и другой заголовок/атрибут с именем **name**.

    Если чувствительность к регистру не обозначена, возникает неоднозначность в выборе заголовка/атрибута. Запрос при этом приводит к ошибке с кодом 400 `AmbiguousFieldName`:

    ```sql
    SELECT s.name FROM S3Object s
    ```

    Если заключить заголовок/атрибут в двойные кавычки, запрос успешно возвращает данные объекта:

    ```sql
    SELECT s."NAME" FROM S3Object s
    ```


## Зарезервированные ключевые слова {#reserved-keywords}

S3 Select имеет набор зарезервированных ключевых слов. Они необходимы для запуска SQL-выражений, используемых при запросе содержимого объекта. К зарезервированным ключевым словам относятся, например, имена функций, названия типов данных и операторы.

В некоторых случаях пользовательские термины могут совпадать с зарезервированным ключевым словом. Для избежания конфликта укажите с помощью двойных кавычек, что вы намеренно используете определенный термин. В противном случае возникнет синтаксическая ошибка с кодом 400.

**Примеры**

Запрашиваемый объект имеет заголовок/атрибут с именем **CAST**, который входит в список зарезервированных ключевых слов.

Если определенный пользователем заголовок/атрибут заключен в двойные кавычки, запрос успешно возвращает данные объекта:

```sql
SELECT s."CAST" FROM S3Object s
```

Если определенный пользователем заголовок/атрибут не заключен в двойные кавычки, возникает конфликт с зарезервированным ключевым словом. Запрос при этом приводит к синтаксической ошибке с кодом 400:

```sql
SELECT s.CAST FROM S3Object s
```

## Скалярные выражения {#scalar-expressions}

В предложениях `WHERE` и `SELECT` у вас могут быть скалярные выражения SQL, которые возвращают скалярные значения. Они могут иметь следующий вид:

* `literal`. Литерал SQL. Литерал — это явное числовое, символьное, строковое или логическое значение (константа), не представленное идентификатором.

* `column_reference`. Ссылка на столбец вида `column_name` или `alias.column_name`. Используется для обращения к столбцу с помощью имени заголовка.

  Пример:

  ```sql
  SELECT city.name FROM S3Object city
  ```

* `unary_op expression`. В этом выражении `unary_op` — унарный SQL-оператор. Унарные операторы выполняют операцию над одним операндом. К ним относится, например, унарный минус, который меняет знак числа.

  Пример:

  ```sql
  SELECT -5 FROM S3Object
  ```

* `expression binary_op expression`. В этом выражении `binary_op` — бинарный SQL-оператор. Бинарные операторы выполняют операцию над двумя операндами. Например, к бинарным относятся арифметические и логические операторы, операторы сравнения.

  Примеры:

  ```sql
  SELECT x FROM S3Object WHERE x=3
  ```

  ```sql
  SELECT result FROM S3Object WHERE result>=1 AND result<=5
  ```

* `func_name`. В этом выражении `func_name` — имя скалярной функции для вызова.

  Пример:

  ```sql
  SELECT CAST(status AS INT) FROM S3Object
  ```

* `expression [ NOT ] BETWEEN expression AND expression`. Проверка значения на вхождение в диапазон.

  Пример:

  ```sql
  SELECT x FROM S3Object WHERE x BETWEEN -1 AND 1
  ```

## Агрегатные функции {#aggregate-functions}

В предложении `SELECT` можно использовать _агрегатные функции_, которые вычисляются от значений в нескольких или во всех строках и возвращают одно результирующее значение.

Поддерживаются следующие функции:

| Функция | Описание | Тип на входе | Тип на выходе |
| ----- | ----- | ----- | ----- |
| `COUNT` | Количество строк | Любой | `INT` |
| `MIN` | Минимум среди значений | `INT` или `DECIMAL` | Как на входе |
| `MAX` | Максимум среди значений | `INT` или `DECIMAL` | Как на входе |
| `SUM` | Сумма значений | `INT`, `FLOAT` или `DECIMAL` | Как на входе |
| `AVG` | Среднее значение | `INT`, `FLOAT` или `DECIMAL` | Если на входе `INT` — `DECIMAL`,<br/>в остальных случаях — как на входе |

Примеры:

{% list tabs group=data_format %}

- JSON {#json}

  Образец данных:

  ```json
  {"timestamp":"2021-02-26T01:27:19Z","object_key":"name1","status":404,"request_time":16}
  {"timestamp":"2021-02-26T01:27:19Z","object_key":"name2","status":200,"request_time":12}
  {"timestamp":"2021-02-26T01:27:20Z","object_key":"name3","status":200,"request_time":6}
  ```

  Запрос с использованием всех агрегатных функций:

  ```sql
  SELECT
    COUNT(*) AS "count",
    MIN(request_time) AS "min",
    MAX(request_time) AS "max",
    SUM(request_time) AS "sum",
    AVG(request_time) AS "avg"
  FROM S3Object
  WHERE status = 200
  ```

  Результат:

  ```json
  {"count": 2, "min": 6, "max": 12, "sum": 18, "avg": 9.0}
  ```

- CSV {#csv}

  Образец данных:

  ```csv
  timestamp,object_key,status,request_time
  2021-02-26T01:27:19Z,name1,404,16
  2021-02-26T01:27:19Z,name2,200,12
  2021-02-26T01:27:20Z,name3,200,6
  ```

  Запрос с использованием всех агрегатных функций:

  ```sql
  SELECT
    COUNT(*) AS "count",
    MIN(CAST(request_time AS FLOAT)) AS "min",
    MAX(CAST(request_time AS FLOAT)) AS "max",
    SUM(CAST(request_time AS FLOAT)) AS "sum",
    AVG(CAST(request_time AS FLOAT)) AS "avg"
  FROM S3Object
  WHERE status = '200'
  ```

  Так как все значения во входных CSV-файлах считаются строками, их нужно приводить к нужным типам с помощью функции `CAST`.

  Результат:

  ```text
  count,min,max,sum,avg
  2,6,12,18,9.0
  ```

{% endlist %}


## Примеры использования {#examples}

* [Получение статистики запросов к объекту с использованием S3 Select](../tutorials/server-logs.md)
* [Получение статистики посещения сайта с использованием S3 Select](../tutorials/user-agent-statistics.md)
* [Анализ поресурсной детализации расходов](../tutorials/billing-resource-detailing.md)