Outdated version

You are browsing the docs for Nexus v1.7.x, the latest release is available here

SparqlView

This view creates a Blazegraph namespace and stores the targeted resources as RDF triples into a Blazegraph instance.

The triples created on each view are isolated from triples created on another view through the namespace.

A default view gets automatically created when the project is created but other views can be created.

Authorization notes

When modifying views, the caller must have views/write permissions on the current path of the project or the ancestor paths.

When querying views, the caller must have the views/query (or a custom permission from Delta v1.5) permission on the current path of the project or the ancestor paths.

When reading views, the caller must have resources/read permissions on the current path of the project or the ancestor paths.

Please visit Authentication & authorization section to learn more about it.

Processing pipeline

An asynchronous process gets trigger for every view. This process can be visualized as a pipeline with different stages.

The first stage is the input of the pipeline: a stream of events scoped for the project where the view was created.

The last stage takes the resource, generated through the pipeline steps, and extracts its RDF triples to store them in a Blazegraph namespace.

SparqlView pipeline

Payload

{
  "@id": "{someid}",
  "@type": "SparqlView",
  "resourceSchemas": [ "{resourceSchema}", ...],
  "resourceTypes": [ "{resourceType}", ...],
  "resourceTag": "{resourceTag}",
  "includeMetadata": {includeMetadata},
  "includeDeprecated": {includeDeprecated},
  "permission": {permission}
}

where…

  • {resourceSchema}: Iri - Selects only resources that are validated against the provided schema Iri. This field is optional.
  • {resourceType}: Iri - Selects only resources of the provided type Iri. This field is optional.
  • {resourceTag}: String - Selects the resources with the provided tag. This field is optional.
  • {includeMetadata}: Boolean - If true, the resource’s nexus metadata (_constrainedBy, _deprecated, …) will be stored in the Sparql graph. Otherwise it won’t. The default value is false.
  • {includeDeprecated}: Boolean - If true, deprecated resources are also indexed. The default value is false.
  • {permission}: String - The required permission to be able to query the view. The default value is views/query. Option available from Delta v1.5

Example

The following example creates an Sparql view that will index resources not deprecated and with tag mytag.

The resulting RDF triples will contain the resources metadata.

{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": "SparqlView",
  "includeMetadata": true,
  "includeDeprecated": false,
  "resourceTag": "mytag"
}

Create using POST

POST /v1/view/{org_label}/{project_label}
  {...}

The json payload:

  • If the @id value is found on the payload, this @id will be used.
  • If the @id value is not found on the payload, an @id will be generated as follows: base:{UUID}. The base is the prefix defined on the view’s project ({project_label}).

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/views/myorg/myproj" \
     -d \
'{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview"
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission",
}'
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/indexing-view",
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_uuid": "9c632570-cdaa-4a35-a6f9-1e95bd3a930e",
  "_deprecated": false,
  "_self": "http://localhost:8080/v1/views/org/proj/nxv:myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/nxv:myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/nxv:myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 1,
  "_updatedAt": "2021-04-18T17:10:22.748Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}

Create using PUT

This alternative endpoint to create a view is useful in case the json payload does not contain an @id but you want to specify one. The @id will be specified in the last segment of the endpoint URI.

PUT /v1/views/{org_label}/{project_label}/{view_id}
  {...}

Example

Note that if the payload contains an @id different from the {view_id}, the request will fail.

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/views/myorg/myproj/nxv:myview" \
     -d \
'{
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission",
}'
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/indexing-view",
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_uuid": "9c632570-cdaa-4a35-a6f9-1e95bd3a930e",
  "_deprecated": false,
  "_self": "http://localhost:8080/v1/views/org/proj/nxv:myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/nxv:myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/nxv:myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 1,
  "_updatedAt": "2021-04-18T17:10:22.748Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}

Update

This operation overrides the payload.

In order to ensure a client does not perform any changes to a view without having had seen the previous revision of the view, the last revision needs to be passed as a query parameter.

PUT /v1/views/{org_label}/{project_label}/{view_id}?rev={previous_rev}
  {...}

… where {previous_rev} is the last known revision number for the view.

Example

Request
sourcecurl -X PUT \
     -H "Content-Type: application/json" \
     "https://nexus.example.com/v1/views/myorg/myproj/nxv:myview?rev=1" \
     -d \
'{
  "@type": "SparqlView",
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission",
}''
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/indexing-view",
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission"
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_uuid": "9c632570-cdaa-4a35-a6f9-1e95bd3a930e",
  "_deprecated": false,
  "_self": "http://localhost:8080/v1/views/org/proj/nxv:myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/nxv:myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/nxv:myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 2,
  "_updatedAt": "2021-04-20T09:32:14.12Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}
