Back to Details

sqldw-consumption-cli

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese
Update Check — ONCE PER SESSION (mandatory) The first time this skill is used in a session, run the check-updates skill before proceeding.
  • GitHub Copilot CLI / VS Code: invoke the 
    check-updates
    skill.
  • Claude Code / Cowork / Cursor / Windsurf / Codex: compare local vs remote package.json version.
  • Skip if the check was already performed earlier in this session.
CRITICAL NOTES
  1. To find the workspace details (including its ID) from workspace name: list all workspaces and, then, use JMESPath filtering
  2. To find the item details (including its ID) from workspace ID, item type, and item name: list all items of that type in that workspace and, then, use JMESPath filtering
会话内仅需检查一次更新（必填） 在会话中首次使用此技能前，请先运行check-updates技能。
  • GitHub Copilot CLI / VS Code：调用
    check-updates
    技能。
  • Claude Code / Cowork / Cursor / Windsurf / Codex：对比本地与远程package.json版本。
  • 若本次会话中已执行过检查，可跳过此步骤。
重要说明
  1. 若要通过工作区名称获取工作区详情（包括ID）：列出所有工作区，然后使用JMESPath筛选
  2. 若要通过工作区ID、项目类型和项目名称获取项目详情（包括ID）：列出该工作区内对应类型的所有项目，然后使用JMESPath筛选

SQL Endpoint Consumption — CLI Skill

SQL Endpoint 调用 — CLI技能

Table of Contents

目录

