Knowledge


level_2


What is it

The Knowledge service handles a graph-based database in the robot’s head.

Each knowledge graph is composed of nodes ResourceNode or Node, grouped by triplets (Triple).

How to use it

Creating a ResourceNode

A ResourceNode is a node with a unique URI among a knowledge graph.

To create a ResourceNode, use the constructor with a valid URI:

// Create a ResourceNode.
ResourceNode resourceNode = new ResourceNode("http://softbankrobotics.com/Bob");

Creating a Node

A Node is a graph node containing an object.

It can contain the following types of objects:

  • String,
  • Integer,
  • Float,
  • Double,
  • LocalizedString,
  • DateTimeString (yyyy-MM-ddThh:mm:ssZ format),
  • DateString (yyyy-MM-dd format),
  • TimeString (hh:mm:ss format),
  • ResourceNode (used to link multiple triples together). For further details, see: Using meta nodes.

To create a Node, use the constructor with the object to contain:

// Create a Node.
Node node = new Node("cat");

Creating a Triple

A Triple is a triplet of nodes:

  • a subject, represented by a ResourceNode,
  • a predicate, represented by a ResourceNode,
  • an object, represented by a Node.
https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/triple.png

To create a Triple, use the constructor with a subject, a predicate and an object:

ResourceNode subjectNode = ...;
ResourceNode predicateNode = ...;
Node objectNode = ...;
// Create a Triple.
Triple triple = new Triple(subjectNode, predicateNode, objectNode);

Retrieving a graph editor

Use an EditableKnowledgeGraph to edit a knowledge graph.

Retrieve the application graph editor with the Knowledge service:

// Retrieving a graph editor.
Knowledge knowledge = qiContext.getKnowledge();
EditableKnowledgeGraph editableKnowledgeGraph = knowledge.editableKnowledgeGraph(qiContext.getRobotContext());

Adding a triple

Add a Triple to an EditableKnowledgeGraph:

EditableKnowledgeGraph editableKnowledgeGraph = ...;
ResourceNode subjectNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode predicateNode = new ResourceNode("http://softbankrobotics.com/favoriteAnimal");
Node objectNode = new Node("cat");
Triple triple = new Triple(subjectNode, predicateNode, objectNode);
// Add a (Bob, favoriteAnimal, "cat") triple.
editableKnowledgeGraph.add(triple);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/add_a_triple.png

It is possible to add multiple objects to the same (subject, predicate) couple by adding a Triple containing the same subject and predicate with a different object:

EditableKnowledgeGraph editableKnowledgeGraph = ...;
ResourceNode subjectNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode predicateNode = new ResourceNode("http://softbankrobotics.com/favoriteAnimal");
Node catNode = new Node("cat");
Node dogNode = new Node("dog");
Triple catTriple = new Triple(subjectNode, predicateNode, catNode);
Triple dogTriple = new Triple(subjectNode, predicateNode, dogNode);
// Add a (Bob, favoriteAnimal, "cat") triple.
editableKnowledgeGraph.add(catTriple);
// Add a (Bob, favoriteAnimal, "dog") triple.
editableKnowledgeGraph.add(dogTriple);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/add_multiple_objects.png

Removing a triple

Remove triples from an EditableKnowledgeGraph:

EditableKnowledgeGraph editableKnowledgeGraph = ...;
ResourceNode bobNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode wildcardResourceNode = new ResourceNode("");
Node wildcardNode = new Node(wildcardResourceNode);
Triple triple = new Triple(bobNode, wildcardResourceNode, wildcardNode);
// Remove every triple with Bob as subject.
editableKnowledgeGraph.remove(triple);

The removed triples will be the ones matching the given triple:

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/remove_a_triple.png

Tip

An empty ResourceNode (containing an empty String, ""), is considered as a wildcard for queries.

An empty Node (containing an empty ResourceNode), is considered as a wildcard for queries.

Updating the object in a triple

To update the object in a Triple, first remove the triple containing the old object and then add the triple containing the new object:

EditableKnowledgeGraph editableKnowledgeGraph = ...;

// Define the old triple.
ResourceNode subjectNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode predicateNode = new ResourceNode("http://softbankrobotics.com/favoriteAnimal");
Node oldObjectNode = new Node("cat");
Triple oldTriple = new Triple(subjectNode, predicateNode, oldObjectNode);
// Remove the old triple.
editableKnowledgeGraph.remove(oldTriple);

// Define the new triple.
Node newObjectNode = new Node("dog");
Triple newTriple = new Triple(subjectNode, predicateNode, newObjectNode);
// Add the new triple.
editableKnowledgeGraph.add(newTriple);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/update_a_triple.png

Clearing a graph

To clear a whole graph, remove a Triple containing only empty nodes:

EditableKnowledgeGraph editableKnowledgeGraph = ...;
ResourceNode wildcardResourceNode = new ResourceNode("");
Node wildcardNode = new Node(wildcardResourceNode);
Triple triple = new Triple(wildcardResourceNode, wildcardResourceNode, wildcardNode);
// Remove every triple (clear the graph).
editableKnowledgeGraph.remove(triple);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/clear_graph.png

