Skip to main content

Concepts Relations

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 allow 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.

tip

Click here to learn how to leverage concept relations for more powerful and precise search queries.

How to Create Relations​

To create a relation between two concepts, you first have to create them in your app. You can see the previous section on how to create concepts.

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

Before using the Python SDK, Node.js SDK, or any of our gRPC clients, ensure they are properly installed on your machine. Refer to their respective installation guides for instructions on how to install and initialize them.

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"])
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​

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')
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
}

List Specific Concept Relations​

Below is an example of how to list the specific 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(concept_id="cat", predicate="synonym"))

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

List Relations in Tree Structure​

You can set the show_tree argument to True in search_concept_relations() to display concept relationships in a rich, hierarchical tree structure.

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(show_tree=True))

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

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)

© 2025 Clarifai, Inc. All rights reserved