Diretivas do SQLly

funcional

Pequenos 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

DiretivaO que fazExemplo
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 lockUm 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 — … … */
nameRotula 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
setDefine 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: pivot e -- SQLLY view: pivot ambos 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 lock bloco: 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;
Uma rede de segurança enquanto você digita. Se um comentário usar o 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 typedThe list offers
-- on a line of its ownA 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.
-- sqO 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 a param: 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 -- sqlly comentá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.