diff --git a/proto/iotics/api/meta.proto b/proto/iotics/api/meta.proto index 67d2d94..1cb3ae8 100644 --- a/proto/iotics/api/meta.proto +++ b/proto/iotics/api/meta.proto @@ -23,13 +23,11 @@ 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: @@ -37,11 +35,11 @@ service MetaAPI { // 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; +}