CaosDB.jl's API

The parent type of all CaosDB errors that can also be used for testing.

Struct containing Messages and codes for status codes<0 that do not correspond to errors or success.

Something went wrong on the client-side or the user is attempting to conduct an invalid operation.

A generic exception that will be raised in case of non-zero return values of the calls to libccaosdb. May carry a message string and a code.

function evaluate_return_code(code::Cint)

Evaluate the return code of a libccaosdb ccall and raise a GenericCaosDBException in case of a non-zero return code.

The minimum version of CaosDB's cpplib and C interface that is supported by this version of CaosDB.jl.

function get_ccaosdb_version()

Return the version of the CaosDB C interface that is used by CaosDB.jl.

get_env_fallback(var[, default])

Return the environmental variable var if it exists, default otherwise. If no default is given an empty string is returned instead.

connect(name::AbstractString="default")

Create a connection with name name from your configuration file, print the version of the server the connection is established to, and return the connection object.

Arguments

• name::AbstractString="default": The name of the configuration defined in your config json that will be used to connect to the CaosDB server defined therein. Default value is "default".

function connect_manually([;
    host::AbstractString="",
    port_str::AbstractString="undefined",
    cacert::AbstractString="",
    username::AbstractString="",
    password::AbstractString="undefined"]
)

Return a connection object created for the given host:port with an SSL certificate located at cacert with the given credentials.

Extended help

Arguments

• host::AbstractString="": The hostname of the CaosDB server. If none is provided, the CAOSDB_SERVER_HOST environmental variable is used instead. If that's not defined, "localhost" is used.
• port_str::AbstractString="undefined": The port of the CaosDB server, given as string. If none is provided, the CAOSDB_SERVER_GRPC_PORT_HTTPS environmental variable is used instead. If that's not defined, "8443" is used. The default value is "undefined" rather than an empty string because an empty string could be a valid port, too, i.e. the CaosDB server is available at host without a port.
• cacert::AbstractString="": The path to the SSL certificate of the CaosDB server. If none is provided, the CAOSDB_SERVER_CERT environmental variable is used instead.
• username::AbstractString="": The username with which to log in into the CaosDB server. If none is provided, the CAOSDB_USER environmental variable is used instead. If that's not defined, "admin" is used.
• password::AbstractString="undefined": The password with which to log in into the CaosDB server. If none is provided, the CAOSDB_PASSWORD environmental variable is used instead. If that's not defined, "caosdb" is used. The default value is "undefined" rather than an empty string to allow an empty password.

function append_parent(entity::Ref{_Entity}, parent::Ref{_Parent})

Append the given parent to the parents of the given entity.

function append_parents(entity::Ref{_Entity}, parents::Vector{Base.RefValue{_Parent}})

Append all given parents to the parents of the given entity.

function append_properties(entity::Ref{_Entity}, properties::Vector{Base.RefValue{_Property}})

Append all given properties to the properties of the given entity.

function append_property(entity::Ref{_Entity}, property::Ref{_Property})

Append the given property to the properties of the given entity.

function create_entity(name::AbstractString = "")

Return a new entity object. If a name was provided, set the name of the entity correspondingly.

function createfileentity(; localpath::AbstractString, remotepath::AbstractString, name::AbstractString = "", )

Return a new entity object with role File. local_path is the path of the file on the local file system. An exception is thrown if this file is not existent. remote_path is the path of the file on the remote caosdb server.

function create_parent(; name::AbstractString = "", id::AbstractString = "")

Create a parent object that can be appended to another _Entity. If name, id, or value are given, the parent's name, id, or value are set accordingly.

function create_property(;
    name::AbstractString = "",
    id::AbstractString = "",
    value::Union{AbstractString, Number, Bool} = "",
    datatype::Union{AbstractString,CaosDB.Constants.DATATYPE._DATATYPE} = "",
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION, Nothing} = nothing,
 )

Create a property object that can be appended to another _Entity. If name, id, or value are given, the property's name, id, or value are set accordingly. The datatype and its collection type can be specified with datatype and collection, respectively.

function create_property_entity(;
    name::AbstractString = "",
    datatype::Union{AbstractString,CaosDB.Constants.DATATYPE._DATATYPE} = "",
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION,Nothing} = nothing,
    unit::AbstractString = "",
)

