# Size constraint annotations · Chromia Docs (concept)

> You can add size constraint annotations to parameters of functions, queries, and operations, to struct attributes, and to entity and object attributes, to…

Source: https://docs.chromia.com/rell/language-features/modules/size-constraint-annotations/

# Size constraint annotations

On this page

* [Available annotations](#available-annotations)
* [Examples](#examples)
* [Combining annotations](#combining-annotations)
* [Validation](#validation)
* [Struct attributes](#struct-attributes)
* [Operations: struct<operation> behavior](#operations-structoperation-behavior)
* [Entity and object attributes](#entity-and-object-attributes)

You can add size constraint annotations to parameters of functions, queries, and operations, to struct attributes, and
to entity and object attributes, to specify size limits on the values. Supported types are
[`text`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/text/) and
[`byte_array`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/byte_array/).

The sections below describe parameters first; see [Struct attributes](#struct-attributes) for structs and
[Entity and object attributes](#entity-and-object-attributes) for the database side.

## Available annotations

* **`@size(n)`**: The parameter must have exactly size `n`
* **`@size(min, max)`**: The parameter must have a size in the range `min` to `max`
* **`@min_size(n)`**: The parameter must have a minimum size of `n`
* **`@max_size(n)`**: The parameter must have a maximum size of `n`

## Examples

Rell

```
// query only accepts pubkeys of size 32
query get_info(@size(32) pubkey: byte_array) { ... }

// status parameter cannot be empty
function print_status(@min_size(1) status: text) { ... }

// can't register a user with name > 50 characters long
operation register_user(@max_size(50) name) { ... }
```

## Combining annotations

Use `@min_size` and `@max_size` together, or the `@size(min, max)` shorthand for a range:

Rell

```
query q(@size(8, 16) data: byte_array) { ... }
...
q(x'0123')  // error, data too small
q(x'00112233445566778899AABBCCDDEEFF00')  // error, data too large
q(x'01234567890AB')  // ok
```

## Validation

Parameter size constraint annotations are checked when the function, query, or operation is called, including when a
default value is used. Default values are not checked at compile-time.

## Struct attributes

The same annotations apply to struct attributes of type `text` and [`byte_array`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/byte_array/):

Rell

```
struct user {
    id: integer;
    @max_size(50) user_name: text;      // user_name must have size <= 50
    @size(32) public_key: byte_array;   // public_key must have size == 32
    @min_size(1) status: text;          // status must have size >= 1
}
```

Struct attribute values are checked at runtime when a struct value is created, whether by its constructor or by
`from_bytes()` or `from_gtv()`, and when a mutable attribute is assigned:

Rell

```
struct item {
    quantity: integer;
    mutable @size(5, 20) description: text;
}
...
item(3, '')                                             // error, description too small
item(7, 'The quick brown fox jumps over the lazy dog')  // error, description too long
val i = item(0, 'party hat');                           // ok
i.description = 'hat';                                  // error, description too small
```

Default values are not checked at compile-time. An invalid default compiles, and the error is raised at runtime when the
default is used:

Rell

```
struct y {
    @size(3) z: text = 'not three characters!';
}
...
y() // error, z has the wrong size
```

## Operations: `struct<operation>` behavior

If an operation parameter has a size constraint annotation, the operation's corresponding `struct<operation>` attribute
behaves as though it were defined with an equivalent size constraint annotation. For example, for operation
`register_user(@max_size(50) name)`:

Rell

```
struct<register_user>('This name is not allowed because it has more than fifty characters!') // error
```

## Entity and object attributes

Since 0.15.1, the same annotations apply to entity and object attributes of type `text` and [`byte_array`](https://docs.chromia.com/pages/rell-stdlib/-rell-system-library/root/byte_array/):

Rell

```
entity user {
    id: integer;
    @max_size(50) userName: text;       // userName must have size <= 50
    @size(32) publicKey: byte_array;    // publicKey must have size == 32
    @min_size(1) status: text;          // status must have size >= 1
}
```

These annotations compile to PostgreSQL `CHECK` constraints, so they are enforced on create and update, and on
assignment to entity attributes with the `=` and `+=` operators:

Rell

```
entity user { @max_size(10) name; }

create user('A very long name'); // error, name too long

update user @* { .name == some_predicate() } ( name = 'A very long name' ); // error, name too long

val u = user @ { .name == some_predicate() };
u.name += 'A long name suffix.'; // error, name too long
```

You can't change the size constraints of an entity that has rows, with one exception: you can relax a constraint, which
means increasing a maximum size or decreasing a minimum size, because that can't invalidate existing data.

Size constraint annotations were added for struct attributes in 0.14.13 and for function, query, and operation
parameters in 0.14.14.

[View this page on docs.chromia.com](https://docs.chromia.com/rell/language-features/modules/size-constraint-annotations/)Content mirrored from the live docs
