knowrob::StorageInterface Class Reference

#include <StorageInterface.h>

Public Types
enum	TransactionType { Insert , Remove , Insert , Remove }
enum	BackendSelection { Including , Excluding , Including , Excluding }
enum	TransactionType { Insert , Remove , Insert , Remove }
enum	BackendSelection { Including , Excluding , Including , Excluding }

Public Member Functions
	StorageInterface (const std::shared_ptr< StorageManager > &backendManager)
auto &	vocabulary () const
auto &	backendManager () const
std::shared_ptr< transaction::Transaction >	createTransaction (const QueryableBackendPtr &queryable, TransactionType type, BackendSelection mode=Excluding, const std::vector< std::shared_ptr< NamedBackend >> &backends={})
bool	removeAllWithOrigin (std::string_view origin)
bool	mergeInsert (const QueryableBackendPtr &backend, const Triple &triple)
bool	contains (const QueryableBackendPtr &backend, const Triple &triple) const
void	match (const QueryableBackendPtr &backend, const TriplePattern &query, const TripleVisitor &visitor) const
void	query (const QueryableBackendPtr &backend, const GraphQueryPtr &q, const BindingsHandler &callback) const
TokenBufferPtr	getAnswerCursor (const QueryableBackendPtr &backend, const GraphPathQueryPtr &query)
	StorageInterface (const std::shared_ptr< StorageManager > &backendManager)
auto &	vocabulary () const
auto &	backendManager () const
std::shared_ptr< transaction::Transaction >	createTransaction (const QueryableBackendPtr &queryable, TransactionType type, BackendSelection mode=Excluding, const std::vector< std::shared_ptr< NamedBackend >> &backends={})
bool	removeAllWithOrigin (std::string_view origin)
bool	mergeInsert (const QueryableBackendPtr &backend, const Triple &triple)
bool	contains (const QueryableBackendPtr &backend, const Triple &triple) const
void	match (const QueryableBackendPtr &backend, const TriplePattern &query, const TripleVisitor &visitor) const
void	query (const QueryableBackendPtr &backend, const GraphQueryPtr &q, const BindingsHandler &callback) const
TokenBufferPtr	getAnswerCursor (const QueryableBackendPtr &backend, const GraphPathQueryPtr &query)

Static Public Member Functions
static void	foreach (const QueryableBackendPtr &backend, const TripleVisitor &visitor)
static void	batch (const QueryableBackendPtr &backend, const TripleHandler &callback)
static void	foreach (const QueryableBackendPtr &backend, const TripleVisitor &visitor)
static void	batch (const QueryableBackendPtr &backend, const TripleHandler &callback)

Protected Member Functions
void	pushIntoCursor (const QueryableBackendPtr &backend, const GraphPathQueryPtr &query, const TokenBufferPtr &resultStream) const
void	pushIntoCursor (const QueryableBackendPtr &backend, const GraphPathQueryPtr &query, const TokenBufferPtr &resultStream) const

Protected Attributes
std::shared_ptr< StorageManager >	backendManager_

Detailed Description

A high-level interface to the storage manager. It includes methods for querying and modifying the extensional database.

Definition at line 18 of file StorageInterface.h.

Member Enumeration Documentation

BackendSelection [1/2]

enum knowrob::StorageInterface::BackendSelection

Determines how storages are selected for a transaction.

Enumerator
Including
Excluding
Including
Excluding

Definition at line 29 of file StorageInterface.h.

                              {
            Including, Excluding
        };

BackendSelection [2/2]

enum knowrob::StorageInterface::BackendSelection

Determines how storages are selected for a transaction.

Enumerator
Including
Excluding
Including
Excluding

Definition at line 29 of file StorageInterface.h.

                              {
            Including, Excluding
        };

TransactionType [1/2]

enum knowrob::StorageInterface::TransactionType

The type of a transaction.

Enumerator
Insert
Remove
Insert
Remove

Definition at line 23 of file StorageInterface.h.

                             {
            Insert, Remove
        };

TransactionType [2/2]

enum knowrob::StorageInterface::TransactionType

The type of a transaction.

Enumerator
Insert
Remove
Insert
Remove

