创建和更改 Azure SQL 外部表

2025-07-18

适用于：✅Azure 数据资源管理器

Creates or alters an Azure SQL external table in the database in which the command is executed.

Note

如果该表存在，则 .create 命令会失败并显示错误。使用 .create-or-alter 或 .alter 修改现有表。
不支持更改外部 Azure SQL 表的架构。

支持的 Azure SQL 外部表类型

SQL Server
MySQL
PostgreSQL
Cosmos DB

Permissions

To .create requires at least Database User permissions and to .alter requires at least Table Admin permissions.

To .create, .alter, or .create-or-alter an external table using managed identity authentication requires Database Admin permissions. SQL Server 和 Cosmos DB 外部表支持此方法。

Syntax

(.create | .alter | .create-or-alter) externaltableTableName(Schema)kind=sql [ table=SqlTableName ] (SqlConnectionString) [with( [ sqlDialect=SqlDialect ] , [ Property, ... ])]

Learn more about syntax conventions.

Parameters

Name	类型	Required	Description
TableName	`string`	✔️	外部表的名称。 The name must follow the rules for entity names, and an external table can't have the same name as a regular table in the same database.
Schema	`string`	✔️	The external data schema is a comma-separated list of one or more column names and data types, where each item follows the format: ColumnName`:`ColumnType.
SqlConnectionString	`string`	✔️	SQL Server 的连接字符串。
SqlTableName	`string`		不包括数据库名称的 SQL 表的名称。如果表的名称包含句点（“.”），则使用 ['Name.of.the.table'] 表示法。如果表不在默认 SQL 数据库架构中，请使用 ['SchemaName.TableName'] 表示法。例如，对于架构“S1”中的表“T1”：['S1。T1'] 除 Cosmos DB 以外的所有类型的表都需要此规范，因为对于 Cosmos DB，集合名称是连接字符串的一部分。
SqlDialect	`string`		指示 Azure SQL 外部表的类型。 SQL Server 是默认值。对于 MySQL，请指定 `MySQL`。对于 PostgreSQL，请指定 `PostgreSQL`。对于 Cosmos DB，请指定 `CosmosDbSql`。
Property	`string`		A key-value property pair in the format PropertyName`=`PropertyValue. See optional properties.

Warning

应该对包含机密信息的连接字符串和查询进行模糊处理，使其在任何 Kusto 跟踪中都被忽略。有关详细信息，请参阅经过模糊处理的字符串文本。

Optional properties

Property	类型	Description
`folder`	`string`	表的文件夹。
`docString`	`string`	一个用来记录表的字符串。
`firetriggers`	`true`/`false`	如果为 `true`，则指示目标系统激发 SQL 表上定义的 INSERT 触发器。默认为 `false`。 (For more information, see BULK INSERT and System.Data.SqlClient.SqlBulkCopy)
`createifnotexists`	`true`/ `false`	如果为 `true`，则会在目标 SQL 表不存在的情况下创建该表；在这种情况下，必须提供 `primarykey` 属性来指示作为主键的结果列。默认为 `false`。
`primarykey`	`string`	如果 `createifnotexists` 为 `true`，则生成的列名称将用作 SQL 表的主键（如果是此命令创建的）。

身份验证和授权

To interact with an external Azure SQL table, you must specify authentication means as part of the SqlConnectionString. The SqlConnectionString defines the resource to access and its authentication information.

有关详细信息，请参阅 Azure SQL 外部表身份验证方法。

Note

If the external table is used for continuous export, authentication must be performed either by username/password or managed identities.

Examples

以下示例演示如何创建每种类型的 Azure SQL 外部表。

SQL Server

.create external table MySqlExternalTable (x:long, s:string) 
kind=sql
table=MySqlTable
( 
   h@'Server=tcp:myserver.database.chinacloudapi.cn,1433;Authentication=Active Directory Integrated;Initial Catalog=mydatabase;'
)
with 
(
   docstring = "Docs",
   folder = "ExternalTables", 
   createifnotexists = true,
   primarykey = x,
   firetriggers=true
)

Output

TableName	TableType	Folder	DocString	属性
MySqlExternalTable	Sql	ExternalTables	Docs	{ "TargetEntityKind": "sqltable`", "TargetEntityName": "MySqlTable", "TargetEntityConnectionString":"Server=tcp:myserver.database.chinacloudapi.cn,1433;Authentication=Active Directory Integrated;Initial Catalog=mydatabase;", "FireTriggers": true, "CreateIfNotExists": true, "PrimaryKey": "x" }

MySQL

.create external table MySqlExternalTable (x:long, s:string) 
kind=sql
table=MySqlTable
( 
   h@'Server=myserver.mysql.database.chinacloudapi.cn;Port = 3306;UID = USERNAME;Pwd = PASSWORD;Database = mydatabase;'
)
with 
(
   sqlDialect = "MySql",
   docstring = "Docs",
   folder = "ExternalTables", 
)

PostgreSQL

.create external table PostgreSqlExternalTable (x:long, s:string) 
kind=sql
table=PostgreSqlTable
( 
   h@'Host = hostname.postgres.database.chinacloudapi.cn; Port = 5432; Database= db; User Id=user; Password=pass; Timeout = 30;'
)
with 
(
   sqlDialect = "PostgreSQL",
   docstring = "Docs",
   folder = "ExternalTables", 
)

Cosmos DB

.create external table CosmosDBSQLExternalTable (x:long, s:string) 
kind=sql
( 
   h@'AccountEndpoint=https://cosmosdbacc.documents.azure.cn/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
)
with 
(
   sqlDialect = "CosmosDbSQL",
   docstring = "Docs",
   folder = "ExternalTables", 
)

通过