Querying

Carbon LDP™ resources can be queried using SPARQL, a W3C standard query language.

SPARQL has some similarities to SQL, the Structured Query Language for relational databases, but there are also fundamental differences. The main difference with SPARQL is that, instead of filtering results to get a desired outcome (like in SQL), you apply patterns that are tested over the data to retrieve results. These patterns are given along with query form to define the shape of the results.

There are four different query forms:

  • SELECT
    • Returns the matched data in a table-like structure
  • ASK
    • Returns true or false indicating whether data matched the pattern(s)
  • CONSTRUCT
    • Returns the matched data in a table-like structure
  • DESCRIBE
    • Returns the matched data in a table-like structure

pattern is defined by using three elements:

  1. Resource: any document, fragment or named fragment referenced by a URI
  2. Property: the name or URI of a property of the resource
  3. Value: the value of the property

For example, if we wanted to match a document that represented a project, which has the property namewith the value "Project X", we could use the pattern:

  1. Resourceprojects/project-01/ (the project’s ID/URI)
  2. Propertyname
  3. Value"Project X"

This example pattern fully defines all of its elements. Each pattern element has the exact value we’re trying to match. But querying involves retrieving more data than we already have, so each pattern element can also be a variable.

A variable acts like a wildcard, matching any values the pattern element can have. But unlike wildcards, a variable stores any value it matches (you can think of them kind of like the columns requested on SQL queries).

E.g: To query the name of a project you would only need the project’s URI (resource) and the name (property). The value would be represented by a variable in which you will obtain the data you queried for

SPARQL Query Builder

The SDK integrates our own query builder called SPARQLER (SPARQL query buildER) which offers a fluent interface to help you construct queries and prevent errors by malformed patterns.

Currently, we only support SELECT queries with SPARQLER.
We intend to extend the builder to cover more features in a subsequent release.

To create a query you must call the method sparql( documentURI:string ) of the documents service along with the document URI to query against.

If you already have a PersistedDocument you can also call its sparql() method, to query directly on it.

let appContext;
// ... get context
appContext.documents.sparql( "resource-end-point/" )
    // ... query construction
    ;


let persistedDocument;
// ... get the persistedDocument
persistedDocument.sparql()
    // ... query construction
    ;
import * as App from "carbonldp/App";
import * as PersistedDocument from "carbonldp/PersistedDocument";

let appContext:App.Context;
// ... get context
appContext.documents.sparql( "resource-end-point/" )
    // ... query construction
    ;


let persistedDocument:PersistedDocument.Class;
// ... get the persistedDocument
persistedDocument.sparql()
    // ... query construction
    ;
var appContext;
// ... get context
appContext.documents.sparql( "resource-end-point/" )
    // ... query construction
    ;


var persistedDocument;
// ... get the persistedDocument
persistedDocument.sparql()
    // ... query construction
    ;

SELECT Query

General structure

SPARQL SELECT queries have the following structure and order:

  1. Select what data to include in the response:
    • .select( ... variables ) or .selectAll()
  2. Specify the patterns to match:
    • .where( ... patterns )
  3. Add optional solution modifiers:
    • .groupBy( ... )
    • .having( ... )
    • .orderBy( ... )
    • .limit( ... )
    • .offset( ... )
  4. And finally execute the query:
    • .execute() or .executeRaw()

Data Selection

We can specify which variables to be included by using one of these methods:

  • .select( ...variables:string[] ). Specify which variables used in the pattern(s) will be returned with the query result
  • .selectAll(). Indicate that all variables used in the pattern(s) will be included in the result
  • .selectDistinct( ...variables:string[] ). Set a list of variables to be retrieved by the query ensuring no repetitions in the set of solutions.
  • .selectAllDistinct(). Set that the query must return all the solutions for the variables used in the pattern(s), ensuring there is not duplicated solutions.
  • .selectReduced( ...variables:string[] ). Set a list of variables to be retrieved by the query permitting eliminations of non-distinct solutions, but not ensuring a set of unique ones.
  • .selectAllReduced(). Set that the query must return all the solutions for the variables used in the pattern(s), permitting eliminations of non-distinct solutions, but not ensuring a set of unique ones.