TaskReferenceNotes
Finding Workspaces and Items in FabricCOMMON-CLI.md § Finding Workspaces and Items in FabricMandatory — READ link first [needed for finding workspace id by its name or item id by its name, item type, and workspace id]
Fabric Topology & Key ConceptsCOMMON-CORE.md § Fabric Topology & Key Concepts
Environment URLsCOMMON-CORE.md § Environment URLs
Authentication & Token AcquisitionCOMMON-CORE.md § Authentication & Token AcquisitionWrong audience = 401; read before any auth issue
Core Control-Plane REST APIsCOMMON-CORE.md § Core Control-Plane REST APIsIncludes pagination, LRO polling, and rate-limiting patterns
OneLake Data AccessCOMMON-CORE.md § OneLake Data AccessRequires 
storage.azure.com
token, not Fabric token
Job ExecutionCOMMON-CORE.md § Job Execution
Capacity ManagementCOMMON-CORE.md § Capacity Management
Gotchas, Best Practices & TroubleshootingCOMMON-CORE.md § Gotchas, Best Practices & Troubleshooting
Tool Selection RationaleCOMMON-CLI.md § Tool Selection Rationale
Authentication RecipesCOMMON-CLI.md § Authentication Recipes
az login
flows and token acquisition
Fabric Control-Plane API via 
az rest
COMMON-CLI.md § Fabric Control-Plane API via az restAlways pass 
--resource
; includes pagination and LRO helpers
OneLake Data Access via 
curl
COMMON-CLI.md § OneLake Data Access via curlUse 
curl
not 
az rest
(different token audience)
SQL / TDS Data-Plane AccessCOMMON-CLI.md § SQL / TDS Data-Plane Access
sqlcmd
(Go) connect, query, CSV export
Job Execution (CLI)COMMON-CLI.md § Job Execution
OneLake ShortcutsCOMMON-CLI.md § OneLake Shortcuts
Capacity Management (CLI)COMMON-CLI.md § Capacity Management
Composite RecipesCOMMON-CLI.md § Composite Recipes
Gotchas & Troubleshooting (CLI-Specific)COMMON-CLI.md § Gotchas & Troubleshooting (CLI-Specific)
az rest
audience, shell escaping, token expiry
Quick ReferenceCOMMON-CLI.md § Quick Reference
az rest
template + token audience/tool matrix
Item-Type Capability MatrixSQLDW-CONSUMPTION-CORE.md § Item-Type Capability MatrixRead first — shows what's read-only (SQLEP) vs read-write (DW)
Connection FundamentalsSQLDW-CONSUMPTION-CORE.md § Connection FundamentalsTDS, port 1433, Entra-only, no MARS
Supported T-SQL Surface Area (Consumption Focus)SQLDW-CONSUMPTION-CORE.md § Supported T-SQL Surface AreaRead before writing T-SQL — includes data types (no 
nvarchar
/
datetime
/
money
)
Read-Side Objects You Can CreateSQLDW-CONSUMPTION-CORE.md § Read-Side Objects You Can CreateViews, TVFs, scalar UDFs, procedures
Temporary TablesSQLDW-CONSUMPTION-CORE.md § Temporary TablesUse 
DISTRIBUTION = ROUND_ROBIN
for INSERT INTO SELECT support
Cross-Database QueriesSQLDW-CONSUMPTION-CORE.md § Cross-Database Queries3-part naming, same workspace
Security for ConsumptionSQLDW-CONSUMPTION-CORE.md § Security for ConsumptionGRANT/DENY, RLS, CLS, DDM
Monitoring and DiagnosticsSQLDW-CONSUMPTION-CORE.md § Monitoring and DiagnosticsIncludes query labels; DMVs (live) + 
queryinsights.*
(30-day history)
Performance: Best Practices and TroubleshootingSQLDW-CONSUMPTION-CORE.md § Performance: Best Practices and TroubleshootingStatistics, caching, clustering, query tips
REST API: Refresh SQL Endpoint MetadataSQLDW-CONSUMPTION-CORE.md § REST API: Refresh SQL Endpoint MetadataForce metadata sync when SQLEP data is stale after ETL
System Catalog Queries (Metadata Exploration)SQLDW-CONSUMPTION-CORE.md § System Catalog Queries
sys.tables
, 
sys.columns
, 
sys.views
, 
sys.stats
Common Consumption Patterns (End-to-End Examples)SQLDW-CONSUMPTION-CORE.md § Common Consumption PatternsReporting views, cross-DB analytics, temp table staging
Gotchas and Troubleshooting ReferenceSQLDW-CONSUMPTION-CORE.md § Gotchas and Troubleshooting Reference18 numbered issues with cause + resolution
Quick Reference: Consumption Capabilities by ScenarioSQLDW-CONSUMPTION-CORE.md § Quick Reference: Consumption CapabilitiesScenario → approach lookup
Schema and Object Discoverydiscovery-queries.md § Schema and Object DiscoveryTables, columns, views, functions, procedures, cross-DB
Security Discoverydiscovery-queries.md § Security Discovery
Statistics and Performance Metadatadiscovery-queries.md § Statistics and Performance Metadata
Bash — Data Exportscript-templates.md § Bash — Data ExportQuery to CSV + parameterized date range export
Bash — Schema Discovery Reportscript-templates.md § Bash — Schema Discovery Report
Bash — Performance Investigationscript-templates.md § Bash — Performance Investigation
PowerShell Templatesscript-templates.md § PowerShell TemplatesQuery to CSV + schema discovery
Tool StackSKILL.md § Tool Stack
ConnectionSKILL.md § Connection
Agentic Exploration ("Chat With My Data")SKILL.md § Agentic ExplorationStart here for data exploration
Script Generationconsumption-cli-quickref.md § Script GenerationFormatting flags, piped input, parameterized queries
Monitoring and Performanceconsumption-cli-quickref.md § Monitoring and PerformanceActive queries DMV, KILL syntax
Gotchas, Rules, TroubleshootingSKILL.md § Gotchas, Rules, TroubleshootingMUST DO / AVOID / PREFER checklists
Agent Integration Notesconsumption-cli-quickref.md § Agent Integration NotesPer-agent CLI tips
任务参考文档说明
在Fabric中查找工作区和项目COMMON-CLI.md § 在Fabric中查找工作区和项目必填 — 请先阅读链接内容 [需通过名称获取工作区ID，或通过名称、类型、工作区ID获取项目ID]
Fabric拓扑与核心概念COMMON-CORE.md § Fabric拓扑与核心概念
环境URLCOMMON-CORE.md § 环境URL
认证与令牌获取COMMON-CORE.md § 认证与令牌获取受众错误会导致401；遇到认证问题前请先阅读
核心控制平面REST APICOMMON-CORE.md § 核心控制平面REST API包含分页、LRO轮询和速率限制模式
OneLake数据访问COMMON-CORE.md § OneLake数据访问需要
storage.azure.com
令牌，而非Fabric令牌
作业执行COMMON-CORE.md § 作业执行
容量管理COMMON-CORE.md § 容量管理
常见问题、最佳实践与故障排查COMMON-CORE.md § 常见问题、最佳实践与故障排查
工具选择依据COMMON-CLI.md § 工具选择依据
认证方案COMMON-CLI.md § 认证方案
az login
流程与令牌获取
通过
az rest
调用Fabric控制平面API		COMMON-CLI.md § 通过az rest调用Fabric控制平面API务必传递
--resource
参数；包含分页和LRO辅助工具
通过
curl
访问OneLake数据		COMMON-CLI.md § 通过curl访问OneLake数据使用
curl
而非
az rest
（令牌受众不同）
SQL / TDS数据平面访问COMMON-CLI.md § SQL / TDS数据平面访问
sqlcmd
（Go版本）连接、查询、CSV导出
作业执行（CLI）COMMON-CLI.md § 作业执行
OneLake快捷方式COMMON-CLI.md § OneLake快捷方式
容量管理（CLI）COMMON-CLI.md § 容量管理
复合方案COMMON-CLI.md § 复合方案
CLI专属常见问题与故障排查COMMON-CLI.md § CLI专属常见问题与故障排查
az rest
受众、shell转义、令牌过期
快速参考COMMON-CLI.md § 快速参考
az rest
模板 + 令牌受众/工具矩阵
项目类型能力矩阵SQLDW-CONSUMPTION-CORE.md § 项目类型能力矩阵请先阅读 — 展示只读（SQLEP）与读写（DW）的区别
连接基础SQLDW-CONSUMPTION-CORE.md § 连接基础TDS、端口1433、仅支持Entra、不支持MARS
支持的T-SQL范围（调用场景）SQLDW-CONSUMPTION-CORE.md § 支持的T-SQL范围编写T-SQL前请先阅读 — 包含数据类型限制（不支持
nvarchar
/
datetime
/
money
）
可创建的只读对象SQLDW-CONSUMPTION-CORE.md § 可创建的只读对象视图、TVF、标量UDF、存储过程
临时表SQLDW-CONSUMPTION-CORE.md § 临时表插入查询时使用
DISTRIBUTION = ROUND_ROBIN
跨数据库查询SQLDW-CONSUMPTION-CORE.md § 跨数据库查询三段式命名、同一工作区
调用场景安全设置SQLDW-CONSUMPTION-CORE.md § 调用场景安全设置GRANT/DENY、RLS、CLS、DDM
监控与诊断SQLDW-CONSUMPTION-CORE.md § 监控与诊断包含查询标签；DMV（实时）+ 
queryinsights.*
（30天历史）
性能：最佳实践与故障排查SQLDW-CONSUMPTION-CORE.md § 性能：最佳实践与故障排查统计信息、缓存、聚类、查询技巧
REST API：刷新SQL Endpoint元数据SQLDW-CONSUMPTION-CORE.md § REST API：刷新SQL Endpoint元数据ETL后SQLEP数据过时，强制同步元数据
系统目录查询（元数据探索）SQLDW-CONSUMPTION-CORE.md § 系统目录查询
sys.tables
、
sys.columns
、
sys.views
、
sys.stats
常见调用模式（端到端示例）SQLDW-CONSUMPTION-CORE.md § 常见调用模式报表视图、跨库分析、临时表 staging
常见问题与故障排查参考SQLDW-CONSUMPTION-CORE.md § 常见问题与故障排查参考18个带原因和解决方案的编号问题
快速参考：按场景划分的调用能力SQLDW-CONSUMPTION-CORE.md § 快速参考：按场景划分的调用能力场景→方法对照表
架构与对象发现discovery-queries.md § 架构与对象发现表、列、视图、函数、存储过程、跨库对象
安全设置发现discovery-queries.md § 安全设置发现
统计信息与性能元数据discovery-queries.md § 统计信息与性能元数据
Bash — 数据导出script-templates.md § Bash — 数据导出查询结果转CSV + 带参数的日期范围导出
Bash — 架构发现报告script-templates.md § Bash — 架构发现报告
Bash — 性能排查script-templates.md § Bash — 性能排查
PowerShell模板script-templates.md § PowerShell模板查询结果转CSV + 架构发现
工具栈SKILL.md § 工具栈
连接SKILL.md § 连接
Agent式探索（"与我的数据对话"）SKILL.md § Agent式探索数据探索从此处开始
脚本生成consumption-cli-quickref.md § 脚本生成格式化标记、管道输入、参数化查询
监控与性能consumption-cli-quickref.md § 监控与性能活跃查询DMV、KILL语法
常见问题、规则与故障排查SKILL.md § 常见问题、规则与故障排查必须做/避免/推荐检查清单
Agent集成说明consumption-cli-quickref.md § Agent集成说明各Agent专属CLI技巧

