Query operation result 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 internally by Comunica actors.

    Query operation output type

    All relevant types and interfaces are exposed by the Comunica types package.

    IQueryOperationResult is a TypeScript union type over the following interfaces:

    Bindings output

    An output of type IQueryOperationResultBindings looks as follows:

    interface IQueryOperationResultBindings {
  type: 'bindings';
  context: ActionContext;
  metadata: () => Promise<IMetadata>;
  bindingsStream: BindingsStream;
}

    The most important field in here is bindingsStream, which is of type BindingsStream. This is a stream containing bindings. Learn more about the usage of these bindings objects in the bindings guide.

    Quads output

    An output of type IQueryOperationResultQuads looks as follows:

    interface IQueryOperationResultQuads {
  type: 'quads';
  context: ActionContext;
  metadata: () => Promise<IMetadata>;
  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 IQueryOperationResultBoolean looks as follows:

    interface IQueryOperationResultBoolean {
  type: 'bindings';
  context: ActionContext;
  execute: () => Promise<boolean>;
}

    The most important method in here is execute, which returns a promise resolving to a boolean.

    Void output

    An output of type IQueryOperationResultVoid looks as follows:

    interface IQueryOperationResultVoid {
  type: 'void';
  context: ActionContext;
  execute: () => Promise<void>;
}

    The most important method in here is execute, which returns a void promise.

    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: Returns IQueryOperationResultBindings.
    • ActorQueryOperation.getSafeQuads: Returns IQueryOperationResultQuads.
    • ActorQueryOperation.getSafeBoolean: Returns IQueryOperationResultBoolean.
    • ActorQueryOperation.getSafeVoid: Returns IQueryOperationResultVoid.

    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: IQueryOperationResultBindings = ActorQueryOperation.getSafeBindings(
  await this.mediatorQueryOperation.mediate({ operation: pattern.right, context }),
);
const rightResult: IQueryOperationResultBindings = ActorQueryOperation.getSafeBindings(
  await this.mediatorQueryOperation.mediate({ operation: pattern.left, context }),
);

leftResult.bindingsStream.filter(...);