CaosDB.jl's API

Below you find the explicit documentation of CaosDB's public interface. You also find the documentation of the internal API which is meant for expert use only. Only use those if you know what you're doing.

Public API

CaosDB.Exceptions.evaluate_return_codeMethod
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.

CaosDB.Utility.get_env_fallbackFunction
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.

CaosDB.Connection.connectFunction
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".
CaosDB.Connection.connect_manuallyMethod
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

Info

Because of type-stability, and since an empty string may be a valid password, the value of password, for which it is fetched from an environmental variable, is "undefined". This means that if you absolutely must use "undefined" as your password, you have to specify it via the CAOSDB_PASSWORD variable.

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.
CaosDB.Entity.append_parentMethod
function append_parent(entity::Ref{_Entity}, parent::Ref{_Parent})

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

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

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

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

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

CaosDB.Entity.append_propertyMethod
function append_property(entity::Ref{_Entity}, property::Ref{_Property})

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

CaosDB.Entity.create_entityFunction
function create_entity(name::AbstractString = "")

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

CaosDB.Entity.create_file_entityMethod

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.

CaosDB.Entity.create_parentMethod
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.

Info

This is not an _Entity that could be inserted or updated by its own but a _Parent that is to be appended to another _Entity.

CaosDB.Entity.create_propertyMethod
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.

Info

This is not an _Entity that could be inserted or updated by its own but a _Property that is to be appended to another _Entity.

CaosDB.Entity.create_property_entityMethod
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.

CaosDB.Entity.create_recordFunction
 function create_record(name::AbstractString = "")

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

CaosDB.Entity.create_recordtypeFunction
function create_recordtype(name::AbstractString = "")

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

CaosDB.Entity.get_codeMethod
function get_code(message::Ref{_Message})

Return the code of the given message.

CaosDB.Entity.get_datatypeMethod
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).

CaosDB.Entity.get_datatypeMethod
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.

CaosDB.Entity.get_errorMethod
function get_error(entity::Ref{_Entity}, index::Cint)

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

CaosDB.Entity.get_errorMethod
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.

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

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

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

Return the id of the given entity

CaosDB.Entity.get_idMethod
function get_id(entity::Ref{_Parent})

Return the id of the given parent

CaosDB.Entity.get_idMethod
function get_id(entity::Ref{_Property})

Return the id of the given property

CaosDB.Entity.get_infoMethod
function get_info(entity::Ref{_Entity}, index::Cint)

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

CaosDB.Entity.get_infoMethod
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.

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

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

CaosDB.Entity.get_nameMethod
function get_name(entity::Ref{_Property})

Return the name of the given property

CaosDB.Entity.get_parentMethod
function get_parent(entity::Ref{_Entity}, index::Cint)

Return the parent of the given entity at position index.

CaosDB.Entity.get_parentMethod
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.

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

Return the vector of all parents of the given entity.

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

Return the vector of all properties of the given entity.

CaosDB.Entity.get_propertyMethod
function get_property(entity::Ref{_Entity}, index::Cint)

Return the property of the given entity at position index.

CaosDB.Entity.get_propertyMethod
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.

CaosDB.Entity.get_unitMethod
function get_unit(entity::Ref{_Property})

Return the unit of the given property

CaosDB.Entity.get_valueMethod
function get_value(property::Ref{_Property})

Return the value of the given property

CaosDB.Entity.get_warningMethod
function get_warning(entity::Ref{_Entity}, index::Cint)

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

CaosDB.Entity.get_warningMethod
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.

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

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

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

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

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

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

CaosDB.Entity.remove_parentMethod
function remove_parent(entity::Ref{_Entity}, index::Cint)

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

CaosDB.Entity.remove_propertyMethod
function remove_property(entity::Ref{_Entity}, index::Cint)

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

CaosDB.Entity.set_datatypeFunction
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.

CaosDB.Entity.set_datatypeFunction
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.

CaosDB.Entity.set_datatypeFunction
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.

CaosDB.Entity.set_datatypeFunction
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.

CaosDB.Entity.set_datatypeMethod
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.

CaosDB.Entity.set_datatypeMethod
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.

CaosDB.Entity.set_descriptionMethod
function set_description(entity::Ref{_Entity}, description::AbstractString)

Set the description of the given entity object.

CaosDB.Entity.set_idMethod
function set_id(entity::Ref{_Entity}, id::AbstractString)

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

CaosDB.Entity.set_idMethod
function set_id(parent::Ref{_Parent}, id::AbstractString)

Set the id of the given parent object.

CaosDB.Entity.set_idMethod
function set_id(property::Ref{_Property}, id::AbstractString)

Set the id of the given property object.

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

Set the importance of the given property object.

CaosDB.Entity.set_local_pathMethod
function set_local_path(entity::Ref{_Entity}, path::AbstractString)

Set the local path of the given entity object.

