SPARQLER

SPARQL query buildER for JavaScript/TypeScript.

SPARQLER offers a fluent interface to help you construct queries and prevent errors by malformed patterns.

Installation

With npm installed, run

`shell script npm install sparqler

## Usage examples

```javascript
import { SPARQLER } from "sparqler";
// const SPARQLER = require( "sparqler" ).SPARQLER // With Node.js

let query = new SPARQLER()
    .base( "https://example.com/resource/" )
    .prefix( "ex", "https://example.com/ns#" )
    .select( _ => [
        _.var( "bar" )
    ] )
    .where( _ => [
        _.resource( "" ) 
            .has( _.resource( "ex:foo" ), _.var( "bar" ) )
            .and( _.resource( "ex:baz" ), _.literal( 10 ) ),
    ] )
    .orderBy( _ => [
        _.desc( _.var( "bar" ) )
    ] )
    .toPrettyString();
    // .toCompactString(); // Minimal query size, but difficult to read

console.log( query );

Output:

BASE <https://example.com/resource/>
PREFIX ex: <https://example.com/ns#>
SELECT ?bar
WHERE {
    <> ex:foo ?bar;
       ex:baz 10
}
ORDER BY DESC (?bar)

Every method generates a different object with the corresponding methods available in that step. This means that, if you store a query reference and modify it afterwards, printing the reference will not have the modification. However, this also means that you can generate different queries using a shared base without mutating it:

import { SPARQLER } from "sparqler";

let query1 = new SPARQLER()
    .base( "https://example.com/resource/" )
    .prefix( "ex", "https://example.com/ns#" )
    .select( _ => _.var( "bar" ) )
    .where( _ => _.resource( "" ).has( _.resource( "ex:foo" ), _.var( "bar" ) ) );

// Add an order
let query2 = query1
    .orderBy( _ => [
        _.desc( _.var( "bar" ) )
    ] );

console.log( query1.toPrettyString() );
console.log( query2.toPrettyString() );

Output:

# query1
BASE <https://example.com/resource/>
PREFIX ex: <https://example.com/ns#>
SELECT ?bar
WHERE { <> ex:foo ?bar }

# query2
BASE <https://example.com/resource/>
PREFIX ex: <https://example.com/ns#>
SELECT ?bar
WHERE { <> ex:foo ?bar }
ORDER BY DESC (?bar) # The added order

API Documentation

See https://carbonldp.github.io/sparqler/ for the API documentation.

License

Copyright (c) 2015-present, Base22 Technology Group, LLC.
All rights reserved.

This source code is licensed under the BSD-style license found in the
LICENSE file in the root directory of this source tree.

Changelog

All notable changes to this project will be documented in this file.

The format is based on Keep a Changelog and this project adheres to Semantic Versioning.

0.8.0 (2019-11-26)

Fixed

• #52 - Merging the FILTER keyword with the label of a function expression
• #53 - PatternBuilder.minus() method not returning a Pattern when Patterns are provided

Breaking Changes

• #47 - Add an _ at the beginning of internal methods.
  Affected methods are:
  
  • Pattern.getPattern() => Pattern._getPattern()
  • TrippleSubject.getSubject() => TrippleSubject._getSubject()
  • Path.getPath() => Path._getPath()
  • OrderCondition.getOrderCondition() => OrderCondition._getOrderCondition()
  • Expression.getExpression() => Expression._getExpression()
  • Projectable.getProjection() => Projectable._getProjection()

0.7.0 (2019-11-05)

Added

• #4 - Add support for SPARQL expressions
  Example:
  

    import { SPARQLER } from "sparqler";
    import { PatternBuilder } from "sparqler/patterns";
  
    new SPARQLER()
        .select( (_:PatternBuilder) => ([
            _.var("foo"),
            _.max(_.var("baz")).as( "total" ),
        ]) )
        .where( (_:PatternBuilder) => ([
            // Using the same object methods
            _.bind( _.var("bar").multiply( 0.5 ), "baz" ),
            // Using the builder methods
            _.filter( _.gte( _.var("bar"), 10 ) ),
        ]))
        .groupBy( (_:PatternBuilder) => ([ _.var("foo") ]) )
    ;

Fixed

• #45 - Not adding all the elements in a single variable values pattern

Breaking Changes

• #4 - The following methods now accept Expression objects, instead of RAW expression strings:

  • BIND
  • FILTER
  • GROUP BY
  • HAVING

  • ORDER BY

    
    Example:
    

    import { SPARQLER } from "sparqler";
    import { PatternBuilder } from "sparqler/patterns";
    
    new SPARQLER()
      .select( "foo", "baz" )
      .where( (_:PatternBuilder) => ([
          // Using the same object methods
          _.bind( _.var("bar").multiply( 0.5 ), "baz" ),
          // Using the builder methods
          _.filter( _.gte( _.var("bar"), 10 ) ),
      ]))
      .groupBy( (_:PatternBuilder) => ([ _.var("foo") ]) )
    ;

0.6.0 (2018-09-20)

Added

• #33 - Full support for property paths
  Example:
  

    ( _:PathBuilder ) => _
      .inverse( "ex:path1" ) // ^ex:path1
        .then( "ex:path2" )   // ^ex:path1 / ex:path2
        .onceOrMore()         // (^ex:path1 / ex:path2)+

0.5.0 (2018-08-22)

Added

• #27 - Add method to debug query

    sparqler
        /* ... */
        .debug( ( query, container ) => {
            // `query`:  the same query before the debug method
            // `container`: the data container of the query (the actual query tokens, IRI options, etc)
        } );

• #30 - Support ASK queries
  Example:
  

    sparqler
        .ask()
        .where( _ => [
            /* Patterns */
        ] );

Breaking Changes

• Refactor internal code (this does not affect SPARQLer interfaces):
  • Create tokens that replicate the grammatical tree
  • Refactor query creation using the new tokens models
  • Refactor patterns using the new model

0.4.0 (2018-03-23)

Added

• #21 - Add support for modifiers in the select statement
  • Add DISTINCT support over selectDistinct() and selectAllDistinct()
  • Add REDUCED support over selectReduced() and selectAllReduced()

0.3.1 (2018-01-29)

Fixed

• #19 - When adding a prefix with the same name, the last one will be preserved
• #18 - Workaround for Stardog's SPARQL query parsing with the BASE definition

0.3.0 (2017-12-29)

Added

• #13 - Support for VALUES as clause
  Example:
  

    sparqler
        .select( "book", "title" )
        .where( _ => _.var( "book" ).has( "title", _.var( "title" ) ) )
        .values( [ "book", "title" ], _ => [
            [ _.resource( "http://example.com/guides/value-clause/" ) ],
            [ "Value Clause Guide" ]
        ] );

• #10 - Support for sub-selects
  Example:
  

    // Comments of the first recommended book
    sparqler
        .select( "book", "comments" )
        .where( _ => [
            _.select( "book" )
                .where( [
                _.var( "book" ).has( "recomendation-points", _.var( "points" )  )
                ] )
                .orderBy( "DESC( ?points )" )
                .limit( 1 ),
            _.var( "book" ).has( "comment", _.var( "comments" ) )
        ] );

• #9 - Add base support for RAW property paths

Fixed

• #14 - Validate variable names

0.2.0 (2017-06-01)

Added

• #7 - Add patterns:
  • SERVICE - Full support
  • SERVICE SILENT - Full support
  • BIND - Basic support with RAW expression string
  • FILTER - Basic support with RAW expression strings

0.1.1 (2017-03-25)

Added

• #1 - Support integration with carbonldp-js-sdk

0.1.0 (2016-12-22)

• First release