Tool Stack

工具栈

ToolRoleInstall
sqlcmd
(Go)		Primary: Execute T-SQL. Standalone binary, no ODBC driver, built-in Entra ID auth via 
DefaultAzureCredential
.
winget install sqlcmd
/ 
brew install sqlcmd
/ 
apt-get install sqlcmd
az
CLI		Auth (
az login
), token acquisition, Fabric REST for endpoint discovery.		Pre-installed in most dev environments
jq
Parse JSON from 
az rest
Pre-installed or trivial
Agent check — verify before first SQL operation:
bash
sqlcmd --version 2>/dev/null || echo "INSTALL: winget install sqlcmd OR brew install sqlcmd"
工具作用安装方式
sqlcmd
（Go版本）		核心工具：执行T-SQL。独立二进制文件，无需ODBC驱动，通过
DefaultAzureCredential
内置Entra ID认证。
winget install sqlcmd
/ 
brew install sqlcmd
/ 
apt-get install sqlcmd
az
CLI		认证（
az login
）、令牌获取、通过Fabric REST发现端点。		多数开发环境已预装
jq
解析
az rest
返回的JSON		已预装或易于安装
Agent检查 — 首次执行SQL操作前请验证：
bash
sqlcmd --version 2>/dev/null || echo "INSTALL: winget install sqlcmd OR brew install sqlcmd"

