Column Aliases

Use column aliases to define multiple names for the same column in a Hydrolix table. Aliases can be used interchangeably in queries as alternate names for columns.

Column alias overview⚓︎

• Column aliases are stored in the aliases array in the table schema.
• Aliases show up as the ALIAS type in DESCRIBE TABLE output.
• The default_expression output points to the actual column.

Advantages of column aliases⚓︎

• Columns can be renamed without downtime or breaking existing queries, dashboards, or applications that reference them.
• Retain support for legacy applications when transitioning to a new naming convention.
• Support multi-tenant and multi-team naming conventions without duplicating data.
• Use multiple API versions simultaneously without data duplication or transforms.
• Enable integration between systems without transformation overhead.

Use cases⚓︎

See examples of ways to use column aliasing.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

-- Actual column: user_id
-- Renamed to: customer_id
-- Both names work in queries after the rename

SELECT customer_id, order_total 
FROM sales 
WHERE user_id > 1000;

-- Legacy dashboards using user_id continue working
SELECT user_id, COUNT(*) as order_count
FROM sales
GROUP BY user_id;

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

-- Actual column: created_timestamp
-- Aliases: createdTimestamp, created_at
-- Support both camelCase and snake_case simultaneously

-- Frontend team uses camelCase
SELECT createdTimestamp, orderTotal 
FROM orders;

-- Backend team uses snake_case
SELECT created_at, order_total 
FROM orders;

-- Both queries return the same data

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14

-- Actual column: response_time_ms
-- Aliases: responseTime, latency

-- API v1 uses responseTime
SELECT endpoint, responseTime, status_code
FROM api_logs
WHERE responseTime > 1000;

-- API v2 uses latency
SELECT endpoint, latency, status_code
FROM api_logs
WHERE latency > 1000;

-- Both APIs work without migration

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

-- Actual column: purchase_amount
-- Aliases: revenue, sales, transaction_value

-- Marketing team queries
SELECT DATE(order_date) as date, SUM(revenue) as daily_revenue
FROM transactions
GROUP BY date;

-- Finance team queries
SELECT DATE(order_date) as date, SUM(purchase_amount) as daily_total
FROM transactions
GROUP BY date;

-- Sales team queries
SELECT customer_id, SUM(sales) as total_sales
FROM transactions
GROUP BY customer_id;

Rename columns with aliases⚓︎

Column aliases are managed through the config API. Rename columns using the Hydrolix UI or the API's /add_name endpoint.

Rename a column in the UI⚓︎

1. Navigate to your table in the Hydrolix UI.
2. Click the Schema tab.
3. Locate the column you want to rename.
4. In the Aliases field, add the new column name.
5. Click Save.

The column can now be queried using either the original name or the new alias.

Rename a column with the API⚓︎

Use the /add_name endpoint to add an alias to an existing column. This adds the new name to the column's aliases array while preserving the original name.

Add an alias to a column⚓︎

This example adds customer_id as an alias for the column user_id.

1
2
3
4
5
6
7

POST /config/v1/orgs/{org_id}/projects/{project_id}/tables/{table_id}/columns/{column_id}/add_name/
Content-Type: application/json
Authorization: Bearer $HDX_TOKEN

{
  "name": "customer_id"
}

1
2
3
4
5

curl --request POST \
  --url "https://$HDX_HOSTNAME/config/v1/orgs/$ORG_ID/projects/$PROJECT_ID/tables/$TABLE_ID/columns/$COLUMN_ID/add_name/" \
  --header "Authorization: Bearer $HDX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name": "customer_id"}'

1
2
3
4
5
6
7

{
  "id": "a1b2c3d4-e5f6-7890-a1b2-c3d4e5f67890",
  "name": "user_id",
  "type": "uint64",
  "aliases": ["user_id", "customer_id"],
  "modified": "2025-12-02T10:30:00.123456Z"
}

Both user_id and customer_id are now valid names for querying this column.

Rename a column multiple times⚓︎

You can call the /add_name endpoint multiple times to track rename history. Each call adds another alias to the array.

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13

# First rename: user_id → customer_id
curl --request POST \
  --url "https://$HDX_HOSTNAME/config/v1/orgs/$ORG_ID/projects/$PROJECT_ID/tables/$TABLE_ID/columns/$COLUMN_ID/add_name/" \
  --header "Authorization: Bearer $HDX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name": "customer_id"}'

# Second rename: customer_id → account_id  
curl --request POST \
  --url "https://$HDX_HOSTNAME/config/v1/orgs/$ORG_ID/projects/$PROJECT_ID/tables/$TABLE_ID/columns/$COLUMN_ID/add_name/" \
  --header "Authorization: Bearer $HDX_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{"name": "account_id"}'

After these calls, all three names (user_id, customer_id, account_id) remain queryable.

Verify aliases with DESCRIBE TABLE⚓︎

After renaming a column, use DESCRIBE TABLE to verify the aliases are configured correctly.

1

DESCRIBE TABLE myproject.sales;

Example output:

The ALIAS type indicates these are column aliases, and the default_expression shows which actual column they reference.

Where to use aliases⚓︎

Column aliases work with most SQL operations:

• Query clauses: Use aliases in SELECT, WHERE, JOIN, and GROUP BY clauses
• ClickHouse functions: All ClickHouse functions work with aliased column names
• Dictionary lookups: Dictionary functions like dictGet() work with aliases
• Summary tables: Existing summary tables continue working after renaming columns in the parent table
• Aggregate functions: Functions like SUM(), COUNT(), AVG() work with any alias

Considerations and limitations⚓︎

Some SQL operations aren't supported with aliases.

ALTER operations⚓︎

ALTER TABLE operations like UPDATE and DELETE only work with the actual column name, not the alias.

1
2
3

ALTER TABLE sales 
UPDATE customer_id = customer_id + 1000 
WHERE order_date > '2024-01-01';

1
2
3
4

ALTER TABLE sales
UPDATE user_id = user_id + 1000
WHERE order_date > '2024-01-01';
-- Error: Column user_id is updated but not requested to read

SELECT * queries⚓︎

SELECT * returns only the actual column names, not aliases. To include aliases in query results, explicitly name them in the SELECT clause.

1
2

-- Assuming customer_id is an alias for user_id
SELECT * FROM sales LIMIT 1;

1
2
3

SELECT customer_id, order_total, order_date
FROM sales
LIMIT 1;

Subqueries and CTEs⚓︎

Subqueries and Common Table Expressions (CTEs) don't preserve aliases. Aliases aren't available in the outer query unless specifically selected.

Subquery examples⚓︎

1
2

SELECT customer_id 
FROM (SELECT * FROM sales);

1
2
3

SELECT user_id 
FROM (SELECT * FROM sales);
-- Error: Missing columns: 'user_id'

Common Table Expression examples⚓︎

1
2

WITH orders AS (SELECT user_id FROM sales)
SELECT user_id FROM orders;

1
2
3

WITH orders AS (SELECT * FROM sales)
SELECT user_id FROM orders;
-- Error: Missing columns: 'user_id'

Column name uniqueness⚓︎

Multiple columns can't be renamed to the same name. The API validates and prevents duplicate column names within a table.