EI-2742 - Introduce FKGQuery RPC, remove SparqlQuery

- Local-scope SparqlQuery can be performed with FKGQuery local-scope

proto/iotics/api/meta.proto

@@ -23,25 +23,23 @@ option php_namespace = "Iotics\\Api";
 // Services only affect local resources, unless stated otherwise.
 service MetaAPI {
 
-  // SparqlQuery performs a SPARQL 1.1 query and returns one or more results, each as a sequence of chunks. Note that:
-  // - Chunks for a particular result will arrive in-order though they might be interleaved with chunks from other
-  //   results (when performing a non-local query). See scope parameter in SparqlQueryRequest;
-  // - The call will only complete once the (specified or host default) request timeout has been reached. The client can
-  //   choose to end the stream early once they have received enough results. (E.g. in the case of Scope.LOCAL this
-  //   would be after the one and only sequence of chunks has been received.). (local and remote)
-  rpc SparqlQuery(SparqlQueryRequest) returns (stream SparqlQueryResponse) {}
+  // FKGQuery performs a SPARQL 1.1 query against the Federated Knowledge Graph of the Iotics network to which this host
+  // belongs. The result is returned as a sequence of chunks. Note that:
+  // - Result chunks MIGHT arrive out of order and it is the client's responsibility to re-assemble them.
+  // - This RPC is currently in alpha!
+  rpc FKGQuery(FKGQueryRequest) returns (stream FKGQueryResponse) {}
 
   // SparqlUpdate performs a SPARQL 1.1 update. When performing an update, the update query must contain a reference to
   // one of the following graph IRIs:
   // 1. http://data.iotics.com/graph#custom-public (aka custom public graph) - All metadata written to this graph will be
   //    visible during SPARQL queries both with local & global scope (and thus, the Iotics network).
   rpc SparqlUpdate(SparqlUpdateRequest) returns (SparqlUpdateResponse) {}
 
-  // ExplorerQuery - Deprecated - use SparqlQuery instead.
+  // ExplorerQuery - Deprecated - use FKGQuery instead.
   rpc ExplorerQuery(ExplorerRequest) returns (stream SparqlQueryResponse) {}
 }
 
-// ExplorerRequest - Deprecated. Use SparqlQueryRequest instead.
+// ExplorerRequest - Deprecated. Use FKGQuery instead.
 message ExplorerRequest {
 
   // Explorer request payload.
@@ -82,29 +80,6 @@ enum SparqlResultType {
   RDF_NTRIPLES = 5;
 }
 
-// SparqlQueryRequest describes a SPARQL query.
-message SparqlQueryRequest {
-
-  // SPARQL query request payload.
-  message Payload {
-
-    // The desired result content type. Note that choosing an invalid result type for the type of query will result in
-    // an error status reported in the response. (See SparqlResultType for valid content-query type combinations.)
-    SparqlResultType resultContentType = 1;
-    // A UTF8-encoded SPARQL 1.1 query
-    bytes query = 2;
-  }
-
-  // SPARQL query request headers
-  Headers headers = 1;
-
-  // SPARQL query request scope
-  Scope scope = 2;
-
-  // SPARQL query request payload
-  Payload payload = 3;
-}
-
 // SparqlQueryResponse is a part of a result for a SPARQL query request. Multiple chunks form a complete result. Related
 // chunks can be identified by a combination of:
 // - The hostId
@@ -168,3 +143,58 @@ message SparqlUpdateResponse {
   // SPARQL update response headers
   Headers headers = 1;
 }
+
+// FKGQueryRequest describes a SPARQL query.
+message FKGQueryRequest {
+
+  // SPARQL query request payload.
+  message Payload {
+
+    // The desired result content type. Note that choosing an invalid result type for the type of query will result in
+    // an error status reported in the response. (See SparqlResultType for valid content-query type combinations.)
+    SparqlResultType resultContentType = 1;
+    // A UTF8-encoded SPARQL 1.1 query
+    bytes query = 2;
+  }
+
+  // SPARQL query request headers
+  Headers headers = 1;
+
+  // SPARQL query request scope
+  Scope scope = 2;
+
+  // SPARQL query request payload
+  Payload payload = 3;
+}
+
+// FKGQueryResponse is a part of a result for a SPARQL query request. Multiple chunks form a complete result. Related
+// chunks can be identified by a combination of:
+// - Client reference (in headers, set by caller)
+// - Chunk sequence number
+message FKGQueryResponse {
+
+  // Payload of the query result chunk
+  message Payload {
+
+    // Position of a chunk in result for a given request. The first chunk has a sequence number of 0.
+    uint64 seqNum = 1;
+
+    // Indicates whether this is the last chunk, for a specific request. Results for different requests can be
+    // identified by setting a unique clientRef in the request headers.
+    bool last = 2;
+
+    // Content type of the result.
+    SparqlResultType contentType = 3;
+
+    // Query result chunk, encoded according to actualType.
+    // Note that:
+    // - The maximum size of each chunk is host-specific.
+    bytes resultChunk = 4;
+  }
+
+  // Headers for the query result. clientRef within can be used to identify which query the result applies to.
+  Headers headers = 1;
+
+  // SPARQL query result chunk payload.
+  Payload payload = 2;
+}