Definition at line 23 of file StorageInterface.h.

                             {
            Insert, Remove
        };

Constructor & Destructor Documentation

StorageInterface() [1/2]

knowrob::StorageInterface::StorageInterface ( const std::shared_ptr< StorageManager > &  backendManager )

inlineexplicit

Definition at line 33 of file StorageInterface.h.

                : backendManager_(backendManager) {}

StorageInterface() [2/2]

knowrob::StorageInterface::StorageInterface ( const std::shared_ptr< StorageManager > &  backendManager )

inlineexplicit

Definition at line 33 of file StorageInterface.h.

                : backendManager_(backendManager) {}

Member Function Documentation

backendManager() [1/2]

auto& knowrob::StorageInterface::backendManager ( ) const

inline

Returns

the storage manager.

Definition at line 44 of file StorageInterface.h.

{ return backendManager_; }

backendManager() [2/2]

auto& knowrob::StorageInterface::backendManager ( ) const

inline

Returns

the storage manager.

Definition at line 44 of file StorageInterface.h.

{ return backendManager_; }

batch() [1/2]

void StorageInterface::batch ( const QueryableBackendPtr &  backend, const TripleHandler &  callback  )

static

Executes a visitor on all triples in the extensional database.

Parameters

backend	the backend to query.
callback	the visitor to execute.

Definition at line 173 of file StorageInterface.cpp.

                                                                                              {
    if (backend->supports(StorageFeature::TripleContext)) {
        backend->batch(callback);
        return;
    }
 
    auto batchSize = GlobalSettings::batchSize();
    // fill a container that reverses a reification.
    UnReificationContainer unReifiedTriples;
    // take over ownership of triples in batches that need to be reified.
    // note: reified triples could be split into multiple batches which makes
    // the collapsing of them more difficult.
    // to this end we defer the collapsing until the batchDirect call has completed
    // while taking over ownership of the reified triples to avoid copies and allow
    // the use of views in the UnReificationContainer.
    std::vector<TriplePtr> reificationTriples;
    auto batch = std::make_shared<TripleViewBatch>(batchSize);
    backend->batch([&](const TripleContainerPtr &triples) {
        for (auto &triple: *triples) {
            if (ReifiedTriple::isPartOfReification(*triple.ptr)) {
                // take over ownership of triple
                if (triple.owned) {
                    triple.owned = false;
                    auto &newOwner = reificationTriples.emplace_back(triple.ptr);
                    unReifiedTriples.add(*newOwner.ptr);
                } else {
                    auto &copy = reificationTriples.emplace_back(new TripleCopy(*triple.ptr));
                    unReifiedTriples.add(*copy.ptr);
                }
            } else {
                batch->add(triple);
                if (batch->size() >= batchSize) {
                    callback(batch);
                    batch->reset();
                }
            }
        }
    });
    for (auto &triple: unReifiedTriples) {
        batch->add(triple);
        if (batch->size() >= batchSize) {
            callback(batch);
            batch->reset();
        }
    }
    if (!batch->empty()) {
        callback(batch);
    }
}

batch() [2/2]

static void knowrob::StorageInterface::batch ( const QueryableBackendPtr &  backend, const TripleHandler &  callback  )

static

Executes a visitor on all triples in the extensional database.

Parameters

backend	the backend to query.
callback	the visitor to execute.

contains() [1/2]

bool StorageInterface::contains	(	const QueryableBackendPtr &	backend,
		const Triple &	triple
	)		const

Checks if a triple is contained in the extensional database.

Parameters

backend	the storage to query.
triple	the triple to check.

Returns

true if the triple is contained in the extensional database, false otherwise.

Definition at line 122 of file StorageInterface.cpp.

                                                                                              {
    if (backend->supports(StorageFeature::TripleContext)) {
        return backend->contains(triple);
    }
 
    ReifiedTriple reification(triple, vocabulary());
    bool containsAll = false;
    for (auto &reified: reification) {
        containsAll = backend->contains(*reified.ptr);
        if (!containsAll) {
            break;
        }
    }
    return containsAll;
}

contains() [2/2]

bool knowrob::StorageInterface::contains	(	const QueryableBackendPtr &	backend,
		const Triple &	triple
	)		const

