Query output types
On this page
Comunica supports different SPARQL query types,
each of which may require different kinds of output.
For example, SELECT
queries returns a stream of bindings,
CONSTRUCT
and DESCRIBE
returns a stream of quads,
and ASK
returns a boolean.
This document gives an overview of how these different output types are represented.
Query operation output type
All relevant types and interfaces are exposed by the Query Operation bus.
IActorQueryOperationOutput
is a TypeScript union type over the following interfaces:
IActorQueryOperationOutputBindings
: Represents a stream of bindings.IActorQueryOperationOutputQuads
: Represents a stream of quads.IActorQueryOperationOutputBoolean
: Represents a boolean result.
Bindings output
An output of type IActorQueryOperationOutputBindings
looks as follows:
interface IActorQueryOperationOutputBindings {
type: 'bindings';
context?: ActionContext;
metadata?: () => Promise<{[id: string]: any}>;
bindingsStream: BindingsStream;
variables: string[];
canContainUndefs: boolean;
}
The most important field in here is bindingsStream
, which is of type BindingsStream
.
This is a stream containing Bindings
,
which are of type Map<string, RDF.Term>
where keys are variable names prefixes with ?
.
Quads output
An output of type IActorQueryOperationOutputQuads
looks as follows:
interface IActorQueryOperationOutputQuads {
type: 'bindings';
context?: ActionContext;
metadata?: () => Promise<{[id: string]: any}>;
quadStream: RDF.Stream & AsyncIterator<RDF.Quad>;
}
The most important field in here is quadStream
, which is of type RDF.Stream
containing RDF/JS quads.
Boolean output
An output of type IActorQueryOperationOutputBoolean
looks as follows:
interface IActorQueryOperationOutputQuads {
type: 'bindings';
context?: ActionContext;
booleanResult: Promise<boolean>;
}
The most important field in here is booleanResult
, which is a promise resolving to a boolean.
Casting an unknown output type
If your actor calls a query operation mediator, it will receive an output of type IActorQueryOperationOutput
.
If you want to operate on the results directly,
and if you are not certain of the output type,
you will have to check the type
field of the output,
and handle it accordingly.
If you however know beforehand what the type will be, you can safely cast the output type with the following helper functions:
ActorQueryOperation.getSafeBindings
: ReturnsIActorQueryOperationOutputBindings
.ActorQueryOperation.getSafeQuads
: ReturnsIActorQueryOperationOutputQuads
.ActorQueryOperation.getSafeBoolean
: ReturnsIActorQueryOperationOutputBoolean
.
For example, the minus query operation actor (@comunica/actor-query-operation-minus
)
can only operate on bindings streams.
As such, it can safely cast outputs as follows:
const leftResult: IActorQueryOperationOutputBindings = ActorQueryOperation.getSafeBindings(
await this.mediatorQueryOperation.mediate({ operation: pattern.right, context }),
);
const rightResult: IActorQueryOperationOutputBindings = ActorQueryOperation.getSafeBindings(
await this.mediatorQueryOperation.mediate({ operation: pattern.left, context }),
);
leftResult.bindingsStream.filter(...);