Return a new entity object with role Record. If name, datatype, or unit were provided, its name, datatype (including whether its collection type), or unit are set accordingly.

 function create_record(name::AbstractString = "")

Return a new entity object with role Record. If a name was provided, its name is set accordingly.

function create_recordtype(name::AbstractString = "")

Return a new entity object with role RecordType. If a name was provided, its name is set accordingly.

function get_code(message::Ref{_Message})

Return the code of the given message.

function get_datatype(entity::Ref{_Entity})

Return a tuple that contains the name of the datatype of the given entity, and its collection type (nothing in case of a scalar datatype).

function get_datatype(entity::Ref{_Property})

Return a tuple that contains the name of the datatype of the given property, whether it is a reference, and whether it is a list.

function get_description(entity::Ref{_Entity})

Return the description of the given entity

function get_description(entity::Ref{_Message})

Return the description of the given message

function get_description(entity::Ref{_Parent})

Return the description of the given parent

function get_description(entity::Ref{_Property})

Return the description of the given property

function get_error(entity::Ref{_Entity}, index::Cint)

Return the error message of the given entity with the provided index.

function get_error(entity::Ref{_Entity}, index::Integer)

Convenience wrapper for get_error(::Ref{_Entity}, ::Cint). Convert index to Int32 and return the error at position index of the given entity.

function get_errors(entity::Ref{_Entity})

Return a Vector of all error messages attached to the given entity.

function get_id(entity::Ref{_Entity})

Return the id of the given entity

function get_id(entity::Ref{_Parent})

Return the id of the given parent

function get_id(entity::Ref{_Property})

Return the id of the given property

function get_importance(property::Ref{_Property})

Return the importance of the given property

function get_info(entity::Ref{_Entity}, index::Cint)

Return the info message of the given entity with the provided index.

function get_info(entity::Ref{_Entity}, index::Integer)

Convenience wrapper for get_info(::Ref{_Entity}, ::Cint). Convert index to Int32 and return the info at position index of the given entity.

function get_warnings(entity::Ref{_Entity})

Return a Vector of all info messages attached to the given entity.

function get_name(entity::Ref{_Entity})

Return the name of the given entity

function get_name(entity::Ref{_Parent})

Return the name of the given parent

function get_name(entity::Ref{_Property})

Return the name of the given property

function get_parent(entity::Ref{_Entity}, index::Cint)

Return the parent of the given entity at position index.

function get_parent(entity::Ref{_Entity}, index::Integer)

Convenience wrapper for get_parent(::Ref{_Entity}, ::Cint). Convert index to Int32 and return the parent at position index of the given entity.

function get_parents(entity::Ref{_Entity})

Return the vector of all parents of the given entity.

function get_properties(entity::Ref{_Entity})

Return the vector of all properties of the given entity.

function get_property(entity::Ref{_Entity}, index::Cint)

Return the property of the given entity at position index.

function get_property(entity::Ref{_Entity}, index::Integer)

Convenience wrapper for get_property(::Ref{_Entity}, ::Cint). Convert index to Int32 and return the property at position index of the given entity.

function get_role(entity::Ref{_Entity})

Return the role of the given entity.

function get_unit(entity::Ref{_Entity})

Return the unit of the given entity

function get_unit(entity::Ref{_Property})

Return the unit of the given property

function get_value(entity::Ref{_Entity})

Return the value of the given entity

function get_value(property::Ref{_Property})

Return the value of the given property

function get_version_id(entity::Ref{_Entity})

Return the version_id of the given entity

function get_warning(entity::Ref{_Entity}, index::Cint)

Return the warning message of the given entity with the provided index.

function get_warning(entity::Ref{_Entity}, index::Integer)

Convenience wrapper for get_warning(::Ref{_Entity}, ::Cint). Convert index to Int32 and return the warning at position index of the given entity.

function get_warnings(entity::Ref{_Entity})

Return a Vector of all warning messages attached to the given entity.

function has_errors(entity::Ref{_Entity})

Return true if the given entity has errors, false otherwise.

function has_warnings(entity::Ref{_Entity})