Connection

连接

Discover the SQL Endpoint FQDN

发现SQL Endpoint的FQDN

Per COMMON-CLI.md Discovering Connection Parameters via REST:
bash
WS_ID="<workspaceId>"
ITEM_ID="<warehouseOrLakehouseId>"
根据COMMON-CLI.md中“通过REST发现连接参数”的说明：
bash
WS_ID="<workspaceId>"
ITEM_ID="<warehouseOrLakehouseId>"

Warehouse

数据仓库

az rest --method get
--resource "https://api.fabric.microsoft.com"
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses/$ITEM_ID"
--query "properties.connectionString" --output tsv
az rest --method get
--resource "https://api.fabric.microsoft.com"
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/warehouses/$ITEM_ID"
--query "properties.connectionString" --output tsv

Lakehouse SQL endpoint

湖仓SQL端点

az rest --method get
--resource "https://api.fabric.microsoft.com"
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/lakehouses/$ITEM_ID"
--query "properties.sqlEndpointProperties.connectionString" --output tsv

Result: `<uniqueId>.datawarehouse.fabric.microsoft.com`
az rest --method get
--resource "https://api.fabric.microsoft.com"
--url "https://api.fabric.microsoft.com/v1/workspaces/$WS_ID/lakehouses/$ITEM_ID"
--query "properties.sqlEndpointProperties.connectionString" --output tsv

结果：`<uniqueId>.datawarehouse.fabric.microsoft.com`

Connect with sqlcmd (Go)

使用sqlcmd（Go版本）连接

bash
undefined
bash
undefined

Interactive session (Entra login via browser if needed)

交互式会话（如需Entra登录，会自动打开浏览器）

sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G

Non-interactive one-shot query

非交互式单次查询

sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G
-Q "SELECT TOP 10 * FROM dbo.FactSales"
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>" -G
-Q "SELECT TOP 10 * FROM dbo.FactSales"

