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

你很少需要自己輸入它們。把結果排成你喜歡的樣子,然後點擊 lock 位於結果名稱前面: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 lockSQLly 在你按一下結果上的鎖定圖示時寫入的區塊註解。其 -- 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:結果送達時,目前顯示的是哪個結果集:分頁模式會選取其分頁,堆疊模式會把它的卡片捲動到可見處。從 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: 以及畫布大小要放在第一行。 這些指令只會在查詢的第一個非空白行被讀取。若查詢開頭有鎖定區塊,則以該區塊的第一行指令作為那一行。
  • 間距很寬鬆 對大多數系列而言: --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 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.
-- 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 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+空格, on macOS too.

應用程式內的說明

  • 懸停 任何 -- sqlly 註解來加上簡短說明,並附有完整選項清單的連結。
  • 說明 › 格式化指令… (命令面板裡也有)會開啟一個參考視窗,列出每個家族、其參數,以及可直接複製的範例。
  • 讓 SQLly 為你撰寫。 點擊結果名稱前的鎖頭圖示,可將整個結果寫成指示詞;或在結果欄標題上按右鍵並選擇 格式 › 設定格式覆寫… ,就會幫你寫好一個 format: 為你寫好的指令。

在本節中

網格
把欄位順序、隱藏與凍結的欄位、排序、分組和篩選都寫進查詢。
格式化 進行中
每當查詢執行時,自動為每個欄位安排它該有的呈現方式與寬度。
條件
針對單一查詢,依值為儲存格上色:醒目提示規則、色階與資料橫條。
計算欄位
新增以 Excel 公式撰寫的欄位:累計總和、利潤率、相對前一列的變化,以及日期。
樞紐分析
只靠一句簡短、可攜的註解,就能把熟悉的結果集變成樞紐分析表。
圖表
在結果到達之前,告訴圖表分頁該繪製什麼故事。
鎖定網格
一鍵即可將結果完全按照目前顯示的樣子寫入查詢,因此每次執行都會得到相同結果。