Examples
Connect to a CaosDB server
See also the hints on how to get started, and set-up of libcaosdb. In order to connect to a CaosDB server with libcaosdb you first have to configure the connection via a configuration file as explained in the “Client Configuration” section. Once the configuration is set up, connecting to the server is as easy as
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
You can print the full version of the server that you are connected to (and therby test the connection) via:
// get version info of the server
connection.RetrieveVersionInfo()
const auto &v_info = connection->GetVersionInfo();
std::cout << "Server Version: " << v_info->GetMajor() << "."
<< v_info->GetMinor() << "." << v_info->GetPatch() << "-"
<< v_info->GetPreRelease() << "-" << v_info->GetBuild()
<< std::endl;
Retrieve a Record
With libcaosdb you can create a transaction object, fill it with sub-requests, execute it, and retrieve the result(s) . This is handy when you want to have several requests in the same transaction. However, most of the time, e.g., when retrieving one or multiple Records, this is not necessary. libcaosdb provides helper functions so you don’t have to worry about transactions and their executions. Assume you want to retrieve an Entity with id=123. This is done via
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
auto transaction(connection->CreateTransaction());
const auto *id = "1231";
transaction->RetrieveById(id);
auto status = transaction->Execute();
const auto &result_set = transaction->GetResultSet();
const auto &entity = result_set.at(0)
You can then use the getter methods like GetId
,
GetParents
, or
GetProperties`
to get the name, the parents, or
the properties of the retrieved entity.
Retrieving multiple entities works in the same way. Type
const std::vector<std::string> ids = {"1220", "1221", "1222"};
transaction->RetrieveById(ids.begin(), ids.end());
to retrieve the entities with ids 1220, 1221 and 1222. They can then be
accessed using result_set.at(1)
etc.
The same (and more) can be achieved by building and executing the transaction manually. This is done by
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
auto transaction(connection->CreateTransaction());
transaction->RetrieveById("1231");
transaction->RetrieveById("1233");
auto status = transaction->Execute();
A result set can be obtained via
GetResultSet`
which contains the
resulting entities and can, e.g., be checked for length.
Execute queries
Executing queries works very similar to the retrieval of entities via ids.
FIND and SELECT queries
In general, entities can be found using CaosDB’s query language like
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
auto query_transaction(connection->CreateTransaction());
query_transaction->Query("FIND ENTITY WITH id = 1222");
query_transaction->Execute();
auto result_set = query_transaction->GetResultSet();
std::cout << "Found " << result_set.size()
<< "entity with id="
<< result_set.at(0).GetId() << std::endl;
result_set
is a (possibly empty) list of entities that can be
inspected as above.
SELECT queries haven't been implemented in the C++ client yet and
thus cannot be executed from libcaosdb right now. SELECT queries
will be added in a future release.
COUNT queries
COUNT queries are different from FIND or SELECT queries in two ways.
Firstly, they do not return entities but a single number which is why,
secondly, they do not have a result set that could be returned.
The result of the count is
obtained using the GetCountResult
function:
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
auto query_transaction(connection->CreateTransaction());
query_transaction->Query("COUNT RECORD person WITH NAME LIKE '*Baggins'");
query_transaction->Execute();
std::cout << "Found " << query_transaction->GetCountResult()
<< "entities."<< std::endl;
Insert, update, and delete entities
Insert, update and delete operations function the same way. The respective task is added to a transaction and the transaction is executed.
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
// ######## INSERT ########
// create the entity
Entity entity;
entity.SetRole(Role::RECORD_TYPE);
entity.SetName("RT1");
// create the transaction, add the task and execute the transaction
auto insert_transaction(connection->CreateTransaction());
insert_transaction->InsertEntity(&entity);
auto insert_status = insert_transaction->Execute();
const auto &insert_result_set = insert_transaction->GetResultSet();
// the result is an entity with the new id
const auto &new_entity = insert_result_set.at(0);
std::cout << "The newly inserted entity has the id "
<< new_entity.GetId() << std::endl;
// get the inserted entity
// RETRIEVE
auto retrieve_transaction(connection->CreateTransaction());
retrieve_transaction->RetrieveById(new_entity.GetId());
retrieve_transaction->Execute();
// save the entity from the result set in a new variable
auto update_entity(retrieve_transaction->GetResultSet().at(0));
// ######## UPDATE ########
// and change it
update_entity.SetName("RT1-Update");
// create update transaction
auto update_transaction(connection->CreateTransaction());
update_transaction->UpdateEntity(&update_entity);
auto update_status = update_transaction->Execute();
// same as with insert transaction, the update transaction returns an entity
// with the id
const auto &updated_entity = update_transaction->GetResultSet().at(0);
std::cout << "The entity with the id "
<< update_entity.GetId() << "was updated." << std::endl;
// ######## DELETE ########
auto delete_transaction(connection->CreateTransaction());
delete_transaction->DeleteById(updated_entity .GetId());
auto delete_status = delete_transaction->Execute();
// again, the delete transaction returns a result set with entities
// with the ids that where deleted
const auto &delete_result_set = delete_transaction->GetResultSet();
Up- and Download a file
const auto &connection =
caosdb::connection::ConnectionManager::GetDefaultConnection();
Entity file;
file.SetRole(Role::FILE);
file.SetFilePath("test.txt");
file.SetLocalPath(test_upload_file_1);
// in order to upload a file, the corresponding entity simply has to be
// inserted
auto insert_transaction(connection->CreateTransaction());
insert_transaction->InsertEntity(&file);
insert_transaction->Execute();
// entity in the result set contains the new id
const auto &insert_results = insert_transaction->GetResultSet();
const auto &inserted_file = insert_results.at(0);
// for the download you need to use the RetrieveAndDownloadFileById task and
// supply the path where the file shall be stored
test_download_file = fs::path("test_download_file_delete_me.dat");
auto download_transaction(connection->CreateTransaction());
download_transaction->RetrieveAndDownloadFileById(
inserted_file.GetId(), test_download_file.string());
download_transaction->ExecuteAsynchronously();
download_transaction->WaitForIt().GetCode()
const auto &download_results = download_transaction->GetResultSet();
const auto &downloaded_file = download_results.at(0);