Outdated version

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

AggregateSparqlView

This view is an aggregate of SparqlViews. The view itself does not create any namespace, but it references the already existing namespaces of the linked SparqlViews.

When performing queries on the sparql endpoint, this view will query all the underlying SparqlViews and then aggregate the results. The order how the results across the different SparqlView gets merged it is not deterministic.

If the caller does not have the permission views/query (or from v1.5, the user-defined permission) on all the views defined on the aggregated view, only a subset of namespaces (or none) will be selected, respecting the defined permissions.

Payload

{
  "@id": "{someid}",
  "@type": "AggregateSparqlView",
  "views": [
    {
        "project": "{project}",
        "viewId": "{viewId}"
    },
    ...
  ]
}

where…

  • {project}: String - the project, defined as {org_label}/{project_label}, where the {viewId} is located.
  • {viewId}: Iri - The Blazegraph view @id value to be aggregated.
Note

This approach to aggregate data from SPARQL does not circumvent the fact that each namespace is isolated. Neither it deals with sorting or filtering in an aggregated manner.

For that reason, path traversals will not work out of the scope of the single namespace (even using an aggregate view).

Ordering and DISTINCT selection won’t work either, due to the fact that the query is executed on each namespace independently.

In order to have a more robust SPARQL aggregation support, please make us of CompositeView.

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/aggregate-view",
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}'
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/aggregate-view",
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}
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": [
    "AggregateSparqlView",
    "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": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}'
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/aggregate-view",
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}
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": [
    "AggregateSparqlView",
    "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://localhost:8080/v1/views/myorg/myproj/nxv:myview?rev=1" \
     -d \
'{
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org3/proj3",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/yetanotherview"
    }
  ]
}'
Payload
source{
  "@id": "https://bluebrain.github.io/nexus/vocabulary/aggregate-view",
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}
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": [
    "AggregateSparqlView",
    "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-20T08:05:10.014Z",
  "_updatedBy": "http://localhost:8080/v1/realms/myrealm/users/Bob"
}

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": [
    "AggregateSparqlView",
    "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": 3,
  "_updatedAt": "2021-04-24T22:18:55.444Z",
  "_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": [
    "AggregateSparqlView",
    "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": 4,
  "_updatedAt": "2021-04-28T11:01:14.398Z",
  "_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" : [
    "AggregateSparqlView",
    "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",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ],
  "_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/aggregate-view",
  "@type": "AggregateSparqlView",
  "views": [
    {
      "project": "org/proj",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myview"
    },
    {
      "project": "org2/proj2",
      "viewId": "https://bluebrain.github.io/nexus/vocabulary/myotherview"
    }
  ]
}

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 aggregated search functionality across all the SparqlViews referenced from the target view_id.

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"
        }
      }
    ]
  }
}
v1.7.x