YQL - начало работы

Введение

YQL - язык запросов к базе данных YDB, диалект SQL. В частности, он обладает синтаксическими особенностями, рассчитанными на его применение при исполнении запросов на кластерах.

Полная информация по синтаксису YQL находится в справочнике по YQL.

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

Базовый интерфейс YDB YQL принимает на вход не одну команду, а скрипт, который может состоять из множества команд.

Инструменты исполнения YQL

YDB предоставляет следующие инструменты для отправки запроса к базе данных на языке YQL:

Встроенный web-интерфейс YDB

Для выполнения запросов и скриптов YQL на самостоятельно развернутых базах данных YDB можно использовать встроенный web-интерфейс YDB. При локальной установке с использованием Docker с параметрами по умолчанию он доступен на http://localhost:8765.

Выберите пункт Databases в меню слева, кликните на базе данных в списке, переключитесь на закладку Query:

embedded_query

Для выполнения YQL-скрипта нажмите кнопку Run Script.

YDB CLI

Для исполнения скриптов через YDB CLI нужно предварительно:

  1. Установить YDB CLI.
  2. Создать профиль, настроенный на соединение с вашей БД.

Примечание

В примерах используется профиль quickstart, подробнее смотрите в Создание профиля для соединения с тестовой БД.

Текст приведенных ниже скриптов нужно сохранить в файл. Назовите его script.yql, чтобы команды в примерах можно было выполнить простым копированием через буфер обмена. Далее выполните команду ydb yql с указанием использования профиля quickstart и чтения скрипта из файла script.yql:

ydb --profile quickstart yql -f script.yql

Работа со схемой данных

Создание таблиц

Таблица с заданными колонками создается командой YQL CREATE TABLE. В таблице обязательно должен быть определен первичный ключ. Типы данных для колонок приведены в статье Типы данных YQL.

По умолчанию все колонки опциональные и могут содержать NULL. Для колонок, входящих в первичный ключ, можно указать ограничение NOT NULL. Ограничения FOREIGN KEY YDB не поддерживает.

Создайте таблицы каталога сериалов: series (Сериалы), seasons (Сезоны), и episodes (Эпизоды), выполнив следующий скрипт:

CREATE TABLE series (
    series_id Uint64 NOT NULL,
    title Utf8,
    series_info Utf8,
    release_date Date,
    PRIMARY KEY (series_id)
);

CREATE TABLE seasons (
    series_id Uint64,
    season_id Uint64,
    title Utf8,
    first_aired Date,
    last_aired Date,
    PRIMARY KEY (series_id, season_id)
);

CREATE TABLE episodes (
    series_id Uint64,
    season_id Uint64,
    episode_id Uint64,
    title Utf8,
    air_date Date,
    PRIMARY KEY (series_id, season_id, episode_id)
);

Описание всех возможностей работы с таблицами приведены в разделах документации по YQL:

  • CREATE TABLE — создание таблицы и определение начальных параметров.
  • ALTER TABLE — изменение состава колонок таблицы и ее параметров.
  • DROP TABLE — удаление таблицы.

Для исполнения скрипта через YDB CLI выполните инструкции, приведенные в пункте Исполнение в YDB CLI данной статьи.

Создание колоночной таблицы

Таблица с заданными колонками создается командой YQL CREATE TABLE. В таблице обязательно должен быть определен первичный ключ и ключ партицирования. Допустимые для использования в аналитических таблицах типы данных описаны в разделе Поддерживаемые типы данных колоночных таблиц.

Колонки, входящие в первичный ключ, должны быть описаны с ограничением NOT NULL. Остальные колонки по умолчанию опциональные и могут содержать NULL. Ограничения FOREIGN KEY YDB не поддерживает.

Создайте таблицу каталога сериалов views (просмотры), выполнив следующий скрипт:

CREATE TABLE views (
    series_id Uint64 NOT NULL,
    season_id Uint64,
    viewed_at Timestamp NOT NULL,
    person_id Uint64 NOT NULL,
    PRIMARY KEY (viewed_at, series_id, person_id)
)
PARTITION BY HASH(viewed_at, series_id)
WITH (
  STORE = COLUMN,
  AUTO_PARTITIONING_MIN_PARTITIONS_COUNT = 10
)

Описание всех возможностей работы с таблицами приведены в разделах документации по YQL:

  • CREATE TABLE — создание таблицы и определение начальных параметров.
  • DROP TABLE — удаление таблицы.

Для исполнения скрипта через YDB CLI выполните инструкции, приведенные в пункте Исполнение в YDB CLI данной статьи.

Получение перечня существующих таблиц в БД

Проверьте, что таблицы фактически созданы в БД.

Во встроенном web-интерфейсе YDB перечень таблиц показывается в левой части страницы базы данных в виде иерархии. На закладке Info показывается детальная информация по выбранному в иерархии объекту.

Для получения перечня существующих таблиц в БД через YDB CLI убедитесь, что выполнены предварительные требования пункта Исполнение в YDB CLI данной статьи, и выполните команду scheme ls:

