Skip to main content

​
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
  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 → 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: 
-- 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): 
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
  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., http://service.cn-hangzhou.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

ParameterTypeDescriptionExample
connection_namestringUnique identifier for this connectionProduction MaxCompute
access_key_idstringAlibaba Cloud RAM user Access Key IDLTAI5t...
access_key_secretstringAlibaba Cloud RAM user Access Key SecretgKxR8...
endpointstringRegion-specific MaxCompute service endpoint (see Step 4)-
project_namestringMaxCompute project namemy_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