Директивы SQLly
функциональныйНебольшие SQL-комментарии, которые запоминают вид результата: столбцы, ширину, форматы, цвета, сводную таблицу и диаграмму.
A директива это обычный комментарий SQL, который понимает SQLly. Для базы данных это просто комментарий, в то время как SQLly использует его для формирования или форматирования результата. Поскольку директивы находятся в тексте запроса, они путешествуют вместе с файлом и применяются каждый раз, когда вы его запускаете.
У всех директив одно пространство имён — слово sqlly после маркера комментария:
-- sqlly view: pivot
-- sqlly grid: order=Region, Year, Sales; freeze=1; sort=Sales desc
-- sqlly pivot: row:Region; column:Year; value:Sales:sum
-- sqlly chart: kind:bar; label:Region; values:Sales
-- sqlly format: column=Sales; number=2; width=40dp
-- sqlly conditional: column=Sales; bar=#5B9BD5
-- sqlly column: Running Total = !Sales + N(!"Running Total"[1])
-- sqlly map: lat=Latitude; lon=Longitude; color=Region; cluster=on
Вам редко приходится их набирать. Расположите результат так, как вам нравится, затем нажмите заблокировать перед именем результата: SQLly записывает всю компоновку в запрос как один блок директив. Смотрите Заблокировать сетку.
Семейства директив
| Директива | Что оно делает | Пример |
|---|---|---|
view: | Открывает результат как grid (по умолчанию), pivot, или chart; map сохраняет сетку и также открывает результат на карте. | -- sqlly view: chart |
grid: | Расположение столбцов сетки: порядок, скрытые и закреплённые столбцы, сортировка, группировка, фильтры столбцов и метки внешних ключей. grid 2: устанавливает один набор результатов, начиная с 1. | -- sqlly grid: hide=Notes; freeze=1; sort=Total desc |
format: | Как отображается один столбец результата и какая у него ширина. | -- sqlly format: column=Created; date=%Y-%m-%d; width=40dp |
conditional: | Окрашивает ячейки по их значениям для этого запроса: правило выделения, цветовая шкала или полоса данных. Одно правило на строку. | -- sqlly conditional: column=Status; when=is Failed; text=#B00020; bold |
column: | Добавляет столбец, вычисляемый по формуле Excel на основе собственных столбцов результата: !Name — это та самая строка, !Name[1] предыдущая строка. Функции и операторы Excel. | -- sqlly column: Total = !Qty * !Price |
pivot: | Строки, столбцы и агрегированное значение сводной таблицы. result:N выбирает набор результатов, к которому он принадлежит. | -- sqlly pivot: row:Rep; column:Quarter; value:Deals:count |
chart: | Тип диаграммы, метка категории, серия и агрегирование. result:N выбирает набор результатов, к которому он принадлежит. | -- sqlly chart: kind:line; label:Month; values:Revenue,Cost |
map: | Как результат отображается на карте: столбцы местоположения, метки и всплывающие подсказки, цвет и размер, точки или тепловую карту (вес, радиус, размытие, интенсивность, непрозрачность, палитра), кластеризация, карта улиц, начальный вид, поведение при клике и то, открывается ли карта сама. map 2: устанавливает один набор результатов, начиная с 1. | -- sqlly map: mode=heatmap; weight=orders; radius=30 |
/* sqlly lock | Блочный комментарий, который SQLly пишет при нажатии на замок у результата. Его -- sqlly строки точно воспроизводят результат таким, какой он был. | /* sqlly lock — … … */ |
name | Помечает вкладку набора результатов номером, начиная с 1. Удобно, когда пакет возвращает несколько. | -- sqlly name 2: Open Orders |
2x2 / result: | Размещает несколько наборов результатов на одном холсте, помещая результат каждого запроса в ячейку. | -- sqlly result: 1|2 |
layout: | Открывает результаты выполнения как stacked, tabbed, или canvas, где бы файл ни был открыт. | -- sqlly layout: stacked |
lines: | Сколько строк отведено каждой карточке в стопке; lines 2: устанавливает один набор результатов, начиная с 1. | -- sqlly lines 2: 20 |
focus: | Какой набор результатов показан, когда приходят результаты: в режиме Tabbed выбирается его вкладка, в режиме Stacked его карточка прокручивается в поле зрения. Отсчёт с 1. | -- sqlly focus: 2 |
param: | Объявляет параметр или задаёт :name заполнителю тип и значение по умолчанию. Полоса над результатами позволяет ввести его значение перед каждым запуском; обычные :id, ? и $1 заполнители получают её и без объявления (см. Параметры запроса). | -- sqlly param: @CustomerId int |
set | Определяет текстовую переменную, которая заменяет каждое ${name} перед выполнением запроса. | -- sqlly set schema = dbo |
param: и set — это два места, которые меняют то, что получает база данных. SQLly подставляет их значения в SQL перед отправкой, вне строк и комментариев. Значение параметра попадает в запрос как экранированный литерал объявленного типа (text, int, decimal, bool, date, или datetime). set подставляется дословно. Вычисляемый столбец формулы читаются как @name.
Где должна находиться директива
- На отдельной строке. Директива после SQL-кода на той же строке игнорируется.
name— это единственное исключение и работает как завершающий комментарий. view:и размер холста указываются в первой строке. Они считываются только из первой непустой строки запроса. Если вверху стоит блок lock, первой строкой считается первая строка с директивой внутри этого блока.- Пробелы не критичны для большинства семейств:
--sqlly view: pivotи-- SQLLY view: pivotоба варианта работают. format:является строгим. Он должен быть написан в точности-- sqlly format:с пробелом после--.- Внутри блочного комментария директива отключается - так удобно отключить одну из них на время. Единственное исключение —
/* sqlly lockблок: его строки работают точно так, как если бы каждая была написана на своей строке.
-- sqlly view: pivot -- sqlly pivot: row:Region; column:Year; value:Sales:sum -- sqlly format: column=Sales; number=2 SELECT Region, Year, Sales FROM sales;
sqlly пространство имён, но написано с опечаткой, размещено там, где не может применяться, или получило неизвестное значение, SQLly подчёркивает это в редакторе и объясняет причину, а не молча игнорирует. Например, -- sqlly view: table станет Неизвестный вид — ожидалось -- sqlly view: grid, -- sqlly view: pivot, -- sqlly view: chart, или -- sqlly view: map.Autocomplete as you type
You don't have to remember any of the spellings above. As soon as a comment looks like a directive, the editor's suggestion list follows the cursor through it and offers the next thing the directive can take:
| You have typed | The list offers |
|---|---|
-- on a line of its own | A ready-made starter line for each kind of directive. view: and the canvas size are offered only on the query's first line, where they work. |
-- sq | Этот sqlly namespace. |
-- sqlly | Every directive family: view:, grid:, format:, pivot:, chart: and the rest. |
-- sqlly grid: | The settings that family takes, leaving out the ones already on the line. |
-- sqlly grid: sort= | The values that setting accepts: here the result's columns. Elsewhere chart kinds, pivot aggregates, filter operators, map modes, number and date formats, time zones, colors. |
-- sqlly grid: sort=Total | What may follow the value: here asc или desc. |
- One choice opens the next. Accepting a setting opens its values straight away, so a whole directive can be built by picking from lists with Tab or Enter.
- Your real column names. Wherever a directive expects a column, the list shows the columns the tab's last run returned, quoted the way that directive needs them. Run the query once to get them.
- Formulas and parameters too. In a
column:formula the list completes column references, Excel worksheet functions and@variables. On aparam:line it offers the query's placeholders that are not declared yet, then every parameter type. - Only what works. Everything in the list is exactly what the directive accepts, so an accepted suggestion never earns the warning underline described above.
- Bring it back anywhere inside a directive with Ctrl+Пробел, on macOS too.
Справка в приложении
- Наведение курсора любое
-- sqllyкомментарий для краткого описания со ссылкой на полный список опций. - Справка ▸ Директивы форматирования… (также в палитре команд) открывает справочное окно с каждым семейством, его параметрами и готовыми к копированию примерами.
- Пусть SQLly это напишет. Нажмите на замок перед названием результата, чтобы записать весь результат как директивы, или щелкните правой кнопкой мыши заголовок столбца результата и выберите Формат › Переопределить форматирование… чтобы для вас записалась одна
format:директива, написанная за вас.
В этом разделе
- Сетка
- Запишите порядок столбцов, скрытые и замороженные столбцы, сортировку, группировку и фильтры в запрос.
- Форматирование в процессе
- Задавайте каждому столбцу то оформление и ту ширину, которых он заслуживает, автоматически при каждом выполнении запроса.
- Условные конструкции
- Окрашивайте ячейки в зависимости от их значения для одного запроса: правила подсветки, цветовые шкалы и полосы данных.
- Вычисляемые столбцы
- Добавляйте столбцы, записанные как формулы Excel: накопительные итоги, маржи, изменения по сравнению с предыдущей строкой и даты.
- Сводная таблица
- Превратите привычный набор результатов в сводную таблицу коротким переносимым комментарием.
- Диаграмма
- Скажите вкладке «Диаграмма», какую историю рисовать, ещё до того, как результат появится.
- Заблокировать сетку
- Один клик записывает результат в запрос ровно в том виде, как он выглядит сейчас, чтобы при каждом запуске он возвращался одинаковым.