Skip to main content

Knowledge Graph

Connect the knowledge gained by different models


The Knowledge Graph uses Clarifai's concept mapping model to establish a hierarchical relationship between your concepts.

It uses three different predicates to organize your concepts: hypernyms, hyponyms, and synonyms.

Hyponym — represents an 'is a kind of' relation. For example, the relationship described as 'honey' (subject), 'hyponym' (predicate), 'food' (object) is more easily read as 'honey' 'is a kind of' 'food'.

Hypernym — is the opposite of 'hyponym'. When you add the relationship, the opposite will automatically appear in your queries. An 'hypernym' can be read as 'is a parent of'. For example, 'food' (subject), 'hypernym' (predicate), 'honey' (object) is more easily read as 'food' is a parent of 'honey'.

Synonym — defines two concepts that essentially mean the same thing. This is more like an "is" relationship. For example, a 'synonym' relationship could be "puppy" is "pup". The reverse is also true if the former is added; so, "pup" is "puppy" will appear in queries as well.

Create Relations

To create a relation between two concepts, you first have to create them in your custom model. See the Concepts section on how to do that programatically.

Each relation should have a specified predicate, which can be hyponym, hypernym, or synonym.

Below is an example of how to create a relation between two concepts.

info

The initialization code used in the following examples is outlined in detail on the client installation page.

###################################################################################
# In this section, we set the user authentication, app ID, subject concept ID,
# object concept ID, and predicate. Change these strings to run your own example.
###################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever relations you want to create
SUBJECT_CONCEPT_ID = 'honey'
OBJECT_CONCEPT_ID = 'food'
PREDICATE = "hypernym" # This can be hypernym, hyponym, or synonym

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

post_concept_relation_response = stub.PostConceptRelations(
service_pb2.PostConceptRelationsRequest(
user_app_id=resources_pb2.UserAppIDSet(
user_id=USER_ID,
app_id=APP_ID
),
concept_id=SUBJECT_CONCEPT_ID,
concept_relations=[
resources_pb2.ConceptRelation(
object_concept=resources_pb2.Concept(id=OBJECT_CONCEPT_ID),
predicate=PREDICATE
)
]
),
metadata=metadata
)

if post_concept_relation_response.status.code != status_code_pb2.SUCCESS:
print(post_concept_relation_response.status)
raise Exception("Post concept relation failed, status: " + post_concept_relation_response.status.description)

print(post_concept_relation_response)
JSON Output Example
status {
code: SUCCESS
description: "Ok"
req_id: "0d0a5ec5df14d62a7d660f392ce26727"
}
concept_relations {
id: "2d794e5ede534500b4ac7da44ef570ee"
subject_concept {
id: "honey"
name: "honey"
value: 1.0
created_at {
seconds: 1643976334
nanos: 237961000
}
language: "en"
app_id: "a39423543bb941bf9ba2ee95fad11f0a"
visibility {
gettable: PRIVATE
}
user_id: "e5y2lteoz3s3iy"
}
object_concept {
id: "food"
name: "food"
value: 1.0
created_at {
seconds: 1643976326
nanos: 123719000
}
language: "en"
app_id: "a39423543bb941bf9ba2ee95fad11f0a"
visibility {
gettable: PRIVATE
}
user_id: "ei2leoz3s3iy"
}
predicate: "hypernym"
visibility {
gettable: PRIVATE
}
}

List Existing Relations

Below is an example of how to list existing relations between concepts.

######################################################################################
# In this section, we set the user authentication, app ID, concept ID, and predicate.
# Change these strings to run your own example.
######################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever concept you want to list its relations
CONCEPT_ID = 'honey'
PREDICATE = "hypernym" # This is optional. If skipped, all concept's relations will be returned

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

list_concept_relation_response = stub.ListConceptRelations(
service_pb2.ListConceptRelationsRequest(
user_app_id=resources_pb2.UserAppIDSet(
user_id=USER_ID,
app_id=APP_ID
),
concept_id=CONCEPT_ID,
predicate=PREDICATE
),
metadata=metadata
)

if list_concept_relation_response.status.code != status_code_pb2.SUCCESS:
print(list_concept_relation_response.status)
raise Exception("List concept relation failed, status: " + list_concept_relation_response.status.description)

for relation in list_concept_relation_response.concept_relations:
print(relation)
JSON Output Example
id: "2d794e5ede534500b4ac7da44ef570ee"
subject_concept {
id: "honey"
name: "honey"
value: 1.0
created_at {
seconds: 1643976334
nanos: 237961000
}
language: "en"
app_id: "a39423543bb941bf9ba2ee95fad11f0a"
visibility {
gettable: PRIVATE
}
user_id: "ei2leoz3s3iy"
}
object_concept {
id: "food"
name: "food"
value: 1.0
created_at {
seconds: 1643976326
nanos: 123719000
}
language: "en"
app_id: "a39423543bb941bf9ba2ee95fad11f0a"
visibility {
gettable: PRIVATE
}
user_id: "ei2leoz3s3iy"
}
predicate: "hypernym"
visibility {
gettable: PRIVATE
}

Delete Relations

Below is an example of how to delete relations between concepts.

tip

You can use either of the following ways to retrieve the CONCEPT_RELATION_IDS:

  • Use the above List Existing Relations method to list ALL existing relations between concepts. Remember to omit the predicate parameter.
  • Log in to the Portal and access the relations details of your concept. Then, inspect the network activity under your browser's Network Tab. The IDs are under the relations category.
###################################################################################
# In this section, we set the user authentication, app ID, object concept ID, and
# concept relation IDs. Change these strings to run your own example.
####################################################################################

USER_ID = 'YOUR_USER_ID_HERE'
# Your PAT (Personal Access Token) can be found in the Account's Security section
PAT = 'YOUR_PAT_HERE'
APP_ID = 'YOUR_APP_ID_HERE'
# Change these to whatever relations you want to delete
OBJECT_CONCEPT_ID = 'YOUR_OBJECT_CONCEPT_ID_HERE'
CONCEPT_RELATION_IDS = ['0d9b0acb10fb4dac9a9d60a149d8fc5c','f5acf9c2a76143d78daf5f984693c52c']

##########################################################################
# YOU DO NOT NEED TO CHANGE ANYTHING BELOW THIS LINE TO RUN THIS EXAMPLE
##########################################################################

from clarifai_grpc.channel.clarifai_channel import ClarifaiChannel
from clarifai_grpc.grpc.api import resources_pb2, service_pb2, service_pb2_grpc
from clarifai_grpc.grpc.api.status import status_code_pb2

channel = ClarifaiChannel.get_grpc_channel()
stub = service_pb2_grpc.V2Stub(channel)

metadata = (('authorization', 'Key ' + PAT),)

delete_concept_relation_response = stub.DeleteConceptRelations(
service_pb2.DeleteConceptRelationsRequest(
user_app_id=resources_pb2.UserAppIDSet(
user_id=USER_ID,
app_id=APP_ID
),
concept_id=OBJECT_CONCEPT_ID,
ids=CONCEPT_RELATION_IDS
),
metadata=metadata
)

if delete_concept_relation_response.status.code != status_code_pb2.SUCCESS:
print(delete_concept_relation_response.status)
raise Exception("Delete concept relation failed, status: " + delete_concept_relation_response.status.description)