.. # # This file is a part of the CaosDB Project. # # Copyright (C) 2021 Timm Fitschen # Copyright (C) 2021 IndiScale GmbH # # This program is free software: you can redistribute it and/or modify # it under the terms of the GNU Affero General Public License as # published by the Free Software Foundation, either version 3 of the # License, or (at your option) any later version. # # This program is distributed in the hope that it will be useful, # but WITHOUT ANY WARRANTY; without even the implied warranty of # MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the # GNU Affero General Public License for more details. # # You should have received a copy of the GNU Affero General Public License # along with this program. If not, see . # # .. _package_caosdb.entity.v1: ####################################### caosdb.entity.v1 ####################################### .. toctree:: :hidden: .. _ref_caosdb/entity/v1/main.proto: caosdb/entity/v1/main.proto ================================================================== This is the main file of the caosdb.entity.v1 package. .. _ref_caosdb.entity.v1.CollectionValues: CollectionValues ------------------------------------------------------------------ Represents collection values (e.g. for lists). .. csv-table:: CollectionValues type fields :header: "Field", "Type", "Label", "Description" :widths: auto "values", ":ref:`ScalarValue`", "repeated", "List of scalar values." .. _ref_caosdb.entity.v1.DataType: DataType ------------------------------------------------------------------ The property value's data type. .. csv-table:: DataType type fields :header: "Field", "Type", "Label", "Description" :widths: auto "atomic_data_type", ":ref:`AtomicDataType`", "", "The atomic data types." "list_data_type", ":ref:`ListDataType`", "", "A list data type." "reference_data_type", ":ref:`ReferenceDataType`", "", "A reference data type." .. _ref_caosdb.entity.v1.DeleteRequest: DeleteRequest ------------------------------------------------------------------ Single delete request (by id) .. csv-table:: DeleteRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "A single id" .. _ref_caosdb.entity.v1.DeleteResponse: DeleteResponse ------------------------------------------------------------------ Response to a single delete request. .. csv-table:: DeleteResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id_response", ":ref:`IdResponse`", "", "Id and messages of the deleted entity." .. _ref_caosdb.entity.v1.Entity: Entity ------------------------------------------------------------------ This is the main class for CaosDB's entities. .. csv-table:: Entity type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "Entity ID. The entity id is the primary key for all entities." "name", ":ref:`string`", "", "Entity name. The entity name is a possibly ambiguous identifier which is intended for human readers. In some cases, names can be restricted to be unique when this makes sense, but only as means to prevent the creation of duplicates." "description", ":ref:`string`", "", "Entity description. A short description of the purpose and meaning of an entity which is intended for human readers." "version", ":ref:`Version`", "", "Entity version. This entity message represents only one version of a multitude of versions of the same entity (i.e. they have the same Entity ID). The different versions represent the change of an entity through transactions." "role", ":ref:`EntityRole`", "", "Entity role (e.g. RecordType, Property, Record)" "unit", ":ref:`string`", "", "Default unit of this entity (only used by properties)." "data_type", ":ref:`DataType`", "", "Default data type of this entity (only used by properties)." "value", ":ref:`Value`", "", "Default value of this entity (only used by properties)." "properties", ":ref:`Property`", "repeated", "Properties of this entity." "parents", ":ref:`Parent`", "repeated", "Parents of this entity." "file_descriptor", ":ref:`FileDescriptor`", "", "File meta data. The actual binary data has to uploaded or downloaded using the File message." .. _ref_caosdb.entity.v1.EntityACL: EntityACL ------------------------------------------------------------------ Entity Access Controll List (ACL) .. csv-table:: EntityACL type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "The entity id" "rules", ":ref:`EntityPermissionRule`", "repeated", "The rules which make up the ACL" "permission", ":ref:`EntityAclPermission`", "", "relevant permissions of the current session, e.g. if the current user is allowed to update the ACL. This is read-only and will be ignored by the server." .. _ref_caosdb.entity.v1.EntityPermissionRule: EntityPermissionRule ------------------------------------------------------------------ Permission rules for Entity ACL .. csv-table:: EntityPermissionRule type fields :header: "Field", "Type", "Label", "Description" :widths: auto "role", ":ref:`string`", "", "The role for which this rule applies" "priority", ":ref:`bool`", "", "Is priority?" "grant", ":ref:`bool`", "", "Is grant?" "permissions", ":ref:`EntityPermission`", "repeated", "permissions" "capabilities", ":ref:`EntityPermissionRuleCapability`", "repeated", "capabilities" .. _ref_caosdb.entity.v1.EntityRequest: EntityRequest ------------------------------------------------------------------ Wraps an entity and associates it with a previous file upload via a transmission id. .. csv-table:: EntityRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity", ":ref:`Entity`", "", "The entity." "upload_id", ":ref:`FileTransmissionId`", "", "The transmission id (if any). Note: upload_ids are only meaningful for File entities." .. _ref_caosdb.entity.v1.EntityResponse: EntityResponse ------------------------------------------------------------------ Wraps an entity and associates it with a transimission id for a file download .. csv-table:: EntityResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity", ":ref:`Entity`", "", "The entity." "download_id", ":ref:`FileTransmissionId`", "", "The transmission id (if any). Note: download_ids are only meaningful for File entities." "errors", ":ref:`Message`", "repeated", "Errors for this entity which occurred during the current transaction. The presence of errors indicates that a transaction was not successful and the errors describe why this is the case." "warnings", ":ref:`Message`", "repeated", "Warnings for this entity which occurred during the current transaction, but the transaction was nevertheless successful. The presence of warnings indicates that the entity is in an undesired or non-standard state itself or in an undesired or non-standard relation to other entities or the server's state or configuration. This might cause errors in the future and should be remedied if possible." "infos", ":ref:`Message`", "repeated", "Info messages for this entity which may inform the client about anything related to the transaction or the new state of the entity itself or in relation to other entities or the server's state or configuration." .. _ref_caosdb.entity.v1.FileChunk: FileChunk ------------------------------------------------------------------ Stores a single chunk of a file .. csv-table:: FileChunk type fields :header: "Field", "Type", "Label", "Description" :widths: auto "file_transmission_id", ":ref:`FileTransmissionId`", "", "Temporary identifier containing the file and registration_id." "data", ":ref:`bytes`", "", "Binary data of a chunk." .. _ref_caosdb.entity.v1.FileDescriptor: FileDescriptor ------------------------------------------------------------------ The file descriptor contains the meta data of the file which describes the file and where the binary data can be retrieved. .. csv-table:: FileDescriptor type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity_id", ":ref:`string`", "", "The corresponding file entity." "path", ":ref:`string`", "", "The path of this file in the internal file system." "size", ":ref:`int64`", "", "The size of the file" "hashes", ":ref:`Hash`", "repeated", "Hash sums for consistency checks." .. _ref_caosdb.entity.v1.FileDownloadRequest: FileDownloadRequest ------------------------------------------------------------------ Request for a file download which has been registered previously. .. csv-table:: FileDownloadRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "file_transmission_id", ":ref:`FileTransmissionId`", "", "Request the next chunk for this file." .. _ref_caosdb.entity.v1.FileDownloadResponse: FileDownloadResponse ------------------------------------------------------------------ Response containing a chunk of a file. .. csv-table:: FileDownloadResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "status", ":ref:`TransmissionStatus`", "", "Status of the download" "chunk", ":ref:`FileChunk`", "", "A single file chunk" .. _ref_caosdb.entity.v1.FileTransmissionId: FileTransmissionId ------------------------------------------------------------------ Temporary identifier of a single file during a transmission. .. csv-table:: FileTransmissionId type fields :header: "Field", "Type", "Label", "Description" :widths: auto "registration_id", ":ref:`string`", "", "The registration id which has been issued by the target of the trans" "file_id", ":ref:`string`", "", "A temporary identifier which identifies the file of this chunk. The file_id is also used by transaction to associate entities (which are to be inserted or updated) with a binary blob." .. _ref_caosdb.entity.v1.FileTransmissionSettings: FileTransmissionSettings ------------------------------------------------------------------ Settings for the the file transmission. .. csv-table:: FileTransmissionSettings type fields :header: "Field", "Type", "Label", "Description" :widths: auto "max_chunk_size", ":ref:`int64`", "", "The maximum chunk size." "max_file_size", ":ref:`int64`", "", "The maximum file size." .. _ref_caosdb.entity.v1.FileUploadRequest: FileUploadRequest ------------------------------------------------------------------ Request for a file upload which has been registered previously. Chunks may be send in any order. .. csv-table:: FileUploadRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "chunk", ":ref:`FileChunk`", "", "A single file chunk" .. _ref_caosdb.entity.v1.FileUploadResponse: FileUploadResponse ------------------------------------------------------------------ Response of the server upon a finished FileUpload. .. csv-table:: FileUploadResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "status", ":ref:`TransmissionStatus`", "", "Status of the upload." .. _ref_caosdb.entity.v1.FindQueryResult: FindQueryResult ------------------------------------------------------------------ Result of a FIND query. .. csv-table:: FindQueryResult type fields :header: "Field", "Type", "Label", "Description" :widths: auto "result_set", ":ref:`EntityResponse`", "repeated", "Entities in the result set." .. _ref_caosdb.entity.v1.Hash: Hash ------------------------------------------------------------------ This represents a hash sum of a file. .. csv-table:: Hash type fields :header: "Field", "Type", "Label", "Description" :widths: auto "algorithm", ":ref:`string`", "", "The algorithm of the hash sum, e.g. SHA512" "value", ":ref:`string`", "", "The value of the hash sum" .. _ref_caosdb.entity.v1.IdResponse: IdResponse ------------------------------------------------------------------ A response containing only the id (of a deleted, inserted, or updated entity) and the usual trias of entity messages. .. csv-table:: IdResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "The entity id." "version", ":ref:`Version`", "", "The entity version." "errors", ":ref:`Message`", "repeated", "Errors for this entity which occurred during the current transaction. The presence of errors indicates that a transaction was not successful and the errors describe why this is the case." "warnings", ":ref:`Message`", "repeated", "Warnings for this entity which occurred during the current transaction, but the transaction was nevertheless successful. The presence of warnings indicates that the entity is in an undesired or non-standard state itself or in an undesired or non-standard relation to other entities or the server's state or configuration. This might cause errors in the future and should be remedied if possible." "infos", ":ref:`Message`", "repeated", "Info messages for this entity which may inform the client about anything related to the transaction or the new state of the entity itself or in relation to other entities or the server's state or configuration." .. _ref_caosdb.entity.v1.InsertRequest: InsertRequest ------------------------------------------------------------------ Request to insert a single entity. .. csv-table:: InsertRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity_request", ":ref:`EntityRequest`", "", "The new entity." .. _ref_caosdb.entity.v1.InsertResponse: InsertResponse ------------------------------------------------------------------ Response to a single insert request. .. csv-table:: InsertResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id_response", ":ref:`IdResponse`", "", "Id and messages of the inserted entity." .. _ref_caosdb.entity.v1.ListDataType: ListDataType ------------------------------------------------------------------ Data type for list value. .. csv-table:: ListDataType type fields :header: "Field", "Type", "Label", "Description" :widths: auto "atomic_data_type", ":ref:`AtomicDataType`", "", "List of atomic data types (e.g. List of DOUBLE)" "reference_data_type", ":ref:`ReferenceDataType`", "", "List of reference (e.g. List of Person(s))" .. _ref_caosdb.entity.v1.Message: Message ------------------------------------------------------------------ Messages are used by server's or client's to transport *transient* information, e.g. general information about a transaction, warnings, or errors. .. csv-table:: Message type fields :header: "Field", "Type", "Label", "Description" :widths: auto "code", ":ref:`int32`", "", "The code is a machine-readable identifier." "description", ":ref:`string`", "", "A short description of the message which is indented for human readers." .. _ref_caosdb.entity.v1.MultiRetrieveEntityACLRequest: MultiRetrieveEntityACLRequest ------------------------------------------------------------------ Request of the MultiRetrieveEntityACL rpc .. csv-table:: MultiRetrieveEntityACLRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "repeated", "The requested entity ids." .. _ref_caosdb.entity.v1.MultiRetrieveEntityACLResponse: MultiRetrieveEntityACLResponse ------------------------------------------------------------------ Response of the MultiRetrieveEntityACL rpc .. csv-table:: MultiRetrieveEntityACLResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "acls", ":ref:`EntityACL`", "repeated", "The entities ACLs" .. _ref_caosdb.entity.v1.MultiTransactionRequest: MultiTransactionRequest ------------------------------------------------------------------ Wraps multiple sub-transaction requests of mixed types. .. csv-table:: MultiTransactionRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "requests", ":ref:`TransactionRequest`", "repeated", "The actual payload." .. _ref_caosdb.entity.v1.MultiTransactionResponse: MultiTransactionResponse ------------------------------------------------------------------ Wraps the reponses to multiple sub-transactions of mixed types. .. csv-table:: MultiTransactionResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "responses", ":ref:`TransactionResponse`", "repeated", "The actual payload." "transaction_errors", ":ref:`Message`", "repeated", "Transaction errors." "transaction_warnings", ":ref:`Message`", "repeated", "Transaction warnings." "transaction_infos", ":ref:`Message`", "repeated", "Transaction info messages." .. _ref_caosdb.entity.v1.MultiUpdateEntityACLRequest: MultiUpdateEntityACLRequest ------------------------------------------------------------------ Request of the MultiUpdateEntityACL rpc .. csv-table:: MultiUpdateEntityACLRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "acls", ":ref:`EntityACL`", "repeated", "The requested entity ids." .. _ref_caosdb.entity.v1.MultiUpdateEntityACLResponse: MultiUpdateEntityACLResponse ------------------------------------------------------------------ Response of the MultiUpdateEntityACL rpc .. _ref_caosdb.entity.v1.Parent: Parent ------------------------------------------------------------------ Parent of an entity. .. csv-table:: Parent type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "ID of the parernt entity." "name", ":ref:`string`", "", "Name of the parernt entity." "description", ":ref:`string`", "", "Description of the parent entity." "errors", ":ref:`Message`", "repeated", "Errors of this parent" "warnings", ":ref:`Message`", "repeated", "Warnings of this parent" "infos", ":ref:`Message`", "repeated", "Info messages of this parent" .. _ref_caosdb.entity.v1.Property: Property ------------------------------------------------------------------ Property of an entity. Don't confuse with an Entity with role="Property" .. csv-table:: Property type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "ID of the implemented Entity" "name", ":ref:`string`", "", "Property name" "description", ":ref:`string`", "", "Property description" "value", ":ref:`Value`", "", "Property value" "importance", ":ref:`Importance`", "", "Property importance" "unit", ":ref:`string`", "", "Property unit" "data_type", ":ref:`DataType`", "", "Property datatype" "errors", ":ref:`Message`", "repeated", "Errors of this property" "warnings", ":ref:`Message`", "repeated", "Warnings of this property" "infos", ":ref:`Message`", "repeated", "Info messages of this property" .. _ref_caosdb.entity.v1.Query: Query ------------------------------------------------------------------ Query message. Currently this messge only wraps the query string. This might be extended in the future. .. csv-table:: Query type fields :header: "Field", "Type", "Label", "Description" :widths: auto "query", ":ref:`string`", "", "The string representation of the query, e.g. "FIND Person WITH name = Aisha"" .. _ref_caosdb.entity.v1.ReferenceDataType: ReferenceDataType ------------------------------------------------------------------ Data type for references to other entities. .. csv-table:: ReferenceDataType type fields :header: "Field", "Type", "Label", "Description" :widths: auto "name", ":ref:`string`", "", "The name of the record type which defines the scope of the reference." .. _ref_caosdb.entity.v1.RegisterFileUploadRequest: RegisterFileUploadRequest ------------------------------------------------------------------ Register a file upload. .. _ref_caosdb.entity.v1.RegisterFileUploadResponse: RegisterFileUploadResponse ------------------------------------------------------------------ Response of the file server upon an upload registration request. .. csv-table:: RegisterFileUploadResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "status", ":ref:`RegistrationStatus`", "", "Whether the server accepted or rejected the registration." "registration_id", ":ref:`string`", "", "The registration id is used to identify chunks and files which belong to the same upload ." "upload_settings", ":ref:`FileTransmissionSettings`", "", "The server's transmission settings for the upload." .. _ref_caosdb.entity.v1.RetrieveRequest: RetrieveRequest ------------------------------------------------------------------ Single retrieve request (by query or by id) .. csv-table:: RetrieveRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "A single id" "query", ":ref:`Query`", "", "A query" "register_file_download", ":ref:`bool`", "", "Is the client requesting to download the file associated with the retrieved entity or query results?" .. _ref_caosdb.entity.v1.RetrieveResponse: RetrieveResponse ------------------------------------------------------------------ Response to a retrieve request .. csv-table:: RetrieveResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity_response", ":ref:`EntityResponse`", "", "Result of a request by id or any other unique identifier." "find_result", ":ref:`FindQueryResult`", "", "Result of a FIND query" "select_result", ":ref:`SelectQueryResult`", "", "Result of a SELECT query" "count_result", ":ref:`int64`", "", "Result of a COUNT query" .. _ref_caosdb.entity.v1.ScalarValue: ScalarValue ------------------------------------------------------------------ A scalar property value. .. csv-table:: ScalarValue type fields :header: "Field", "Type", "Label", "Description" :widths: auto "integer_value", ":ref:`int64`", "", "The value as integer" "double_value", ":ref:`double`", "", "The value as double" "boolean_value", ":ref:`bool`", "", "The value as bool" "string_value", ":ref:`string`", "", "The value as string. For the empty string, you may use special_value." "special_value", ":ref:`SpecialValue`", "", "The value is a special value (e.g. NULL or the empty string)" .. _ref_caosdb.entity.v1.SelectQueryColumn: SelectQueryColumn ------------------------------------------------------------------ A single header column of the result of a SELECT query .. csv-table:: SelectQueryColumn type fields :header: "Field", "Type", "Label", "Description" :widths: auto "name", ":ref:`string`", "", "The column name. This is one of the SELECT'ed fields." .. _ref_caosdb.entity.v1.SelectQueryHeader: SelectQueryHeader ------------------------------------------------------------------ The header line of the result of a SELECT query .. csv-table:: SelectQueryHeader type fields :header: "Field", "Type", "Label", "Description" :widths: auto "columns", ":ref:`SelectQueryColumn`", "repeated", "List of columns in this table. The order defines the order of the cells in each of the SelectQueryRows." .. _ref_caosdb.entity.v1.SelectQueryResult: SelectQueryResult ------------------------------------------------------------------ A table which is a result of a SELECT query .. csv-table:: SelectQueryResult type fields :header: "Field", "Type", "Label", "Description" :widths: auto "header", ":ref:`SelectQueryHeader`", "", "The header contains the SELECT'ed fields" "data_rows", ":ref:`SelectQueryRow`", "repeated", "The actual results" .. _ref_caosdb.entity.v1.SelectQueryRow: SelectQueryRow ------------------------------------------------------------------ A single result row of a SELECT query .. csv-table:: SelectQueryRow type fields :header: "Field", "Type", "Label", "Description" :widths: auto "cells", ":ref:`Value`", "repeated", "The cells of the table row contain the value of the SELECT'ed fields. The order of the cells follows the order of the columns of the SelectQueryHeader." .. _ref_caosdb.entity.v1.TransactionRequest: TransactionRequest ------------------------------------------------------------------ Single request containing either a query, an id or a complete entity. .. csv-table:: TransactionRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "retrieve_request", ":ref:`RetrieveRequest`", "", "Single request for a retrieve transaction." "update_request", ":ref:`UpdateRequest`", "", "Single request for an update transaction." "insert_request", ":ref:`InsertRequest`", "", "Single request for an insert transaction." "delete_request", ":ref:`DeleteRequest`", "", "Single request for a delete transaction." .. _ref_caosdb.entity.v1.TransactionResponse: TransactionResponse ------------------------------------------------------------------ Single response containing either an id, a COUNT query result, a SELECT-table or complete entities. .. csv-table:: TransactionResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "delete_response", ":ref:`DeleteResponse`", "", "Single response to a delete transaction." "update_response", ":ref:`UpdateResponse`", "", "Single response to an update transaction." "retrieve_response", ":ref:`RetrieveResponse`", "", "Single response to a retrieve transaction." "insert_response", ":ref:`InsertResponse`", "", "Single response to an insert transaction." .. _ref_caosdb.entity.v1.UpdateRequest: UpdateRequest ------------------------------------------------------------------ Request to update a single Entity .. csv-table:: UpdateRequest type fields :header: "Field", "Type", "Label", "Description" :widths: auto "entity_request", ":ref:`EntityRequest`", "", "The entity which is to be updated." .. _ref_caosdb.entity.v1.UpdateResponse: UpdateResponse ------------------------------------------------------------------ Response to a single update request. .. csv-table:: UpdateResponse type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id_response", ":ref:`IdResponse`", "", "Id and messages of the updated entity." .. _ref_caosdb.entity.v1.Value: Value ------------------------------------------------------------------ The value of a property. .. csv-table:: Value type fields :header: "Field", "Type", "Label", "Description" :widths: auto "scalar_value", ":ref:`ScalarValue`", "", "The scalar values." "list_values", ":ref:`CollectionValues`", "", "The list values." .. _ref_caosdb.entity.v1.Version: Version ------------------------------------------------------------------ Version of an entity. .. csv-table:: Version type fields :header: "Field", "Type", "Label", "Description" :widths: auto "id", ":ref:`string`", "", "Version id" .. _ref_caosdb.entity.v1.AtomicDataType: AtomicDataType ------------------------------------------------------------------ Atomic data types. .. csv-table:: Enum AtomicDataType values :header: "Name", "Number", "Description" :widths: auto "ATOMIC_DATA_TYPE_UNSPECIFIED", "0", "The data type is unset/unknown." "ATOMIC_DATA_TYPE_TEXT", "1", "TEXT data type." "ATOMIC_DATA_TYPE_DOUBLE", "2", "DOUBLE data type." "ATOMIC_DATA_TYPE_DATETIME", "3", "DATETIME data type." "ATOMIC_DATA_TYPE_INTEGER", "4", "INTEGER data type." "ATOMIC_DATA_TYPE_BOOLEAN", "5", "BOOLEAN data type." .. _ref_caosdb.entity.v1.EntityAclPermission: EntityAclPermission ------------------------------------------------------------------ Entity ACL Permission indicates whether the current user is allowed to update the Entity's ACL. .. csv-table:: Enum EntityAclPermission values :header: "Name", "Number", "Description" :widths: auto "ENTITY_ACL_PERMISSION_UNSPECIFIED", "0", "UNSPECIFIED, effectively means "NO"" "ENTITY_ACL_PERMISSION_EDIT_ACL", "1", "Non-priority rules may be edited." "ENTITY_ACL_PERMISSION_EDIT_PRIORITY_ACL", "2", "Priority and non-priority rules may be edited." .. _ref_caosdb.entity.v1.EntityPermission: EntityPermission ------------------------------------------------------------------ Entity permissions .. csv-table:: Enum EntityPermission values :header: "Name", "Number", "Description" :widths: auto "ENTITY_PERMISSION_UNSPECIFIED", "0", "Unspecified permission." "ENTITY_PERMISSION_RETRIEVE_ENTITY", "1", "Permission to retrieve the full entity (name, description, data type, ...) with all parents and properties (unless prohibited by another rule on the property level)." "ENTITY_PERMISSION_RETRIEVE_ACL", "2", "Permission to retrieve the full and final ACL of this entity." "ENTITY_PERMISSION_RETRIEVE_HISTORY", "3", "Permission to retrieve the history of this entity." "ENTITY_PERMISSION_RETRIEVE_OWNER", "4", "Permission to retrieve the owner(s) of this entity." "ENTITY_PERMISSION_RETRIEVE_FILE", "5", "Permission to download the file belonging to this entity." "ENTITY_PERMISSION_DELETE", "6", "Permission to delete an entity." "ENTITY_PERMISSION_EDIT_ACL", "7", "Permission to change the user-specified part of this entity's ACL. Roles with this Permission are called 'Owners'." "ENTITY_PERMISSION_UPDATE_DESCRIPTION", "8", "Permission to change the value of this entity." "ENTITY_PERMISSION_UPDATE_VALUE", "9", "Permission to change the value of this entity." "ENTITY_PERMISSION_UPDATE_ROLE", "10", "Permission to change the role of this entity." "ENTITY_PERMISSION_UPDATE_REMOVE_PARENT", "11", "Permission to remove parents from this entity." "ENTITY_PERMISSION_UPDATE_ADD_PARENT", "12", "Permission to add a parent to this entity." "ENTITY_PERMISSION_UPDATE_REMOVE_PROPERTY", "13", "Permission to remove properties from this entity." "ENTITY_PERMISSION_UPDATE_ADD_PROPERTY", "14", "Permission to add a property to this entity." "ENTITY_PERMISSION_UPDATE_NAME", "15", "Permission to change the name of this entity." "ENTITY_PERMISSION_UPDATE_DATA_TYPE", "16", "Permission to change the data type of this entity." "ENTITY_PERMISSION_UPDATE_REMOVE_FILE", "17", "Permission to delete the file of this entity." "ENTITY_PERMISSION_UPDATE_ADD_FILE", "18", "Permission to set a file for this entity." "ENTITY_PERMISSION_UPDATE_MOVE_FILE", "19", "Permission to move an existing file to a new location." "ENTITY_PERMISSION_USE_AS_REFERENCE", "20", "Permission to refer to this entity via a reference property." "ENTITY_PERMISSION_USE_AS_PROPERTY", "21", "Permission to implement this entity as a property." "ENTITY_PERMISSION_USE_AS_PARENT", "22", "Permission to use this entity as a super type for other entities." "ENTITY_PERMISSION_USE_AS_DATA_TYPE", "23", "Permission to use this entity as a data type for reference properties." "ENTITY_PERMISSION_UPDATE_QUERY_TEMPLATE_DEFINITION", "24", "Permission to update the query template definition of this QueryTemplate" .. _ref_caosdb.entity.v1.EntityPermissionRuleCapability: EntityPermissionRuleCapability ------------------------------------------------------------------ What (given enough permissions) can be done with an EntityPermissionRule. E.g. globel entity permission rules, which are to be specified in a configuration file cannot be deleted, thus they are missing the ENTITY_PERMISSION_RULE_CAPABILITY_DELETE capability. .. csv-table:: Enum EntityPermissionRuleCapability values :header: "Name", "Number", "Description" :widths: auto "ENTITY_PERMISSION_RULE_CAPABILITY_UNSPECIFIED", "0", "Unspecified capability." "ENTITY_PERMISSION_RULE_CAPABILITY_DELETE", "1", "This permission rule can be deleted/removed from the ACL" .. _ref_caosdb.entity.v1.EntityRole: EntityRole ------------------------------------------------------------------ The roles of entities. .. csv-table:: Enum EntityRole values :header: "Name", "Number", "Description" :widths: auto "ENTITY_ROLE_UNSPECIFIED", "0", "Unspecified role." "ENTITY_ROLE_RECORD_TYPE", "1", "RecordType" "ENTITY_ROLE_RECORD", "2", "Record" "ENTITY_ROLE_PROPERTY", "3", "Property" "ENTITY_ROLE_FILE", "4", "File" .. _ref_caosdb.entity.v1.Importance: Importance ------------------------------------------------------------------ The property importance. .. csv-table:: Enum Importance values :header: "Name", "Number", "Description" :widths: auto "IMPORTANCE_UNSPECIFIED", "0", "The importance is unset/unknown." "IMPORTANCE_OBLIGATORY", "1", "The property is obligatory for children of this entity. The server will flag an error when an obligatory property of a parent is missing during updates or insertions of a child entity. It says: "YOU MUST!"" "IMPORTANCE_RECOMMENDED", "2", "The property is recommended for children of this entity. The server will flag a warning when a recommended property of a parent is missing during updates or insertions of a child entity. It says: "YOU SHOULD!"" "IMPORTANCE_SUGGESTED", "3", "The property is merely suggested for children of this entity. It says: "YOU MAY WANT TO?"" "IMPORTANCE_FIX", "4", "The property is fix and child entities should not add this property to themselves (This is a bit like static in object-oriented programming languages). It says: "KINDLY IGNORE THIS ONE FOR CHILDREN OF THIS ENTITY"" .. _ref_caosdb.entity.v1.MessageCode: MessageCode ------------------------------------------------------------------ Messages codes. Entities and transactions contain errors, warnings and info messages which use these codes. .. csv-table:: Enum MessageCode values :header: "Name", "Number", "Description" :widths: auto "MESSAGE_CODE_UNSPECIFIED", "0", "Unspecific code. Use this for anything where a client is not expected to handle this message in a specific way." "MESSAGE_CODE_UNKNOWN", "1", "Unknown code. This value is a fall-back which may be used when the message code was not in this list. An unknown error code is a sign of a wrong otr out-dated implementation on either side." "MESSAGE_CODE_ENTITY_DOES_NOT_EXIST", "2", "The requested entity (retrieve, delete, or update) does not exist." "MESSAGE_CODE_ENTITY_HAS_NO_PROPERTIES", "3", "The entity has no properties." "MESSAGE_CODE_ENTITY_HAS_BEEN_DELETED_SUCCESSFULLY", "4", "This entity has been deleted successfully." "MESSAGE_CODE_ENTITY_HAS_UNQUALIFIED_PROPERTIES", "5", "On insert or update: Entity has unqualified properties." "MESSAGE_CODE_ENTITY_HAS_UNQUALIFIED_PARENTS", "6", "On insert or update: Entity has unqualified parents." "MESSAGE_CODE_ENTITY_HAS_NO_ID", "7", "On update: Entity, Property or Parent has no ID and the server is configured to require a valid ID for all entities which are to be updated and for their properties and parents as well." "MESSAGE_CODE_REQUIRED_BY_PERSISTENT_ENTITY", "8", "On delete: Entity is required by other entities which are not to be deleted." "MESSAGE_CODE_PROPERTY_HAS_NO_DATA_TYPE", "9", "Property has no datatype." "MESSAGE_CODE_ENTITY_HAS_NO_DESCRIPTION", "10", "Entity has no description." "MESSAGE_CODE_ENTITY_HAS_NO_NAME", "11", "Entity has no name." "MESSAGE_CODE_OBLIGATORY_PROPERTY_MISSING", "12", "On insert or update: An obligatory property is missing." "MESSAGE_CODE_ENTITY_HAS_NO_PARENTS", "13", "On insert or update: Entity has no parents." "MESSAGE_CODE_FILE_HAS_NO_TARGET_PATH", "14", "No target path specified." "MESSAGE_CODE_TARGET_PATH_NOT_ALLOWED", "15", "This target path is not allowed." "MESSAGE_CODE_TARGET_PATH_EXISTS", "16", "This target path does already exist." "MESSAGE_CODE_PROPERTY_HAS_NO_UNIT", "17", "Property has no unit." "MESSAGE_CODE_CANNOT_PARSE_VALUE", "18", "Cannot parse value." "MESSAGE_CODE_CHECKSUM_TEST_FAILED", "19", "Checksum test failed. File is corrupted." "MESSAGE_CODE_SIZE_TEST_FAILED", "20", "Size test failed. File is corrupted." "MESSAGE_CODE_CANNOT_CREATE_PARENT_FOLDER", "21", "Cannot create parent folder in the file system." "MESSAGE_CODE_FILE_HAS_NOT_BEEN_UPLOAED", "22", "File has not been uploaded." "MESSAGE_CODE_CANNOT_MOVE_FILE_TO_TARGET_PATH", "23", "Cannot move file to it's target folder." "MESSAGE_CODE_CANNOT_PARSE_DATETIME_VALUE", "24", "Cannot parse value as datetime value." "MESSAGE_CODE_CANNOT_PARSE_DOUBLE_VALUE", "25", "Cannot parse value as double value." "MESSAGE_CODE_CANNOT_PARSE_INT_VALUE", "26", "Cannot parse value as integer value." "MESSAGE_CODE_CANNOT_PARSE_BOOL_VALUE", "27", "Cannot parse value as boolean value (either 'true' or 'false', case insensitive)." "MESSAGE_CODE_FILE_NOT_FOUND", "28", "File could not be found." "MESSAGE_CODE_WARNING_OCCURED", "29", "A warning occured while processing an entity with the strict flag." "MESSAGE_CODE_ENTITY_NAME_IS_NOT_UNIQUE", "30", "On insert or update: Name is already in use. Choose a different name or reuse an existing entity." "MESSAGE_CODE_QUERY_EXCEPTION", "31", "This query finished with errors." "MESSAGE_CODE_TRANSACTION_ROLL_BACK", "32", "An unknown error occured during the transaction and it was rolled back." "MESSAGE_CODE_UNKNOWN_UNIT", "34", "Unknown unit. Values with this unit cannot be converted to other units when used in search queries." "MESSAGE_CODE_AUTHORIZATION_ERROR", "35", "You are not allowed to do this." "MESSAGE_CODE_REFERENCE_IS_NOT_ALLOWED_BY_DATA_TYPE", "36", "Reference not qualified. The value of this Reference Property is to be a child of its data type." "MESSAGE_CODE_ENTITY_NAME_DUPLICATES", "37", "This entity cannot be identified due to name duplicates." "MESSAGE_CODE_DATA_TYPE_NAME_DUPLICATES", "38", "This data type cannot be identified due to name duplicates." "MESSAGE_CODE_ENTITY_HAS_NO_NAME_OR_ID", "39", "This entity cannot be identified as it didn't come with a name or id." "MESSAGE_CODE_AFFILIATION_ERROR", "40", "Affiliation is not defined for this child-parent constellation." "MESSAGE_CODE_QUERY_PARSING_ERROR", "41", "An error occured during the parsing of this query. Maybe you were using a wrong syntax?" "MESSAGE_CODE_NAME_PROPERTIES_MUST_BE_TEXT", "42", "A property which has 'name' as its parent must have a TEXT data type." "MESSAGE_CODE_PARENT_DUPLICATES_WARNING", "43", "This entity had parent duplicates. That is meaningless and only one parent had been inserted." "MESSAGE_CODE_PARENT_DUPLICATES_ERROR", "44", "This entity had parent duplicates. Parent duplicates are meaningless and would be ignored (and inserted only once). But these parents had diverging inheritance instructions which cannot be processed." "MESSAGE_CODE_ATOMICITY_ERROR", "45", "One or more entities are not qualified. None of them have been inserted/updated/deleted." "MESSAGE_CODE_NO_SUCH_ENTITY_ROLE", "46", "There is no such role." "MESSAGE_CODE_REQUIRED_BY_UNQUALIFIED", "47", "This entity cannot be deleted due to dependency problems" "MESSAGE_CODE_ENTITY_HAS_UNQUALIFIED_REFERENCE", "48", "This entity has an unqualified reference. I.e. the referenced entity is not qualified for the transaction." "MESSAGE_CODE_REFERENCED_ENTITY_DOES_NOT_EXIST", "49", "Referenced entity does not exist." "MESSAGE_CODE_REFERENCE_NAME_DUPLICATES", "50", "This reference cannot be identified due to name duplicates." "MESSAGE_CODE_DATA_TYPE_INHERITANCE_AMBIGUOUS", "51", "The datatype which is to be inherited could not be detected due to divergent datatypes of at least two parents." "MESSAGE_CODE_DATA_TYPE_DOES_NOT_ACCEPT_COLLECTION_VALUES", "52", "This datatype does not accept collections of values (e.g. Lists)." "MESSAGE_CODE_CANNOT_PARSE_UNIT", "53", "This unit cannot be parsed." "MESSAGE_CODE_ADDITIONAL_PROPERTY", "54", "This property is an additional property which has no corresponding property among the properties of the parents." "MESSAGE_CODE_PROPERTY_WITH_DATA_TYPE_OVERRIDE", "55", "This property overrides the datatype." "MESSAGE_CODE_PROPERTY_WITH_DESCRIPTION_OVERRIDE", "56", "This property overrides the description." "MESSAGE_CODE_PROPERTY_WITH_NAME_OVERRIDE", "57", "This property overrides the name." "MESSAGE_CODE_INTEGER_VALUE_OUT_OF_RANGE", "58", "Indicates that this server cannot process this integer value because it is out of range. The integer range is an implementation detail and thus this can happen even though the API allows the value." "MESSAGE_CODE_INTEGRITY_VIOLATION", "59", "This entity caused an unexpected integrity violation. This is a strong indicator for a server bug. Please report." .. _ref_caosdb.entity.v1.RegistrationStatus: RegistrationStatus ------------------------------------------------------------------ Indicates whether a registration (for upload or download) has been accepted or rejected. .. csv-table:: Enum RegistrationStatus values :header: "Name", "Number", "Description" :widths: auto "REGISTRATION_STATUS_UNSPECIFIED", "0", "The registration status is unspecified." "REGISTRATION_STATUS_ACCEPTED", "1", "The registration has been accepted and the client may proceed with the actual transmissions." "REGISTRATION_STATUS_REJECTED", "2", "The registration has been rejected and the client should not try to proceed with the transmission." .. _ref_caosdb.entity.v1.SpecialValue: SpecialValue ------------------------------------------------------------------ Represents special values which are otherwise hard to transfer via protobuf. .. csv-table:: Enum SpecialValue values :header: "Name", "Number", "Description" :widths: auto "SPECIAL_VALUE_UNSPECIFIED", "0", "Represent the NULL value." "SPECIAL_VALUE_EMPTY_STRING", "1", "The empty string." .. _ref_caosdb.entity.v1.TransmissionStatus: TransmissionStatus ------------------------------------------------------------------ Indicates the state of an upload or a download (a stream of chunks). .. csv-table:: Enum TransmissionStatus values :header: "Name", "Number", "Description" :widths: auto "TRANSMISSION_STATUS_UNSPECIFIED", "0", "The transmission status is unspecified." "TRANSMISSION_STATUS_SUCCESS", "1", "The transmission has been successful." "TRANSMISSION_STATUS_ERROR", "2", "The transmission terminated with errors." "TRANSMISSION_STATUS_GO_ON", "3", "The transmission is incomplete and the client may send/request the next chunk." .. _ref_caosdb.entity.v1.EntityTransactionService: EntityTransactionService ------------------------------------------------------------------ Entity Transaction Service .. csv-table:: EntityTransactionService service methods :header: "Method Name", "Request Type", "Response Type", "Description" :widths: auto "MultiTransaction", ":ref:`ref_caosdb.entity.v1.MultiTransactionRequest`", ":ref:`ref_caosdb.entity.v1.MultiTransactionResponse`", "Issue multiple mixed requests" "MultiRetrieveEntityACL", ":ref:`ref_caosdb.entity.v1.MultiRetrieveEntityACLRequest`", ":ref:`ref_caosdb.entity.v1.MultiRetrieveEntityACLResponse`", "Request the Entity ACLs" "MultiUpdateEntityACL", ":ref:`ref_caosdb.entity.v1.MultiUpdateEntityACLRequest`", ":ref:`ref_caosdb.entity.v1.MultiUpdateEntityACLResponse`", "Set the Entity ACLs," .. _ref_caosdb.entity.v1.FileTransmissionService: FileTransmissionService ------------------------------------------------------------------ File Transaction Service .. csv-table:: FileTransmissionService service methods :header: "Method Name", "Request Type", "Response Type", "Description" :widths: auto "RegisterFileUpload", ":ref:`ref_caosdb.entity.v1.RegisterFileUploadRequest`", ":ref:`ref_caosdb.entity.v1.RegisterFileUploadResponse`", "Register a file upload. This needs to be done prior to the actual upload and prior to the transaction request which uses the uploaded files." "FileUpload", ":ref:`ref_caosdb.entity.v1.FileUploadRequest` stream", ":ref:`ref_caosdb.entity.v1.FileUploadResponse`", "The actual file upload. The upload has to be registered prior to this rpc." "FileDownload", ":ref:`ref_caosdb.entity.v1.FileDownloadRequest`", ":ref:`ref_caosdb.entity.v1.FileDownloadResponse` stream", "A file download. The download has to be registered prior this rpc in the RetrieveRequest."