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.
val resourceNode: ResourceNode = ResourceNode("http://softbankrobotics.com/Bob")

// 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.
val node: Node = Node("cat")

// 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.

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

val subjectNode: ResourceNode = ...
val predicateNode: ResourceNode = ...
val objectNode: Node = ...
// Create a Triple.
val triple: Triple = Triple(subjectNode, predicateNode, objectNode)

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.
val knowledge: Knowledge = qiContext.knowledge
val editableKnowledgeGraph: EditableKnowledgeGraph = knowledge.editableKnowledgeGraph(qiContext.robotContext)

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

Adding a triple¶

Add a Triple to an EditableKnowledgeGraph:

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

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);

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:

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

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);

../../../_images/add_multiple_objects.png

Removing a triple¶

Remove triples from an EditableKnowledgeGraph:

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

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:

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:

val editableKnowledgeGraph: EditableKnowledgeGraph = ...

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

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

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);

Clearing a graph¶

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

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

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);

Retrieving the graph name¶

Retrieve the graph name from an EditableKnowledgeGraph:

 // Retrieving the graph name.
val editableKnowledgeGraph: EditableKnowledgeGraph = ...
val graphName: String = editableKnowledgeGraph.graphName

// 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.
val knowledge: Knowledge = qiContext.knowledge
val knowledgeBase: KnowledgeBase = knowledge.knowledgeBase()

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

Querying triples¶

Query triples by specifying their nodes:

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

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);

Querying subjects¶

Query subjects by specifying a predicate and an object:

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

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);

Querying predicates¶

Query predicates by specifying a subject and an object:

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

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);

Querying objects¶

Query objects by specifying a subject and a predicate:

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

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);

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).
val nodes: List<Node> = ...

// Get the values on each Node.
val objects: List<Any> = nodes.map { it.value }

// Convert elements one by one.
objects.forEach {
    val string = qiContext.convert<String>(it, String::class.java)
}

// Convert the whole list.
val typeForListOfStrings: Type = object : TypeToken<List<String>>() {}.type
val listOfStrings: List<String> = qiContext.convert<String>(objects, typeForListOfStrings)

// 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:

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

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

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:

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

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:

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

knowledgeSubscriber.addOnTripleAddedListener {
    // Called when a triple with Bob as subject is added.
}

knowledgeSubscriber.addOnTripleRemovedListener {
    // Called when a triple with Bob as subject is removed.
}

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.
    }
});