Retrieving the graph name

Retrieve the graph name from an EditableKnowledgeGraph:

// Retrieving the graph name.
EditableKnowledgeGraph editableKnowledgeGraph = ...;
String graphName = editableKnowledgeGraph.getGraphName();

Retrieving the knowledge base

Use the KnowledgeBase to read data from knowledge graphs.

Retrieve the KnowledgeBase with the Knowledge service:

// Retrieving the knowledge base.
Knowledge knowledge = qiContext.getKnowledge();
KnowledgeBase knowledgeBase = knowledge.knowledgeBase();

Querying triples

Query triples by specifying their nodes:

KnowledgeBase knowledgeBase = ...;
ResourceNode bobNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode wildcardResourceNode = new ResourceNode("");
Node wildcardNode = new Node(wildcardResourceNode);
Triple triple = new Triple(bobNode, wildcardResourceNode, wildcardNode);
// Query triples with Bob as subject.
List<Triple> triplesWithBobAsSubject = knowledgeBase.queryTriples(triple, graphName);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/query_triples.png

Querying subjects

Query subjects by specifying a predicate and an object:

KnowledgeBase knowledgeBase = ...;
ResourceNode predicateNode = new ResourceNode("http://softbankrobotics.com/favoriteAnimal");
Node objectNode = new Node("cat");
// Query subjects with "cat" as favorite animal.
List<ResourceNode> subjectsWithCatAsFavoriteAnimal = knowledgeBase.querySubjects(predicateNode, objectNode, graphName);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/query_subjects.png

Querying predicates

Query predicates by specifying a subject and an object:

KnowledgeBase knowledgeBase = ...;
ResourceNode subjectNode = new ResourceNode("http://softbankrobotics.com/Bob");
Node objectNode = new Node("cat");
// Query predicates linking Bob and "cat".
List<ResourceNode> linksBetweenBobAndCat = knowledgeBase.queryPredicates(subjectNode, objectNode, graphName);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/query_predicates.png

Querying objects

Query objects by specifying a subject and a predicate:

KnowledgeBase knowledgeBase = ...;
ResourceNode subjectNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode predicateNode = new ResourceNode("http://softbankrobotics.com/favoriteAnimal");
// Query favorite animals of Bob.
List<Node> favoriteAnimalsOfBob = knowledgeBase.queryObjects(subjectNode, predicateNode, graphName);

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/query_objects.png

Converting objects

Convert the return of a query of objects using the QiContext:

// Return of knowledgeBase.queryObjects(...) (here contains a list of nodes representing strings).
List<Node> nodes = ...;
// Get the values using getValue() on each Node.
List<Object> objects = ...;

// Convert elements one by one.
for (Object o : objects) {
    String string = qiContext.convert(o, String.class);
}

// Convert the whole list.
Type typeForListOfStrings = new TypeToken<List<String>>() {}.getType();
List<String> listOfStrings = qiContext.convert(objects, typeForListOfStrings);

Using meta nodes

A meta node is a ResourceNode representing a Triple:

https://developers.softbankrobotics.com/sites/default/files/repository/58_rst_pepper/public/source/_build/html/_images/meta_node.png

To convert a Triple into a meta node, use queryMetaNode:

KnowledgeBase knowledgeBase = ...;
Triple triple = ...;
// Convert a Triple into a meta node.
ResourceNode metaNode = knowledgeBase.queryMetaNode(triple, graphName);

To convert a meta node into a Triple, use queryTripleFromMetaNode:

KnowledgeBase knowledgeBase = ...;
ResourceNode metaNode =  ...;
// Convert a meta node into a Triple.
Triple triple = knowledgeBase.queryTripleFromMetaNode(metaNode, graphName);

Subscribing to additions/removals

Subscribe to additions/removals of triples using a KnowledgeSubscriber.

Every addition/removal of a matching triple will trigger the corresponding listener:

KnowledgeBase knowledgeBase = ...;
ResourceNode bobNode = new ResourceNode("http://softbankrobotics.com/Bob");
ResourceNode wildcardResourceNode = new ResourceNode("");
Node wildcardNode = new Node(wildcardResourceNode);
Triple triple = new Triple(bobNode, wildcardResourceNode, wildcardNode);
// Subscribe to any triple with Bob as subject.
KnowledgeSubscriber knowledgeSubscriber = knowledgeBase.subscribe(triple, graphName);

knowledgeSubscriber.addOnTripleAddedListener(new KnowledgeSubscriber.OnTripleAddedListener() {
    @Override
    public void onTripleAdded(Triple tripleAdded) {
        // Called when a triple with Bob as subject is added.
    }
});

knowledgeSubscriber.addOnTripleRemovedListener(new KnowledgeSubscriber.OnTripleRemovedListener() {
    @Override
    public void onTripleRemoved(Triple tripleRemoved) {
        // Called when a triple with Bob as subject is removed.
    }
});

See also