在 Elasticsearch SQL 查詢中，format 參數決定了返回數據的結構和可讀性，主要分為人類可讀格式和機器友好格式兩大類。選擇哪種格式取決於你是在命令行查看結果，還是需要程序進一步處理數據。

下面的表格詳細對比了常見的幾種格式：

格式 (format=)

主要特點

數據結構

適用場景

txt

默認的友好格式，以文本表格形式展示，便於在命令行直接閲讀。

純文本表格，包含表頭和分割線。

在 Kibana Dev Tools、終端中快速查看和驗證查詢結果。

csv

逗號分隔值，是一種通用的結構化數據交換格式。

每行一條記錄，字段間用逗號分隔。

將查詢結果導出到 Excel、Numbers 等電子表格軟件進行後續分析。

tsv

製表符分隔值，與 CSV 類似，但使用製表符（\t）作為分隔符。

每行一條記錄，字段間用製表符分隔。

需要避免字段內容本身包含逗號而引發解析錯誤時的通用數據交換。

json

最常用且功能完整的格式，返回結構化的 JSON 對象，便於程序解析，並且是支持分頁遊標（cursor）的必要格式。

完整的 JSON 對象，包含 columns（列信息）和 rows（數據行）等鍵。

應用程序調用接口、需要程序化處理數據、以及進行大數據量分頁查詢時。

yaml

另一種對人類友好的數據序列化格式，可讀性高。

層次化的 YAML 格式文本。

適合在需要良好可讀性的配置或文檔中展示數據結構。

💡 重要區別：分頁遊標 (Cursor)

當進行大數據量分頁查詢（使用 fetch_size 參數）時，json 格式和其他格式有關鍵區別：

  • format=json：響應體中會直接包含一個 cursor 字段。你可以用這個遊標獲取下一批數據，直到取完。
  • format=txt/csv/tsv/yaml：響應體中沒有遊標，遊標信息會放在 HTTP 響應頭裏（Cursor 頭）。這對程序處理來説不如 JSON 格式方便。

🛠️ 如何選擇格式

你可以根據使用場景來快速決定：

  • 日常調試、查看數據：直接用 format=txt，清晰明瞭。
  • 寫代碼調用 ES 接口：務必使用 format=json，便於解析，並且是支持遊標分頁的標準做法。
  • 導出數據到表格：選擇 format=csv 或 format=tsv。
  • 想看看 SQL 被翻譯成了什麼原生查詢：使用 /_sql/translate API，它會把你的 SQL 語句轉換成底層的 Elasticsearch DSL 查詢語句。

💎 總結與建議

簡單來説，txt 給人看最方便，json 對程序最友好、功能最全（尤其是分頁）。在開發和調試時，你可以先用 txt 確認查詢正確，再在代碼中切換到 json 格式。

如果你能告訴我你主要的使用場景（例如是在寫程序還是在手動查詢），我可以給你更具體的示例。