OpenSlides/docs/interfaces/datastore-service.txt

# Datastore Interface

Enum EventType {
    Create,
    Update,
    Delete,
    Restore,
}

Exception ModelDoesNotExist(model: Fqid);
Exception ModelExist(model: Fqid);
Exception ModelNotDeleted(model: Fqid);
Exception ModelLocked(key: Fqid | Fqfield | CollectionField);
Exception InvalidFormat(msg: string);
Exception InvalidRequest(msg: string);

# Note: Error returns via HTTP 400:
Interface ErrorResponse {
    error: InvalidFormatData |
        InvalidRequestData |
        ModelDoesNotExistData |
        ModelExistData |
        ModelMotDeletedData |
        ModelLockedData;
}
Interface InvalidFormatData {
    type: 1;
    msg: string;
}
Interface InvalidRequestData {
    type: 2;
    msg: string;
Interface ModelDoesNotExistData {
    type: 3;
    fqid: string;
}
Interface ModelExistData {
    type: 4;
    fqid: string;
}
Interface ModelNotDeletedData {
    type: 5;
    fqid: string;
}
Interface ModelLockedData {
    type: 6;
    key: string;
}

## Writer
# Note: Different host and port than the reader!

/**
 * Writes Events into the datastore.
 * Url: POST to /datastore/writer/write
 *
 * @throws ModelDoesNotExist
 * @throws ModelExists
 * @throws ModelLocked
 * @throws InvalidFormat
 * @throws ModelNotDeleted
 */
write(request: WriteRequest): void publishes ModifiedFieldsEvent

Interface WriteRequest {
    events: (CreateEvent | RestoreEvent | UpdateEvent | DeleteEvent)[];
    information: {
        <fqid>: Object
    };
    user_id: number;
    locked_fields: {
        <fqid>: Position;
        <fqfield>: Position;
        <CollectionField>: Position;
    }
}

Interface CreateEvent {
    type: 'create';
    fqid: Fqid;
    fields: {
        <field>: Value;
    }
}

// Note: For deleting keys, they must be set to `None`. These keys
// will be removed from the model.
Interface UpdateEvent {
    type: 'update';
    fqid: Fqid;
    fields: {
        <field>: Value;
    }
}

Interface RestoreEvent {
    type: 'restore';
    fqid: Fqid;
}

Interface DeleteEvent {
    type: 'delete';
    fqid: Fqid;
}

// Note: The modified fqfields include:
// - all updated fqfields
// - all deleted fqfields
// - all fqfields of all deleted models
// - all fqfields of all created models
// - all fqfields of all restored models (logically the same as created)
Event ModifiedFieldsEvent on topic ModifiedFields {
    modified: Fqfield[];
}

/**
 * Gibt n sequentielle Ids für die gegebene Collection zurück.
 * Url: POST to /datastore/writer/get_ids
 */
getIds(collection: Collection, n: number): Id[]

## Reader
# Note: Different host and port than the writer!

/** Common notes:
 * - parameter `position`: Optional, if given reads the data to this position.
 * - parameter `mapped_fields`: List of fields, that should onl be present in the response.
 * - All operations adds the fields `meta_position` and `meta_deleted` to the models.
 * - The InvalidFormat exception can always be thrown, if the requested formats are
 *   wrong, including something like empty collections, ...
 */

/**
 * Returns a model. Deleted models are not returned (and handled as a ModelDoesNotExit)
 *
 * @throws ModelDoesNotExist
 * @throws InvalidFormat
 */
get(model: Fqid, position?: Position, mapped_fields?: fields[]): Partial<Model>;

/**
 * Analogous to `get`, but also finds deleted models (see `meta_deleted` in the model)
 *
 * @throws ModelDoesNotExist
 * @throws InvalidFormat
 */
getWithDeleted(model: Fqid, position?: Position, mapped_fields?: Field[]): Partial<Model>;

/**
 * Returns multiple (non-deleted) models of a collection. If one id is not found, it is
 * not included in the response instead of throwing a ModelDoesNotExist.
 */
getMany(collection: Collection, ids: Id[], position?: Position, mapped_fields?: Field[]): Partial<Model>[];

/**
 * Analogous to `getMany`, but includes deleted instances.
 *
 * @throws InvalidFormat
 */
getManyWithDeleted(collection: Collection, ids: Id[], position?: Position, mapped_fields?: Field[]): Partial<Model>[];

/**
 * Returns all (non-deleted) modells of one collection. It is not possible to specify
 * an id, so this method can not be used, if the user browses the history. It should
 * be noted, that it is highly disencouraged to use this method, becuase it might
 * return a huge amount of data.
 */
getAll(collection: Collection, mapped_fields?: Field[]): Partial<Model>[];

/**
 * Like `getAll`, but with deleted models included.
 *
 * @throws InvalidFormat
 */
getAllWithDeleted(collection: Collection, meeting_id?: Id, mapped_fields?: Field[]): Partial<Model>[];

/**
 * Like `getAll`, but returns only all deleted models.
 *
 * @throws InvalidFormat
 */
getAllOnlyDeleted(collection: Collection, meeting_id?: Id, mapped_fields?: Field[]): Partial<Model>[];

/**
 * Returns all models of one collection, that satisifes the filter condition. This method
 * does not take a position and can not be used when browsing the history.
 *
 * @throws InvalidFormat
 */
filter(collection: Collection, filter: Filter, mapped_fields?: Field[]): Partial<Model>[]

/**
 * See `filter`, returns true, if at least one model was found. The returned position is
 * the highest position in the complete datastore.
 *
 * @throws InvalidFormat
 */
exists(collection: Collection, filter: Filter): {exists: boolean; position: Position;}

/**
 * See `filter`, returns the amount of found models. The returned position is
 * the highest position in the complete datastore.
 *
 * @throws InvalidFormat
 */
count(collection: Collection, filter: Filter): {count: number; position: Position;}

/**
 * Executes a min aggregation about all models of one collection, that
 * satisfy the filter condition.
 *
 * @throws InvalidFormat
 */
min(collection: Collection, filter: Filter): {min: Value; position: Position;}

/**
 * Executes a max aggregation about all models of one collection, that
 * satisfy the filter condition.
 *
 * @throws InvalidFormat
 */
max(collection: Collection, filter: Filter): {min: Value; position: Position;}

Type Filter = And | Or | Not | FilterOperator

/**
 * The filter predicate. M[field] states the value of the field of a model M.
 * For all operations the predicate if true, if `M[field] <op> value` is true.
 */
Interface FilterOperator {
    field: Field;
    value: Value | null;
    operator: '==' | '!=' | '<' | '>' | '>=' | '<=';
}

Interface Not {
    not: Filter;
}

Interface And {
    and: Filter[];
}

Interface Or {
    or: Filter[];
}