> ## Documentation Index
> Fetch the complete documentation index at: https://docs.clarityq.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MaxCompute

> Connect Alibaba Cloud MaxCompute to ClarityQ

## Setup

### Step 1: Get your Alibaba Cloud credentials

To connect ClarityQ to your MaxCompute project, you'll need the following information:

1. **Access Key ID**
2. **Access Key Secret**
3. **MaxCompute Endpoint**
4. **Project Name**

### Step 2: Create a RAM user for ClarityQ

Create a dedicated RAM (Resource Access Management) user for ClarityQ to securely access your MaxCompute data:

1. Log in to the [Alibaba Cloud Console](https://ram.console.alibabacloud.com/)
2. Navigate to **RAM** → **Users**
3. Click **Create User**
4. Enter the login name `clarityq`
5. Check **Permanent AccessKey** ("Create an AccessKey ID and Secret for API or SDK access")
6. A confirmation prompt will appear — check **I confirm that it is necessary to create an AccessKey**
7. Click **OK**
8. **Copy the Access Key ID and Access Key Secret** immediately — the secret is only shown once

### Step 3: Assign permissions to the RAM user

Grant the ClarityQ RAM user the necessary permissions to read your MaxCompute data.

First, find your Main Account UID and the RAM user's UID:

1. Go to the [RAM Console](https://ram.console.alibabacloud.com/) → **Users**
2. Click on the `clarityq` user
3. Copy the **User UID** (a numeric ID) — this is your `<ram-user-uid>`
4. Your **Main Account ID** can be found by hovering over your avatar in the top-right corner of the Alibaba Cloud Console — this is your `<main-account-uid>`

Then run the following SQL commands in the MaxCompute SQL editor, replacing `<main-account-uid>`, `<ram-user-uid>`, and `<project_name>` with your values:

```sql theme={null}
-- Add the RAM user to your MaxCompute project
ADD USER RAM$<main-account-uid>:<ram-user-uid>;

-- Create a read-only role for ClarityQ
CREATE ROLE clarityq_reader;

-- Grant the role permission to run queries, list tables, and read all table data
GRANT CreateInstance, List ON PROJECT <project_name> TO ROLE clarityq_reader;
GRANT Describe, Select ON TABLE * TO ROLE clarityq_reader;

-- Assign the role to the ClarityQ user
GRANT clarityq_reader TO RAM$<main-account-uid>:<ram-user-uid>;
```

To grant access to specific tables only (instead of all tables):

```sql theme={null}
GRANT Describe, Select ON TABLE <table_name> TO ROLE clarityq_reader;
```

### Step 4: Find your MaxCompute endpoint

The MaxCompute endpoint is region-specific. Use the endpoint that corresponds to the region your project is deployed in:

1. Go to the [MaxCompute Endpoints documentation](https://www.alibabacloud.com/help/en/maxcompute/user-guide/endpoints)
2. Find the row matching your project's region
3. Copy the appropriate endpoint URL

### Step 5: Configure connection in ClarityQ

In the ClarityQ interface, fill out the connection form with the following fields:

#### Required Fields

* **Connection Name**: Choose a name for this connection (e.g., "Production MaxCompute")
* **Access Key ID**: Your RAM user's Access Key ID
* **Access Key Secret**: Your RAM user's Access Key Secret
* **Endpoint**: Your region-specific MaxCompute endpoint (e.g., `https://service.us-east-1.maxcompute.aliyun.com/api`)
* **Project Name**: Your MaxCompute project name (e.g., `my_analytics_project`)

### Step 6: Test the connection

Verify the connection in ClarityQ to ensure:

* Alibaba Cloud authentication succeeds
* MaxCompute project is accessible
* Table metadata can be discovered
* Query execution works correctly

## Connection parameters reference

### Required parameters

| Parameter           | Type   | Description                                              | Example                                               |
| ------------------- | ------ | -------------------------------------------------------- | ----------------------------------------------------- |
| `connection_name`   | string | Unique identifier for this connection                    | `Production MaxCompute`                               |
| `access_key_id`     | string | Alibaba Cloud RAM user Access Key ID                     | `LTAI5t...`                                           |
| `access_key_secret` | string | Alibaba Cloud RAM user Access Key Secret                 | `gKxR8...`                                            |
| `endpoint`          | string | Region-specific MaxCompute service endpoint (see Step 4) | `https://service.us-east-1.maxcompute.aliyun.com/api` |
| `project_name`      | string | MaxCompute project name                                  | `my_analytics_project`                                |

## Troubleshooting

### Common connection issues

**Authentication failed**

* Verify your Access Key ID and Secret are correct and active
* Ensure the RAM user has **Permanent AccessKey** enabled
* Check that the Access Key has not been disabled or deleted in the RAM console

**Project not found**

* Confirm the project name is spelled correctly (case-sensitive)
* Verify the endpoint region matches the region where your project was created
* Ensure the RAM user has been granted access to the project

**Permission denied on tables**

* Confirm the RAM user has been granted **SELECT** permissions at the project level
* For project-level permissions, ensure the `ADD USER` command was run before granting table access
* Check if the project owner has restricted access via security policies or label-based security