Protocol Documentation
Table of Contents
grpc.proto
RdfStreamReceived
Acknowledgement of receiving a stream sent by the server to the client.
RdfStreamSubscribe
Subscribe command sent by the client to the server.
| Field | Type | Label | Description |
|---|---|---|---|
| topic | string | The topic to which the client wants to subscribe (UTF-8 encoded). | |
| requested_options | RdfStreamOptions | Optional: the stream options requested by the client. The server should respond with a stream that matches these options. In case that is not possible, the server must respond with the INVALID_ARGUMENT error. |
RdfStreamService
Pub/Sub service for RDF streams, to be implemented by the server.
| Method Name | Request Type | Response Type | Description |
|---|---|---|---|
| SubscribeRdf | RdfStreamSubscribe | RdfStreamFrame stream | Subscribe to an RDF stream. |
| PublishRdf | RdfStreamFrame stream | RdfStreamReceived | Publish an RDF stream. In case the server cannot process the stream, it must respond with the INVALID_ARGUMENT error. |
patch.proto
RdfPatchFrame
A batch of RDF patch rows.
| Field | Type | Label | Description |
|---|---|---|---|
| rows | RdfPatchRow | repeated | Patch rows |
RdfPatchHeader
Metadata header for RDF Patch. Header rows must occur at the start of the patch frame.
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | Header key (required) | |
| h_iri | eu.ostrzyciel.jelly.core.proto.v1.RdfIri | IRI | |
| h_bnode | string | Blank node | |
| h_literal | eu.ostrzyciel.jelly.core.proto.v1.RdfLiteral | Literal | |
| h_triple_term | eu.ostrzyciel.jelly.core.proto.v1.RdfTriple | RDF-star quoted triple |
RdfPatchNamespace
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Short name of the namespace (e.g., "ex") Do NOT include the colon. | |
| value | eu.ostrzyciel.jelly.core.proto.v1.RdfIri | IRI of the namespace (e.g., "http://example.org/")..) Optional in the "prefix delete" (PD) operation, but required in the "prefix add" (PA) operation. | |
| g_iri | eu.ostrzyciel.jelly.core.proto.v1.RdfIri | IRI | |
| g_bnode | string | Blank node | |
| g_default_graph | eu.ostrzyciel.jelly.core.proto.v1.RdfDefaultGraph | Default graph | |
| g_literal | eu.ostrzyciel.jelly.core.proto.v1.RdfLiteral | Literal – only valid for generalized RDF streams |
RdfPatchOptions
RDF Patch stream options
| Field | Type | Label | Description |
|---|---|---|---|
| statement_type | PatchStatementType | Type of statements in the stream (required) | |
| stream_type | PatchStreamType | Type of the stream (required) | |
| generalized_statements | bool | Whether the stream may contain generalized triples, quads, or datasets | |
| rdf_star | bool | Whether the stream may contain RDF-star statements | |
| max_name_table_size | uint32 | Maximum size of the name lookup table (required, must be >= 8) | |
| max_prefix_table_size | uint32 | Maximum size of the prefix lookup table (required if the prefix lookup is used) | |
| max_datatype_table_size | uint32 | Maximum size of the datatype lookup table (required if datatype literals are used) | |
| version | uint32 | Protocol version (required) For Jelly-Patch 1.0.x (based on Jelly-RDF 1.1.x), the value must be 1. For custom extensions, the value must be 10000 or higher. |
RdfPatchPunctuation
RdfPatchRow
A row in an RDF Patch stream
| Field | Type | Label | Description |
|---|---|---|---|
| options | RdfPatchOptions | Stream options. Must be the first row in the stream. | |
| statement_add | eu.ostrzyciel.jelly.core.proto.v1.RdfQuad | Add a triple/quad statement (A) | |
| statement_delete | eu.ostrzyciel.jelly.core.proto.v1.RdfQuad | Delete a triple/quad statement (D) | |
| namespace_add | RdfPatchNamespace | Add a namespace/prefix declaration (PA) | |
| namespace_delete | RdfPatchNamespace | Delete a namespace/prefix declaration (PD) | |
| transaction_start | RdfPatchTransactionStart | Transaction start (TX) | |
| transaction_commit | RdfPatchTransactionCommit | Transaction commit (TC) | |
| transaction_abort | RdfPatchTransactionAbort | Transaction abort (TA) | |
| name | eu.ostrzyciel.jelly.core.proto.v1.RdfNameEntry | Entry in the name lookup table. | |
| prefix | eu.ostrzyciel.jelly.core.proto.v1.RdfPrefixEntry | Entry in the prefix lookup table. | |
| datatype | eu.ostrzyciel.jelly.core.proto.v1.RdfDatatypeEntry | Entry in the datatype lookup table. | |
| header | RdfPatchHeader | Header entry (H) | |
| punctuation | RdfPatchPunctuation | Punctuation mark, only used in stream type PUNCTUATED Indicates the end of a patch. |
RdfPatchTransactionAbort
RdfPatchTransactionCommit
RdfPatchTransactionStart
PatchStatementType
Type of statements in the stream. This determines whether the statements are interpreted as triples or quads.
| Name | Number | Description |
|---|---|---|
| PATCH_STATEMENT_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| PATCH_STATEMENT_TYPE_TRIPLES | 1 | RDF triples |
| PATCH_STATEMENT_TYPE_QUADS | 2 | RDF quads |
PatchStreamType
Type of the stream. This determines whether each RdfPatchFrame is a complete patch by itself, or part of a larger patch.
| Name | Number | Description |
|---|---|---|
| PATCH_STREAM_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| PATCH_STREAM_TYPE_FRAME | 1 | Each RdfPatchFrame is a complete patch. In this case, transactions cannot span multiple frames. |
| PATCH_STREAM_TYPE_FLAT | 2 | Entire stream is a single patch. Transactions may span multiple frames. |
| PATCH_STREAM_TYPE_PUNCTUATED | 3 | Stream contains multiple patches separated by punctuation marks. Patches and transactions may span multiple frames. Each frame must contain at most one patch. |
rdf.proto
RdfDatatypeEntry
Entry in the datatype lookup table
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfDatatypeEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the datatype (UTF-8 encoded) |
RdfDefaultGraph
Empty message indicating the default RDF graph.
RdfGraphEnd
End of a graph in a GRAPHS stream
RdfGraphStart
Start of a graph in a GRAPHS stream
In contrast to RdfQuad, setting the graph oneof to some value is always required. No repeated terms are allowed.
| Field | Type | Label | Description |
|---|---|---|---|
| g_iri | RdfIri | IRI | |
| g_bnode | string | Blank node | |
| g_default_graph | RdfDefaultGraph | Default graph | |
| g_literal | RdfLiteral | Literal – only valid for generalized RDF streams |
RdfIri
RDF IRIs The IRIs are reconstructed by the consumer using the prefix and name lookup tables.
| Field | Type | Label | Description |
|---|---|---|---|
| prefix_id | uint32 | 1-based, refers to an entry in the prefix lookup. 0 signifies "use the same prefix_id as in the previous IRI". For this to work, IRIs must be processed strictly in order: firstly by stream row, then by term (subject, predicate, object, graph). This also applies recursively to RDF-star quoted triples. If 0 appears in the first IRI of the stream (and in any subsequent IRI), this should be interpreted as an empty ("") prefix. This is for example used when the prefix lookup table is disabled. | |
| name_id | uint32 | 1-based, refers to an entry in the name lookup. 0 signifies "use the previous name_id + 1". This requires the same order guarantees as prefixes. If 0 appears in the first IRI of the stream, it should be interpreted as name_id = 1. |
RdfLiteral
RDF literals
| Field | Type | Label | Description |
|---|---|---|---|
| lex | string | The lexical form of the literal (required). | |
| langtag | string | Language-tagged string. | |
| datatype | uint32 | Typed literal. The datatype is a reference to an entry in the datatype lookup. This value is 1-based and the value of 0 is invalid (in contrast to prefix_id and name_id in RdfIri). |
RdfNameEntry
Entry in the name lookup table
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfNameEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the name (UTF-8 encoded) |
RdfNamespaceDeclaration
Explicit namespace declaration
This does not correspond to any construct in the RDF Abstract Syntax. Rather, it is a hint to the consumer that the given IRI prefix (namespace) may be associated with a shorter name, like in Turtle syntax: PREFIX ex: <http://example.org/>
These short names (here "ex:") are NOT used in the RDF statement encoding. This is a purely cosmetic feature useful in cases where you want to preserve the namespace declarations from the original RDF document. These declarations have nothing in common with the prefix lookup table.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Short name of the namespace (e.g., "ex") Do NOT include the colon. | |
| value | RdfIri | IRI of the namespace (e.g., "http://example.org/")) |
RdfPrefixEntry
Entry in the prefix lookup table
Note: the prefixes in the lookup table can be arbitrary strings, and are NOT meant to be user-facing. They are only used for IRI compression. To transmit user-facing namespace declarations for cosmetic purposes, use RdfNamespaceDeclaration.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first RdfPrefixEntry of the stream, it should be interpreted as 1. | |
| value | string | Value of the prefix (UTF-8 encoded) |
RdfQuad
RDF quad
Fields 1–12 are repeated from RdfTriple for performance reasons.
Similarly to RdfTriple, this message allows for representing generalized RDF quads (for example, with literals as predicates). Whether this is used in the stream is determined by the stream options (see RdfStreamOptions).
If no field in a given oneof is set, the term is interpreted as a repeated term – the same as the term in the same position in the previous quad. In the first quad of the stream, all terms must be set.
| Field | Type | Label | Description |
|---|---|---|---|
| s_iri | RdfIri | IRI | |
| s_bnode | string | Blank node | |
| s_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| s_triple_term | RdfTriple | RDF-star quoted triple | |
| p_iri | RdfIri | IRI | |
| p_bnode | string | Blank node Only valid in a generalized RDF stream. | |
| p_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| p_triple_term | RdfTriple | RDF-star quoted triple | |
| o_iri | RdfIri | IRI | |
| o_bnode | string | Blank node | |
| o_literal | RdfLiteral | Literal | |
| o_triple_term | RdfTriple | RDF-star quoted triple | |
| g_iri | RdfIri | IRI | |
| g_bnode | string | Blank node | |
| g_default_graph | RdfDefaultGraph | Default graph | |
| g_literal | RdfLiteral | Literal – only valid for generalized RDF streams |
RdfStreamFrame
RDF stream frame – base message for RDF streams.
| Field | Type | Label | Description |
|---|---|---|---|
| rows | RdfStreamRow | repeated | Stream rows |
| metadata | RdfStreamFrame.MetadataEntry | repeated | Arbitrary metadata The keys are UTF-8 encoded strings, the values are byte arrays. This may be used by implementations in any way they see fit. The metadata does not affect the RDF data in any way, treat it as comments in a text file. |
RdfStreamFrame.MetadataEntry
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | bytes |
RdfStreamOptions
RDF stream options
| Field | Type | Label | Description |
|---|---|---|---|
| stream_name | string | Name of the stream (completely optional). This may be used for, e.g., topic names in a pub/sub system. | |
| physical_type | PhysicalStreamType | Type of the stream (required) | |
| generalized_statements | bool | Whether the stream may contain generalized triples, quads, or datasets | |
| rdf_star | bool | Whether the stream may contain RDF-star statements | |
| max_name_table_size | uint32 | Maximum size of the name lookup table (required, must be >= 8) | |
| max_prefix_table_size | uint32 | Maximum size of the prefix lookup table (required if the prefix lookup is used) | |
| max_datatype_table_size | uint32 | Maximum size of the datatype lookup table (required if datatype literals are used) | |
| logical_type | LogicalStreamType | Logical (RDF-STaX-based) stream type In contrast to the physical type, this field is entirely optional. | |
| version | uint32 | Protocol version (required) For Jelly 1.0.x value must be 1. For Jelly 1.1.x value must be 2. For custom extensions, the value must be 10000 or higher. |
RdfStreamRow
RDF stream row
| Field | Type | Label | Description |
|---|---|---|---|
| options | RdfStreamOptions | Stream options. Must occur at the start of the stream. | |
| triple | RdfTriple | RDF triple statement. Valid in streams of physical type TRIPLES or GRAPHS. | |
| quad | RdfQuad | RDF quad statement. Only valid in streams of physical type QUADS. | |
| graph_start | RdfGraphStart | Graph boundary: ends the currently transmitted graph and starts a new one Only valid in streams of physical type GRAPHS. | |
| graph_end | RdfGraphEnd | Explicit end of a graph. Signals the consumer that the transmitted graph is complete. Only valid in streams of physical type GRAPHS. | |
| namespace | RdfNamespaceDeclaration | Explicit namespace declaration. | |
| name | RdfNameEntry | Entry in the name lookup table. | |
| prefix | RdfPrefixEntry | Entry in the prefix lookup table. | |
| datatype | RdfDatatypeEntry | Entry in the datatype lookup table. |
RdfTriple
RDF triple
For each term (subject, predicate, object), the fields are repeated for performance reasons. This is to avoid the need for boxing each term in a separate message.
Note: this message allows for representing generalized RDF triples (for example, with literals as predicates). Whether this is used in the stream is determined by the stream options (see RdfStreamOptions).
If no field in a given oneof is set, the term is interpreted as a repeated term – the same as the term in the same position in the previous triple. In the first triple of the stream, all terms must be set. All terms must also be set in quoted triples (RDF-star).
| Field | Type | Label | Description |
|---|---|---|---|
| s_iri | RdfIri | IRI | |
| s_bnode | string | Blank node | |
| s_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| s_triple_term | RdfTriple | RDF-star quoted triple | |
| p_iri | RdfIri | IRI | |
| p_bnode | string | Blank node Only valid in a generalized RDF stream. | |
| p_literal | RdfLiteral | Literal Only valid in a generalized RDF stream. | |
| p_triple_term | RdfTriple | RDF-star quoted triple | |
| o_iri | RdfIri | IRI | |
| o_bnode | string | Blank node | |
| o_literal | RdfLiteral | Literal | |
| o_triple_term | RdfTriple | RDF-star quoted triple |
LogicalStreamType
Logical stream type, according to the RDF Stream Taxonomy (RDF-STaX). Type 0 is reserved for the unspecified stream type. The rest of the type numbers follow the taxonomical structure of RDF-STaX. For example: 1 is a subtype of 0, 13 and 23 are subtypes of 3, 114 is a subtype of 14, etc.
Types 1–4 correspond to the four base concrete stream types. Their subtypes can be in most cases simply processed in the same way as the base types. Therefore, implementations can take the modulo 10 of the stream type to determine the base type of the stream and use this information to select the appropriate processing logic.
RDF-STaX version: 1.1.2 https://w3id.org/stax/1.1.2
^ The above URL is used to automatically determine the version of RDF-STaX in the Jelly protocol specification. Please keep it up-to-date and in the same format.
| Name | Number | Description |
|---|---|---|
| LOGICAL_STREAM_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| LOGICAL_STREAM_TYPE_FLAT_TRIPLES | 1 | Flat RDF triple stream https://w3id.org/stax/ontology#flatTripleStream |
| LOGICAL_STREAM_TYPE_FLAT_QUADS | 2 | Flat RDF quad stream https://w3id.org/stax/ontology#flatQuadStream |
| LOGICAL_STREAM_TYPE_GRAPHS | 3 | RDF graph stream https://w3id.org/stax/ontology#graphStream |
| LOGICAL_STREAM_TYPE_DATASETS | 4 | RDF dataset stream https://w3id.org/stax/ontology#datasetStream |
| LOGICAL_STREAM_TYPE_SUBJECT_GRAPHS | 13 | RDF subject graph stream (subtype of RDF graph stream) https://w3id.org/stax/ontology#subjectGraphStream |
| LOGICAL_STREAM_TYPE_NAMED_GRAPHS | 14 | RDF named graph stream (subtype of RDF dataset stream) https://w3id.org/stax/ontology#namedGraphStream |
| LOGICAL_STREAM_TYPE_TIMESTAMPED_NAMED_GRAPHS | 114 | RDF timestamped named graph stream (subtype of RDF dataset stream) https://w3id.org/stax/ontology#timestampedNamedGraphStream |
PhysicalStreamType
Physical stream type This determines how the data is encoded in the stream, not the logical structure of the data. See LogicalStreamType for the latter.
| Name | Number | Description |
|---|---|---|
| PHYSICAL_STREAM_TYPE_UNSPECIFIED | 0 | Unspecified stream type – invalid |
| PHYSICAL_STREAM_TYPE_TRIPLES | 1 | RDF triples |
| PHYSICAL_STREAM_TYPE_QUADS | 2 | RDF quads |
| PHYSICAL_STREAM_TYPE_GRAPHS | 3 | RDF triples grouped in graphs |
rdf2.proto
RdfLiteral2
RDF literal, with support for the RDF 1.2 base direction.
Fields 1–3 are the same as in RdfLiteral (rdf.proto), so every valid RdfLiteral message is also a valid RdfLiteral2 message with no base direction, and the other way round. TODO (RDF 1.2): unify this!
| Field | Type | Label | Description |
|---|---|---|---|
| lex | string | The lexical form of the literal (required). | |
| langtag | string | Language-tagged string. | |
| datatype | uint32 | Typed literal. The datatype is a reference to an entry in the datatype lookup. This value is 1-based and the value of 0 is invalid (in contrast to prefix_id and name_id in RdfIri). Must not refer to rdf:langString or rdf:dirLangString – use langtag and direction instead. | |
| direction | RdfBaseDirection | Base direction of a language-tagged string. Must not be set unless langtag is set. |
RdfLookupEntryPacked
Packed entries of a lookup table (name, prefix, or datatype).
Lookup entries are almost always assigned consecutive identifiers, because that is what the "id = 0 means previous_id + 1" rule of the unpacked entries optimizes for. A packed entry states the identifier once and then lists the values of a whole run of consecutive entries, saving the framing of every entry after the first.
The identifier of the first value follows the same rule as the unpacked entries: 0 means previous_id + 1, or 1 at the start of the stream. Every following value takes the identifier of the previous one plus 1.
A packed entry with no values at all is a no-op and must not be written.
| Field | Type | Label | Description |
|---|---|---|---|
| id | uint32 | 1-based identifier of the first value. If id=0, it should be interpreted as previous_id + 1. If id=0 appears in the first entry of a given lookup table in the stream, it should be interpreted as 1. | |
| values | string | repeated | Values of the lookup entries (UTF-8 encoded), for consecutive identifiers starting at id. |
RdfTripleTerm
RDF 1.2 triple term.
This message can only represent triples that are valid in RDF 1.2: the subject is an IRI or a blank node, the predicate is an IRI, and only the object may be a nested triple term. There are no repeated terms: every position must be set.
The field numbers are the same as in RdfTriple.
| Field | Type | Label | Description |
|---|---|---|---|
| s_iri | RdfIri | IRI | |
| s_bnode | string | Blank node | |
| p_iri | RdfIri | Predicate (required). | |
| o_iri | RdfIri | IRI | |
| o_bnode | string | Blank node | |
| o_literal | RdfLiteral2 | Literal | |
| o_triple_term | RdfTripleTerm | Nested triple term |
RdfBaseDirection
Initial text direction of a language-tagged string (RDF 1.2).
| Name | Number | Description |
|---|---|---|
| RDF_BASE_DIRECTION_UNSPECIFIED | 0 | No base direction: an ordinary language-tagged string (rdf:langString). |
| RDF_BASE_DIRECTION_LTR | 1 | Left-to-right ("ltr"): a directional language-tagged string (rdf:dirLangString). |
| RDF_BASE_DIRECTION_RTL | 2 | Right-to-left ("rtl"): a directional language-tagged string (rdf:dirLangString). |
RdfVersion
Version of RDF that a stream conforms to, following the version labels of RDF 1.2 Concepts: https://www.w3.org/TR/rdf12-concepts/#defined-version-labels
Each version includes the ones listed before it: RDF 1.1 data is valid RDF 1.2 Basic data, which is valid RDF 1.2 data.
| Name | Number | Description |
|---|---|---|
| RDF_VERSION_UNSPECIFIED | 0 | Unspecified. Each format that uses this enum defines how to interpret it. |
| RDF_VERSION_1_1 | 1 | RDF 1.1 (version label "1.1"): no triple terms, no base directions. |
| RDF_VERSION_1_2_BASIC | 2 | RDF 1.2 Basic (version label "1.2-basic"): base directions are allowed, triple terms are not. |
| RDF_VERSION_1_2 | 3 | RDF 1.2 (version label "1.2"): base directions and triple terms are allowed. |
sparql.proto
SparqlAskResult
Boolean result of a SPARQL ASK query.
| Field | Type | Label | Description |
|---|---|---|---|
| value | bool | The boolean value of the result. |
SparqlBnodeColumn
Column of blank node values.
| Field | Type | Label | Description |
|---|---|---|---|
| values | string | repeated | Run values (blank node labels), in row order. |
| layouts | uint32 | repeated | Sequence layout, see above. |
SparqlIriColumn
Column of IRI values.
The run values are two parallel packed lists of prefix and name identifiers.
| Field | Type | Label | Description |
|---|---|---|---|
| name_ids | uint32 | repeated | Name identifiers of the run values, in row order. This list defines the number of run values in the column. The name_id inference rule of RdfIri applies along this list: 0 means "previous name_id + 1", and the state resets at the start of every column in every frame, where 0 means name_id = 1. Columns can therefore be decoded independently of each other (given the lookup tables). |
| layouts | uint32 | repeated | Sequence layout, see above. Empty = every cell is bound, no repeats. |
| prefix_ids | uint32 | repeated | Prefix identifiers of the run values, in row order. The list must have one of three lengths: 0 – every value has prefix_id = 0 (no prefix), which is the case when the prefix lookup is disabled 1 – every value uses this one prefix, which is the case for a column of IRIs sharing a namespace len(name_ids) – one entry per value In the third form the prefix_id inference rule of RdfIri applies along the list: 0 means "same prefix as the previous IRI", starting from 0. This is the last field of the message because it is usually tiny. |
SparqlLiteralColumn
Column of literal values.
Each run value is a lexical form plus a literal kind, which says whether it is a simple literal, a literal with a datatype from the datatype lookup, or a language-tagged string with one of the column's language tags. A column in which every value has the same kind states the kind once, which lets readers keep the column in a string array instead of one object per value.
| Field | Type | Label | Description |
|---|---|---|---|
| lex_values | string | repeated | Lexical forms of the run values, in row order. This list defines the number of run values in the column. |
| layouts | uint32 | repeated | Sequence layout, see above. |
| literal_kinds | uint32 | repeated | Literal kind of each run value, parallel to lex_values: 0 – simple literal (xsd:string) odd v – literal with the datatype of datatype lookup id (v + 1) / 2 even v > 0 – language-tagged string with language tag v / 2 - 1, an index into langtags The list must have one of three lengths: 0 – every value is a simple literal 1 – every value has this kind len(lex_values) – one entry per value A datatype must not be rdf:langString or rdf:dirLangString – use a language tag instead. Simple literals do not need an xsd:string entry in the datatype lookup. |
| langtags | string | repeated | The language tags referred to by literal_kinds, in the order of first use. Each should be a valid BCP 47 language tag. The same tag may appear more than once, with different base directions. |
| langtag_directions | uint32 | repeated | Base directions of the language tags (RdfBaseDirection numbers), parallel to langtags. Empty means no base direction for any tag. A direction other than RDF_BASE_DIRECTION_UNSPECIFIED is not valid if the stream options declare RDF_VERSION_1_1. |
SparqlPolyColumn
Polymorphic column: values may be RDF terms of any type. To be used only for variables whose values mix term types – prefer the monomorphic columns whenever possible.
The run values are split by term type into typed sub-columns. The kinds
field says which sub-column contains the next run value. The sub-columns
have no layouts of their own: producers must not set layouts in them.
Consumers should ignore it, and may throw an error if it is set.
| Field | Type | Label | Description |
|---|---|---|---|
| kinds | bytes | Term type of each run value, in row order, 2 bits per value, four values per byte starting from the least significant bits: 0 – the next value of iris 1 – the next value of literals 2 – the next value of bnodes 3 – the next value of triple_terms The number of run values is the total number of values in the sub-columns, and kinds must have exactly ceil(values / 4) bytes. Unused bits of the last byte must be 0. | |
| layouts | uint32 | repeated | Sequence layout of the whole column, see above. |
| iris | SparqlIriColumn | The IRIs of the column. | |
| literals | SparqlLiteralColumn | The literals of the column. | |
| bnodes | SparqlBnodeColumn | The blank nodes of the column. | |
| triple_terms | eu.ostrzyciel.jelly.core.proto.v1.RdfTripleTerm | repeated | The triple terms of the column. Not valid if the stream options declare RDF_VERSION_1_1 or RDF_VERSION_1_2_BASIC. The IRIs inside the triple terms share one RdfIri inference state, which advances through them in order – subject, predicate, object, recursively into nested triple terms. It is separate from the state of the iris sub-column, and resets at the start of every column in every frame. |
SparqlResultsFrame
SPARQL results frame – base message of a SPARQL result stream.
A frame contains a batch of rows (solutions). A frame must contain either exactly the columns established by the most recent header (the same number of columns of each type), or no columns at all. The no-columns form is only valid when row_count is 0 (or the result set has no variables), and is the recommended encoding for a frame with no rows. A column whose cells are all unbound in a frame is encoded as an empty message. Columns must decode to at most row_count cells each (shorter columns are padded with unbound cells – see the layout encoding).
Frames are self-contained except for the lookup tables and the header: a frame can be decoded using only the lookup table state left by the preceding frames and the most recently transmitted header.
| Field | Type | Label | Description |
|---|---|---|---|
| options | SparqlResultsOptions | Stream options. Must be set in the first frame of the stream. May be set again in a later frame. Doing so empties the lookup tables (identifier numbering restarts at 1). In a FLAT stream, it also makes the header cease to be in effect, so the same frame must restate it, with the same variables as the first frame. Blank node labels are not reset. This is intended only for concatenating result streams of the same query. In a PUNCTUATED stream, the options may be set again only in the first frame of a result set. | |
| variables | SparqlVariable | repeated | Result set header: the variables of the result set, in projection (SELECT clause) order, each mapped to one column. Must be set in the first frame of every result set with a solution sequence. A later frame of the same result set may restate the header to change the column layout (e.g., to move a variable from a monomorphic column to a polymorphic one). A restated header must list exactly the same variables in the same order – only the column assignments (and thus the number of columns of each type) may change. It takes effect for the frame it appears in and for all subsequent frames, until restated again. An empty variables list in the first frame of a result set, or in a frame that contains the options, declares a zero-variable result set (row_count then conveys the number of empty solutions). |
| row_count | uint32 | Number of rows (solutions) in this frame (required). Must not be greater than 2^27 - 1, the largest number of cells the layout encoding can address. | |
| names | eu.ostrzyciel.jelly.core.proto.v1.RdfLookupEntryPacked | repeated | Entries in the name lookup table. All lookup entries of a frame are applied, in order, before any column of the frame is decoded. Consequently, every lookup id referenced by the frame's columns must still hold the intended value after all entries are applied: the working set of a single frame must fit in the lookup tables. |
| prefixes | eu.ostrzyciel.jelly.core.proto.v1.RdfLookupEntryPacked | repeated | Entries in the prefix lookup table. See names for ordering rules. Note: the prefixes in the lookup table can be arbitrary strings, and are NOT meant to be user-facing. They are only used for IRI compression. To transmit user-facing namespace declarations for cosmetic purposes, use RdfNamespaceDeclaration. |
| datatypes | eu.ostrzyciel.jelly.core.proto.v1.RdfLookupEntryPacked | repeated | Entries in the datatype lookup table. See names for ordering rules. |
| iri_columns | SparqlIriColumn | repeated | IRI columns. |
| bnode_columns | SparqlBnodeColumn | repeated | Blank node columns. |
| literal_columns | SparqlLiteralColumn | repeated | Literal columns. |
| poly_columns | SparqlPolyColumn | repeated | Polymorphic columns. |
| ask_result | SparqlAskResult | Boolean (ASK) result. If set, the result set is a boolean result instead of a solution sequence. It may be set only in the first frame of a result set, which must include no variables, no columns, and row_count = 0. A boolean result is always the only frame of its result set. | |
| trailer | SparqlResultsTrailer | End-of-result-set marker. See SparqlResultsTrailer. | |
| metadata | SparqlResultsFrame.MetadataEntry | repeated | Arbitrary metadata The keys are UTF-8 encoded strings, the values are byte arrays. The metadata does not affect the result data in any way, treat it as comments in a text file. Well-known keys (their values must be valid UTF-8): link – zero or more IRIs separated by LF (U+000A), describing the result set as a whole (not the frame). Corresponds to head.link in the SPARQL Query Results JSON format. All other keys may be used by implementations in any way they see fit, and their values are arbitrary bytes. |
SparqlResultsFrame.MetadataEntry
| Field | Type | Label | Description |
|---|---|---|---|
| key | string | ||
| value | bytes |
SparqlResultsOptions
Stream options for SPARQL result streams.
| Field | Type | Label | Description |
|---|---|---|---|
| stream_name | string | Name of the stream (completely optional). This may be used for, e.g., topic names in a pub/sub system. | |
| stream_type | SparqlStreamType | Type of the stream: one result set, or a sequence of result sets. Optional. Defaults to SPARQL_STREAM_TYPE_FLAT. Must be the same in every options message of the stream. | |
| rdf_version | eu.ostrzyciel.jelly.core.proto.v1.RdfVersion | Version of RDF whose terms may occur in the stream. RDF_VERSION_1_1 – no triple terms, no base directions RDF_VERSION_1_2_BASIC – base directions, no triple terms RDF_VERSION_1_2 – base directions and triple terms Unspecified (the default) means that no version is announced: the stream may contain any RDF 1.2 term. Values not listed here are invalid. | |
| max_name_table_size | uint32 | Maximum size of the name lookup table (required, must be >= 128) | |
| max_prefix_table_size | uint32 | Maximum size of the prefix lookup table (required if the prefix lookup is used) | |
| max_datatype_table_size | uint32 | Maximum size of the datatype lookup table (required if datatype literals are used) | |
| version | uint32 | Protocol version (required) For this proposal, the value must be 1. For custom extensions, the value must be 10000 or higher. |
SparqlResultsTrailer
End-of-result-set marker, saying whether the result set is complete.
Producers must write a trailer in the last frame of every result set, unless they cannot write anything more at all (for example, because the process died).
In a FLAT stream, the trailer ends the stream: a frame containing a trailer must not be followed by any frame that does not include the stream options. In a PUNCTUATED stream, the frame after a trailer starts a new result set.
| Field | Type | Label | Description |
|---|---|---|---|
| error | string | Empty (the default) means the result set is complete. A non-empty value is a human-readable explanation of why the producer could not complete the result set (e.g., query failure mid-evaluation). |
SparqlVariable
Header entry mapping one result variable to one column.
| Field | Type | Label | Description |
|---|---|---|---|
| name | string | Name of the variable, without the leading "?" or "$". Must not be empty. | |
| column_index | uint32 | 0-based index of the column that holds this variable's values. The index points into the virtual concatenation of all column lists of a frame, in field number order: iri_columns first, then bnode_columns, literal_columns, and finally poly_columns. For example, if a frame has 2 IRI columns, 1 blank node column, and 2 literal columns, the column indices are as follows: iri_columns[0] |
SparqlStreamType
Type of a SPARQL result stream.
| Name | Number | Description |
|---|---|---|
| SPARQL_STREAM_TYPE_FLAT | 0 | The entire stream is a single result set. This is the default. buf:lint:ignore ENUM_ZERO_VALUE_SUFFIX |
| SPARQL_STREAM_TYPE_PUNCTUATED | 1 | The stream is a sequence of result sets, each ended by a frame with a trailer. A result set may span multiple frames, and each frame belongs to exactly one result set. The result sets are independent of each other (they may have different variables, and mix solution sequences with boolean results), but the lookup tables are kept from one to the next. Blank node labels are scoped to one result set. |