Return true if the given entity has warnings, false otherwise.

function remove_parent(entity::Ref{_Entity}, index::Cint)

Remove the parent at position index from the parents of the given entity.

function remove_property(entity::Ref{_Entity}, index::Cint)

Remove the property at position index from the properties of the given entity.

function set_datatype(
    entity::Ref{_Entity},
    datatype::AbstractString,
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION, Nothing}
)

Set the datatype of the given entity object to a reference to the given datatype name. Only possible if the role of the entity is "PROPERTY". Specify whether the datatype is a list by specifying a collection. If none is given, a scalar datatype is set.

function set_datatype(
    property::Ref{_Property},
    datatype::CaosDB.Constants.DATATYPE._DATATYPE,
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION, Nothing}
)

Set the datatype of the given property object to a reference to the given atomic datatype. Specify whether the datatype is a list by specifying a collection. If none is given, a scalar datatype is set.

function set_datatype(
    property::Ref{_Property},
    datatype::AbstractString,
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION, Nothing}
)

Set the datatype of the given property object to a reference to the given datatype name. Specify whether the datatype is a list by specifying a collection. If none is given, a scalar datatype is set.

function set_datatype(
    entity::Ref{_Entity},
    datatype::CaosDB.Constants.DATATYPE._DATATYPE,
    collection::Union{CaosDB.Constants.COLLECTION._COLLECTION, Nothing}
)

Set the datatype of the given entity object to a reference to the given atomic datatype. Only possible if the role of the entity is "PROPERTY". Specify whether the datatype is a list by specifying a collection. If none is given, a scalar datatype is set.

function set_datatype(entity::Ref{_Entity}, datatype::Tuple{Any, Any})

Convenience wrapper for the set_datatype functions s.th. expressions like set_datatype(entity_a, get_datatype(entity_b)) work.

function set_datatype(property::Ref{_Property}, datatype::Tuple{Any, Any})

Convenience wrapper for the set_datatype functions s.th. expressions like set_datatype(property_a, get_datatype(property_b)) work.

function set_description(entity::Ref{_Entity}, description::AbstractString)

Set the description of the given entity object.

function set_id(entity::Ref{_Entity}, id::AbstractString)

Throws a CaosDB.Exceptions.ClientException since you are not allowed to set the id of entities.

function set_id(parent::Ref{_Parent}, id::AbstractString)

Set the id of the given parent object.

function set_id(property::Ref{_Property}, id::AbstractString)

Set the id of the given property object.

function set_importance(
    property::Ref{_Property},
    importance::CaosDB.Constants.IMPORTANCE._IMPORTANCE
)

Set the importance of the given property object.

function set_local_path(entity::Ref{_Entity}, path::AbstractString)

Set the local path of the given entity object.

function set_name(entity::Ref{_Entity}, name::AbstractString)

Set the name of the given entity object.

function set_name(parent::Ref{_Parent}, name::AbstractString)

Set the name of the given parent object.

function set_name(property::Ref{_Property}, name::AbstractString)

Set the name of the given property object.

function set_remote_path(entity::Ref{_Entity}, path::AbstractString)

Set the remote file path of the given entity object.

function set_role(entity::Ref{_Entity}, role::CaosDB.Constants.ROLE._ROLE)

Set the role of the given entity object.

function set_unit(entity::Ref{_Entity}, unit::AbstractString)

Set the unit of the given entity object.

function set_unit(property::Ref{_Property}, unit::AbstractString)

Set the unit of the given property object.

function set_value(
    entity::Ref{_Entity},
    value::Union{AbstractString,Number,Bool,Vector{T}},
) where {T<:Union{AbstractString,Number,Bool}}

Set the value of the given entity object. Throw an error if it doesn't have the correct role. The value must be either string, Boolean, Integer, Float, or a vector thereof.

function set_value(property::Ref{_Property}, value::AbstractString)

Set the value of the given property object.

function add_delete_by_id(transaction::Ref{_Transaction}, id::AbstractString)

Add a sub-request to delete a single entity to the given transaction.

function add_insert_entity(transaction::Ref{_Transaction}, entity::Ref{_CaosDB.Entity.Entity})

Add a sub-request to insert a single entity to the given transaction.

