Usage Guide – Virtuoso GraphQL Views Creation & Management

Virtuoso Universal Server Tips, Tricks, and HowTos
, , , ,
1

GraphQL Bridge Usage Guide

Installation Steps

  1. Install Virtuoso — using the 08.03.3326 Maintenance Release or later installer that includes the graphql.so plug-in and adds it to the [Plugins] INI section.

  2. Create GraphQL Views for Virtual or Physical Graphs as described in the steps below.

Virtual Graphs

Using the Demo database, based on the Northwind Database Schema, perform the following steps:

  1. Generate an RDF View definition using the Wizard approach. During the process, take note of the IRI that denotes the Ontology generated by the system.

  2. Use the generated ontology — which is actually also a GraphQL Mapping Schema! — as the sole argument of the GQL_CREATE_TYPE_SCHEMA procedure that’s used to generate triples and load them into a designated Introspection Graph.

  3. Given the IRI http://demo.openlinksw.com/schemas/northwind/ that denotes an ontology generated by the RDF Views Wizard, and a designated Introspection Graph denoted by the IRI urn:northwind:intro, you can generate the introspection triples by executing the following SQL query:

    TTLP (GQL_CREATE_TYPE_SCHEMA ('http://demo.openlinksw.com/schemas/northwind/'), '', 'urn:northwind:intro');

At this juncture, you can test GraphQL access to the newly created views using your preferred GraphQL client.

Example Scripts

Physical Graphs

This example loads data from DBpedia into separate function-specific named graphs known as the Assumption Box (ABox) and Terminology Box (TBox).

  1. Load Book descriptions into the named graph functioning as the ABox.

  2. Load Book Property & Class definitions into the named graph functioning as the TBox.

  3. Create a GraphQL Mapping Schema that indicates what GraphQL views are to be generated and how their Properties and Classes are to be mapped to GraphQL Fields and Types

  4. Use the IRI that denotes the hand-crafted Mapping Schema as the sole argument of the GQL_CREATE_TYPE_SCHEMA() procedure that’s used to generate triples and load them into a designated Introspection Graph

  5. Given the IRI urn:graphql:dbpedia:bridge:books that denotes a hand-crafted GraphQL Mapping Schema, and a designated Introspection Graph denoted by the IRI urn:dbpedia:intro, you can generate the introspection triples by executing the following SQL query:

    TTLP (GQL_CREATE_TYPE_SCHEMA ('urn:graphql:dbpedia:bridge:books'), '', 'urn:dbpedia:intro');

  6. At this juncture, you can test GraphQL access to the newly created views using your preferred GraphQL client.

You can repeat this process by using Virtuoso’s built-in Extract, Load, and Transform middleware (a/k/a “The Sponger”) to target HTML documents that include embedded Knowledge Graphs as Structured Data Islands and/or other enhanced metadata.

Example Scripts

GraphQL Client Tools Used

GraphQL Bridge System

System Graphs

  1. Schema Graph — urn:graphql:schema

  2. Introspection System Graph — urn:graphql:intro

System Setup or Re-initialization

GQL_INIT_TYPE_SCHEMA() is the main built-in procedure for managing the system.

Arguments for the GQL_INIT_TYPE_SCHEMA() procedure are as follows:

  • 0 — i.e., GQL_INIT_TYPE_SCHEMA(); — upgrade, as used in the examples above

  • 1 — i.e., GQL_INIT_TYPE_SCHEMA(1); — re-initialize only core system graphs

  • 2 — i.e., GQL_INIT_TYPE_SCHEMA(2); — erase all graphql bridge-related data and core system graphs,

GraphQL Bridge Introspection System Interactions

Introspection enables GraphQL (GQL) clients to deductively determine the queries filters, fields, and field values exposed by a GQL server.

Virtuoso’s implementation of GQL addresses this functionality via the use of metadata stored in view-specific introspection graphs. These graphs are derived from GraphQL View definitions (annotations or mappings).

As a multi-model DBMS, Virtuoso provides operators with an ability to create view definitions using a built-in stored procedure or via the GQL Schema Definition Language (SDL).

Creating Introspection Graphs using the GraphQL Schema Definition Language

This approach serves the needs of a typical GQL developer, DevOps, architect, or DataOps seeking to publish a GQL Schema for a server they manage.

Task completion steps breakdown as follows.

  1. Create GQL View Definition (comprising Annotations or Mappings)
  2. Create SDL schema
  3. Generate Introspection metadata using the built-in procedure GQL_GENERATE_INTRO ()
  4. Test introspection from your favorite GQL client

Here’s a simple definition example for a schema that defines Offers and Products queries and their associated field, using terms from the Schema.org vocabulary.

TTLP (GQL_GENERATE_INTRO ('
        type Query {
            "Offers Collection"
            Offers(name:String, iri:IRI, price:Float): [Offer]

            "Products Collection"
            SchemaProducts(name:String, iri:IRI): [SchemaProduct]
        }
       
        " [Offer class](http://schema.org/Offer) "
        type Offer {
            iri: IRI!
            name: String
            sku: String
            potentialAction: IRI
            price: Float
            priceCurrency: String
            lowPrice: Float
            highPrice: Float
        }

        " [Product class](http://schema.org/Product) "
        type SchemaProduct {
            iri: IRI!
            name: String
            description: String
            sku: String
            brand: String
            offers: [Offer]
            mainEntityOfPage: IRI
            image: IRI
            url: IRI
            potentialAction: IRI
        }
          '), '', 'urn:graphql:intro:schemaorg:products');
Creating Introspection Graphs using built-in GQL Type System Generator Procedure

  1. Add DBpedia Books Mappings to a designated Introspection Graph

    TTLP (GQL_CREATE_TYPE_SCHEMA ('urn:graphql:dbpedia:bridge:books'), '', 'urn:dbpedia:intro');

GQL_INTRO_ADD('urn:dbpedia:intro');

  2. Add Northwind Database Mappings to a designated Introspection Graph

    TTLP (GQL_CREATE_TYPE_SCHEMA ('http://demo.openlinksw.com/schemas/northwind/'), '', 'urn:northwind:intro');

GQL_INTRO_ADD('urn:northwind:intro');

  3. Add GraphQL Landscape Mappings to a designated Introspection Graph

    TTLP (GQL_CREATE_TYPE_SCHEMA ('http://demo.openlinksw.com/schemas/graphql_landscape/'), '', 'urn:graphql_landscape:intro');

GQL_INTRO_ADD('urn:graphql_landscape:intro');
Removing existing Introspection Graphs

  1. Remove DBpedia Books Mappings to GraphQL Bridge Introspection System

    GQL_INTRO_DEL('urn:graphql:dbpedia:bridge:books');

  2. Remove Northwind Database Mappings to GraphQL Bridge Introspection System

    GQL_INTRO_DEL('http://demo.openlinksw.com/schemas/northwind/');

  3. Remove GraphQL Landscape Mappings to GraphQL Bridge Introspection System

    GQL_INTRO_DEL('http://demo.openlinksw.com/schemas/graphql_landscape/');

Related