SQL: rpk byoc apply and data type limitations (#603)

* Rerun rpk byoc apply command, add replicas field to API call

* Data type limitations in Iceberg

* Minor edit

* Minor edit

* Apply suggestions from review

---------

Co-authored-by: Joyce Fee <102751339+Feediver1@users.noreply.github.com>

Author: kbatuigas

modules/sql/pages/get-started/deploy-sql-cluster.adoc

@@ -47,8 +47,6 @@ Cloud API::
 +
 --
 . Authenticate to the link:/api/doc/cloud-controlplane/topic/topic-cloud-api-overview[Cloud API]. For details, see link:/api/doc/cloud-controlplane/authentication[Authenticate to the Cloud API].
-// TODO: Is selecting capacity (currently node count, expected to change to RPUs)
-// available with this endpoint?
 . Make a link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[`POST /v1/clusters`] request with `rpsql.enabled` set to `true` in the cluster spec:
 +
 [,bash]
@@ -66,19 +64,22 @@ curl -X POST "https://api.redpanda.com/v1/clusters" \
       "throughput_tier": "<tier>",
       "resource_group_id": "<resource-group-id>",
       "rpsql": {
-        "enabled": true
+        "enabled": true,
+        "replicas": <n>
       }
     }
   }'
 ----
 +
-For the full request body and field reference, see the link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[Create Cluster API].
+For the full request body and field reference, see the link:/api/doc/cloud-controlplane/operation/operation-clusterservice_createcluster[Create Cluster API]. Use the `replicas` field to set the initial number of SQL compute nodes (minimum 1).
 . The request returns the ID of a long-running operation. Poll the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] endpoint until the operation completes.
 --
 =====
 
 === On an existing cluster
 
+NOTE: If your BYOC cluster on AWS was created before May 28, 2026, rerun `rpk cloud byoc aws apply --redpanda-id=<cluster-id>` to update the agent's IAM permissions before enabling Redpanda SQL.
+
 [tabs]
 =====
 Cloud Console::
@@ -102,7 +103,7 @@ Cloud API::
 curl -X PATCH "https://api.redpanda.com/v1/clusters/{cluster.id}" \
   -H "Authorization: Bearer $AUTH_TOKEN" \
   -H "Content-Type: application/json" \
-  -d '{"rpsql":{"enabled":true}}'
+  -d '{"rpsql":{"enabled":true,"replicas":<n>}}'
 ----
 +
 The request returns the ID of a long-running operation. Poll the link:/api/doc/cloud-controlplane/operation/operation-operationservice_getoperation[`GET /v1/operations/{operation.id}`] endpoint until the operation completes:

modules/sql/pages/get-started/redpanda-sql-vs-postgresql.adoc

@@ -121,6 +121,16 @@ SELECT ABS(-1.0);
 |working as expected
 |===
 
+== Data type limitations
+
+The following Iceberg column types have no valid Redpanda SQL type mapping and cause `CREATE TABLE` or `REFRESH` to fail:
+
+* `map`
+* `decimal` with precision greater than 18
+* nested `list` types
+
+For details, see xref:sql:query-data/query-iceberg-topics.adoc#iceberg-type-limitations[Iceberg type limitations].
+
 == Suggested reading
 
 * xref:sql:get-started/overview.adoc[Redpanda SQL Overview]

modules/sql/pages/query-data/query-iceberg-topics.adoc

@@ -2,7 +2,7 @@
 :description: Query the history of a Redpanda topic in Iceberg, and run a single SQL query that spans live records and historical Iceberg-committed records.
 :page-topic-type: how-to
 :personas: app_developer, data_engineer
-:learning-objective-1: Identify the storage and catalog objects Cloud sets up for querying Iceberg-enabled topics
+:learning-objective-1: Describe the storage and catalog objects that Redpanda Cloud configures for Iceberg-enabled topic queries
 :learning-objective-2: Query both the live records and the Iceberg-committed history of a topic in a single result
 :learning-objective-3: Handle schema differences between a Redpanda topic and its Iceberg table
 
@@ -110,6 +110,16 @@ Redpanda SQL handles this divergence by treating the topic's Schema Registry sub
 * If the Iceberg table is missing a column that the topic schema has, Redpanda SQL returns `NULL` for that column on Iceberg-side rows. This is common after adding a new column to the topic schema, since earlier records already in Iceberg don't have it.
 * If the Iceberg table has columns the topic schema does not, the query fails at planning time with the error `Kafka schema must be a name-superset of Iceberg schema`. This happens when a column is removed from the topic's Schema Registry subject. To resolve, re-add the column to the topic's Schema Registry subject so the topic schema covers every column present in the Iceberg table.
 
+== Iceberg type limitations
+
+When Redpanda SQL maps an Iceberg-enabled topic as a SQL table, it reads the Iceberg schema and converts each column type to a SQL type. The following column types currently have no valid Redpanda SQL type mapping and cause `CREATE TABLE` or `REFRESH` to fail with an error.
+
+* Columns of type `map` are not supported, whether at the top level or nested inside a struct.
+* `decimal` columns with precision greater than 18 cannot be mapped. Iceberg allows decimal precision up to 38, but Redpanda SQL stores decimals as 64-bit integers with a maximum precision of 18. Decimals with precision 18 or lower work as expected.
+* A `list` whose element type is also a `list` is not supported. Simple lists (list of primitives or list of structs) work as expected.
+
+These schema-mapping constraints apply only to columns in the Iceberg schema. Columns sourced from live topic records are not subject to these type restrictions.
+
 == Next steps
 
 * xref:sql:query-data/query-streaming-topics.adoc[Query streaming topics]: the streaming-only query path, without the Iceberg history layer.