Query from an application

Run SQL over HTTPS with an Altertable SDK or HTTP client. You need lakehouse credentials for the environment that owns your catalogs.

For terminal queries, use the CLI. For all request fields, response formats, and errors, use the HTTP API reference.

1. Verify authentication

Set your credentials locally, then send a query that needs no existing table:

ALTERTABLE_USERNAME='YOUR_LAKEHOUSE_USERNAME'
ALTERTABLE_PASSWORD='YOUR_LAKEHOUSE_PASSWORD'
curl https://api.altertable.ai/query \
  --user "$ALTERTABLE_USERNAME:$ALTERTABLE_PASSWORD" \
  -H 'Content-Type: application/json' \
  -d '{"statement":"SELECT 1 AS connected"}'

Confirm that the response contains a connected column and a row with 1. If authentication fails, check the credentials and target environment before querying application data.

2. Query your data

Replace the example catalog and table with names from your environment. The SDK examples show client initialization and result handling:

cURL

Terminal

curl -X POST https://api.altertable.ai/query \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -d '{"statement": "SELECT * FROM my_catalog.main.events ORDER BY timestamp DESC LIMIT 100"}'

SDKs

JavaScript

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

16

17

18

19

20

21

22

23

24

import { AltertableLakehouseClient } from '@altertable/lakehouse';

const client = new AltertableLakehouseClient({
  username: 'YOUR_LAKEHOUSE_USERNAME',
  password: 'YOUR_LAKEHOUSE_PASSWORD',
});

const result = await client.queryAll({
  statement: `
    SELECT
      date_trunc('day', timestamp) AS day,
      event,
      COUNT(*)                     AS events,
      ROUND(AVG(value), 2)         AS avg_value
    FROM   my_catalog.main.events
    WHERE  timestamp >= NOW() - INTERVAL '30 days'
    GROUP  BY 1, 2
    ORDER  BY day DESC, events DESC
  `,
});

for (const row of result.rows) {
  console.log(row);
}

Use fully qualified table names and bound exploratory queries with LIMIT. In application code, store credentials in your runtime's secret configuration.

Use bind parameters for values supplied by users. Named parameters use $name; positional parameters use $1, $2, and so on. Send an object or array in params rather than interpolating values into SQL:

{
  "statement": "SELECT * FROM my_catalog.main.users WHERE id = $id",
  "params": { "id": 123 }
}

3. Consume results

The default HTTP response is a JSONL stream containing query metadata, a column-name array, and result rows. Process it line by line rather than parsing the whole response as one JSON document. An SDK can handle the stream for you.

If your consumer expects a standard format, request CSV, row-oriented JSONL, or Parquet. The response format reference defines the exact envelopes and options.

Tune execution when needed

• Choose compute for workload sizing and session constraints.
• Transpile SQL when porting queries from another dialect.
• Inspect or cancel a query through the query lifecycle endpoints.

Troubleshooting

• Unauthorized request: use lakehouse credentials from the intended environment.
• Missing table: qualify the table with its catalog and schema, then check catalog permissions.
• Unexpected response shape: check whether you requested the default envelope or a standard output format.
• No available Worker: inspect compute availability and retry with backoff. See compute sizing.