Explicit ActiveDirectoryDefault (uses az login session)

显式使用ActiveDirectoryDefault（依赖az login会话）

sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>"
--authentication-method ActiveDirectoryDefault
-Q "SELECT TOP 10 * FROM dbo.FactSales"
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>"
--authentication-method ActiveDirectoryDefault
-Q "SELECT TOP 10 * FROM dbo.FactSales"

Service principal (CI/CD)

服务主体（CI/CD场景）

SQLCMDPASSWORD="<clientSecret>"
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>"
--authentication-method ActiveDirectoryServicePrincipal
-U "<appId>"
-Q "SELECT COUNT(*) FROM dbo.FactSales"
undefined
SQLCMDPASSWORD="<clientSecret>"
sqlcmd -S "<endpoint>.datawarehouse.fabric.microsoft.com" -d "<DatabaseName>"
--authentication-method ActiveDirectoryServicePrincipal
-U "<appId>"
-Q "SELECT COUNT(*) FROM dbo.FactSales"
undefined

Reusable Connection Variables

可复用的连接变量

bash
undefined
bash
undefined

Set once at script top

在脚本顶部设置一次

FABRIC_SERVER="<endpoint>.datawarehouse.fabric.microsoft.com" FABRIC_DB="<DatabaseName>" SQLCMD="sqlcmd -S $FABRIC_SERVER -d $FABRIC_DB -G"
FABRIC_SERVER="<endpoint>.datawarehouse.fabric.microsoft.com" FABRIC_DB="<DatabaseName>" SQLCMD="sqlcmd -S $FABRIC_SERVER -d $FABRIC_DB -G"

Use throughout

在脚本中复用

$SQLCMD -Q "SELECT TOP 5 * FROM dbo.DimProduct" $SQLCMD -i myscript.sql
undefined
$SQLCMD -Q "SELECT TOP 5 * FROM dbo.DimProduct" $SQLCMD -i myscript.sql
undefined

PowerShell / Windows CMD

PowerShell / Windows CMD

powershell
undefined
powershell
undefined

PowerShell

PowerShell

$s = "<endpoint>.datawarehouse.fabric.microsoft.com"; $db = "<DatabaseName>" sqlcmd -S $s -d $db -G -Q "SELECT TOP 10 * FROM dbo.FactSales"
$s = "<endpoint>.datawarehouse.fabric.microsoft.com"; $db = "<DatabaseName>" sqlcmd -S $s -d $db -G -Q "SELECT TOP 10 * FROM dbo.FactSales"

CMD: use set S=... and %S% / %DB% instead of $variables

CMD：使用set S=...，并以%S% / %DB%替代$变量


---

---

Agentic Exploration ("Chat With My Data")

Agent式探索（"与我的数据对话"）

Schema Discovery Sequence

架构发现流程

Run these in order to understand what's in the endpoint. See references/discovery-queries.md for extended discovery queries.
bash
undefined
按顺序运行以下命令，了解端点中的内容。扩展发现查询请参考references/discovery-queries.md。
bash
undefined

1. List schemas

1. 列出架构

$SQLCMD -Q "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name" -W
$SQLCMD -Q "SELECT schema_name FROM information_schema.schemata ORDER BY schema_name" -W

2. List tables and views

2. 列出表和视图

$SQLCMD -Q "SELECT table_schema, table_name, table_type FROM information_schema.tables ORDER BY table_schema, table_name" -W
$SQLCMD -Q "SELECT table_schema, table_name, table_type FROM information_schema.tables ORDER BY table_schema, table_name" -W

3. Columns for a table

3. 查询表的列信息

$SQLCMD -Q "SELECT column_name, data_type, character_maximum_length, is_nullable FROM information_schema.columns WHERE table_schema='dbo' AND table_name='FactSales' ORDER BY ordinal_position" -W
$SQLCMD -Q "SELECT column_name, data_type, character_maximum_length, is_nullable FROM information_schema.columns WHERE table_schema='dbo' AND table_name='FactSales' ORDER BY ordinal_position" -W

4. Preview rows

4. 预览数据行

