- URL:
- https://<knowledgegraphserver_graph-url>/query
- Methods:
GET
Description
The query
operation is performed on a knowledge graph service's graph resource. The entities and relationships in the graph are queried by sending an openCypher query. Learn more about openCypher queries.
Request parameters
Parameter | Details |
---|---|
| Allows you to return the entities and relationships in a graph, as well as the properties of those entities and relationships, by providing an openCypher query. |
| The response format. The default response format is Values: |
Example usage
The following is an example request URL to query a knowledge graph service named School
for information about the students enrolled at a specific school. If an openCypher query is specified such as the example below, the query will return the first Student
entity found with the Enrolled
relationship to a School
entity whose name
property is set to Eastside Elementary
:
MATCH (p:Student)-[e:EnrolledAt]->(s:School) WHERE s.name = 'Eastside Elementary' RETURN p,e,s.principal,s.numStaff LIMIT 1
A description of the Student
entity, its Enrolled
relationship, and the related School
entity will be provided along with the specified property values.
Sample request URL
https://machine.domain.com/webadaptor/rest/services/Hosted/SchoolDistrict/KnowledgeGraphServer/graph/query?openCypherQuery=MATCH+%28p%3AStudent%29-%5Be%3AEnrolledAt%5D-%3E%28s%3ASchool%29+WHERE+s.name+%3D+%27Eastside+Elementary%27+RETURN+p%2Ce%2Cs.principal%2Cs.numStaff+LIMIT+1&f=html
HTML Response syntax
When an openCypher query is specified on the HTML page for the knowledge graph server's query operation, an HTML response is displayed on the page. The values returned depend on the query that is issued.
When a query returns entities, the value for an entity will include its label and properties. An entity's label identifies the Entity
. When a query returns relationships, the value for a relationship will include its type and properties. A relationship's type identifies the Relationship
. For both entities and relationships, only properties with a value are included in the response.
An openCypher query can also return individual property values or summary information about the graph's content. In these cases the query will return individual text strings representing the property values or a count of the number of instances of an entity that satisfy the query.
The example below represents the syntax for the example query provided previously. Entities always have globalid
and objectid
properties. Relationships always have globalid
, objectid
, origin
, and destination
properties. The origin
identifies the entity that is the origin of the relationship. The destination
identifies the entity that is the destination of the relationship.
header:
dataModelTimestamp: <dataModelTimestamp>
fieldNames: [<returnValuesFromQuery>]
results:
exceededTransferLimit: <boolean>
rows:
values:
entityValue:
label: <EntityType>
properties:
globalid: {<GUID>}
objectid: <integer>
property1: <property1Value>
property2: <property2Value>
property3: <property3Value>
relationshipValue:
type: <RelationshipType>
properties:
globalid: {<GUID>}
originGlobalID: {<GUID>}
destinationGlobalID: {<GUID>}
objectid: <integer>
property1: <property1Value>
<returnedValue>
<returnedValue>
HTML Response example one
The following is an example request URL to query a knowledge graph service named School
. The query counts how many Student
entities have an Enrolled
relationship to a School
entity:
MATCH (School)<-[EnrolledAt]-(p:Student) RETURN Count(p)
Sample request URL
https://machine.domain.com/webadaptor/rest/services/Hosted/SchoolDistrict/KnowledgeGraphServer/graph/query?openCypherQuery=MATCH (s:School)<-[e:EnrolledAt]-(p:Student) RETURN +Count(p)&f=html
This example illustrates the response to the above query. The response includes one row of data. There is one value, 15
, in one field named Count(p)
.
header:
dataModelTimestamp: 1628172329005
fieldNames: [Count(p)]
results:
exceededTransferLimit: false
rows:
values: [15]
HTML Response example two
The following is an example request URL to query a knowledge graph service named School
for information about the Student entities it contains. If an openCypher query is specified such as the example below, the query will return the first tuple found where a Student
entity (p
) has any relationship (e
) with a School
entity (s
) where the name of the school is Eastside Elementary
:
MATCH (p:Student)-[e]->(s:School) WHERE s.name = 'Eastside Elementary' RETURN p,e,s.principal,s.numStaff LIMIT 1
Sample request URL
https://machine.domain.com/webadaptor/rest/services/Hosted/BeersOfTheWorld/KnowledgeGraphServer/graph/query?openCypherQuery=MATCH+%28b%3ABeer%29+RETURN+b+LIMIT+1&f=html
Full information describing the Student entity and their relationship to the school will be returned, along with individual property of the school identified in the query: the value of the principal
property and the value of the num
property.
header:
dataModelTimestamp: 1628172329005
fieldNames: [p, e, s.principal, s.numStaff]
results:
exceededTransferLimit: false
rows:
values:
entityValue:
label: Student
properties:
name: John Smith
extracurriculars: theatre, band
globalid: {567EACFE-6779-4EBD-8773-F8E1486A6F79}
objectid: 11
relationshipValue:
type: EnrolledAt
properties:
globalid: {F4D89C49-E1C2-4482-9D3E-6919BA9F230F}
originGlobalID: {567EACFE-6779-4EBD-8773-F8E1486A6F79}
destinationGlobalID: {B5025C91-118C-4B28-91D2-3073401C0992}
objectid: 2
startDate: 1628272439016
Ms. Jane Principal
19
PBF Request
Create a PBF-formatted request to perform this operation based on the Query
file.
PBF Response
Create a PBF-formatted response to get feedback from the operation based on the Query
file.