Publish and maintain a table

How-to guideApplies to: Unified engine deployments

Use SQL over HTTP to create a private Iceberg table, publish inline rows, and inspect it. Then use the supported maintenance statements for that table.

Before you start

Choose a writable Iceberg catalog and an unused namespace. This example uses http_docs_01; change it everywhere if it already exists. Set the catalog name under Example values before sending the USE statement.

Publish and inspect a private Iceberg table

Send each statement separately in one session. Wait for success before its dependent step. Cleanup is explicit.

Placeholder	Value
`{{catalog_name}}`	Your environment value.
`{{statement_0}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_1}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_2}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_3}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_4}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_5}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_6}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_7}}`	A new UUID for this request; reuse it when recovering the same submission.
`{{statement_8}}`	A new UUID for this request; reuse it when recovering the same submission.

Replace the placeholders in your client. Keep returned IDs for later requests. Paths below use the native API prefix; adjust it for your deployment.

1. Open a session

POST /api/v1/sessions
Host: <ENGINE_HOST>

From the response, keep session_id from /session_id. Endpoint reference.

2. Choose the writable catalog

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_0}}",
  "sql": "USE CATALOG {{catalog_name}}",
  "source": "external"
}

Endpoint reference.

3. Follow: Choose the writable catalog

GET /api/v1/sessions/{{session_id}}/operations/{{statement_0}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

4. Create the private namespace

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_1}}",
  "sql": "CREATE NAMESPACE http_docs_01",
  "source": "external"
}

Endpoint reference.

5. Follow: Create the private namespace

GET /api/v1/sessions/{{session_id}}/operations/{{statement_1}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

6. Create a format-v2 table

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_2}}",
  "sql": "CREATE TABLE http_docs_01.category_sales (category STRING, sales BIGINT) USING iceberg TBLPROPERTIES ('format-version' = '2')",
  "source": "external"
}

Endpoint reference.

7. Follow: Create a format-v2 table

GET /api/v1/sessions/{{session_id}}/operations/{{statement_2}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

8. Publish category totals

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_3}}",
  "sql": "INSERT INTO http_docs_01.category_sales WITH orders(id, category, region, amount) AS (VALUES (1, 'Books', 'North', 20), (2, 'Games', 'South', 30), (3, 'Games', 'North', 15), (4, 'Books', 'North', 40), (5, 'Garden', 'South', 25), (6, 'Garden', 'North', 10)) SELECT category, SUM(amount) AS sales FROM orders GROUP BY category ORDER BY category",
  "source": "external"
}

Endpoint reference.

9. Follow: Publish category totals

GET /api/v1/sessions/{{session_id}}/operations/{{statement_3}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

10. Read published totals

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_4}}",
  "sql": "SELECT category, sales FROM http_docs_01.category_sales ORDER BY category",
  "source": "external"
}

Endpoint reference.

11. Follow: Read published totals

GET /api/v1/sessions/{{session_id}}/operations/{{statement_4}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

12. Read: Read published totals

GET /api/v1/sessions/{{session_id}}/operations/{{statement_4}}/results?limit=1
Host: <ENGINE_HOST>

Endpoint reference.

13. Compact eligible files

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_5}}",
  "sql": "CALL system.rewrite_data_files(table => 'http_docs_01.category_sales', strategy => 'binpack', target_file_size_bytes => 1048576, max_group_size_bytes => 8388608, min_input_files => 2)",
  "source": "external"
}

Endpoint reference.

14. Follow: Compact eligible files

GET /api/v1/sessions/{{session_id}}/operations/{{statement_5}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

15. Read: Compact eligible files

GET /api/v1/sessions/{{session_id}}/operations/{{statement_5}}/results?limit=1
Host: <ENGINE_HOST>

Endpoint reference.

16. Verify totals after maintenance

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_6}}",
  "sql": "SELECT COUNT(*) AS categories, SUM(sales) AS sales FROM http_docs_01.category_sales",
  "source": "external"
}

Endpoint reference.

17. Follow: Verify totals after maintenance

GET /api/v1/sessions/{{session_id}}/operations/{{statement_6}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

18. Read: Verify totals after maintenance

GET /api/v1/sessions/{{session_id}}/operations/{{statement_6}}/results?limit=1
Host: <ENGINE_HOST>

Endpoint reference.

19. Clean up the practice table

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_7}}",
  "sql": "DROP TABLE http_docs_01.category_sales",
  "source": "external"
}

