Conversation
|
Important Review skippedAuto reviews are disabled on base/target branches other than the default branch. Please check the settings in the CodeRabbit UI or the ⚙️ Run configurationConfiguration used: Organization UI Review profile: CHILL Plan: Pro Run ID: You can disable this status message by setting the Use the checkbox below for a quick retry:
✨ Finishing Touches🧪 Generate unit tests (beta)
Comment |
✅ Deploy Preview for rp-cloud ready!
To edit notification comments on pull requests, go to your Netlify project configuration. |
kbatuigas
force-pushed
the
DOC-1984-convert-and-migrate-existing-oxla-docs-to-asciidoc
branch
from
7a76f8f to
a95a3ed
Compare
|
Overall review feedback:
Content gaps:
I have also created a patch for the original Oxla docs ('oxla-docs' repository) that includes all the necessary changes proposal. It's in the attachment and can be used as a reference or can be applied on the original 'oxla-docs' main branch and a new migration patch for cloud-docs can be derived from it. 0001-W.I.P.-Docs-updates-needed-due-to-changes-since-the-.patch |
| @@ -0,0 +1,19 @@ | |||
| = SQL STATEMENTS | |||
There was a problem hiding this comment.
This overview is incomplete. The following statements are available but not listed:
ALTER TABLE
CREATE REDPANDA CATALOG
ALTER REDPANDA CATALOG
CREATE STORAGE
ALTER STORAGE
SHOW EXECS
GENERATE_SERIES
Also, the description should note that Redpanda SQL operates in read-only mode - this explains why INSERT INTO, COPY FROM, UPDATE, and DELETE are absent.
| @@ -0,0 +1,41 @@ | |||
| = SHOW NODES | |||
There was a problem hiding this comment.
Consider also mentioning system.queries and system.execs as related system virtual tables, or linking to a dedicated System Virtual Tables page (to be created - see overall review)
There was a problem hiding this comment.
Added note and TODO for system virtual tables
| @@ -0,0 +1,74 @@ | |||
| = DROP | |||
There was a problem hiding this comment.
DROP STORAGE is documented here, but there's no corresponding CREATE STORAGE page. Similarly, DROP REDPANDA CATALOG is here but CREATE REDPANDA CATALOG is missing. Users will find it confusing to see how to drop objects they can't find documentation for creating
|
|
||
| The `CREATE TABLE` statement maps a Redpanda topic to a SQL table through a catalog. After creating the table, you can query topic data using standard SQL. | ||
|
|
||
| NOTE: This statement requires an existing Redpanda catalog. Regular `CREATE TABLE` for user-defined tables is not supported in Redpanda SQL. |
There was a problem hiding this comment.
The note says "Regular CREATE TABLE for user-defined tables is not supported in Redpanda SQL", which is good, but this page would benefit from a "See also" link to a CREATE REDPANDA CATALOG page, since creating a catalog is a prerequisite. Currently that CREATE REDPANDA CATALOG page doesn't exist in this PR
|
@wkozlowski-oxla Since we are only including changes to existing pages that were migrated from oxla-docs, I think this PR is actually complete. The next step is to open a separate PR for changes that require creating brand new pages: Conceptual: Redpanda Catalog overview (^ does not include other doc requests tracked in https://redpandadata.atlassian.net/browse/DOC-1981) |
There was a problem hiding this comment.
- In the beginning, there is compression mentioned, which I think pertains to the Oxla storage compression, but the Oxla storage/ingestion is not supported/disabled.
- sql/connect-to-sql/language-clients/psycopg2/#supported-features: insert update delete not supported. A lot of examples assume it is, but we (at least initially) disable such operations.
- sql/connect-to-sql/language-clients/java-jdbc/#unsupported-functions-and-structures:
(issues after cancel). I'm not sure we should place the reasons why those functions are not supported. Especially when those stem from missing Oxla features/problems. - sql/connect-to-sql/language-clients/php-pdo/#unsupported-functions-and-structures: DELETE/UPDATE mentioned, which are disabled.
- reference/sql/sql-statements/select/#examples: INSERT INTO mentioned. In fact, we cannot create tables without specifying the external catalog. More like and explanation how query work instead of what's supported in redpanda sql
- dubious Tip: table duplication should result in an error. This Tip suggests, that creating a table with the same name will overwrite the existing table.
- reference/sql/sql-clauses/from/:
SELECTstatementclumped. - reference/sql/sql-clauses/from/join/: Venn diagrams with JOIN types are missing.
- reference/sql/sql-clauses/from/groupby/: spaces between aggregation function name and parens. Inconsistent with the rest.
- reference/sql/sql-clauses/having/#having-clause-with-count-function: in the example, there is
HAVING(score_stat = 'PASSED) > 2'. It's simply not true. It will count all non-NULL rows no matter what the value in thescore_statcolumn is. - reference/sql/sql-clauses/order-by/#syntax: Oxla also supports NULLS FIRST/NULLS LAST.
- reference/sql/sql-clauses/order-by/#use-order-by-with-interval-data-type: wrong interval sorting examples. Oxla and Postgres work correct. The Intervals are sorted by the total duration, not hierarchically by months, days, and microseconds.
- reference/sql/sql-clauses/offset/: There are LIMIT + OFFSET examples first, and then OFFSET is introduced
- reference/sql/sql-clauses/set-operations/except/#example: "The result will include the names of employees who were present in 2021 but are not present in 2022:"? This sentence is unrelated to the examples above and below.
- reference/sql/sql-clauses/set-operations/union/#union: the second part of the tip (2.) for the UNIONs applies to INTERSECT/EXCEPT too.
- reference/sql/sql-clauses/over-window/#syntax-2: Actually, both ROWS and RANGE frames are supported. Only GROUPS is not supported.
- reference/sql/sql-data-types/: there are also GEOMETRY and GEOGRAPHY types, although these are quite uncommon.
<=in code blocks is displayed as a 'left arrow', instead of a literal <= operator.- reference/sql/sql-data-types/data-type-operators/: This list is really non-exhaustive
- reference/sql/sql-data-types/timestamp-with-time-zone/: Weird formatting for timestamp with time zone
- reference/sql/sql-data-types/date/#structure: Should we mention the internal memory representation of the DATE type? I think it doesn't matter for the end user, and can potentially change in the future.
- reference/sql/sql-data-types/interval/: Interval values are tricky. For arithmetic operations, it's assumed, that 1 month = 30 days, 1 day = 24h. However, adding 30 days to a timestamp is not always equivalent of adding a 1 month, because months have different durations. Worth adding a "Note" there.
- reference/sql/sql-data-types/bool/:
Bool is stored as a bitmap in u64 values.<- implementation detail. Not sure it should be exposed in the documentation. - reference/sql/sql-functions/math-functions/: BITWISE SHIFT LEFT/RIGHT functions do not exist. only << and >> operators do.
- System Catalogs are not catalogs. The list of pg_* tables is not exhaustive: missing: pg_language, pg_authid, pg_policy, pg_inherits, pg_am, pg_proc, pg_statistic_ext, pg_auth_members, pg_enum, pg_proc_function_overload, pg_publication_namespace, pg_tablespace, pg_aggregate, pg_shadow, pg_database, pg_roles, pg_publication, pg_user, pg_publication_rel, pg_range
| +--------------+--------------+ | ||
| | passed_count | subject | | ||
| +--------------+--------------+ | ||
| | 4 | Math | | ||
| | 3 | Biology | | ||
| +--------------+--------------+ |
There was a problem hiding this comment.
Now since the query changed, the output changed too. This is the output of the query above:
passed_count | subject
--------------+---------
6 | Math
4 | Art
4 | Biology
There was a problem hiding this comment.
Thanks for flagging @Greketrotny , I get a different result actually
+--------------+---------+
| passed_count | subject |
+--------------+---------+
| 3 | Math |
+--------------+---------+
Does that look right to you?
kbatuigas
force-pushed
the
DOC-1984-convert-and-migrate-existing-oxla-docs-to-asciidoc
branch
from
f3d1086 to
562bdc1
Compare
kbatuigas
force-pushed
the
DOC-1984-convert-and-migrate-existing-oxla-docs-to-asciidoc
branch
from
2511239 to
9a365e6
Compare
| ); | ||
| ---- | ||
|
|
||
| [WARNING] |
There was a problem hiding this comment.
@kbatuigas Are these all really warnings? Or should we change the warnings on this page to important admonitions?
| @@ -0,0 +1,62 @@ | |||
| = What is Redpanda SQL | |||
| :description: Redpanda SQL is a column-oriented OLAP query engine built into Redpanda Cloud BYOC that lets you query Kafka topics using standard SQL. | |||
There was a problem hiding this comment.
@kbatuigas Instead of saying it's built into Redpanda Cloud BYOC here (+ other places), should we put an admonition at the top of the page similar to this that says it's available for BYOC?
| :description: Redpanda SQL is a column-oriented OLAP query engine built into Redpanda Cloud BYOC that lets you query Kafka topics using standard SQL. | ||
| :page-topic-type: concept | ||
|
|
||
| // TODO (REWRITE): This page needs BYOC framing. Frame Redpanda SQL as a Kafka query engine |
There was a problem hiding this comment.
This page already has a TODO (REWRITE) marker on lines 5-6 flagging the need for BYOC framing — Redpanda SQL is read-only (no DDL/DML), not a standalone database, and self-hosting framing should be removed or reframed.
Several prose-level findings I came across during the Person 4 review overlap with content the BYOC rewrite is likely to restructure or delete:
- Line 12: passive
data is ingested into Redpanda topics and made available for SQL queries - Line 22: passive
Columnar storage … is designed for analytical workloads, allowing for faster scans - Line 30:
Redpanda SQL is distributed, meaning it can run across multiple CPUs (nodes) in parallel - Line 32: passive
Execution strategies are selected at runtime based on workload characteristics - Line 36: colloquial
under the hood - Line 56: colloquial
This principle is baked into how it is designed and built. - Lines 50-62: the entire "Why use Redpanda SQL" section reads as marketing-adjacent framing
Recommendation: defer prose-level QA on this page until after the BYOC rewrite, then run docs-team-standards review against the rewritten content. Fixing voice on lines that the rewrite will replace is wasted effort, and locking in stylistic choices on content that's about to change risks creating the wrong kind of friction for the rewriter.
| System catalogs (`pg_*` tables) are unrelated to xref:reference:sql/redpanda-catalogs.adoc[Redpanda catalogs]. System catalogs provide PostgreSQL-compatible database metadata. Redpanda catalogs are named connections that map Redpanda topics to SQL tables. | ||
| ==== | ||
|
|
||
| The following system catalog tables are available in Redpanda SQL: |
There was a problem hiding this comment.
Across the 18 catalog pages in system-catalogs/catalogs/, an identical NOTE appears verbatim:
[NOTE]
====
This table is designed for compatibility with tools that require PostgreSQL system tables, so it mostly has dummy data. Not all columns in `pg_X` are applicable to every type of relation.
====
(Files: pg_attrdef, pg_attribute, pg_authid, pg_class, pg_constraint, pg_database, pg_depend, pg_description, pg_index, pg_language, pg_namespace, pg_proc, pg_roles, pg_settings, pg_shadow, pg_statio_user_tables, pg_type, pg_user.)
Something to consider: extract into a single shared partial — e.g. modules/reference/partials/sql/system-catalogs/dummy-data-disclaimer.adoc — and replace each occurrence with include::reference:partial$sql/system-catalogs/dummy-data-disclaimer.adoc[]. This matches the pattern we already use elsewhere in the repo (property docs, etc.) and keeps the disclaimer single-sourced if the wording ever changes.
|
Cross-cutting question on PostgreSQL external links across this PR (Person 4 bucket): The 18 system-catalog pages each link to Plus,
The Question for Eng / @kbatuigas: which PG version does Redpanda SQL target for compatibility? If it's pinned (for example, PG 15), I'd suggest swapping |
|
|
||
| [source,php] | ||
| ---- | ||
| conn = new PDO( |
There was a problem hiding this comment.
Flagging for the Oxla SME pass listed in the PR description ("Names and identifiers"):
The connection-string example here uses Oxla-named placeholders and a literal dbname=oxla:
conn = new PDO(
"pgsql:host={oxla_host};port={oxla_port};dbname=oxla",
{oxla_user},
{oxla_password},
...Should be updated alongside the other Oxla identifier replacements. Outside the doc-team review scope, just making sure these specific lines aren't missed.
| ---- | ||
| docker run --rm -it -p 5432:5432 public.ecr.aws/oxla/release:latest | ||
| ---- | ||
|
|
There was a problem hiding this comment.
Flagging for the Oxla SME pass listed in the PR description:
This Docker run example uses the public Oxla ECR image:
docker run --rm -it -p 5432:5432 public.ecr.aws/oxla/release:latestThe connect() call further down (lines 59-62) also still uses oxla_node_1 / oxla / oxla as the dbname, user, and password literals. Outside the doc-team review scope, but flagging these specific lines so they aren't missed during the SME pass.
| @@ -0,0 +1,105 @@ | |||
| = LENGTH | |||
| :description: The LENGTH() function is used to find the length of a string, i.e., the number of characters in a given string. | |||
There was a problem hiding this comment.
| :description: The LENGTH() function is used to find the length of a string, i.e., the number of characters in a given string. | |
| :description: Use the LENGTH() function to find the length of a string (for example, the number of characters in a given string). |
| :description: The LENGTH() function is used to find the length of a string, i.e., the number of characters in a given string. | ||
| :page-topic-type: reference | ||
|
|
||
| The `LENGTH()` function is used to find the length of a string, i.e., the number of characters in a given string. It accepts a string as a parameter. The syntax of the length function is as follows: |
There was a problem hiding this comment.
| The `LENGTH()` function is used to find the length of a string, i.e., the number of characters in a given string. It accepts a string as a parameter. The syntax of the length function is as follows: | |
| Use the `LENGTH()` function to find the length of a string(for example, the number of characters in a given string). It accepts a string as a parameter. The syntax of the length function is: |
|
|
||
| *Special cases:* | ||
|
|
||
| * If a null value is passed in the function, i.e., `LENGTH(NULL)`, it returns `NULL`. |
There was a problem hiding this comment.
| * If a null value is passed in the function, i.e., `LENGTH(NULL)`, it returns `NULL`. | |
| * If a null value is passed in the function. (For example, `LENGTH(NULL)`, it returns `NULL`). |
| @@ -0,0 +1,107 @@ | |||
| = ABS | |||
| :description: The ABS() function returns an absolute number, i.e., the positive value of a number. | |||
There was a problem hiding this comment.
| :description: The ABS() function returns an absolute number, i.e., the positive value of a number. | |
| :description: The ABS() function returns an absolute number (for example, the positive value of a number). |
| :description: The ABS() function returns an absolute number, i.e., the positive value of a number. | ||
| :page-topic-type: reference | ||
|
|
||
| The `ABS()` function returns an absolute number, i.e., the positive value of a number. The data type of the returned value will depend on the data type of the value passed to the `ABS()` function. |
There was a problem hiding this comment.
| The `ABS()` function returns an absolute number, i.e., the positive value of a number. The data type of the returned value will depend on the data type of the value passed to the `ABS()` function. | |
| The `ABS()` function returns an absolute number (for example, the positive value of a number). The data type of the returned value will depend on the data type of the value passed to the `ABS()` function. |
|
|
||
| * All text inside double quote `"\{text}"` will not be considered a pattern | ||
| * The quote character (`"`) will not appear in the result string | ||
| * Any text that is not a template pattern is copied verbatim i.e. preserved in the result string |
There was a problem hiding this comment.
| * Any text that is not a template pattern is copied verbatim i.e. preserved in the result string | |
| * Any text that is not a template pattern is copied verbatim (for example, preserved in the result string) |
|
|
||
| === Interval overflow restrictions | ||
|
|
||
| Interval overflow occurs when an operation involving interval values exceeds the maximum limits of the interval data type, resulting in an error or unexpected behavior. This can happen when adding, subtracting or multiplying interval values that lead to a representation that goes beyond the allowable range for any of its components i.e. years, months, days, hours, minutes and seconds. When executing the `TO_CHAR` function for intervals, it is important to be aware of the following overflow restrictions: |
There was a problem hiding this comment.
| Interval overflow occurs when an operation involving interval values exceeds the maximum limits of the interval data type, resulting in an error or unexpected behavior. This can happen when adding, subtracting or multiplying interval values that lead to a representation that goes beyond the allowable range for any of its components i.e. years, months, days, hours, minutes and seconds. When executing the `TO_CHAR` function for intervals, it is important to be aware of the following overflow restrictions: | |
| Interval overflow occurs when an operation involving interval values exceeds the maximum limits of the interval data type, resulting in an error or unexpected behavior. This can happen when adding, subtracting or multiplying interval values that lead to a representation that goes beyond the allowable range for any of its components (for example, years, months, days, hours, minutes and seconds). When executing the `TO_CHAR` function for intervals, it is important to be aware of these overflow restrictions: |
| FORMAT_TIMESTAMP(timestamp, format_string) | ||
| ---- | ||
|
|
||
| This function requires two arguments, i.e., a *timestamp* string that represents the timestamp value that needs to be converted to a specified format and a *format_string* that specifies the format to be converted into. Its return type is a timestamp value with a timezone. |
There was a problem hiding this comment.
| This function requires two arguments, i.e., a *timestamp* string that represents the timestamp value that needs to be converted to a specified format and a *format_string* that specifies the format to be converted into. Its return type is a timestamp value with a timezone. | |
| This function requires two arguments. For example, a *timestamp* string that represents the timestamp value that needs to be converted to a specified format and a *format_string* that specifies the format to be converted into. Its return type is a timestamp value with a timezone. |
|
|
||
| == `FORMAT_TIMESTAMP()` function if the input value of the year is less than 4 digits | ||
|
|
||
| `FORMAT_TIMESTAMP()` will adjust the year to the nearest year value if the input argument has less than the required number of digits i.e., less than 4. To see how it works, look at the following example: |
There was a problem hiding this comment.
| `FORMAT_TIMESTAMP()` will adjust the year to the nearest year value if the input argument has less than the required number of digits i.e., less than 4. To see how it works, look at the following example: | |
| `FORMAT_TIMESTAMP()` will adjust the year to the nearest year value if the input argument has less than the required number of digits (for example, less than 4). This example shows how it works: |
Clarify NOTE about CREATE TABLE behavior, convert multi-value option descriptions to lists for scannability, and rename ambiguous example heading. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]>
kbatuigas
force-pushed
the
DOC-1984-convert-and-migrate-existing-oxla-docs-to-asciidoc
branch
from
390341a to
54cd054
Compare
Style fixes across 31 files:
- Future tense → present tense ("will return" → "returns")
- Wordy instructions ("lets you" → direct verb)
- Awkward phrasing ("Here's how" → cleaner alternatives)
- First person ("we're going to" → "This example")
- Passive "It" patterns in tables → active voice
- Positional references ("the above query" → "Output:")
- Typo fix ("ouput" → "output")
Co-Authored-By: Claude Opus 4.5 <[email protected]>
JakeSCahill
left a comment
JakeSCahill
left a comment
There was a problem hiding this comment.
Looks good, no blockers.
I do wonder if these connection strings should mention oxla. Wouldn't Redpanda Cloud provide the connection string in the UI? "pgsql:host={oxla_host};port={oxla_port};dbname=oxla"
I would also remove the tips and notes on this page. They're not tips or anything noteworthy. I also question whether the info itself is useful: https://deploy-preview-521--rp-cloud.netlify.app/redpanda-cloud/sql/get-started/oltp-vs-olap/
kbatuigas
deleted the
DOC-1984-convert-and-migrate-existing-oxla-docs-to-asciidoc
branch
* Add converted SQL reference files * Duplicate file * Add index files * Add SQL reference to Cloud nav * Move reference pages to reference module * Convert remaining docs * Add placeholder index files * Cleanup * Move SQL section after RPCN * Continue cleanup using plugin audit and review * External links open in new window * Minor edit to trigger deploy preview * Migrate degraded state doc * Minor style edits * Address drift from Oxla changes since mid-Oct 2025 * Include CREATE TABLE and DROP changes * Update existing pages with placeholders for pages to be created * Another pass at style fixes * Missing TODO * Add remaining new reference pages to address doc drift * Remove Oxla storage compression references * Remove INSERT/UPDATE/DELETE from psycopg2 supported features * Remove Oxla-specific reasons from java-jdbc unsupported list * Remove DELETE/UPDATE references from php-pdo rowCount * Remove CREATE TABLE/INSERT example from select.adoc Assume that a student_data table is already created and populated with data * Remove table duplication TIP * Fix clumped "SELECTstatement" * Add missing Venn diagrams to JOIN pages * Inconsistent formatting with function names and parentheses * Incorrect COUNT logic with HAVING * Add NULLS FIRST/LAST, fix interval sorting * Replace CREATE TABLE oxlafunctions example in offset.adoc Redpanda SQL does not support CREATE TABLE without an external catalog Example assumes precreated salaryemp table * Unrelated "employees" text * Move column compatibility note to set-operations index Column type compatibility and flexible ordering applies to all set operations (UNION, INTERSECT, EXCEPT) * Both ROWS and RANGE frame modes are supported * Add GEOMETRY/GEOGRAPHY * Create sql-operators section with full operator list * timestamp-with-time-zone formatting * Remove internal memory representation for date type * Add month and day conversion note * Remove internal memory representation from bool type * System catalogs disambiguation note and 7 new pg_* pages * Fix nav * Move bitwise operators * Double check SQL examples and outputs * Remove unix_macros * Reorganize math and trig function pages * Implement some deferred fixes related to old Oxla examples * Fix anchors in xrefs * Apply QA checklist first pass across SQL reference docs Run 11-point QA checklist against all migrated SQL pages (148 files). Fixes applied: remove "Please note" phrasing, fix "here" link text, replace future tense output descriptions with present tense, simplify "allows/enables you to" constructions, remove minimizing language, fix wordy instructions, add missing admonition punctuation, replace verbose output lead-ins, remove "etc.", normalize positional references, and update stale PostgreSQL doc links to /docs/current/. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * Person 4 edits, including future tense, passive voice * more Person 4 edits * Person 4 edits * Parallelize :description: metadata for SQL language client pages Standardize the Java, PHP, and Python connector pages on the same imperative "Connect to Redpanda SQL from <language> using <tool>" template already used by the C# page and the parent index page. Co-Authored-By: Claude Opus 4.7 (1M context) <[email protected]> * Apply Feediver1 review suggestions Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * Apply pending PR suggestion comments Co-Authored-By: Claude Sonnet 4.6 <[email protected]> * Minor edit - statements index * keywords.adoc - move in nav tree, make table more scannable * alter-table minor edit * create-redpanda-catalog: Improve Options section * create-storage minor edit * Improve CREATE TABLE reference page clarity Clarify NOTE about CREATE TABLE behavior, convert multi-value option descriptions to lists for scannability, and rename ambiguous example heading. Co-Authored-By: Claude Opus 4.6 (1M context) <[email protected]> * select: review fixes * set-show: review fixes * show-tables minor edit * show-nodes: review fixes * describe: review fixes * sql-statements review pass * from - review pass * Minor edit * set-operations: review fixes * More review fixes for sql-clauses * other-functions review fixes * Normalize QA fixes * Apply edits based on doc team review * Standardize "To do X, run:" * Structural improvements * Sweep for passive voice * Person 2 style review: aggregate, window, JSON functions Style fixes across 31 files: - Future tense → present tense ("will return" → "returns") - Wordy instructions ("lets you" → direct verb) - Awkward phrasing ("Here's how" → cleaner alternatives) - First person ("we're going to" → "This example") - Passive "It" patterns in tables → active voice - Positional references ("the above query" → "Output:") - Typo fix ("ouput" → "output") Co-Authored-By: Claude Opus 4.5 <[email protected]> * Pass to standardize QA * Apply suggestions from review * Minor edits --------- Co-authored-by: Claude Opus 4.6 (1M context) <[email protected]> Co-authored-by: micheleRP <[email protected]> Co-authored-by: Joyce Fee <[email protected]> Co-authored-by: JakeSCahill <[email protected]>
6 participants
Description
This PR adds the converted content (MDX/Mintlify -> AsciiDoc/Antora) from docs.oxla.com into our Cloud docs.
The bulk of this migration involves SQL reference pages, which have been added to a new
sqlsubdirectory in the existingreferencemodule.A few other pages (primarily conceptual content) have also been added to a new
sqlmodule. These pages are organized under the "Redpanda SQL" section in the navigation.Items for manual review
(Not completed in the first pass at QA as described in Fixes done below)
Current Redpanda SQL implementation (changes from mid-October) - Engineering must verify
[ ] Functions:
ROUND(number, scale)— Two-argument form takes a number (F32/F64) and an integer scale.ROUND(3.14159, 2)returns3.14.CURRENT_TIMESTAMP(precision)— Accepts an integer literal 0–6 that truncates fractional seconds.CURRENT_TIMESTAMP(0)returns a timestamp with no fractional part.TO_CHAR(timestamp, NULL)returns '' — Returns empty string instead of NULL when the format string is NULL.TO_TIMESTAMP(NULL, format)returns NULL — Returns NULL instead of raising an error when the source string is NULL.[ ] Clauses:
JOIN ... USING (column [, ...])—USINGclause accepts a comma-separated list of column names shared by both tables.FROM t1, t2 WHERE ...behaves as a cross join filtered by the WHERE predicate.[ ] Statements:
SHOW NODES=SELECT * FROM system.nodes— Users can query system.nodes directly with WHERE/ORDER BY.SHOW TABLES FROM catalog_name— Lists tables mapped through a specific Redpanda catalog.lines 776–779)
DESCRIBE TABLE catalog_name=>table_name— Describes a table mapped through a catalog.DESCRIBE REDPANDA CATALOG catalog_name— Lists tables and topic mappings in a catalog.COPY my_catalog=>table_name TO ...— Confirm => is the correct operator for referencing catalog tables in all COPY TO variants.[ ] CREATE TABLE:
CREATE TABLE [IF NOT EXISTS] catalog=>table WITH (...)— Confirm this is the correct syntax for mapping a topic to atable.
topic(STRING, required) — Redpanda topic name.schema_subject(STRING, optional) — Schema Registry subject name.schema_lookup_policy(STRING, optional) — Only LATEST is supported. Confirm SCHEMA_ID returns a runtime error.error_handling_policy(STRING, optional) — FAIL (default), FILL_NULL, DROP_RECORD. Confirm all three values.struct_mapping_policy(STRING, optional) — JSON (default), FLATTEN, COMPOUND, VARIANT. Confirm all four values.output_schema_message_full_name(STRING, optional) — Full protobuf message name for multi-message schemas.[ ] DROP:
DROP TABLE [IF EXISTS] catalog=>table— Removes a catalog table mapping without deleting the underlying topic.DROP REDPANDA CATALOG [IF EXISTS] catalog_name— Removes a catalog connection.DROP STORAGE [IF EXISTS] storage_name— Removes a named storage definition.Oxla references
'Oxla'/'OxlaDocumentation'in code block string literalsoxla.enable_fast_math(set-show.adoc)[email protected]oxladbandoxlarefsas example schema namespublic.ecr.aws/oxla/release:latestand Oxla-specific connection stringsoxla_internal.oxla_roleandn_oxla_node_*(system catalog pages)Page attributes - doc team review
Style fixes (context-dependent) - doc team review
Deprecated terms (~42 occurrences in ~27 files)
e.g.→ "for example" (rewrite surrounding sentence for flow)i.e.→ "that is" (or rewrite to avoid the parenthetical)please→ remove or rewriteetc.→ specific list or removePassive voice (~93 occurrences across ~43 files)
First person (~354 occurrences in ~130 files)
Directional language (~739 occurrences in ~176 files)
Links - doc team review
Fixes done
Branding / Oxla references
Metadata
:page-topic-type: conceptto 3 sql module get-started pages:page-topic-type: referenceto all non-index pages in reference/pages/sql/ (172 pages):description:attributes exceeding 155 charactersHeadings — prohibited patterns
across 31+ files)
Headings — title case → sentence case
Headings — gerunds → imperative/noun phrase
files)
Links — external links open in new window using
^Style
&→andin headingsarabicnotation with proper AsciiDoc list continuation with+(31 files)Resolves https://github.com/redpanda-data/documentation-private/issues/
Review deadline:
Page previews
Reference > Redpanda SQL Reference
Redpanda SQL (guides, concepts, etc) - where most new content will be added
Checks