Checks if a triple is contained in the extensional database.

Parameters

backend	the storage to query.
triple	the triple to check.

Returns

true if the triple is contained in the extensional database, false otherwise.

createTransaction() [1/2]

std::shared_ptr< transaction::Transaction > StorageInterface::createTransaction	(	const QueryableBackendPtr &	queryable,
		TransactionType	type,
		BackendSelection	mode = Excluding,
		const std::vector< std::shared_ptr< NamedBackend >> &	backends = {}
	)

Creates a new transaction.

Parameters

queryable	a storage used to perform any queries needed to complete the transaction.
type	the type of the transaction.
mode	determines how storages are selected for the transaction.
backends	the storages to include or exclude from the transaction.

Returns

the transaction.

Definition at line 17 of file StorageInterface.cpp.

                                                                {
    std::shared_ptr<transaction::Transaction> transaction;
    if (transactionType == Insert) {
        transaction = std::make_shared<transaction::Insert>(queryable, vocabulary());
    } else {
        transaction = std::make_shared<transaction::Remove>(queryable, vocabulary());
    }
    if (transactionTargets == Including) {
        for (auto &backend: backends) {
            transaction->addBackend(backend);
        }
    } else {
        for (auto &definedBackend: backendManager_->plugins()) {
            auto &backend = definedBackend.second->value();
 
            bool skip = false;
            if (transactionTargets == Excluding) {
                for (auto &excluded: backends) {
                    if (excluded && backend == excluded->value()) {
                        skip = true;
                        break;
                    }
                }
            }
            if (skip) continue;
            transaction->addBackend(definedBackend.second);
        }
    }
    return transaction;
}

createTransaction() [2/2]

std::shared_ptr<transaction::Transaction> knowrob::StorageInterface::createTransaction	(	const QueryableBackendPtr &	queryable,
		TransactionType	type,
		BackendSelection	mode = Excluding,
		const std::vector< std::shared_ptr< NamedBackend >> &	backends = {}
	)

Creates a new transaction.

Parameters

queryable	a storage used to perform any queries needed to complete the transaction.
type	the type of the transaction.
mode	determines how storages are selected for the transaction.
backends	the storages to include or exclude from the transaction.

Returns

the transaction.

foreach() [1/2]

void StorageInterface::foreach ( const QueryableBackendPtr &  backend, const TripleVisitor &  visitor  )

static

Executes a visitor on all triples in the extensional database.

Parameters

backend	the backend to query.
visitor	the visitor to execute.

Definition at line 138 of file StorageInterface.cpp.

                                                                                               {
    if (backend->supports(StorageFeature::TripleContext)) {
        backend->foreach(visitor);
        return;
    }
 
    // fill a container that reverses a reification.
    UnReificationContainer unReifiedTriples;
    // the UnReificationContainer uses triple views, but memory of original triples can be
    // lost in the loop. So we need to store the original triples in a vector, and create
    // a view on them in the UnReificationContainer.
    std::vector<TriplePtr> originalTriples;
    // finally loop over all original triples
    backend->foreach([&](const TriplePtr &triple) {
        if (ReifiedTriple::isPartOfReification(*triple)) {
            auto &copy = originalTriples.emplace_back();
            copy.owned = true;
            // try to take over ownership of triple
            if (triple.owned) {
                copy.ptr = triple.ptr;
                triple.owned = false;
            } else {
                copy.ptr = new TripleCopy(*triple.ptr);
            }
            unReifiedTriples.add(*copy.ptr);
        } else {
            visitor(triple);
        }
    });
    // after looping over all original triples, also visit the un-reified ones
    for (auto &triple: unReifiedTriples) {
        visitor(triple);
    }
}

foreach() [2/2]

static void knowrob::StorageInterface::foreach ( const QueryableBackendPtr &  backend, const TripleVisitor &  visitor  )

static

Executes a visitor on all triples in the extensional database.

Parameters

backend	the backend to query.
visitor	the visitor to execute.

getAnswerCursor() [1/2]

TokenBufferPtr StorageInterface::getAnswerCursor	(	const QueryableBackendPtr &	backend,
		const GraphPathQueryPtr &	query
	)