Endpoint reference.

20. Follow: Clean up the practice table

GET /api/v1/sessions/{{session_id}}/operations/{{statement_7}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

21. Clean up the empty namespace

POST /api/v1/sessions/{{session_id}}/operations
Host: <ENGINE_HOST>
Content-Type: application/json

{
  "operation_id": "{{statement_8}}",
  "sql": "DROP NAMESPACE http_docs_01",
  "source": "external"
}

Endpoint reference.

22. Follow: Clean up the empty namespace

GET /api/v1/sessions/{{session_id}}/operations/{{statement_8}}
Host: <ENGINE_HOST>

Repeat this read until /status reaches a terminal state: Succeeded, Failed, Cancelled, OutcomeUnknown, Skipped. Endpoint reference.

23. Close the session

DELETE /api/v1/sessions/{{session_id}}
Host: <ENGINE_HOST>

Endpoint reference. Expect three category rows with totals Books 60, Games 45, and Garden 35. Inspect execution and commit evidence, then read the destination through the SELECT step.

Maintain the output

Use Maintenance for the exact supported statement and parameters. Submit each statement through a separate operation in the same session. Follow execution before assuming a table rewrite committed. A successful request is not a transaction across the entire example. One small write can leave no eligible files to compact; a no-op maintenance result is valid. The final check should still show three categories and sales of 140.

Clean up

After execution finishes, use the example’s explicit DROP steps for only the private table and namespace created here. Cleanup is never automatic. Close the session at the end. Keep the table instead if you intend to inspect its metadata or run maintenance exercises.

Transformation Engine

Learn Laminar

Workloads

SQL reference

HTTP API

Recipes

Operations

Publish and maintain a table

Before you start

Publish and inspect a private Iceberg table

1. Open a session

2. Choose the writable catalog

3. Follow: Choose the writable catalog

4. Create the private namespace

5. Follow: Create the private namespace

6. Create a format-v2 table

7. Follow: Create a format-v2 table

8. Publish category totals

9. Follow: Publish category totals

10. Read published totals

11. Follow: Read published totals

12. Read: Read published totals

13. Compact eligible files

14. Follow: Compact eligible files

15. Read: Compact eligible files

16. Verify totals after maintenance

17. Follow: Verify totals after maintenance

18. Read: Verify totals after maintenance

19. Clean up the practice table

20. Follow: Clean up the practice table

21. Clean up the empty namespace

22. Follow: Clean up the empty namespace

23. Close the session

Maintain the output

Clean up

​Before you start

​Publish and inspect a private Iceberg table

​1. Open a session

​2. Choose the writable catalog

​3. Follow: Choose the writable catalog

​4. Create the private namespace

​5. Follow: Create the private namespace

​6. Create a format-v2 table

​7. Follow: Create a format-v2 table

​8. Publish category totals

​9. Follow: Publish category totals

​10. Read published totals

​11. Follow: Read published totals

​12. Read: Read published totals

​13. Compact eligible files

​14. Follow: Compact eligible files

​15. Read: Compact eligible files

​16. Verify totals after maintenance

​17. Follow: Verify totals after maintenance

​18. Read: Verify totals after maintenance

​19. Clean up the practice table

​20. Follow: Clean up the practice table

​21. Clean up the empty namespace

​22. Follow: Clean up the empty namespace

​23. Close the session

​Maintain the output

​Clean up

Before you start

Publish and inspect a private Iceberg table

1. Open a session

2. Choose the writable catalog

3. Follow: Choose the writable catalog

4. Create the private namespace

5. Follow: Create the private namespace

6. Create a format-v2 table

7. Follow: Create a format-v2 table

8. Publish category totals

9. Follow: Publish category totals

10. Read published totals

11. Follow: Read published totals

12. Read: Read published totals

13. Compact eligible files

14. Follow: Compact eligible files

15. Read: Compact eligible files

16. Verify totals after maintenance

17. Follow: Verify totals after maintenance

18. Read: Verify totals after maintenance

19. Clean up the practice table

20. Follow: Clean up the practice table

21. Clean up the empty namespace

22. Follow: Clean up the empty namespace

23. Close the session

Maintain the output

Clean up