@c This file is a part of the CaosDB Project.
@c
@c Copyright (C) 2021 IndiScale GmbH <info@indiscale.com>
@c Copyright (C) 2021 Daniel Hornung <d.hornung@indiscale.com>
@c
@c This program is free software: you can redistribute it and/or modify
@c it under the terms of the GNU Affero General Public License as
@c published by the Free Software Foundation, either version 3 of the
@c License, or (at your option) any later version.
@c
@c This program is distributed in the hope that it will be useful,
@c but WITHOUT ANY WARRANTY; without even the implied warranty of
@c MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
@c GNU Affero General Public License for more details.
@c
@c You should have received a copy of the GNU Affero General Public License
@c along with this program. If not, see <https://www.gnu.org/licenses/>.

@node Caosdb
@comment  node-name,  next,  previous,  up
@chapter The CaosDB class

@c %%%%%%%%%%%%%%% Caosdb %%%%%%%%%%%%%%%

@deftp {Class} Caosdb

This is the main class of the CaosDB client for Octave.

The @code{Caosdb} class holds information about the connection to a CaosDB server.  It provides a
convenient interface to the possible transactions (insert, query, retrieve, update, delete) with the
server.

@end deftp

@c %%%%%%%%%%%%%%% connection %%%%%%%%%%%%%%%
@deftypeivar {Caosdb} string connection

The name of the connection which shall be used for transactions via this @code{Caosdb} object.  The
available connections are taken from the active libcaosdb configuration.  If @code{connection} is
the empty string, the default connection will be used.

@end deftypeivar

@c %%%%%%%%%%%%%%% Caosdb() %%%%%%%%%%%%%%%
@defmethod Caosdb Caosdb ([string @var{connection}])

The constructor takes an optional @var{connection} argument which, if given, is used as connection
name for transactions via this object.

@end defmethod

@c %%%%%%%%%%%%%%% info() %%%%%%%%%%%%%%%
@defmethod Caosdb info ()

Return a string with information about the libraries and the server.

@end defmethod

@c %%%%%%%%%%%%%%% retrieve_by_id() %%%%%%%%%%%%%%%
@defmethod Caosdb retrieve_by_id( @var{ids}, @dots{} )

Retrieve entities by IDs.

@example
entities = Caosdb.retrieve_by_id("my_id", @{"more", "ids"@});
@end example

@strong{Parameters}

@param{ids, string or cell array of strings, The ID(s) of the entity (entities) to be retrieved.}

@strong{Returns}

@param{entities, cell array, The retrieved entities.}

@end defmethod

@c %%%%%%%%%%%%%%% query() %%%%%%%%%%%%%%%
@defmethod Caosdb query( @var{query_str} )

Execute a query.

@example
entities = Caosdb.query("FIND Record Foo WITH bar=baz");
entities = Caosdb.query("COUNT Record Foo WITH bar=baz");
@end example

@strong{Parameters}

@param{query_str, string, The query to be executed.}

@strong{Returns}

@param{entities, cell array, The retrieved entities.  If the query was a COUNT query@comma{} the
result is an int64 instead.}

@end defmethod

@c %%%%%%%%%%%%%%% insert() %%%%%%%%%%%%%%%
@defmethod Caosdb insert( @var{entities} )

Insert an entity.

@example
inserted = Caosdb.insert(entities);
@end example

@strong{Parameters}

@param{entities, cell array, A cell array with the entities to be inserted.}

@strong{Returns}

@param{inserted, cell array, The resulting inserted entities (sparse@comma{} only for ID and
version).}

@end defmethod

@c %%%%%%%%%%%%%%% update() %%%%%%%%%%%%%%%
@defmethod Caosdb update( @var{entities} )

Update an entity.

@example
updated = Caosdb.update(entities);
@end example

@strong{Parameters}

@param{entities, cell array, A cell array with the entities to be updated.  All entities must have a
valid ID.}

@strong{Returns}

@param{updated, cell array, The resulting updated entities.}

@end defmethod

@c %%%%%%%%%%%%%%% delete_by_id() %%%%%%%%%%%%%%%
@defmethod Caosdb retrieve_by_id( @var{ids}, @dots{} )

Delete entities by IDs.

@example
entities = Caosdb.delete_by_id("my_id", @{"more", "ids"@});
@end example

The usage is equivalent to @code{retrieve_by_id(...)}.

@cartouche
@b{Note:} @code{Caosdb.delete()} will call the destructor of the Caosdb object.
@end cartouche

@strong{Parameters}

@param{ids, string or cell array of strings, The ID(s) of the entity (entities) to be deleted.}

@strong{Returns}

@param{entities, cell array, The deleted entities.}

@end defmethod

@c %%%%%%%%%%%%%%% download_file_by_single_id() %%%%%%%%%%%%%%%
@defmethod Caosdb download_file_by_single_id( @var{id}, @var{local_path} )

Download a file by ID.

@example
entity = Caosdb.download_file_by_single_id("my_id", "/save/file/here.dat");
@end example

Inserting files is done by creating a "@code{FILE}" @ref{Entity} and inserting it.

@strong{Parameters}

@param{ids, string, The ID of the file to be downloaded.}
@param{local_path, string, The location where the file shall be saved.}

@strong{Returns}

@param{entity, cell array, 1x1 cell array with the retrieved file entity.}

@end defmethod