[do not merge] SQL GA

modules/reference/pages/sql/comment-support.adoc

@@ -0,0 +1,61 @@
+= Comment Support
+:description: Redpanda SQL fully supports comments in your queries.
+:page-topic-type: reference
+
+Redpanda SQL fully supports comments in your queries. Comments provide a way to add explanatory notes and improve the readability of queries, making it easier for developers and stakeholders to understand complex queries.
+
+There are two types of comments in Redpanda SQL: single-line and multi-line (block).
+
+== Single line comments
+
+A single-line comment in Redpanda SQL starts with two consecutive hyphens (--) and extends to the end of the line. Use these comments to annotate specific parts of a query with brief explanations or notes that help readers understand the query.
+
+=== Syntax
+
+[source,sql]
+----
+-- This is an example single line comment
+----
+
+== Multi-line (block) comments
+
+Redpanda SQL also supports multi-line comments, often referred to as block comments. These comments begin with `/*` and end with `*/`, allowing for multi-line explanations or temporarily disabling sections of the query.
+
+=== Syntax
+
+[source,sql]
+----
+/*
+This is an example multi-line comment.
+It can span multiple lines and is useful for providing detailed explanations.
+*/
+----
+
+== Comment placement
+
+In Redpanda SQL, single-line comments should always be placed at the end of the line they refer to, whereas multi-line comments can be positioned anywhere within the query.
+
+=== Comment on a single line
+
+[source,sql]
+----
+SELECT column1, column2 -- This is an example single line comment
+FROM table_name;
+----
+
+=== Comment on multiple lines
+
+[source,sql]
+----
+SELECT /* comment 1 */ column1, column2
+FROM table_name /* comment 2 */
+WHERE column3 = 42 /* comment 3 */ ;
+----
+
+== Best practices for commenting
+
+To maximize the benefits of comments in Redpanda SQL queries, follow these best practices:
+
+* Be concise. Write clear and concise comments that provide meaningful insights into the specific parts of the query.
+* Update comments during code changes. Whenever the query is modified, update the associated comments to reflect the changes accurately.
+* Avoid over-commenting. While comments are helpful, excessive commenting can clutter the code and reduce readability.

modules/reference/pages/sql/index.adoc

@@ -0,0 +1,12 @@
+= SQL Reference
+:description: This section provides information about the syntax and semantics of SQL queries, clauses, data types, and functions that Redpanda SQL supports.
+
+This section provides information about the syntax and semantics of SQL queries, clauses, data types, and functions that Redpanda SQL supports. The information in this section is divided into groups according to the kind of operation they perform as follows:
+
+* xref:reference:sql/sql-statements/index.adoc[SQL Statements]. Learn how to create a request for data or information from one or more database tables using supported statements.
+* xref:reference:sql/sql-clauses/index.adoc[SQL Clauses]. Learn how to write user-friendly queries and analyze data using different constraints and conditions.
+* xref:reference:sql/sql-data-types/index.adoc[SQL Data Types]. Learn how to implement supported data types to run your operations, such as text, timestamp, numeric, and many more.
+* xref:reference:sql/sql-functions/index.adoc[SQL Functions]. See how you can combine statements, data types, and other references into specific functions for particular tasks.
+* xref:reference:sql/schema.adoc[Schema]. Learn about a logical container that holds database objects and relationships of data in a database.
+* xref:reference:sql/comment-support.adoc[Comment Support]. Add comments in your queries for better documentation and collaboration.
+* xref:reference:sql/transactions.adoc[Transactions]. Learn more about managing your transactions.

modules/reference/pages/sql/redpanda-catalogs.adoc

