Add Oxla SQL Reference documentation (Beta)#1567
Add Oxla SQL Reference documentation (Beta)#1567emaxerrno wants to merge 1 commit intoredpanda-data:mainfrom
Conversation
✅ Deploy Preview for redpanda-docs-preview ready!Built without sensitive environment variables
To edit notification comments on pull requests, go to your Netlify project configuration. |
|
Important Review skippedToo many files! This PR contains 219 files, which is 69 over the limit of 150. You can disable this status message by setting the
✨ Finishing touches🧪 Generate unit tests (beta)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
emaxerrno
force-pushed
the
feature/integrate-oxla-docs
branch
2 times, most recently
from
9302d85 to
f9b321c
Compare
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 16
Note
Due to the large number of review comments, Critical severity comments were prioritized as inline comments.
🤖 Fix all issues with AI agents
In `@oxla/modules/oxla-reference/pages/sql-clauses/over-window.adoc`:
- Around line 119-120: The SELECT statement shown (SELECT * SUM(qty) OVER
(PARTITION BY sellerid) AS seller_qty) is missing a comma between the wildcard
and the windowed aggregate; update the SQL in the document so there is a comma
after the * (i.e., between SELECT * and SUM(qty) OVER (PARTITION BY sellerid) AS
seller_qty) to produce valid SQL.
- Around line 154-155: The SQL example has a syntax error: the SELECT list is
missing a comma between the wildcard (*) and the windowed expression; update the
example so there's a comma separating "*" and "SUM(qty) OVER seller AS
seller_qty" (i.e., add a comma after the "*" in the SELECT clause) to produce a
valid SELECT list.
In
`@oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/for-max.adoc`:
- Line 25: In the FOR_MAX documentation entry, replace the incorrect phrase
"metric minimum value" with "metric maximum value" so the sentence reads that
the `value` corresponding to the metric maximum value is `NULL`; locate the
FOR_MAX doc (for-max.adoc) and update that single phrasing to correct the
copy-paste error from FOR_MIN.
In
`@oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/for-min.adoc`:
- Around line 119-124: Remove the empty/malformed AsciiDoc table block starting
with the marker [cols="",options="header"] and the surrounding |=== ... |===
table delimiters (the stray block shown between the aggregate-functions document
content) so the leftover table markup is deleted entirely; this will restore
proper document structure and remove the empty table placeholders.
In
`@oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/ordered-set-aggregate-functions/percentile-disc.adoc`:
- Around line 10-48: The file uses HTML/React components (<Tabs>, <Tab>, <h2>,
<p>, <code>) that won't render in Antora; replace each Tab block with native
AsciiDoc instead—use level-3 headings (=== Discrete Percentile and === Multiple
Discrete Percentile) and plain paragraphs for descriptions/Parameters, keep the
existing [source,sql] code blocks for PERCENTILE_DISC(fraction) WITHIN GROUP
(...) and PERCENTILE_DISC(fractions) WITHIN GROUP (...), and optionally switch
to Antora's tabs extension if tabbed UI is required; remove all raw HTML tags
and ensure notes remain AsciiDoc NOTE blocks referencing PERCENTILE_DISC
semantics.
In `@oxla/modules/oxla-reference/pages/sql-functions/math-functions/least.adoc`:
- Line 8: The overview sentence incorrectly refers to "comparing the greatest
value" while this page documents the LEAST() function; update the sentence on
the LEAST() overview to reference "least" (or "smallest") instead of "greatest"
and ensure the example mentions LEAST() comparing 4, "two", and 9 will result in
an error, so change wording to match the LEAST() function semantics and mention
LEAST() explicitly.
In `@oxla/modules/oxla-reference/pages/sql-functions/math-functions/ln.adoc`:
- Line 14: Fix the typo in the section heading in ln.adoc where the heading
reads "## *yntax" — replace the asterisk-prefixed word with the correct heading
text "## Syntax" so the section title is properly spelled; update the heading
line in the file (the line currently containing "## *yntax") to "## Syntax".
- Line 6: The description for LN() is technically wrong: replace the phrase that
says "will return the exponential value of its argument" with a clear statement
that LN() returns the natural logarithm (base e) of its argument and is the
inverse of the exponential function; update the overview sentence for LN() to
read something like "LN() returns the natural logarithm (base e) of its argument
— the inverse of the exponential function," ensuring the symbol LN() and that
wording are used so the change is easy to locate.
In
`@oxla/modules/oxla-reference/pages/sql-functions/math-functions/overview.adoc`:
- Line 17: The LN() entry text is incorrect: change the description for LN()
(the LN() symbol in the document) to state that it computes the natural
logarithm (ln) of its argument (e.g., "This function returns the natural
logarithm of its argument") rather than saying it returns the exponential;
ensure EXP() remains described as the exponential function to avoid confusion.
- Line 26: The xref in overview.adoc points to the wrong target: change the xref
target currently referencing "bitwise-shift-left.adoc" for the "BITWISE SHIFT
RIGHT" entry to "bitwise-shift-right.adoc" so the link and description match;
locate the xref line containing
xref:oxla-reference:sql-functions/math-functions/bitwise-shift-left.adoc[BITWISE
SHIFT RIGHT] and update the target filename to bitwise-shift-right.adoc.
In
`@oxla/modules/oxla-reference/pages/sql-functions/other-functions/pg-get-indexdef.adoc`:
- Around line 11-25: The Syntax section uses a non-standard <CodeGroup> wrapper
and inconsistent code block delimiters causing malformed AsciiDoc; replace the
<CodeGroup> block with proper AsciiDoc code blocks for each version and correct
the fencing so the two variants of the function signature
(pg_get_indexdef(index_oid, column_oid) and pg_get_indexdef(index_oid,
column_oid, pretty_bool)) are each inside valid [source,sql] ... ---- ... ----
blocks, remove stray extra "----" markers, and ensure the "Version 1" / "Version
2" labels are plain text or AsciiDoc headings so the page renders correctly.
- Line 80: Remove the extraneous closing delimiter "----" that appears at the
end of the document; locate the orphaned delimiter line (the lone "----" at the
file tail) and delete it so the AsciiDoc file ends cleanly without an unmatched
block delimiter.
In
`@oxla/modules/oxla-reference/pages/sql-functions/string-functions/concat.adoc`:
- Line 7: The "Special cases" sentence incorrectly claims CONCAT "Returns `NULL`
if there are no input rows or `NULL` values"; update this to state that CONCAT
skips NULL input values (e.g., CONCAT('Talent Source ', NULL) -> 'Talent
Source') and only returns NULL when there are no non-NULL input values or no
input rows. Edit the line describing special cases in the CONCAT docs to match
the behavior shown in Case 3 and keep references to CONCAT and Case 3 to verify
consistency.
In
`@oxla/modules/oxla-reference/pages/sql-functions/string-functions/length.adoc`:
- Around line 19-20: Update the two special-case examples for the LENGTH
function: replace the malformed LENGTH(") with LENGTH("") and state it returns 0
for an empty string, and replace LENGTH('')/its description with LENGTH(' ') (a
single space character) and state it returns 1 because the input contains one
space; ensure the symbols LENGTH("") and LENGTH(' ') are used exactly in the
text and the accompanying return-value explanations are corrected.
In
`@oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/unix-micros.adoc`:
- Line 24: The SQL example uses the wrong function name; update the SELECT to
call UNIX_MICROS instead of UNIX_MICRO (change the function identifier in the
example line that currently reads SELECT UNIX_MICRO(... ) AS unix_microsvalues;
to SELECT UNIX_MICROS(... ) AS unix_microsvalues; so the function name matches
the documented UNIX_MICROS function).
- Line 10: The example uses the wrong function name: change the example call
from UNIX_MICRO(TIMESTAMP) to the correct function UNIX_MICROS(TIMESTAMP) so the
documentation matches the actual function name (update the single-line example
referencing UNIX_MICRO to UNIX_MICROS).
🟠 Major comments (33)
oxla/modules/oxla-reference/pages/comment-support.adoc-37-39 (1)
37-39:⚠️ Potential issue | 🟠 MajorIncorrect statement about single-line comment placement.
Line 39 states that "single-line comments should always be placed at the end of the line they refer to," but this is factually incorrect. In SQL, single-line comments (starting with
--) can be placed at the beginning of a line or inline. The--marker starts a comment that extends to the end of the line, regardless of where on the line it appears.For example, this is valid SQL:
-- This comment is at the start of a line SELECT column1 FROM table_name;The current wording incorrectly restricts users from placing comments at the beginning of lines.
📝 Suggested correction
-In OXLA, 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. +In OXLA, single-line comments can be placed anywhere on a line and extend to the end of that line, whereas multi-line comments can span multiple lines and be positioned anywhere within the query.oxla/modules/oxla-reference/pages/sql-clauses/set-operations/except.adoc-104-113 (1)
104-113:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
The HTML
<img>tags with React-styleclassNameattributes are not valid AsciiDoc syntax. Use AsciiDoc's native image macro.📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/except/except-one-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/except/except-one-dark.png" - alt="" -/> +image::images/except/except-one-light.png[EXCEPT diagram showing rows unique to first table]oxla/modules/oxla-reference/pages/sql-clauses/set-operations/intersect.adoc-111-120 (1)
111-120:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
The HTML
<img>tags with React-styleclassNameattributes are not valid AsciiDoc syntax. Use AsciiDoc's native image macro.📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/intersect/intersect-one-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/intersect/intersect-one-dark.png" - alt="" -/> +image::images/intersect/intersect-one-light.png[INTERSECT diagram showing common rows between tables]oxla/modules/oxla-reference/pages/sql-clauses/set-operations/intersect.adoc-255-264 (1)
255-264:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
Same issue as the previous image block. Use AsciiDoc's native image macro instead of HTML tags.
📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/intersect/intersect-two-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/intersect/intersect-two-dark.png" - alt="" -/> +image::images/intersect/intersect-two-light.png[INTERSECT ALL diagram showing common products across all three years]oxla/modules/oxla-reference/pages/sql-clauses/set-operations/except.adoc-228-237 (1)
228-237:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
Same issue as the previous image block. Use AsciiDoc's native image macro instead of HTML tags.
📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/except/except-two-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/except/except-two-dark.png" - alt="" -/> +image::images/except/except-two-light.png[EXCEPT ALL diagram showing unique customer-product pairs]oxla/modules/oxla-reference/pages/sql-clauses/set-operations/union.adoc-237-246 (1)
237-246:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
Same issue as the previous image block. Use AsciiDoc's native image macro instead of HTML tags.
📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/union/union-two-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/union/union-two-dark.png" - alt="" -/> +image::images/union/union-two-dark.png[UNION ALL diagram showing all rows included]oxla/modules/oxla-reference/pages/sql-clauses/set-operations/union.adoc-115-124 (1)
115-124:⚠️ Potential issue | 🟠 MajorReplace HTML img tags with AsciiDoc image syntax.
The HTML
<img>tags with React-styleclassNameattributes are not valid AsciiDoc syntax and will not render correctly in Antora. Use AsciiDoc's native image macro instead.📸 Proposed fix using AsciiDoc image syntax
-<img - className="block dark:hidden" - src="images/union/union-one-light.png" - alt="" -/> -<img - className="hidden dark:block" - src="images/union/union-one-dark.png" - alt="" -/> +image::images/union/union-one-light.png[UNION diagram showing duplicate removal]Note: If you need theme-specific images (light/dark mode), consult Antora's documentation for the proper approach in this documentation system.
oxla/modules/oxla-reference/pages/sql-functions/other-functions/current-schema.adoc-12-27 (1)
12-27:⚠️ Potential issue | 🟠 MajorFix malformed CodeGroup/source blocks in Syntax.
The current markup won’t render because the fences and block titles are mismatched.
✅ Corrected CodeGroup
<CodeGroup> .Version 1 [source,sql] ---- SELECT current_schema(); -[source] ---- ---- -sql Version 2 +.Version 2 +[source,sql] +---- SELECT current_schema; ---- </CodeGroup>oxla/modules/oxla-reference/pages/sql-functions/other-functions/has-schema-privillege.adoc-6-27 (1)
6-27:⚠️ Potential issue | 🟠 MajorFix broken AsciiDoc in overview and CodeGroup.
The link/backticks and the CodeGroup fencing are malformed, so the syntax blocks will not render correctly.
As per coding guidelines: “AsciiDoc linking: prefer using xref links with empty brackets … Avoid hard-coding link text; use xref:...[] to let the target document's title render as the link text when publishing.”✅ Suggested structure
-The <a href="https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-ACCESS" target="_blank">has_schema_privilege()</a>`has_schema_privilege` is an access privilege inquiry function that checks whether the current user has specific privileges on a schema. +The link:https://www.postgresql.org/docs/current/functions-info.html#FUNCTIONS-INFO-ACCESS[has_schema_privilege()] is an access privilege inquiry function that checks whether the current user has specific privileges on a schema. <CodeGroup> .Version 1 [source,sql] ---- SELECT has_schema_privilege('user', 'schema', 'privilege'); ----- -[source] ----- - ----- -sql Version 2 -SELECT has_schema_privilege('schema', 'privilege'); +---- + +.Version 2 +[source,sql] +---- +SELECT has_schema_privilege('schema', 'privilege'); ---- </CodeGroup>oxla/modules/oxla-reference/pages/sql-functions/math-functions/ln.adoc-24-24 (1)
24-24:⚠️ Potential issue | 🟠 MajorContradictory parameter description.
The parameter description states "
x: A positive or a negative number" but Line 10 explicitly notes that "The logarithm doesn't take negative numbers or 0." This is a contradiction. The natural logarithm is only defined for positive numbers.📝 Proposed fix
-`x`: A positive or a negative number (or an expression that evaluates to a number). +`x`: A positive number (or an expression that evaluates to a positive number).oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/timestamp-millis.adoc-43-55 (1)
43-55:⚠️ Potential issue | 🟠 MajorFix INSERT target table name.
The table is
unix_example, but the INSERT usesunix_timestamp.Suggested fix
-INSERT INTO unix_timestamp VALUES +INSERT INTO unix_example VALUESoxla/modules/oxla-reference/pages/sql-functions/math-functions/sign.adoc-71-75 (1)
71-75:⚠️ Potential issue | 🟠 MajorCorrect function description: SIGN() returns sign, not absolute value.
This description is inaccurate and could mislead readers.
Suggested fix
-The following example demonstrates how the `SIGN()` function can be used with a table to obtain the absolute values of all numbers in a specific column: +The following example demonstrates how the `SIGN()` function can be used with a table to obtain the sign of all numbers in a specific column:oxla/modules/oxla-reference/pages/sql-clauses/with.adoc-53-57 (1)
53-57:⚠️ Potential issue | 🟠 MajorUse single quotes for string literals.
subject="Math"treatsMathas an identifier, not a string. Use single quotes.Suggested fix
-WITH math_grades AS (SELECT g_date, semester_id, grade FROM grades WHERE subject="Math") +WITH math_grades AS (SELECT g_date, semester_id, grade FROM grades WHERE subject='Math')oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/timestamp-micros.adoc-43-88 (1)
43-88:⚠️ Potential issue | 🟠 MajorFix inconsistent table names in the example.
The table is created as
timemirco_examplebut later referenced astimemicro_example, which will fail.Suggested fix
-Create TABLE timemirco_example ( +CREATE TABLE timemicro_example ( @@ -INSERT INTO timemirco_example VALUES +INSERT INTO timemicro_example VALUES @@ -SELECT * FROM timemirco_example; +SELECT * FROM timemicro_example; @@ -FROM timemicro_example; +FROM timemicro_example;oxla/modules/oxla-reference/pages/sql-functions/other-functions/pg-get-constraintdef.adoc-10-25 (1)
10-25:⚠️ Potential issue | 🟠 MajorFix return type and invalid "no parameters" restriction.
pg_get_constraintdef()returnstext(the human-readable constraint definition), notNULL. The restriction claiming the function returnsNULLwhen no parameters are specified is incorrect and should be removed; the function requiresconstraint_oidand has an optionalpretty_boolparameter.Suggested fix
-<pre><code>pg_get_constraintdef (constraint_oid [, pretty_bool]) → NULL</code></pre> +<pre><code>pg_get_constraintdef (constraint_oid [, pretty_bool]) → text</code></pre> @@ -* This function always returns `NULL` if there are no parameters specified +* Requires `constraint_oid`; returns the constraint definition as `text`.oxla/modules/oxla-reference/pages/sql-functions/math-functions/bitwise-shift-right.adoc-27-34 (1)
27-34:⚠️ Potential issue | 🟠 MajorResolve contradiction about negative shift amounts.
There's a direct contradiction in the documentation:
- Line 27 states: "shift_amount: a non-negative integer"
- Line 31 states: "shift amount to be a non-negative integer"
- Lines 32-34 state: "Oxla treats negative shift counts as valid by applying modulo arithmetic"
These statements cannot both be true. Either:
- Negative shift amounts are not allowed (non-negative requirement is enforced), OR
- Negative shift amounts are allowed and handled via modulo arithmetic
Please clarify the actual behavior and update the documentation consistently.
oxla/modules/oxla-reference/pages/sql-functions/string-functions/starts-with.adoc-99-169 (1)
99-169:⚠️ Potential issue | 🟠 MajorFix major inconsistencies in Case
#2example.Case
#2has several conflicting statements about NULL vs. empty string:
- Line 101 states "with a
NULLvalue in the breed column"- Line 121 actually inserts an empty string
''(not NULL)- Line 142 shows
'goldfish'in the output table, which doesn't match the INSERT- Line 155 says it returns true "even the
nullone" but the example uses empty string- Line 168 shows
nullin output, inconsistent with both the INSERT and line 142The example needs to be corrected to either:
- Use NULL consistently (insert NULL, describe NULL behavior, show NULL in output), or
- Use empty string consistently (insert '', describe empty string behavior, show empty string in output)
Additionally, the behavior described at line 155-156 conflates the special case from line 22 (which is about an empty
second_argument, not about NULL in the data).oxla/modules/oxla-reference/pages/sql-clauses/from/join.adoc-25-32 (1)
25-32:⚠️ Potential issue | 🟠 MajorFix
common_filedtypos in JOIN syntax and explanation.
It should becommon_fieldto avoid confusion.🔧 Suggested fix
-ON table_1.common_filed = table_2.common_field +ON table_1.common_field = table_2.common_field(Apply the same correction in the explanatory bullets and alias syntax.)
Also applies to: 45-46
oxla/modules/oxla-reference/pages/sql-functions/string-functions/strpos.adoc-14-15 (1)
14-15:⚠️ Potential issue | 🟠 MajorReturn type is incorrect.
STRPOS returns an integer position, not a string. Please correct the “input and return” line.🔧 Suggested fix
-The input and return must be of type `string`. +The input is type `string`, and the return type is `integer`.oxla/modules/oxla-reference/pages/sql-functions/string-functions/position.adoc-53-60 (1)
53-60:⚠️ Potential issue | 🟠 MajorFix Example 2 output mismatch.
The narrative says the result is 1, but the output table shows 7. ForPOSITION('123' IN '1a2b3c'), the correct result is 0 (substring not contiguous). Align the narrative and the output table.🔧 Suggested fix
-`123` is found starting at position 1, the result would be 1. +`123` is not found because the characters are not contiguous; the result is 0. ... position ---------- - 7 + 0oxla/modules/oxla-reference/pages/sql-clauses/from/left-join.adoc-35-38 (1)
35-38:⚠️ Potential issue | 🟠 MajorCorrect clause labels in LEFT JOIN explanation.
Line 36 says “FORM” and Line 37 says “RIGHT JOIN” in a LEFT JOIN section.🔧 Suggested fix
-2. `FROM table_1` defines the **left table** as the main table in the FORM clause. -3. `RIGHT JOIN table_2` defines the **right table** as the table the main table joins. +2. `FROM table_1` defines the **left table** as the main table in the FROM clause. +3. `LEFT JOIN table_2` defines the **right table** as the table the main table joins.oxla/modules/oxla-reference/pages/sql-clauses/from/outer-join.adoc-27-36 (1)
27-36:⚠️ Potential issue | 🟠 MajorFix
table2typo in JOIN condition.
Usetable_2consistently.🔧 Suggested fix
-ON table_1.matching_field = table2.matching_field; +ON table_1.matching_field = table_2.matching_field;oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/date-trunc.adoc-13-27 (1)
13-27:⚠️ Potential issue | 🟠 MajorFix malformed syntax block structure.
This section has multiple AsciiDoc syntax issues that will likely cause rendering problems:
<CodeGroup>appears to be a custom component tag—verify it's supported by your AsciiDoc processor.- Line 19 has
[source]inside a code block, which is invalid.- Lines 22-25 have a code block without proper
----delimiters and contain what looks like a mangled heading (sql With time_zone).📝 Suggested fix (using tabs extension)
-<CodeGroup> - -.Without time_zone -[source,sql] ----- -DATE_TRUNC(field, source) -[source] ----- - ----- -sql With time_zone -DATE_TRUNC(field, source, time_zone) ----- - -</CodeGroup> +[tabs] +==== +Without time_zone:: ++ +[source,sql] +---- +DATE_TRUNC(field, source) +---- + +With time_zone:: ++ +[source,sql] +---- +DATE_TRUNC(field, source, time_zone) +---- +====Alternatively, if tabs aren't available, use two separate labeled code blocks.
oxla/modules/oxla-manage/pages/access-control.adoc-14-14 (1)
14-14: 🛠️ Refactor suggestion | 🟠 MajorConvert HTML anchor tags to xref links.
Internal documentation links should use AsciiDoc
xrefsyntax rather than HTML anchor tags. This allows Antora to properly resolve links and pull titles automatically from the referenced documents.♻️ Proposed conversion to xref links
Line 14:
-<a href="/configuration-deployment/configuration/oxla-configuration-file" target="_blank">Configuration File</a> documentation. +xref:oxla:configuration-deployment/configuration/oxla-configuration-file.adoc[] documentation.Line 38:
-<a href="/security/roles#changing-password" target="_blank">ALTER ROLE</a> query +xref:oxla-manage:roles.adoc#changing-password[ALTER ROLE] queryLine 66:
-<a href="/troubleshooting-optimization/degraded-state-handling" target="_blank">**degraded state**</a>. +xref:oxla-troubleshoot:degraded-state-handling.adoc[degraded state].Note: Verify the exact module names and paths match your Antora configuration.
Based on learnings: "AsciiDoc linking: prefer using xref links with empty brackets (e.g., xref:section/target.adoc[]) because the title is pulled from the referenced document automatically."
Also applies to: 38-38, 66-66
oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/for-max.adoc-103-118 (1)
103-118:⚠️ Potential issue | 🟠 MajorOutput data for John is incorrect.
Line 47 shows John has only one row with discount 0.1, but line 117 shows the query output as 0.2. Since
FOR_MAX(price, discount)returns the discount value from the row with the maximum price, and John's only row has discount 0.1, the expected output should be 0.1, not 0.2.Verify the input data for John—either an additional row with a higher price and discount 0.2 is missing from the
INSERTstatement, or the output table should show 0.1.oxla/modules/oxla-reference/pages/sql-functions/overview.adoc-12-20 (1)
12-20: 🛠️ Refactor suggestion | 🟠 MajorUse empty brackets in xref links to auto-pull document titles.
All xref links in this table use hardcoded link text (e.g.,
[BOOLEAN FUNCTIONS],[MATH FUNCTIONS]). Per the established pattern, xref links should use empty brackets[]to automatically pull the title from the target document. This ensures consistency and reduces maintenance burden when target document titles change.♻️ Proposed refactor
-|xref:oxla-reference:sql-functions/boolean-functions/if-function.adoc[BOOLEAN FUNCTIONS] |Evaluate logical conditions and return `TRUE`, `FALSE` OR `NULL` -|xref:oxla-reference:sql-functions/math-functions/overview.adoc[MATH FUNCTIONS] |Perform mathematical operations on numeric data, such as rounding, exponentiation calculation -|xref:oxla-reference:sql-functions/string-functions/overview.adoc[STRING FUNCTIONS] |Manipulate string data for text processing, including concatenation, substring extraction and case conversion -|xref:oxla-reference:sql-functions/timestamp-functions/overview.adoc[TIMESTAMP FUNCTIONS] |Handle date and time values including extracting components, adding intervals and comparing timestamps -|xref:oxla-reference:sql-functions/trigonometric-functions/overview.adoc[TRIGONOMETRIC FUNCTIONS] |Perform calculations using trigonometric ratios, such as sine, cosine and tangent -|xref:oxla-reference:sql-functions/json-functions/overview.adoc[JSON FUNCTIONS] |Manipulate and query JSON data stored in the database, including extracting values and creating JSON objects -|xref:oxla-reference:sql-functions/aggregate-functions/overview.adoc[AGGREGATE FUNCTIONS] |Summarize a set of values and return a single result, such as calculating sums, averages and counts -|xref:oxla-reference:sql-functions/window-functions/overview.adoc[WINDOW FUNCTIONS] |Operate over a subset of rows defined by a windowing clause, enabling ranking, aggregation and row numbering within result sets -|xref:oxla-reference:sql-functions/other-functions/overview.adoc[OTHER FUNCTIONS] |Includes a variety of specialized functions not categorized elsewhere +|xref:oxla-reference:sql-functions/boolean-functions/if-function.adoc[] |Evaluate logical conditions and return `TRUE`, `FALSE` OR `NULL` +|xref:oxla-reference:sql-functions/math-functions/overview.adoc[] |Perform mathematical operations on numeric data, such as rounding, exponentiation calculation +|xref:oxla-reference:sql-functions/string-functions/overview.adoc[] |Manipulate string data for text processing, including concatenation, substring extraction and case conversion +|xref:oxla-reference:sql-functions/timestamp-functions/overview.adoc[] |Handle date and time values including extracting components, adding intervals and comparing timestamps +|xref:oxla-reference:sql-functions/trigonometric-functions/overview.adoc[] |Perform calculations using trigonometric ratios, such as sine, cosine and tangent +|xref:oxla-reference:sql-functions/json-functions/overview.adoc[] |Manipulate and query JSON data stored in the database, including extracting values and creating JSON objects +|xref:oxla-reference:sql-functions/aggregate-functions/overview.adoc[] |Summarize a set of values and return a single result, such as calculating sums, averages and counts +|xref:oxla-reference:sql-functions/window-functions/overview.adoc[] |Operate over a subset of rows defined by a windowing clause, enabling ranking, aggregation and row numbering within result sets +|xref:oxla-reference:sql-functions/other-functions/overview.adoc[] |Includes a variety of specialized functions not categorized elsewhereBased on learnings: prefer using xref links with empty brackets (e.g., xref:section/target.adoc[]) because the title is pulled from the referenced document automatically, avoiding hard-coded link text.
oxla/modules/oxla-reference/pages/sql-functions/other-functions/pg-get-expr.adoc-11-26 (1)
11-26:⚠️ Potential issue | 🟠 MajorFix malformed AsciiDoc code block structure.
The syntax block contains invalid AsciiDoc markup with
<CodeGroup>tags and broken code block delimiters. This will likely cause rendering errors.Issues identified:
- Lines 11, 26:
<CodeGroup>and</CodeGroup>are not standard AsciiDoc syntax- Line 18:
[source]appears without proper context- Lines 14-24: Code block delimiters (
----) are improperly nested- Line 22: Text "sql Version 2" appears outside a proper code block
🔧 Proposed fix for proper AsciiDoc syntax
-There are two available syntax versions of the `pg_get_expr()` function: -<CodeGroup> - - -.Version 1 -[source,sql] ----- -SELECT pg_get_expr('expr_text', relation_oid); -[source] ----- - ----- -sql Version 2 -SELECT pg_get_expr('expr_text', relation_oid, pretty_bool); ----- - -</CodeGroup> +There are two available syntax versions of the `pg_get_expr()` function: + +.Version 1 +[source,sql] +---- +SELECT pg_get_expr('expr_text', relation_oid); +---- + +.Version 2 +[source,sql] +---- +SELECT pg_get_expr('expr_text', relation_oid, pretty_bool); +----oxla/modules/oxla-reference/pages/sql-data-types/date.adoc-4-82 (1)
4-82:⚠️ Potential issue | 🟠 MajorUse AsciiDoc section markers (
==) instead of Markdown (##).This file is
.adocbut uses Markdown headings. Convert## Overview,## Structure,## Format, and## Exampleto==sections so Antora renders them correctly.🛠️ Proposed fix
-## Overview +== Overview ... -## Structure +== Structure ... -## Format +== Format ... -## Example +== Exampleoxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/sum.adoc-4-266 (1)
4-266:⚠️ Potential issue | 🟠 MajorConvert Markdown-style headings to AsciiDoc.
This
.adocfile uses##and####Case`` headings. Switch to==/`===` and drop the “#” to avoid rendering issues.🛠️ Proposed fix
-## Overview +== Overview ... -## Examples +== Examples ... -### `#Case` 1: `SUM()` in `SELECT` statement +=== Case 1: `SUM()` in `SELECT` statement ... -### `#Case` 2: `SUM()` with a `NULL` result +=== Case 2: `SUM()` with a `NULL` result ... -### `#Case` 3: `SUM()` with `GROUP BY` clause +=== Case 3: `SUM()` with `GROUP BY` clause ... -### `#Case` 4: `SUM()` with `HAVING` clause +=== Case 4: `SUM()` with `HAVING` clause ... -### `#Case` 5: `SUM()` with multiple expression +=== Case 5: `SUM()` with multiple expressionsoxla/modules/oxla-reference/pages/sql-data-types/numeric-type/numeric.adoc-4-330 (1)
4-330:⚠️ Potential issue | 🟠 MajorUse AsciiDoc section markers and fix a grammar typo.
Replace
##with==for section headers and correct “table show below” → “table shown below”.🛠️ Proposed fix
-## Int Type +== Int Type ... -## Bigint Type +== Bigint Type ... -## Real Type +== Real Type ... -## Double Precision Type +== Double Precision Type ... -It will result in a table show below. +It will result in a table shown below.oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/bool-and.adoc-4-121 (1)
4-121:⚠️ Potential issue | 🟠 MajorUse AsciiDoc section syntax and remove the empty code block.
This file uses Markdown-style headings (
##,###) and contains an empty[source,sql]block (Lines 111–115). In.adoc, use==/===for sections, and remove the empty block to avoid rendering issues.🛠️ Proposed fix
-## Overview +== Overview ... -## Examples +== Examples ... -### Case `#1`: `BOOL_AND` with a false result +=== Case `#1`: `BOOL_AND` with a false result ... -### Case `#2`: `BOOL_AND` with a true result +=== Case `#2`: `BOOL_AND` with a true result -.+------------+ -[source,sql] ----- -----oxla/modules/oxla-reference/pages/sql-data-types/array.adoc-4-201 (1)
4-201:⚠️ Potential issue | 🟠 MajorReplace Markdown headings (
##/###) with AsciiDoc section titles.This is an
.adocfile;##/###will render as plain text. Use==/===.✅ Suggested fix (example pattern)
-## Overview +== Overview @@ -### Field Size Limit +=== Field Size Limitoxla/modules/oxla-reference/pages/sql-data-types/time-type/time-operators.adoc-6-410 (1)
6-410:⚠️ Potential issue | 🟠 MajorReplace Markdown headings (
##/###) with AsciiDoc section titles.This is an
.adocfile, so##/###won’t create sections or TOC entries. Use==/===etc.✅ Suggested fix (example pattern)
-## 1. DATE + INTEGER +== 1. DATE + INTEGER @@ -### 1.1. INTEGER + DATE +=== 1.1. INTEGER + DATE
oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/for-max.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/aggregate-functions/for-min.adoc
Outdated
Show resolved
Hide resolved
...pages/sql-functions/aggregate-functions/ordered-set-aggregate-functions/percentile-disc.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/other-functions/pg-get-indexdef.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/string-functions/concat.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/string-functions/length.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/unix-micros.adoc
Outdated
Show resolved
Hide resolved
oxla/modules/oxla-reference/pages/sql-functions/timestamp-functions/unix-micros.adoc
Outdated
Show resolved
Hide resolved
This commit resolves all issues identified by CodeRabbit's automated review for PR redpanda-data#1567: SQL Syntax Fixes: - Fix missing commas in over-window.adoc SELECT statements (lines 119-120, 154-155) - Correct UNIX_MICRO to UNIX_MICROS in unix-micros.adoc function calls AsciiDoc Format Conversions: - Convert HTML img tags to native image:: syntax in union.adoc, intersect.adoc, except.adoc - Convert HTML/React components (Tabs, Tab, h2, p) to AsciiDoc in percentile-disc.adoc - Convert Markdown headings (##, ###) to AsciiDoc (==, ===) in date.adoc, sum.adoc, numeric.adoc, array.adoc Documentation Accuracy Corrections: - Fix ln.adoc description (natural logarithm, not exponential value) and heading typo - Fix least.adoc to reference "least value" instead of "greatest value" - Fix sign.adoc to correctly describe sign function (not absolute values) - Fix for-max.adoc to reference "maximum value" instead of "minimum value" - Fix length.adoc malformed quote syntax for empty string and space character examples - Remove contradictory "non-negative" requirement from bitwise-shift-right.adoc Typos and Cross-Reference Fixes: - Fix common_filed → common_field typo in join.adoc - Fix table2 → table_2 inconsistency in left-join.adoc, right-join.adoc, outer-join.adoc - Fix position.adoc example #2 output (should be 0, not 7) - Fix strpos.adoc return type documentation (integer, not string) - Convert malformed CodeGroup to proper AsciiDoc in date-trunc.adoc - Convert HTML anchor tags to proper xref links in access-control.adoc - Fix incorrect xref for BITWISE SHIFT RIGHT in math functions overview.adoc Data Consistency Fixes: - Fix timemirco_example → timemicro_example typo in timestamp-micros.adoc - Fix INSERT table name in timestamp-millis.adoc (unix_example not unix_timestamp) - Fix for-max.adoc output value to match input data (0.1 not 0.2) - Fix starts-with.adoc to use NULL instead of empty string for consistency Miscellaneous Fixes: - Remove empty malformed table block in for-min.adoc (lines 119-124) - Remove orphaned delimiter in pg-get-indexdef.adoc (line 80) - Fix concat.adoc NULL handling documentation to match actual behavior - Fix pg-get-constraintdef.adoc return type (text not NULL) All 33 issues have been resolved to ensure quality and functionality. Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
This PR integrates Oxla SQL Reference documentation into the main Redpanda docs
repository as a new Antora component with beta status.
## Content Added
- **Oxla SQL Reference**: 202 pages covering SQL statements, functions, data types, and system catalogs
- **Security documentation**: 6 pages on access control, roles, and privileges
- **Troubleshooting guides**: 2 pages on error handling and degraded state management
- **Total**: 225 AsciiDoc pages + 143 images
## Structure
```
oxla/
├── antora.yml # Component configuration with beta badge
└── modules/
├── oxla/ # Landing page and home content
├── oxla-reference/ # SQL reference documentation
├── oxla-manage/ # Security and access control
└── oxla-troubleshoot/ # Troubleshooting guides
```
## Documentation Quality Improvements
All content has been reviewed and corrected for:
### SQL Syntax Accuracy
- Fixed missing commas in window function SELECT statements
- Corrected function name inconsistencies (UNIX_MICROS)
### AsciiDoc Format Compliance
- Converted all HTML markup to native AsciiDoc syntax
- Replaced HTML img tags with image:: directives
- Converted Markdown headings to AsciiDoc heading syntax
- Replaced React components with proper AsciiDoc structures
### Technical Accuracy
- Corrected function descriptions (ln, least, sign, for-max)
- Fixed parameter documentation (length, bitwise-shift-right)
- Ensured consistent NULL handling documentation
### Cross-References & Navigation
- Fixed all internal cross-reference links
- Converted HTML anchors to proper xref syntax
- Corrected navigation paths and file references
### Data Consistency
- Fixed table name typos across timestamp functions
- Corrected example outputs to match input data
- Ensured consistent data types in examples
## Beta Status
Oxla documentation is clearly marked as BETA at multiple levels:
- Beta badge in component configuration (oxla.yml)
- Beta indicator in main navigation
- Beta banner on landing page
- `page-beta` attribute applied to all Oxla pages
## Integration Details
- Updated main navigation (modules/ROOT/nav.adoc)
- Updated Antora playbook for local builds
- All internal cross-references use new module names (oxla-reference, oxla-manage, oxla-troubleshoot)
- Follows Redpanda Antora conventions and patterns
Co-Authored-By: Claude Sonnet 4.5 <noreply@anthropic.com>
emaxerrno
force-pushed
the
feature/integrate-oxla-docs
branch
from
9190d90 to
17a19e9
Compare
|
Given that oxla will only work with byoc out of the gate, I'm curious to understand why this is all going into the Self-Managed docs instead? |
|
List of disabled features to be removed from documentation: |
4 participants
Overview
This PR integrates Oxla SQL Reference documentation into the main Redpanda docs repository as a new Antora component with beta status.
Changes
New Content
Structure
Navigation
Key Features
Beta Status
Oxla documentation is clearly marked as BETA at multiple levels:
page-betaattribute applied to all Oxla pagesTechnical Details
Cross-reference Updates
All internal cross-references have been updated to use new module names:
xref:reference:→xref:oxla-reference:xref:manage:→xref:oxla-manage:xref:troubleshoot:→xref:oxla-troubleshoot:xref:ROOT:→xref:oxla:Antora Configuration
The component follows Redpanda Antora conventions:
Migration Path
This integration enables deprecation of the standalone
oxla-docsrepository:Testing Checklist
Related
Preview
Once merged, Oxla SQL documentation will be available at:
/oxla//oxla-reference/overview/oxla-manage/access-control🆕 All pages will display beta indicators to users.
🤖 Generated with Claude Code