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

Example usage

The following is an example request URL to query a knowledge graph service named SchoolDistrict 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 EnrolledAt 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 EnrolledAt relationship, and the related School entity will be provided along with the specified property values.

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 EntityType. When a query returns relationships, the value for a relationship will include its type and properties. A relationship's type identifies the RelationshipType. 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, originGlobalID, and destinationGlobalID properties. The originGlobalID identifies the entity that is the origin of the relationship. The destinationGlobalID 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 SchoolDistrict. The query counts how many Student entities have an EnrolledAt relationship to a School entity:

MATCH (School)<-[EnrolledAt]-(p:Student) RETURN Count(p)

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 SchoolDistrict 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

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 numStaff 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 QueryRequest.proto file.

PBF Response

Create a PBF-formatted response to get feedback from the operation based on the QueryResponse.proto file.