Concepts Relations | Clarifai Docs

Connect and organize concepts for smarter AI

The Knowledge Graph establishes semantic and hierarchical relationships between your concepts — such as synonyms, hyponyms, and hypernyms — laying the foundation for more intelligent, context-aware systems.

These relationships are crucial for building robust knowledge representations that enhance both computer vision and natural language processing capabilities.

Whether you're managing a product catalog, powering a search engine, or organizing complex datasets, using concept relationships allows you to structure, search, and retrieve information more effectively — making your AI applications significantly smarter and more precise.

Types of Concepts Relations

Hyponym — This represents an “is a kind of” relationship. For instance, if you define the relationship as 'honey' (subject), 'hyponym' (predicate), 'food' (object), it can be interpreted as "honey is a kind of food." This helps systems understand that "honey" belongs to a broader category.
Hypernym — This is the inverse of a hyponym, signifying a “parent of” relationship. Using the same example, if you define 'food' (subject), 'hypernym' (predicate), 'honey' (object), it is read as "food is a parent of honey." When a hyponym is defined, the corresponding hypernym is automatically inferred in queries, and vice versa, ensuring consistency in how concept hierarchies are interpreted.
Synonym — This relationship connects two concepts that essentially mean the same thing, similar to an “is” statement. For example, defining 'puppy' as a synonym of 'pup' allows the model to treat them interchangeably. This relationship is bidirectional, so adding one synonym automatically implies the reverse, making searches and classifications more flexible and inclusive.

Use Case Examples

Enhanced search and retrieval — Concept relationships enable more intelligent searches. For example, a search for “Animal” can automatically include related hyponyms like “Dog” and “Cat,” returning broader and more relevant results.
Improved data organization — Hierarchical relationships help structure complex datasets more effectively. For example, hypernyms allow models to group specific entities under broader categories, improving organizational structures.
Contextual understanding — When models grasp the semantic links between concepts, they can better interpret context. For instance, recognizing that “Puppy” is a synonym of “Dog” ensures all relevant information is considered during classification or prediction.
Dynamic content delivery — In use cases like personalized content, search recommendations, or targeted advertising, concept relationships allow systems to infer user intent and deliver more relevant, meaningful results.

How to Create Relations

To create a relation between two concepts, you first have to create them in your app. 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.

import os
from clarifai.client.app import App

# Set your Personal Access Token (PAT)
os.environ["CLARIFAI_PAT"] = "YOUR_PAT_HERE"

app = App(user_id="YOUR_USER_ID_HERE", app_id="YOUR_APP_ID_HERE")

# A hyponym relation between "cat" and "animal", indicating that "cat" is a kind of "animal"
# A synonym relation between "cat" and "kitten", suggests that these two concepts are essentially the same
app.create_concept_relations("cat", ["animal", "kitten"], ["hyponym", "synonym"])

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

List Existing Relations

List All Relations

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

import os
from clarifai.client.app import App

# Set your Personal Access Token (PAT)
os.environ["CLARIFAI_PAT"] = "YOUR_PAT_HERE"

app = App(user_id="YOUR_USER_ID_HERE", app_id="YOUR_APP_ID_HERE")

concept_relations = list(app.search_concept_relations())

for relation in concept_relations:
    print("Subject_concept:", relation.subject_concept.id)
    print('\t' "Object_concept:", relation.object_concept.id)
    print('\t' "Predicate:", relation.predicate, '\n')

Delete Relations

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

###################################################################################
# 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']

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)

Conclusion

Build your next AI app, test and tune popular LLMs models, and much more.