function add_query(transaction::Ref{_Transaction}, query::AbstractString)

Add a query sub-request to the given transaction.

function add_retrieve_and_download_file_by_id(
    transaction::Ref{_Transaction},
    id::AbstractString,
    path::AbstractString,
)

Add a sub-request to retrieve and download a single entity (File) to the given transaction.

function add_retrieve_by_id(transaction::Ref{_Transaction}, id::AbstractString)

Add a sub-request to retrieve a single entity by its id to the given transaction.

function add_retrieve_by_id(
    transaction::Ref{_Transaction},
    ids::Vector{T},
) where {T<:AbstractString}

Add a sub-request to retrieve several entities by their ids to the given transaction.

function add_update_entity(transaction::Ref{_Transaction}, entity::Ref{_CaosDB.Entity.Entity})

Add a sub-request to update a single entity to the given transaction.

create_transaction(name::AbstractString = "default")

Return a transaction created with the connection of the given name. If none is given, the defult connection is used.

function create_transaction(connection::Ref{CaosDB.Connection._Connection})

Return a transactioncreated with the given connection object.

function delete_by_id(id::AbstractString)

Delete a single Entity identified by its id.

function execute(transaction::Ref{_Transaction})

Send the given transaction to the CaosDB server for excecution and wait for it to finish.

function execute_query(
    query::AbstractString,
    name::AbstractString = "default"
)

Execute the given query and return its results. Use the connection with the given name. If none is given, the default connection is used.

function execute_query(
    query::AbstractString,
    connection::Ref{CaosDB.Connection._Connection}
)

Execute the given query and return its results. Use the given connection.

function get_count_result(transaction::Ref{_Transaction})

Return the number of results of the COUNT query in the given transaction.

function get_result_at(results::Ref{_ResultSet}, index::Cint)

Return the entity at position index of the given results.

function get_result_at(results::Ref{_ResultSet}, index::Integer)

Convenience wrapper for get_result_at(::Ref{_ResultSet}, ::Cint). Convert the given index to Int32 and return the result at position index of results.

function get_result_set(transaction::Ref{_Transaction})

Return the result set of the given transaction.

function get_results(result_set::Ref{_ResultSet})

Return all entities of the given result_set.

function get_results(transaction::Ref{_Transaction})

Return all results of the given transaction.

function insert_entity(entity::Ref{CaosDB.Entity._Entity})

Insert a single Entity.

function retrieve(id::AbstractString, name::AbstractString = "default")

Retrieve and return the entity with the given id. Use the connection with the given name. If none is provided, the default connection is used.

function retrieve(id::AbstractString, connection::Ref{CaosDB.Connection._Connection})

Retrieve and return the entity with the given id. Use the given connection.

function retrieve(
    ids::Vector{T},
    connection::Ref{CaosDB.Connection._Connection},
) where {T<:AbstractString}

Retrieve and return the entities with the given ids. Use the given connection.

function retrieve(
    ids::Vector{T},
    name::AbstractString = "default",
) where {T<:AbstractString}

Retrieve and return the entities with the given ids. Use the connection of the given name. If none is provided, the default connection is used.

function retrieve_and_download_file_by_id(
    id::AbstractString, 
    download_path::AbstractString)

Retrieve and download a single File-Entity identified by its id. download_path is the path where the file will be downloaded.

function update_entity(entity::Ref{CaosDB.Entity._Entity})

Update a single Entity.

Chose the name of the library according to the OS you're running.

Struct containing version information of the CaosDB server. Meant mainly for internal usage; use CaosDB.Connection.get_version_info or CaosDB.Connection.print_version_info to retrieve the version of the connected CaosDB server.

Struct containing a pointer to the wrapped cpp class providing the certificate provider. Meant for internal use; call a CaosDB.Connection.create_<certificate_provider> function to create an certificate-provider object from a configuration.

Struct containing a pointer to the wrapped cpp class for storing the connection configuration. Meant for internal use; call a CaosDB.Connection.create_<configuration> function to create an connection-configuration object from a configuration.

Struct containing the actual connection to a CaosDB server. Meant for internal use; call a CaosDB.Connection.create_<connection> function to create an connection object from a configuration.

