OpenSlides/docs/interfaces/datastore-service.txt

247 lines
6.3 KiB
Plaintext
Raw Normal View History

2020-01-20 07:43:25 +01:00
# Datastore Interface
Enum EventType {
Create,
Update,
Delete,
Restore,
}
Exception ModelDoesNotExist(model: Fqid);
Exception ModelExist(model: Fqid);
Exception ModelNotDeleted(model: Fqid);
2020-01-22 11:39:51 +01:00
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;
}
2020-01-20 07:43:25 +01:00
## Writer
2020-01-22 11:39:51 +01:00
# Note: Different host and port than the reader!
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* Writes Events into the datastore.
* Url: POST to /datastore/writer/write
2020-01-20 07:43:25 +01:00
*
* @throws ModelDoesNotExist
* @throws ModelExists
* @throws ModelLocked
* @throws InvalidFormat
* @throws ModelNotDeleted
*/
2020-01-22 11:39:51 +01:00
write(request: WriteRequest): void publishes ModifiedFieldsEvent
2020-01-20 07:43:25 +01:00
Interface WriteRequest {
events: (CreateEvent | RestoreEvent | UpdateEvent | DeleteEvent)[];
information: {
<fqid>: Object
};
user_id: number;
locked_fields: {
<fqid>: Position;
2020-01-22 11:39:51 +01:00
<fqfield>: Position;
2020-01-20 07:43:25 +01:00
<CollectionField>: Position;
}
}
Interface CreateEvent {
2020-01-22 11:39:51 +01:00
type: 'create';
2020-01-20 07:43:25 +01:00
fqid: Fqid;
2020-01-22 11:39:51 +01:00
fields: {
2020-01-20 07:43:25 +01:00
<field>: Value;
}
}
2020-01-22 11:39:51 +01:00
// Note: For deleting keys, they must be set to `None`. These keys
// will be removed from the model.
2020-01-20 07:43:25 +01:00
Interface UpdateEvent {
2020-01-22 11:39:51 +01:00
type: 'update';
fqid: Fqid;
fields: {
<field>: Value;
2020-01-20 07:43:25 +01:00
}
}
Interface RestoreEvent {
2020-01-22 11:39:51 +01:00
type: 'restore';
2020-01-20 07:43:25 +01:00
fqid: Fqid;
}
Interface DeleteEvent {
2020-01-22 11:39:51 +01:00
type: 'delete';
2020-01-20 07:43:25 +01:00
fqid: Fqid;
}
2020-01-22 11:39:51 +01:00
// 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[];
2020-01-20 07:43:25 +01:00
}
2020-01-22 11:39:51 +01:00
/**
* Gibt n sequentielle Ids für die gegebene Collection zurück.
* Url: POST to /datastore/writer/get_ids
*/
getIds(collection: Collection, n: number): Id[]
2020-01-20 07:43:25 +01:00
2020-01-22 11:39:51 +01:00
## 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, ...
2020-01-20 07:43:25 +01:00
*/
/**
2020-01-22 11:39:51 +01:00
* Returns a model. Deleted models are not returned (and handled as a ModelDoesNotExit)
2020-01-20 07:43:25 +01:00
*
* @throws ModelDoesNotExist
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
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
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
getWithDeleted(model: Fqid, position?: Position, mapped_fields?: Field[]): Partial<Model>;
/**
2020-01-22 11:39:51 +01:00
* 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.
2020-01-20 07:43:25 +01:00
*/
getMany(collection: Collection, ids: Id[], position?: Position, mapped_fields?: Field[]): Partial<Model>[];
/**
2020-01-22 11:39:51 +01:00
* Analogous to `getMany`, but includes deleted instances.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
getManyWithDeleted(collection: Collection, ids: Id[], position?: Position, mapped_fields?: Field[]): Partial<Model>[];
/**
2020-01-22 11:39:51 +01:00
* 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.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
getAllWithDeleted(collection: Collection, meeting_id?: Id, mapped_fields?: Field[]): Partial<Model>[];
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* Like `getAll`, but returns only all deleted models.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
getAllOnlyDeleted(collection: Collection, meeting_id?: Id, mapped_fields?: Field[]): Partial<Model>[];
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* 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.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
filter(collection: Collection, filter: Filter, mapped_fields?: Field[]): Partial<Model>[]
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* See `filter`, returns true, if at least one model was found. The returned position is
* the highest position in the complete datastore.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
exists(collection: Collection, filter: Filter): {exists: boolean; position: Position;}
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* See `filter`, returns the amount of found models. The returned position is
* the highest position in the complete datastore.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
count(collection: Collection, filter: Filter): {count: number; position: Position;}
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* Executes a min aggregation about all models of one collection, that
* satisfy the filter condition.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
min(collection: Collection, filter: Filter): {min: Value; position: Position;}
2020-01-20 07:43:25 +01:00
/**
2020-01-22 11:39:51 +01:00
* Executes a max aggregation about all models of one collection, that
* satisfy the filter condition.
2020-01-20 07:43:25 +01:00
*
2020-01-22 11:39:51 +01:00
* @throws InvalidFormat
2020-01-20 07:43:25 +01:00
*/
2020-01-22 11:39:51 +01:00
max(collection: Collection, filter: Filter): {min: Value; position: Position;}
2020-01-20 07:43:25 +01:00
Type Filter = And | Or | Not | FilterOperator
/**
2020-01-22 11:39:51 +01:00
* 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.
2020-01-20 07:43:25 +01:00
*/
Interface FilterOperator {
field: Field;
value: Value | null;
operator: '==' | '!=' | '<' | '>' | '>=' | '<=';
}
Interface Not {
not: Filter;
}
Interface And {
and: Filter[];
}
Interface Or {
or: Filter[];
}