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)
Raw 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)
Raw 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)

© 2024 Clarifai, Inc. All rights reserved