Migrate SQL docs

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. These comments are used to annotate specific parts of a query, providing brief explanations or notes to assist in understanding 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,75 @@
+= 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 enable you to 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.adoc[DROP]
+|Remove catalog tables, catalogs, or storage connections.
+
+|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,245 @@
+= Schema Definition
+:description: Have you ever wondered how to work with your fellows in one database without interfering with each other? Is it possible to organize the database obje
+:page-topic-type: reference
+
+== What is a schema?
+
+Have you ever wondered how to work with your fellows in one database without interfering with each other? Is it possible to organize the database objects into logical groups which do not collide with the other objects’ names?
+
+A schema addresses these needs:
+
+A schema is a collection of tables. A schema also contains views, indexes, sequences, data types, operators, and functions. Redpanda SQL supports multiple schemas. For example, you can have a database named `oxla` and have multiple schemas based on your needs, like `auth`, `model`, `business`, etc.
+
+== Default schema in Redpanda SQL
+
+By default, the `public` schema is used in Redpanda SQL. When unqualified `table_name` is used, that `table_name` is equivalent to `public.table_name`. It also applies to `CREATE`, `DROP`, and `SELECT TABLE` statements.
+
+[NOTE]
+====
+Furthermore, you can create multiple schemas per your needs.
+====
+
+== Schema usage scenarios
+
+=== Create a schema
+
+The basic syntax of creating a schema is as follows:
+
+[source,sql]
+----
+CREATE SCHEMA [IF NOT EXISTS] schema_name;
+----
+
+* `schema_name` is the schema name you are going to create.
+* `IF NOT EXISTS` is an optional parameter to avoid errors if the schema already exists.
+
+=== Create a table in schema
+
+The syntax to create a table in a specified schema is as follows:
+
+[source,sql]
+----
+CREATE TABLE schema_name.table_name(
+...
+);
+----
+
+* `schema_name` is the schema that you have created.
+* `table_name` is the table name you are going to create.
+
+=== Select a table in schema
+
+After creating the table and inserting some data, display all rows with the syntax below:
+
+[source,sql]
+----
+SELECT * FROM schema_name.table_name;
+----
+
+* `schema_name` is the name of the schema.
+* `table_name` is the name of the table you want to display.
+
+=== Drop the schema
+
+Option 1: To drop an empty schema where no objects remain in it, use the command below:
+
+[source,sql]
+----
+DROP SCHEMA [IF EXISTS] schema_name;
+----
+
+* `schema_name` is the schema name you are going to create.
+* `IF EXISTS` is an optional parameter to avoid errors if the schema does not exist.
+
+Option 2: Tables reside in a schema, so it is impossible to drop a schema without also dropping the tables. With the command below, you will also drop the schema with the tables.
+
+[source,sql]
+----
+DROP SCHEMA schema_name CASCADE;
+----
+
+== Examples
+
+=== Create schema
+
+. First, connect to Redpanda SQL and create a schema as shown below:
++
+[source,sql]
+----
+CREATE SCHEMA oxlarefs;
+----
+
+. Next, create a table in the above schema with the following details:
++
+[source,sql]
+----
+CREATE TABLE oxlarefs.functions(
+  id int,
+  function_name text,
+  active bool
+);
+
+INSERT INTO oxlarefs.functions(id, function_name, active)
+VALUES
+('1111', 'Numeric', 'TRUE'),
+('2222', 'Text', 'TRUE'),
+('3333', 'Timestamp', 'TRUE'),
+('4444', 'JSON', 'TRUE'),
+('5555', 'Boolean', 'TRUE');
+----
+
+. You can verify and show the table made with the command below:
++
+[source,sql]
+----
+SELECT * FROM oxlarefs.functions;
+----
+
+. You will get the following result:
++
+[source,sql]
+----
++------+---------------+---------+
+| id   | function_name | active  |
++------+---------------+---------+
+| 1111 | Numeric       | t       |
+| 2222 | Text          | t       |
+| 3333 | Timestamp     | t       |
+| 4444 | JSON          | t       |
+| 5555 | Boolean       | t       |
++------+---------------+---------+
+----
+
+=== Create schema using IF NOT EXISTS
+
+To avoid errors when the schema already exists, use the `IF NOT EXISTS` option. Here is how it works:
+
+==== Example without IF NOT EXISTS
+
+. First, create the schema without using the `IF NOT EXISTS` option.
++
+[source,sql]
+----
+CREATE SCHEMA oxladb;
+----
++
+Output:
++
+[source,sql]
+----
+CREATE SCHEMA
+----
+
+. If you attempt to create the schema again without using `IF NOT EXISTS`, it will result in an error.
++
+[source,sql]
+----
+CREATE SCHEMA oxladb;
+----
++
+Output:
++
+[source,sql]
+----
+ERROR:  Schema: oxladb already exists
+----
+
+==== Example with IF NOT EXISTS
+
+Now, create the schema using the `IF NOT EXISTS` option to avoid the error.
+
+[source,sql]
+----
+CREATE SCHEMA IF NOT EXISTS oxladb;
+----
+
+Using `IF NOT EXISTS` allows the query to create a schema even if it already exists.
+
+[source,sql]
+----
+CREATE
+----
+
+=== Drop schema
+
+Use the command below to delete the schema and also the tables in it.
+
+[source,sql]
+----
+DROP SCHEMA oxlarefs CASCADE;
+----
+
+Another case is if there is no table or object created inside the schema, you can use the following command to drop the schema.
+
+[source,sql]
+----
+DROP SCHEMA oxlarefs;
+----
+
+=== Drop schema using IF EXISTS
+
+==== Example without IF EXISTS
+
+. First, drop the schema without using the `IF EXISTS` option.
++
+[source,sql]
+----
+DROP SCHEMA oxladb;
+----
++
+Output:
++
+[source,sql]
+----
+DROP
+----
+
+. If you attempt to drop the schema again without using `IF EXISTS`, it will result in an error.
++
+[source,sql]
+----
+DROP SCHEMA oxladb;
+----
++
+Output:
++
+[source,sql]
+----
+ERROR:  schema "oxladb" does not exist
+----
+
+==== Example with IF EXISTS
+
+Now, drop the schema using the `IF EXISTS` option.
+
+[source,sql]
+----
+DROP SCHEMA IF EXISTS oxladb;
+----
+
+Using `IF` EXISTS allows the query to succeed even if the schema does not exist.
+
+[source,sql]
+----
+DROP
+----