Partition and distribution

These are two separate questions. Partitioning says how the data is split; distribution says where each part lives.

create_schema('events')
    .fields({
        'seq':  {type: int64, autoincrement: true, primary_key: true},
        'what': {type: string, max_length: 200}
    })
    .set_partition({
        'seq': {strategy: range, period: 10000}
    })
    .set_distribution({
        'seq': [
            {start: 0,     end: 10000, location: local()},
            {start: 10000, end: 30000, location: file('parts/events_2.ndbp')},
            {start: 30000, location: remote('10.0.0.12:7070'), credential: 'node02'}
        ]
    })
    .commit();

Partitioning#

• One key field. Partitioning by several fields is not supported yet.
• Strategy: range.
• For integer keys period is a number and start defaults to 0.
• For date keys period is a duration (180d, 4w, 12h) and start is required.

create_schema('logs')
    .fields({'day': {type: date}, 'message': {type: text}})
    .set_partition({'day': {start: '2026-01-01', period: 180d}})
    .commit();

Duration units: ms, s, m, h, d, w. Months and years have no fixed length, so they cannot be used.

The distribution map#

• Ranges are [start, end): the start is included, the end is not. Only the last range can leave its end open.
• Ranges must be in order and must not overlap. Every boundary must fall on a partition boundary (start + n × period).
• Ranges that are not in the map live in this .ndbc file.
• Locations: local(), file('path.ndbp') (.ndbp = nar database partition), remote('host:port').

The map is embedded in the .ndbc file. Even when a partition lives in another file or on another server, the information about where it lives stays in the database itself. Every database has a 128-bit database_id; external partitions will link to the right database with it.

Keys never go into a schema#

A remote range needs a credential. This is not a key; it is the name of an entry in the system keychain.

# error: never put keys in a schema: store the key in the system keychain and write credential: 'name' instead
create_schema('x')
    .fields({'id': {type: int64}})
    .set_partition({'id': {period: 10000}})
    .set_distribution({'id': [
        {start: 0, location: remote('10.0.0.12:7070'), private_key: 'ndb_tbk_93hdhf'}
    ]});

Server details cannot go into set_partition:

# error: 'use_remote_server' belongs to .set_distribution()
create_schema('x')
    .fields({'id': {type: int64}})
    .set_partition({'id': {period: 10000, use_remote_server: true}});