$SQLCMD -Q "SELECT TOP 5 * FROM dbo.FactSales" -W
$SQLCMD -Q "SELECT TOP 5 * FROM dbo.FactSales" -W

5. Row counts

5. 统计行数

$SQLCMD -Q "SELECT s.name AS [schema], t.name AS [table], SUM(p.rows) AS row_count FROM sys.tables t JOIN sys.schemas s ON t.schema_id=s.schema_id JOIN sys.partitions p ON t.object_id=p.object_id AND p.index_id IN (0,1) GROUP BY s.name, t.name ORDER BY row_count DESC" -W
$SQLCMD -Q "SELECT s.name AS [schema], t.name AS [table], SUM(p.rows) AS row_count FROM sys.tables t JOIN sys.schemas s ON t.schema_id=s.schema_id JOIN sys.partitions p ON t.object_id=p.object_id AND p.index_id IN (0,1) GROUP BY s.name, t.name ORDER BY row_count DESC" -W

6. Programmability objects (views, functions, procedures)

6. 可编程对象（视图、函数、存储过程）

$SQLCMD -Q "SELECT name, type_desc FROM sys.objects WHERE type IN ('V','FN','IF','P','TF') ORDER BY type_desc, name" -W
undefined
$SQLCMD -Q "SELECT name, type_desc FROM sys.objects WHERE type IN ('V','FN','IF','P','TF') ORDER BY type_desc, name" -W
undefined

Agentic Workflow

Agent式工作流

  1. Discover → Run Steps 1–3 to understand available tables/columns.
  2. Sample → 
    SELECT TOP 5
    on relevant tables.
  3. Formulate → Write T-SQL using SQLDW-CONSUMPTION-CORE.md Supported T-SQL Surface Area.
  4. Execute → 
    $SQLCMD -Q "..."
    .
  5. Iterate → Refine based on results.
  6. Present → Show results or generate a reusable script (Script Generation section).
  1. 发现 → 运行步骤1-3，了解可用的表/列。
  2. 采样 → 对相关表执行
    SELECT TOP 5
    。
  3. 编写 → 参考SQLDW-CONSUMPTION-CORE.md的“支持的T-SQL范围”编写T-SQL。
  4. 执行 → 运行
    $SQLCMD -Q "..."
    。
  5. 迭代 → 根据结果优化查询。
  6. 呈现 → 展示结果或生成可复用脚本（参考脚本生成章节）。

Gotchas, Rules, Troubleshooting

常见问题、规则与故障排查

For full T-SQL/platform gotchas: SQLDW-CONSUMPTION-CORE.md Gotchas and Troubleshooting Reference and COMMON-CLI.md Gotchas & Troubleshooting (CLI-Specific).
完整的T-SQL/平台常见问题请参考：SQLDW-CONSUMPTION-CORE.md的“常见问题与故障排查参考”，以及COMMON-CLI.md的“CLI专属常见问题与故障排查”。

MUST DO

必须做

  • Always 
    -d <DatabaseName>
     — FQDN alone is insufficient.
  • Always 
    -G
    or 
    --authentication-method
     — SQL auth not supported on Fabric.
  • az login
    first     — 
    ActiveDirectoryDefault
    uses az session. No session → cryptic failure.
  • SET NOCOUNT ON;
     in scripts — suppresses row-count messages that corrupt output.
  • Label queries with 
    OPTION (LABEL = 'AGENTCLI_...')
    for Query Insights tracing.
  • 始终指定
    -d <DatabaseName>
     — 仅使用FQDN是不够的。
  • 始终使用
    -G
    或
    --authentication-method
     — Fabric不支持SQL认证。
  • 先执行
    az login
     — 
    ActiveDirectoryDefault
    依赖az会话。无会话会导致模糊的错误。
  • 脚本中添加
    SET NOCOUNT ON;
     — 抑制会破坏输出的行数统计信息。
  • 为查询添加标签：使用
    OPTION (LABEL = 'AGENTCLI_...')
    ，便于Query Insights追踪。

AVOID

