Skip to content

Commit 6711085

Browse files
BohuTANGBohuTANG
authored
docs: refresh connection parameter guides (#2937)
* docs: refresh connection parameter guides * fix: correct aws doc link punctuation
1 parent 00d7f5a commit 6711085

File tree

4 files changed

+388
-190
lines changed

4 files changed

+388
-190
lines changed

‎docs/cn/sql-reference/00-sql-reference/51-connect-parameters.md‎

Lines changed: 127 additions & 98 deletions
Original file line numberDiff line numberDiff line change
@@ -2,188 +2,217 @@
22
title: 连接参数
33
---
44
import FunctionDescription from '@site/src/components/FunctionDescription';
5+
import Tabs from '@theme/Tabs';
6+
import TabItem from '@theme/TabItem';
57

68
<FunctionDescription description="Introduced or updated: v1.2.294"/>
79

8-
连接参数是用于建立与外部存储服务（如 Amazon S3）安全连接的键值对。这些参数对于创建 Stage、将数据复制到 Databend 以及查询外部文件等任务至关重要。
9-
10-
有关每个存储服务的具体连接详细信息，请参见下表。
10+
运行 `CREATE CONNECTION` 时需要给出一组键值对作为连接参数，用来定义可复用的外部连接。创建好连接后，可以在 Stage、COPY 等语句中通过 `CONNECTION = (CONNECTION_NAME = '<connection-name>')` 直接引用。完整语法请参见 [CREATE CONNECTION](../10-sql-commands/00-ddl/13-connection/create-connection.md)。
1111

12-
import Tabs from '@theme/Tabs';
13-
import TabItem from '@theme/TabItem';
12+
不同存储服务的连接参数见下表。
1413

1514
<Tabs groupId="operating-systems">
1615
<TabItem value="Amazon S3" label="Amazon S3">
1716

18-
下表列出了用于访问类似 Amazon S3 的存储服务的连接参数：
17+
下表列出了访问 Amazon S3 及其兼容存储服务所需的连接参数：
1918

2019
| Parameter | Required? | Description |
2120
|--------------------------- |----------- |-------------------------------------------------------------- |
22-
| endpoint_url | Yes | 类似 Amazon S3 的存储服务的 Endpoint URL。 |
23-
| access_key_id | Yes | 用于标识请求者的 Access Key ID。 |
24-
| secret_access_key | Yes | 用于身份验证的 Secret Access Key。 |
25-
| enable_virtual_host_style | No | 是否使用虚拟主机样式的 URL。默认为 *false*。 |
26-
| master_key | No | 用于高级数据加密的可选 Master Key。 |
27-
| region | No | Bucket 所在的 AWS 区域。 |
28-
| security_token | No | 用于临时凭证的安全令牌。 |
21+
| endpoint_url | Yes | Amazon S3 兼容存储的 Endpoint URL。 |
22+
| access_key_id | Yes | 请求方的 Access Key ID。 |
23+
| secret_access_key | Yes | 用于认证的 Secret Access Key。 |
24+
| enable_virtual_host_style | No | 是否使用虚拟主机样式 URL，默认 *false*。 |
25+
| master_key | No | 用于高级加密的 Master Key。 |
26+
| region | No | Bucket 所在的 AWS 区域。 |
27+
| security_token | No | 临时凭证的安全令牌。 |
2928

3029
:::note
31-
- 如果命令中未指定 **endpoint_url** 参数，则 Databend 默认在 Amazon S3 上创建 Stage。因此，当您在 S3 兼容的对象存储或其他对象存储解决方案上创建外部 Stage 时，请务必包含 **endpoint_url** 参数。
30+
- 如果命令里没有 **endpoint_url**，Databend 会默认把 Stage 建在 Amazon S3。因此在 S3 兼容对象存储或其他对象存储上建外部 Stage 时，记得显式填写 **endpoint_url**。
3231

33-
- **region** 参数不是必需的，因为 Databend 可以自动检测区域信息。通常不需要手动为此参数指定值。如果自动检测失败，Databend 将默认使用 'us-east-1' 作为区域。当使用 MinIO 部署 Databend 且未配置区域信息时，它将自动默认使用 'us-east-1'，并且可以正常工作。但是，如果您收到诸如 "region is missing" 或 "The bucket you are trying to access requires a specific endpoint. Please direct all future requests to this particular endpoint" 之类的错误消息，则需要确定您的区域名称并将其显式分配给 **region** 参数。
32+
- **region** 通常不需手动填写，Databend 会自动识别区域信息；若识别失败，则回落到 `us-east-1`。例如在 MinIO 未配置区域时仍能正常工作。如果看到 “region is missing” 或 “The bucket you are trying to access requires a specific endpoint...” 之类的错误提示，请确认实际区域并为 **region** 指定正确值。
3433
:::
3534

36-
```sql title='Examples'
35+
```sql title='示例'
36+
-- 创建可复用的 Amazon S3 连接
37+
CREATE CONNECTION my_s3_conn
38+
STORAGE_TYPE = 's3'
39+
ACCESS_KEY_ID = '<your-ak>'
40+
SECRET_ACCESS_KEY = '<your-sk>';
41+
42+
-- 创建 Stage 时引用连接
3743
CREATE STAGE my_s3_stage
38-
's3://my-bucket'
39-
CONNECTION = (
40-
ACCESS_KEY_ID = '<your-ak>',
41-
SECRET_ACCESS_KEY = '<your-sk>'
42-
);
44+
URL = 's3://my-bucket'
45+
CONNECTION = (CONNECTION_NAME = 'my_s3_conn');
4346

47+
-- 为 MinIO 等 S3 兼容服务创建连接
48+
CREATE CONNECTION my_minio_conn
49+
STORAGE_TYPE = 's3'
50+
ENDPOINT_URL = 'http://localhost:9000'
51+
ACCESS_KEY_ID = 'ROOTUSER'
52+
SECRET_ACCESS_KEY = 'CHANGEME123';
53+
4454
CREATE STAGE my_minio_stage
45-
's3://databend'
46-
CONNECTION = (
47-
ENDPOINT_URL = 'http://localhost:9000',
48-
ACCESS_KEY_ID = 'ROOTUSER',
49-
SECRET_ACCESS_KEY = 'CHANGEME123'
50-
);
55+
URL = 's3://databend'
56+
CONNECTION = (CONNECTION_NAME = 'my_minio_conn');
5157
```
5258

59+
也可以改用 AWS IAM Role 和 External ID 认证，以更细粒度地控制可访问的 S3 Bucket，同时增加额外的安全校验。更多背景请参考 [AWS 文档](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html)。
5360

54-
要访问您的 Amazon S3 Bucket，您还可以指定 AWS IAM 角色和外部 ID 进行身份验证。通过指定 AWS IAM 角色和外部 ID，您可以更精细地控制用户可以访问哪些 S3 Bucket。这意味着，如果 IAM 角色已被授予仅访问特定 S3 Bucket 的权限，则用户将只能访问这些 Bucket。外部 ID 可以通过提供额外的验证层来进一步增强安全性。有关更多信息，请参见 https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-role.html
55-
56-
下表列出了使用 AWS IAM 角色身份验证访问 Amazon S3 存储服务的连接参数：
61+
下表列出了使用 AWS IAM 角色访问 Amazon S3 的连接参数：
5762

5863
| Parameter | Required? | Description |
5964
|-------------- |----------- |------------------------------------------------------- |
6065
| endpoint_url | No | Amazon S3 的 Endpoint URL。 |
61-
| role_arn | Yes | 用于授权访问 S3 的 AWS IAM 角色的 ARN。 |
62-
| external_id | No | 用于增强角色承担安全性的外部 ID。 |
63-
64-
```sql title='Examples'
65-
CREATE STAGE my_s3_stage
66-
's3://my-bucket'
67-
CONNECTION = (
68-
ROLE_ARN = 'arn:aws:iam::123456789012:role/my-role',
69-
EXTERNAL_ID = 'my-external-id'
70-
);
66+
| role_arn | Yes | 用于授权访问 S3 的 AWS IAM 角色 ARN。 |
67+
| external_id | No | 用于增强角色授权安全性的 External ID。 |
68+
69+
```sql title='示例'
70+
-- 使用 IAM 角色创建连接
71+
CREATE CONNECTION my_iam_conn
72+
STORAGE_TYPE = 's3'
73+
ROLE_ARN = 'arn:aws:iam::123456789012:role/my-role'
74+
EXTERNAL_ID = 'my-external-id';
75+
76+
-- 创建 Stage 时引用连接
77+
CREATE STAGE my_iam_stage
78+
URL = 's3://my-bucket'
79+
CONNECTION = (CONNECTION_NAME = 'my_iam_conn');
7180
```
7281

7382
</TabItem>
7483

7584
<TabItem value="Azure Blob" label="Azure Blob">
7685

77-
下表列出了用于访问 Azure Blob Storage 的连接参数：
86+
下表列出了访问 Azure Blob Storage 的连接参数：
7887

7988
| Parameter | Required? | Description |
8089
|----------------|-------------|-------------------------------------------------------|
8190
| endpoint_url | Yes | Azure Blob Storage 的 Endpoint URL。 |
82-
| account_key | Yes | 用于身份验证的 Azure Blob Storage 帐户密钥。 |
83-
| account_name | Yes | 用于标识的 Azure Blob Storage 帐户名称。 |
84-
85-
```sql title='Examples'
91+
| account_key | Yes | Azure Blob Storage 帐户密钥。 |
92+
| account_name | Yes | Azure Blob Storage 帐户名称。 |
93+
94+
```sql title='示例'
95+
-- 创建 Azure Blob Storage 连接
96+
CREATE CONNECTION my_azure_conn
97+
STORAGE_TYPE = 'azblob'
98+
ACCOUNT_NAME = 'myaccount'
99+
ACCOUNT_KEY = 'myaccountkey'
100+
ENDPOINT_URL = 'https://<your-storage-account-name>.blob.core.windows.net';
101+
102+
-- 创建 Stage 并引用该连接
86103
CREATE STAGE my_azure_stage
87-
'azblob://my-container'
88-
CONNECTION = (
89-
ACCOUNT_NAME = 'myaccount',
90-
ACCOUNT_KEY = 'myaccountkey',
91-
ENDPOINT_URL = 'https://<your-storage-account-name>.blob.core.windows.net'
92-
);
104+
URL = 'azblob://my-container'
105+
CONNECTION = (CONNECTION_NAME = 'my_azure_conn');
93106
```
94107

95108
</TabItem>
96109

97110
<TabItem value="Google GCS" label="Google GCS">
98111

99-
下表列出了用于访问 Google Cloud Storage 的连接参数：
112+
下表列出了访问 Google Cloud Storage 的连接参数：
100113

101114
| Parameter | Required? | Description |
102115
|----------------|-------------|-------------------------------------------------------|
103-
| credential | Yes | 用于身份验证的 Google Cloud Storage 凭据。 |
116+
| credential | Yes | 用于认证的 Google Cloud Storage 凭证。 |
104117

105-
要获取 `credential`，您可以按照 Google 文档中的主题 [创建服务帐户密钥](https://cloud.google.com/iam/docs/keys-create-delete#creating)
106-
创建一个服务帐户密钥文件并下载。下载服务帐户密钥文件后，您可以
107-
通过以下命令将其转换为 base64 字符串：
118+
可以按照 Google 文档 [Create a service account key](https://cloud.google.com/iam/docs/keys-create-delete#creating) 生成服务账号密钥文件，并用下面的命令把它转成 base64：
108119

109120
```
110-
base64 -i -o ~/Desktop/base64-encoded-key.txt
121+
base64 -i <key.json> -o ~/Desktop/base64-encoded-key.txt
111122
```
112123

113-
```sql title='Examples'
124+
```sql title='示例'
125+
-- 创建 GCS 连接
126+
CREATE CONNECTION my_gcs_conn
127+
STORAGE_TYPE = 'gcs'
128+
CREDENTIAL = '<your-base64-encoded-credential>';
129+
130+
-- 创建 Stage 时引用连接
114131
CREATE STAGE my_gcs_stage
115-
'gcs://my-bucket'
116-
CONNECTION = (
117-
CREDENTIAL = '<your-base64-encoded-credential>'
118-
);
132+
URL = 'gcs://my-bucket'
133+
CONNECTION = (CONNECTION_NAME = 'my_gcs_conn');
119134
```
120135

121136
</TabItem>
122137

123138
<TabItem value="Alibaba OSS" label="Alibaba Cloud OSS">
124139

125-
下表列出了用于访问阿里云 OSS 的连接参数：
140+
下表列出了访问阿里云 OSS 的连接参数：
126141

127142
| Parameter | Required? | Description |
128143
|---------------------- |----------- |--------------------------------------------------------- |
129-
| access_key_id | Yes | 用于身份验证的阿里云 OSS Access Key ID。 |
130-
| access_key_secret | Yes | 用于身份验证的阿里云 OSS Access Key Secret。 |
144+
| access_key_id | Yes | 阿里云 OSS Access Key ID。 |
145+
| access_key_secret | Yes | 阿里云 OSS Access Key Secret。 |
131146
| endpoint_url | Yes | 阿里云 OSS 的 Endpoint URL。 |
132-
| presign_endpoint_url | No | 用于预签名阿里云 OSS URL 的 Endpoint URL。 |
147+
| presign_endpoint_url | No | 用于预签名 URL 的 Endpoint。 |
148+
149+
```sql title='示例'
150+
-- 创建阿里云 OSS 连接
151+
CREATE CONNECTION my_oss_conn
152+
STORAGE_TYPE = 'oss'
153+
ACCESS_KEY_ID = '<your-ak>'
154+
ACCESS_KEY_SECRET = '<your-sk>'
155+
ENDPOINT_URL = 'https://<bucket-name>.<region-id>[-internal].aliyuncs.com';
133156

134-
```sql title='Examples'
157+
-- 创建 Stage 并引用该连接
135158
CREATE STAGE my_oss_stage
136-
'oss://my-bucket'
137-
CONNECTION = (
138-
ACCESS_KEY_ID = '<your-ak>',
139-
ACCESS_KEY_SECRET = '<your-sk>',
140-
ENDPOINT_URL = 'https://<bucket-name>.<region-id>[-internal].aliyuncs.com'
141-
);
159+
URL = 'oss://my-bucket'
160+
CONNECTION = (CONNECTION_NAME = 'my_oss_conn');
142161
```
143162

144163
</TabItem>
145164

146165
<TabItem value="Tencent COS" label="Tencent COS">
147166

148-
下表列出了用于访问腾讯云对象存储（COS）的连接参数：
167+
下表列出了访问腾讯云对象存储（COS）的连接参数：
149168

150169
| Parameter | Required? | Description |
151170
|-------------- |----------- |------------------------------------------------------------- |
152-
| endpoint_url | Yes | 腾讯云对象存储的 Endpoint URL。 |
153-
| secret_id | Yes | 用于身份验证的腾讯云对象存储 Secret ID。 |
154-
| secret_key | Yes | 用于身份验证的腾讯云对象存储 Secret Key。 |
155-
156-
```sql title='Examples'
171+
| endpoint_url | Yes | 腾讯云 COS 的 Endpoint URL。 |
172+
| secret_id | Yes | 腾讯云 COS Secret ID。 |
173+
| secret_key | Yes | 腾讯云 COS Secret Key。 |
174+
175+
```sql title='示例'
176+
-- 创建腾讯云 COS 连接
177+
CREATE CONNECTION my_cos_conn
178+
STORAGE_TYPE = 'cos'
179+
SECRET_ID = '<your-secret-id>'
180+
SECRET_KEY = '<your-secret-key>'
181+
ENDPOINT_URL = '<your-endpoint-url>';
182+
183+
-- 创建 Stage 并引用该连接
157184
CREATE STAGE my_cos_stage
158-
'cos://my-bucket'
159-
CONNECTION = (
160-
SECRET_ID = '<your-secret-id>',
161-
SECRET_KEY = '<your-secret-key>',
162-
ENDPOINT_URL = '<your-endpoint-url>'
163-
);
185+
URL = 'cos://my-bucket'
186+
CONNECTION = (CONNECTION_NAME = 'my_cos_conn');
164187
```
165188

166189
</TabItem>
167190

168191
<TabItem value="Hugging Face" label="HuggingFace">
169192

170-
下表列出了用于访问 Hugging Face 的连接参数：
193+
下表列出了访问 Hugging Face 的连接参数：
171194

172195
| Parameter | Required? | Description |
173196
|-----------|-----------------------|-----------------------------------------------------------------------------------------------------------------|
174-
| repo_type | No (default: dataset) | Hugging Face 仓库的类型。可以是 `dataset` 或 `model`。 |
175-
| revision | No (default: main) | Hugging Face URI 的修订版本。可以是仓库的分支、标签或提交。 |
176-
| token | No | 来自 Hugging Face 的 API 令牌，可能需要用于访问私有仓库或某些资源。 |
177-
178-
```sql title='Examples'
197+
| repo_type | No (default: dataset) | Hugging Face 仓库类型，可取 `dataset` 或 `model`。 |
198+
| revision | No (default: main) | Hugging Face URI 的版本，可为分支、标签或提交。 |
199+
| token | No | Hugging Face API Token，访问私有仓库或部分资源时需要。 |
200+
201+
```sql title='示例'
202+
-- 创建 Hugging Face 连接
203+
CREATE CONNECTION my_hf_conn
204+
STORAGE_TYPE = 'hf'
205+
REPO_TYPE = 'dataset'
206+
REVISION = 'main'
207+
TOKEN = '<optional-access-token>';
208+
209+
-- 创建 Stage 并引用该连接
179210
CREATE STAGE my_huggingface_stage
180-
'hf://opendal/huggingface-testdata/'
181-
CONNECTION = (
182-
REPO_TYPE = 'dataset'
183-
REVISION = 'main'
184-
);
211+
URL = 'hf://opendal/huggingface-testdata/'
212+
CONNECTION = (CONNECTION_NAME = 'my_hf_conn');
185213
```
186214

187-
</TabItem>
215+
访问公开仓库可以省略 `TOKEN`，访问私有或受限仓库时再补上。
188216

189-
</Tabs>
217+
</TabItem>
218+
</Tabs>

0 commit comments

Comments
 (0)