CaosDB.Entity.set_nameMethod
function set_name(entity::Ref{_Entity}, name::AbstractString)

Set the name of the given entity object.

CaosDB.Entity.set_nameMethod
function set_name(parent::Ref{_Parent}, name::AbstractString)

Set the name of the given parent object.

CaosDB.Entity.set_nameMethod
function set_name(property::Ref{_Property}, name::AbstractString)

Set the name of the given property object.

CaosDB.Entity.set_remote_pathMethod
function set_remote_path(entity::Ref{_Entity}, path::AbstractString)

Set the remote file path of the given entity object.

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

Set the role of the given entity object.

CaosDB.Entity.set_unitMethod
function set_unit(entity::Ref{_Entity}, unit::AbstractString)

Set the unit of the given entity object.

CaosDB.Entity.set_unitMethod
function set_unit(property::Ref{_Property}, unit::AbstractString)

Set the unit of the given property object.

CaosDB.Entity.set_valueMethod
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.

CaosDB.Entity.set_valueMethod
function set_value(property::Ref{_Property}, value::AbstractString)

Set the value of the given property object.

CaosDB.Transaction.add_delete_by_idMethod
function add_delete_by_id(transaction::Ref{_Transaction}, id::AbstractString)

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

Info

This does not execute the transaction.

CaosDB.Transaction.add_insert_entityMethod
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.

Info

This does not execute the transaction.

CaosDB.Transaction.add_queryMethod
function add_query(transaction::Ref{_Transaction}, query::AbstractString)

Add a query sub-request to the given transaction.

Warning

Only COUNT queris and FIND queries (and no SELECT queries) are currently supported.

Info

This does not execute the transaction

CaosDB.Transaction.add_retrieve_and_download_file_by_idMethod
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.

Info

This does not execute the transaction.

CaosDB.Transaction.add_retrieve_by_idMethod
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.

Info

This does not execute the transaction.

CaosDB.Transaction.add_retrieve_by_idMethod
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.

Info

This does not execute the transaction.

CaosDB.Transaction.add_update_entityMethod
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.

Info

This does not execute the transaction.

CaosDB.Transaction.create_transactionFunction
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.

CaosDB.Transaction.executeMethod
function execute(transaction::Ref{_Transaction})

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

CaosDB.Transaction.execute_queryFunction
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.

Info

Since only the resulting entities are returned, this only makes sense for FIND (and, in the future, SELECT) queries. To get the result of a COUNT query, you have to execute the transaction yourself using create_transaction, add_query, and execute, and get the result with get_count_result.

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

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

Info

Since only the resulting entities are returned, this only makes sense for FIND (and, in the future, SELECT) queries. To get the result of a COUNT query, you have to execute the transaction yourself using create_transaction, add_query, and execute, and get the result with get_count_result.

CaosDB.Transaction.get_count_resultMethod
function get_count_result(transaction::Ref{_Transaction})

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

Info

This is only a meaningful quantity if there actually was a COUNT query in the transaction, and it already has been executed. In all other cases the return value will be -1.

CaosDB.Transaction.get_result_atMethod
function get_result_at(results::Ref{_ResultSet}, index::Cint)

Return the entity at position index of the given results.

CaosDB.Transaction.get_result_atMethod
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.

CaosDB.Transaction.retrieveFunction
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.

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

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

CaosDB.Transaction.retrieveMethod
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.

CaosDB.Transaction.retrieveMethod
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.

CaosDB.Transaction.retrieve_and_download_file_by_idMethod
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.

Expert-use only API functions

CaosDB.library_nameConstant

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

CaosDB.Info._VersionInfoType

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.

CaosDB.Connection._CertificateProviderType

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.

CaosDB.Connection._ConfigurationType

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.

CaosDB.Connection._ConnectionType

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.

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

Return a TLS connection configuration with authentication.

CaosDB.Connection.print_version_infoMethod
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.

CaosDB.Authentication._AuthenticatorType

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.

CaosDB.Entity._DataTypeType

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.

CaosDB.Entity._EntityType

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

CaosDB.Entity._MessageType

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

CaosDB.Entity._ParentType

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

CaosDB.Entity._PropertyType

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

CaosDB.Entity._ValueType

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.

CaosDB.Entity._get_datatypeMethod
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).

CaosDB.Entity._get_valueMethod
function _get_value(value::Ref{_Value})

Return the value of the given CaosDB value object.

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

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

CaosDB.Entity.create_atomic_list_datatypeMethod
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.

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

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

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

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

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

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

CaosDB.Transaction._ResultSetType

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.

CaosDB.Transaction._TransactionType

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

CaosDB.Transaction._release_result_atMethod
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.

CaosDB.Transaction._release_resultsMethod
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.

CaosDB.Transaction._release_resultsMethod
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.

CaosDB.Transaction.get_result_sizeMethod
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.