Evaluates a query on the extensional database and fills a token buffer with the results in a separate thread.

Parameters

backend	the backend to query.
query	the query to evaluate.

Returns

the token buffer with the results.

Definition at line 361 of file StorageInterface.cpp.

                                                                                                               {
    std::shared_ptr<TokenBuffer> result = std::make_shared<TokenBuffer>();
    auto runner =
            std::make_shared<ThreadPool::LambdaRunner>(
                    [this, q, result, backend](const ThreadPool::LambdaRunner::StopChecker &) {
                        pushIntoCursor(backend, q, result);
                    });
    DefaultThreadPool()->pushWork(runner, [result, q](const std::exception &e) {
        KB_WARN("an exception occurred for graph query ({}): {}.", *q, e.what());
        result->close();
    });
    return result;
}

getAnswerCursor() [2/2]

TokenBufferPtr knowrob::StorageInterface::getAnswerCursor	(	const QueryableBackendPtr &	backend,
		const GraphPathQueryPtr &	query
	)

Evaluates a query on the extensional database and fills a token buffer with the results in a separate thread.

Parameters

backend	the backend to query.
query	the query to evaluate.

Returns

the token buffer with the results.

match() [1/2]

void StorageInterface::match	(	const QueryableBackendPtr &	backend,
		const TriplePattern &	query,
		const TripleVisitor &	visitor
	)		const

Evaluates a query on the extensional database and executes a visitor on the results which are returned in the form of triples.

Parameters

backend	the backend to query.
query	the query to evaluate.
visitor	the visitor to execute.

Definition at line 250 of file StorageInterface.cpp.

                                                                 {
    static auto ctx = std::make_shared<QueryContext>();
    if (backend->supports(StorageFeature::TripleContext)) {
        backend->match(q, visitor);
    } else {
        auto flags = ReifiedQuery::getReificationFlags(q);
        if (flags & IncludeOriginal) {
            backend->match(q, visitor);
        }
        if (flags & IncludeReified) {
            static auto v_o = std::make_shared<Variable>("o");
            static auto v_begin = std::make_shared<Variable>("begin");
            static auto v_end = std::make_shared<Variable>("end");
            static auto v_confidence = std::make_shared<Variable>("confidence");
            static auto v_uncertain = std::make_shared<Variable>("uncertain");
            static auto v_occasional = std::make_shared<Variable>("occasional");
 
            auto reified = std::make_shared<ReifiedQuery>(q, vocabulary(), true);
            // insert variables for contextual parameters
            setReifiedVariables(reified->term(), {
                    {reification::hasBeginTime->stringForm(),  v_begin},
                    {reification::hasEndTime->stringForm(),    v_end},
                    {reification::hasConfidence->stringForm(), v_confidence},
                    {reification::isUncertain->stringForm(),   v_uncertain},
                    {reification::isOccasional->stringForm(),  v_occasional}
            });
 
            backend->query(reified, [&](const BindingsPtr &bindings) {
                TriplePtr triple;
                triple.ptr = new TripleView();
                triple.owned = true;
 
                if (q.instantiateInto(*triple, bindings)) {
                    if (bindings->contains(v_begin->name())) {
                        auto &t_begin = bindings->get(v_begin->name());
                        if (t_begin->isNumeric()) {
                            triple->setBegin(std::static_pointer_cast<Numeric>(t_begin)->asDouble());
                        }
                    }
                    if (bindings->contains(v_end->name())) {
                        auto &t_end = bindings->get(v_end->name());
                        if (t_end->isNumeric()) {
                            triple->setEnd(std::static_pointer_cast<Numeric>(t_end)->asDouble());
                        }
                    }
                    if (bindings->contains(v_confidence->name())) {
                        auto &t_confidence = bindings->get(v_confidence->name());
                        if (t_confidence->isNumeric()) {
                            triple->setConfidence(std::static_pointer_cast<Numeric>(t_confidence)->asDouble());
                        }
                    }
                    if (bindings->contains(v_uncertain->name())) {
                        auto &t_uncertain = bindings->get(v_uncertain->name());
                        if (t_uncertain->isNumeric()) {
                            triple->setIsUncertain(std::static_pointer_cast<Boolean>(t_uncertain)->asBoolean());
                        }
                    } else {
                        triple->setIsUncertain(false);
                    }
                    if (bindings->contains(v_occasional->name())) {
                        auto &t_occasional = bindings->get(v_occasional->name());
                        if (t_occasional->isNumeric()) {
                            triple->setIsOccasional(std::static_pointer_cast<Boolean>(t_occasional)->asBoolean());
                        }
                    } else {
                        triple->setIsOccasional(false);
                    }
                    visitor(triple);
                }
            });
        }
    }
}

