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 5 commits into
base: development
Choose a base branch
from
+133 −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
5 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
b3249c0
Add more examples to L/RPAD and use `·` for the space character in ex…
passalaqua May 27, 2026
18ced86
Re-add info about optional parameter in padding functions
passalaqua May 27, 2026
237e220
Add null/empty values specifications to oql padding functions
passalaqua May 28, 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
131 changes: 131 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,71 @@ 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.

Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 27, 2026

Choose a reason for hiding this comment

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

Is it worth noting that this edge case behavior depends on the database and that the customer should test them on their configuration? I'm not sure that all our users would think about this, or might raise questions about it.

This function returns `NULL` if `expression` is `NULL`.
The behavior for the empty string is database specific.

#### length_expression

`length_expression` specifies the length of the resulting string. The expression must be of type `integer` or `long`.
This function returns `NULL` if `length_expression` is `NULL`.

{{% 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.

Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 27, 2026

Choose a reason for hiding this comment

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

Thanks for the answer. We've said that it's database specific, so let's just leave it like that, rather than trying to give an actual answer.

{{% /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.
If `pad_expression` is `NULL` or the empty string, the behavior is database specific.

#### Examples

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

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

Where `·` represents the space character.


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

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

Comment on lines +1383 to +1390
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?

Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 27, 2026

Choose a reason for hiding this comment

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

Let's go for the clearer one.
(I need to review this page and split it up anyhow if we want it to be translatable - another few lines won't make any difference)

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

| padded |
|:-----------|
| abcabhello |

### Ranges in Datasets

{{% alert color="info" %}}
Expand Down Expand Up @@ -1507,6 +1574,70 @@ 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.
This function returns `NULL` if `expression` is `NULL`.
The behavior for the empty string is database specific.

#### length_expression

`length_expression` specifies the length of the resulting string. The expression must be of type `integer` or `long`.
This function returns `NULL` if `length_expression` is `NULL`.

{{% 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.

Copy link
Copy Markdown
Collaborator

@MarkvanMents MarkvanMents May 27, 2026

Choose a reason for hiding this comment

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

OK - should we add the note about it being database specific to encourage the user to test it?

Copy link
Copy Markdown
Contributor Author

@passalaqua passalaqua May 27, 2026

Choose a reason for hiding this comment

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

RPAD is consistent. It's only LPAD that behaves differently in HSQLDB and other dbs.

{{% /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.
If `pad_expression` is `NULL` or the empty string, the behavior is database specific.

#### Examples

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

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

Where `·` represents the space character.

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

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

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

| padded |
|:-----------|
| helloabcab |

### SUBSTRING{#substring-function}

#### Description
Expand Down