Diretivas do SQLly
funcionalPequenos comentários SQL que lembram como um resultado se parece: suas colunas, larguras, formatos, cores, pivô e gráfico.
A diretiva é um comentário SQL comum que o SQLly entende. Para o banco de dados, é apenas um comentário, enquanto o SQLly o utiliza para moldar ou formatar o resultado. Como as diretivas vivem no texto da consulta, elas viajam com o arquivo e se aplicam novamente toda vez que você o executa.
Cada diretiva compartilha o mesmo namespace - a palavra sqlly depois do marcador de comentário:
-- 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
Você raramente precisa digitá-las. Organize o resultado da maneira que preferir, e então clique no bloquear na frente do nome do resultado: o SQLly escreve toda a organização na consulta como um bloco de diretivas. Veja Bloquear grade.
As famílias de diretivas
| Diretiva | O que faz | Exemplo |
|---|---|---|
view: | Abre o resultado como grid (o padrão), pivot, ou chart; map mantém a grade e também abre o resultado em um mapa. | -- sqlly view: chart |
grid: | A disposição das colunas da grade: ordem, colunas ocultas e fixas, ordenação, agrupamento, filtros de colunas e rótulos de chave estrangeira. grid 2: define um conjunto de resultados, contando a partir de 1. | -- sqlly grid: hide=Notes; freeze=1; sort=Total desc |
format: | Como uma coluna de resultado é exibida e qual a largura dela. | -- sqlly format: column=Created; date=%Y-%m-%d; width=40dp |
conditional: | Colore células pelos seus valores nesta consulta: uma regra de destaque, uma escala de cores ou uma barra de dados. Uma regra por linha. | -- sqlly conditional: column=Status; when=is Failed; text=#B00020; bold |
column: | Adiciona uma coluna calculada com uma fórmula do Excel a partir das próprias colunas do resultado: !Name é esta linha, !Name[1] a linha anterior. Funções e operadores do Excel. | -- sqlly column: Total = !Qty * !Price |
pivot: | Linhas, colunas e o valor agregado de uma tabela dinâmica. result:N seleciona o conjunto de resultados ao qual pertence. | -- sqlly pivot: row:Rep; column:Quarter; value:Deals:count |
chart: | Tipo de gráfico, rótulo da categoria, série e agregação. result:N seleciona o conjunto de resultados ao qual pertence. | -- sqlly chart: kind:line; label:Month; values:Revenue,Cost |
map: | Como um resultado é desenhado no mapa: colunas de localização, rótulos e dicas de ferramenta, cor e tamanho, pontos ou mapa de calor (peso, raio, desfoque, intensidade, opacidade, paleta), agrupamento, o mapa de ruas, a visão inicial, comportamento ao clicar e se o mapa abre sozinho. map 2: define um conjunto de resultados, contando a partir de 1. | -- sqlly map: mode=heatmap; weight=orders; radius=30 |
/* sqlly lock | Um comentário em bloco que o SQLly escreve quando você clica no cadeado de um resultado. Suas -- sqlly linhas reproduzem o resultado exatamente como apareceu. | /* sqlly lock — … … */ |
name | Rotula a aba de um conjunto de resultados, contando a partir de 1. Útil quando um lote retorna vários. | -- sqlly name 2: Open Orders |
2x2 / result: | Distribui vários conjuntos de resultados em uma única tela, colocando o resultado de cada instrução em uma célula. | -- sqlly result: 1|2 |
layout: | Abre os resultados da execução como stacked, tabbed, ou canvas, onde quer que o arquivo seja aberto. | -- sqlly layout: stacked |
lines: | Linhas atribuídas a cada cartão empilhado; lines 2: define um conjunto de resultados, contando a partir de 1. | -- sqlly lines 2: 20 |
focus: | Qual conjunto de resultados está em exibição quando os resultados chegam: sua aba está selecionada em Em Abas, e seu cartão está rolado para visualização em Empilhado. A contagem começa em 1. | -- sqlly focus: 2 |
param: | Declara um parâmetro, ou dá um :name placeholder um tipo e padrão. Uma faixa acima dos resultados permite digitar seu valor antes de cada execução; placeholders simples :id, ? e $1 recebem um sem declaração (veja Parâmetros de consulta). | -- sqlly param: @CustomerId int |
set | Define uma variável de texto que substitui cada ${name} antes da execução da consulta. | -- sqlly set schema = dbo |
param: e set são os dois que mudam o que o banco de dados recebe. O SQLly substitui seus valores no SQL antes de enviá-lo, fora de strings e comentários. O valor de um parâmetro entra como um literal escapado do tipo declarado (text, int, decimal, bool, date, ou datetime). Um set o valor entra como está. Coluna calculada são lidas das duas formas, como @name.
Onde a diretiva deve ficar
- Em uma linha própria. Uma diretiva após o código SQL na mesma linha é ignorada.
nameé a única exceção e funciona como comentário final. view:e o tamanho da tela vai na primeira linha. Eles são lidos apenas na primeira linha não vazia da consulta. Em um bloco de lock no topo, a primeira linha de diretiva do bloco vale como essa primeira linha.- O espaçamento é flexível para a maioria das famílias:
--sqlly view: pivote-- SQLLY view: pivotambos funcionam. format:é rigoroso. Deve ser escrito exatamente-- sqlly format:, com um espaço depois--.- Dentro de um comentário de bloco, uma diretiva é desativada - o que é um jeito prático de desativar uma por um tempo. A única exceção é o
/* sqlly lockbloco: suas linhas funcionam exatamente como se cada uma fosse escrita em sua própria linha.
-- 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 namespace, mas está grafado errado, está em um lugar onde não pode se aplicar ou recebeu um valor desconhecido, o SQLly o sublinha no editor e diz o porquê, em vez de ignorá-lo em silêncio. Por exemplo, -- sqlly view: table recebe Visualização desconhecida — era esperado -- sqlly view: grid, -- sqlly view: pivot, -- sqlly view: chart, ou -- 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 | O 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 ou 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+Espaço, on macOS too.
Ajuda no aplicativo
- Passar o mouse qualquer
-- sqllycomentário para uma descrição curta, com um link para a lista completa de opções. - Ajuda › Diretivas de formatação… (também na paleta de comandos) abre uma janela de referência com cada família, seus parâmetros e exemplos prontos para copiar.
- Deixe o SQLly escrever. Clique no cadeado na frente do nome de um resultado para escrever todo o resultado como diretivas, ou clique com o botão direito no cabeçalho de uma coluna de resultado e escolha Formatar › Definir substituição de formatação… para que uma
format:seja escrita para você.
Nesta seção
- Grade
- Escreva a ordem das colunas, colunas ocultas e congeladas, ordenação, agrupamento e filtros na consulta.
- Formatação em andamento
- Dê a cada coluna a apresentação e a largura que merece, automaticamente sempre que a consulta for executada.
- Condicional
- Colorir as células pelos valores delas em uma consulta: regras de destaque, escalas de cores e barras de dados.
- Colunas calculadas
- Adicione colunas escritas como fórmulas do Excel: totais acumulados, margens, alterações em relação à linha anterior e datas.
- Pivô
- Transforme um conjunto de resultados familiar em uma tabela cruzada com um comentário curto e portátil.
- Gráfico
- Diga à aba Gráfico qual história desenhar antes mesmo do resultado chegar.
- Bloquear grade
- Um clique escreve o resultado exatamente como ele está agora na consulta, para que ele volte da mesma forma em cada execução.