match() [2/2]

void knowrob::StorageInterface::match	(	const QueryableBackendPtr &	backend,
		const TriplePattern &	query,
		const TripleVisitor &	visitor
	)		const

Evaluates a query on the extensional database and executes a visitor on the results which are returned in the form of triples.

Parameters

backend	the backend to query.
query	the query to evaluate.
visitor	the visitor to execute.

mergeInsert() [1/2]

bool StorageInterface::mergeInsert	(	const QueryableBackendPtr &	backend,
		const Triple &	triple
	)

Inserts a triple into the extensional database and merges it with existing ones if possible.

Parameters

backend	the storage to modify.
triple	the triple to insert.

Returns

true if the triple was inserted, false otherwise.

Definition at line 88 of file StorageInterface.cpp.

                                                                                           {
    auto pat = std::make_shared<TriplePattern>(triple);
    // Match triples where interval intersection is not empty
    pat->setIsOccasionalTerm(groundable(Numeric::trueAtom()));
    // Construct a merged triple
    TripleView mergedTriple(triple);
    // Store overlapping triples to remove them after matching
    std::vector<TriplePtr> overlappingTriples;
    // Match a triple pattern in backend.
    // Note that the match will return the un-reified variant of the triple no matter
    // if the backend stores the triple reified or not.
    match(backend, *pat, [&](const TriplePtr &matchedTriple) {
        if (mergedTriple.mergeFrame(*matchedTriple)) {
            auto &x = overlappingTriples.emplace_back();
            x.owned = true;
            // try to take over ownership of matched triple
            if (matchedTriple.owned) {
                x.ptr = matchedTriple.ptr;
                matchedTriple.owned = false;
            } else {
                x.ptr = new TripleCopy(*matchedTriple);
            }
        }
    });
    if (!overlappingTriples.empty()) {
        // remove overlapping triples if any
        auto container = std::make_shared<ProxyTripleContainer>(&overlappingTriples);
        createTransaction(backend, Remove)->commit(container);
    }
    // Insert the triple after merging with overlapping existing ones
    createTransaction(backend, Insert)->commit(mergedTriple);
    return true;
}

mergeInsert() [2/2]

bool knowrob::StorageInterface::mergeInsert	(	const QueryableBackendPtr &	backend,
		const Triple &	triple
	)

Inserts a triple into the extensional database and merges it with existing ones if possible.

Parameters

backend	the storage to modify.
triple	the triple to insert.

Returns

true if the triple was inserted, false otherwise.

pushIntoCursor() [1/2]

void StorageInterface::pushIntoCursor ( const QueryableBackendPtr &  backend, const GraphPathQueryPtr &  query, const TokenBufferPtr &  resultStream  ) const

protected

Definition at line 339 of file StorageInterface.cpp.

                                                                                {
    auto expanded = backend->expand(q);
    auto channel = TokenStream::Channel::create(resultStream);
    try {
        bool hasPositiveAnswer = false;
        query(backend, expanded->expanded, [&](const BindingsPtr &bindings) {
            channel->push(backend->yes(q, expanded, bindings));
            hasPositiveAnswer = true;
        });
        if (!hasPositiveAnswer) {
            channel->push(backend->no(q));
        }
        channel->push(EndOfEvaluation::get());
    }
    catch (const std::exception &e) {
        // make sure EOS is pushed to the stream
        channel->push(EndOfEvaluation::get());
        throw;
    }
}

pushIntoCursor() [2/2]

void knowrob::StorageInterface::pushIntoCursor ( const QueryableBackendPtr &  backend, const GraphPathQueryPtr &  query, const TokenBufferPtr &  resultStream  ) const

