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 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: | 結果送達時,目前顯示的是哪個結果集:分頁模式會選取其分頁,堆疊模式會把它的卡片捲動到可見處。從 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 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:為你寫好的指令。