Skip to content

Low-level usage

Warning

This page describes a low-level API that is a bit of a hassle to use directly. It's recommended to use the higher-level abstractions provided by the jelly-stream module, or the integrations with Apache Jena's RIOT or RDF4J's Rio libraries. If you really want to use this, it is highly recommended that you first get a basic understanding of how Jelly works under the hood and take a look at the code in the jelly-stream module to see how it's done there.

Note

The following guide uses the Apache Jena library as an example. The exact same thing can be done with RDF4J or any other RDF library that has a Jelly integration.

Deserialization

To parse a serialized stream frame into triples/quads:

  1. Call eu.ostrzyciel.jelly.core.proto.v1.RdfStreamFrame.parseFrom if it's a non-delimited frame (like you would see, e.g., in a Kafka or gRPC stream), or parseDelimitedFrom if it's a delimited stream (like you would see in a file or a socket).
  2. Obtain a decoder that turns RdfStreamFrames into triples/quads: eu.ostrzyciel.jelly.convert.jena.JenaConverterFactory has different methods for different physical stream types:
    • anyStatementDecoder for any physical stream type, outputs Triple or Quad
    • triplesDecoder for TRIPLES streams, outputs Triple
    • quadsDecoder for QUADS streams, outputs Quad
    • graphsDecoder for GRAPHS streams, outputs (Node, Iterable[Triple])
    • graphsAsQuadsDecoder for GRAPHS streams, outputs Quad
  3. For each row in the frame, call the decoder's ingestRow method to get the output iteratively.

Serialization

To serialize triples/quads into a stream frame:

  1. If you want to serialize an RDF graph/dataset, transform them first into triples/quads in an iterable form. Use the asTriples/asQuads/asGraphs extension methods provided by the eu.ostrzyciel.jelly.convert.jena.JenaIterableAdapter object.
  2. Obtain an encoder that turns triples/quads into RdfStreamRows (the rows of a stream frame): use the eu.ostrzyciel.jelly.convert.jena.JenaConverterFactory.encoder method to get an instance of eu.ostrzyciel.jelly.convert.jena.JenaProtoEncoder .
  3. Call the encoder's methods to add quads, triples, or named graphs to the stream frame.
    • Note that YOU are responsible for sticking to a specific physical stream type. For example, you should not mix triples with quads. It is highly recommended that you first read on the available stream types in Jelly.
    • You are also responsible for setting the appropriate stream options with proper stream types. See the guide on Jelly options presets for more information.
  4. The encoder will be returning batches or rows. You are responsible for grouping those rows logically into RdfStreamFrames. What you do here depends highly on the logical stream type you are working with.

See also