Skip to content

Add documentation for the LPAD and RPAD OQL functions #11190

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
passalaqua wants to merge 3 commits into
base: development
Choose a base branch
from
+106 −0
Open

Add documentation for the LPAD and RPAD OQL functions #11190

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
bc21da1
Add documentation for the LPAD and RPAD OQL functions
passalaqua May 12, 2026
a196c91
Change introduction date for oql padding functions to 11.12 and remov…
passalaqua May 18, 2026
7973784
Proofread oql-experssion-syntax.
MarkvanMents May 21, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions content/en/docs/refguide/modeling/domain-model/oql/_index.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -46,6 +46,8 @@ OQL is under constant development so some expressions and features are not avail
| DATEPARSE | 11.10.0 |
| DATETRUNC | 11.9.0 |
| LOCATE | 11.9.0 |
| LPAD | 11.12.0 |
| RPAD | 11.12.0 |
| STRING_AGG in View Entities and Datasets | 11.2.0 |
| SUBSTRING | 11.9.0 |

Expand Down
104 changes: 104 additions & 0 deletions content/en/docs/refguide/modeling/domain-model/oql/oql-expression-syntax.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -692,10 +692,12 @@ These are the currently supported functions:
* LENGTH
* LOCATE
* LOWER
* LPAD
* RANGEBEGIN
* RANGEEND
* REPLACE
* ROUND
* RPAD
* UPPER

### CAST{#cast}
Expand Down Expand Up @@ -1329,6 +1331,57 @@ SELECT * FROM Sales.Customer WHERE LOWER(LastName) = 'doe'
This query can no longer take advantage of an index for `LastName` for comparison, resulting in a performance decrease.
{{% /alert %}}

### LPAD {#lpad-function}

#### Description

Pads a string on the left side with a specified character to reach a target length. If no character is specified for padding, the space character is used.

{{% alert color="info" %}}
This function was introduced in Mendix version 11.12.0.
{{% /alert %}}

#### Syntax

```sql
LPAD ( expression , length_expression [, pad_expression ] )
```

#### expression

`expression` specifies the expression of type `string` to pad.
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Any special behavior for NULL? For Trim it returns NULL but does this just return a whole load of pad_expression?

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

They just return null if either the expression or length are null. If the padding pattern is null, it is usually null (HSQLDB is the exception and throws an error).

And if expression is the empty string or the length is zero, then Oracle returns null, but other databases return the empty string.

And if the padding pattern is the empty string, then Oracle and MariaDB return null, HSQLDB uses the space character, MySQL returns the empty string, and other databases return the original string. It's kind of a mess and I suppose those are cases where things can be described as "it's database dependent", so I didn't add to this page.


#### length_expression

`length_expression` specifies the length of the resulting string. The expression must be of type `integer` or `long`

{{% alert color="info" %}}
If `length_expression` is smaller than the length of `expression`, this function truncates it. This behavior is database specific.
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Truncates the right side, even though we are doing LPAD?

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Weirdly, yes. We were just as confused when implementing. The only exception is HSQLDB, which does the right thing, but possibly by accident given how special it is.

{{% /alert %}}

#### pad_expression

`pad_expression` is an optional parameter that specifies the character or string to pad with. If not specified, the space character is used.
Comment thread
passalaqua marked this conversation as resolved.

#### Examples

```sql
SELECT LPAD('hello', 10) AS padded FROM Sales.Order
```

| padded |
|:-----------|
| hello |
Comment on lines +1372 to +1374
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

This looks wrong when built. May have to think around this (  would work - but still difficult to see that it is space padded rather than right justified)

Image

)

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

I suppose we can change the query to

SELECT '|' + LPAD('hello', 10) + '|' AS padded FROM Sales.Order

The resulting string would be | hello|. Would we render it correctly with spaces?

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

We could also just render the result as

·····hello

Or something similar and indicate · represents a whitespace.



```sql
SELECT LPAD('hello', 10, 'x') AS padded FROM Sales.Order
```

| padded |
|:-----------|
| xxxxxhello |

Comment on lines +1377 to +1384
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Is it worth an example with a string pad_expression?

SELECT LPAD('hello', 10, 'abc') AS padded FROM Sales.Order

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Probably a good idea. I can write it as part of the same query (shorter page) or as a separate example (clearer). Which one do you prefer?

### Ranges in Datasets

{{% alert color="info" %}}
Expand Down Expand Up @@ -1507,6 +1560,57 @@ SELECT ROUND((Price : 7), 2) as RoundedPrice, Price : 7 FROM Sales.Order
| 0.33 | 3.33333333 |
| 1.17 | 1.17142857 |

### RPAD {#rpad-function}
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Same comments as for LPAD


#### Description

Pads a string on the right side with a specified character to reach a target length. If no character is specified for padding, the space character is used.

{{% alert color="info" %}}
This function was introduced in Mendix version 11.12.0.
{{% /alert %}}

#### Syntax

```sql
RPAD ( expression , length_expression [, pad_expression ] )
```

#### expression

`expression` specifies the expression of type `string` to pad.

#### length_expression

`length_expression` specifies the length of the resulting string. The expression must be of type `integer` or `long`

{{% alert color="info" %}}
If `length_expression` is smaller than the length of `expression`, this function truncates it.
Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Still normal truncation - so the same as LPAD?

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 21, 2026

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Yep.

{{% /alert %}}

#### pad_expression

`pad_expression` is an optional parameter that specifies the character or string to pad with. If not specified, the space character is used.

#### Examples

```sql
SELECT RPAD('hello', 10) AS padded FROM Sales.Order
```

| padded |
|:-----------|
| hello |


```sql
SELECT RPAD('hello', 10, 'x') AS padded FROM Sales.Order
```

| padded |
|:-----------|
| helloxxxxx |

### SUBSTRING{#substring-function}

#### Description
Expand Down