Note

Updating a view creates a new Blazegraph namespace and deletes the existing one. The indexing process will start from the beginning.

Tag

Links a view’s revision to a specific name.

Tagging a view is considered to be an update as well.

POST /v1/views/{org_label}/{project_label}/{view_id}/tags?rev={previous_rev}
  {
    "tag": "{name}",
    "rev": {rev}
  }

… where

  • {previous_rev}: Number - the last known revision for the resolver.
  • {name}: String - label given to the view at specific revision.
  • {rev}: Number - the revision to link the provided {name}.

Example

Request
sourcecurl -X POST \
     -H "Content-Type: application/json" \
     "http://localhost:8080/v1/views/myorg/myproj/nxv:myview/tags?rev=2" \
     -d \
'{
  "tag": "mytag",
  "rev": 1
}'
Payload
source{
  "tag": "mytag",
  "rev": 1
}
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_uuid": "9c632570-cdaa-4a35-a6f9-1e95bd3a930e",
  "_deprecated": false,
  "_self": "http://localhost:8080/v1/views/org/proj/myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 3,
  "_updatedAt": "2021-04-22T13:03:50.978Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}

Deprecate

Locks the view, so no further operations can be performed. It also stops the indexing process and delete the associated namespace.

Deprecating a view is considered to be an update as well.

DELETE /v1/views/{org_label}/{project_label}/{view_id}?rev={previous_rev}

… where {previous_rev} is the last known revision number for the view.

Example

Request
sourcecurl -X DELETE \
     "https://nexus.example.com/v1/views/myorg/myproj/nxv:myview?rev=3"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql-metadata.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type": [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_uuid": "9c632570-cdaa-4a35-a6f9-1e95bd3a930e",
  "_deprecated": true,
  "_self": "http://localhost:8080/v1/views/org/proj/nxv:myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/nxv:myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/nxv:myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 5,
  "_updatedAt": "2021-04-24T17:28:01.321Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}

Fetch

GET /v1/views/{org_label}/{project_label}/{view_id}?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional. {rev} and {tag} fields cannot be simultaneously present.

Example

Request
sourcecurl "http://localhost:8080/v1/views/myorg/myproj/nxv:myview"
Response
source{
  "@context": [
    "https://bluebrain.github.io/nexus/contexts/sparql.json",
    "https://bluebrain.github.io/nexus/contexts/metadata.json"
  ],
  "@id": "https://bluebrain.github.io/nexus/vocabulary/myview",
  "@type" : [
    "SparqlView",
    "View"
  ],
  "_constrainedBy": "https://bluebrain.github.io/nexus/schemas/views.json",
  "_createdAt": "2021-04-18T17:10:22.748Z",
  "_createdBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "_deprecated": false,
  "_self": "http://localhost:8080/v1/views/org/proj/nxv:myview",
  "_incoming": "http://localhost:8080/v1/views/org/proj/nxv:myview/incoming",
  "_outgoing": "http://localhost:8080/v1/views/org/proj/nxv:myview/outgoing",
  "_project": "http://localhost:8080/v1/projects/org/proj",
  "_rev": 1,
  "_updatedAt": "2021-04-18T17:10:22.748Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob",
  "includeDeprecated": false,
  "includeMetadata": false,
  "permission": "views/query",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTag": "v1.5",
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "_uuid": "61c74973-0f04-40f0-a694-7c8ed0fb090f"
}

Fetch original payload

GET /v1/views/{org_label}/{project_label}/{view_id}/source?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional. {rev} and {tag} fields cannot be simultaneously present.

Example

Request
sourcecurl "http://localhost:8080/v1/views/myorg/myproj/nxv:myview/source"
Response
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/indexing-view",
  "@type": "SparqlView",
  "resourceSchemas": [
    "https://bluebrain.github.io/nexus/vocabulary/some-schema"
  ],
  "resourceTypes": [
    "https://bluebrain.github.io/nexus/vocabulary/SomeType"
  ],
  "includeMetadata": false,
  "includeDeprecated": false,
  "permission": "my/permission"
}

Fetch tags

GET /v1/views/{org_label}/{project_label}/{view_id}/tags?rev={rev}&tag={tag}

where …

  • {rev}: Number - the targeted revision to be fetched. This field is optional and defaults to the latest revision.
  • {tag}: String - the targeted tag to be fetched. This field is optional.