@@ -0,0 +1,81 @@
+= Redpanda Catalogs
+:description: Redpanda catalogs are named connections that map Redpanda topics to queryable SQL tables.
+:page-topic-type: reference
+
+Redpanda catalogs are named connections that let you query Redpanda topics using standard SQL. The catalog model consists of three core concepts:
+
+* Catalogs: Named connections to a Redpanda cluster, created with xref:reference:sql/sql-statements/create-redpanda-catalog.adoc[CREATE REDPANDA CATALOG].
+* Tables: Redpanda topics mapped as queryable SQL tables using the `catalog_name\=>table_name` syntax, created with xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE].
+* Storage connections: Named connections to external object storage such as Amazon S3, created with xref:reference:sql/sql-statements/create-storage.adoc[CREATE STORAGE].
+
+NOTE: Redpanda SQL operates in read-only mode. Data mutation operations such as `INSERT`, `UPDATE`, and `DELETE` are not available. Data is ingested into Redpanda topics and made queryable through catalog mappings.
+
+== Typical workflow
+
+To query Redpanda topic data with SQL:
+
+. Create a catalog connection:
++
+[source,sql]
+----
+CREATE REDPANDA CATALOG my_catalog
+WITH (
+  initial_brokers = 'broker1:9092',
+  schema_registry_url = 'http://schema-registry:8081'
+);
+----
+
+. Map a topic as a table:
++
+[source,sql]
+----
+CREATE TABLE my_catalog=>user_events
+WITH (topic = 'user-events');
+----
+
+. Query the data:
++
+[source,sql]
+----
+SELECT * FROM my_catalog=>user_events LIMIT 10;
+----
+
+== Related statements
+
+[cols="<40%,<60%",options="header"]
+|===
+|Statement |Description
+
+|xref:reference:sql/sql-statements/create-redpanda-catalog.adoc[CREATE REDPANDA CATALOG]
+|Create a catalog connection to a Redpanda cluster.
+
+|xref:reference:sql/sql-statements/alter-redpanda-catalog.adoc[ALTER REDPANDA CATALOG]
+|Modify connection properties of an existing catalog.
+
+|xref:reference:sql/sql-statements/create-table.adoc[CREATE TABLE]
+|Map a Redpanda topic to a SQL table through a catalog.
+
+|xref:reference:sql/sql-statements/alter-table.adoc[ALTER TABLE]
+|Modify options of an existing catalog table.
+
+|xref:reference:sql/sql-statements/drop-table.adoc[DROP TABLE]
+|Remove a catalog table mapping.
+
+|xref:reference:sql/sql-statements/drop-redpanda-catalog.adoc[DROP REDPANDA CATALOG]
+|Remove a Redpanda catalog connection.
+
+|xref:reference:sql/sql-statements/drop-storage.adoc[DROP STORAGE]
+|Remove a named storage definition.
+
+|xref:reference:sql/sql-statements/show-tables.adoc[SHOW TABLES]
+|List tables within a catalog.
+
+|xref:reference:sql/sql-statements/describe.adoc[DESCRIBE]
+|Show details about a catalog or catalog table.
+
+|xref:reference:sql/sql-statements/create-storage.adoc[CREATE STORAGE]
+|Create a connection to external object storage.
+
+|xref:reference:sql/sql-statements/alter-storage.adoc[ALTER STORAGE]
+|Modify an existing storage connection.
+|===

modules/reference/pages/sql/schema.adoc

