Get in touch
Get in touch

How to link Concepts

Linking data through semantic relationships is a critical part of building a useful knowledge graph. To do this there are a number of important concepts to understand:

  1. How graphs join data entities using linked-data principles
  2. Creating relationships in your domain or ontology model
  3. How to load related Concepts into that model using the Data Graphs app
  4. How to load in related concepts in bulk using CSV files
  5. How to load in related concepts in bulk using the API

Linked Data Principles

Linked-data patterns use the identity (the ID), of entities to connect them, this id usually takes the form of a URI or a URN. In Data Graphs entities (Concepts) use URNs as identifiers. The URNs for a concept are globally unique in your knowledge graph and take the form:

urn:{account}:{type}:{id}

For example :

urn:demo:Person:12345

Thus two concepts, a Person and an Organization, are linked together via their IDs like this.

Creating Relationships in the Domain Model

Creating relationships in your Data Graphs domain model is easy. It just requires some sequencing. 

Given a relationship is made between the classes or types of concepts, for example a Person  worksFor an Organization, in this case, the Person type owns the relationship, so the relationship is defined by adding the property worksFor to the Person concept type/class. The datatype (or range) of the property must be set to Organization. This implies you need to create the Organization concept type/class before creating this property on the Person type.

Once you have added your property, Data Graphs knows that this property belongs to a Person and can only have Organization concepts (or concepts that are sub-classes of Organization) assigned to this relationship. 

Loading linked data via the Data Graphs UI

This is super-easy. Once the model is relationship aware (above), the UI understands the model, and when you edit a Concept (eg in this case a Person), when adding the worksFor property Data Graphs will only allow you select Organizations. If you have not already loaded any Organization instances, of course you will not be able to add one to your property.

Saving this will then create a Person (Jane Doe), connected to an Organization (Apple) by the worksFor property :

Loading linked data via CSV

Loading data in bulk using the CSV importer also uses the concept identifiers to make the relationship joins. Using our Person worksFor Organization example model, assuming we have created 3 organization concepts as follows :

Organization name Organization ID
Apple 59k0AZ8rcripmaLcL2BisK
Amazon 5ir3poyfNQLjjsra50BDRI
Microsoft 5qnrcsngabk85QSrrT4M1E

If we then create a CSV of people that work for these organizations, with 2 columns person name and the identifier of the company they work for, like this:

If we load this CSV into our dataset using the CSV Importer, choosing to load these as Person concepts, and mapping the worksFor column to the worksFor property of the Person type, when we import, Data Graphs will automatically make the relationships between the Person and the Organization.  You can see on line 5, Carol James works for two organizations so the worksFor column has the identifiers of both companies in a quoted array. The CSV importer lets us map our columns to our Person properties like this :

and Data Graphs knows that the identifiers in the worksFor column must be Organizations from our domain model. It can just make the connections automatically during import. One the import completes, the graph of our people looks like this :

Loading linked concepts using the API

When loading concepts using the Data Graphs API you need to POST the concepts to the dataset you want to insert them into. More information about the API POST request to create concepts can be found here. When using the API you must send fully formed JSON in the request body, and for relationship properties you must identified the concept being connected by its fully qualified URN.

For example to send Person concepts using our worksFor examples the JSON would like this (assuming the Person concept is defined using automatically assigned identifiers:

[
  {
    "type": "Person",
    "name": "Jane Doe",
    "worksFor": [
      "urn:test:Organization:5ir3poyfNQLjjsra50BDRI"
    ]
  },
  {
    "type": "Person",
    "name": "Jim Smith",
    "worksFor": [
      "urn:test:Organization:59k0AZ8rcripmaLcL2BisK"
    ]
  },
  {
    "type": "Person",
    "name": "John Jones",
    "worksFor": [
      "urn:test:Organization:59k0AZ8rcripmaLcL2BisK"
    ]
  },
  {
    "type": "Person",
    "name": "Carol James",
    "worksFor": [
      "urn:test:Organization:5qnrcsngabk85QSrrT4M1E",
      "urn:test:Organization:5ir3poyfNQLjjsra50BDRI"
    ]
  }
]