Size constraint annotations

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 and byte_array.

The sections below describe parameters first; see Struct attributes for structs and 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

// 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:

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:

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:

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:

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):

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:

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:

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.