@@ -0,0 +1,228 @@
+= Schemas
+:description: Schemas are namespaces that organize tables and other database objects in Redpanda SQL.
+:page-topic-type: reference
+
+A schema is a namespace that groups related database objects, including tables, views, indexes, sequences, data types, operators, and functions. Schemas let you organize objects into logical groups so their names do not collide.
+
+Redpanda SQL supports multiple schemas in a single database. For example, in a database named `mydb`, you might define schemas such as `auth`, `model`, and `business`.
+
+== Default schema
+
+By default, Redpanda SQL uses the `public` schema. When you reference an unqualified table name, it is equivalent to `public.table_name`. The same rule applies to `CREATE`, `DROP`, and `SELECT` statements.
+
+== Syntax
+
+=== Create a schema
+
+[source,sql]
+----
+CREATE SCHEMA [IF NOT EXISTS] schema_name;
+----
+
+* `schema_name`: Name of the schema to create.
+* `IF NOT EXISTS`: Optional. Prevents an error if the schema already exists.
+
+=== Create a table in a schema
+
+[source,sql]
+----
+CREATE TABLE schema_name.table_name(
+...
+);
+----
+
+* `schema_name`: Name of an existing schema.
+* `table_name`: Name of the table to create.
+
+=== Query a table in a schema
+
+[source,sql]
+----
+SELECT * FROM schema_name.table_name;
+----
+
+* `schema_name`: Name of the schema.
+* `table_name`: Name of the table to query.
+
+=== Drop a schema
+
+To drop an empty schema:
+
+[source,sql]
+----
+DROP SCHEMA [IF EXISTS] schema_name;
+----
+
+* `schema_name`: Name of the schema to drop.
+* `IF EXISTS`: Optional. Prevents an error if the schema does not exist.
+
+To drop a schema that contains tables, use `CASCADE` to drop the schema and its contents:
+
+[source,sql]
+----
+DROP SCHEMA schema_name CASCADE;
+----
+
+== Examples
+
+=== Create a schema and table
+
+. Create a schema:
++
+[source,sql]
+----
+CREATE SCHEMA app_data;
+----
+
+. Create a table in the `app_data` schema and insert rows:
++
+[source,sql]
+----
+CREATE TABLE app_data.functions(
+  id int,
+  function_name text,
+  active bool
+);
+
+INSERT INTO app_data.functions(id, function_name, active)
+VALUES
+('1111', 'Numeric', 'TRUE'),
+('2222', 'Text', 'TRUE'),
+('3333', 'Timestamp', 'TRUE'),
+('4444', 'JSON', 'TRUE'),
+('5555', 'Boolean', 'TRUE');
+----
+
+. Verify the table contents:
++
+[source,sql]
+----
+SELECT * FROM app_data.functions;
+----
+
+. The query returns:
++
+[source,sql]
+----
++------+---------------+---------+
+| id   | function_name | active  |
++------+---------------+---------+
+| 1111 | Numeric       | t       |
+| 2222 | Text          | t       |
+| 3333 | Timestamp     | t       |
+| 4444 | JSON          | t       |
+| 5555 | Boolean       | t       |
++------+---------------+---------+
+----
+
+=== Use IF NOT EXISTS
+
+The `IF NOT EXISTS` option lets the `CREATE SCHEMA` query succeed without error when the schema already exists. The schema is not modified.
+
+==== Without IF NOT EXISTS
+
+. Create a schema:
++
+[source,sql]
+----
+CREATE SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+CREATE SCHEMA
+----
+
+. Run the same `CREATE SCHEMA` statement again. The query fails with an error:
++
+[source,sql]
+----
+CREATE SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+ERROR:  Schema: analytics already exists
+----
+
+==== With IF NOT EXISTS
+
+Run the same `CREATE SCHEMA` statement with `IF NOT EXISTS`. The query succeeds without error:
+
+[source,sql]
+----
+CREATE SCHEMA IF NOT EXISTS analytics;
+----
+
+[source,sql]
+----
+CREATE
+----
+
+=== Drop a schema
+
+To drop a schema and all its tables, use `CASCADE`:
+
+[source,sql]
+----
+DROP SCHEMA app_data CASCADE;
+----
+
+If the schema is empty, you can drop it without `CASCADE`:
+
+[source,sql]
+----
+DROP SCHEMA app_data;
+----
+
+=== Use IF EXISTS
+
+The `IF EXISTS` option lets the `DROP SCHEMA` query succeed without error when the schema does not exist.
+
+==== Without IF EXISTS
+
+. Drop a schema:
++
+[source,sql]
+----
+DROP SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+DROP
+----
+
+. Run the same `DROP SCHEMA` statement again. The query fails with an error:
++
+[source,sql]
+----
+DROP SCHEMA analytics;
+----
++
+The query returns:
++
+[source,sql]
+----
+ERROR:  schema "analytics" does not exist
+----
+
+==== With IF EXISTS
+
+Run the same `DROP SCHEMA` statement with `IF EXISTS`. The query succeeds without error:
+
+[source,sql]
+----
+DROP SCHEMA IF EXISTS analytics;
+----
+
+[source,sql]
+----
+DROP
+----