Optionally, you can select a default document to be used in the search for the query solutions using:

  • .from( iri:string ). Set a default document or documents as the dataset where to look for the query solutions.
  • .fromNamed( iri:string ). Set a named document to be included as the Dataset where to look for the query solutions.

If several from() methods are used, the query is executed in the merge of all the documents specified. The documents specified by the fromNamed() method are only queried with the instructions inside a graph pattern.

In the case of the pattern to match, it’s a little different since you need to provide a function where you can construct the pattern:

  • .where( patternFunction:( builder:PatternBuilder ) => GraphPattern ). A single pattern to match
  • .where( patternFunction:( builder:PatternBuilder ) => GraphPattern[] ). Multiple patterns to match

As you can see, the patternFunction receives a SPARQL/PatternBuilder object which contains helper properties and functions to construct the patterns you need.

Example

Assuming we had the following object stored:

// Representation of the stored object
{
    // Document URI
    "@id": "http://localhost:8083/apps/my-app/projects/project-01/",

    // Properties
    "name": "Project X",
    "startDate": "2017/02/19"

    // ...
}

The following query would retrieve the values of the name and startDate property:

let appContext;
// ... get context

appContext.documents.sparql( "projects/project-01/" )
    .select( "projectName", "projectStart" )
    .where( _ => {
        return _.resource( "projects/project-01/" )
            .has( "name", _.var( "projectName" ) )
            .and( "startDate", _.var( "projectStart" ) );
    } )
    ;
import * as App from "carbonldp/App";
import { PatternBuilder } from "sparqler/PatternBuilder";

let appContext:App.Context;
// ... get context

appContext.documents.sparql( "projects/project-01/" )
    .select( "projectName", "projectStart" )
    .where( ( _:PatternBuilder ) => {
        return _.resource( "projects/project-01/" )
            .has( "name", _.var( "projectName" ) )
            .and( "startDate", _.var( "projectStart" ) );
    } )
    ;
var appContext;
// ... get context

appContext.documents.sparql( "projects/project-01/" )
    .select( "projectName", "projectStart" )
    .where( function( _ ) {
        return _.resource( "projects/project-01/" )
            .has( "name", _.var( "projectName" ) )
            .and( "startDate", _.var( "projectStart" ) );
    } )
    ;

The query can be translated to:

  • Search for a resource that has the id projects/project-01/
  • This resource must have a property name with any value(s)
    • Store those values in the projectName variable
  • The resource must also have the property startDate with any value(s)
    • Store those values in the projectStart variable
  • Return me the values stored in the variables projectName and projectStart

In this example we are using the var( variableName ) function of the helper object _ to declare two variables:

  • projectName
  • projectStart

These variables must appear in the pattern to match so they can be assigned values. In the .where() method, we use the PatternBuilder to first indicate we are targeting a resource with the URI: projects/project-01/, and as the URI is relative, it will be automatically resolved to http://localhost:8083/apps/my-app/projects/project-01/ (assuming the platform’s host is http://localhost:8083/ and the app being used is apps/my-app/). From this resource we call the has() method, to indicate that the resource must have a property called name, with value(s) bound to the variable projectName. Next we call the and() method, stating that it also needs to have a property startDate, with value(s) bound to the variable projectStart.

Example

To retrieve the name and start date from all available projects, we need to consider the following:

  • The end-point of the query must be the container of the projects: projects/
  • The children of the container are under the property: http://www.w3.org/ns/ldp#contains
  • We need to bind every child document (project) and ask for its name and start date, as in the previous example
let appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( _ => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    ;
import * as App from "carbonldp/App";
import { PatternBuilder } from "sparqler/PatternBuilder";

let appContext:App.Context;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( ( _:PatternBuilder ) => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    ;
var appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( function( _ ) {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    ;
As we can see, the major difference is that we return of an array of patterns. The first pattern matches the child documents from the projects/ container and binds them to the everyProject variable. With this variable we can then ask for the name and start date of every corresponding project.

Solution modifiers

This methods are optional and they let you modify the solutions returned:

  • .groupBy( rawCondition:string ). Group the data in order to calculate aggregated values for a solution
  • .having( rawCondition:string ). Filter grouped solution sets
  • .orderBy( rawCondition:string ). Establish the order of the a sequence of solutions
  • .limit( limit:string ). Restrict the number of solutions returned
  • .offset( offset:string ). Control where the solutions returned start from the overall set of them

Example

Considering the same case of retrieving the name and start date of every project, but with the solutions modifiers we’ll retrieve the last 10 projects that have been started.

let appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( _ => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    ;
import * as App from "carbonldp/App";
import { PatternBuilder } from "sparqler/PatternBuilder";

let appContext:App.Context;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( ( _:PatternBuilder ) => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    ;
var appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( function( _ ) {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    ;
We use the .orderBy() method to specify a descending order for the results, based on the project start date, and we use the .limit() method to limit the returned solutions to 10. Notice that it is not required to use a question mark with the variables declared with the _.var() helper. However, the solution modifiers like .orderBy() use RAW strings, so we have to use a question mark to specify the variable (e.g. ?projectStart.)

Query execution

Until now we’ve only been building the query and nothing more, but the important thing is to execute it and use the solutions returned.

For a SELECT query we have two methods:

Example

Following the previous examples, we’ll execute the query we have been building and then return an array of projects with the data obtained.

let appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( _ => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    .execute()
    .then( ( [ result, response ] ) => {
        return result
            .bindings
            .map( binding => ( {
                name: binding[ "projectName" ],
                startDate: binding[ "projectStart" ],
            } )
            ;
    } )
    ;
import * as App from "carbonldp/App";
import * as SPARQL from "carbonldp/SPARQL";
import * as HTTP from "carbonldp/HTTP";
import { PatternBuilder } from "sparqler/PatternBuilder";

let appContext:App.Context;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( ( _:PatternBuilder ) => {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    .execute()
    .then( ( [ result, response ]:[ SPARQL.SELECTResults.Class, HTTP.Response.Class ] ) => {
        return result
            .bindings
            .map( binding => ( {
                name: binding[ "projectName" ],
                startDate: binding[ "projectStart" ],
            } )
            ;
    } )
    ;
var appContext;
// ... get context

appContext.documents.sparql( "projects/" )
    .prefix( "ldp", "http://www.w3.org/ns/ldp#" )
    .select( "projectName", "projectStart" )
    .where( function( _ ) {
        return [
            _.resource( "projects/" )
                .has( "ldp:contains", _.var( "everyProject" ) ),
            _.var( "everyProject" )
                .has( "name", _.var( "projectName" ) )
                .and( "startDate", _.var( "projectStart" ) )
        ];
    } )
    .orderBy( "DESC( ?projectStart )" )
    .limit( 10 )
    .execute()
    .then( function( [ result, response ] ) {
        return result
            .bindings
            .map( function( binding ) {
                return {
                    name: binding[ "projectName" ],
                    startDate: binding[ "projectStart" ],
                };
            } )
            ;
    } )
    ;
The result object contains a bindings property with an array containing the solutions of the query. Every element in this array is an object that has the variable names as keys and each variable’s bound value.

Query configuration

With the SPARQLER integration, every query has access to the following default information:

  • Prefixes. Every prefix in the global schema
  • Vocabulary. The application vocabulary to resolve property names, as in the Object Schema
  • Base. The URI of the current context to resolve relative resources. In the case of an App.Context it is the app URI.

To configure the builder to your own preferences you can use the following methods:

  • vocab( uri:string ): Set or replace the existing vocabulary
  • base( uri:string ): Replace the base URI
  • prefix( name:string, uri:string ): Add or replace existing prefixes in the SPARQLER

Example

let appContext;
// ... get context

appContext.documents.sparql( "resource-end-point/" )
    // Sets a well defined vocabulary
    .vocab( "https://schema.org/" )

    // Sets the base to the document end point
    .base( "resource-end-point/" )

    // Adds new prefixes that may be used in the document
    .prefix( "bib": "https://bib.schema.org/" )
    .prefix( "auto": "https://auto.schema.org/" )
    ;
import * as App from "carbonldp/App";

let appContext:App.Context;
// ... get context

appContext.documents.sparql( "resource-end-point/" )
    // Sets a well defined vocabulary
    .vocab( "https://schema.org/" )

    // Sets the base to the document end point
    .base( "resource-end-point/" )

    // Adds new prefixes that may be used in the document
    .prefix( "bib": "https://bib.schema.org/" )
    .prefix( "auto": "https://auto.schema.org/" )
    ;
var appContext;
// ... get context

appContext.documents.sparql( "resource-end-point/" )
    // Sets a well defined vocabulary
    .vocab( "https://schema.org/" )

    // Sets the base to the document end point
    .base( "resource-end-point/" )

    // Adds new prefixes that may be used in the document
    .prefix( "bib": "https://bib.schema.org/" )
    .prefix( "auto": "https://auto.schema.org/" )
    ;

As an alternative to the way of building queries with the SPARQL Query Builder (as we’ve shown so far), the SDK also supports the use of standard SPARQL queries passed as strings. You might prefer this approach when if you are comfortable writing standard SPARQL queries or in order to leverage features that are not yet available in the SPARQL Query Builder.

Standard SPARQL queries can be written and tested using the SPARQL Client in the Carbon LDP Workbench. They can then be copied and pasted directly into JavaScript strings as-is. A notable difference is that relative property names cannot be used as they can in the SPARQL Query Builder, so standard SPARQL queries might be more verbose with fully qualified URIs in some cases.

The methods to execute a standard SPARQL query (given as a string), are also called from the Documentsservice.

SELECT Queries

  • executeSELECTQuery( documentURI:string, selectQuery: string )
  • executeRawSELECTQuery( documentURI:string, selectQuery: string )

These methods are the equivalent to the .execute() and .executeRaw() in a SELECT query with the Query Builder.

let appContext;
// ... get context

appContext.documents.executeSELECTQuery( "projects/", `
    BASE <http://localhost:8083/apps/my-app/>
    PREFIX ldp: <http://www.w3.org/ns/ldp#>
    SELECT ?projectName ?projectStart
    WHERE {
        <projects/> ldp:contains ?everyProject .
        ?everyProject <vocabulary/#name> ?projectName ;
                      <vocabulary/#startDate> ?projectStart
    }
    ORDER BY DESC( ?projectStart )
    LIMIT 10
` )
    .then( ( [ result, response ] ) => {
        return result
            .bindings
            .map( binding => ( {
                name: binding[ "projectName" ],
                startDate: binding[ "projectStart" ],
            } )
            ;
    } )
    ;
import * as App from "carbonldp/App";
import * as SPARQL from "carbonldp/SPARQL";
import * as HTTP from "carbonldp/HTTP";

let appContext:App.Context;
// ... get context

appContext.documents.executeSELECTQuery( "projects/", `
    BASE <http://localhost:8083/apps/my-app/>
    PREFIX ldp: <http://www.w3.org/ns/ldp#>
    SELECT ?projectName ?projectStart
    WHERE {
        <projects/> ldp:contains ?everyProject .
        ?everyProject <vocabulary/#name> ?projectName ;
                      <vocabulary/#startDate> ?projectStart
    }
    ORDER BY DESC( ?projectStart )
    LIMIT 10
` )
    .then( ( [ result, response ]:[ SPARQL.SELECTResults.Class, HTTP.Response.Class ] ) => {
        return result
            .bindings
            .map( binding => ( {
                name: binding[ "projectName" ],
                startDate: binding[ "projectStart" ],
            } )
            ;
    } )
    ;
var appContext;
// ... get context

appContext.documents.executeSELECTQuery( "projects/", "" +
    "BASE <http://localhost:8083/apps/my-app/>" +
    "PREFIX ldp: <http://www.w3.org/ns/ldp#>" +
    "SELECT ?projectName ?projectStart" +
    "WHERE {" +
    "   <projects/> ldp:contains ?everyProject ." +
    "   ?everyProject <vocabulary/#name> ?projectName ;" +
    "                 <vocabulary/#startDate> ?projectStart" +
    "}" +
    "ORDER BY DESC( ?projectStart )" +
    "LIMIT 10"
)
    .then( function( [ result, response ] ) {
        return result
            .bindings
            .map( function( binding ) {
                return {
                    name: binding[ "projectName" ],
                    startDate: binding[ "projectStart" ],
                };
            } )
            ;
    } )
    ;

ASK Queries

A standard SPARQL ASK query can be given as string and executed with one of the following:

  • executeASKQuery( documentURI:string, askQuery: string )
  • executeRawASKQuery( documentURI:string, askQuery: string )

The fist option returns a simple response with only the resulting boolean of the ASK query (e.g. true or false). The second one will return a JSON object as described in the API ReferenceCarbon.SPARQL.RawResults.Class

let appContext;
// ... get context

appContext.documents.executeASKQuery( "projects/project-01/", `
    BASE        <http://localhost:8083/apps/my-app/>
    ASK {
        <projects/project-01/> <vocabulary/#name> "Project X" ;
                               <vocabulary/#startDate> "2017/02/19"
    }
` )
    .then( ( [ result, response ] ) => {
        // result will be `true`
    } )
    ;
import * as App from "carbonldp/App";
import * as HTTP from "carbonldp/HTTP";

let appContext:App.Context;
// ... get context

appContext.documents.executeASKQuery( "projects/project-01/", `
    BASE        <http://localhost:8083/apps/my-app/>
    ASK {
        <projects/project-01/> <vocabulary/#name> "Project X" ;
                               <vocabulary/#startDate> "2017/02/19"
    }
` )
    .then( ( [ result, response ]:[ boolean, HTTP.Response.Class ] ) => {
        // result will be `true`
    } )
    ;
var appContext;
// ... get context

appContext.documents.executeASKQuery( "projects/project-01/", "" +
    "BASE        <http://localhost:8083/apps/my-app/>" +
    "ASK {" +
    "    <projects/project-01/> <vocabulary/#name> \"Project X\" ;" +
    "                           <vocabulary/#startDate> \"2017/02/19\"" +
    "}" +
)
    .then( function( [ result, response ] ) {
        // result will be `true`
    } )
    ;

CONSTRUCT Queries

When using the CONSTRUCT query, the server will respond with a raw string in the JSON-LD format, so you will have to process and parse it to your needs.

let appContext;
// ... get context

appContext.documents.executeRawCONSTRUCTQuery( "projects/project-01/", `
    BASE        <http://localhost:8083/apps/my-app/>
    PREFIX schema:  <https://schema.org/>
    CONSTRUCT   {
        <projects/project-01/> schema:name ?projectName ;
                               schema:startDate ?projectStart
    }
    WHERE {
        <projects/project-01/> <vocabulary/#name> ?projectName ;
                               <vocabulary/#startDate> ?projectStart
    }
` )
    .then( ( [ result, response ] ) => {
        // ... process the result JSON-LD string
    } )
    ;
import * as App from "carbonldp/App";
import * as HTTP from "carbonldp/HTTP";

let appContext:App.Context;
// ... get context

appContext.documents.executeRawCONSTRUCTQuery( "projects/project-01/", `
    BASE        <http://localhost:8083/apps/my-app/>
    PREFIX schema:  <https://schema.org/>
    CONSTRUCT   {
        <projects/project-01/> schema:name ?projectName ;
                               schema:startDate ?projectStart
    }
    WHERE {
        <projects/project-01/> <vocabulary/#name> ?projectName ;
                               <vocabulary/#startDate> ?projectStart
    }
` )
    .then( ( [ result, response ]:[ string, HTTP.Response.Class ] ) => {
        // ... process the result JSON-LD string
    } )
    ;
var appContext;
// ... get context

appContext.documents.executeRawCONSTRUCTQuery( "projects/project-01/", "" +
    "BASE        <http://localhost:8083/apps/my-app/>" +
    "PREFIX schema:  <https://schema.org/>" +
    "CONSTRUCT   {" +
    "	<projects/project-01/> schema:name ?projectName ;" +
    "                          schema:startDate ?projectStart" +
    "}" +
    "WHERE {" +
    "    <projects/project-01/> <vocabulary/#name> ?projectName ;" +
    "                           <vocabulary/#startDate> ?projectStart" +
    "}"
)
    .then( function( [ result, response ] ) {
        // ... process the result JSON-LD string
    } )
    ;
In this example we create an Document with only the name and start date of the project, but the difference is that we rename the properties to a well defined the vocabulary: https://schema.org/:

// Representation of the string returned
{
    "id": "http://localhost:8083/apps/my-app/projects/project-01/",

    // Properties
    "https://schema.org/name": "Project X",
    "https://schema.org/startDate": "2017/02/19"
}

DESCRIBE Queries

When using the DESCRIBE query, the server will respond with a raw string in the JSON-LD format, so you will have to process and parse it to your needs.

let appContext;
// ... get context

appContext.documents.executeRawDESCRIBEQuery( "projects/project-01/", `
    BASE     <http://localhost:8083/apps/my-app/>
    DESCRIBE <projects/project-01/>
` )
    .then( ( [ result, response ] ) => {
        // ... process the result JSON-LD string
    } )
    ;
import * as App from "carbonldp/App";
import * as HTTP from "carbonldp/HTTP";

let appContext:App.Context;
// ... get context

appContext.documents.executeRawDESCRIBEQuery( "projects/project-01/", `
    BASE     
    DESCRIBE 
` )
    .then( ( [ result, response ]:[ string, HTTP.Response.Class ] ) => {
        // ... process the result JSON-LD string
    } )
    ;
var appContext;
// ... get context

appContext.documents.executeRawDESCRIBEQuery( "projects/project-01/", "" +
    "BASE     <http://localhost:8083/apps/my-app/>" +
    "DESCRIBE <projects/project-01/>"
)
    .then( function( [ result, response ] ) {
        // ... process the result JSON-LD string
    } )
    ;

UPDATE

A SPARQL UPDATE doesn’t return any results data, thus it’s not exactly a query and there’s only one method in the SDK for executing the UPDATE.

let appContext;
// ... get context

appContext.documents.executeUPDATE( "projects/project-01/", `
    BASE     <http://localhost:8083/apps/my-app/>
    DELETE {
        <projects/project-01/> <vocabulary/#name> "Project X"
    }
    INSERT {
        <projects/project-01/> <vocabulary/#name> "My new awesome name"
    }
    WHERE {
        <projects/project-01/> <vocabulary/#name> "Project X"
    }
` )
    .then( response  => {
        // ... Update finished
    } )
    ;
import * as App from "carbonldp/App";
import * as HTTP from "carbonldp/HTTP";

let appContext:App.Context;
// ... get context

appContext.documents.executeUPDATE( "projects/project-01/", `
    BASE     <http://localhost:8083/apps/my-app/>
    DELETE {
        <projects/project-01/> <vocabulary/#name> "Project X"
    }
    INSERT {
        <projects/project-01/> <vocabulary/#name> "My new awesome name"
    }
    WHERE {
        <projects/project-01/> <vocabulary/#name> "Project X"
    }
` )
    .then( ( response:HTTP.Response.Class ) => {
        // ... Update finished
    } )
    ;
var appContext;
// ... get context

appContext.documents.executeUPDATE( "projects/project-01/", "" +
    "BASE     <http://localhost:8083/apps/my-app/>" +
    "DELETE {" +
    "	<projects/project-01/> <vocabulary/#name> \"Project X\"" +
    "}" +
    "INSERT {" +
    "	<projects/project-01/> <vocabulary/#name> \"My new awesome name\"" +
    "}" +
    "WHERE {" +
    "	<projects/project-01/> <vocabulary/#name> \"Project X\"" +
    "}"
)
    .then( function( response ) {
        // ... Update finished
    } )
    ;

Conclusion

In this guide, we’ve demonstrated two alternative ways to query with SPARQL using the SDK:

  • Using the SPARQL Query Builder (a.k.a. SPARQLER) – a fluent chain of methods assembled in a dot-notation to build up a query.
  • Using SPARQL Services – methods that accept a standard SPARQL query string passed in a parameter to the method.

We also provided an overview, with code examples, for the different query forms SELECTASKCONSTRUCTDESCRIBE, and UPDATE.

Want to know more?

Now that you understand how to query with SPARQL using the SDK, you may want to learn more about the SPARQL language. We recommend the following references:

RDF Icon

SPARQL 1.1 Overview

Introduction from the W3C.

RDF Icon

SPARQL 1.1 Query Language

Specification from the W3C.

RDF Icon

Learning SPARQL

Book about Querying and Updating with SPARQL 1.1, by Bob DuCharme, O’REILLY®.