create_connection(config::Ref{_Configuration})

Return a connection based on the given config.

create_pem_file_certificate_provider(path::AbstractString)

Return a _CertificateProvider for the pem certificate located at path.

create_tls_connection_configuration(
    host::AbstractString,
    port::Cint,
    authenticator::Ref{CaosDB.Authentication._Authenticator},
    provider::Ref{_CertificateProvider}
    )

Return a TLS connection configuration with authentication.

get_version_info(con::Ref{_Connection})

Return the version of the CaosDB server that con is connected to.

print_version_info(con::Ref{_Connection})

Retrieve the version info for the CaosDB server con is connected to, and print the version in a nice message.

Struct containing a pointer to the wrapped cpp authenticator class. Meant for internal use; call a CaosDB.Authentication.create_<authenticator> function to create an authenticator object from a configuration.

create_plain_password_authenticator(
    username::AbstractString,
    password::AbstractString,
)

Return an authenticator object that contains a wrapped cpp plain-password authenticator configured with username and password.

Struct containing a pointer to the wrapped cpp DataType object. Meant for internal use only; use CaosDB.Entity.create_<type>_datatype to create a valid DataType object or use the `set/getdatatype` functions.

Struct containing a pointer to the wrapped cpp entity object. Meant for internal use; use CaosDB.Entity.create_entity to create an entity.

Struct containing a pointer to the wrapped cpp messsage object. Meant for internal use only; don't create it by yourself.

Struct containing a pointer to the wrapped cpp parent object. Meant for internal use; use CaosDB.Entity.create_parent to create an parent.

Struct containing a pointer to the wrapped cpp property object. Meant for internal use; use CaosDB.Entity.create_property to create an property.

Struct containing a pointer to the wrapped cpp AbstractValue object. Meant for internal use only; use CaosDB.Entity.create_value to create a Value object or use the `set/getvaluefunctions.

function _get_datatype(datatype::Ref{_DataType})

Return a tuple that contains the name of the datatype, and its collection type (nothing in case of a scalar datatype).

function _get_value(value::Ref{_Value})

Return the value of the given CaosDB value object.

function create_atomic_datatype(name::CaosDB.Constants.DATATYPE._DATATYPE)

Create and return a DataType object with an atomic datatype specified by the name.

function create_atomic_list_datatype(name::CaosDB.Constants.DATATYPE._DATATYPE)

Create and return a DataType object which is a list of atomics specified by name.

function create_reference_datatype(name::AbstractString)

Create and return a DataType object with a reference datatype specified by name.

function create_reference_list_datatype(name::AbstractString)

Create and return a DataType object which is a list of references specified by name.

function get_errors_size(entity::Ref{_Entity})

Return the number of error messages attached to the given entity.

function get_infos_size(entity::Ref{_Entity})

Return the number of info messages attached to the given entity.

function get_parents_size(entity::Ref{_Entity})

Return the number of parents attached to the given entity.

function get_properties_size(entity::Ref{_Entity})

Return the number of properties attached to the given entity.

function get_warnings_size(entity::Ref{_Entity})

Return the number of warning messages attached to the given entity.

Struct containing a pointer to the wrapped cpp result set of a transaction. The struct is meant for internal use only and shouldn't be created directly by the user but is returned by, e.g., get_result_set.

Struct containing a pointer to the wrapped cpp transaction object. Meant for internal use; call CaosDB.Transaction.create_transaction to create a transaction object.

function _release_result_at(results::Ref{_ResultSet}, index::Cint)

Return the entity at position index of the given results.

This function releases the entity from the result set and leaves the result set in a corrupted state. It should only be used to release the entity from a result set which is about to be destroyed anyway.

function _release_results(result_set::Ref{_ResultSet})

Return all entities of the given result_set.

This function also leaves the resultset object in a corrupted state and should only be used to release the entities from a resultset which is about to be destroyed anyway.

function _release_results(transaction::Ref{_Transaction})

Return all results fo the given transaction.

This function also leaves the transaction object in a corrupted state and should only be used to release the results from a transaction which is about to be destroyed anyway.

function get_result_size(results::Ref{_ResultSet})

Return the size of the given results, i.e., the number of entities or other responses returned in this result set.