protected

query() [1/2]

void StorageInterface::query	(	const QueryableBackendPtr &	backend,
		const GraphQueryPtr &	q,
		const BindingsHandler &	callback
	)		const

Evaluates a query on the extensional database and executes a visitor on the results which are returned in as bindings.

Parameters

backend	the backend to query.
q	the query to evaluate.
callback	the visitor to execute.

Definition at line 325 of file StorageInterface.cpp.

                                                                    {
    if (!backend->supports(StorageFeature::TripleContext) && ReifiedQuery::hasReifiablePattern(q)) {
        // if there is at least one reifiable pattern, we need to reify the query entirely,
        // and run the reified query on the original backend.
        auto reified = std::make_shared<ReifiedQuery>(q, vocabulary());
        backend->query(reified, [&](const BindingsPtr &bindings) {
            callback(bindings);
        });
    } else {
        backend->query(q, callback);
    }
}

query() [2/2]

void knowrob::StorageInterface::query	(	const QueryableBackendPtr &	backend,
		const GraphQueryPtr &	q,
		const BindingsHandler &	callback
	)		const

Evaluates a query on the extensional database and executes a visitor on the results which are returned in as bindings.

Parameters

backend	the backend to query.
q	the query to evaluate.
callback	the visitor to execute.

removeAllWithOrigin() [1/2]

bool StorageInterface::removeAllWithOrigin

(

std::string_view

origin

)

Removes all triples with a given origin from all storages.

Parameters

origin

the origin of the triples to remove.

Returns

true if the triples were removed from all storages, false otherwise.

Definition at line 52 of file StorageInterface.cpp.

                                                                {
    // remove all triples with a given origin from all backends.
    std::vector<std::shared_ptr<ThreadPool::Runner>> transactions;
    for (auto &it: backendManager_->plugins()) {
        auto definedBackend = it.second;
        // create a worker goal that performs the transaction
        auto transaction = std::make_shared<ThreadPool::LambdaRunner>(
                [definedBackend, origin](const ThreadPool::LambdaRunner::StopChecker &) {
                    if (definedBackend->value()->removeAllWithOrigin(origin)) {
                        // unset version of origin in backend
                        definedBackend->value()->setVersionOfOrigin(origin, std::nullopt);
                    } else {
                        KB_WARN("removal of triples with origin '{}' from backend '{}' failed!", origin,
                                definedBackend->name());
                    }
                });
        // push goal to thread pool
        DefaultThreadPool()->pushWork(
                transaction,
                [definedBackend](const std::exception &exc) {
                    KB_ERROR("transaction failed for backend '{}': {}", definedBackend->name(), exc.what());
                });
        transactions.push_back(transaction);
    }
 
    // wait for all transactions to finish
    for (auto &transaction: transactions) transaction->join();
 
    // remove origin from import hierarchy
    if (!vocabulary()->importHierarchy()->isReservedOrigin(origin)) {
        vocabulary()->importHierarchy()->removeCurrentGraph(origin);
    }
 
    return true;
}

removeAllWithOrigin() [2/2]

bool knowrob::StorageInterface::removeAllWithOrigin

(

std::string_view

origin

)

Removes all triples with a given origin from all storages.

Parameters

origin

the origin of the triples to remove.

Returns

true if the triples were removed from all storages, false otherwise.

vocabulary() [1/2]

auto& knowrob::StorageInterface::vocabulary ( ) const

inline

Returns

the vocabulary.

Definition at line 39 of file StorageInterface.h.

{ return backendManager_->vocabulary(); }

vocabulary() [2/2]

auto& knowrob::StorageInterface::vocabulary ( ) const

inline

Returns

the vocabulary.

Definition at line 39 of file StorageInterface.h.

{ return backendManager_->vocabulary(); }

Member Data Documentation

backendManager_

std::shared_ptr< StorageManager > knowrob::StorageInterface::backendManager_

protected

Definition at line 127 of file StorageInterface.h.

---

The documentation for this class was generated from the following files:

• build/_CPack_Packages/Linux/DEB/knowrob-2.1.0-Linux/usr/include/knowrob/storage/StorageInterface.h
• src/storage/StorageInterface.cpp