@clickzetta/cz-cli-darwin-arm64 0.5.15 → 0.5.17

package/bin/skills/lakehouse-doc-en/references/create-api-connection.md

@@ -1,104 +1,90 @@
 # Create API CONNECTION
 
-This type of CONNECTION is mainly used to store and protect the authentication information of third-party application services. Through API Connection, Lakehouse can securely interact with these services via API calls. Currently, the external services supported by API Connection include Alibaba Cloud Function Compute (FC) and Tencent Cloud Function Service.
+API CONNECTION is primarily used to store and protect authentication information for third-party application services. Through API CONNECTION, Singdata Lakehouse's EXTERNAL FUNCTIONs can securely interact with these services via API calls. Currently, the external services supported by API CONNECTION include **Alibaba Cloud Function Compute (FC)**, **Tencent Cloud Functions (SCF)**, and **AWS Lambda**.
 
 ## Syntax
 
-Syntax 1
 ```
-CREATE API CONNECTION [ IF NOT EXISTS ] connection_name
-TYPE CLOUD_FUNCTION
-PROVIDER=''
-REGION=''
-ROLE_ARN=''
-NAMESPCE=''
-CODE_BUCKET=''
+CREATE API CONNECTION [ IF NOT EXISTS ] <connection_name>
+  TYPE  CLOUD_FUNCTION
+  PROVIDER = '<provider>'
+  REGION = '<region>'
+  ROLE_ARN = '<role_arn>'
+  NAMESPACE = '<namespace>'
+  CODE_BUCKET = '<code_bucket>'
 ```