ydb --profile quickstart scheme ls

Работа с данными

Команды исполнения YQL запросов и скриптов в YDB CLI и web-интерфейсе работают в режиме Autocommit, то есть после успешного исполнения транзакция подтверждается автоматически.

UPSERT — запись данных

Самым эффективным способом записи данных в YDB является команда UPSERT. Она выполняет запись новых данных по первичным ключам независимо от того, существовали ли данные по этим ключам ранее в таблице. В результате, в отличие от привычных INSERT и UPDATE, ее исполнение не требует на сервере предварительного чтения данных для проверки уникальности ключа. Всегда при работе с YDB рассматривайте UPSERT как основной способ записи данных, используя другие команды только при необходимости.

Все команды записи данных в YDB поддерживают работу как с выборками, так и со множеством записей, передаваемых непосредственно в запросе.

Добавим данные в созданные ранее таблицы:

UPSERT INTO series (series_id, title, release_date, series_info)
VALUES
    (
        1,
        "IT Crowd",
        Date("2006-02-03"),
        "The IT Crowd is a British sitcom produced by Channel 4, written by Graham Linehan, produced by Ash Atalla and starring Chris O'Dowd, Richard Ayoade, Katherine Parkinson, and Matt Berry."),
    (
        2,
        "Silicon Valley",
        Date("2014-04-06"),
        "Silicon Valley is an American comedy television series created by Mike Judge, John Altschuler and Dave Krinsky. The series focuses on five young men who founded a startup company in Silicon Valley."
    )
    ;

UPSERT INTO seasons (series_id, season_id, title, first_aired, last_aired)
VALUES
    (1, 1, "Season 1", Date("2006-02-03"), Date("2006-03-03")),
    (1, 2, "Season 2", Date("2007-08-24"), Date("2007-09-28")),
    (2, 1, "Season 1", Date("2014-04-06"), Date("2014-06-01")),
    (2, 2, "Season 2", Date("2015-04-12"), Date("2015-06-14"))
;

UPSERT INTO episodes (series_id, season_id, episode_id, title, air_date)
VALUES
    (1, 1, 1, "Yesterday's Jam", Date("2006-02-03")),
    (1, 1, 2, "Calamity Jen", Date("2006-02-03")),
    (2, 1, 1, "Minimum Viable Product", Date("2014-04-06")),
    (2, 1, 2, "The Cap Table", Date("2014-04-13"))
;

Для исполнения скрипта через YDB CLI выполните инструкции, приведенные в пункте Исполнение в YDB CLI данной статьи.

Вы можете дополнительно ознакомиться с командами записи данных в справочнике YQL:

  • INSERT — добавление записей.
  • REPLACE — добавление/изменение записей.
  • UPDATE — изменение указанных полей.
  • UPSERT — добавление записей/изменение указанных полей.

SELECT — выборка данных

Запросите выборку записанных на предыдущем шаге данных:

SELECT 
    series_id,
    title AS series_title,
    release_date
FROM series;

или

SELECT * FROM episodes;

Если в скрипте YQL будет несколько команд SELECT, то в результате его исполнения будет возвращено несколько выборок, к каждой из которых можно обратиться отдельно. Выполните приведенные выше команды SELECT, объединенные в одном скрипте.

Для исполнения скрипта через YDB CLI выполните инструкции, приведенные в пункте Исполнение в YDB CLI данной статьи.

Вы можете дополнительно ознакомиться с полным описанием команд, связанных с выборкой данных, в справочнике YQL:

  • SELECT — выполнение выборки данных.
  • SELECT ... JOIN — соединение таблиц при выполнении выборки данных.
  • SELECT ... GROUP BY — группировка данных при выполнении выборки.

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

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

Для определения параметров в тексте запроса YQL применяется команда DECLARE.

Описание методов исполнения параметризованных запросов YDB SDK доступно в разделе Тестовый пример, в секции Параметризованные запросы для нужного языка программирования.

При отладке параметризованного запроса в YDB SDK вы можете проверить его работоспособность вызовом YDB CLI, скопировав полный текст запроса без каких-либо корректировок, и задав значения параметров.

Сохраните скрипт выполнения параметризованного запроса в текстовом файле script.yql:

DECLARE $seriesId AS Uint64;
DECLARE $seasonId AS Uint64;

SELECT sa.title AS season_title, sr.title AS series_title
FROM   seasons AS sa
INNER JOIN series AS sr ON sa.series_id = sr.series_id
WHERE sa.series_id = $seriesId AND sa.season_id = $seasonId;

Для выполнения параметризованной выборки убедитесь, что выполнены предварительные требования пункта Исполнение в YDB CLI данной статьи, и выполните следующую команду:

ydb --profile quickstart yql -f script.yql -p '$seriesId=1' -p '$seasonId=1'

Полное описание возможностей передачи параметров находится в справочнике по YDB CLI.

Туториал YQL

Вы можете изучить больше примеров использования YQL, выполняя задания из Туториала YQL.

Предыдущая
Обзор
Следующая
Обзор
В этой статье: