Concepts

This section is about Timbr SQL Data Definition Language (DDL) queries to create and edit concepts with their relationships, properties and tags.

Create or replace concept

Create or replace a concept in an ontology.

Required information for creating or replacing a concept (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to create
{property_name1} - an example of a property name to be associated with the concept
{property_type1} - The data type associated with the property
{property_name2} - an example of a property name to be associated with the concept
{property_type2} - The data type associated with the property
{inherits_from_concept} - The parent concept of the concept you want to create
{concept_description} - Optional. A description of the concept

CREATE OR REPLACE CONCEPT `{concept_name}` (`{property_name1}` {property_type1}, `{property_name2}` {property_type2}, 
    PRIMARY KEY(`{property_name1}`), 
    LABEL(`{property_name2}`), 
) INHERITS (`{inherits_from_concept}`)
DESCRIPTION '{concept_description}';

Create or replace concept with relationships

Create or replace a concept with relationships.

Required information for creating or replacing a concept with a relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to create
{property_name1} - an example of a property name to be associated with the concept
{property_type1} - The data type associated with the property
{property_name2} - an example of a property name to be associated with the concept and used in the relationship
{property_type2} - The data type associated with the property
{relationship_name} - The relationship name you want to create as it will appear in this concept queries and metadata
{target_concept} - The target concept to which the relationships point to
{target_concept_property} - The property in the target concept which is related to the property in the source concept
{inverse_relationship_name} - The relationship name as it will appear from the target concept context.
{inherits_from_concept} - The parent concept of the concept you want to create
{concept_description} - Optional. A description of the concept

CREATE OR REPLACE CONCEPT `{concept_name}` (`{property_name}` {property_type}, `{property_name2}` {property_type2},
    PRIMARY KEY(`{property_name}`), 
    LABEL(`{property_name2}`),
    CONSTRAINT `{relationship_name}`
        FOREIGN KEY (`{property_name2}`)
        REFERENCES `{target_concept}` (`{target_concept_property}`)
        INVERSEOF `{inverse_relationship_name}`
) INHERITS (`{inherits_from_concept}`)
DESCRIPTION '{concept_description}';

Create or replace concept with transitive relationships

Create or replace a concept with a transitive relationship.

Required information for creating or replacing a concept with a transitive relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to create
{property_name1} - an example of a property name to be associated with the concept
{property_type1} - The data type associated with the property
{property_name2} - an example of a property name to be associated with the concept and used in the relationship
{property_type2} - The data type associated with the property
{relationship_name} - The relationship name you want to create as it will appear in this concept queries and metadata
{target_concept} - The target concept to which the relationships point to
{target_concept_property} - The property in the target concept which is related to the property in the source concept
{inverse_relationship_name} - The relationship name as it will appear from the target concept context.
{transitive_depth} - The maximum number of transitive hops for the relationship
{inherits_from_concept} - The parent concept of the concept you want to create
{concept_description} - Optional. A description of the concept

CREATE OR REPLACE CONCEPT `{concept_name}` (`{property_name}` {property_type}, `{property_name2}` {property_type2},
    PRIMARY KEY(`{property_name}`), 
    LABEL(`{property_name2}`),
    CONSTRAINT `{relationship_name}`
        FOREIGN KEY (`{property_name2}`)
        REFERENCES `{target_concept}` (`{target_concept_property}`)
        INVERSEOF `{inverse_relationship_name}` 
        TRANSITIVE ({transitive_depth}) 
) INHERITS (`{inherits_from_concept}`)
DESCRIPTION '{concept_description}';

Create or replace logic concept

Create or replace a logic concept (based on a filter).

Required information for creating or replacing a logic concept (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to create
{inherits_from_concept} - The parent concept of the concept you want to create
{concept_to_query} - The parent concept to query for the filter
{sql_query_filter} - The query filter to be performed on which the logic concept is based on

CREATE OR REPLACE CONCEPT `{concept_name}`
    INHERITS (`{inherits_from_concept}`)
    FROM `timbr`.`{concept_to_query}`
    WHERE {sql_query_filter};

Add / Remove property from a concept

Adding or Removing properties from a knowledge graph concept.

Required information for Adding or Removing a concept property (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to add or remove a property from
{property_name} - The name of the property you want to add or remove from the concept

Add property

ALTER CONCEPT `{concept_name}` ADD PROPERTY `{property name}`;

Remove property

ALTER CONCEPT `{concept_name}` REMOVE PROPERTY `{property name}`;

Add One-to-Many relationship to concept

Add a One-to-Many Relationship to concept.

Required information for Add a One-to-Many Relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{source_concept_name} - The name of the source concept you want to create a One-to-Many Relationship for
{relationship_name} - The One-to-Many relationship name you want to create as it will appear in the queries and metadata
{source_concept_property} - The property from the source concept to be associated with the relationship
{target_concept_name} - The name of the target concept you want to connect the One-to-Many Relationship to
{inverse_relationship_name} - The relationship name as it will appear from the target concept context.

ALTER CONCEPT `{source_concept_name}` 
    ADD CONSTRAINT `{relationship_name}`
        FOREIGN KEY (`{source_concept_property}`)
        REFERENCES `{target_concept_name}` (`{target_concept_property}`)
        INVERSEOF `{inverse_relationship_name}`;

Constraint with multiple properties

You can define a relationship constraint with multiple properties, but you must make sure that the amount of properties from the source concept matches the amount of properties from the target concept.

When deciding to define multiple properties, it's important to note that the order of the properties from the source concept will be matched with the order of the properties from the target concept.

So for example when defining properties (source_a, source_b) ... (target_a, target_b), this will mean: source_a = target_a & source_b = target_b

Same name relationships

In order to create multiple relationships with the same relationship name, the target concepts in those relationships must be the same. (Meaning there are different source concepts connecting to the same target concept with the same relationship name. The inverse relationship names going back from the target concepts to the source concepts must be different as well.)

Add Many-to-Many relationship to concept

Add a Many-to-Many Relationship to concept.

Required information for adding a Many-to-Many Relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{source_concept_name} - The name of the source concept you want to create a Many-to-Many Relationship for
{relationship_name} - The Many-to-Many relationship name you want to create as it will appear in the queries and metadata
{target_concept_name} - The name of the target concept you want to connect the Many-to-Many Relationship to
{inverse_relationship_name} - The relationship name as it will appear from the target concept context.

ALTER CONCEPT `{source_concept_name}` 
    ADD CONSTRAINT `{relationship_name}`
        MULTIREFERENCE `{target_concept_name}`
        INVERSEOF `{inverse_relationship_name}`;

Many-to-Many Mapping required

The creation of the Many-to-Many Relationship above is only a declaration of the relationship. For the relationship to take effect in queries, a Many-to-Many mapping is required and can be found in the mapping section. The mapping can be done using the proper SQL commands, or without the use of code using the Maptool component in the Timbr platform.

Add / Update / Remove concept tag

Adding, updating, or removing a tag of a concept

Required information for adding, updating, or removing a concept tag (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to add the tag to
{tag_name} - The tag key (name) to be added or updated to the concept
{tag_value} - The tag value to be associated with the tag key of the concept

Add / Update / Remove concept options

ADD - This option is used to add a new tag to a concept. If the tag already exists, the operation will fail. The syntax for adding a tag is:

ALTER CONCEPT `{concept_name}` ADD TAG `{tag_name}` = '{tag_value}';

UPDATE - This option is used to update an existing tag or create it if it doesn't exist (effectively a 'create or replace' operation). This is useful for modifying tags without worrying about their prior existence. The syntax is:

ALTER CONCEPT `{concept_name}` UPDATE TAG `{tag_name}` = '{tag_value}';

DROP - This option is for removing a tag from a concept. The DROP operation has a slightly different syntax as it does not require a tag value:

ALTER CONCEPT `{concept_name}` DROP TAG `{tag_name}`

Show SQL create concept statement

Show the create concept statement for an ontology.

Required information for show create concept (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to show a create statement for.

SHOW CREATE CONCEPT `{concept_name}` 

Rename a concept

Renames a concept in the ontology.

Required information for Renaming a concept in the ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

{current_name} - The current name of the concept you want to rename
{new_name} - The new name you'd like to assign to the concept

ALTER CONCEPT `{current_name}` rename to `{new_name}`;

Remove a concept

Removes a concept from an ontology.

Required information for removing a concept from the ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to remove

DROP CONCEPT `{concept_name}`;

Create or replace property

Create and edit properties in the knowledge graph

Required information for creating or replacing a property (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to create or replace
{property_type} - The type of the property you want to create or replace
{description_text} - Optional. The description of the property

Create or Update property

CREATE [OR REPLACE] PROPERTY `{property_name}` {property_type} DESCRIPTION '{description_text}';

Example:

CREATE [OR REPLACE] PROPERTY `city` STRING DESCRIPTION 'city name of customer';

Create or replace calculated property

Create and edit calculated properties

Required information for creating or replacing a calculated property (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to create or replace
{property_type} - The type of the property you want to create or replace
{description_text} - Optional. The description of the property
{calculation_or_transformation} - The calculation or transformation you want to apply on the property

Create or Update calculated property

CREATE [OR REPLACE] PROPERTY `{property_name}` {property_type} DESCRIPTION '{description_text}' AS SELECT {calculation_or_transformation};

Example:

CREATE [OR REPLACE] PROPERTY `usd_revenue` decimal DESCRIPTION 'Euro Revenue calculated in USD currency' AS SELECT eu_revenue * 1.07;

Creating a calculated property over an existing property

Users can create calculated properties over existing properties by simply following the SQL template above of - CREATE OR REPLACE PROPERTY...

Add / Update a property description

Add or update a property description

Required information for adding or updating a property description (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to add the description to
{description_value} - The description value to be associated with the property

ALTER PROPERTY `{property_name}` SET DESCRIPTION = '{description_value}';

removing description

To remove a property description, use the same statement above for setting a property description, only this time set the description value with an empty string as follows:

ALTER PROPERTY `{property_name}` SET DESCRIPTION = '';

Add / Update / Remove property tag

Adding, updating, or removing a tag of a property

Required information for adding, updating, or removing a property tag (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to add the tag to
{tag_name} - The tag key (name) to be added or updated to the property
{tag_value} - The tag value to be associated with the tag key of the property

Add / Update / Remove property options

ADD - This option is used to add a new tag to a property. If the tag already exists, the operation will fail. The syntax for adding a tag is:

ALTER PROPERTY `{property_name}` ADD TAG `{tag_name}` = '{tag_value}';

ALTER PROPERTY `{property_name}` UPDATE TAG `{tag_name}` = '{tag_value}';

DROP - This option is for removing a tag from a property. The DROP operation has a slightly different syntax as it does not require a tag value:

ALTER PROPERTY `{property_name}` DROP TAG `{tag_name}`

Show SQL create property statement

Required information for show create property (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to show a create statement for.

SHOW CREATE PROPERTY `{property_name}` 

Rename a property

Renames a property in the knowledge graph.

Required information for Renaming a property in the knowledge graph (the curly brackets {} should not be an input, they are used only as a variable substitution):

{current_name} - The current name of the property you want to rename
{new_name} - The new name you'd like to assign to the property

ALTER PROPERTY `{current_name}` rename to `{new_name}`;

Remove a property

Removes a property from an ontology

Required information for removing a property from the ontology (the curly brackets {} should not be an input, they are used only as a variable substitution):

{property_name} - The name of the property you want to remove

DROP PROPERTY `{property_name}`;

Removing a property

It's important to notice that removing a property from the ontology model, will have the property removed from all instances and concepts it is assigned to.

Updating Relationships in the Knowledge Graph

The sections below focus on actions for managing and updating existing relationships within the Timbr SQL Data Definition Language (DDL). It encompasses four essential operations:

Add Relationship Description - Enhances relationship context with descriptive information.
Add / Update / Remove Relationship Tag - Enables to manage tags for organization and categorization.
Rename a Relationship - Allows for relationship names to stay accurate and relevant.
Remove a Relationship - Enables to execute careful deletions of relationships to preserve the accuracy and consistency of the data.

Add / Update relationship description

Add a Relationship Description.

Required information for adding a description for a relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{concept_name} - The name of the concept you want to show a create statement for.

ALTER CONSTRAINT `{relationship_name}` SET DESCRIPTION = '{description value}';

removing description

To remove a relationship description, use the same statement above for setting a relationship description, only this time set the description value with an empty string as follows:

ALTER CONSTRAINT `{relationship_name}` SET DESCRIPTION = '';

Add / Update / Remove relationship tag

Adding, updating, or removing a tag of a relationship.

Required information for adding, updating, or removing a relationship tag (the curly brackets {} should not be an input, they are used only as a variable substitution):

{relationship_name} - The name of the relationship you want to add the tag to
{tag_name} - The tag key (name) to be added or updated to the relationship
{tag_value} - The tag value to be associated with the tag key of the relationship

Add / Update / Remove relationship options

ADD - This option is used to add a new tag to a relationship name. If the tag already exists, the operation will fail. The syntax for adding a tag is:

ALTER CONSTRAINT `{relationship_name}` ADD TAG `{tag_name}` = '{tag_value}';

ALTER CONSTRAINT `{relationship_name}` UPDATE TAG `{tag_name}` = '{tag_value}';

DROP - This option is for removing a tag from a relationship name. The DROP operation has a slightly different syntax as it does not require a tag value:

ALTER CONSTRAINT `{relationship_name}` DROP TAG `{tag_name}`

Rename a relationship

Renames a relationship in the knowledge graph.

Required information for Renaming a relationship in the knowledge graph (the curly brackets {} should not be an input, they are used only as a variable substitution):

{current_name} - The current name of the relationship you want to rename
{new_name} - The new name you'd like to assign to the relationship

ALTER RELATIONSHIP `{current_name}` rename to `{new_name}`;

Remove a relationship

Removing a relationship from the knowledge graph.

Required information for removing a relationship (the curly brackets {} should not be an input, they are used only as a variable substitution):

{source_concept_name} - The name of the source concept that contains the Relationship you want to drop
{relationship_name} - The relationship name you want to drop

ALTER CONCEPT `{source_concept_name}` DROP CONSTRAINT `{relationship_name}`;

removing a relationship

It's important to know that removing a relationship from the knowledge graph will affect all source concepts with this relationship. In addition, this will remove all inverse relationships from target concepts as well.

Concepts

Create or replace concept​

Create or replace concept with relationships​

Create or replace concept with transitive relationships​

Create or replace logic concept​

Add / Remove property from a concept​

Add One-to-Many relationship to concept​

Add Many-to-Many relationship to concept​

Add / Update / Remove concept tag​

Show SQL create concept statement​

Rename a concept​

Remove a concept​

Create or replace property​

Create or replace calculated property​

Add / Update a property description​

Add / Update / Remove property tag​

Show SQL create property statement​

Rename a property​

Remove a property​

Updating Relationships in the Knowledge Graph​

Add / Update relationship description​

Add / Update / Remove relationship tag​

Rename a relationship​

Remove a relationship​