Using roboy_memory¶
As part of the restructuring of dialog, the ROS connection between Dialog and Memory has been removed. Instead, one can now use memory as a static library. We still retain the ability to start the ROS services if the need arises, however it is not recommendable due to efficiency reasons.
Availible Operations¶
The Roboy Memory Module offers the next services in order to work with the memory contents:
- create - creates a node in the Neo4j DB with provided properties and face features (Redis)
- update - adds new relationships between specified nodes or properties to the specified node
- get - retrieves information about the specified node or returns IDs of all nodes which fall into the provided conditions
- remove - removes properties or relationships from the specified node
Using Direct Function calls¶
One can now simply call the functions:
create(String request)
update(String request)
get(String request)
remove(String request)
These functions are located in org.roboy.memory.util.MemoryOperations
and can be called, as long as a NEO4J is running at the points specified in your environmental variables (see getting started).
The functions take JSON-formed queries as parameters. There is no need for a header in this case, all one needs to do is to send the payload.
Create queries¶
Create a node of the type ‘Person’ with properties:
MemoryOperations.create("{'type':'node','label':'Person','properties':{'name':'Lucas','sex':'male'}}");
On success you will get:
Answer: {‘id’: x } - //ID of the created node
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Update queries¶
Add properties to the node with id 15:
MemoryOperations.update("{ 'type':'node', 'id':15, 'properties':{ 'surname':'Ki', 'xyz':'abc' } }");
Add relationships to the node with id 15:
MemoryOperations.update("{'type':'node','id':15,'relationships':{'LIVE_IN':[28,23],'STUDY_AT':[16]}}"
Add properties + relationships to the node with id 15:
"{'type':'node','id':15,'properties':{'surname':'Ki', 'xyz':123},'relationships':{'LIVE_IN':[28,23],'STUDY_AT':[16]}}"
On success you will get:
Answer: {status:”OK”}
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Get queries¶
Get properties and relationships of a node by id:
MemoryOperations.get("{'id':15}");
Answer::
{
'id': 15,
'labels': ["person"],
'properties': {
"birthdate":"01.01.1970",
"surname":"ki",
"sex":"male",
"name":"lucas"
},
'relationships': {
"from":[28],
"friend_of":[124, 4, 26, 104, 106, 71, 96, 63],
"member_of":[20], "study_at":[16], "is":[17],
"has_hobby":[18],
"live_in":[23, 28]
}
}
Get ids of nodes which have all specified labels, relationships and/or properties:
MemoryOperations.get("{'label':'Person','relationships':{'FRIEND_OF':[15]},'properties':{'name':'Laura'}}");
On success you will get:
Answer: {‘id’:[x]} - an array with all fitting IDs
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Remove queries¶
Warning
Please, do not try running remove queries without considering significant risks. Be responsible!
Remove properties of node 15:
MemoryOperations.remove("{'type':'node','id':15,'properties':['birthdate','surname']}");
Remove relationships of node 15:
MemoryOperations.remove("{'type':'node','id':15,'relationships':{'LIVE_IN':[28,23],'STUDY_AT':[16]}}");
Remove properties and relationships of node 15:
MemoryOperations.remove("{'type':'node','id':15,'properties':['birthdate','surname'],'relationships':{'LIVE_IN':[23]}}");
On success you will get:
Answer: {status:”OK”}
On error you will get:
Error: {status:”FAIL”, message:”error message”}
Using ROS¶
There you can find basic examples on how to access the memory with JSON-formed queries using ROS. For more information, please, refer to Public Interfaces (ROS), Neo4j Memory Architecture and Roboy Communication Standard.
To start the ROS services, simply run the Main class’ Main method.
Verifying ROS services are active¶
In order to check available services, in your catkin environment, run:
rosservice list
You should get the next output:
/roboy/cognition/memory/create
/roboy/cognition/memory/cypher
/roboy/cognition/memory/get
/roboy/cognition/memory/remove
/roboy/cognition/memory/update
/rosout/get_loggers
/rosout/set_logger_level
Calling the ROS¶
General syntax for a ROS message:
rosservice call /roboy/cognition/memory/--service_name-- "\"---header---\"" "\"---payload---\""
Sample Header:
The header (JSON object) consists of a timestamp and the module which is sending the query (‘user’): You may try using the next header for your initial experience.
{
'user':'test',
'datetime':'0'
}
Payload Elements:
The payload (JSON object) may comprise several elements such as:
- ‘label’ specifies the class of node in the knowledge graph
- ‘id’ of a node is a unique number specified for each node that may be accessed be searched or modified in the knowledge graph
- ‘relationships’ comprise a map of relationship types with an array of node IDs for each of them, providing multiple relationships tracing
- ‘properties’ = A map of property keys with values
Consider Roboy Communication Standard for the correct use use of properties, relationships and labels. Sample payloads as well as the whole structure of the calls are mentioned below.
Create queries¶
Create a node of the type ‘Person’ with properties:
rosservice call /roboy/cognition/memory/create "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'label':'Person',
'properties':{
'name':'Lucas',
'sex':'male'
}
}\""
On success you will get:
Answer: {‘id’: x } - //ID of the created node
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Update queries¶
Add properties to the node with id 15:
rosservice call /roboy/cognition/memory/update "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'properties':{
'surname':'Ki',
'xyz':'abc'
}
}\""
Add relationships to the node with id 15:
rosservice call /roboy/cognition/memory/update "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'relationships':{
'LIVE_IN':[28,23],
'STUDY_AT':[16]
}
}\""
Add properties + relationships to the node with id 15:
rosservice call /roboy/cognition/memory/update "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'properties':{
'surname':'Ki', 'xyz':123
},
'relationships':{
'LIVE_IN':[28,23],
'STUDY_AT':[16]
}
}\""
On success you will get:
Answer: {status:”OK”}
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Get queries¶
Get properties and relationships of a node by id:
rosservice call /roboy/cognition/memory/get "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'id':15
}\""
Answer::
{
'id': 15,
'labels': ["person"],
'properties': {
"birthdate":"01.01.1970",
"surname":"ki",
"sex":"male",
"name":"lucas"
},
'relationships': {
"from":[28],
"friend_of":[124, 4, 26, 104, 106, 71, 96, 63],
"member_of":[20], "study_at":[16], "is":[17],
"has_hobby":[18],
"live_in":[23, 28]
}
}
Get ids of nodes which have all specified labels, relationships and/or properties:
rosservice call /roboy/cognition/memory/get "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'label':'Person',
'relationships':{
'FRIEND_OF':[15]
},
'properties':{
'name':'Laura'
}
}\""
On success you will get:
Answer: {‘id’:[x]} - an array with all fitting IDs
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)
Remove queries¶
Warning
Please, do not try running remove queries without considering significant risks. Be responsible!
Remove properties of node 15:
rosservice call /roboy/cognition/memory/remove "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'properties':['birthdate','surname']
}\""
Remove relationships of node 15:
rosservice call /roboy/cognition/memory/remove "\"{
'user':'vision','datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'relationships':{
'LIVE_IN':[28,23],
'STUDY_AT':[16]
}
}\""
Remove properties and relationships of node 15:
rosservice call /roboy/cognition/memory/remove "\"{
'user':'vision',
'datetime':'1234567'
}\"" "\"{
'type':'node',
'id':15,
'properties':['birthdate','surname'],
'relationships':{
'LIVE_IN':[23]
}
}\""
On success you will get:
Answer: {status:”OK”}
On error you will get:
Error: {status:”FAIL”, message:”error message”}
You can find detailed information in Public Interfaces (ROS)