{rev} and {tag} fields cannot be simultaneously present.

Example

Request
sourcecurl "http://localhost:8080/v1/views/myorg/myproj/fd8a2b32-170e-44e8-808f-44a8cbbc49b0/tags?rev=2"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/tags.json",
  "tags": [
    {
      "rev": 1,
      "tag": "mytag"
    }
  ]
}

SPARQL query

Provides search functionality on the SparqlView content.

POST /v1/views/{org_label}/{project_label}/{view_id}/sparql
  {query}

or

GET /v1/views/{org_label}/{project_label}/{view_id}/sparql?query={query}

In both endpoints, {query} is defined by the SPARQL documentation

The Content-Type HTTP header for POST request is application/sparql-query.

From Delta 1.5, we have added support for multiple Content Negotiation types when querying the SPARQL view, allowing clients to request different response formats. The Content Negotiation is controlled by the HTTP Accept header. The following values are supported:

  • application/ld+json: Returns an expanded JSON-LD document. This is supported for a subset of SPARQL queries.
  • application/n-triples: Returns the n-triples representation. This is supported for a subset of SPARQL queries
  • application/rdf+xml: Returns an XML document.
  • application/sparql-results+xml: Returns the sparql results in XML.
  • application/sparql-results+json: Returns the sparql results in Json (default).

Example

Request
sourcecurl -XPOST \
     -H "Content-Type: application/sparql-query" \
     "https://localhost:8080/v1/views/myorg/myproj/nxv:myview/sparql" \
     -d 'SELECT ?s where {?s ?p ?o} LIMIT 2'
Response
source{
  "head": {
    "vars": [
      "s"
    ]
  },
  "results": {
    "bindings": [
      {
        "s": {
          "type": "uri",
          "value": "http://example.com/myview"
        }
      },
      {
        "s": {
          "type": "uri",
          "value": "http://example.com/other"
        }
      }
    ]
  }
}

Fetch indexing

GET /v1/views/{org_label}/{project_label}/{view_id}/offset

Example

Request
sourcecurl "http://localhost:8080/v1/views/myorg/myproj/nxv:myview/offset"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/offset.json",
  "@type": "TimeBasedOffset",
  "instant": "2021-05-12T12:57:19.375Z",
  "value": "95d159f6-b321-11eb-a5f9-e5c0b5ea0976"
}

where…

  • instant - timestamp of the last event processed by the view
  • value - the value of the offset

Fetch statistics

GET /v1/views/{org_label}/{project_label}/{view_id}/statistics

Example

Request
sourcecurl "http://localhost:8080/v1/views/myorg/myproj/nxv:myview/statistics"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/statistics.json",
  "@type": "ViewStatistics",
  "totalEvents": 3754,
  "processedEvents": 3754,
  "evaluatedEvents": 3754,
  "remainingEvents": 0,
  "discardedEvents": 0,
  "failedEvents": 0,
  "delayInSeconds": 0,
  "lastEventDateTime": "2021-04-30T15:04:44.021Z",
  "lastProcessedEventDateTime": "2021-04-30T15:04:44.021Z"
}

where…

  • totalEvents - total number of events in the project
  • processedEvents - number of events that have been considered by the view
  • remainingEvents - number of events that remain to be considered by the view
  • discardedEvents - number of events that have been discarded (were not evaluated due to filters, e.g. did not match schema, tag or type defined in the view)
  • evaluatedEvents - number of events that have been used to update an index
  • lastEventDateTime - timestamp of the last event in the project
  • lastProcessedEventDateTime - timestamp of the last event processed by the view
  • delayInSeconds - number of seconds between the last processed event timestamp and the last known event timestamp

Restart indexing

This endpoint restarts the view indexing process. It does not delete the created namespaces but it overrides the resource GRAPH when going through the event log.

DELETE /v1/views/{org_label}/{project_label}/{view_id}/offset

Example

Request
sourcecurl -XDELETE "http://localhost:8080/v1/views/myorg/myproj/nxv:myview/offset"
Response
source{
  "@context": "https://bluebrain.github.io/nexus/contexts/offset.json",
  "@type": "ViewStatistics",
  "delayInSeconds": 0,
  "discardedEvents": 2,
  "evaluatedEvents": 8,
  "failedEvents": 0,
  "lastEventDateTime": "2021-05-12T09:58:20.507Z",
  "lastProcessedEventDateTime": "2021-05-12T09:58:20.507Z",
  "processedEvents": 10,
  "remainingEvents": 0,
  "totalEvents": 10
}
v1.7.x