-* PROVIDER: Cloud function provider, such as TENCENT, ALIYUN, and AWS
-* REGION: The region where the corresponding cloud function is located, such as 'cn-shanghai'. For Alibaba Cloud, refer to the link [region](https://help.aliyun.com/zh/oss/user-guide/regions-and-endpoints?scm=20140722.S_help%40%40%E6%96%87%E6%A1%A3%40%4031837.S_BB2%40bl%2BRQW%40ag0%2BBB1%40ag0%2Bhot%2Bos0.ID_31837-RL_%E5%9F%9F%E5%90%8D-LOC_doc%7EUND%7Eab-OR_ser-V_4-P0_2\&spm=a2c4g.11186623.d_help_search.i3), for Tencent Cloud refer to the link [region](https://cloud.tencent.com/document/product/583/17299#.E6.94.AF.E6.8C.81.E5.9C.B0.E5.9F.9F) such as: ap-beijing, for AWS refer to: [China region endpoints](https://docs.amazonaws.cn/aws/latest/userguide/endpoints-arns.html), international endpoints [region](https://docs.aws.amazon.com/general/latest/gr/lambda-service.html)
-* ROLE\_ARN: The role assumed when creating the cloud function, such as acs:ram::12228000000000000:role/czudfrole
-* CODE\_BUCKET: The name of the object storage bucket where the cloud function program files are located.
-* NAMESPCE: Required when using Tencent Cloud. For other cloud services, you can leave it blank or directly fill in 'default'. This value can be obtained as shown in the figure below
-![](.topwrite/assets/image_1740368445142.png)
-  Syntax two
-```SQL
-CREATE API CONNECTION [ IF NOT EXISTS ] connection_name
-TYPE CLOUD_FUNCTION 
-WITH PROPERTIES('parameter_key'='parameter_value')
-[COMMENT 'comment'];
-```
-**Parameter Description**
 
-* `connection_name`: The name of the connection to be created.
-* `TYPE`: Specifies the type of data source for the connection, such as `CLOUD_FUNCTION`.
-* `WITH PROPERTIES`: Specifies the authentication and connection information required for the external data source.
-* `parameter_key`: Property key.
-* `parameter_value`: Property value.
-* `IF NOT EXISTS`: Optional parameter. If the specified connection already exists, no changes are made, and a message indicating the connection exists is returned; if not specified and the connection exists, an error message is returned.
-* `COMMENT`: Optional parameter for adding comment information.
+### Parameter Descriptions
 
-### Supported Data Source Types and Parameters
+| Parameter | Description |
+| ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| `connection_name` | Name of the API connection to create. |
+| `PROVIDER` | Cloud function service provider. Supported values: `'tencent'`, `'aliyun'`, and `'aws'`. |
+| `REGION` | Region where the cloud function is deployed. **Examples**: Alibaba Cloud: `'cn-shanghai'` ([region codes](https://help.aliyun.com/document_detail/40654.html)); Tencent Cloud: `'ap-beijing'` ([region codes](https://intl.cloud.tencent.com/document/product/213/6091)); AWS: `'ap-southeast-1'` (international) or `'cn-north-1'` (China) |
+| `ROLE_ARN` | Role ARN used to execute cloud functions. **Example (Alibaba Cloud)**: `acs:ram::1222800000000000:role/czudfrole`. **Example (Tencent Cloud)**: `qcs::cam::uin/1000*******:roleName/LakehouseRole`. **Example (AWS)**: `arn:aws:iam::928925945197:role/Lambda-S3-Role` |
+| `NAMESPACE` | Namespace for the cloud function. **Required for Tencent Cloud**. For other cloud services, fill in `'default'` or leave blank as appropriate. |
+| `CODE_BUCKET` | Name of the object storage bucket containing the cloud function code package. **Tencent Cloud format is `BucketName-APP_ID`**, e.g., `myfunction-131xxxxx`. |
 
-The following are the parameters required for the `CLOUD_FUNCTION` type data source:
+For NAMESPACE: required when using Tencent Cloud. For other cloud services it can be omitted or set to `'default'`. The value is obtained as shown in the image below:
+![](.topwrite/assets/image_1735616872087.png)
 
-| Parameter Name                | Description            | Example Value                               | Required |
-| ---------------------------- | --------------------- | ----------------------------------------- | ------ |
-| `cloud_function.provider`    | Cloud function service provider | `aliyun`                                  | Yes      |
-| `cloud_function.region`      | Region where the cloud function service is located | `cn-beijing` / `cn-hangzhou`              | Yes      |
-| `cloud_function.role_arn`    | User's ARN authorization information | `acs:ram::123456789012:role/YourRoleName` | Yes      |
-| `cloud_function.namespace`   | Specifies the namespace of the external function, required for Tencent Cloud | `your_namespace`                          | Yes      |
-| `cloud_function.code_bucket` | Object storage Bucket information where the user's code is stored | `your_bucket_name`                        | Yes      |
+^
 
 ## Case Description
 
-API CONNECTION is mainly used for creating EXTERNAL FUNCTION. The usage process of EXTERNAL FUNCTION is as follows:
+API CONNECTION is primarily used for creating EXTERNAL FUNCTIONs. The EXTERNAL FUNCTION usage flow is:
+
+* User activates cloud function compute services (e.g., Alibaba Cloud Function Compute FC) and object storage services
+* Upload function execution code & executables, dependent libraries, models, and data files to object storage
+* Grant Singdata Lakehouse permission to operate the above services and access function files
+* User calls EXTERNAL FUNCTION in Singdata Lakehouse SQL statements
+* Singdata Lakehouse sends an HTTP request to the provided service address using the authentication information to invoke the function
+* Singdata Lakehouse retrieves the response and returns the result
 
-* Users activate cloud function computing services (such as Alibaba Cloud Function Compute FC) and object storage services.
-* Upload the function execution code & executable files, dependent libraries, models, and data files to object storage.
-* Grant Singdata Lakehouse permission to operate the above services and access function files.
-* Users call Remote function in Singdata Lakehouse SQL statements.
-* Singdata Lakehouse sends an HTTP request to call the running function based on the provided service address and authentication information.
-* Singdata Lakehouse retrieves the response information and returns the result.
-  Therefore, you must activate function computing services and object storage services and grant Lakehouse permissions.
+Therefore, you must activate function compute and object storage services and grant Singdata Lakehouse the necessary permissions.
 
-### Example 1: Creating API CONNECTION on Alibaba Cloud
+### Creating API CONNECTION on Alibaba Cloud
 
 * **Environment Preparation**
-  UDF relies on Alibaba Cloud's "[Object Storage](https://oss.console.aliyun.com/overview)" and "[Function Compute](https://fcnext.console.aliyun.com/overview)" services. Please ensure that the relevant services are activated.
-
-* step1: Users activate cloud function computing services (such as Alibaba Cloud Function Compute FC) and object storage services.
-
-* step2. Alibaba Cloud operations: Create a permission policy (CzUdfOssAccess) in the Alibaba Cloud RAM console: Note: Users need to have RAM permissions.
-  * Access the Alibaba Cloud Resource Access Management (RAM) [product console](https://ram.console.aliyun.com/policies).
-  * In the left navigation bar, **Permission Management** -> **Permission Policies**, search for **AliyunFCFullAccess** in the permission control interface -> Edit the **AliyunFCFullAccess** permission policy to add the following "acs\*\*:**Service**": "**fc.aliyuncs.com**"\*\* part.
-    ```JSON
-    {
-        "Version": "1",
-        "Statement": [
-            {
-                "Action": "fc:*",
-                "Resource": "*",
-                "Effect": "Allow"
-            },
-            {
-                "Action": "ram:PassRole",
-                "Resource": "*",
-                "Effect": "Allow",
-                "Condition": {
-                    "StringEquals": {
-                        "acs:Service": "fc.aliyuncs.com"
-                    }
-                }
-            }
-        ]
-    }
-    ```
-* step3: Create a permission policy (CzUdfOssAccess) in the Alibaba Cloud RAM console: Note: The user needs to have RAM permissions
-
-  * Access the Alibaba Cloud Resource Access Management (RAM) product console
-  * In the left navigation bar, go to **Permission Management** -> **Permission Policies**, and select **Create Permission Policy** in the permission control interface
-  * On the **Create Permission Policy** page, select the **Script Editor** tab, and replace `[bucket_name_1|2|3]` below with the actual OSS bucket names. Note: According to Alibaba Cloud OSS conventions, the same bucket needs to have two Resource entries: `"acs:oss:*:*:bucket_name_1"` and `"acs:oss:*:*:bucket_name_1/*"` must both exist to achieve the authorization effect:
-  ```JSON
+  EXTERNAL FUNCTION depends on Alibaba Cloud's "[Object Storage](https://oss.console.aliyun.com/overview)" and "[Function Compute](https://fcnext.console.aliyun.com/overview)" services. Ensure these services are activated.
+
+* Step 1: Activate Function Compute FC and Object Storage OSS services. Keep them in the same region as the Singdata Lakehouse instance (e.g., `cn-shanghai`).
+
+* Step 2: Get OSS Bucket + AccessKey.
+  * Go to [OSS Console](https://oss.console.aliyun.com) → Create Bucket (same region as FC).
+  * Go to [RAM User Management](https://ram.console.aliyun.com/users) → Create AccessKey, record the **AccessKey ID** and **AccessKey Secret**.
+
+* Step 3: Edit the AliyunFCFullAccess permission policy (add ram:PassRole permission).
+  * Go to [RAM Policy Console](https://ram.console.aliyun.com/policies) → search for **AliyunFCFullAccess** → Edit, add the `ram:PassRole` section:
+
+  ```json
+  {
+      "Version": "1",
+      "Statement": [
+          {
+              "Action": "fc:*",
+              "Resource": "*",
+              "Effect": "Allow"
+          },
+          {
+              "Action": "ram:PassRole",
+              "Resource": "*",
+              "Effect": "Allow",
+              "Condition": {
+                  "StringEquals": {
+                      "acs:Service": "fc.aliyuncs.com"
+                  }
+              }
+          }
+      ]
+  }
+  ```
+
+* Step 4: Create custom permission policy CzUdfOssAccess.
+  * Go to [RAM Policy Console](https://ram.console.aliyun.com/policies) → **Create Permission Policy** → **Script Editor**.
+  * Replace `bucket_name_1` etc. with actual OSS bucket names. Note: the same bucket needs both `bucket_name` and `bucket_name/*` Resource entries:
+
+  ```json
   {
       "Version": "1",
       "Statement": [
@@ -112,48 +98,54 @@ API CONNECTION is mainly used for creating EXTERNAL FUNCTION. The usage process
               ],
               "Resource": [
                   "acs:oss:*:*:bucket_name_1",
-                  "acs:oss:*:*:bucket_name_1/*",
-                  "acs:oss:*:*:bucket_name_2",
-                  "acs:oss:*:*:bucket_name_2/*",
-                  "acs:oss:*:*:bucket_name_3",
-                  "acs:oss:*:*:bucket_name_3/*"
+                  "acs:oss:*:*:bucket_name_1/*"
               ]
           }
       ]
   }
   ```
-* step4 Alibaba Cloud Console: Create a role in Alibaba Cloud RAM (e.g., CzUDFRole):
-  * In the RAM console, navigate to **Identity Management** -> **Roles** on the left sidebar, and click **Create Role**
-  * On the **Create Role** page, select the type as **Alibaba Cloud Account**, fill in the custom **Role Name** (e.g., CzUDFRole), select **Other Cloud Account** in **Select Trusted Cloud Account**, and enter: 1384322691904283 (Singdata Lakehouse Shanghai's cloud main account), then click **Complete**
-  * After creation, click **Authorize Role**:
-  * In **System Policies**, grant the **AliyunFCFullAccess** policy to the role CzUDFRole
-  * In **Custom Policies**, grant the newly created policy (**CzUdfOssAccess**) to the role
-
-* step5: After creation, click **Authorize Role**: In **Custom Policies**, grant the newly created policy (CzUdfOssAccess) to the role. In the role CzUDFRole details page, obtain the RoleARN information of the role: `'acs:ram::1222808864xxxxxxx:role/czudfrole'`![](.topwrite/assets/image_1740368644886.png)
-
-* step6: Fill the above role\_arn into the syntax parameter, and create an Alibaba Cloud Function Compute connection
-```SQL
-CREATE API CONNECTION my_funciton_connection
-TYPE CLOUD_FUNCTION
-PROVIDER='aliyun'
-REGION='cn-hangzhou'
-ROLE_ARN='acs:ram::1757168149572678:role/czudfrole'
-CODE_BUCKET='function-compute-my1';
-```
-* step7: desc connection to obtain external ID information: In this example, the external ID is: `VW9UaGwYENBQ7cFp`
+
+  * Click **Next**, enter the policy name **CzUdfOssAccess**, click **Done**.
+
+* Step 5: Create a RAM Role and authorize it.
+  * Go to [RAM Role Console](https://ram.console.aliyun.com/roles) → **Create Role**:
+  * Role type: **Alibaba Cloud Account** → **Other Cloud Account**
+  * Enter Account ID `1384322691904283` (Singdata Lakehouse's main account), click **Next**
+  * Under **Select Permissions**, check both the system policy **AliyunFCFullAccess** and the custom policy **CzUdfOssAccess**
+  * Click **Next**, enter the role name (e.g., `CzUDFRole`), click **OK**
+  * After successful creation, go to the role detail page to get the **Role ARN**: `acs:ram::<your_account_id>:role/CzUDFRole`
+
+* Step 6: Execute SQL to create API CONNECTION.
+
+  ```sql
+  CREATE API CONNECTION my_funciton_connection
+      TYPE CLOUD_FUNCTION
+      PROVIDER = 'aliyun'
+      REGION = 'cn-shanghai'
+      ROLE_ARN = 'acs:ram::1757168149572678:role/CzUDFRole'
+      CODE_BUCKET = 'function-compute-my1';
   ```
+
+* Step 7 (optional): Configure External ID.
+
+  After successful creation, run the following to get the External ID:
+
+  ```sql
   DESC CONNECTION my_funciton_connection;
   ```
-![](.topwrite/assets/image_1735638011131.png)
-  * In Alibaba Cloud RAM -> Roles -> Trust Policy, modify the **trust policy** of CzUDFRole:
-  ```Python
+
+  ![](.topwrite/assets/image_1735638011131.png)
+
+  Go back to Alibaba Cloud [RAM Roles](https://ram.console.aliyun.com/roles) → `CzUDFRole` → **Trust Policy** → **Edit**, replace the `sts:ExternalId` value with the value from the DESC result:
+
+  ```json
   {
     "Statement": [
       {
         "Action": "sts:AssumeRole",
         "Condition": {
           "StringEquals": {
-            "sts:ExternalId": "O0lQUogDJajHqnAQ"
+            "sts:ExternalId": "Replace with the ExternalId from DESC result"
           }
         },
         "Effect": "Allow",
@@ -167,186 +159,223 @@ CODE_BUCKET='function-compute-my1';
     "Version": "1"
   }
   ```
-### Example 2: Create API CONNECTION on Tencent Cloud
+
+  > The `1384322691904283` in the trust policy is the Singdata main account and must not be changed.
+
+### Creating API CONNECTION on Tencent Cloud
 
 **Environment Preparation**
-UDF relies on Tencent Cloud's "[Object Storage](https://console.cloud.tencent.com/cos)" and "[Cloud Functions](https://console.cloud.tencent.com/scf/list?rid=1\&ns=default)" services. Please ensure that the relevant services are activated.
-
-* Object Storage: Required in the Lakehouse deployment region (e.g., ap-shanghai) to store UDF base code;
-* Cloud Functions: After activating the **Cloud Functions** service, it is recommended to manually create a function using the template creation feature, preferably using templates with the WebFunc tag such as the Flask framework template. During this process, the Tencent Cloud console will guide users through some initial configurations, such as activating the log service (CLS) and other dependent services, creating necessary Access Control (CAM) roles, and granting necessary Access Control (CAM) permissions.
-* **step1**: Users activate Tencent Cloud's cloud function computing service. The cloud function region should be consistent with the Lakehouse service region.
-![](.topwrite/assets/image_1740368721078.png)
-* **step2**: Data creation permission policy (LakehouseAccess):
-
-  * Log in to Tencent Cloud and go to the **Access Management** [product console](https://console.cloud.tencent.com/cam/policy)
-  * In the **Access Management** page, navigate to **Policies** on the left sidebar, and in the permission control interface, select **Create Custom Policy** -> **Create by Policy Generator** -> **Visual Policy Generator**.
-  * In the **Visual Policy Generator** tab, **Service**: Select **Cloud Functions**; **Action**: Select **All Actions** (you can make more granular selections based on actual needs); **Resource**: Select **All Resources** or **Specific Resources** as needed. In this case, select specific resources, use namespace authorization as shown below, click the edit button, select the region activated in step1, the resource can be * or a specified namespace, in this case, the namespace from step1: default. As shown in the red-marked area of the cloud function in Figure 2![](.topwrite/assets/image_1740369082106.png)
-![](.topwrite/assets/image_1740368445142.png)
-    Click to create the policy
-* step3: [Create Role](https://console.cloud.tencent.com/cam/role) CzUdfRole
-  * Create a new role
-  * Select Tencent Cloud Account
-  * Select **Other Main Account 100029595716 (Singdata Main Account)**, keep other options as default, and click **Next**
-  * In the **Configure Role Policy** configuration, authorize the newly created LakehouseAccess custom policy to the current role. Click **Next**, and in **Role Naming**, fill in `LakehouseRole` to complete the creation.
-  * After successful creation, go to the details page of the role `LakehouseRole` in the role list to get the RoleARN information of the role: `qcs::cam::uin/1000*******:roleName/LakehouseRole`
-  * Remember the RoleArn, for example: `qcs::cam::uin/1000*******:roleName/LakehouseRole`
-* step4: Activate COS and create a new BUCKET
-  * Create a new bucket to store udf code, the region should be consistent with the Lakehouse service region. The newly created bucket is myfunction as shown below![](.topwrite/assets/image_1740378042671.png)
-  * Authorize Lakehouse to access the bucket (myfunction)
-  * Go to the **Access Management** [product console](https://console.cloud.tencent.com/cam/policy). Find the newly created "LakehouseAccess" policy. Select Edit![](.topwrite/assets/image_1740378228008.png)
-  * Select the Visual Policy Generator. Add permissions![](.topwrite/assets/image_1740378259906.png)
-* **Service**: Select **Object Storage (cos)**; **Action**: Select **All Actions** (you can make more granular selections based on actual needs); **Resource**: Select **All Resources** or **Specific Resources** as needed. In this example, select specific resources, which is `myfunction-131xxxxx` in Shanghai.![](.topwrite/assets/image_1740378387729.png)
-* step5: Create Connection on the Lakehouse side
-  \* Execute the following command in Studio or the Lakehouse JDBC client:
-  `SQL
-      CREATE API CONNECTION my_funciton_connection
+EXTERNAL FUNCTION depends on Tencent Cloud's "[Object Storage](https://console.cloud.tencent.com/cos)" and "[Cloud Functions](https://console.cloud.tencent.com/scf/list?rid=1\&ns=default)" services. Ensure these services are activated.
+
+* Object Storage: Required in the Singdata Lakehouse deployment region (e.g., ap-shanghai) for storing function base code.
+* Cloud Functions: After activating **Cloud Functions**, it is recommended to manually create a function using the template creation feature, preferably Flask framework templates or other templates with a WebFunc tag. During this process, the Tencent Cloud console will guide users through initial configurations such as activating log services (CLS) and other dependencies, creating necessary Access Control (CAM) roles, and granting necessary CAM permissions.
+
+* Step 1: Activate Tencent Cloud's Cloud Functions (SCF) service. Keep the cloud function region consistent with the Singdata Lakehouse service region.
+  ![](.topwrite/assets/image_1735616566747.png)
+
+* Step 2: Activate COS and create a storage bucket.
+  * Go to [COS Console](https://console.cloud.tencent.com/cos) → Create bucket (same region as SCF, e.g., `ap-shanghai`).
+  * After creation, the full name in the bucket list is `BucketName-APP_ID` (e.g., `myfunction-1310000503`). **Record the Bucket name and APP_ID**—both are needed for configuration.
+
+* Step 3: Obtain API credentials.
+  * Go to [Access Management](https://console.cloud.tencent.com/cam/capi) → Create credentials, record **SecretId** and **SecretKey**.
+
+* Step 4: Create CAM custom policy (LakehouseAccess).
+  * Log in to Tencent Cloud, go to the **Access Management** [product console](https://console.cloud.tencent.com/cam/policy)
+  * In the left navigation bar go to **Policies**, select **Create Custom Policy** → **Create by Policy Syntax** → select **Blank Template**, paste the following JSON (replace `<region>`, `<APP_ID>`, `<bucket>` with actual values):
+
+  ```json
+  {
+      "statement": [
+          {
+              "action": ["scf:*"],
+              "effect": "allow",
+              "resource": ["*"]
+          },
+          {
+              "action": ["cos:*"],
+              "effect": "allow",
+              "resource": [
+                  "qcs::cos:<region>:uid/<APP_ID>:<bucket>-<APP_ID>/*"
+              ]
+          }
+      ],
+      "version": "2.0"
+  }
+  ```
+
+  > Example: `qcs::cos:ap-shanghai:uid/1253896122:qiliang-external-function-1253896122/*`
+
+  * Click **Next**, set the policy name to **`LakehouseAccess`** (must use this name exactly), click **Done**.
+
+  > ⚠️ The policy must include both `scf:*` and `cos:*` rules. Missing the COS permission will cause `AccessDenied (Status Code: 403)` during `CREATE FUNCTION`. The COS Resource format is `qcs::cos:<region>:uid/<APP_ID>:<bucket>-<APP_ID>/*`; the trailing `/*` is required.
+
+* Step 5: Create CAM Role (LakehouseRole).
+  * Go to [Access Management](https://console.cloud.tencent.com/cam/role) → Create role:
+  * Role entity: **Tencent Cloud Account** → **Other Main Account**
+  * Enter Account ID `100029595716` (Singdata's Tencent Cloud main account), click **Next**
+  * Check the newly created `LakehouseAccess` policy, click **Next**
+  * Set the role name to **`LakehouseRole`** (must use this name exactly), click **Done**
+  * After successful creation, go to the role detail page to get the Role ARN: `qcs::cam::uin/<your_account_id>:roleName/LakehouseRole`
+
+  > ⚠️ The role name must be `LakehouseRole`. The role entity must be set to "Other Main Account" and trust Singdata account `100029595716`—**not** "Tencent Cloud Product Services".
+
+* Step 6: Execute SQL to create API CONNECTION.
+
+  ```sql
+  CREATE API CONNECTION my_funciton_connection
       TYPE CLOUD_FUNCTION
-      PROVIDER='tencent'
-      REGION='ap-shanghai'
-      ROLE_ARN='qcs::cam::uin/xxxx:roleName/CzUDFRole'
-      NAMESPCE='default'
-      CODE_BUCKET='myfunction-131xxxx';
-      `
-
-  * Note: To prevent the ROLE_ARN from being obtained by third parties for unauthorized data access, you can use `EXTERNAL ID` as an additional layer of verification to ensure that access is only allowed when the request contains the preset `EXTERNAL ID`. This means that even if a third party knows some other access information (such as the role ARN), they cannot access the resource without the correct `EXTERNAL ID`.
-  * During the API Connection process, Lakehouse will generate this EXTERNAL ID, which can be configured into the role verification of the COS account to achieve access control:
-```
--- View EXTERNAL ID
-DESC CONNECITON my_funciton_connection ;
-```
-![](.topwrite/assets/image_1740378621626.png)
+      PROVIDER = 'tencent'
+      REGION = 'ap-shanghai'
+      ROLE_ARN = 'qcs::cam::uin/<your_account_id>:roleName/LakehouseRole'
+      NAMESPACE = 'default'
+      CODE_BUCKET = 'myfunction-1310000503';
+  ```
+
+  > ⚠️ `CODE_BUCKET` format is `BucketName-APP_ID` (cannot be just the Bucket name). `NAMESPACE` is required for Tencent Cloud and is typically `default`.
+
+* Step 7 (optional): Configure External ID.
+  > ⚠️ **Note**: To prevent the ROLE_ARN from being obtained by third parties for unauthorized data access, you can use `EXTERNAL ID` as an additional verification layer, ensuring that access is only allowed when the request includes the preset `EXTERNAL ID`. This means that even if a third party knows other access information (such as the role ARN), they cannot access the resource without the correct `EXTERNAL ID`.
+
+  After the API CONNECTION is successfully created, run the following to get the External ID:
+
+  ```sql
+  DESC CONNECTION my_funciton_connection;
+  ```
+
+  ![](.topwrite/assets/image_1735630257317.png)
 
-  * Client side: Enter the Tencent Cloud **Access Management** console, **Role** -> **CzUDFRole** -> **Role Carrier** -> **Manage Carrier**, select **Add Account** -> select **Current Main Account**, and fill in the main account ID: `100029595716` (Singdata's Tencent Cloud main account), and check **Enable Verification**, enter the EXTERNAL\_ID from the previous DESC result, click **Confirm** -> **Update**
+  * On the client side: Go to the Tencent Cloud **Access Management** console, **Role** → **LakehouseRole** → **Role Entity** → **Manage Entities**, select **Add Account** → select **Current Main Account**, enter the main account ID `100029595716` (Singdata's Tencent Cloud main account), check **Enable Verification**, enter the EXTERNAL_ID from the DESC result, click **Confirm** → **Update**.
 
-### Example 3: Create API CONNECTION on AWS
+### Creating API CONNECTION on AWS
 
 * **Environment Preparation**
-  UDF relies on Alibaba Cloud's "[Object Storage](https://cn-north-1.console.amazonaws.cn/s3/get-started?region=cn-north-1\&bucketType=general)" and "[Lambda Function](https://cn-north-1.console.amazonaws.cn/lambda/home)" services. Please ensure that the relevant services are activated.
-
-* step1: User activates Lambda and Object Storage services on the cloud
-
-* step2: Create permission policy on AWS side (LakehouseAccess):
-  * Log in to the AWS cloud platform and enter the **Identity and Access Management (IAM)** product console
-  * In the IAM page's left navigation bar, go to **Account Settings**, in the **Security Token Service (STS)** section, find the **Endpoint** list, locate the region corresponding to the Singdata Lakehouse for the current instance, and if the **STS Status** is not enabled, please enable it.
-  * In the IAM page's left navigation bar, go to **Policies**, in the **Policies** interface, select **Create Policy**, and choose Json in the policy editor.
-  * Add the policy to allow Singdata Lakehouse to access the S3 bucket and directory. Below is a sample policy, please replace `<bucket>` with the actual bucket and path prefix name.
-    ```JSON
-    {
-    	"Version": "2012-10-17",
-    	"Statement": [
-    		{
-    			"Sid": "VisualEditor0",
-    			"Effect": "Allow",
-    			"Action": [
-    				"lambda:CreateFunction",
-    				"lambda:DeleteProvisionedConcurrencyConfig",
-    				"lambda:GetFunctionConfiguration",
-    				"lambda:ListProvisionedConcurrencyConfigs",
-    				"lambda:GetProvisionedConcurrencyConfig",
-    				"lambda:ListLayers",
-    				"lambda:ListLayerVersions",
-    				"lambda:DeleteFunction",
-    				"lambda:GetAlias",
-    				"lambda:ListCodeSigningConfigs",
-    				"lambda:UpdateFunctionEventInvokeConfig",
-    				"lambda:DeleteFunctionCodeSigningConfig",
-    				"lambda:ListFunctions",
-    				"lambda:GetEventSourceMapping",
-    				"lambda:InvokeFunction",
-    				"lambda:ListAliases",
-    				"lambda:GetFunctionCodeSigningConfig",
-    				"lambda:UpdateAlias",
-    				"lambda:UpdateFunctionCode",
-    				"lambda:ListFunctionEventInvokeConfigs",
-    				"lambda:ListFunctionsByCodeSigningConfig",
-    				"lambda:GetFunctionConcurrency",
-    				"lambda:PutProvisionedConcurrencyConfig",
-    				"lambda:ListEventSourceMappings",
-    				"lambda:PublishVersion",
-    				"lambda:DeleteEventSourceMapping",
-    				"lambda:CreateAlias",
-    				"lambda:ListVersionsByFunction",
-    				"lambda:GetLayerVersion",
-    				"lambda:PublishLayerVersion",
-    				"lambda:InvokeAsync",
-    				"lambda:GetAccountSettings",
-    				"lambda:CreateEventSourceMapping",
-    				"lambda:GetLayerVersionPolicy",
-    				"lambda:PutFunctionConcurrency",
-    				"lambda:DeleteCodeSigningConfig",
-    				"lambda:ListTags",
-    				"lambda:DeleteLayerVersion",
-    				"lambda:PutFunctionEventInvokeConfig",
-    				"lambda:DeleteFunctionEventInvokeConfig",
-    				"lambda:CreateCodeSigningConfig",
-    				"lambda:PutFunctionCodeSigningConfig",
-    				"lambda:UpdateEventSourceMapping",
-    				"lambda:UpdateFunctionCodeSigningConfig",
-    				"lambda:GetFunction",
-    				"lambda:UpdateFunctionConfiguration",
-    				"lambda:UpdateCodeSigningConfig",
-    				"lambda:GetFunctionEventInvokeConfig",
-    				"lambda:DeleteAlias",
-    				"lambda:DeleteFunctionConcurrency",
-    				"lambda:GetCodeSigningConfig",
-    				"lambda:GetPolicy"
-    			],
-    			"Resource": "*"
-    		},
-    		{
-    			"Sid": "VisualEditor1",
-    			"Effect": "Allow",
-    			"Action": [
-    				"s3:PutObject",
-    				"s3:GetObject",
-    				"s3:DeleteObjectVersion",
-    				"s3:ListBucket",
-    				"s3:DeleteObject",
-    				"s3:GetBucketLocation",
-    				"s3:GetObjectVersion"
-    			],
-    			"Resource": "arn:aws-cn:s3:::cz-udf-code"
-    		}
-    	]
-    }
-    ```
-* Select Next, enter the policy name (e.g., LakehouseAccess) and description (optional)
-  * Click Create Policy to complete the policy creation
-
-step3: Create a role on the AWS side (LakehouseVolumeRole):
-
-* Log in to the AWS cloud platform and go to the **Identity and Access Management (IAM)** product console
-* In the IAM page's left navigation bar, go to **Roles** -> **Create role** -> **AWS account**, select **Another AWS account**, and enter `028022243208` in the Account ID
-
-> Note: To prevent the ROLE\_ARN from being obtained by third parties for unauthorized data access, you can check **Options** and select **Require external ID (best time for third party to assume this role)**. After checking, you can fill in `000000` as a placeholder in the **EXTERNAL ID** field to be filled in later. `EXTERNAL ID` serves as an additional verification layer, ensuring that access is only allowed when the request includes the preset `EXTERNAL ID`. This means that even if a third party knows some other access information (such as the role ARN), they cannot access the resources without the correct `EXTERNAL ID`.
-
-![](.topwrite/assets/image_1740379714725.png)
-
-* Select Next, on the Add permissions page, choose the policy created in step2 `LakehouseAccess`, then select Next
-* Fill in the Role name (e.g., `LakehouseVolumeRole`) and description, click **Create role** to complete the role creation
-* On the role details page, obtain the value of **Role ARN** to create the STORAGE CONNECTION
-
-![](.topwrite/assets/image_1740379729037.png)
-
-
-
-step4: Create an API CONNECTION on the Singdata Lakehouse side:
-
-* Execute the following commands in Studio or the Lakehouse JDBC client:
-```
-CREATE API CONNECTION udf_noah 
-    TYPE cloud_function
-    PROVIDER = 'aws'
-    REGION = 'cn-north-1'
-    ROLE_ARN = 'arn:aws-cn:iam::028022243208:role/CzUdfRole'
-    CODE_BUCKET = 'cz-udf-code'
-    NAMESPACE = 'default';
-```
-* During the process of creating a storage connection, Lakehouse will generate this EXTERNAL ID. You can configure this EXTERNAL ID into the Trust Policy of the AWS IAM role (`LakehouseVolumeRole`) created in step 3 to achieve additional access control:
-```
--- View EXTERNAL ID 
-DESC CONNECTION udf_noah ;
-```
-![](.topwrite/assets/image_1740379856735.png)
+  EXTERNAL FUNCTION depends on AWS's "[Object Storage](https://s3.console.aws.amazon.com)" and "[Lambda Functions](https://console.aws.amazon.com/lambda/home)" services. Ensure these services are activated.
+  * For China region, use the [Beijing console](https://cn-north-1.console.amazonaws.cn); for international regions, use the appropriate regional console.
+
+* Step 1: Activate Lambda and S3 services.
+  * Go to the [Lambda Console](https://console.aws.amazon.com/lambda) and [S3 Console](https://s3.console.aws.amazon.com) and confirm the services are activated.
+
+* Step 2: Create an S3 storage bucket.
+  * Go to [S3 Console](https://s3.console.aws.amazon.com) → Create bucket (same region as Lambda, e.g., `ap-southeast-1`).
+  * Record the Bucket name—it will be needed in the SQL later.
+
+* Step 3: Create an IAM user and get an AccessKey.
+  * Go to [IAM Users](https://console.aws.amazon.com/iam) → Create user:
+  * Any username (e.g., `qiliang-udf`); do not check "Provide user access to the AWS Management Console"
+  * Attach policy directly: search and select `AmazonS3FullAccess`
+  * After creation, go to the user → **Security credentials** → **Create access key**
+  * Select **Command Line Interface (CLI)** → Create → Save the **Access Key ID** and **Secret Access Key**
+
+* Step 4: Create IAM permission policy.
+  * Log in to the AWS platform, go to the **Identity and Access Management (IAM)** product console.
+  * In the left navigation bar go to **Policies**, select **Create policy** → **JSON**, paste the following policy (replace `<bucket>` with the Bucket name from Step 2):
+
+  ```json
+  {
+      "Version": "2012-10-17",
+      "Statement": [
+          {
+              "Effect": "Allow",
+              "Action": [
+                  "s3:GetObject",
+                  "s3:GetObjectVersion",
+                  "s3:PutObject",
+                  "s3:ListBucket"
+              ],
+              "Resource": [
+                  "arn:aws:s3:::<bucket>",
+                  "arn:aws:s3:::<bucket>/*"
+              ]
+          },
+          {
+              "Effect": "Allow",
+              "Action": "lambda:*",
+              "Resource": "*"
+          }
+      ]
+  }
+  ```
+
+  > ⚠️ S3 must include `PutObject` (the platform needs to write code packages to S3). Lambda uses `lambda:*` to avoid missing operations by listing them individually.
+
+  * Click **Next**, set the policy name to `LakehouseAccess`, click **Create policy**.
+
+* Step 5: Create IAM Role.
+  * Go to [IAM Roles](https://console.aws.amazon.com/iam/home#/roles) → Create role:
+  * Trusted entity type: **AWS service** → Use case: **Lambda**
+  * Permission policies: check the newly created `LakehouseAccess` and the AWS built-in `AWSLambdaBasicExecutionRole`
+  * Click **Next**, set the role name to `Lambda-S3-Role`, click **Create role**
+  * After successful creation, go to the role detail page and copy the **Role ARN**: `arn:aws:iam::<your_AWS_account_id>:role/Lambda-S3-Role`
+
+* Step 6: Edit the trust policy (add Singdata account's AssumeRole permission).
+  * Role detail page → **Trust relationships** → **Edit trust policy**, add both the Lambda service and the Singdata account:
+
+  ```json
+  {
+      "Version": "2012-10-17",
+      "Statement": [
+          {
+              "Effect": "Allow",
+              "Principal": {
+                  "Service": "lambda.amazonaws.com"
+              },
+              "Action": "sts:AssumeRole"
+          },
+          {
+              "Effect": "Allow",
+              "Principal": {
+                  "AWS": "arn:aws:iam::014617434350:root"
+              },
+              "Action": "sts:AssumeRole"
+          }
+      ]
+  }
+  ```
+
+  > ⚠️ `014617434350` is Singdata's international AWS account; China site uses `028022243208`. Missing Singdata account's trust relationship will result in `AccessDenied: sts:AssumeRole`.
+
+  > ⚠️ This is the **trust policy** (Trust relationships), not the permissions policy (Permissions). Do not paste the permissions policy JSON here—they are on different pages.
+
+* Step 7: Execute SQL to create API CONNECTION.
+
+  ```sql
+  CREATE API CONNECTION udf_noah
+      TYPE CLOUD_FUNCTION
+      PROVIDER = 'aws'
+      REGION = 'ap-southeast-1'
+      ROLE_ARN = 'arn:aws:iam::928925945197:role/Lambda-S3-Role'
+      CODE_BUCKET = 'qiliang-udf-code';
+  ```
+
+  > International region endpoint format is `s3.<region>.amazonaws.com`; China region is `s3.<region>.amazonaws.com.cn`.
+
+* Step 8 (optional): Configure External ID.
+  After the API CONNECTION is successfully created, run the following to get the External ID:
+
+  ```sql
+  DESC CONNECTION udf_noah;
+  ```
+
+  ![](.topwrite/assets/image_1735802829076.png)
+
+  Go back to **IAM Roles** → `Lambda-S3-Role` → **Trust relationships** → **Edit trust policy**, add a `Condition` to the Singdata account's `Statement`:
+
+  ```json
+  {
+      "Effect": "Allow",
+      "Principal": {
+          "AWS": "arn:aws:iam::014617434350:root"
+      },
+      "Action": "sts:AssumeRole",
+      "Condition": {
+          "StringEquals": {
+              "sts:ExternalId": "ExternalId value from DESC result"
+          }
+      }
+  }
+  ```
+
+### Next Steps:
 
-* In the AWS IAM console, navigate to **Roles** in the left sidebar, find the role created in step 3 and enter the role details page. In **Trust relationships**, replace the value of `sts:ExternalId` `000000` with the `EXTERNAL_ID` from the DESC result. Click **Update** to complete the role policy update.
+After completing the API CONNECTION creation, you can proceed to create external functions, supporting Python and Java scripts to process data in Singdata Lakehouse. See: [Create External Function](create_external_function.md)