Load records and files

Use append for new JSON records, upload for files, and upsert for rows that should update existing primary keys. You need a writable catalog and lakehouse credentials.

The steps below use the CLI. For application code, use the SDK or HTTP examples in step 2. Exact limits and request fields live in the HTTP API reference.

Steps

1. Choose an ingest mode

Use bucket synchronization for scheduled file imports from object storage.

2. Append JSON records

From the CLI, append a test record to a new table. Replace my_catalog with your destination catalog:

altertable append '{"event":"onboarding_test","source":"cli"}' --to my_catalog.main.events

Append acknowledges accepted records before insertion finishes. Allow a few seconds, then query the table to verify that they arrived. An acknowledgement alone does not verify insertion.

If a row fails insertion after retries, Altertable stores it in altertable.main.quarantined_appends. Inspect the error and original payload before correcting and resending it.

Append from application code

Use your lakehouse credentials to authenticate HTTP requests or initialize an SDK:

cURL

Terminal

curl -X POST "https://api.altertable.ai/append?catalog=my_catalog&schema=main&table=events" \
  -H "Authorization: Basic $ALTERTABLE_BASIC_AUTH_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"timestamp":"2026-01-01","event":"click","value":42}'

SDKs

JavaScript

1

2

3

4

5

6

7

8

9

10

11

12

13

14

15

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

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

await client.append({
  catalog: 'my_catalog',
  schema: 'main',
  table: 'events',
  body: {
    Single: { timestamp: '2026-01-01', event: 'click', value: 42 },
  },
});

3. Upload files

To create a new table from a file:

altertable upload users.csv --to my_catalog.main.users --mode create

To add file rows to an existing table, use --mode append. Use --mode overwrite only when you intend to replace the table with the uploaded data. See upload behavior for supported formats and limits.

4. Upsert by primary key

If users.csv contains a stable id column, update matching rows and insert new ones with:

altertable upsert users.csv --to my_catalog.main.users --key id

Check that the key is populated and identifies the rows you intend to update. See upsert behavior for HTTP requests and supported formats.

Verification

After uploading or upserting the file, inspect the destination:

altertable query "SELECT * FROM my_catalog.main.users LIMIT 10"

Compare the returned values with the file, including any rows you expected to update. For append, query its destination table after processing has completed.

Troubleshooting

• Unauthorized request: check the destination environment and lakehouse credentials.
• A new append row is missing: wait for processing, then inspect altertable.main.quarantined_appends for failures.
• The file exceeds the request limit: consult the endpoint limits and split the data when needed.
• Upsert changes unexpected rows: check the primary key column and its values before sending another request.