避免

  • ODBC sqlcmd (
    /opt/mssql-tools/bin/sqlcmd
    ) — requires ODBC driver. Use Go version.
  • Omitting 
    -W
     in scripts — trailing spaces corrupt CSV.
  • DML on SQLEP — Lakehouse/Mirrored DB endpoints are read-only. DML only on Warehouse.
  • MARS — not supported. Remove 
    MultipleActiveResultSets
    from connection strings.
  • Hardcoded FQDNs — discover via REST API (Discover the SQL Endpoint FQDN).
  • ODBC版sqlcmd（
    /opt/mssql-tools/bin/sqlcmd
    ） — 需要ODBC驱动，请使用Go版本。
  • 脚本中省略
    -W
     — 尾随空格会破坏CSV。
  • 在SQLEP上执行DML — 湖仓/镜像数据库端点是只读的。仅可在数据仓库上执行DML。
  • 使用MARS — 不支持此功能。从连接字符串中移除
    MultipleActiveResultSets
    。
  • 硬编码FQDN — 通过REST API发现（参考“发现SQL Endpoint的FQDN”章节）。

PREFER

推荐

  • sqlcmd (Go) -G
     over curl+token for SQL queries.
  • -Q
     (non-interactive exit) for agentic use.
  • Piped input for multi-statement batches or queries with quotes.
  • -i file.sql
     for complex queries — avoids shell escaping.
  • -F vertical
     for exploration of wide tables.
  • Env vars (
    FABRIC_SERVER
    , 
    FABRIC_DB
    ) for script reuse.
  • az rest
     for Fabric REST API — use sqlcmd only for T-SQL.
  • 使用
    sqlcmd (Go) -G
     而非curl+令牌执行SQL查询。
  • Agent场景使用
    -Q
    （非交互式执行后退出）。
  • 多语句批处理或含引号的查询使用管道输入。
  • 复杂查询使用
    -i file.sql
     — 避免shell转义问题。
  • 宽表探索使用
    -F vertical
    。
  • 使用环境变量（
    FABRIC_SERVER
    , 
    FABRIC_DB
    ）实现脚本复用。
  • Fabric REST API使用
    az rest
     — 仅在执行T-SQL时使用sqlcmd。

TROUBLESHOOTING

故障排查

SymptomCauseFix
Login failed for user '<token-identified principal>'
Wrong DB name or no accessVerify 
-d
matches item name exactly (case-sensitive)
Cannot open server
Wrong FQDN or networkRe-discover via REST API; check port 1433
Login timeout expired
Port 1433 blocked
nc -zv <endpoint> 1433
; check firewall/VPN
ActiveDirectoryDefault
failure
az login
expired or wrong tenant
az login --tenant <tenantId>
Garbled CSV outputMissing 
-W
or wrong 
-s
Add 
-W -s"," -w 4000
(N rows affected)
in file		No 
SET NOCOUNT ON
Prepend 
SET NOCOUNT ON;
Invalid object name 'queryinsights...'
New warehouse < 2 min oldWait ~2 minutes
No rows but data existsRLS filteringCheck 
USER_NAME()
, verify RLS policies
sqlcmd
not found		Go version not installed
winget install sqlcmd
/ 
brew install sqlcmd
症状原因修复方案
Login failed for user '<token-identified principal>'
数据库名称错误或无访问权限验证
-d
指定的名称与项目名称完全匹配（区分大小写）
Cannot open server
FQDN错误或网络问题通过REST API重新发现；检查端口1433
Login timeout expired
端口1433被阻塞执行
nc -zv <endpoint> 1433
；检查防火墙/VPN
ActiveDirectoryDefault
失败
az login
会话过期或租户错误		执行
az login --tenant <tenantId>
CSV输出乱码缺少
-W
或
-s
参数错误		添加
-W -s"," -w 4000
文件中出现
(N rows affected)
未添加
SET NOCOUNT ON
在脚本开头添加
SET NOCOUNT ON;
Invalid object name 'queryinsights...'
新建数据仓库不足2分钟等待约2分钟
数据存在但查询无结果RLS过滤检查
USER_NAME()
，验证RLS策略
sqlcmd
未找到		未安装Go版本执行
winget install sqlcmd
/ 
brew install sqlcmd